diff --git a/contribute-to-celo/builders.mdx b/contribute-to-celo/builders.mdx index 118e759f9..1d4bcdd6e 100644 --- a/contribute-to-celo/builders.mdx +++ b/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. diff --git a/contribute-to-celo/index.mdx b/contribute-to-celo/index.mdx index 908bc3089..5872f8ba8 100644 --- a/contribute-to-celo/index.mdx +++ b/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 diff --git a/restructure-research/01-benchmark-report.md b/restructure-research/01-benchmark-report.md new file mode 100644 index 000000000..0d7257d68 --- /dev/null +++ b/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). diff --git a/restructure-research/02-restructure-review.md b/restructure-research/02-restructure-review.md new file mode 100644 index 000000000..ed4546b8f --- /dev/null +++ b/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. diff --git a/restructure-research/03-web2-readability-audit.md b/restructure-research/03-web2-readability-audit.md new file mode 100644 index 000000000..f96747637 --- /dev/null +++ b/restructure-research/03-web2-readability-audit.md @@ -0,0 +1,80 @@ +# Web2 Readability Audit + +How understandable are the Celo docs for a Web2 developer — someone who builds with Stripe, Express, and React, has never held a private key, and arrives because they heard "agents can pay and verify identity on Celo"? This audit walks the two journeys such a developer actually takes, page by page, and lists concrete fixes. Pages audited on this branch, 2026-07. + +**Bottom line: the ingredients are good — the agent pages are among the strongest in the docs — but the path to them is invisible, and every page assumes wallet literacy the target reader doesn't have.** A Stripe developer bounces before reaching x402, and if they search for agent identity, the docs have no answer at all (Self Agent ID, live on Celo mainnet, is not mentioned anywhere). + +--- + +## Journey 1 — "I build AI agents and want them to send/receive payments" + +### Hop 1: Landing page (`home/index.mdx`) + +The first page a visitor sees **does not contain the words "agent" or "AI" at all.** The headline is "Discover Celo — an Ethereum Layer-2 designed to make blockchain technology accessible to all." For the primary audience the team wants to win, the landing page is a dead end: nothing routes them anywhere. Compare: Base's landing leads with Payments/Agents/Tokens task links; World's first row of cards includes AgentKit; Stripe's `/agents` hub is one click from the docs root. + +Other Web2 friction on this page: +- "Fully EVM-compatible", "Token Duality", "ERC20", "native transfer", "governance", "staking" — all unexplained, none of it relevant to the arriving reader's job. +- The page's calls to action are governance voting and Discord — not "build something in 10 minutes". + +### Hop 2: Finding the agent docs + +The agent hub lives at *Build on Celo → Build with AI → Overview* — tab 2, nested group, below the fold of the nav. A visitor has to already believe Celo has agent tooling to go looking for it. There is no `/agents` URL, no landing-page card, no llms.txt to route AI assistants (all 11 benchmarked docs sites with agent ambitions ship one; Celo doesn't yet — flagged in PR #2209 as a to-do). + +### Hop 3: `build-with-ai/overview.mdx` + +The strongest Web2-facing page in the docs. "Agentic Activity with Real World Utility" is a clear pitch; the fee-abstraction section brilliantly frames a real agent problem ("your agent's treasury is one stablecoin") with a complete copy-paste example. Remaining friction: +- The code example starts from `AGENT_PRIVATE_KEY` in an env var, with no pointer to *how an agent gets a wallet and funds in the first place* (key generation, testnet faucet, onramp). Stripe/CDP/Crossmint all answer "where does the money come from" before "how do I move it". +- Adapter-vs-token address and 6-vs-18 decimals arrive with no warm-up — correct content, but it needs a "you can get this wrong silently" warning box earlier. +- The "Types of AI Agents" taxonomy (basic/functional/autonomous/multi-agent) is filler for this audience; a "Ship your first paying agent in 10 minutes" link would earn that space. + +### Hop 4: `build-with-ai/x402.mdx` + +Good structure (the comparison table against traditional payments is exactly the right Web2 framing; the sequence diagram is clear). Friction for a Web2 reader: +- **No signup-free first success.** CDP's x402 seller quickstart runs on testnet with no account; Celo's page jumps into thirdweb SDK code requiring a thirdweb client ID and secret key before the first request works. +- Undefined jargon at first use: *facilitator* (load-bearing concept, never defined in plain words), *settlement*, *ERC-2612 permit / ERC-3009 authorization*, *base units* (`maxValue: "1000000"` — is that $1 or $1M? — no comment). +- Prerequisites are implicit: a funded wallet, familiarity with `privateKeyToAccount`, and understanding that "price: $0.01" is denominated in real dollars but paid in a stablecoin. +- No "Congratulations, you just charged an agent $0.01" checkpoint (Stripe ends every quickstart with an explicit success state and next-step branches). + +**Journey 1 verdict:** a determined Web2 developer who *finds* these pages can succeed in an afternoon; the failure mode is discovery (hops 1–2) and the missing wallet-and-funds on-ramp, not the core content. + +--- + +## Journey 2 — "I want identity/verification for my users or agents" + +Per the team's direction, this journey should land on **Self Agent ID**. + +### What happens today + +Searching the docs for identity leads to `build-on-celo/build-with-self.mdx`. That page: +- Describes Self as human identity verification (passports, EU ID, Aadhaar) — good, but **contains no mention of Agent ID**, Self's agent-identity product that is *live on Celo mainnet* with a soulbound registry, an SDK (`@selfxyz/agent-sdk`, plus Python/Rust), wallet-free registration modes, and a REST API. +- Is a feature-list page ("New Features (2025)", integrations, points program) rather than a journey: no code, no quickstart, ten external links with no guidance on which one to click first. +- The ERC-8004 page and the Self page don't reference each other, even though Self Agent ID is a reference implementation of ERC-8004 with a proof-of-human extension — the exact "trust layer" story the 8004 page is trying to tell in the abstract. + +**Journey 2 verdict: dead end.** The docs' best agent-identity asset isn't documented. A Web2 developer cannot discover from Celo's docs that they can give an agent a verified, sybil-resistant identity, with no crypto wallet required, backed by a passport-scan proof-of-human. + +### What the Self section should say (concrete fix for `build-with-self.mdx`) + +Add an "Identity for AI agents" section covering: Agent ID is live on Celo mainnet (registry `0xaC3DF9ABf80d0F5c020C06B04Cced27763355944`, chain 42220; Sepolia `0x043DaCac...`, chain 11142220 — warn that this is *not* the old Alfajores 44787); the wallet-free CLI registration quickstart (`self-agent register init --mode wallet-free --network testnet` → QR scan → export); `agent.fetch()` auto-signing on the agent side and the Express-middleware verifier (`requireAge(18).sybilLimit(3)`) on the service side; the ERC-8004 relationship (cross-link both directions); and Celo Agent Visa (gasless, tiered agent-activity NFT). Links: https://docs.self.xyz/docs/agent-id/overview/ (canonical — the same page the official MiniPay docs link to), the agent-builder guide, github.com/selfxyz/self-agent-id. + +--- + +## Jargon inventory (terms used before/without definition, high-traffic pages) + +| Term | Where | Fix | +|---|---|---| +| facilitator | x402 page, load-bearing | One-sentence plain definition at first use ("a service that checks and submits the payment for you — like a payment processor") | +| base units / decimals | x402 `maxValue`, adapter table | Inline comment with the dollar value; "you can lose 12 orders of magnitude here" warning | +| ERC-2612 / ERC-3009 / ERC20 / EVM | x402, landing | Link on first use or drop from intro-level pages | +| Token Duality, native transfer | landing | Move to protocol docs; irrelevant to arriving builders | +| fee currency / adapter address | AI overview | Keep — but always paired with the "why" sentence it already has (this page does it best) | +| soulbound NFT, nullifier, attestation | (will arrive with Agent ID content) | Introduce with plain-language glosses, as Self's own agent-builder guide does | +| ODIS, SocialConnect | identity pages | Fine for protocol docs; keep out of the agent-identity journey | + +## Structural fixes, ranked by impact + +1. **Landing page must route the primary audience.** Rewrite `home/index.mdx` (or the future real homepage — PR #2209 open decision #6) around jobs-to-be-done cards: *Build an agent that pays* / *Build a Mini App for 10M MiniPay users* / *Accept stablecoin payments* / *Run a node*. Sample rewrite of the intro for a Stripe-calibrated reader: + > **Celo is where AI agents and mobile-first apps move real money.** Payments settle in about a second and cost less than a cent, in stablecoins your users already understand (dollars, euros, and 20+ local currencies). Your agents don't need a separate gas token, your users don't need seed phrases, and your first payment works on testnet in ten minutes — no account required. +2. **Give agents a discoverable front door**: an `/agents`-style section reachable in one click, plus llms.txt so AI assistants route themselves (every benchmarked competitor ships this). +3. **Add the missing first mile**: one page answering "give my agent a wallet and test funds" (key generation → faucet → first transfer), linked before every code example that assumes `AGENT_PRIVATE_KEY`. +4. **Document Self Agent ID** (see Journey 2 fix) — currently the largest content gap relative to the team's stated message. +5. **Make one x402 path signup-free on testnet**, with an explicit success checkpoint, before introducing SDK keys. diff --git a/restructure-research/04-freshness-automation-proposal.md b/restructure-research/04-freshness-automation-proposal.md new file mode 100644 index 000000000..816c11f1d --- /dev/null +++ b/restructure-research/04-freshness-automation-proposal.md @@ -0,0 +1,162 @@ +# Docs Freshness Automation — Proposal + +**Status: proposal / basis for discussion. Nothing in this document is implemented yet.** + +The goal: whenever something changes in the Celo ecosystem — cLabs ships a release, DevRel publishes a new tool or template, a new project lands in the celo-org GitHub org, a program opens or *closes* — an automated loop drafts an example PR against the docs. Maintainers review and merge or close it. Humans always stay in the loop; the bot never pushes to `main`. + +## Why now + +- The only automation today is a broken-links check on PRs (`.github/workflows/docs-validation.yml`) and a manually-run contract-address generator (`scripts/update_contracts.py`). +- Staleness is already visible: hardcoded dates in `contribute-to-celo/daos.mdx` ("As of March 2025…"), a discontinued accelerator (Celo Camp) that was still listed in two pages until this PR, program links whose state the docs can't see, and network-upgrade notices that run on human memory. +- The repo already accepts bot PRs (Renovate), so the review culture exists. + +## Architecture overview + +Three loops, one config file, one state store. Core principle: **detection is deterministic (gh / curl / jq); only the drafting of page edits is LLM-driven; PR mechanics are owned by the workflow, never by the LLM.** + +``` +watch-targets.yml ──▶ detector job (gh api / curl + content hash) ──▶ change events + │ (exit early if none — zero LLM cost) +state branch ◀── cursor updates ▼ + claude-code-action (scoped prompt per event, + page allowlist, no git/gh/Bash tools) + │ + peter-evans/create-pull-request + (draft, labeled, idempotent branch name) + ▼ + maintainer merges or closes (close = permanent "no") +``` + +## 1. What to watch (signal sources) + +| Signal | Mechanism | Docs pages affected | +|---|---|---| +| Releases/tags on cLabs repos (celo-org/optimism, celo-org/op-geth, celo-org/celo-monorepo, celo-org/celo-composer) | `gh api repos/{r}/releases` against a stored cursor | `infra-partners/notices/*`, node pages, quickstart | +| New repos in the celo-org GitHub org (DevRel tools, templates, new projects) | `gh api orgs/celo-org/repos?sort=created` — filter: not a fork, not archived, has a description, ≥7 days old (quiet period) | `contribute-to-celo/builders.mdx`, tooling pages | +| **Program pages: Prezenti, CeloPG programs page (incl. Proof of Ship), other grant/accelerator pages** | `curl` + content hash of extracted text; alert on change, HTTP 4xx/5xx, or redirect-to-home | `contribute-to-celo/builders.mdx`, `contribute-to-celo/index.mdx`, MiniPay "Opportunities" section | +| **Celopedia (celo-org/celopedia-skills repo)** — program/grant/ecosystem data updated there | releases/commits on the repo's data files | program listings, ecosystem references — keeps docs and Celopedia telling the same story | +| **Dev-tooling sync: every documented tool** — Celo Composer, Celopedia, the x402 stack, Celo MCP server, the agent skills repos | **merged PRs** and releases on each repo (`gh api repos/{r}/pulls?state=closed&base=main` against a cursor, filtered to merged) → prompt: "verify the docs pages documenting this tool still match its current behavior/CLI/flags/APIs; draft corrections if not" | each tool's docs page(s) — e.g. `build-on-celo/quickstart.mdx` (Composer), `build-with-ai/x402.mdx`, `build-with-ai/celopedia.mdx`, `build-with-ai/mcp/*` | +| **Official MiniPay docs (docs.minipay.xyz)** | content hash of its `llms.txt` — a precise, cheap change signal (their page inventory + descriptions in one file) | Celo's MiniPay overview and any page linking into MiniPay docs — verify links still resolve and the overview still reflects what the official docs cover | +| Contract addresses | existing `update_contracts.py` (deterministic, no LLM) | `tooling/contracts/*` | + +> Open item: one more program source was requested but the name didn't come through clearly ("PDA scale"). CeloPG's programs page and Proof of Ship are included above as the likely candidates — to be confirmed and adjusted in `watch-targets.yml`. + +### Removals, not just additions + +Program content rots in both directions, and removal is the harder half — nothing "arrives" to trigger it. The Celo Camp case (accelerator discontinued, still listed in two pages) is the template for how the loop handles it: + +1. **URL-watch degradation**: a watched program URL starts failing (4xx/5xx), redirects to a generic homepage, or its content hash changes drastically → the event prompt explicitly asks: *"determine whether this program still exists; if it appears discontinued, draft a PR **removing** it from the listed pages, citing the evidence in the PR body."* +2. **Cross-source disagreement**: if Celopedia's program data drops a program that the docs still list, that mismatch is itself an event → removal PR. +3. **Cadence-based re-verification**: every page carrying a `review_cadence` (below) gets re-checked when overdue; the check prompt includes "remove anything you can no longer verify as active, and say so in the PR body" rather than only "update dates". + +Removal PRs get their own label (`bot:removal`) so reviewers know the diff is destructive and give it a closer look. + +## 2. Trigger + loop mechanics + +**Cron over webhooks for v1.** `repository_dispatch` from source repos needs org-level PAT coordination — defer to Phase 3. A weekly/twice-weekly cron loses at most a few days of latency, which is fine for docs. + +Per-run flow (`freshness-watch.yml`): +1. Checkout `main`; fetch `state.json` (cursors, URL hashes) from an `automation/state` branch. +2. Detector script emits `events.json`. **Exit early if empty — no LLM call on quiet weeks.** +3. Dedup: for each event, search existing PRs (open *and closed*) by idempotency key in the title. Closed-by-human = permanent "no", never retried. +4. Cap at `max_prs_per_run` (default 3); dropped events keep their cursor and surface next run. +5. Per surviving event: run `anthropics/claude-code-action` with a scoped prompt assembled from the target's `pages:` allowlist + prompt template + event payload. Tools restricted to Read/Grep/Glob/Edit/Write — **no Bash, no git, no gh**. +6. `peter-evans/create-pull-request`: branch `bot/freshness/`, `draft: true`, labels, body containing the source link, detected change, and idempotency key. +7. Commit updated cursors to `automation/state`. + +Declarative config, `.github/freshness/watch-targets.yml` (illustrative): + +```yaml +defaults: { max_prs_per_run: 3, labels: [bot:freshness] } +targets: + - id: op-geth-releases + kind: releases + repo: celo-org/op-geth + pages: [infra-partners/notices/, infra-partners/operators/] + prompt: > + A new op-geth release {tag} was published: {release_url}. + Check whether node-operator pages reference outdated versions or a new + upgrade notice is warranted. Edit only the listed pages. + - id: prezenti + kind: url-watch + url: https://www.prezenti.xyz/ + pages: [contribute-to-celo/builders.mdx] + prompt: > + The Prezenti page changed (or stopped resolving). Determine whether the + program is still active and whether its description in the docs is + accurate. If discontinued, remove it and say so in the PR body. + - id: celopg-programs + kind: url-watch + url: https://www.celopg.eco/programs + pages: [contribute-to-celo/builders.mdx, contribute-to-celo/index.mdx, build-on-celo/build-on-minipay/overview.mdx] + - id: celopedia-data + kind: releases + repo: celo-org/celopedia-skills + pages: [contribute-to-celo/builders.mdx, build-on-celo/build-with-ai/celopedia.mdx] + - id: celo-composer-sync + kind: merged-prs + repo: celo-org/celo-composer + pages: [build-on-celo/quickstart.mdx] + prompt: > + PRs were merged in celo-org/celo-composer since the last run: {pr_list}. + Verify the quickstart still matches the current CLI (commands, flags, + templates, prerequisites). Draft corrections if anything drifted. + - id: minipay-docs + kind: url-watch + url: https://docs.minipay.xyz/llms.txt + pages: [build-on-celo/build-on-minipay/] + prompt: > + The official MiniPay docs changed. Verify Celo's MiniPay pages still + link to valid targets and the overview still matches what the official + docs cover; the official docs are canonical for mini-app lifecycle + content — prefer removing duplication over restating it. + - id: new-org-repos + kind: new-repos + org: celo-org + filters: { min_age_days: 7, exclude_forks: true, require_description: true } + pages: [contribute-to-celo/builders.mdx, tooling/] + labels: [bot:new-project] +``` + +## 3. Page-level freshness metadata + +Additive frontmatter convention (Mintlify ignores unknown keys; survives the 4-tab restructure since the scanner globs `**/*.mdx`): + +```yaml +--- +title: Builders +last_verified: 2026-07-06 +review_cadence: 90 # days; omit → repo default 180 +sources: + - https://www.prezenti.xyz/ + - https://www.celopg.eco/programs +--- +``` + +A small script (`scripts/freshness_report.py`, no LLM) scans all pages weekly, groups them into overdue / no-metadata / autogenerated (skipped via the existing "DO NOT EDIT" marker), and updates **one pinned issue** (labeled `bot:stale-report`, body replaced each week — one issue forever, not one per week). `last_verified` is bumped by humans when merging bot PRs or touching a page. + +Roll out incrementally: start with the ~15 known stale-prone pages (programs, DAOs, notices, provider lists); do the bulk rollout **after** the 4-tab restructure lands to avoid mass conflicts with the restructure PRs. + +## 4. Guardrails + +- **Draft PRs only, never a push to `main`** (branch protection enforces this regardless of bugs). +- Label taxonomy: `bot:freshness`, `bot:new-project`, `bot:removal`, `bot:contracts`, `bot:stale-report` — all also `automation` for one-click filtering. +- Noise controls: max 3 PRs/run, 7-day quiet period on new repos, closed-PR keys never retried, detector exits before any LLM call when nothing changed, `--max-turns` cap on the action. +- Content controls: contract pages are script-owned (LLM denied from `tooling/contracts/`); each prompt is constrained to its target's page allowlist; the existing broken-links check runs on every bot PR. +- Secrets: `ANTHROPIC_API_KEY`, `TENDERLY_API_KEY` (contracts job), and one fine-grained PAT or GitHub App token — needed because PRs created with the default `GITHUB_TOKEN` don't trigger the docs-validation workflow. +- Cost: weekly cadence, ≤3 scoped LLM invocations per run with small page allowlists → cents to low dollars per week. The stale report and contracts jobs use no LLM at all. + +## 5. Phasing + +- **Phase 0 (day one, no LLM):** schedule `update_contracts.py` weekly; open a PR only when `git diff` is non-empty. Proves out the whole draft-PR/label/secret plumbing every later loop reuses. (Runner needs `celocli`, Foundry's `cast`, Python 3.12, `TENDERLY_API_KEY` — pin versions.) +- **Phase 1 (MVP):** `freshness-watch.yml` with 2–3 release targets (op-geth, optimism → upgrade notices and node pages — the content whose staleness has real operational cost), **plus the URL-watch targets (Prezenti, CeloPG, docs.minipay.xyz llms.txt) with removal handling**, plus the LLM-free stale-page report with metadata on the known stale pages. +- **Phase 2:** dev-tooling sync loop — merged-PR watchers on every documented tool (Celo Composer, x402 stack, Celopedia, Celo MCP, agent skills repos) verifying the corresponding docs pages after each merge; new-repo detector for the celo-org org; DevRel template repos. +- **Phase 3:** `repository_dispatch` from source repos for near-real-time triggers, full metadata rollout post-restructure, optional `/verified` PR-comment command to bump `last_verified`. + +## Files this would add (when implemented) + +- `.github/workflows/update-contracts.yml` (Phase 0) +- `.github/workflows/freshness-watch.yml`, `.github/workflows/stale-report.yml` (Phase 1) +- `.github/freshness/watch-targets.yml` — the single place the team edits to watch something new +- `scripts/detect_changes.sh`, `scripts/freshness_report.py` +- `state.json` on an `automation/state` branch (not on `main`) diff --git a/restructure-research/05-skills-and-feedback-discussion.md b/restructure-research/05-skills-and-feedback-discussion.md new file mode 100644 index 000000000..ad0ac5d44 --- /dev/null +++ b/restructure-research/05-skills-and-feedback-discussion.md @@ -0,0 +1,48 @@ +# Skills & Builder Feedback — Discussion Document + +**Status: discussion input, not a decision.** This document frames one question the team needs to settle: *how should feedback from builders (and their AI agents) flow back into the docs and dev tooling — through a flag in every skill, or through one central feedback skill?* It also answers the related question: *does a dedicated "docs skill" make sense?* + +## Current state + +- Celo already ships a family of installable agent skills (x402, ERC-8004, MiniPay integration, Celo Composer, stablecoins, fee abstraction, RPC, DeFi, wallet integration, Foundry/Hardhat, thirdweb, viem, wagmi, …). +- **Celopedia already exists and is exactly the "encyclopaedia" idea**: a knowledge skill packaging ecosystem data, contract addresses, MiniPay guidance, grants info, and agent-infrastructure references, installable via `npx skills add celo-org/celopedia-skills` (documented at `build-on-celo/build-with-ai/celopedia.mdx`). +- What does **not** exist: any structured way for a builder — or a builder's coding agent — who hits a docs gap, a wrong contract address, or a broken example to turn that into a tracked issue or draft PR. Today that feedback dies in Discord or never gets reported. +- Benchmark context: Stripe, Base, Solana, and Abstract all ship installable docs/skills stacks, but none of them has solved the *feedback return path* either. This is a place Celo can lead, and it composes with the freshness automation proposal (`04-freshness-automation-proposal.md`) — bot loops push updates out, the feedback skill pulls corrections in, both land as labeled draft PRs/issues in the same queue. + +## The options + +### Option A — feedback flag in every skill +Each skill (x402, MiniPay, viem, …) gets its own "if something didn't work, report it" section with repo targets and instructions. + +- Pro: feedback guidance is right where the failure happens. +- Con: the routing knowledge (which repo, which labels, issue template, dedup etiquette, when to open a PR vs an issue) is duplicated N times and **will drift** — the same maintenance problem the docs themselves have, multiplied across every skill. Updating a label taxonomy would mean touching every skill. + +### Option B — one central feedback skill +A single `celo-feedback` skill that owns all routing knowledge. Every other skill contains only a one-line pointer: "Hit a problem with these instructions? Use the celo-feedback skill." + +- Pro: one place to maintain routing (repos, labels, templates); consistent, deduplicatable output on the maintainer side; the skill can get smarter (search existing issues before filing, attach environment info, propose a docs diff) without touching any other skill. +- Con: one extra install/reference hop; the feedback skill must know the whole surface (docs repo vs composer repo vs celopedia repo) — but that's precisely the knowledge that should be centralized. + +### Option C — hybrid (recommended) +Option B, plus the thin one-line pointer in each skill's "troubleshooting" section. The pointer is stable (it never changes), so there's nothing to drift; all living knowledge stays in `celo-feedback`. + +## Recommendation + +1. **One central `celo-feedback` skill (Option C).** Routing knowledge in one place; every other skill carries only a stable pointer. +2. **Don't build a new "docs skill" — Celopedia already is one.** Extend Celopedia as the canonical encyclopaedia and make the funnel explicit: *answer first, feedback second.* When a builder (or their agent) has a question, Celopedia answers it from ecosystem knowledge; only when the answer is missing, wrong, or outdated does it hand off to `celo-feedback`. This keeps noise out of the issue tracker and gives maintainers signal-rich reports ("Celopedia had no answer for X" is itself a docs-gap datapoint). +3. **Feed the same queue as the freshness automation.** Feedback-skill output uses the same label taxonomy (`feedback:docs`, `feedback:skill`, `feedback:tooling` alongside the `bot:*` labels), so maintainers review one stream of labeled, deduplicated, draft-first contributions. + +## Sketch: what `celo-feedback` would contain + +- **Routing table**: docs repo (celo-org/docs), Celopedia (celo-org/celopedia-skills), Celo Composer, MCP server repo, skill repos — each with: what belongs there, issue labels, whether draft PRs are welcome. +- **Dedup protocol**: search open and closed issues/PRs for the same symptom before filing; comment on an existing thread instead of duplicating. +- **Report format**: what was attempted, exact failing step/command, environment (chain, network, SDK version), expected vs actual, and — when the fix is obvious — a proposed diff as a draft PR rather than an issue. +- **Escalation guidance**: what goes to GitHub vs what goes to Discord/Forum (usage questions vs defects). + +## Open questions for the discussion + +1. Who owns triage of the incoming `feedback:*` queue — DevRel, docs maintainers, or rotating? +2. Should the feedback skill be allowed to open draft PRs directly (higher value, higher noise risk), or issues only in v1? +3. Does agent-filed feedback need its own label (`feedback:agent-filed`) so humans can calibrate trust? +4. Should Celopedia's "I had no answer for this" events be logged somewhere even when the user doesn't file feedback — turning unanswered questions into a docs-gap heatmap? +5. Scope: docs + skills only in v1, or all dev tooling (Composer, MCP, SDK wrappers) from day one? diff --git a/restructure-research/README.md b/restructure-research/README.md new file mode 100644 index 000000000..9c67461cb --- /dev/null +++ b/restructure-research/README.md @@ -0,0 +1,13 @@ +# Restructure Research + +Companion research to the docs restructure proposal (PR #2209). No navigation or content moves happen here — these documents inform the restructure discussion and two follow-up workstreams (freshness automation, builder feedback skills). + +| Doc | What it answers | +|---|---| +| `01-benchmark-report.md` | How 11 leading docs sets (Base, World, Optimism, Solana, TON, CDP, Stripe, NEAR, Privy, Abstract, Crossmint) structure for consumer + agent developers, and what Celo should adopt | +| `02-restructure-review.md` | Review of PR #2209 from the agent-first lens: endorsements, the one gap, positions on all 7 open decisions, new work items slotted into its PR sequence | +| `03-web2-readability-audit.md` | Page-by-page walk of two Web2-developer journeys (agent payments, agent identity), jargon inventory, ranked structural fixes | +| `04-freshness-automation-proposal.md` | Design (proposal only) for automated loops that draft docs PRs when cLabs/DevRel/ecosystem ships — or discontinues — something; page-freshness metadata; guardrails; phasing | +| `05-skills-and-feedback-discussion.md` | Discussion input: one central feedback skill vs per-skill flags, and Celopedia's role as the docs encyclopaedia | + +The only content change bundled with this PR: removal of the discontinued Celo Camp accelerator from `contribute-to-celo/builders.mdx` and `contribute-to-celo/index.mdx` — which doubles as the worked example for the "removals" section of doc 04.