diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index db3201d..5ff4fa3 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -206,7 +206,7 @@ The management API (REST + gRPC) uses MCIAS bearer tokens:
 | GET | `/v1/zones/{zone}` | Bearer | Get zone details |
 | PUT | `/v1/zones/{zone}` | Admin | Update zone SOA parameters |
 | DELETE | `/v1/zones/{zone}` | Admin | Delete zone and all its records |
-| GET | `/v1/zones/{zone}/records` | Bearer | List records in a zone |
+| GET | `/v1/zones/{zone}/records` | Bearer | List records in a zone (optional `?name=`/`?type=` filters) |
 | POST | `/v1/zones/{zone}/records` | Admin | Create a record |
 | GET | `/v1/zones/{zone}/records/{id}` | Bearer | Get a record |
 | PUT | `/v1/zones/{zone}/records/{id}` | Admin | Update a record |
@@ -229,6 +229,8 @@ service ZoneService {
 }
 
 service RecordService {
+  // ListRecords returns records in a zone. The name and type fields in
+  // ListRecordsRequest are optional filters; omit them to return all records.
   rpc ListRecords(ListRecordsRequest) returns (ListRecordsResponse);
   rpc CreateRecord(CreateRecordRequest) returns (Record);
   rpc GetRecord(GetRecordRequest) returns (Record);
@@ -298,6 +300,31 @@ Response 201:
 }
 ```
 
+### gRPC Usage Examples
+
+**List zones with grpcurl:**
+```bash
+grpcurl -cacert ca.pem \
+  -H "Authorization: Bearer $TOKEN" \
+  mcns.svc.mcp.metacircular.net:9443 mcns.v1.ZoneService/ListZones
+```
+
+**Create a record with grpcurl:**
+```bash
+grpcurl -cacert ca.pem \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"zone":"svc.mcp.metacircular.net","name":"metacrypt","type":"A","value":"192.168.88.181","ttl":300}' \
+  mcns.svc.mcp.metacircular.net:9443 mcns.v1.RecordService/CreateRecord
+```
+
+**List records with name filter:**
+```bash
+grpcurl -cacert ca.pem \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"zone":"svc.mcp.metacircular.net","name":"metacrypt"}' \
+  mcns.svc.mcp.metacircular.net:9443 mcns.v1.RecordService/ListRecords
+```
+
 ## Configuration
 
 ```toml
diff --git a/CLAUDE.md b/CLAUDE.md
index 04dcd1e..6faab1c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -56,6 +56,27 @@ deploy/              Docker, systemd, install scripts, examples
 - `srv/` — local dev runtime data
 - `gen/` — regenerated from proto, not hand-edited
 
+## Shared Library
+
+MCNS uses `mcdsl` (git.wntrmute.dev/kyle/mcdsl) for shared platform packages:
+auth, db, config, httpserver, grpcserver. These provide MCIAS authentication,
+SQLite database helpers, TOML config loading, and TLS-configured HTTP/gRPC
+server scaffolding.
+
+## Testing Patterns
+
+- Use stdlib `testing` only. No third-party test frameworks.
+- Tests use real SQLite databases in `t.TempDir()`. No mocks for databases.
+
+## Key Invariants
+
+- **SOA serial format**: YYYYMMDDNN, auto-incremented on every record mutation.
+  If the date prefix matches today, NN is incremented. Otherwise the serial
+  resets to today with NN=01.
+- **CNAME exclusivity**: Enforced at the DB layer within transactions. A name
+  cannot have both CNAME and A/AAAA records. Attempts to violate this return
+  `ErrConflict`.
+
 ## Critical Rules
 
 1. **REST/gRPC sync**: Every REST endpoint must have a corresponding gRPC