docs: merge Build on Celo and Tooling into one Build tab by GigaHierz · Pull Request #2368 · celo-org/docs

GigaHierz · 2026-10-02T13:02:48Z

"Build on Celo" and "Tooling" become one Build tab. The Tooling tab is gone. Agents and Mini Apps lead, in the order the issue asks for. #2367 (Learn) has merged, so this PR is now against main.

Group order

Quickstart, Agents, Mini Apps, Network info, Guides, Tools, Reference.

Group	Pages
Quickstart	Build home, quickstart, the tooling overview, migrate from Ethereum
Agents	One flat ordered list: overview, use docs with AI, ERC-8004, Self Agent ID, x402, x402 discovery, MPP, Celopedia, vibe coding, the three MCP pages, use cases, attribution tags
Mini Apps	The single MiniPay overview
Network info	Celo Sepolia, node overview, Forno, Alchemy
Guides	Farcaster, Self, local stablecoins, USA₮, SocialConnect, DeFi, the three fee-abstraction pages, scaling, Nightfall, funding
Tools	Libraries and SDKs (CLI, ContractKit), dev environments (thirdweb as one tool page), wallets, indexers, oracles, explorers, contract verification, bridges
Reference	The five contract pages and the launch checklist

Every moved page appears exactly once in the nav.

Paths

