Epic: Docs restructure — 7 tabs → Learn / Build / Operate / Contribute

[GigaHierz]

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	#2252	done — PR #2280 merged 762173a0
#2260	Operate tab (+ Specs)	@palango	#2252 #2254	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	#2251	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)	—	—	open — split out of #2277
#2282	Rewrite the Celo Protocol overview for the L2	@GigaHierz	—	done — PR #2284 merged a4233070
#2250	Research + add an AI assistant	@GigaHierz	—	in review — PR #2286, changes requested
#2268	Sepolia USDC token address is the mainnet adapter	@GigaHierz	—	done — PR #2273 merged
#2283	Brand-level Organization JSON-LD	@GigaHierz	—	in review — PR #2285, rewritten to use Mintlify's native seo.organization after review
#2241	Colliding page titles	@GigaHierz	#2254 #2255	partly done — PR #2274 merged e38da175 retitled 7 of 9; the thirdweb pair goes with #2255
#2253	Orphaned-pages audit	@GigaHierz	—	in review — PR #2293, review findings addressed; orphan check now gates CI
#2255	De-promote thirdweb	@GigaHierz	#2252	code done — PR #2291 merged. Ops half (usage audit, vendor move) still open
#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	#2253	unblocked once #2293 merges
#2139	Release-process doc fixes (not an epic child)	@martinvol	—	superseded by PR #2295
#2257	Differentiate fee-abstraction pages	@GigaHierz	#2253	unblocked once #2293 merges
#2258	Learn tab	@GigaHierz	#2253 #2256	blocked
#2259	Build tab	@GigaHierz	#2253 #2255 #2256 #2257	blocked
#2261	Homepage + Contribute + AI resources	@GigaHierz	#2258 #2259	blocked
#2263	Agent-experience pass	@viral-sangani	#2259	blocked on #2259 for paths; content draftable now

Tabs at a07223d8 are Home · Build on Celo · Tooling · Contribute to Celo · Operate — Operate has landed; Learn (#2258) and Build (#2259) are the two renames still outstanding.

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) and CLAUDE.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

[GigaHierz]

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 a14395f8

• RESTRUCTURE_PLAN.md Part 4 — migration mechanics: catch-all wildcard redirects per tab + per-file overrides, the 6-PR sequence, mint broken-links as 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.md Appendix 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 6 infra-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; the build-with-ai/agent-skills row (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 into AGENTS.md — task: Add AGENTS.md — repo guidance for structure, headings, writing style, and code-example policy #2251.

PR #2210 at 9bd831fe

• 01-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.
• Its one content change (Celo Camp removal) shipped separately as docs: remove Celo Camp accelerator from builders page #2235 (bdf40b37). The Startup Pathway link that went with it is not re-added (decided).

Both branches are kept; nothing is deleted.