chore: update CLAUDE.md files

Author: chris-c-thomas

CLAUDE.md

@@ -271,7 +271,8 @@ Note: identifiers use `/us/cfr/` (content type) not `/us/ecfr/` (data source). B
 ## Common Pitfalls
 
 - **Hono v4 HTTPException bypasses middleware catch blocks**: In Hono v4, `HTTPException` is intercepted at the compose layer before middleware try-catch runs. Use `app.onError()` (not middleware) to handle `HTTPException`. The Data API configures this in `apps/api/src/app.ts`.
-- **USC snapshot tests break on version bumps**: `packages/usc/src/snapshot.test.ts` contains inline snapshots with the `generator` field. After changesets bump versions, update with `pnpm turbo test --filter=@lexbuild/usc -- --update` and commit the updated `fixtures/expected/*.md` files.
+- **USC snapshot tests break on version bumps**: `packages/usc/src/snapshot.test.ts` uses file snapshots in `fixtures/expected/*.md` containing the `generator` field. After version bumps, update with `find fixtures/expected -name "*.md" -exec sed -i '' 's/lexbuild@OLD/lexbuild@NEW/g' {} +` and commit. **Timing pitfall**: if a changeset file exists, the changesets bot creates a Version Packages PR with bumped versions but stale fixtures — CI fails. Either update fixtures in that PR, or do a manual version bump (all package.json + fixtures + changelogs) without a changeset file.
+- **Changeset `major` with lockstep versioning bumps ALL packages**: All 6 published packages are in the `fixed` array. A `major` changeset on any one package bumps every package to the next major (e.g., 1.x → 2.0.0). Prefer `minor` or `patch` unless all packages genuinely have breaking changes. When the Version Packages PR would cause fixture breakage, consider a manual version bump (update all `package.json` files + fixtures + changelogs) and skip the changeset file entirely.
 - **`??` does not catch empty strings**: `"" ?? "fallback"` returns `""`, not `"fallback"`. Use `||` when empty strings should be treated as falsy (e.g., date components defaulting to `"0000"`).
 - **`const` temporal dead zone in closures**: A closure that captures a `const` variable defined later in the same scope will throw `ReferenceError` when invoked — even though the closure itself is defined without error. Watch for this with `resolveLink` callbacks that reference `outputPath`.
 - **XHTML namespace tables**: `<table>` elements in USC XML are in the XHTML namespace, not the USLM namespace. The SAX parser must handle namespace-aware element names.

apps/api/CLAUDE.md

@@ -162,3 +162,4 @@ All endpoints: API key auth (optional), tiered rate limiting, X-RateLimit header
 - **First PM2 deploy uses `pm2 start`, not `pm2 reload`**: The deploy script's `--api` mode uses `pm2 reload` which fails for new processes. First deploy: `pm2 start apps/astro/ecosystem.config.cjs --only lexbuild-api && pm2 save`.
 - **DB paths auto-resolve from monorepo root**: The entry point walks up from its own location to find `pnpm-workspace.yaml` and resolves `LEXBUILD_DB_PATH` and `LEXBUILD_KEYS_DB_PATH` defaults relative to that root. No inline env var needed for local dev.
 - **API routes use `/api/` not `/api/v1/`**: Versioned prefix was removed since new sources are additive, not breaking.
+- **Documentation curl examples must URL-encode shorthand identifiers**: Since `{identifier}` is a single Hono path segment, curl examples like `curl .../documents/t1/s1` won't work. Use `t1%2Fs1` in all doc curl examples. The pattern `documents/tNN/sNNN` needs the `/` between title and section encoded as `%2F`.

packages/mcp/CLAUDE.md

@@ -86,3 +86,4 @@ src/
 - **Stdio transport logs to stderr**: All logging goes to `console.error` to avoid corrupting the stdout JSON-RPC stream.
 - **SSRF protection**: The API client validates that all requests go to the configured `LEXBUILD_API_URL` host only.
 - **Response budget**: Tool responses are checked against `LEXBUILD_MCP_MAX_RESPONSE_BYTES` after JSON serialization. Oversized responses throw `McpServerError` with code `response_too_large`.
+- **API source renames touch many files**: Changing a source identifier (e.g., `"cfr"` → `"ecfr"`) requires updates in: `api/client.ts` (type + methods), `api/types.ts`, `resources/uri.ts` (parser + return value), all `tools/*.ts` (Zod enum + descriptions), all `prompts/*.ts` (Zod enum + descriptions), and their corresponding test files. Grep for the old string literal to find all references.