docs(agents): add Self Agent ID page under Agent Identity and turn the Self page into a journey

[GigaHierz]

The hole, and the fix

Self Agent ID is live on Celo mainnet and was documented nowhere on this site: build-on-celo/build-with-self.mdx contained 0 occurrences of "agent" and was a feature list ("New Features (2025)", points program, integrations) with no code; Agent ID was mentioned only in passing on the ERC-8004 and use-cases pages.

This PR:

• adds build-on-celo/build-with-ai/self-agent-id.mdx — what Agent ID is, how it works, verified contract addresses for mainnet and Celo Sepolia, CLI registration (linked and wallet-free), agent.fetch() on the agent side, SelfAgentVerifier middleware on the service side, troubleshooting, Celo Agent Visa, and how it maps onto ERC-8004
• creates an "Agent Identity" nav sub-group under Build with AI holding ERC-8004 and Self Agent ID; x402 / MPP / Celopedia / vibe-coding stay under "Agent Infrastructure"
• rewrites build-with-self.mdx as a journey (how it works → what you can check → get started → resources), drops the 2025 feature list, the points program and an unsourced "only leader in the space" claim, and points agent-identity readers to the new page
• cross-links 8004.mdx to Self Agent ID (Integration with Celo + Related)

Per the code-example policy (#2251): troubleshooting-grade snippets only, no end-to-end app.

What this does NOT do / residual risk

• CLI flags verified via --help the CLI has no --help; flags were verified by reading the installed dist/cli.js (corrected in this body, see evidence).
• The full register-via-QR flow was not executed — it needs the Self app and a document scan. What was verified is listed below: package, CLI subcommands/flags, TypeScript API surface, and on-chain code at every address. The CLI flags and API names are from @selfxyz/agent-sdk as installed today; a future SDK release can change them.
• Sepolia addresses for the reputation and validation registries are linked to Self's contracts page rather than listed (not verified here).
• No change to home/celo.mdx's "ZK Identity" card (still points at Build with Self, which now routes agents onward).
• Does not touch the restructure's eventual Build-tab layout (story: Build tab — merge "Build on Celo" and Tooling into build/*, with Agents and Mini Apps leading #2259); the new sub-group is inside today's structure and moves with it.

Judgement calls

• A dedicated page under a new "Agent Identity" sub-group, instead of a section inside the Self page as the issue first suggested — the agent-builder and the app-builder audiences differ, and the restructure promotes agent content. Reversible: one nav entry.
• Default CLI example uses --mode linked (the mode Self's own guide leads with) with the wallet-free variant as a comment; the modes table covers all six.
• Dropped the "only production-ready / fully audited" superlative from the Self page: unsourced, and AGENTS.md forbids it. Happy to restore with a source.

Issues

Refs #2262 — closes: Agent ID section with verified addresses; wallet-free CLI registration; agent.fetch() + verifier middleware; cross-links both ways; page restructured as a journey with the 2025 headings removed. Still open: "every snippet run once" — the registration flow itself was not run (see above); the snippets were typechecked against the installed SDK instead.

Stacking / conflicts

Branched off main, independent of my other open PRs. Shares docs.json with #2267 (top-level integrations block, different hunk — no conflict) and #2271 (MiniPay nav group, different hunk — no conflict). Merge in any order.

Verification evidence

On-chain (Celo mainnet https://forno.celo.org, Celo Sepolia https://forno.celo-sepolia.celo-testnet.org, 2026-08-21):

eth_getCode  mainnet SelfAgentRegistry      0xaC3D…5944 -> 135 bytes of code
eth_getCode  mainnet SelfReputationRegistry 0x69Da…63f4 -> 135 bytes
eth_getCode  mainnet SelfValidationRegistry 0x71a0…0577 -> 135 bytes
eth_getCode  mainnet CeloAgentVisa          0xCa97…e109 -> 142 bytes
eth_getCode  sepolia SelfAgentRegistry      0x043D…d379 -> 135 bytes
eth_getCode  sepolia CeloAgentVisa          0xf049…E875 -> 142 bytes
eth_call     mainnet registry name() = "Self Agent ID", symbol() = "SAID"

Package and CLI (fresh npm i @selfxyz/agent-sdk; the CLI prints no --help, so flags were read from the installed dist/cli.js):

$ grep -o -- '--[a-z-]*' node_modules/@selfxyz/agent-sdk/dist/cli.js | sort -u   # flags the installed CLI (v0.2.1) recognises
--human-address --minimum-age --mode --network --ofac --out --print-private-key --session --unsafe 
$ grep -oE 'register (init|open|wait|status|export)|wallet-free|ed25519-linked|smartwallet|privy' dist/cli.js | sort -u
"ed25519-linked" "linked" "smartwallet" "wallet-free" register export register init register open register status register wait 
$ grep -oE 'x-self-agent-(address|signature|timestamp)|300' node_modules/@selfxyz/agent-sdk/dist/*.js | sort -u | head
x-self-agent-address x-self-agent-signature x-self-agent-timestamp

TypeScript API surface (tsc --noEmit --strict over the page's two snippets: SelfAgent with network and with registryAddress+rpcUrl, agent.fetch, isRegistered, getCredentials, SelfAgentVerifier.create().requireAge(18).requireOFAC().sybilLimit(1).build(), verifier.auth()):

tsc: snippets typecheck OK

Links:

$ mint broken-links      # on b8e046f4, clean worktree
success no broken links found

All 9 external docs.self.xyz / GitHub URLs on the page returned 200 today.

Remaining ops steps

• Someone with the Self app runs the Celo Sepolia registration once end-to-end and pastes the register status output here; then story: Document Self Agent ID (live on mainnet, currently undocumented) #2262 can close

Checklist

• Title is the commit message I want on main
• mint broken-links passes on this head; snippets typechecked against the installed SDK
• Addresses verified on-chain, not copied
• Judgement calls flagged above
• No secrets in the diff
• Questions for the maintainer: keep the Celo Agent Visa section, or reduce it to one link? (It is Self's product; I kept the tier table because the eligibility numbers are the part a builder asks about.)