tooling/<path> becomes build/tools/<path>, and build-on-celo/<path> becomes build/<path>, 1:1, with these overrides: build-on-celo/build-with-ai/* becomes build/agents/*, attribution-tags becomes build/agents/attribution-tags, and build-on-minipay/overview becomes build/mini-apps/overview.
126 files moved (125 pages and the CLI README.txt). 75 files had inbound links rewritten, including AGENTS.md, ANALYTICS.md and scripts/ (the contract generator now writes to build/tools/contracts/). The GitHub edit link on build/fund-your-project and one /build/build-with-ai/... link on build/agents/vibe-coding now point at the new locations.
.github/CODEOWNERS: /build-on-celo/ and /tooling/... become /build/ and /build/tools/..., keeping each team's ownership.

Redirects

Catch-alls /build-on-celo/:slug* to /build/:slug* and /tooling/:slug* to /build/tools/:slug*, plus /build-on-celo to /build and /tooling to /build/tools/overview.
Per-file overrides for the agent pages, the MiniPay paths and attribution-tags.
Every existing redirect that pointed into the old locations now points straight at the new page, so there are no chains.
The old /build/... URLs keep working. The old /build/:slug* catch-all had to go (it would shadow real /build/... pages), so each old /build/<x> that used to reach a page through it is covered explicitly: /build/build-with-ai/{build-with-goat,examples}/:slug*, /build/build-with-ai/{multi-agent-systems,resources,tools,agent-skills,celo-pedia,celina,mcp/composer-mcp}, /build/build-with-zk-identity, /build/cel2-architecture, /build/network-overview, /build/attribution-tags, /build/build-with-bridge, /build/contract-development/deploy/deploy-with-foundry, /build/minipay/overview and /build/mobile-wallets/minipay. The exact /build/build-on-socialconnect is dropped (it is now a real page).
Wildcards are ordered most specific first, because the first matching wildcard wins. That fixes the particle-network and celina wildcards that the new catch-alls would have shadowed, and the /home/protocol/transaction/:slug* wildcard from docs: rename the Home tab to Learn and move home/ to learn/ #2367, which sat below /home/:slug* and so never fired.

Verification

$ mint broken-links --check-redirects
success no broken links found
$ bash scripts/check-orphans.sh
No orphan pages found.

A script resolved every old page URL on main (home, build-on-celo, tooling), every old exact redirect source, and every old /build/<x> URL through docs.json. The only sources it cannot resolve are the ones that redirect to external sites. It also reports no shadowed wildcards.
Under mint dev, 22 sampled old URLs redirect in one step to the new page, and 19 new URLs return 200. The tab bar reads Learn, Build, Contribute to Celo, Operate.

Not in this PR

Page titles are not rewritten, so the "Build with X / Build for X" convention is not applied: filed as task: apply the Build with X / Build for X naming convention to Build tab titles #2379.
tooling/nodes/run-a-celo-node does not exist any more, so the agreed Operate redirect has nothing to add.
Open PRs that edit files under build-on-celo/ and tooling/ will need a rebase; git follows the renames.

Blocks #2261 and #2263.

🤖 Generated with Claude Code

palango

The move itself looks clean. After normalising the diff against the path mapping, the only content changes are link rewrites plus the AGENTS.md, scripts README and stablecoins.json path updates. The nav page set is identical to base with no duplicates, the group order matches #2259, and CODEOWNERS carries every team over. Orphan check, mint broken-links, mint broken-links --check-redirects and mint validate all pass for me on 961edef, and every page URL from main and the base branch resolves through the new redirects without 404s or chains.

The redirects need another pass before this can merge, though.

Dropping /build/:slug* breaks old /build/... URLs that production still redirects today. They currently reach a page through /build/:slug* and then the exact /build-on-celo/... entries. With this PR, /build/build-with-ai/:slug* sends them to /build/agents/<x>, which doesn't exist, and two have no match at all. These 404 under mint dev on this branch:

/build/build-with-ai/build-with-goat/{mint-nft-agent,send-token-agent,token-swap-agent}
/build/build-with-ai/examples/{ai-memecoins,build-with-nebula,building_with_goat}
/build/build-with-ai/{multi-agent-systems,resources,tools}
/build/build-with-ai/mcp/composer-mcp
/build/build-with-zk-identity
/build/cel2-architecture

For example, https://docs.celo.org/build/build-with-ai/resources returns 308 to /build-on-celo/build-with-ai/resources today. Adding /build/build-with-ai/build-with-goat/:slug* and /build/build-with-ai/examples/:slug* above /build/build-with-ai/:slug*, plus exact entries for the other six, would cover them, using the same destinations the /build-on-celo/... versions already have.

Two existing wildcards are now dead because the new catch-alls sit near the top of the array, and between wildcards the first match wins. Details inline.

Smaller things. build/fund-your-project.mdx:26 still has a GitHub edit link to edit/main/build-on-celo/fund-your-project.mdx, which will 404 after merge and which broken-links doesn't check. build/agents/vibe-coding.mdx:109 still links /build/build-with-ai/mcp/index; it works through the redirect but should point at /build/agents/mcp/index. And #2259's scope includes the "Build with X / Build for X" naming convention, which this PR defers, so either open a follow-up for it or don't close #2259 from here.

One for #2367 rather than this PR: /home/:slug* sits above /home/protocol/transaction/:slug*, so the latter never fires and /home/protocol/transaction/... ends up at /learn/protocol/transaction/..., which doesn't exist (the folder is transactions).

palango · 2026-10-02T13:12:23Z

+      "destination": "/build/tools/overview"
+    },
+    {
+      "source": "/tooling/:slug*",


This now sits above /tooling/libraries-sdks/particle-network/:slug* (line 2959), and between wildcards the first match wins, so that entry never fires. /tooling/libraries-sdks/particle-network has no exact entry, so it now goes to /build/tools/libraries-sdks/particle-network, which 404s (production sends it to celo-sdks today). Move the particle-network wildcard above this line.

palango · 2026-10-02T13:12:23Z

+      "destination": "/build"
+    },
+    {
+      "source": "/build-on-celo/build-with-ai/:slug*",


Same here. /build-on-celo/build-with-ai/celina/:slug* at line 4695 is now unreachable because this wildcard matches first, so celina sub-paths go to /build/agents/celina/... and 404 (the page is at build/agents/mcp/celina). Move the celina wildcard above this one.

palango · 2026-10-02T13:12:23Z

+      "destination": "/build/mini-apps/overview"
+    },
+    {
+      "source": "/build/build-with-ai/:slug*",


Old /build/build-with-ai/* pages that no longer exist now land on /build/agents/<x> and 404: the three build-with-goat/*, the three examples/*, multi-agent-systems, resources, tools and mcp/composer-mcp. Before this PR they went through /build/:slug* to the exact /build-on-celo/... entries. Could you add /build/build-with-ai/build-with-goat/:slug* and /build/build-with-ai/examples/:slug* above this line, plus exact entries for the other four, with the same destinations as their /build-on-celo counterparts?

palango · 2026-10-02T13:12:23Z

-      "destination": "/build-on-celo"
-    },
-    {
-      "source": "/build/:slug*",


Removing this catch-all also drops /build/build-with-zk-identity (should go to /build/build-with-self) and /build/cel2-architecture (should go to /learn/network/architecture). Both redirect fine in production today but 404 on this branch, so they need exact entries.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…y specificity Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

GigaHierz · 2026-10-06T10:23:19Z

All points from the review are addressed in 59ef059, and the branch is rebased onto main now that #2367 has merged.

Old /build/... URLs: explicit entries added for everything you listed (/build/build-with-ai/{build-with-goat,examples}/:slug*, multi-agent-systems, resources, tools, mcp/composer-mcp, /build/build-with-zk-identity, /build/cel2-architecture). The same check found more that would have 404ed and are now covered: /build/build-with-ai/{agent-skills,celo-pedia,celina}, /build/network-overview, /build/attribution-tags, /build/build-with-bridge, /build/contract-development/deploy/deploy-with-foundry, /build/minipay/overview and /build/mobile-wallets/minipay.
Shadowed wildcards: wildcards are now ordered most specific first, which also revives the particle-network and celina entries and /home/protocol/transaction/:slug* from docs: rename the Home tab to Learn and move home/ to learn/ #2367.
build/fund-your-project edit link and the build/agents/vibe-coding link are fixed.
The "Build with X / Build for X" convention is deferred to task: apply the Build with X / Build for X naming convention to Build tab titles #2379, so Closes #2259 is fine from here.

I resolved every old exact redirect source, every old page URL and every old /build/<x> URL through the new docs.json and none ends on a 404 (external destinations aside); no wildcard is shadowed. mint broken-links --check-redirects and the orphan check pass.

palango

Thanks, this covers everything from my last review. I went through every nav page URL, every exact redirect source and every old /build/... URL against the new docs.json, and each one lands on the same page as before, with no chains and no shadowed wildcards. /home/protocol/transaction/:slug* works now too. mint broken-links --check-redirects, mint validate and the orphan check pass on 59ef059, and #2364 merges cleanly in either order, with its oracle edits landing in build/tools/oracles/.

One thing left, outside the diff so I can't comment inline: the "Docs for AI" global anchor in docs.json (line 545) still points at /build-on-celo/build-with-ai/use-docs-with-ai. It works through the redirect, but it shows on every page, and the redirect check in #2369 flags it ("redirects /build-on-celo/build-with-ai/use-docs-with-ai, which navigation links to"), so whichever of the two PRs merges second would fail CI. Could you point it at /build/agents/use-docs-with-ai before merging?

…plit and OP column - deployments: channelTimeout 50 for Celo and OP (Granite constant), OP finalizationPeriodSeconds 604800 and maxSequencerDrift 600 from OP's mainnet deploy config, note on channelTimeout under the table - transaction-fees: canonical fee wording, sentence-case heading, fix two typos, add the Celo Sepolia FeeHandler split - point the two new core-contracts links at /build/tools after celo-org#2368 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…K page at its new path celocli defaults to localhost:8545, so the mainnet label alone did not pick the network. The DEK link pointed at a /tooling/ path that #2368 moved and only resolved through a redirect.

GigaHierz requested review from a team as code owners October 2, 2026 13:02

GigaHierz requested review from palango and seolaoh and removed request for a team October 2, 2026 13:02

palango requested changes Oct 2, 2026

View reviewed changes

palango mentioned this pull request Oct 2, 2026

ci: check docs.json redirects that cannot work #2369

Merged

eddiemessiah mentioned this pull request Oct 6, 2026

docs(bridges): remove retired Satellite, offline Galaxy and deprecated Allbridge, fix redirected links #2374

Merged

7 of 15 tasks

Base automatically changed from GigaHierz/2258-learn-tab to main October 6, 2026 10:11

docs: merge Build on Celo and Tooling into one Build tab

80009f2

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

GigaHierz mentioned this pull request Oct 6, 2026

task: apply the Build with X / Build for X naming convention to Build tab titles #2379

Open

4 tasks

docs: restore the old /build redirects and order wildcard redirects b…

59ef059

…y specificity Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

GigaHierz force-pushed the GigaHierz/2259-build-tab branch from 961edef to 59ef059 Compare October 6, 2026 10:22

GigaHierz requested a review from palango October 6, 2026 10:23

palango approved these changes Oct 6, 2026

View reviewed changes

GigaHierz merged commit 7b8f97c into main Oct 6, 2026
5 checks passed

GigaHierz deleted the GigaHierz/2259-build-tab branch October 6, 2026 17:44

GigaHierz mentioned this pull request Oct 6, 2026

docs: point the Docs for AI anchor at the moved agents page #2382

Closed

GigaHierz mentioned this pull request Oct 15, 2026

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

Open

Navigation Menu

Repository navigation

docs: merge Build on Celo and Tooling into one Build tab - #2368

docs: merge Build on Celo and Tooling into one Build tab#2368
GigaHierz merged 2 commits into
mainfrom
GigaHierz/2259-build-tab

GigaHierz commented Oct 2, 2026 •

edited

Loading

Uh oh!

palango left a comment

Uh oh!

palango Oct 2, 2026

Uh oh!

palango Oct 2, 2026

Uh oh!

palango Oct 2, 2026

Uh oh!

palango Oct 2, 2026

Uh oh!

GigaHierz commented Oct 6, 2026

Uh oh!

palango left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

GigaHierz commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Group order

Paths

Redirects

Verification

Not in this PR

Uh oh!

palango left a comment

Choose a reason for hiding this comment

Uh oh!

palango Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

palango Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

palango Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

palango Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

GigaHierz commented Oct 6, 2026

Uh oh!

palango left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

GigaHierz commented Oct 2, 2026 •

edited

Loading