Repository navigation
Epic: Docs restructure — 7 tabs → Learn / Build / Operate / Contribute #2266
Description
Why
The current seven-tab structure (Home, Build on Celo, Tooling, Contribute to Celo, Infra Partners, Specs, Legacy) mixes audiences, jobs and topics on one axis. Verified at bdf40b37: "Home" is protocol reference with no real homepage; Tooling holds 90 of 292 pages (31%) across ten unrelated groups; Legacy conflates dead L1 content with pages that still apply on L2; 105 duplicate files sit in _deprecated/; 25 tracked pages are unreachable from navigation (including the whole dev-environment-setup group); wallets, fee abstraction and thirdweb are each documented in three or more places; 167 redirects dead-end.
Decisions (agreed — not re-opened in the child issues)
| Decision | Outcome |
|---|---|
| Tab shape | 7 → 4: Learn / Build / Operate / Contribute |
| Specs tab | Folded into Operate as a "Specification" section; redirects from old specs paths |
| Legacy tab | Removed, not archived. Still-relevant content migrated to Learn (history) or Operate (old L1 node context) before deletion |
| Tooling tab | Dissolved into Build |
| Build-tab order | Quickstart → Agents → Mini Apps → Network info → Guides → Tools → Reference |
| thirdweb | Stays as one tool page at parity with other tools; no code examples, no recommendations |
| MiniPay | One overview that routes to docs.minipay.xyz for the mini-app lifecycle |
| Code examples | Troubleshooting-first: keep edge-case examples (e.g. paying gas in USDC); drop large end-to-end examples derivable from SDK docs |
| Writing standard | AGENTS.md at repo root: headings, structure, writing style, move/redirect checklist |
| Highest priority now | Analytics + an AI assistant (not Mintlify Pro; research Mintlify-compatible and open-source options) |
| End-user vs tooling | Every page states who it is for; end-user project listings also live on celo.org/ecosystem |
| Orphans | Sheet of the orphaned pages only; team marks re-nav/delete; applied in one pass |
| Startup Pathway link | Not re-added (removed with Celo Camp in #2235) |
Children, in execution order
| # | Ticket | Owner | Depends on | Status |
|---|---|---|---|---|
| #2249 | Add Google Analytics (GA4) | @viral-sangani | — | done — PR #2267 merged 453efdc2 |
| #2251 | AGENTS.md | @GigaHierz | — | done — PR #2269 merged a9b0a19c |
| #2252 | Cleanup: _deprecated, dead redirects, orphan CI check | @palango | — | done — PR #2279 merged 3604c629 |
| #2254 | Remove the Legacy tab | @palango | done — PR #2280 merged 762173a0 |
|
| #2260 | Operate tab (+ Specs) | @palango | done — PR #2289 merged a07223d8; specs.celo.org stub re-pointing split to celo-org/specs#199 |
|
| #2262 | Document Self Agent ID | @GigaHierz | — | done — PR #2270 merged f2ee83af |
| #2264 | MiniPay: one overview → docs.minipay.xyz | @GigaHierz | done — PR #2271 merged a8175ebb |
|
| #2240 | docs.json duplicate nav entry | @palango | — | done — PR #2272 merged bfa4f52d |
| #2277 | Partner contract addresses: link out instead of hardcoding | @GigaHierz | — | done — PR #2278 merged ea9ba97f; residual retired-testnet refs split to #2290 |
| #2290 | Remaining live Alfajores references (6 pages) | @palango | — | done — PR #2346 merged; split out of #2277 |
| #2311 | op-geth notice still framed as upcoming | @palango | — | done — PR #2326 merged; op-geth how-to content removed by PR #2351 (#2325) |
| #2282 | Rewrite the Celo Protocol overview for the L2 | @GigaHierz | — | done — PR #2284 merged a4233070 |
| #2250 | Research + add an AI assistant | @GigaHierz | — | done — PR #2286 merged; API-key ownership (ops) still to confirm |
| #2268 | Sepolia USDC token address is the mainnet adapter | @GigaHierz | — | done — PR #2273 merged |
| #2283 | Brand-level Organization JSON-LD | @GigaHierz | — | done — PR #2285 merged (native seo.organization) |
| #2241 | Colliding page titles | @GigaHierz | done — PR #2274 retitled 7 of 9; thirdweb pair removed by #2291 | |
| #2253 | Orphaned-pages audit | @GigaHierz | — | done — PR #2293 merged; orphan check gates CI |
| #2255 | De-promote thirdweb | @GigaHierz | done — PR #2291 merged | |
| #2265 | End-user projects on celo.org/ecosystem | @GigaHierz | — | repo-side done — PR #2294 merged; the parity sheet and submissions are ops |
| #2256 | Split wallet docs (end-user vs developer) | @GigaHierz | done — PR #2350 merged | |
| #2139 | Release-process doc fixes (not an epic child) | @martinvol | — | superseded by PR #2295 (merged) |
| #2257 | Differentiate fee-abstraction pages | @GigaHierz | done — PR #2363 merged; example fixes split to #2362 (PRs #2366 and #2384 merged; the CLI transfer and a Celo Sepolia send still need a funded key to run) | |
| #2258 | Learn tab | @GigaHierz | done — PR #2367 merged | |
| #2259 | Build tab | @GigaHierz | done — PR #2368 merged | |
| #2261 | Homepage + Contribute + AI resources | @GigaHierz | in review — PRs #2393 (homepage), #2394 (Contribute rename), #2395 (AI resources page); merge #2394 first, then rebase #2393 | |
| #2263 | Agent-experience pass | @viral-sangani | in review — PRs #2396 (wallet and test funds page), #2397 (x402 facilitator and check step), #2398 (EIP-3009 links); examples need one run with a funded key; discoverability research still not attached |
Tabs on main are Learn · Build · Contribute to Celo · Operate. #2394 renames Contribute to Celo to Contribute. After the PRs above merge, the open items are the ops work on #2265 (parity sheet, submissions), the funded-key runs for #2362 and #2263, and #2227 (specs dedup, not an epic child).
Overlap rules: #2252 touches no orphaned page (it adds the check); #2253 decides the 22 non-thirdweb orphans; the 3 thirdweb orphans belong to #2255. #2256, #2257, #2264 change content in place; #2258–#2260 move paths and do not rewrite content. #2254 owns legacy/, #2258 owns home/, #2259 owns build-on-celo/ + tooling/, #2260 owns infra-partners/ + specs/. #2257 leaves the spec-vs-guide trim to #2227.
Gate for every child PR
npx mintlify broken-links green (CI), the orphan check green once #2253 lands, and every moved or deleted path has a redirect in docs.json.
Prior art (pinned to commits, not branches)
- PR WIP: restructure #2209 at
a14395f8926eb43424e0d20e6d67ab96f2c8209b—RESTRUCTURE_PLAN.md(rationale, migration mechanics, Appendix A file-by-file map; its Operate section is stale — see story: Operate tab — move infra-partners/* to operate/* and fold Specs in as a Specification section #2260) andCLAUDE.md(absorbed by task: Add AGENTS.md — repo guidance for structure, headings, writing style, and code-example policy #2251) - PR Restructure research: benchmarks, agent-first review, Web2 audit, freshness automation proposal #2210 at
9bd831fe0dc55c29f3e276dd1aee163330513039—restructure-research/01(11-site benchmark),02(agent-first review),03(Web2 readability audit incl. the Self Agent ID spec),04(freshness automation proposal),05(skills & feedback discussion) - Related open issues: Deduplicate migrated Specs pages against the Home and Build guides #2227 (specs dedup), Migrate frontmatter og:description to description on non-legacy pages #2239 (frontmatter
description), docs.json: duplicate navigation entry for odis-use-case-phone-number-privacy #2240 (duplicate nav entry), Disambiguate colliding page titles (Overview x3, Bridging, Escrow, Encrypted Payment Comments) #2241 (colliding titles), llms.txt: stale OpenAPI spec registration emits a 404 (Mintlify support ticket) #2238 (llms.txt OpenAPI 404)
Non-goals
Freshness automation (doc 04 in #2210) — not decided; gets its own issue if and when it is. Re-adding the Startup Pathway link.
Measured at: bdf40b37
Activity
GigaHierz commentedon Aug 21, 2026
Value captured from the two draft PRs (closed in favour of this epic)
Neither PR moved a page; both were discussion artifacts. What they contain that the child issues reuse, pinned to each PR's head SHA (branch links rot):
PR #2209 at
a14395f8RESTRUCTURE_PLAN.mdPart 4 — migration mechanics: catch-all wildcard redirects per tab + per-file overrides, the 6-PR sequence,mint broken-linksas the gate. Adopted as-is by 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.RESTRUCTURE_PLAN.mdAppendix A — file-by-file map: the Learn, Build and Contribute sections are still broadly accurate and are the starting point for 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: Homepage, Contribute rename, and an "AI resources" page — final pass #2261. Stale and must be re-derived: the Operate section (its Integration group lists 6infra-partners/integration/*files that do not exist on main; the notices list predates the archive split) — see story: Operate tab — move infra-partners/* to operate/* and fold Specs in as a Specification section #2260; thebuild-with-ai/agent-skillsrow (page does not exist); the orphan list (11 then, 25 now — task: Orphaned-pages audit — re-nav or delete the 22 pages on disk that are missing from navigation #2253).CLAUDE.md: workflow, move checklist, writing style. Absorbed intoAGENTS.md— task: Add AGENTS.md — repo guidance for structure, headings, writing style, and code-example policy #2251.PR #2210 at
9bd831fe01-benchmark-report.md: 11-site audit; the evidence behind the Build-tab order and the card homepage.02-restructure-review.md: Agents + Mini Apps lead the Build tab (story: Build tab — merge "Build on Celo" and Tooling into build/*, with Agents and Mini Apps leading #2259), real homepage + AI-resources page (story: Homepage, Contribute rename, and an "AI resources" page — final pass #2261), MiniPay link-don't-duplicate (story: MiniPay — slim the section to one overview that routes to docs.minipay.xyz #2264).03-web2-readability-audit.md: the Self Agent ID section spec (story: Document Self Agent ID (live on mainnet, currently undocumented) #2262), the first-mile wallet page, x402 fixes and jargon inventory (story: Agent-experience pass — first-mile wallet page, x402 polish, troubleshooting examples, discoverability research #2263). Note one finding in it is already resolved on main: x402 no longer requires a thirdweb client ID; the llms.txt / llms-full.txt / per-page.md"missing" finding is also out of date — all three are live.04-freshness-automation-proposal.md: not decided; no issue yet (epic non-goal).05-skills-and-feedback-discussion.md: discussion input only.bdf40b37). The Startup Pathway link that went with it is not re-added (decided).Both branches are kept; nothing is deleted.