docs(repo): add AGENTS.md — page templates, writing style, code-example policy, agent discoverability

[GigaHierz]

The hole, and the fix

The repo had no written standard: no AGENTS.md/CLAUDE.md on main, a PR template written for application code, and one prose style page (contribute-to-celo/contributors/documentation-contributors.mdx) with six generic rules. The result is visible in the content: 329 Title-Case vs 235 sentence-case H2s, 18 pages still on og:description, three shell and two TypeScript fence aliases in use, 11 pages with > blockquote callouts, and the same numbers stated differently across pages (block time, fee level, stablecoin count, MiniPay reach).

This adds AGENTS.md (155 lines) as the single standard for humans and coding agents, and a one-line CLAUDE.md pointing at it. It codifies what the best current pages already do rather than inventing a new style:

• repo mechanics and the mandatory 4-step move/redirect checklist
• frontmatter rules (title + description required; never og:description/id/icon/mode)
• section order per page type (guide / concept / reference / notice / index), ## Resources + ## Related closers, sentence-case headings
• writing style, including no history narration, no invented details, no competitor positioning
• code-example policy (decided): troubleshooting-first, every example must run, one language tag per language
• one fact, one page: a canonical-page table for chain IDs, block time, fees, fee abstraction, stablecoins, MiniPay, token duality, EigenDA, agent stack — with the phrasing to use (e.g. "1-second blocks", not "1-second finality"; "below $0.01", not "<$0.001")
• naming rules (USDm vs USDM, USDT, Celo Sepolia only — Alfajores retired)
• writing for AI agents: what Mintlify already serves (llms.txt, per-page .md, /mcp, contextual menu) and nine rules that make a page usable by an agent, leading with Celo's primitives (stablecoins, gas in stablecoins, MiniPay, ERC-8004 / Self Agent ID, x402 / MPP)
• PR conventions

Basis: a survey of all 229 non-legacy pages (frontmatter keys, component usage, heading case, link style, fence tags, section names) plus the CLAUDE.md draft from PR #2209 at a14395f8.

What this does NOT do / residual risk

• Does not rewrite any page to match. The contradictions the survey found (block-time/finality wording on home/index.mdx:28, fee claims on x402.mdx:184, three different Mento counts, 18 og:description pages) stay as they are; the canonical-page table tells editors which value wins. The Sepolia USDC address error is filed separately as bug: Sepolia USDC token address in fee-abstraction tables is the mainnet adapter (no code on Sepolia) #2268.
• Does not replace the generic .github/PULL_REQUEST_TEMPLATE.md (synced from pm-kit; out of scope here).
• AGENTS.md and CLAUDE.md are parsed by mint broken-links like any Markdown file; they are not in navigation, so they do not publish.

Judgement calls

• Sentence-case headings for new/rewritten pages, no mass retitle. The newest pages (x402, MPP, Celopedia, use-docs-with-ai) already use it; 329 older Title-Case H2s are left alone to avoid churn. Reversible by editing one bullet.
• Canonical-page table pins phrasing ("1-second blocks", "below $0.01") to the spec pages rather than the marketing pages, because the spec pages are the ones the blockchain team maintains. If you'd rather the marketing numbers win, it's a table edit.
• No <Steps> component even though Mintlify offers it: it is used 0 times in the repo; consistency beats the nicer component. One-line change to allow it.
• CLAUDE.md is a pointer file, not a symlink, so it renders on GitHub.

Issues

Refs #2251 — closes "AGENTS.md merged" and "CLAUDE.md is a pointer". Still open: "the epic and tab tickets link to it as the acceptance standard" (done after merge, it needs the merged URL).

Stacking / conflicts

Branched off main, independent of my other open PRs (#2267 touches docs.json only). No other open PR adds a root AGENTS.md/CLAUDE.md.

Verification evidence

$ mint broken-links        # on 7feb25a6, clean worktree
success no broken links found
$ wc -l AGENTS.md CLAUDE.md
     155 AGENTS.md
       1 CLAUDE.md

Every internal path named in the canonical-page table exists on main today except /build-on-celo/build-with-ai/self-agent-id, which is added by the Self Agent ID PR (#2262); mint broken-links does not check prose paths inside a .md table, so I checked them by hand against docs.json. No test seam applies to a guidance file; the enforcement is review against it.

Remaining ops steps

• After merge: link AGENTS.md from the epic Epic: Docs restructure — 7 tabs → Learn / Build / Operate / Contribute #2266 and from story: Learn tab — move home/* (plus kept L1 content) to learn/* #2258, story: Build tab — merge "Build on Celo" and Tooling into build/*, with Agents and Mini Apps leading #2259, story: Operate tab — move infra-partners/* to operate/* and fold Specs in as a Specification section #2260, story: Homepage, Contribute rename, and an "AI resources" page — final pass #2261 as the acceptance standard

Checklist

• Title is the commit message I want on main
• mint broken-links passes on this head
• Judgement calls flagged above
• No secrets in the diff
• Questions for the maintainer: none beyond the judgement calls above