celo-org / celo-org/docs

story: Agent-experience pass — first-mile wallet page, x402 polish, troubleshooting examples, discoverability research

Open
#2,263 0 comments 0 reactions 1 assignee Claimed by @viral-sangani View on GitHub
documentation enhancement priority:medium size:M status: triage
Dominant language
MDX
Stars
90
Forks
382
Avg merge
3d 9h
Merged PRs (30d)
35

Description

Part of #2266.

### User story

As a Web2 developer arriving for agent payments, I want to succeed on testnet without leaving the docs; as an AI agent, I want the troubleshooting facts the SDK docs leave out.

### Context & evidence

Verified at `bdf40b37`:
- `build-on-celo/build-with-ai/overview.mdx` and `x402.mdx` start from `AGENT_PRIVATE_KEY` in an env var with no page answering "how does my agent get a wallet and test funds".
- `x402.mdx` uses *facilitator* without a plain-language definition, shows `maxValue: "1000000"` without saying what that is in dollars, and has no explicit success checkpoint. (The earlier "needs a thirdweb client ID first" blocker is already fixed — Celo's own facilitator is the featured path.)
- Troubleshooting cases that SDK docs cover in one paragraph — paying gas in USDC, adapter vs token address, 6 vs 18 decimals — are the examples worth keeping per the code-example policy in `AGENTS.md` (#2251).
- Agent-discoverability research exists and is to be folded in here once shared (OPEN: attach it to this issue).

### Scope

1. One **"Give your agent a wallet and test funds"** page: key generation → faucet → first transfer; linked before every example that assumes `AGENT_PRIVATE_KEY`.
2. **x402 page:** define *facilitator* in one plain sentence at first use; inline-comment base units (`maxValue: "1000000"` = $1 for a 6-decimal token); an explicit "you just charged an agent $0.01" success checkpoint.
3. **Troubleshooting examples** across the agent pages: gas in USDC per SDK, adapter vs token address, decimals.
4. **Fold in the discoverability research:** actionable items done here or split into follow-ups.
5. **Jargon pass** on the agent journey: link ERC-20 / EVM on first use.

### Acceptance criteria

- [ ] First-mile page live and linked from `build-with-ai/overview` and `x402`
- [ ] x402 changes as listed
- [ ] Research attached; each actionable item either done here or linked as a follow-up issue
- [ ] Every example run once; command and output in the PR

### Non-goals

Self Agent ID (#2262); the AI-resources page (#2261); MiniPay (#2264).

### Depends on / blocks

Depends on #2259 for final paths — content can be drafted earlier.

**Measured at:** `bdf40b37`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.