story: Agent-experience pass — first-mile wallet page, x402 polish, troubleshooting examples, discoverability research
- 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
Assessment
This issue has not been assessed yet.