feat: agents docs

README.md

@@ -31,6 +31,16 @@ We enable businesses and consumers to quickly introduce instantaneous Bitcoin pa
 
 With ZBD, it's easy! Anyone can do it. **[What are YOU building?](https://dashboard.zbdpay.com)**
 
+## Agents Docs Fast Path
+
+If you are documenting or testing the Agents toolkit, start here:
+
+- Overview: `/agents`
+- Quick start: `/agents/quickstart`
+- Runnable examples: `/agents/agent-pay` and `/agents/agent-fetch`
+
+The `agent-pay` and `agent-fetch` repositories include `examples/` scripts that let users run a working paid-request flow in minutes.
+
 ## Contributing
 
 ### Development

agents.mdx

@@ -0,0 +1,96 @@
+---
+title: "ZBD Agents"
+sidebarTitle: "Overview"
+description: "Build agent-native Bitcoin flows with zbdw, agent-pay, and agent-fetch."
+---
+
+The ZBD Agents toolkit gives you an end-to-end stack for agentic payments: a wallet CLI (`zbdw`), an L402 client (`agent-fetch`), an L402 server middleware (`agent-pay`), and supporting apps for identity and operations.
+
+<Info>
+  Want the fastest hands-on path? Start with the runnable scripts in `agent-pay/examples/http-server.mjs` and `agent-fetch/examples/zbd-agent-fetch.mjs`.
+</Info>
+
+<CardGroup cols={2}>
+  <Card title="Start in Minutes" icon="rocket" href="/agents/quickstart">
+    Install one package, run `zbdw init`, and execute your first paid request.
+  </Card>
+  <Card title="Monetize Any Endpoint" icon="lock" href="/agents/agent-pay">
+    Add payment gates to Express, Hono, and Next.js route handlers.
+  </Card>
+  <Card title="Pay 402 Automatically" icon="bolt" href="/agents/agent-fetch">
+    Auto-handle L402 challenges with max payment guardrails and token caching.
+  </Card>
+  <Card title="Learn Pay Per Call (L402)" icon="coins" href="/agents/l402">
+    Follow the complete server + client pattern for Lightning-gated API calls.
+  </Card>
+  <Card title="Operate with Confidence" icon="chart-line" href="/agents/agent-wallet-dashboard">
+    Use the dashboard to inspect balances, payment history, and local wallet state.
+  </Card>
+  <Card title="Ship Agent Skills" icon="wand-magic-sparkles" href="/agents/skills">
+    Package `zbdw` workflows into reusable skills for IDE agents and OpenClaw-compatible runtimes.
+  </Card>
+</CardGroup>
+
+## Choose Your Path
+
+<Tabs>
+  <Tab title="Developer">
+    **Goal:** launch a working agent payment flow fast.
+
+    1. Start with the [Quick Start](/agents/quickstart)
+    2. Add payment-gated routes with [agent-pay](/agents/agent-pay)
+    3. Pay those routes with [agent-fetch](/agents/agent-fetch) or `zbdw fetch`
+  </Tab>
+  <Tab title="Product & PM">
+    **Goal:** validate monetization and ops fit.
+
+    - Map capabilities in [Architecture](/agents/architecture)
+    - Review deployment surfaces in [Repo Map](/agents/repo-map)
+    - Track live wallet activity in [Agent Wallet Dashboard](/agents/agent-wallet-dashboard)
+  </Tab>
+  <Tab title="Platform Team">
+    **Goal:** standardize identity and payments infrastructure.
+
+    - Set up [zbd.ai Registry](/agents/registry) for stable Lightning addresses
+    - Standardize env vars and shared file paths
+    - Adopt workspace verification scripts for CI
+  </Tab>
+</Tabs>
+
+## Core Repositories
+
+<CardGroup cols={2}>
+  <Card title="agent-wallet" icon="github" href="https://github.com/zbdpay/agent-wallet">
+    CLI wallet and command router for ZBD agent payments (`zbdw`).
+  </Card>
+  <Card title="agent-fetch" icon="github" href="https://github.com/zbdpay/agent-fetch">
+    L402-aware fetch client for paid HTTP resources.
+  </Card>
+  <Card title="agent-pay" icon="github" href="https://github.com/zbdpay/agent-pay">
+    L402 middleware for Express, Hono, and Next.js.
+  </Card>
+  <Card title="agent-wallet-dashboard" icon="github" href="https://github.com/zbdpay/agent-wallet-dashboard">
+    Local dashboard for wallet balances and payments history.
+  </Card>
+</CardGroup>
+
+<Info>
+  `zbdw` is the binary shipped by `@zbdpay/agent-wallet`. It is designed for JSON-first CLI interoperability with agent runners.
+</Info>
+
+## What You Can Build
+
+<AccordionGroup>
+  <Accordion title="Paid API products" icon="server">
+    Gate premium API routes with `agent-pay`, then let autonomous clients unlock access via `agent-fetch`.
+  </Accordion>
+  <Accordion title="Autonomous data acquisition" icon="database">
+    Use `zbdw fetch` to allow agents to pay per request and retrieve premium content in one command.
+  </Accordion>
+  <Accordion title="Agent-to-agent commerce" icon="arrow-right-arrow-left">
+    Combine wallet send/receive primitives with L402 middleware to create closed-loop service economies.
+  </Accordion>
+  <Accordion title="Operations and observability" icon="gauge-high">
+    Track local wallet activity in `~/.zbd-wallet` and visualize it with the dashboard.
+  </Accordion>
+</AccordionGroup>

