[HAPPYS1NGH]

Changes

• Add developer-guide/guide/connect-universal-usernames — the owner's path from choosing the parent to managing the connection, including the resolver switch that copies the parent's records first — owners can connect without reading the contract
• Add the endpoint reference — request, schema v1, status codes, what every failure returns, limits, the 60 s cache and proof expiry, public records — one page a brand's backend team can build against
• Add Records — text keys, coin types (with the Rootstock-vs-Polygon 137 trap), the ENSIP-19 default EVM rules including coin type 60, contenthash protocols — checked against address-encoder 2.0.1 and content-hash 3.1.0-rc.1
• Add Troubleshooting — every one of the 30 ValidationIssueCodes with cause and fix, the 12 owner API errors, and the accepted behaviours (onchain child shadows the endpoint, no fallback resolver, nested names, proof and wallet caching)
• Add examples/universal-usernames-adapter — Hono + TypeScript, lookupUser stub, optional constant-time ENDPOINT_TOKEN, 404 vs 200 vs 500, JSON content type, 13 Vitest tests that validate the body against schema v1 — self-contained, so CI runs it today
• Add the adapter template page — shows src/app.ts and src/bearer-token.ts verbatim, kept in sync by the drift check
• Add SDK pages for @thenamespace/universal-usernames 0.1.0 and the Offchain Manager 1.2.0 connection methods, plus changelog entries marked Unreleased
• Extend openapi/offchain-openapi.json with all 12 public routes from the contract (11 universal-usernames routes + GET /api/v1/auth/nonce), 22 schemas, and uun-session / uun-operation-signature schemes — no /internal/* routes — existing paths untouched (one line changed, the top-level tags)
• Add 12 thin API pages and an owner-auth section on the API overview, backed by examples/universal-usernames-owner-api.ts (type-checked by check:examples) — tokens are base64 of UTF-8 so Unicode parent names work
• Document UPSTREAM_UNAVAILABLE (503, retryable) on every owner route and in Troubleshooting, and that credential rotation promotes itself while an endpoint replacement is save then activate — matches offchain-manager #61
• Keep the schema in one place: snippets/universal-usernames/profile-v1.schema.json, shown through an MDX snippet; check-docs now skips snippets/, which aren't pages
• Add scripts/check-uun-schema.mjs (check:uun-schema) — fails on schema drift in the snippet, template or any titled JSON block, on invalid example profiles, on template-page source drift, and on issue codes missing from Troubleshooting
• Add check:adapter to npm run check; CI caches both lockfiles — ajv becomes a direct dev dependency (already installed through mint); root .gitignore now excludes .env*
• Link the overview, SDK overview and Skills page to the new pages and the universal-usernames skill

Notes

• Stacked on docs(universal-usernames): match the overview to v1 scope #19 (docs/universal-usernames-v1-overview). Merge that first.
• Blocked on publish: the SDK pages, the validator CLI command, and the changelog entries describe @thenamespace/universal-usernames 0.1.0 and @thenamespace/offchain-manager 1.2.0, which aren't on npm yet. The adapter template doesn't depend on either.
• The Offchain Manager page follows the plan's P4 method names and the contract's request bodies; contract §6 confirms getUsernameConnection returns null on 404 and that the SDK signs for the API host. The provider option name (same as the Avatar SDK) and the error-class mapping still need checking against the 1.2.0 code before merge.
• The skill install line needs the skills PR (feat/universal-usernames-skill) merged.
• Verification: npm ci then npm run check — build validation, broken links, a11y, content checks (106 pages, 105 routes), check:examples, check:uun-schema (schema copies match, 3 example profiles valid, 30 issue codes documented), check:adapter (13 tests) all pass. The template lockfile also installs and tests with npm 10, which CI's Node 22 uses. Mutation-tested the drift check (schema, template schema, template source, issue code, invalid example each fail). Rendered the new pages with mint dev.
• Follow-ups: once 0.1.0 is published, make check:uun-schema also compare against USERNAME_PROFILE_SCHEMA_V1 from the package, and bump the docs' @thenamespace/offchain-manager pin from 1.0.13 when 1.2.0 ships. Contract §6 settles the SIWE domain (API host or App domains), UTF-8 token encoding, UPSTREAM_UNAVAILABLE, one-step credential rotation, and expectedRevision after a disconnect; all are reflected here.
• No pre-existing failures.

🤖 Generated with Claude Code

https://claude.ai/code/session_019oGqmTa3TRAEt8JZnPPL6p