Restructure research: benchmarks, agent-first review, Web2 audit, freshness automation proposal

contribute-to-celo/builders.mdx

@@ -19,5 +19,3 @@ There are several ways to get started as a builder on Celo:
 * **Join the office hour**: Office Hours are an excellent way to learn about opportunities in the ecosystem, get feedback on your project and connect with the community. Find governance events on our community [event platform](https://lemonade.social/s/celogovernance).
 
 * **Apply for Grants**: Celo has grants programs, like [Prezenti](https://www.prezenti.xyz/) and [Celo Public Goods](https://www.celopg.eco/) which supports projects that align with its mission to provide financial services to the next billion people.
-
-* **Apply for an Accelerator**: Check out [Celo Camp](https://www.celocamp.com/), the accelerator focused on the Celo ecosystem. If you are not yet at that stage, they also offer [Startup Pathway](https://startup-pathway.mykajabi.com/) a program, that leads you through your first steps to becoming a founder.

contribute-to-celo/index.mdx

@@ -21,7 +21,6 @@ Welcome to the Celo Ecosystem! Whether you're a user, developer, founder, or con
 - [**Get involved in a local chapter:**](/contribute-to-celo/daos) Attend in-person workshops for mentoring and support.
 - [**Participate in Celo Public Goods:**](https://www.celopg.eco/) Explore ongoing funding rounds.
 - **Introduce your project** in the [**Celo Forum**](https://forum.celo.org/) in the founders' category.
-- [**Apply to Celo Camp:**](https://www.celocamp.com/) Join the accelerator focused on scaling apps on Opera MiniPay.
 - **Explore grant opportunities:** Apply for [Prezenti Grants](https://www.prezenti.xyz/) .
 
 ### As a Contributor

restructure-research/01-benchmark-report.md

@@ -0,0 +1,49 @@
+# Benchmark Report: 11 Leading Docs Sets, Consumer + Agent Lens
+
+Field research for the Celo docs restructure. Eleven documentation sites were audited live in 2026-07 against a fixed rubric: information architecture, landing-page value proposition, quickstart quality, agent docs, mini-app/consumer docs, freshness practices, and Web2 accessibility. Set (user-approved): Base, World, Optimism, Solana, TON/Telegram Mini Apps, Coinbase Developer Platform (CDP), Stripe, NEAR, Privy, Abstract, Crossmint.
+
+## Scorecard
+
+| Docs | IA axis | Agents in nav | AI-readability stack¹ | First-success path | Web2 accessibility |
+|---|---|---|---|---|---|
+| [Base](https://docs.base.org) | Use-case-first (Payments/Agents/Tokens) | **Top-level tab** | llms.txt + full + .md + MCP + skills + prompt library | 5–10 min, zero-framework HTML, real USDC on testnet | Strong |
+| [World](https://docs.world.org) | Product-first, apps before chain | Top-level (AgentKit) | llms.txt + .md mirrors + 2 hosted MCP servers | `npx create-mini-app`, submission included | Strong (mini apps) |
+| [Optimism](https://docs.optimism.io) | Persona-first (chain ops lead) | **None** (readability only) | llms.txt + full + .md + agent banners + Open-in-Claude | No true app quickstart | Poor |
+| [Solana](https://solana.com/docs) | Layered (/docs + /developers + cookbook) | /developers/ai hub | llms.txt + full + **root SKILL.md** + MCP | Zero-install browser playground | Moderate |
+| [TON/Telegram](https://docs.ton.org) | Product-first, split across 3 sites | Front-page (@ton/mcp, agentic wallets) | llms.txt + /llms markdown routes + skills | BotFather + any HTTPS URL; zero blockchain | Strong (mini apps) |
+| [CDP](https://docs.cdp.coinbase.com) | Capability-grouped products | AgentKit + x402 products | llms.txt with "AI & Agent Tooling" section | `npm create onchain-agent` 5-min; **signup-free x402 testnet** | Strong |
+| [Stripe](https://docs.stripe.com) | Jobs-to-be-done first | **/agents hub** + ACP | llms.txt w/ LLM instructions + .md + MCP + skills catalog | ~10 min, framework switchers, test mode default | Gold standard |
+| [NEAR](https://docs.near.org) | Tech-layer tabs | "Tools for AI Agents" page (Shade Agents deprecated) | llms.txt + hosted docs-MCP + on-chain MCP + skills | Tabbed chooser w/ time badges | Moderate |
+| [Privy](https://docs.privy.io) | Product-first, two-path landing | Agentic-wallets recipe + MPP | llms.txt w/ imperative agent instructions + MCP + skill | 3-step React, auth-first, no crypto needed | Strong |
+| [Abstract](https://docs.abs.xyz) | Product-first | **Top-level "AI Agents" tab** | llms.txt + full + .md + MCP + SKILL.MD | One scaffold command | Moderate |
+| [Crossmint](https://docs.crossmint.com) | Product-first + solutions layer | Top-level section + mental-model page | llms.txt + full + .md + docs MCP | **In-page interactive demo**, under 5 min, email-only | Strong |
+
+¹ "AI-readability stack" = machine-readable docs for coding agents: llms.txt/llms-full.txt, per-page markdown export, docs MCP server, installable skills.
+
+**Celo today, same rubric:** agents two levels deep in tab 2 of 6; landing page without the word "agent"; no llms.txt, no .md export, no docs MCP page, skills exist but are documented on one sub-page (Celopedia); quickstart is solid (`npx @celo/celo-composer`) but not agent- or payment-flavored; no changelog; Web2 accessibility mixed (excellent fee-abstraction framing, jargon-heavy landing). Detail in `03-web2-readability-audit.md`.
+
+## What the leaders agree on (adopt these)
+
+1. **Agents are a top-level surface, never a guide sub-group.** 9 of 11 sites surface agents at or near the nav root; the two that don't (Optimism, and NEAR after its deprecation) are the two *not* competing for agent developers. → Celo: promote "Agents" to a named Build-tab group + homepage card (see `02-restructure-review.md`).
+2. **The full AI-readability stack is table stakes in 2026.** Every single benchmarked site ships llms.txt; the leaders add llms-full.txt, per-page `.md`, a docs MCP server, and installable skills, gathered on one "resources for AI agents" page (Base, Solana, Abstract, NEAR, Stripe). Two go further in ways worth copying: Stripe embeds imperative LLM instructions in llms.txt steering agents away from legacy APIs; Optimism prepends a banner to every page telling agents to fetch /llms.txt. Mintlify provides most of this via config. → Celo: one PR, mostly `docs.json`.
+3. **Entry points are tasks, not products or concepts.** Stripe's landing links are "Accept payments online"; Base's are "Accept payments / Get started with MCP / Launch a token"; Privy forks by builder intent; NEAR is a quickstart chooser with time badges. Nobody lands visitors on "what is X" prose. → Celo: real homepage with jobs-to-be-done cards (PR #2209 open decision #6).
+4. **First success before any account, framework, or crypto knowledge.** Base: one HTML file to a USDC payment. CDP: x402 on testnet with no signup. Crossmint: in-page demo with just an email. Solana: browser playground, "no programming knowledge required". TON: a mini app is "just static files at an HTTPS URL". The consistent trick: sandbox/testnet is the default universe and the quickstart ends with an explicit success checkpoint. → Celo: signup-free x402 testnet path; keep composer as the scaffold path.
+5. **Distribution is documented as a product feature.** World's Mini Apps section (its largest) includes app-store submission *inside the quickstart* plus a Growth section (analytics, viral invites, notifications); Solana Mobile pitches "100k+ crypto power users"; TON has an Apps Center. MiniPay's 10M+ users are Celo's strongest single asset and the docs say almost nothing about getting discovered by them. → Celo: MiniPay Growth/distribution section.
+6. **Freshness is engineered, not promised.** Optimism auto-generates release pages from GitHub releases and renders contract addresses live from a registry; NEAR auto-syncs its RPC OpenAPI from nearcore; Stripe/CDP/Crossmint ship dated, product-tagged changelogs with breaking-change flags; World runs prose linters in CI. Nobody relies on humans remembering. → Celo: `04-freshness-automation-proposal.md`.
+7. **Fewer, stabler top-level sections; satellites for volatile depth.** NEAR keeps ~8 tabs and pushes deep/volatile products to satellite sites; TON splits platform/chain/SDK across three sites with hard redirects; NEAR and Base both *deleted* dead products outright. The anti-pattern is Celo's current 6-tab spread with a 39%-of-pages Tooling drawer — which PR #2209 already fixes.
+
+## Per-site notes worth stealing (beyond the consensus)
+
+- **Stripe**: "Recommended" labels on one option in every comparison table (kills choice paralysis); complexity ratings (1/5) on integration paths; no-code → low-code → full-code ladder; named API versions in the changelog with Breaking/Non-breaking flags.
+- **Base**: deprecated its own MiniKit/Farcaster mini-app stack and shipped an *AI migration skill* to automate the transition — automation applied to deprecation, the hardest freshness problem.
+- **World**: the closest MiniPay analog. 15 command pages, 8 documented error codes on the pay command, migration guides *into* the mini-app format from plain web apps.
+- **Crossmint**: one conceptual "how agents pay" mental-model page before any API reference — the pattern for making x402/8004 land with newcomers.
+- **Privy**: llms.txt opens with "STOP — do this before generating any code" aimed at coding agents; recipes are named by business outcome ("Treasury wallets", "Send USDC").
+- **CDP**: dollar-denominated prices in every code sample (`price: "$0.001"`); chains appear as config values, not concepts to learn first.
+- **TON**: mini-app docs stay thin by owning only the wallet/chain-specific layer and linking out for generic web dev — a maintenance-cost insight as much as a UX one.
+- **Optimism**: the negative case — best-in-class AI readability and freshness engineering, near-zero consumer/agent content, and a landing page serving chain operators first. Structure alone doesn't win the audience; the message has to lead.
+- **NEAR**: the other cautionary tale — promote only what you maintain; delete what you deprecate.
+
+## Sources
+
+Each claim above is grounded in the live sites as of 2026-07-06; primary URLs: docs.base.org, docs.world.org, docs.optimism.io, solana.com/docs, docs.ton.org, core.telegram.org/bots/webapps, docs.cdp.coinbase.com, docs.stripe.com, docs.near.org, docs.near.ai, docs.privy.io, docs.abs.xyz, docs.crossmint.com (and their respective llms.txt files and public GitHub repos).

restructure-research/02-restructure-review.md

@@ -0,0 +1,56 @@
+# Review of the Restructure Proposal (PR #2209) — Agent-First Lens
+
+A companion review of the draft 4-tab restructure (`RESTRUCTURE_PLAN.md`, PR #2209), evaluated against the goal that Celo's primary docs message is **agents, mini apps, and consumer applications**, with protocol/node/operator content as a stable secondary track. Benchmark evidence cited below comes from `01-benchmark-report.md` (11 docs sets, fetched 2026-07).
+
+## What the proposal gets right — endorse as-is
+
+- **The 4-tab shape (Learn / Build / Operate / Contribute)** is sound, and the migration mechanics are excellent: catch-all redirects, 6-PR sequencing, `mint broken-links` gating, orphan-file rescue, `_deprecated/` deletion.
+- **Killing the "Legacy" tab** in favor of notices + archive matches every benchmarked site (Optimism's Notices tab, Base's config changelog, NEAR outright deleting dead products).
+- **Tooling dissolved into Build** — no benchmarked site has a top-level "Tooling" junk drawer.
+- **Dedup work** (wallets, fee abstraction, thirdweb ×3) and the llms.txt to-do.
+- **The don't-touch zone is respected**: Operate and Contribute changes are renames/moves only. This review proposes no changes there.
+
+## The gap: agents and mini apps are filed, not led
+
+In the proposal, the team's primary message lands at `build/guides/ai/*` and `build/guides/minipay/*` — the third group of the second tab, two clicks deep, alphabetically adjacent to "local stablecoin" and "Nightfall". The benchmark field says this is the one place the plan is behind:
+
+- **Base**: Agents is a top-level nav section, peer of the chain itself; landing page leads with Payments / Agents / Tokens task links.
+- **Abstract**: two flagship products (Global Wallet, AI Agents) each get a top-level tab beside the chain docs.
+- **World**: landing cards order Mini Apps and AgentKit first, the chain last; Mini Apps is the largest section of the docs (60+ pages).
+- **Crossmint**: Agents is a top-level section with a dedicated mental-model page before any API detail.
+- **Stripe**: a `/agents` hub one click from the docs root.
+- **Solana**: `/developers/ai` plus a root-level SKILL.md; "AI Agent Resources" is literally the first section of its llms.txt.
+- **TON**: agents promoted on the docs front page ("Enable TON for agents with @ton/mcp").
+
+The cautionary tale is **NEAR**: it promoted an agent framework to top-level, then had to deprecate it and restructure again. The lesson isn't "don't lead with agents" — it's *lead with what you actually maintain*. Celo's agent stack (x402, ERC-8004, fee abstraction for agents, MCP, Celopedia, skills) is shipping and maintained, so the risk profile is Base's, not NEAR's.
+
+### Recommendation: keep 4 tabs, change what leads
+
+No fifth tab needed (the proposal's concern about a dominant tab is fair). Three changes inside the agreed structure:
+
+1. **Build tab group order becomes: Quickstart → Agents → Mini Apps (MiniPay) → Network info → Other guides → Tools → Reference.** Rename "AI / agents" to **"Agents"** and promote it and MiniPay from sub-groups of "Guides" to named top-level groups of the Build tab. Farcaster/Self/DeFi/SocialConnect stay under Guides.
+2. **A real homepage (resolves Open Decision #6 — see below)** whose cards are jobs-to-be-done: *Build an agent that pays* / *Build a Mini App for 10M+ MiniPay users* / *Accept stablecoin payments* / *What is Celo* / *Run a node*. The landing page currently doesn't contain the word "agent" at all (see `03-web2-readability-audit.md`).
+3. **One "AI resources" page under Agents**, unifying llms.txt, llms-full.txt, per-page `.md` export, the Celo MCP server, Celopedia, and the installable skills — the pattern every leader ships (Base's "Resources for AI agents", Solana's root agent stack, Abstract's Agent Resources, NEAR's "Tools for AI Agents"). Most of it is Mintlify configuration, not new content: Optimism got llms.txt, per-page `.md`, agent-hint banners, and Open-in-Claude/ChatGPT menus essentially from `docs.json` settings.
+
+## Positions on the 7 open decisions
+
+1. **End-user wallet/exchange content — split to celo.org, but not in this restructure.** All three of the proposal's own references (Base, World, Optimism) keep end-user content out of dev docs, and nothing in the other 8 benchmarks contradicts that. Park it in Learn > Using CELO now (as proposed) so the restructure isn't blocked, and open a separate follow-up for the celo.org migration.
+2. **Decommissioned mechanisms (granda-mento, doto, randomness) — archive, don't delete.** Inbound citations from research papers are real SEO/credibility value at near-zero carrying cost once they're out of primary nav. (NEAR's hard-delete of BOS is the counterexample, but NEAR had no research-citation surface on those pages.)
+3. **L1 validator content — archive**, same reasoning; ~17 files out of nav costs nothing.
+4. **Tab name "Operate" — keep.** Verb-consistency (Learn/Build/Operate/Contribute) reads better than Optimism's noun personas, and no benchmark suggests the name matters much. Not worth more discussion time.
+5. **`specs.mdx` to Learn > Network — agree.** Spec reference serves builders and operators; Learn is the shared shelf.
+6. **Root index — build a real homepage, don't land on Learn.** This is the strongest-evidenced decision in the set: Base, World, Stripe, Crossmint, CDP, and Privy all use a card/task homepage; NEAR's landing is a tabbed quickstart chooser with time-to-success badges. Landing on Learn would put "what is Celo" prose in front of an audience that wants "what can I ship". The homepage is also where the agent-first message gets made — without it, recommendation 1 above has nowhere to live.
+7. **Persona-first vs product-first — the axis is a false choice; go task-first at the entry, persona-ish behind it.** The field is genuinely split (Optimism persona-first; Base/World/Crossmint/Abstract product-first; Stripe jobs-to-be-done-first), so neither is "the default". What *is* universal across all 11: the entry points are tasks/use-cases, and agents+consumer products are surfaced at the top level regardless of the underlying axis. The proposed 4 verb-tabs are a fine skeleton — decision made by adopting the homepage (decision 6) + Build-tab reordering above.
+
+## Additions to the plan (new work items, sequenced)
+
+These slot into the existing 6-PR sequence without disturbing it:
+
+- **With PR 4 (Build tab):** the group reordering + "Agents" rename above; a "give your agent a wallet and test funds" first-mile page; a signup-free x402 testnet path with an explicit success checkpoint (CDP's pattern); Self Agent ID documentation in the Self guide — currently the largest single content gap versus the stated message (details in `03-web2-readability-audit.md`).
+- **With PR 6 (llms.txt):** go beyond llms.txt to the full Mintlify AI-readability stack — llms-full.txt, per-page `.md`, contextual menu (Copy / Open in Claude / Open in ChatGPT / MCP), and the "AI resources" page. Same PR, mostly config.
+- **With PR 4 (Build tab), MiniPay content strategy — link, don't duplicate.** The official MiniPay docs (https://docs.minipay.xyz/) now cover the full mini-app lifecycle — quickstart, testing inside MiniPay, wallet connection, deployment, submission, and a technical reference (deeplinks, phone-number lookup, custom methods) — with their own llms.txt and per-page `.md` exports. Celo's `build-on-minipay/*` pages duplicate a subset of this and lag it (the deeplinks and ngrok pages are the known-stale examples). There is no clean way to "pull" content across two Mintlify sites, and syndication would just create a second copy to keep fresh plus duplicate-content SEO. So: slim Celo's MiniPay section to **one strong overview** (why MiniPay: 10M+ activations, distribution, discovery page; what's Celo-specific: stablecoins, fee abstraction, phone-number mapping; funding/Proof of Ship pointers) that routes into docs.minipay.xyz for everything lifecycle-related — the TON pattern, where the chain docs own only the chain-specific layer and stay thin and current. This shrinks the proposal's `build/guides/minipay/*` mapping (5 pages) to 1–2 pages, and the freshness loop watches docs.minipay.xyz's llms.txt so the overview can't silently drift (see `04-freshness-automation-proposal.md`).
+- **After the restructure:** a MiniPay "Growth"/distribution angle on that overview (analytics, notifications, discovery-page submission — World treats distribution as a documented product feature and its Mini Apps section is its biggest asset); a product-tagged changelog (Stripe/CDP/Crossmint pattern); freshness frontmatter rollout per `04-freshness-automation-proposal.md`.
+
+## What this review deliberately does not touch
+
+Operate tab content, Contribute tab content, protocol reference, node-operator guides, and anything owned by the infra/protocol track — per the agreed division: the restructure PR already handles their mechanical moves, and their substance is not this workstream's to change.