agents/agent-fetch.mdx

@@ -0,0 +1,140 @@
+---
+title: "Agent Fetch"
+description: "Use agentFetch to parse 402 challenges, pay invoices, and retry automatically with L402 proof."
+---
+
+`@zbdpay/agent-fetch` is the client half of the L402 flow. It accepts a payment hook, handles challenge parsing, enforces guards, and retries with proof.
+
+<CardGroup cols={2}>
+  <Card title="Repository" icon="github" href="https://github.com/zbdpay/agent-fetch">
+    Source, tests, and engineering contract.
+  </Card>
+  <Card title="NPM Package" icon="cube" href="https://www.npmjs.com/package/@zbdpay/agent-fetch">
+    Install and integrate into existing runtimes.
+  </Card>
+</CardGroup>
+
+## Install
+
+```bash
+npm install @zbdpay/agent-fetch
+```
+
+## Minimal Integration
+
+```typescript
+import { agentFetch, FileTokenCache } from "@zbdpay/agent-fetch";
+
+const tokenCache = new FileTokenCache(`${process.env.HOME}/.zbd-wallet/token-cache.json`);
+
+const response = await agentFetch("https://example.com/protected", {
+  tokenCache,
+  maxPaymentSats: 100,
+  pay: async (challenge) => {
+    // Pay challenge.invoice with your wallet implementation.
+    return {
+      preimage: "<payment-preimage>",
+      paymentId: "<payment-id>",
+      amountPaidSats: challenge.amountSats,
+    };
+  },
+});
+
+console.log(response.status, await response.json());
+```
+
+## API Surface
+
+```typescript
+import {
+  agentFetch,
+  requestChallenge,
+  payChallenge,
+  fetchWithProof,
+  FileTokenCache,
+} from "@zbdpay/agent-fetch";
+```
+
+## Core Options
+
+| Option | Required | Purpose |
+|---|---|---|
+| `pay(challenge)` | Yes | Pays parsed challenge and returns preimage or payment ID |
+| `waitForPayment(paymentId)` | No | Polls async settlement when preimage is not immediate |
+| `tokenCache` | No | Cache for URL-scoped authorization proofs |
+| `maxPaymentSats` | No | Hard cap to reject expensive challenges |
+| `requestInit` | No | Base request options forwarded to `fetch` |
+| `paymentTimeoutMs` | No | Async settlement timeout |
+| `paymentPollIntervalMs` | No | Poll interval for async settlement |
+
+## Manual Flow (Advanced)
+
+<CodeGroup>
+```typescript requestChallenge + payChallenge
+import { requestChallenge, payChallenge } from "@zbdpay/agent-fetch";
+
+const challenge = requestChallenge({
+  status: 402,
+  headers: response.headers,
+  bodyText: await response.text(),
+});
+
+const paid = await pay(challenge);
+const authorization = payChallenge(challenge, paid);
+```
+
+```typescript fetchWithProof
+import { fetchWithProof } from "@zbdpay/agent-fetch";
+
+const res = await fetchWithProof(
+  "https://example.com/protected",
+  { method: "GET" },
+  authorization,
+  fetch,
+);
+```
+</CodeGroup>
+
+## Behavior Guarantees
+
+<Steps>
+  <Step title="Cache lookup first">
+    If a valid token exists for the URL, request is sent with proof immediately.
+  </Step>
+  <Step title="Pass-through for non-402">
+    Non-paid endpoints are returned untouched.
+  </Step>
+  <Step title="Challenge parsing">
+    Supports both `L402` and `LSAT` challenge schemes.
+  </Step>
+  <Step title="Payment and retry">
+    Runs caller-provided payment logic, then retries with authorization proof.
+  </Step>
+  <Step title="Proof caching">
+    Stores token and optional expiry for reuse.
+  </Step>
+</Steps>
+
+## Runnable Examples
+
+The repository includes maintained scripts under `examples/`:
+
+- `examples/zbd-agent-fetch.mjs`: end-to-end paid fetch using ZBD API payment hooks
+- `examples/fetch-with-known-proof.mjs`: fetch with a precomputed L402 authorization token
+
+From the agents workspace, run:
+
+```bash
+npm --prefix agent-fetch run build
+PROTECTED_URL="https://api.example.com/protected" ZBD_API_KEY=<your_api_key> npm --prefix agent-fetch run example:zbd
+```
+
+If you already have an authorization token:
+
+```bash
+PROTECTED_URL="https://api.example.com/protected" L402_AUTHORIZATION="L402 <macaroon>:<preimage>" npm --prefix agent-fetch run example:proof
+```
+
+<Warning>
+  `pay` is mandatory. `agent-fetch` does not call ZBD directly unless you implement that behavior in your payment hook.
+</Warning>