docs: resolve the 20 orphaned pages — 10 re-nav'd, 10 deleted with redirects (#2253)

[GigaHierz]

Closes #2253. Stacked on #2291 — base is GigaHierz/2255-thirdweb-one-page, since the orphan check can only flip to gating once the three thirdweb orphans are also gone. Review that one first; this retargets to main automatically when it merges.

What changed

All 20 non-thirdweb orphans resolved per the decisions in the audit sheet (the Remove column plus its Notes). Every .mdx on disk is now reachable from docs.json navigation.

Re-nav'd — current tab, no path moves (10)

Page	Nav home
tooling/overview/migrate/from-ethereum	Tooling › Overview
build-on-celo/build-with-usat	Build on Celo › Use Cases
build-on-celo/build-on-socialconnect	Build on Celo › Use Cases
tooling/oracles/wit-oracle	Tooling › Oracles
tooling/wallets/ledger/eip712-workaround	Tooling › Wallets › Ledger Wallet
contractkit/{data-encryption-key, migrating-to-viem, migrating-to-contractkit-v1, migrating-to-contractkit-v2, notes-web3-with-contractkit}	Tooling › Libraries & SDKs › ContractKit

Deleted with a redirect (10)

The six tooling/overview/setup/* pages, build-on-celo/support, tooling/contract-verification/foundry, tooling/testnets/celo-sepolia/disclaimer, tooling/wallets/coinbase-wallet. Each redirect points at the nearest page that answers the same question, and none of them point at another redirect source.

Two places the sheet and the repo disagreed

Worth a look, because in both cases the sheet's inbound-link count was 0 and the repo says otherwise.

1. build-on-celo/build-on-socialconnect — kept, not deleted. Marked Remove=TRUE with inbound = 0, but it is linked from six in-nav pages: home/wallets.mdx:10, tooling/wallets/index.mdx:11, build-on-celo/build-with-self.mdx:50, build-on-celo/build-on-minipay/overview.mdx:102, contractkit/odis.mdx:25, contractkit/migrating-to-contractkit-v1.mdx:45. Re-nav'd into Use Cases next to build-with-self; all six links keep working. Please correct the row.

2. tooling/contract-verification/foundry — deleted, but its content was kept. Also marked inbound = 0; in fact tooling/dev-environments/foundry.mdx:112 linked to it, and deleting it outright would have left Foundry as the only deploy path in the docs with no verification instructions while Hardhat, Remix, Blockscout and Celoscan all keep theirs. The forge verify-contract commands are now a "Using Foundry" section on the contract-verification overview — a page that did not mention Foundry at all before — and the redirect lands there.

Same treatment for the other two deletes that held unique content: the Celo Sepolia terms and conditions became an <Accordion> on the testnet page, and the support channels became a "Get support" section on build-on-celo/index. Nothing that only existed on a deleted page was dropped.

Inbound links repointed, not papered over

tooling/dev-environments/hardhat.mdx listed three deleted setup pages as its prerequisites; that block is now a single sentence naming the actual prerequisites. tooling/dev-environments/foundry.mdx:112 points at the new anchor.

The CI check now gates

continue-on-error: true removed from .github/workflows/docs-validation.yml, and the stale "report-only" comment updated in scripts/check-orphans.sh. A new page that is not added to navigation now fails CI.

Incidental fixes on pages this already touches

• og:description → description on the nine re-nav'd pages that carried it. These pages are entering llms.txt for the first time and would otherwise arrive with no description at all (Migrate frontmatter og:description to description on non-legacy pages #2239).
• tooling/oracles/wit-oracle.mdx: emoji heading removed per AGENTS.md, and the Solidity example fixed — constructor(IWitnetPriceRouter _router)) had an unbalanced paren and a missing brace, so it could not compile. The sheet's "update to sepolia" note is already satisfied: docs(partners): link provider address catalogs instead of hardcoding partner contract addresses #2278 removed the hardcoded addresses, and the page describes Mainnet contracts with a mainnet RPC.
• tooling/contract-verification/index.mdx: the four /developer/verify/* links were stale redirect sources; now current paths.

Verification

$ bash scripts/check-orphans.sh
No orphan pages found.

$ npx mintlify broken-links
success no broken links found

Unblocks #2256 (decides coinbase-wallet and ledger/eip712-workaround), #2257 (decides from-ethereum and development-chain), #2258 and #2259.

[palango]

Reviewed the full change set against the PR head (6579bf5). The mechanics mostly check out: all ten new nav entries exist on disk with no duplicates, all ten redirect destinations exist and are in nav, docs.json parses, check-orphans.sh passes at head, and the /build#celo-l2-mainnet anchor resolves. Fifteen findings survived verification; twelve are inline comments on the diff, and the three below anchor on lines outside it.

Ranked, most severe first: 1. legacy-URL redirect chains (inline, docs.json:573) 2. from-ethereum content errors (inline) 3. migrating-to-viem Alfajores content and broken examples (inline) 4. hardhat prerequisites dead-end (inline) 5. mis-aimed deletion redirects (inline, docs.json:609) 6. socialconnect redirects not tightened (below) 7. orphan-gate blind spots (inline, check-orphans.sh) 8. circular foundry.toml promise (inline) 9. Foundry invisible in list and sidebar (inline) 10. segment-dropping wildcards (below) 11. nonexistent "Edit this page" control (inline) 12. stale duplicate lede (inline) 13. emoji headings on the socialconnect page (inline) 14. wit-oracle fence tags (inline) 15. orphaned image assets (below).

Socialconnect redirects not tightened (docs.json 3085, 2229, 753/761/789/3321). This PR adds build-on-celo/build-on-socialconnect to navigation, which was the recorded precondition for re-pointing these. /build/build-on-socialconnect (line 3085) is the page's own legacy path and still lands on /build-on-celo/index. /protocol/socialconnect (2229) still leaves the site for self.xyz, a different product per the Self/SocialConnect split in AGENTS.md section 7. The identity-concept sources at 753, 761 and 3321 still point at the ContractKit ODIS API page, as does 789, whose #using-the-mapping-for-payment fragment matches no heading there while the socialconnect page opens with exactly that payments use case. The ODIS-specific sources (769, 821, 3337) are fine as they are.

Segment-dropping wildcards (docs.json 2609, 2613). /developer/setup/:slug* and /developer/migrate/:slug* both rewrite to /tooling/overview/:slug*, dropping a path segment, so all six legacy /developer/setup/* URLs and /developer/migrate/from-ethereum 404. This predates the PR, but the PR retires the setup pages and publishes from-ethereum, and it forecloses the one-line wildcard fix because the corrected targets are now redirect sources themselves. While the redirect set is open: explicit /developer/setup/* entries mirroring the new block at 573-596, plus /developer/migrate/from-ethereum and the three celo-for-eth-devs sources (1433, 1513, 1557) pointed at /tooling/overview/migrate/from-ethereum, which now answers exactly that question.

Orphaned image assets. Deleting replit.mdx and wallet.mdx leaves img/doc-images/deploy-replit/ (12 PNGs, 6.9 MB) and img/doc-images/testnet-wallet/ (6 PNGs, 1.0 MB) with zero references anywhere in the tree. Nothing in CI catches unreferenced images, so git rm -r both directories in this PR while the deletions are in context.

[palango]

These ten redirects cover the current paths of the deleted pages, but older wildcards further down the array rewrite legacy URLs onto these same paths, and Mintlify only takes one hop. Six URLs that resolved at the base commit now 404:

• /developer/verify/foundry (wildcard at line 2585)
• /network/alfajores/disclaimer, /network/baklava/disclaimer, /network/celo-sepolia/disclaimer (2745/2753/2761)
• /wallet/coinbase-wallet (2789)
• /build/support (the /build/:slug* wildcard at 2557 matches before the specific /build/support entry at 3149, which is now dead code)

Each needs a specific entry above the wildcard, pointing at the final destination already chosen here. AGENTS.md section 2: point at the final page, not at another redirect.

[palango]

Adding this page to navigation publishes content that contradicts the canonical pages:

• Line 78 says Celo "uses EigenLayer as the data settlement layer". It is EigenDA, for data availability (AGENTS.md section 7, /operate/specification/eigenda).
• Line 16 says "1 second block finality" and line 78 "all blocks are finalized immediately... no need to wait for more than 1 block confirmation". AGENTS.md rules out the 1-second-finality phrasing; L2 finality follows Ethereum (/operate/specification/finality).
• Line 84 has a reversed link, (transaction types)[/what-is-celo/...], which renders as plain text, and even fixed the path dead-ends: the /what-is-celo/using-celo/protocol/:slug* wildcard rewrites to singular /home/protocol/transaction/... while the page lives under transactions/. The working target is /home/protocol/transactions/transaction-types.
• Lines 67-107 still recommend Celo Rosetta and celo-blockchain and describe L1 epoch-block receipt behavior.

Worth a content pass before this enters the sidebar, or hold the page back for #2257.

[palango]

This page enters the nav with content AGENTS.md rules out and code that does not run:

• Alfajores references at lines 21, 194 and 234 ("Alfajores (44787) is retired - do not reference it"). Line 234's Alfajores USDm address is passed as feeCurrency on a mainnet client at line 247, which reverts on chain.
• tokenAddresses["StableToken] at lines 156 and 174 is an unterminated string literal.
• publicClient.getAddresses() (42), walletClient.sendSignedTransaction(...) (80) and sendTransaction straight after simulateContract (185) are not viem APIs; AGENTS.md: every example that stays must run.
• The title is "Migration document from Contractkit" with no sidebarTitle, so that misspelled label is what the sidebar shows, while the sunset banners on the sibling pages call this "the migration guide". Migrating to viem would match.

Either fix the page in this PR or hold it out of nav until it is fixed; publishing as-is ships broken examples on the recommended migration path.

[palango]

This sentence replaces the only route readers had to account-creation guidance, and the guide now dead-ends: the config below requires process.env.MNEMONIC with derivation path m/44'/52752'/0'/0, and after this PR no page in the repo explains how to obtain one. The natural reading of the new prerequisite (MetaMask plus faucet) does not produce a usable mnemonic either; tooling/wallets/metamask/use.mdx says MetaMask cannot export or import along the Celo derivation path. Cheapest fix: link celocli account:new (tooling/libraries-sdks/cli/account.mdx, in nav) with a note on the derivation path, or switch the example to a private-key account.

[palango]

Three of the new destinations do not answer the question the deleted page answered (AGENTS.md section 2: redirect to the nearest page that answers the same question):

• This one: tooling/wallets/index.mdx never mentions Coinbase and has no chain params. The deleted page's wallet_addEthereumChain/wallet_watchAsset content survives near-verbatim at /tooling/wallets/metamask/setup (in nav), which is the better target.
• /tooling/overview/setup/wallet (585) goes to the Celo Sepolia network page, which has faucet links but nothing on creating or importing a wallet; /tooling/wallets/metamask/add-celo-testnet-to-metamask covers both.
• /tooling/overview/setup/replit (589) goes to a dev-environments index that never mentions Replit or any no-install path; /tooling/dev-environments/remix is the surviving browser-only option, as the new hardhat.mdx prerequisite itself says.

[palango]

Foundry is missing from this list even though the "Using Foundry" section is two lines below it, and it is also absent from the Contract Verification sidebar group in docs.json, so someone scanning either surface sees four methods and concludes Foundry is not covered. Minimum fix: add - [Using Foundry](#using-foundry) here. The symmetric alternative is to keep foundry.mdx as a fifth page in the group alongside Hardhat, Blockscout, Remix and Celoscan.

[palango]

docs.json has no feedback key, and Mintlify only renders the suggest-edits control when feedback.suggestEdit is configured, so there is no "Edit this page" at the bottom of any page; a reader following this instruction finds nothing. The sentence came over from the deleted support page, but since it is being rewritten anyway: either add the feedback block to docs.json in this PR or drop the clause and keep the issue link.

[palango]

Leftover from the rewrite: this line plus the --- under it restate the frontmatter description right above the new lede at line 11, so the page opens with the same sentence twice and a stray rule. Suggest deleting lines 7-9. While in the file, ## Verify Contracts on Celo on line 13 should be sentence case; the AGENTS.md heading rule explicitly covers rewritten pages.

[palango]

Publishing this page while editing its frontmatter leaves all four headings against the AGENTS.md heading rules this same PR applies to wit-oracle.mdx: emoji in every heading, a question heading on a non-FAQ page, and "Further Reading", which AGENTS.md names as an out-of-vocabulary synonym. The emoji also end up in the generated anchor slugs, so plain #key-features-style deep links scroll nowhere, and mint broken-links does not validate anchors. Separately, the page has zero internal links (everything points at socialconnect-docs.vercel.app), which makes the AGENTS.md-canonical page for phone-number mapping a dead end in the link graph.

[palango]

Good catch on the constructor. The fence this block sits in is still tagged javascript though, as are the other two on the page: lines 36 and 106 are Solidity, and the snippet at line 76 mixes Python calls with // comments and parses in neither language. Since this PR already edits inside the first block, worth retagging the fences and fixing the line-76 snippet in the same pass.

[palango]

Fences and the constructor are fixed. The web3 snippet parses as Python now, but it still won't run: the ABI string types _id as bytes32 while the call passes four bytes.

web3 7.16.0
  bytes32 + bytes.fromhex("9ed884be") -> MismatchedABI
  bytes4  + bytes.fromhex("9ed884be") -> OK  0xd2476bd49ed884be00...

The bytes32 is the wrong half, not the argument. The Solidity block above already calls router.valueFor(bytes4(0x24beead4)), and Witnet types these IDs as bytes4 upstream: IWitPriceFeedsLegacy.sol declares latestPrice(bytes4 feedId) and documents hash() as returning "the ERC-2362 identifier of the given data feed caption string, truncated to bytes4". So "type": "bytes4" and "internalType": "bytes4", argument unchanged. That moves the selector from 0xf78eea83 to 0xd2476bd4, so it is not cosmetic; as written the snippet calls a function the proxy does not have.

Same block, smaller: the heading above it still reads #### Javascript example over a python fence.

One thing beyond this PR. IWitnetPriceRouter no longer exists in witnet-solidity-bridge: the interfaces directory now carries IWitPriceFeeds.sol with computeID4/getPrice(ID4), and the router shape has moved under legacy/. Both Solidity blocks on the page import a path upstream dropped. Worth its own issue rather than growing this one.

[GigaHierz]

All 15 addressed in a3ce702c. Rebased on main, so #2291 is out of the diff and the base is main now.

Finding 1 + 10 — redirect precedence. Confirmed the mechanism and it was worse than the six URLs you listed. /build/:slug* also shadowed the three thirdweb entries, which is a regression I shipped in #2291: /build/build-with-thirdweb/overview hit the wildcard, landed on /build-on-celo/build-with-thirdweb/overview, and my redirect from there was a second hop. Four pre-existing /build/* sources (composer-kit, mcp, mcp/celo-mcp, mcp/composer-mcp) were dead the same way.

I wrote a resolver that walks the array in order, expands :slug*, and checks the destination against the nav set:

chains (destination is itself a source):   0
dead destinations (not in navigation):     0
sources shadowed by an earlier wildcard:   0

Finding 2 — from-ethereum. Every item was right. EigenLayer→EigenDA, the finality phrasing, the reversed link and its non-resolving path. On the two you flagged as L1 leftovers I checked before rewriting: celo-org/rosetta is archived, and celo-org/celo-blockchain's own description now reads "Previous official repository... for current see op-geth". The precompile link points at core/vm/celo_contracts.go in op-geth (celo-rebase-17, verified 200) — Celo does still add precompiles, so the claim survives, just not the v1.3.2 link.

Finding 3 — migrating-to-viem. All four code defects confirmed. The one worth recording: 0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1 passed as feeCurrency on a mainnet client —

$ eth_call symbol() @ 0x874069... on forno.celo.org  -> no code
$ eth_call symbol() @ 0x765DE8... on forno.celo.org  -> "USDm"

so it would revert exactly as you said. Also: the CeloTokens helper returned [string, string][], so tokenAddresses["StableToken"] was never going to work even with the quote closed. It now returns a Record and both blocks use it, which keeps the registry-lookup pattern rather than hardcoding.

Findings 4, 5, 6, 8, 9, 11, 12, 13, 14 — all applied as suggested. For 5 I took your three targets. For 9 I did the minimum fix (Foundry in the list); keeping foundry.mdx as a fifth page is the better shape long-term but that is a nav change for the Build-tab ticket.

Finding 7 — orphan gate. Both gaps closed, and I tested them rather than assuming:

# orphaned .md is caught
$ touch build-on-celo/zz-temp-orphan.md && bash scripts/check-orphans.sh
Found 1 orphan page(s) ... build-on-celo/zz-temp-orphan     (exit 1)

# href-only reference is not a false positive
$ # removed use-docs-with-ai from its pages array, leaving only the href at :519
$ bash scripts/check-orphans.sh
No orphan pages found.                                       (exit 0)

The .md widening needed the excludes you predicted (README, AGENTS, CLAUDE, scripts/, dotdirs).

Finding 15 — both directories gone, 18 files, 7.9 MB.

One thing I did not do: add the feedback block to docs.json for finding 11. I dropped the clause instead, since turning on suggest-edits site-wide is a bigger call than this PR should make. Worth its own issue if you want the control.

check-orphans.sh green, mintlify broken-links green.

[GigaHierz]

Reopening finding 11 — I got the call wrong, and the answer is more annoying than either of us assumed.

The docs used to have an edit-a-page control and it is wanted back, so "drop the clause" was not the right resolution. But your diagnosis was correct and the fix you offered is not available: feedback.suggestEdit was a mint.json v1 key. Against https://mintlify.com/docs.json, which this repo already declares as its $schema:

$ grep -oiE "feedback|suggestEdit|raiseIssue|thumbsRating" mint-schema.json | sort -u
(no output)

Zero hits for all four. There is no edit key of any kind in the schema, nothing in Mintlify's own llms.txt about the control, and the live site renders none.

The closest supported mechanism is a custom entry in contextual.options, which is now added. One real limitation, which the description is worded around rather than hiding: the href cannot be per-page. Mintlify substitutes $path only inside query-parameter values, not in the base URL, so github.com/celo-org/docs/edit/main/<path>.mdx is not expressible. The entry opens the repository and GitHub's own edit-and-PR flow takes over — which is the workflow that was actually being used.

The GitHub-search alternative (base: github.com/search, query: [{key: q, value: $path}]) would give a per-page deep link, but GitHub code search requires a login, so a logged-out reader hits a wall instead of a file. Not worth it.

So this PR now carries the site-wide contextual entry after all, which is a bigger footprint than an orphan-audit PR would normally take. Say the word and I will split it out into its own PR — it is one object in docs.json plus one sentence in build-on-celo/index.

c5c313a9. Branch is up to date with main; broken-links and check-orphans both green.

[GigaHierz]

Split done — the context-menu change is now #2297, and this PR is back to the orphan audit plus its review fixes only.

What stayed here is one sentence on build-on-celo/index: the support section no longer names an "Edit this page" control, and instead points at celo-org/docs and the flow GitHub provides from there. That reads correctly whether or not #2297 lands, so there is no forward reference and the two PRs can merge in either order.

46500e91.

[palango]

Required change. Putting this page in the sidebar brings its headings under the AGENTS.md heading rules, the same ones this PR applied to socialconnect and wit-oracle.

Line 14 is a question heading on a page that is not an FAQ (AGENTS.md:72). Title case is still on lines 14, 23, 58, 89, 93, 99 and 103. AGENTS.md:71 does say not to mass-retitle old pages for case alone, but it scopes that to pages you are not otherwise touching, and this PR rewrites four sections of this one.

[palango]

Required change. /protocol/identity/index at line 2230 still points at https://self.xyz/. With this line fixed the two legacy identity paths now disagree: /celo-codebase/protocol/identity/index reaches the SocialConnect page this PR adds to nav, while /protocol/identity/index leaves the site for a different product. AGENTS.md section 7 keeps Self and SocialConnect apart, so self.xyz does not answer the identifier-mapping question. Give it the same destination as this line.