run402: Instructions file for Codex

AGENTS.md

This file is the single source of truth for AI coding agents working in this repository (Claude Code, Codex, Cursor, Grok, Cline, OpenClaw, etc.). CLAUDE.md imports it via @AGENTS.md.

Updating docs? See documentation.md — the map of every doc surface, with target audience, content summary, and update triggers. Scan it before merging code changes.

Documentation policy

Use CLI by default in general operating examples. Use SDK examples in typed scripting/reference guides, MCP calls in MCP references, HTTP in protocol references, and native code in application-runtime guides. Root SKILL.md and openclaw/SKILL.md share the CLI-first body; MCP-native onboarding lives in the MCP reference. Describe the HTTP API foundation, the typed and opinionated SDK workflow layer, and thin CLI/MCP adapters. Edit authoring sources and regenerate flat docs/discovery artifacts. Never turn a missing CLI capability into an invented command.

What This Is

run402 is a developer platform that ships Postgres databases, content-addressed CDN storage, static site hosting, Node 22 serverless functions, email, image generation, and KMS-backed Ethereum signing — provisioned by AI agents and paid for autonomously via x402 USDC on Base, MPP pathUSD on Tempo, or the organization's card-funded allowance. Prototype tier is free on testnet.

This monorepo ships six interfaces:

• SDK (sdk/) — typed TypeScript client for the run402 API. Used by external integrators and by MCP/CLI/OpenClaw. Published as @run402/sdk on npm. Two entry points: root (isomorphic — works in Node 22, Deno, Bun, V8 isolates) and /node (zero-config Node defaults — keystore + wallet + x402).
• MCP server (root src/) — published as run402-mcp on npm. Exactly eight tools: up and deploy (the first deploy), status, whoami, doctor, docs, run, and expand_result. Every other operation is a run snippet: TypeScript executed against the Node SDK in a QuickJS-in-WebAssembly sandbox. Read by Claude Desktop / Cursor / Cline / Claude Code.
• CLI (cli/) — standalone CLI published as run402 on npm. Each subcommand is a thin shim over an SDK call; argv parsing and JSON output stay at the CLI edge.
• Functions library — in-function helper imported inside deployed serverless functions. Exposes auth.* (the canonical auth namespace — auth.user, requireUser, requireRole, requireMembership, requireFresh, fetch, csrfToken/csrfField, sessions.*, identities.link), db(req?), adminDb(), email, ai, and assets. Published as @run402/functions on npm. Source lives in the public run402-core repo under packages/functions; Run402 Cloud consumes the published npm package when it bundles deployed functions. Distinct from the SDK: this is the request-scoped, in-function shape; the SDK is the typed external client. The two are complementary, not redundant.
• OpenClaw skill (openclaw/) — script-based skill for OpenClaw agents, re-exports from CLI modules.
• Astro integration (astro/) — framework integration that wires the SDK into Astro's build pipeline. Ships an <Image> component (build-time scan + variant rewrite), an assetsDir/manifest pattern for data-driven sites, and runtime helpers (resolveVariants, renderPicture) for the recommended AssetRef-persistence pattern where consumers store the full AssetRef returned by r.assets.put in their data rows. Published as @run402/astro on npm.
• Buzz integration (buzz/) — self-contained run402-buzz skill with global CLI/profile setup, dual-proof fixtures/helper, four-state human/community/agent control-plane reporting, verified no-deploy readiness, bounded enrollment offers, and an approval-gated org-of-one fallback. It never accepts or derives from a Nostr private key, and public proof alone grants no authority.