# Run402 CLI -- Postgres & Static Hosting for AI Agents

> CLI: npm install -g run402
> SDK: npm install @run402/sdk (typed TS client for custom code — same namespaces as the CLI, works in Node/Deno/Bun/V8 isolates)
> Docs URL: https://docs.run402.com/llms-cli.txt
> API Docs: https://run402.com/llms.txt
> Operator: Kychee, Inc.
> Terms: https://run402.com/humans/terms.html
> Contact: run402 message send "your message" (requires active tier)

## TL;DR

Run402 is a Postgres + REST + Auth + Storage + static site hosting + Node 22 serverless functions + email + image generation platform, exposed through one CLI. Three things make it different from stitching together a DB host, a static-site host, and a functions runtime:

1. One atomic apply across the whole stack. `run402 deploy apply --manifest app.json` ships DB migrations, site files, function code, secrets, and the route table as a single transaction. Partial failures roll back as a unit — there is no "frontend deployed, DB migration failed, now what" state to clean up.
2. No platform access token to mint or rotate. The credential is a local allowance file (`~/.config/run402/allowance.json`) the agent owns and signs with — no Run402 dashboard token, no service-account JSON, no expiring CLI key. Per-project `anon_key` / `service_key` exist for the runtime data plane (PostgREST, Storage, Functions) but never expire either; they're embedded in client code, not rotated.
3. The agent pays for its own usage. Provisioning, deploys, and metered calls authorize via x402 USDC on Base or MPP pathUSD on Tempo, signed by the allowance — no human-in-the-loop billing handoff. A human can top up the allowance with Stripe credits; the agent doesn't notice the funding source.

**Install + deploy in 5 commands:**

```bash
npm install -g run402
run402 init
run402 tier set prototype
run402 projects provision --name "my-app"    # → returns anon_key, service_key, project_id
run402 deploy apply --manifest app.json      # use the anon_key in your frontend code
```

Provision first, then write your frontend code with the real `anon_key` embedded. The key has no expiry — it's a permanent project identifier. The `prototype` tier is free with the testnet faucet (it verifies your allowance and x402 signing work end-to-end without spending real money); switch to `hobby` / `team` in Step 3 when you're ready for mainnet.

## Core facts

- Allowance: `~/.config/run402/allowance.json` (0600). Projects: `~/.config/run402/projects.json` (0600)
- Credentials saved automatically after provision or fork
- `<id>` in commands = `project_id` from `run402 projects list`
- All output is JSON on stdout; errors are JSON on stderr; exit 0 = success, non-zero = error. See Output Contract below.
- The CLI handles x402 signing automatically — do not request private keys or set up payment libraries manually
- GitHub Actions deploys use OIDC: link once with `run402 ci link github`, then the generated workflow calls the existing `run402 deploy apply` command with `permissions: id-token: write`
- Projects, sites, subdomains, forks, functions, secrets, blob storage: free with active tier. Only image generation ($0.03) is per-call
- Env overrides: `RUN402_API_BASE` (default `https://api.run402.com`), `RUN402_CONFIG_DIR` (base credential dir, default `~/.config/run402`), `RUN402_WALLET` (active named wallet/profile, default `default`; alias `RUN402_PROFILE`), `RUN402_ALLOWANCE_PATH` (custom allowance file path, default `{config_dir}/allowance.json`)
- Multiple wallets on one machine: `run402 wallets` manages named wallets (profiles). Select per-command with `--wallet <name>` (alias `--profile`), `RUN402_WALLET`, or a per-directory `.run402.json` binding (walk-up, commit-safe — holds only a name). Precedence: `--wallet` > `RUN402_WALLET` > `.run402.json`/`.run402.local.json` > `wallets use` default > `default`. A `RUN402_WALLET` that conflicts with a `.run402.json` binding is a hard error unless `--wallet` is passed. The `default` wallet stays at the config-dir root (zero migration); named wallets live under `{base}/profiles/<name>/`. The active wallet name is echoed on stderr for non-default selections and appears in `run402 status` / `run402 wallets current`.

## Output Contract

Every CLI subcommand follows the same stdout/stderr/exit-code contract. Read this once; it applies uniformly to every command in the rest of this file.

Stdout (success) — the natural JSON payload, never wrapped. No top-level `status` field. The payload's shape depends on the command:
- Reads / lists / info — emit the resource directly (`projects info` returns `{ project_id, anon_key, ... }`; `projects list` returns `{ projects: [...], scope?, has_more?, next_cursor? }`).
- Mutations with no natural payload — echo the affected resource identifiers plus an explicit boolean state field naming what happened, e.g. `{ key, project_id, set: true }`, `{ name, project_id, deleted: true }`, `{ domain, project_id, released: true }`. Never an empty object.
- Local-state inspection — `run402 status` and `run402 allowance status` use typed nullable payload fields: `{ wallet: null, hint: "Run: run402 init" }` when absent, and the populated account/wallet payload when present. Absence exits 0 — it is an informational read, not an error.
- Plain text — a small set of commands (e.g. `run402 allowance export` returning a wallet address) emit a plain-text value with a trailing newline; their help text documents this.

Stderr (failure) — a structured JSON error envelope with `status: "error"` and non-zero exit. The `status` field is the sentinel that says "this is an error" — it is preserved on stderr only and never appears on stdout. The envelope's other canonical fields are described under Error JSON and Safe Retry below.

Exit code — `0` means the subcommand completed; non-zero means it failed and the structured envelope is on stderr. Validation commands that find issues (e.g. `validate-expose` reporting `hasErrors: true`) still exit 0 — the command itself succeeded; agents read `hasErrors` from the payload to decide what to do.

Per-payload `status` fields are not envelopes. `run402 doctor` reports per-check items inside a `checks[]` array, each of which has its own `status: "ok" | "warning" | "missing" | "skipped"` label. Those are payload contents, not the top-level envelope, and they are NOT the same as the (forbidden) top-level `status` wrapper.

This contract is enforced by a drift-protection test (`cli-output-contract.test.mjs`) that fails CI on any new top-level `JSON.stringify({ status: ... })` emission outside `cli/lib/sdk-errors.mjs`. If you find a command violating this contract, file an issue — it is a regression, not a feature.

**Breaking change in v3.0:** Earlier `run402` CLI versions wrapped many success payloads as `{ status: "ok", ...payload }`. v3.0 dropped the wrapper across every subcommand. Consumers should drop any `.status === "ok"` checks and gate on exit code instead. The stderr error envelope is unchanged.

## Error JSON and Safe Retry

CLI errors are JSON on stderr with an outer `"status": "error"` sentinel. Run402 JSON bodies may be merged into that object with canonical fields. Branch on `code`, not English `message` or legacy `error` text.

Canonical fields:
- `code`: stable machine-readable reason, e.g. `PROJECT_FROZEN`, `PAYMENT_REQUIRED`, `MIGRATION_FAILED`, `MIGRATE_GATE_ACTIVE`. Client-side validation failures (missing flag, malformed JSON, unknown local project) default to `BAD_USAGE`; specific client-side cases use richer codes e.g. `UNKNOWN_FLAG`, `BAD_FLAG`, `PROJECT_NOT_FOUND` (with `details.source: "local_registry"`), `NO_DEPLOYMENT`, `NO_ALLOWANCE`, `BAD_JSON_FLAG`, `CONFIRMATION_REQUIRED`.
- `retryable`: the same request may succeed later
- `safe_to_retry`: repeating the same request should not duplicate or corrupt a mutation
- `mutation_state`: one of `none`, `not_started`, `committed`, `rolled_back`, `partial`, `unknown`
- `trace_id`: include this when reporting the issue
- `request_id`: routed/function failure handle; use `run402 functions logs <id> <name> --request-id <req_...>` for function diagnostics. This is distinct from gateway `trace_id`.
- `details`: structured route-specific context
- `next_actions`: advisory suggestions e.g. `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, `edit_migration`, or `deploy_site_first`; do not execute route-like suggestions without validating method/path/auth/safety

Retry policy:
- If `retryable: true` and `safe_to_retry: true`, retry the same request; for mutating commands reuse the same idempotency key when available.
- `safe_to_retry: true` alone is not a retry signal; it means duplicate-safe, not likely-to-succeed. Lifecycle-gated writes, auth token exchanges, and passkey verifies need the indicated action before retrying.
- `run402 deploy apply` already handles safe `BASE_RELEASE_CONFLICT` release races for omitted/current-base deploy specs: it re-plans, emits `deploy.retry` events on stderr, and stops after its bounded SDK retry budget. Exhausted deploy retries include `attempts`, `max_retries`, and `last_retry_code` in the error envelope. Do not hand-roll this specific retry loop around the CLI unless you intentionally disabled SDK retries upstream.
- If a mutating command returns 5xx with `safe_to_retry: false`, or `mutation_state` is `committed`, `partial`, or `unknown`, inspect/poll/reconcile state before retrying. For deploys, prefer `run402 deploy events <operation_id>` or `run402 deploy resume <operation_id>` over starting a duplicate operation.
- Lifecycle/payment errors usually need an action: `PROJECT_FROZEN`/`PROJECT_DORMANT`/`PROJECT_PAST_DUE` -> `run402 projects usage <id>` or `run402 tier set <tier>`; `PAYMENT_REQUIRED`/`INSUFFICIENT_FUNDS` -> submit payment or fund allowance.
- `NOT_AUTHORIZED` (HTTP 403) is an org-owned-control-plane authorization denial (v1.77+), distinct from auth or payment: the wallet *authenticated*, but its resolved principal lacks the org role or per-project grant the action needs. `details` carries `required_role` / `required_capability` / `reason`. Not retryable without obtaining a covering org membership/role or grant; high-stakes ops (delete, transfer-of-ownership, membership change) require an active `owner` membership. The gateway returns 403 even when the project does not exist (so existence isn't leaked) — re-check the `<id>` too. The CLI envelope adds an actionable `hint`.
- `STEP_UP_REQUIRED` (HTTP 403) is a freshness/provenance demand for a high-stakes control-plane op: the session is valid but not fresh enough, or was minted by a read/device-flow path that can't satisfy a passkey step-up. `details` carries `required_amr` / `max_age_seconds` / `challenge_url` / `reason`, plus `next_actions[]`. The SDK raises a typed `StepUpRequiredError` (`isStepUpRequired()` guard). Resolve with `run402 operator login --step-up` on the same client, then retry. Distinct from `NOT_AUTHORIZED` (a role/grant gap, not a freshness gap).
- Client-side `BAD_JSON_FLAG` errors include `details.flag` (the offending flag, e.g. `--abi`) and `details.value_preview` (truncated value) so callers know which flag value to fix.
- CLI commands reject unknown flags and missing flag values locally with `UNKNOWN_FLAG` or `BAD_FLAG` before network work. Numeric and wei-like flags are strict decimal integers: malformed, fractional, negative, and scientific-notation values fail locally instead of being forwarded to the API.
- Commands with fixed positional shapes also reject extra positional arguments locally. This includes deploy resume/list/events/release subcommands, functions list/delete, and blob get/rm/sign/diagnose.

Examples:
```json
{ "status": "error", "http": 403, "message": "Project is frozen.", "code": "PROJECT_FROZEN", "category": "lifecycle", "retryable": false, "safe_to_retry": true, "mutation_state": "none", "next_actions": [{ "action": "renew_tier" }, { "action": "check_usage" }] }
```

```json
{ "status": "error", "http": 402, "message": "Payment required.", "code": "PAYMENT_REQUIRED", "category": "payment", "retryable": true, "safe_to_retry": true, "next_actions": [{ "action": "submit_payment" }] }
```

```json
{ "status": "error", "message": "Migration failed.", "code": "MIGRATION_FAILED", "category": "deploy", "retryable": false, "safe_to_retry": true, "mutation_state": "rolled_back", "trace_id": "trc_...", "details": { "operation_id": "op_...", "phase": "migrate" }, "next_actions": [{ "action": "edit_migration" }] }
```

---
## Step 1: Install

Requires Node.js >= 22.

```bash
npm install -g run402
```

## Step 2: Set Up Allowance and Funding

The fastest way -- does everything in one command:

```bash
run402 init
```

This will:
1. Create a local agent allowance (if none exists)
2. Check your USDC balance
3. Request free testnet USDC from the faucet (if balance is zero)
4. Show your tier status and projects

Or do it step by step:

```bash
run402 allowance create    # Generate a new allowance
run402 allowance fund      # Get free testnet USDC (Base Sepolia)
run402 allowance balance   # Check USDC balance (mainnet + testnet + billing)
```

The allowance is stored locally at `~/.config/run402/allowance.json` with 0600 permissions. The CLI handles all x402 payment signing automatically -- you never need to touch private keys or payment libraries.

## Step 3: Subscribe to a Tier

```bash
run402 tier set prototype    # $0.10/7d, free with testnet faucet (verifies allowance setup, no real money)
run402 tier set hobby        # $5 for 30 days (real money)
run402 tier set team         # $20 for 30 days (real money)
```

Tier is per billing account, not per project. One subscribe / renew / upgrade applies immediately to every project on the account, and `api_calls` / `storage_bytes` quotas are enforced against the pooled total across every project on the account. Multi-wallet accounts (via `run402 billing link-wallet`) share that same pool. Quota-denial error envelopes include `details.scope: "account" | "project"` -- `"account"` for the pooled path, `"project"` for the orphan fallback (project whose billing account row was purged but cascade has not yet run).

`run402 tier set` refetches `/tiers/v1/status` after the call and includes the refreshed account-pool snapshot as `status_after` in the JSON output so you can see the new pooled `api_calls` / `storage_bytes` totals in one step.

The server auto-detects the action based on your allowance state:
- No tier or expired -> subscribe
- Same tier, active -> renew (extends from current expiry)
- Higher tier -> upgrade (prorated refund to billing allowance)
- Lower tier, active -> downgrade (prorated refund if usage fits)

Check your tier status:

```bash
run402 tier status
```

`tier status` `pool_usage` sums `api_calls` and `storage_bytes` across every project on the billing account (across every linked wallet), not the requesting wallet's projects.

After subscribing, you can create unlimited projects, deploy unlimited sites, and fork apps -- all free with your allowance signature, subject to the account-pooled api_calls and storage_bytes caps for your tier. Only image generation ($0.03/image) has a per-call cost.

---
## Deploying Apps

### Unified Deploy (v1.34 → v2.0 unified apply, recommended)

The canonical deploy primitive. All bytes ride through CAS (no inline-body cap), supports both `replace` and `patch` semantics per resource, atomic multi-resource activation, and resumable recovery from partial failures. This is the path the SDK exposes as `r.project(id).apply(...)`.

⚠️ You still need the `anon_key` BEFORE writing your manifest -- provision first, then embed the real key in your HTML.

```bash
run402 projects provision --name "my-app"
# → copy anon_key from output into your HTML
```

Manifest format mirrors a v2 `ReleaseSpec`. For editor autocomplete, use top-level `"$schema": "https://run402.com/schemas/release-spec.v1.json"`; the CLI accepts that metadata and strips it before planning.

```json
{
  "$schema": "https://run402.com/schemas/release-spec.v1.json",
  "project_id": "prj_1741340000_42",
  "database": {
    "migrations": [
      {
        "id": "001_init",
        "sql": "CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, title text NOT NULL); INSERT INTO items (title) VALUES ('Buy groceries');"
      }
    ],
    "expose": {
      "version": "1",
      "tables": [
        { "name": "items", "expose": true, "policy": "public_read_authenticated_write" }
      ]
    }
  },
  "secrets": { "require": ["OPENAI_API_KEY"], "delete": ["OLD_KEY"] },
  "functions": {
    "replace": {
      "api": {
        "runtime": "node22",
        "source": { "data": "export default async (req) => new Response('ok')" },
        "config": { "timeoutSeconds": 30, "memoryMb": 256 },
        "schedule": "*/15 * * * *"
      }
    }
  },
  "site": {
    "replace": {
      "index.html": { "data": "<!doctype html><html>...</html>" },
      "assets/logo.png": { "data": "iVBORw0KGgo...", "encoding": "base64" }
    }
  },
  "subdomains": { "set": ["my-app"] },
  "routes": {
    "replace": [
      { "pattern": "/api/*", "methods": ["GET", "POST"], "target": { "type": "function", "name": "api" } }
    ]
  },
  "i18n": {
    "defaultLocale": "en",
    "locales": ["en", "es", "fr"],
    "detect": ["cookie:wl_locale", "accept-language"]
  }
}
```

File entries accept a bare UTF-8 string, `{ "data": "...", "encoding": "utf-8" | "base64", "contentType": "..." }`, or `{ "path": "dist/index.html", "contentType": "text/html" }`. In `--manifest` files, relative paths resolve against the manifest file's directory; in `--spec` / stdin they resolve against the current working directory. Migration entries may use `"sql_path"` or `"sql_file"` instead of inline `"sql"`. The CLI and MCP adapters share the SDK's typed `normalizeDeployManifest` path, so the same JSON can become SDK-native `ReleaseSpec` code without reimplementing base64 or path handling. The adapter is strict: only top-level `$schema` metadata is ignored; unknown fields and no-op specs are rejected before deploy planning, so typos like `"subdomain"`, `"site.replcae"`, `"functions.replace.api.deps"`, or `"functions.replace.api.config.schedule"` do not become partial deploys.

Function specs in unified deploy accept `runtime` (`"node22"`), exactly one code source (`source` for a single module, or `files` plus `entrypoint` for multi-file functions), `config.timeoutSeconds`, `config.memoryMb`, and `schedule` as a sibling of `config`. In patch mode, omit `schedule` to leave it unchanged and use `"schedule": null` to remove an existing schedule. Unified deploy manifests do not accept `deps` yet; bundle dependencies into the function files or use `run402 functions deploy --deps` for the standalone function path.

Deploy preflights obvious tier function caps after manifest normalization but before CAS upload or `/apply/v1/plans`: timeout, memory, cron interval, and scheduled-function count. Structured local failures use `code: "BAD_FIELD"` with `details.field`, `details.value`, `details.tier`, the relevant limit e.g. `tier_max` or `min_interval_minutes`, and `details.limit_source` (`tier_status` or `local_static_fallback`). Current authoring caps: prototype 10s / 128 MB / 1 scheduled fn / 15 min, hobby 30s / 256 MB / 3 / 5 min, team 60s / 512 MB / 10 / 1 min. `run402 tier status` shows live function caps and current scheduled usage when the gateway returns them.

Subdomain specs use one mode per deploy: `"set"` replaces the release's managed subdomain list, `"add"` appends without removing existing entries, and `"remove"` deletes named entries. Current gateway support allows at most one subdomain in `subdomains.set` for a project; multi-subdomain `set` fails locally with `SUBDOMAIN_MULTI_NOT_SUPPORTED`.

Complete static site + function + route manifest:

```json
{
  "project_id": "prj_...",
  "site": { "replace": {
    "index.html": { "data": "<!doctype html><main id='app'></main><script>fetch('/api/hello')</script>" },
    "events.html": { "data": "<!doctype html><h1>Events</h1>" }
  }, "public_paths": {
    "mode": "explicit",
    "replace": {
      "/events": { "asset": "events.html", "cache_class": "html" }
    }
  } },
  "functions": {
    "replace": {
      "api": {
        "runtime": "node22",
        "source": { "data": "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }" }
      },
      "login": {
        "runtime": "node22",
        "source": { "data": "export default async function handler(req) { return Response.json({ ok: true }); }" }
      }
    }
  },
  "routes": { "replace": [
    { "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } },
    { "pattern": "/login", "methods": ["POST"], "target": { "type": "function", "name": "login" } }
  ] }
}
```

Static public paths:
- Release static asset paths and public browser paths are distinct. In the example, `events.html` is the release asset and `/events` is the browser-visible static URL declared through `site.public_paths`.
- `site.public_paths.mode: "explicit"` means only the complete `public_paths.replace` table is directly reachable as static URLs. `/events.html` is not public unless separately declared.
- `site.public_paths.mode: "implicit"` restores filename-derived public reachability and can widen access. Review gateway warnings before confirming a deploy that switches to implicit mode.
- Known `cache_class` inputs are `"html"`, `"immutable_versioned"`, and `"revalidating_asset"`. Preserve unknown future cache-class strings returned by release inventory, diff, or diagnostics instead of branching as if the list is closed.
- A site spec containing only `public_paths` is meaningful deploy content: `{ "site": { "public_paths": { "mode": "explicit", "replace": {} } } }` removes direct public static URLs without changing release assets.

Route semantics:
- Omit `routes` or pass `routes: null` to carry forward base routes. `routes: { "replace": [] }` clears dynamic routes. `routes: { "replace": [...] }` replaces the route table atomically with the release.
- Route entries use `pattern`, optional non-empty `methods` (`GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`), and a target. Function targets are `{ "type": "function", "name": "<materialized function name>" }`. Prefer `site.public_paths` for ordinary clean static URLs e.g. `/events -> events.html`. Static route targets are exact, method-aware route-table aliases e.g. `{ "pattern": "/events", "methods": ["GET", "HEAD"], "target": { "type": "static", "file": "events.html" } }`; the `file` is a release static asset path, not a public path, URL, CAS hash, rewrite, or redirect. Static targets require exact patterns only and methods `["GET"]` or `["GET","HEAD"]`; the file path is relative to deployed site content with no leading slash, wildcard, directory shorthand, query, or fragment. Path-keyed maps like `"routes": { "/api/*": { "function": "api" } }` are invalid.
- Exact patterns look like `/admin`; prefix wildcard patterns use final `/*`, like `/admin/*`. `/admin/*` does not match `/admin`, `/admin/`, `/admin.css`, or `/administrator`, so deploy both `/admin` and `/admin/*` for a dynamic section root.
- Query strings are ignored for matching and preserved in the handler's full public `req.url`. Exact beats prefix, longest prefix wins, and method-compatible dynamic routes beat static assets.
- A `POST /login` route can coexist with static `GET /login` HTML. Unsafe method mismatch returns `405`, not SPA HTML. Matched dynamic route failures fail closed and do not fall back to static files.
- Routed browser ingress uses Node 22 Fetch Request -> Response: `export default async function handler(req) { ... }`. `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains, so derive OAuth callbacks from `new URL(req.url).origin`. The raw `run402.routed_http.v1` envelope is internal; do not write route handlers against it. Direct `/functions/v1/:name` remains API-key protected. The function owns app auth, CSRF, CORS/`OPTIONS`, cookies, redirects, and spoofed forwarding-header hygiene.
- Anti-patterns: routing every static file, broad method lists by default, wildcard static route targets, leading-slash static files, directory shorthand, one-static-route-target-per-page route-table exhaustion, wildcard function routes shadowing direct public static paths, and confusing omitted/null `routes` with `routes: { "replace": [] }`.

Apply it:

```bash
run402 deploy apply --manifest app.json
```

Stdout returns `{ status: "ok", release_id, operation_id, urls, ... }`. Stderr streams structured progress events as JSON-line (one event per line). Pass `--quiet` or `--final-only` to silence stderr while preserving the final stdout JSON envelope.

Patch semantics — only the listed file changes:

```json
{
  "project_id": "prj_...",
  "site": { "patch": { "put": { "index.html": { "data": "<h1>v2</h1>" } } } }
}
```

Or via `--spec` for a one-line CLI invocation:

```bash
run402 deploy apply --spec '{"project_id":"prj_...","site":{"patch":{"delete":["old.html"]}}}'
```

Astro builds: pass `--dir <build-output>` to read `dist/run402/adapter.json` and merge the multi-slice ReleaseSpec (site + functions + routes) from the build product. Combine with `--manifest` to declare cross-cutting slices (database, secrets, subdomains, i18n) in the manifest while the slice carries the build output:

```bash
# Astro-only: --dir is the whole spec source (requires @run402/astro installed)
run402 deploy apply --dir ./dist --project prj_...

# Astro + cross-cutting slices: --dir owns site/functions/routes, --manifest owns the rest
run402 deploy apply --dir ./dist --manifest run402.config.json --project prj_...
```

The CLI dynamically imports `@run402/astro/release-slice` (must be installed in the consuming project, **`@run402/astro >=1.2.1` + `@run402/sdk >=2.18.0`** — older SDKs reject `FunctionSpec.class: 'ssr'` locally in `validateKnownFields` before the spec ever reaches the gateway; the helper preflights this and emits `R402_ASTRO_SDK_VERSION_TOO_OLD` with a precise upgrade command). The helper bundles the SSR server output with esbuild into a single `source` (the gateway rejects multi-file function specs), roots the site at the resolved `build.client` dir (`dist/run402/client/`, NOT `dist/`), **omits `routes` entirely from the returned slice** (the gateway routes every unmatched path to the project's `class: 'ssr'` function automatically, so no route table is needed; omitting `routes` — rather than sending an empty `replace` that would CLEAR the table — carries forward any base-release routes such as a separately-declared `/api/*` function and keeps the slice safe to submit from a CI OIDC session without route scopes), defaults `site.public_paths: { mode: "implicit" }` to opt out of inherited explicit-mode paths from the base release, and colocates the `_assets-manifest.json` inside the resolved `build.client` dir (so the slice's site replace dir carries it). On a missing/incompatible manifest the error envelope carries `code: "R402_ASTRO_ADAPTER_MANIFEST_MISSING"` or `R402_ASTRO_ADAPTER_MANIFEST_VERSION_UNSUPPORTED` with `hint` + `docs` fields pointing at run402.com/errors. Direct-SDK callers get the same primitive via `import { buildAstroReleaseSlice } from "@run402/astro/release-slice"`. Do NOT hand-roll `site` / `public_paths`: if a deploy ships the adapter build tree (`run402/adapter.json`, `run402/server/**`) as site content — the symptom of rooting a file source at `dist/` instead of `dist/run402/client/` — the SDK rejects it locally with `ASTRO_ADAPTER_TREE_IN_SITE` before any upload, and the gateway warns `SITE_NO_REACHABLE_HTML` when a release ships HTML that isn't reachable at any public path (kychee-com/run402#411).

Recovery from a stuck deploy: when an `apply` ends in `activation_pending` (rare; transient gateway failure between SQL commit and the pointer-swap activation), the gateway auto-resumes on the hourly tick. Static spec/config activation failures are classified promptly and thrown as structured deploy errors instead of polling until timeout. For genuinely resumable operations, call resume explicitly:

```bash
run402 deploy resume <operation_id>
```

The gateway re-runs only the failed phase forward — SQL is never replayed.

Recovery from a destructive apply (v1.58+): when an `apply` shipped content the operator regrets (accidental destructive prune, content overwrite, broken release), `run402 deploy promote <release-id>` re-points the project's live release at a prior release row WITHOUT re-running the apply pipeline. No bytes-upload, no bundling, no migration — just a pointer swap on `internal.projects.live_release_id` plus an ssr_cache flush. Designed for "oops on a real project ID" recovery in seconds rather than re-deploying.

```bash
# rel_old (good)  →  rel_new (bad, destructive)  →  promote back
run402 deploy promote rel_old_abc123 --project prj_xyz \
  --allow-warning MIGRATIONS_NOT_REVERSIBLE
```

Surfaces structured warnings. `MIGRATIONS_NOT_REVERSIBLE` (requires_confirmation: true) fires when the target release predates migrations applied since — the migrations remain applied, so the post-promote release runs against the current schema. Ack with `--allow-warning MIGRATIONS_NOT_REVERSIBLE`. `FUNCTION_VERSION_MISMATCH` (informational) fires when overlapping function names have different code_hashes; the Lambda code is whatever's currently `$LATEST`. Rejected codes: `PROMOTE_TARGET_NOT_FOUND` (release id doesn't exist), `PROMOTE_PROJECT_MISMATCH` (release belongs to another project), `PROMOTE_RELEASE_NOT_READY` (release status not promotable: must be `ready`, `active`, or `superseded`), `PROMOTE_NO_OP` (target IS already the current live; use `cache.invalidateAll` to refresh cache instead), `PROMOTE_WARNING_REQUIRES_ACK` (at least one blocking warning unacked).

Inspect deploy history: list recent operations for a project, or pull the recorded phase-event stream for a specific operation (after the fact — for live progress events during an in-flight deploy, the `apply` command already streams them on stderr):

```bash
run402 deploy list --project prj_... --limit 10
run402 deploy events <operation_id> --project prj_...
run402 deploy release active --project prj_... --site-limit 5000
run402 deploy release get rel_... --project prj_...
run402 deploy release diff --from empty --to active --project prj_... --limit 1000
run402 deploy diagnose --project prj_123 https://example.com/events --method GET
run402 deploy resolve --project prj_123 --url https://example.com/events?utm=x#hero --method GET
run402 deploy resolve --project prj_123 --host example.com --path /events --method GET
```

`list` returns `{ operations: [...], cursor }`; the SDK and MCP `deploy_list` surface accept that cursor for pagination when it is non-null. `events` returns the same `DeployEvent` shapes that `apply` emits inline.

`release active` and `release get` return `{ "release": ReleaseInventory }`. Inventories include release metadata, `state_kind` (`current_live`, `effective`, or `desired_manifest`), site paths (capped by `--site-limit`), `static_public_paths` when returned, functions, secret keys only, subdomains, materialized routes, applied migrations, `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata`, the release's `i18n` slice (object with `defaultLocale` / `locales` / `detect`, or `null` when the release has no slice), and inventory warnings when returned. `site.paths` is the release static asset inventory; `static_public_paths[]` is the browser reachability inventory with `public_path`, `asset_path`, `reachability_authority`, `direct`, cache class, and content type. `static_manifest_metadata: null` means unavailable, not zero; when present it includes `file_count`, `total_bytes`, `cache_classes`, `cache_class_sources`, and `spa_fallback`. Use `i18n` as the positive verification readback after a deploy — `jq '.release.i18n'` confirms `spec.i18n` shipped, since `apply()` not throwing is necessary but not sufficient. Older gateways predating the inventory-i18n change may omit the field entirely; treat absent (not `null`) as "unknown on this gateway."

`release diff` returns `{ "diff": ReleaseToReleaseDiff }`. `--from` accepts `empty`, `active`, or a release id. `--to` accepts `active` or a release id. Diff migrations use `migrations.applied_between_releases`; secrets and subdomains expose `added` / `removed` only; routes expose `added` / `removed` / `changed`; `static_assets` exposes unchanged/changed/added/removed files, `newly_uploaded_cas_bytes`, `reused_cas_bytes`, `deployment_copy_bytes_eliminated`, `legacy_immutable_warnings`, `previous_immutable_failures`, and `cas_authorization_failures`.

`deploy diagnose` is the URL-first public diagnostic: `run402 deploy diagnose --project prj_123 https://example.com/events --method GET`. `deploy resolve` is lower-level parity with the SDK/endpoint: pass `--url` or pass `--host` with optional `--path`; do not combine `--url` with `--host`/`--path`. Both commands print a structured JSON envelope with `status`, `would_serve`, `diagnostic_status`, `match`, `summary`, normalized `request`, `warnings`, full `resolution`, and structured `next_steps`. Query strings/fragments in URL mode are ignored for route/static lookup and reported under `request.ignored` and warnings. When returned, `asset_path`, `reachability_authority`, and `direct` explain which release asset backs the public URL and whether reachability came from implicit file-path mode, explicit `site.public_paths`, or a route-only static alias. Diagnostic misses e.g. host misses exit 0 when the resolver call succeeds; branch on `would_serve: false`.

Stable-host diagnostics may include `authorization_result`, `cas_object` (`sha256`, `exists`, `expected_size`, `actual_size`), hostname-specific `response_variant`, and route/static fields e.g. `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Known current resolve `match` literals are `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; preserve unknown future strings. Known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. `result` is diagnostic body status, not HTTP transport status. Do not treat resolve/diagnose as a fetch, cache purge, or cache-policy oracle; branch on structured JSON e.g. `cache_class`, `allow`, and `cas_object`, and preserve unknown cache classes.

Route warning guidance:

| Code | Meaning | Recover |
|---|---|---|
| `PUBLIC_ROUTED_FUNCTION` | Function becomes public same-origin browser ingress. | Review app auth, CSRF, CORS/`OPTIONS`, and cookies; direct `/functions/v1/:name` remains API-key protected. Prefer `--allow-warning PUBLIC_ROUTED_FUNCTION` after review; use `--allow-warnings` only after every warning was reviewed. |
| `ROUTE_TARGET_CARRIED_FORWARD` | Carried-forward route still targets a base-release function. | Inspect `run402 deploy release active` and deploy a replacement route table if needed. |
| `ROUTE_SHADOWS_STATIC_PATH` / `WILDCARD_ROUTE_SHADOWS_STATIC_PATHS` | Dynamic route shadows direct public static content. | Inspect warning details, active routes, `static_public_paths`, and resolve diagnostics; confirm only when intentional. |
| `METHOD_SPECIFIC_ROUTE_ALLOWS_GET_STATIC_FALLBACK` | Unmatched methods can serve static content. | Confirm fallback is intended or add method coverage. |
| `WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS` | Wildcard function route only allows `GET`/`HEAD`. | Add mutation methods e.g. `POST`, omit methods for an API prefix, or set `acknowledge_readonly: true` on an intentionally read-only GET/HEAD final-wildcard function route. `--allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS` is a reviewed CLI escape hatch; broad `--allow-warnings` is last resort. |
| `ROUTE_TABLE_NEAR_LIMIT` | Route table is near a limit. | Consolidate or remove routes. |
| `ROUTES_NOT_ENABLED` | Routes are disabled for the project/environment. | Deploy without `routes` or request enablement; direct function invoke is not a browser-route substitute. |
| `STATIC_ALIAS_SHADOWS_STATIC_PATH` / `STATIC_ALIAS_RELATIVE_ASSET_RISK` | Route-only static alias conflicts with a direct public static path or has relative-asset risk. | Inspect active routes, `static_public_paths`, and the backing `asset_path`; prefer `site.public_paths` for ordinary clean URLs and confirm only when intentional. |
| `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` / `STATIC_ALIAS_EXTENSIONLESS_NON_HTML` | Route-only static alias may duplicate another direct public path or expose extensionless non-HTML. | Use one canonical public path per page and reserve exact static route targets for method-aware aliases. |
| `STATIC_ALIAS_TABLE_NEAR_LIMIT` | Static route targets are near route-table limits. | Avoid one-static-route-target-per-page tables; consolidate. |

Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED` (manifest/propagation), `ROUTED_INVOKE_WORKER_SECRET_MISSING` (custom-domain Worker secret), `ROUTED_INVOKE_AUTH_FAILED` (internal invoke signature), `ROUTED_ROUTE_STALE` (selected route failed release revalidation), `ROUTE_METHOD_NOT_ALLOWED` (method mismatch), and `ROUTED_RESPONSE_TOO_LARGE` (body over 6 MiB).

**Routed functions: locale awareness.** Declare supported locales with a `spec.i18n` release slice and the gateway negotiates a locale per routed-function request, surfacing the result to user code via `x-run402-locale` and `x-run402-default-locale` request headers (omitted entirely when the active release has no `i18n` slice — additive-compat for pre-i18n functions). The slice has its own carry-forward rules — simpler than `routes`, no `{ replace }` envelope:

```json
{
  "i18n": {
    "defaultLocale": "en",
    "locales": ["en", "es", "fr", "zh-Hant"],
    "detect": ["cookie:wl_locale", "accept-language"]
  }
}
```

- Omit `i18n` to carry forward from the base release; pass `"i18n": null` to clear the slice on the new release; pass `{ defaultLocale, locales, detect? }` to replace.
- `defaultLocale` MUST be byte-identical to one entry in `locales[]`. The platform does NOT silently canonicalize; the CLI/SDK validate this client-side before planning.
- Locale tags MUST match `/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/` AND be in RFC 5646 canonical casing: primary subtag lowercase, script subtag Titlecase, 2-alpha region UPPERCASE, 3-digit (UN M.49) region preserved, variants/extensions lowercase. Examples: `pt-BR`, `zh-Hant`, `zh-Hant-TW`, `de-1996`. The gateway rejects non-canonical casing at deploy time with `code: "R402_LOCALE_NOT_CANONICAL"` (HTTP 400) carrying `fix: { input, canonical }` so agents can auto-correct and retry. The platform does NOT silently canonicalize because translations are typically keyed on the literal locale string in your DB (e.g. `section_translations.language = 'pt-BR'`); auto-canonicalization would create a silent split between the spec and your column values. `locales[]` is non-empty, max 50 entries.
- Negotiation returns canonical casing from `locales[]`, NOT the request's casing.
- `detect[]` (default `["accept-language"]`, max 10, `[]` allowed and means "always default") is walked in order; first match wins. Sources: `"accept-language"` (RFC 9110 parsing, RFC 4647 §3.4 lookup-style truncation `zh-Hant-TW` → `zh-Hant` → `zh`; a generic request tag does NOT match a more specific `locales[]` entry — `Accept-Language: es` does NOT match `locales: ["es-MX"]`) and `"cookie:<name>"` (RFC 6265 cookie-name grammar `/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/`, raw value matched case-insensitively against `locales[]`).
- Static-route hits do NOT receive locale negotiation; only routed HTTP function invocations do.
- Run402 does NOT inject `Vary` headers — apps that return public-cacheable responses varying by locale must set their own `Vary` until per-locale edge caching ships.

Routed-function read pattern (single-arg `(req)` signature, not `(req, ctx)` — the bundled `@run402/functions` runtime translates the routed envelope into a Web-standard `Request` before calling user code, so the envelope's `context.locale` is NOT visible to typical user functions):

```ts
export default async (req) => {
  const locale = req.headers.get('x-run402-locale');
  const defaultLocale = req.headers.get('x-run402-default-locale');
  if (locale && locale !== defaultLocale) {
    return renderWithTranslations({ locale });
  }
  return renderBase({ locale: defaultLocale ?? 'en' });
};
```

Client-side gotcha — language switchers must write a cookie. Apps that persist locale to `localStorage` only (a common pattern from Astro/Next i18n tutorials) won't be seen by Run402's server-side negotiation. Mirror the locale to a cookie so the next request hits the right translations, then declare a cookie source in `spec.i18n.detect`:

```js
function setLanguage(lang) {
  localStorage.setItem('wl_locale', lang);
  document.cookie =
    `wl_locale=${encodeURIComponent(lang)}; path=/; max-age=31536000; samesite=lax`;
}
```

Then deploy with `"detect": ["cookie:wl_locale", "accept-language"]` so the server honors the user's choice on the next request.

Migration registry: each migration is identified by `(id, checksum)`. Re-shipping the same `id` + same SQL is a registry noop; same `id` + different SQL is a hard error (`MIGRATION_CHECKSUM_MISMATCH`). Ship idempotent migrations (`CREATE TABLE IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS` in a `DO` block) and re-deploys are free.

---
### GitHub Actions OIDC Deploys

Use this when the same repo should deploy itself from GitHub Actions without storing Run402 service keys, allowance files, or API keys in GitHub secrets. KISS rule: link once locally, then CI runs the same `run402 deploy apply` command agents already know.

Local setup:

```bash
run402 ci link github --project prj_... --manifest run402.deploy.json
run402 ci link github --project prj_... --manifest run402.deploy.json --route-scope /admin --route-scope /api/*
```

Full link syntax:

```bash
run402 ci link github \
  [--project <id>] \
  [--manifest <path>] \
  [--repo <owner/repo>] \
  [--branch <name> | --environment <name>] \
  [--repository-id <numeric_id>] \
  [--workflow <path>] \
  [--expires-at <iso_timestamp>] \
  [--route-scope <pattern> ...] \
  [--force]
```

Defaults:
- `--project`: active project
- `--manifest`: `run402.deploy.json`
- `--repo`: inferred from `git remote get-url origin`
- `--branch`: current branch from `git branch --show-current`
- `--workflow`: `.github/workflows/run402-deploy.yml`
- `--route-scope`: omitted by default, which means no CI route-declaration authority; repeat for exact paths like `/admin` or final wildcard prefixes like `/api/*`
- allowed events: fixed to `push` and `workflow_dispatch`
- allowed action: fixed to `deploy`

The command fetches GitHub's numeric repository id using `GITHUB_TOKEN` or `GH_TOKEN` when available. If lookup fails, pass `--repository-id <numeric_id>` explicitly. The subject is generated from `--branch` as `repo:<owner/repo>:ref:refs/heads/<branch>`, or from `--environment` as `repo:<owner/repo>:environment:<environment>`.

Generated workflow shape:

```yaml
name: Run402 Deploy

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to run402
        run: npx --yes run402@1.60.0 deploy apply --manifest 'run402.deploy.json' --project 'prj_...' < /dev/null
```

Output on success:

```json
{
  "binding_id": "cib_...",
  "project_id": "prj_...",
  "provider": "github-actions",
  "subject_match": "repo:owner/name:ref:refs/heads/main",
  "allowed_events": ["push", "workflow_dispatch"],
  "allowed_actions": ["deploy"],
  "route_scopes": ["/admin", "/api/*"],
  "github_repository_id": "123456789",
  "github_repository_id_status": "verified",
  "workflow_path": ".github/workflows/run402-deploy.yml",
  "manifest_path": "run402.deploy.json",
  "run402_version": "1.60.0",
  "delegation_chain_id": "eip155:84532",
  "bootstrap_caveat": "Commit the generated workflow and manifest before expecting GitHub Actions deploys.",
  "consent_summary": ["..."],
  "revocation_residuals": ["..."]
}
```

Management:

```bash
run402 ci list [--project <id>]
run402 ci revoke <binding_id>
```

`list` prints `{ "project_id": "...", "bindings": [...] }`.
`revoke` prints `{ "binding": {...}, "revoked": true, "revocation_residuals": [...] }`.

Intentional omissions in v1: no raw `--subject`, no wildcard flag, no `--allow-event`, no PR deploy flags, and no `--no-repository-id`. Use `--branch` or `--environment`; create a follow-up design before broadening trust.

CI deploy restrictions: when `run402 deploy apply` runs inside GitHub Actions with OIDC env vars present, it uses the GitHub subject token, exchanges it for a Run402 CI session, and skips the local allowance preflight. CI manifests may include only `project_id`, `database`, `functions`, `site`, absent/current `base`, and route declarations covered by the binding's `route_scopes`. Without `--route-scope`, CI cannot ship `routes`. CI cannot ship `secrets`, `subdomains`, `checks`, unknown future top-level fields, non-current base, or oversized manifests that require `manifest_ref`.

Common CI error codes:
- `invalid_token`: check `permissions: id-token: write` and the workflow's OIDC environment
- `access_denied`: no active binding matched this repo/branch/environment
- `event_not_allowed`: v1 allows only `push` and `workflow_dispatch`
- `repository_id_mismatch`: re-link from the current repo or pass the correct numeric `--repository-id`
- `forbidden_spec_field` / `forbidden_plan`: remove disallowed CI manifest fields or run the deploy locally
- `CI_ROUTE_SCOPE_DENIED`: re-link with covering `--route-scope` patterns e.g. `/admin` or `/api/*`, or run the route-changing deploy locally
- `payment_required`: renew/upgrade/fund the project tier outside CI, then rerun the workflow

---
### Unified Deploy

Use `run402 deploy apply --manifest app.json` for full-stack releases. The manifest is a v2 `ReleaseSpec` with explicit replace-vs-patch semantics per resource. Add top-level `"$schema": "https://run402.com/schemas/release-spec.v1.json"` for editor autocomplete; the CLI strips it before planning.

⚠️ You need the anon_key BEFORE writing your manifest.
Run provision first, then write your HTML with the real key:

```bash
run402 projects provision --name "my-app"
```

→ copy anon_key from output into your HTML, then:

Create a manifest file `app.json` (use the `project_id` from provision):

```json
{
  "$schema": "https://run402.com/schemas/release-spec.v1.json",
  "project_id": "prj_1741340000_42",
  "database": {
    "migrations": [
      {
        "id": "001_init",
        "sql": "CREATE TABLE items (id serial PRIMARY KEY, title text NOT NULL, done boolean DEFAULT false);"
      }
    ],
    "expose": {
      "$schema": "https://run402.com/schemas/manifest.v1.json",
      "version": "1",
      "tables": [
        { "name": "items", "expose": true, "policy": "public_read_authenticated_write" }
      ]
    }
  },
  "functions": {
    "replace": {
      "my-fn": {
        "runtime": "node22",
        "source": { "data": "export default async (req) => new Response('ok')" },
        "config": { "timeoutSeconds": 30, "memoryMb": 256 },
        "schedule": "*/15 * * * *"
      }
    }
  },
  "site": {
    "replace": {
      "index.html": { "data": "<!DOCTYPE html><html>...</html>" },
      "style.css": { "data": "body { margin: 0; }" },
      "logo.png": { "data": "iVBORw0KGgo...", "encoding": "base64" }
    }
  },
  "subdomains": { "set": ["my-app"] }
}
```

`project_id` is required (from `run402 projects provision`). All other fields are optional; omitted top-level sections are carried forward from the current release. The adapter is strict: only top-level `$schema` metadata is ignored; typo fields e.g. `subdomain`, `site.replcae`, `functions.replace.my-fn.deps`, or `functions.replace.my-fn.config.schedule` fail before planning.

Function specs accept `runtime: "node22"`, exactly one code source (`source`, or `files` plus `entrypoint`), `config.timeoutSeconds`, `config.memoryMb`, a sibling `schedule`, and the v1.51+ auth-gate fields `requireAuth` / `requireRole` (see "Function-level auth gates" below). Omit `schedule` in patch mode to leave it unchanged; set it to `null` to remove the schedule. Unified deploy manifests do not accept `deps`; bundle dependencies into the function files or use `run402 functions deploy --deps`.

Function-level auth gates (v1.51+). Two optional declarative fields on each function spec:

- `requireAuth: true` — gateway rejects callers without a valid project user JWT with `401`. No DB lookup. Independent from `requireRole`.
- `requireRole: { table, idColumn, roleColumn, allowed[], cacheTtl? } | null` — gateway resolves the caller's role from the project-schema table (RLS-bypass) and rejects callers whose role is not in `allowed` with `403`. Implies authentication (no JWT → 401). Pass `null` in patch mode to remove an existing gate. `cacheTtl` is seconds; default 60, max 600, 0 disables caching (use for instant-revocation paths).

When a gate passes, the gateway injects `x-run402-user-id` (always when any gate ran) and `x-run402-user-role` (only when `requireRole` ran) into the request. In-function code reads them with `getUserId(req)` / `getRole(req)` from `@run402/functions` 2.5+.

Worked example — manifest fragment:

```json
{
  "functions": {
    "patch": {
      "set": {
        "list-my-items": {
          "source": { "path": "functions/list.ts" },
          "requireAuth": true
        },
        "delete-content": {
          "source": { "path": "functions/delete.ts" },
          "requireRole": {
            "table": "members",
            "idColumn": "user_id",
            "roleColumn": "role",
            "allowed": ["admin"],
            "cacheTtl": 60
          }
        },
        "moderate-content": {
          "source": { "path": "functions/moderate.ts" },
          "requireRole": {
            "table": "members",
            "idColumn": "user_id",
            "roleColumn": "role",
            "allowed": ["admin", "moderator"]
          }
        }
      }
    }
  }
}
```

Validation rules:

- One role table per release. All `requireRole` blocks in a single release must share the same `(table, idColumn, roleColumn)` triple. Different `allowed` sets are fine; different tables are rejected at plan time with the canonical `INVALID_SPEC` envelope.
- Unqualified identifiers only. Schema-qualified names (e.g. `"public.members"`) are rejected with `INVALID_SPEC`. The project schema is resolved server-side.
- `cacheTtl` range. `0 ≤ cacheTtl ≤ 600`; out-of-range rejected with `INVALID_SPEC`.
- Empty `allowed`. Rejected with `INVALID_SPEC` — set the role values explicitly.
- Deploy-time validation. Missing table or column at activation fails with `DEPLOY_INVALID_ROLE_GATE` (HTTP 422) *before* flipping the live release. `run402 deploy apply` surfaces the structured envelope on stderr.

Reading the role in-function — TWO approaches (`@run402/functions` 3.4.0+; `{ from }` since 3.5.0). The edge gate now authenticates BOTH `Authorization: Bearer` callers and cookie-session SSR browsers (capability `ssr-aware-role-gate`), so pick by your function TOPOLOGY, not by how the caller authenticates.

1. Dedicated function / route → the deploy-spec `requireRole` EDGE gate (above). It authenticates Bearer JWT AND the browser cookie session, enforces before dispatch, and caches the role lookup (TTL). In-function, `await auth.requireRole("operator")` returns `{ user, role }` (throwing a *distinct* `RoleGateNotConfiguredError` (500) if no gate is declared vs `InsufficientRoleError` (403) for a mismatch); for multi-role gates read `await auth.role()` and branch — `requireRole(x)` requires `x` in `allowed`. For a browser console, add `onDeny: "redirect"` + `signInPath` (a same-origin path) to the gate so an unauthenticated HTML request gets a `303` to sign-in (401-class only — an authenticated wrong-role 403 stays a JSON envelope, no redirect loop). The gate is PER-FUNCTION.

2. Catch-all SSR function, or finer per-path control → the in-function `{ from }` guard. Because the edge gate is per-function, a single catch-all function (one ssr function = `/admin/*` console AND the public 404 fallback) can't gate just `/admin/*` — an edge gate would also gate the public 404s and the public `/admin/login`. Use `{ from }`: it resolves the cookie user (`auth.user()`) and reads their role from your tenant table (RLS-bypass), scoped in-app to your admin pages, no gate required:

```ts
const { user } = await auth.requireRole("operator", { from: { table: "staff", idColumn: "user_id", roleColumn: "role" } });
// or, for an .astro page (a throw in frontmatter renders a 500, not a redirect) use the non-throwing read:
const role = await auth.role({ from: { table: "staff", idColumn: "user_id", roleColumn: "role" } });
if (role !== "operator") return Astro.redirect("/admin/login", 303);
```

Worked example — an Astro SSR hybrid where ONE ssr function serves `/admin/*` AND the public catch-all/404 fallback: use the in-function `{ from }` guard (an edge gate, being per-function, would also gate the public 404s + `/admin/login`). If your console is instead a DEDICATED function/route, prefer the edge gate — it's cookie-aware, supports `onDeny: "redirect"` to sign-in, and caches the role lookup.

Scaffolding + first-operator bootstrap. `run402 auth scaffold-roles --roles operator` emits the conventional `app_roles(user_id uuid, role text)` migration, the matching `requireRole` snippet, and a service-role `INSERT` to grant the FIRST role — the table starts empty, so the first grant must bypass RLS with the service key. The gate keys on the tenant user id (`internal.users.id` / JWT `sub`), NOT a wallet. The conventional table is a default — `requireRole` accepts any `(table, idColumn, roleColumn)`.

The gate applies to both routed (`/your/route`) and direct (`POST /functions/v1/:name` with API key plus user JWT) invocation. Direct invocation still requires the API key at the edge; the gate runs after API-key auth, against the user JWT.

Binary files (images, fonts, PDFs): Set `"encoding": "base64"` and provide base64-encoded data. MIME types are auto-detected from the file extension (`.png` → `image/png`, `.woff2` → `font/woff2`, etc.). Text files use `"encoding": "utf-8"` (the default — can be omitted).

Assets slice (v2.0+, bulk content-addressed storage in the apply transaction). `assets` is a top-level `ReleaseSpec` slice — the same atomic transaction promotes site bytes, function code, secrets, *and* asset entries. Two shapes:

```json
"assets": {
  "put": [
    { "key": "static/app.css", "sha256": "<64-hex>", "size_bytes": 1234, "content_type": "text/css", "visibility": "public", "immutable": true }
  ]
}
```

Additive batch. Each entry carries the locally-computed `sha256` so the gateway can deduplicate against the CAS substrate — only new shas trigger an upload via the same direct-to-S3 presigned URL flow as `run402 assets put`. Defaults: `visibility: "public"`, `immutable: true`. Existing keys outside the batch are left untouched.

```json
"assets": {
  "put": [...],
  "sync": {
    "prefix": "static/",
    "prune": true,
    "confirm": { "base_revision": "<hex>", "delete_set_digest": "<hex>", "expected_delete_count": 42 }
  }
}
```

Declarative sync. `prune: true` deletes keys under `prefix` that aren't in the new `put` batch. Requires an explicit `prefix` — no implicit project-root prune. First apply without `confirm` returns the `asset_sync` block in the plan response (`base_revision`, `delete_set_digest`, `expected_delete_count`, `sample_keys`); surface those to the user, then re-run with `confirm` populated. Gateway activation re-checks via `ASSET_SYNC_DRIFT` if inventory mutates between commit and activation.

Why this exists: the SDK's Node helpers (`r.assets.uploadDir(path, { project })`, `syncDir`, `prepareDir`, `putMany`) walk a local directory, compute SHA-256s in streaming chunks, and submit through this same apply slice. The CLI doesn't ship a `run402 assets sync` subcommand — write the manifest and use `deploy apply`, or call the Node SDK directly from a script.

Migrations can be inline (`sql`) or read from a file with `sql_path` / `sql_file` on each migration entry.

Make migrations idempotent: Use `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`. If you redeploy to the same project, non-idempotent migrations will fail with a 422 error (e.g., `relation "items" already exists`).

Evolving your schema: `CREATE TABLE IF NOT EXISTS` only prevents "table already exists" errors — it will not add new columns to an existing table. When your app needs new columns, use `ALTER TABLE ... ADD COLUMN` wrapped in a DO block to make it idempotent:

```sql
CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, title text NOT NULL);
DO $$ BEGIN
  ALTER TABLE items ADD COLUMN priority int DEFAULT 0;
EXCEPTION WHEN duplicate_column THEN NULL;
END $$;
```

This pattern is safe to re-run on every deploy. Put your `CREATE TABLE IF NOT EXISTS` first, then one `DO` block per new column (or group them in a single block).

Authorization (the `manifest.json` file pattern)

Tables you create are dark by default — `anon` and `authenticated` can't read them until your manifest declares them with `expose: true`. Closes the "agent created a table, forgot to set RLS, data leaked" footgun.

JSON Schema: `https://run402.com/schemas/manifest.v1.json` — point your editor's `$schema` at it for autocomplete.

The preferred way to declare authorization is to ship a `manifest.json` file in the bundle's `files[]` (shown above). The platform reads it, validates it against the migration SQL, applies it, and strips it from `files[]` before the site deploys so it's never publicly reachable on your subdomain. The deploy response includes `manifest_applied: true` on success. If the manifest references a table your migration doesn't create, the deploy is rejected with HTTP 400 and a structured `errors` array listing every violation.

For a non-mutating feedback loop before applying, run `run402 projects validate-expose [project_id] --file manifest.json [--migration-file setup.sql]`. It validates the auth/expose manifest used by `manifest.json`, `database.expose`, and `apply-expose`; it is not deploy-manifest validation. Migration SQL is used only for reference checks and is not executed as a PostgreSQL dry run. The command prints `{ "hasErrors": boolean, "errors": [...], "warnings": [...] }` and exits 0 even when `hasErrors` is true — the validator ran, so the command succeeded; agents read `hasErrors` to decide what to do.

Built-in policies (one per table):

- `user_owns_rows` — owner column matches `auth.uid()`. Requires `owner_column`. With `force_owner_on_insert: true`, a per-table `BEFORE INSERT` trigger named `<table>_set_owner` calls `<table>_set_owner_fn()` and fills the owner only when `NEW.<owner_column>` is `NULL`: `IF NEW."<owner_column>" IS NULL THEN NEW."<owner_column>" := auth.uid(); END IF;`. It does not overwrite explicit non-null owners; ordinary authenticated inserts with a different explicit owner still fail the `WITH CHECK (owner_column = auth.uid())` policy. `service_key` / service-role writes bypass RLS, but the trigger still runs; if no JWT subject is present then `auth.uid()` is null, so admin writes should set the owner explicitly when needed. Best for user-scoped data (todos, workouts, messages). `uuid` owner columns get index-friendly policies; other types fall back to a `::text` cast with a warning; a btree index is auto-created.
- `public_read_authenticated_write` — anyone reads; any authenticated user can INSERT/UPDATE/DELETE any row (not just their own). For collaborative content (shared boards, announcements).
- `public_read_write_UNRESTRICTED` — ⚠ fully open; `anon_key` can read AND write any row. For intentionally public tables only (guestbooks, waitlists, feedback forms). Requires `"i_understand_this_is_unrestricted": true` on the table entry.
- `custom` — escape hatch. Provide `custom_sql` containing `CREATE POLICY` statements; they run inside the apply transaction after RLS is enabled + forced.

| Policy | anon SELECT | anon writes | auth SELECT | auth writes |
|---|:---:|:---:|:---:|:---:|
| (omitted from manifest) | — | — | — | — |
| `user_owns_rows` | — | — | own rows | own rows |
| `public_read_authenticated_write` | all | — | all | all rows |
| `public_read_write_UNRESTRICTED` | all | yes | all | yes |

`—` = denied. `service_key` bypasses all policies. Views are always created with `security_invoker=true` — they inherit the underlying table's RLS. RPCs require an entry in `rpcs[*]` with `grant_to` to be callable as `/rest/v1/rpc/<fn>` (since v1.30, `CREATE FUNCTION` revokes PUBLIC EXECUTE automatically).

Worked example covering all three slices (drop in as `manifest.json` or under `database.expose` in a deploy manifest):

```json
{
  "$schema": "https://run402.com/schemas/manifest.v1.json",
  "version": "1",
  "tables": [
    { "name": "posts", "expose": true, "policy": "public_read_authenticated_write" },
    { "name": "notes", "expose": true, "policy": "user_owns_rows", "owner_column": "user_id", "force_owner_on_insert": true }
  ],
  "views": [
    { "name": "posts_public", "base": "posts", "select": ["id", "title", "published_at"], "expose": true }
  ],
  "rpcs": [
    { "name": "increment_counter", "signature": "(counter_name text)", "grant_to": ["authenticated"] },
    { "name": "now_utc", "signature": "()", "grant_to": ["anon", "authenticated"] }
  ]
}
```

`rpcs[*].signature` is the parenthesized argument list — `"()"` for no-arg functions, `"(arg_name type, ...)"` otherwise. The schema regex is `^\([^;]*\)$` (no semicolons, parentheses required). `grant_to` is a non-empty array of Postgres roles — typically `anon`, `authenticated`, `service_role`, or `project_admin`. The function must already exist in your migration SQL with a matching signature; the manifest only grants EXECUTE. Views require `base` plus a non-empty `select`; they are always created `security_invoker=true` and inherit the base table's RLS.

**Imperative escape hatch:** for ad-hoc changes outside a deploy, use `run402 projects apply-expose <project_id> --file manifest.json`. Inspect current state with `run402 projects get-expose <project_id>` — `source: "applied"` means it came from a prior apply; `"introspected"` means it was reconstructed from live DB state.

The manifest is convergent: applying the same manifest twice is a no-op; items removed between applies have their policies revoked, grants revoked, triggers dropped, views dropped. Include everything you want exposed in every apply.

Deploy:

```bash
run402 deploy apply --manifest app.json
```

This deploys to an existing project: runs migrations, applies the authorization manifest from `database.expose`, deploys functions, deploys the site, and claims the subdomain. Secret values must be set before deploy with `run402 secrets set`; deploy manifests may only declare `secrets.require` / `secrets.delete`. Provision the project first with `run402 projects provision`.

### Step-by-Step Deploy

If you want more control:

```bash
# 1. Provision a database
run402 projects provision --name my-app

# 2. Create tables
run402 projects sql <project_id> "CREATE TABLE items (id serial PRIMARY KEY, title text NOT NULL, done boolean DEFAULT false)"

# 3. Insert seed data
run402 projects sql <project_id> "INSERT INTO items (title) VALUES ('Buy groceries'), ('Read a book')"

# 4. Declare authorization. Write manifest.json first:
#    {"version":"1","tables":[{"name":"items","expose":true,"policy":"public_read_authenticated_write"}]}
run402 projects validate-expose <project_id> --file manifest.json
run402 projects apply-expose    <project_id> --file manifest.json

# 5. Deploy a static site (uses active project automatically)
run402 sites deploy --manifest site.json

# 6. Claim a subdomain (uses active project + last deployment automatically)
run402 subdomains claim my-app
```

---
## Command Reference

### init
- `run402 init` — set up with x402 (Base Sepolia). Creates allowance, requests faucet, checks tier, lists projects.
- `run402 init mpp` — set up with MPP (Tempo Moderato testnet). Same steps, different payment rail.

### status
`run402 status` — show full account state in one shot (wallet, rail, balances, tier, projects, active project). Read-only, JSON output. Includes a `wallet: { local_label, server_label, address }` object naming the active named wallet (`local_label` is the local selector, `server_label` the server-synced display name or null), a top-level `rail`, and a `balances: { on_chain_usd_micros, on_chain_token, prepaid_credit_usd_micros, held_usd_micros }` object. The on-chain token tracks the rail (USDC on x402, pathUSD on mpp); prepaid credit is rail-independent.

### wallets
Manage multiple named wallets (profiles) on one machine. Keys never leave the machine (non-custodial). The `default` wallet lives at the config-dir root; named wallets live under `{config_dir}/profiles/<name>/`.
- `run402 wallets list` — JSON array of `{ local_label, server_label, address, address_short, rail, active }`. Reads non-secret `meta.json`; never loads private keys.
- `run402 wallets current` — the resolved active wallet `{ name, source, source_detail, address, label, warnings }`. `source` ∈ flag|env|binding|config|default. `warnings` surfaces env-vs-binding conflicts and local-name-vs-server-label drift.
- `run402 wallets new <name> [--mpp]` — create a new named wallet (generates a key). `{ name, address, rail, created: true }`.
- `run402 wallets use <name>` — set the global default wallet (`config.json` `active_wallet`). `{ name, active: true }`.
- `run402 wallets rename <old> <new>` — rename a wallet; renaming `default` migrates its root files into `profiles/<new>/`. `{ from, to, renamed: true }`.
- `run402 wallets bind [<name>]` — write `./.run402.json` binding this directory to a wallet (defaults to the active one). Safe to commit (holds only a name). `{ wallet, file, bound: true, safe_to_commit: true }`.
- `run402 wallets unbind` — remove `./.run402.json`. `{ file, unbound }`.
- `run402 wallets import <name> --key <path|->` — adopt an existing 0x-prefixed 64-hex private key (file path or `-` for stdin) as a named wallet. `{ name, address, imported: true }`.
- `run402 wallets rm <name> --yes` — delete a wallet and its keys. Requires `--yes` (agent-first: no interactive prompt). Refuses to remove `default`. `{ name, removed: true }`.
- Server-side display label: `new`/`rename`/`import` push the wallet's name to a server-side label (signed by the wallet — proof of control) so the same name shows cross-machine and in the operator console (WEB). Best-effort and on by default; `RUN402_WALLET_LABEL_SYNC=0` opts out (fully offline wallet ops). The local folder name is the source of truth; the label is a mirror, and `wallets current` flags any drift.
- Selection for ANY command: `--wallet <name>` (alias `--profile`) > `RUN402_WALLET` > nearest `./.run402.json`/`.run402.local.json` > `wallets use` default > `default`. A conflicting env + binding errors with `WALLET_SELECTION_CONFLICT` (resolve via `--wallet`, `unset RUN402_WALLET`, or `wallets unbind`). Selecting a non-existent wallet errors with `WALLET_NOT_FOUND`.

### allowance
- `run402 allowance <create|status|fund|balance|export>`
- `run402 allowance checkout --amount <usd_micros>`
- `run402 allowance history [--limit <n>]`

### tier
Tier and quotas are per billing account (not per project) — `set` is account-wide, `status.pool_usage` is the pooled total across every project on the account. `set` refetches status after the call and includes it as `status_after`.

- `run402 tier status`
- `run402 tier set <prototype|hobby|team>`

### projects
- `run402 projects quote`
- `run402 projects list [--org <id>] [--all]` — SERVER read of the named, domain-aware inventory (NOT the local keystore). Membership-scoped by default: every project owned by an org your wallet is an active member of, each row `{ project_id, name, site_url, custom_domains, org_id, status, active }` (`active` from local state). `--org <id>` filters to one org (authorize-before-reveal: non-member/guessed id -> 403, non-UUID -> 400). `--all` reads the cross-wallet inventory across every wallet controlling your operator email — run `run402 operator login` first for the union, else it falls back to the current wallet's slice and echoes `scope`. Bare `run402 projects list` is the cold-start path (no login needed). Tier/lifecycle live on the billing account — use `run402 status` / `run402 tier status`.
- `run402 projects rename <id> --name <label>` — rename a project (fix an auto-generated name). Needs org `admin`+ (or a `project:write` grant) on the owning org; authorize-before-reveal (unauthorized/guessed id -> 403, never a not-found oracle). Works even if the project isn't in the local keystore. Server-validated name (1-200 chars, no control characters).
- `run402 projects provision [--name <name>] [--org <id>]` — `--org` provisions into an EXISTING org (you need `developer`+ on it); omit for the cold-start path (the wallet's billing account). Tier is org-governed — a client-supplied `--tier` is ignored when targeting an org.
- `run402 projects use <id>`
- `run402 projects info <id>`
- `run402 projects sql <id> "<sql>" [--file <path>] [--params '<json_array>']`
- `run402 projects rest <id> <table> "<query>"`
- `run402 projects keys <id>` — print anon_key + service_key as JSON
- `run402 projects costs <id> [--window <24h|7d|30d|90d>]` — admin-only per-project finance: revenue, direct cost, margin, and cost breakdown. Uses the configured allowance wallet for admin auth; `RUN402_ADMIN_COOKIE='run402_admin=...'` is an optional browser-session override.
- `run402 projects promote-user <id> <email>` — promote a user to project_admin role
- `run402 projects demote-user <id> <email>` — demote a user from project_admin role
- `run402 projects <usage|schema> <id>`
- `run402 projects delete <id> --confirm` — cascade deletes all project resources: Lambda functions, subdomains, S3 site files, deployments, secrets, and published app versions. The schema slot is dropped and recreated. This is irreversible. `--confirm` is required.
- `run402 projects validate-expose [id] <manifest_json>` — validate an auth/expose manifest without applying it
- `run402 projects validate-expose [id] --file manifest.json [--migration-file setup.sql]` — validate file input with optional migration-reference SQL
- `run402 projects apply-expose <id> <manifest_json>` — apply a declarative authorization manifest
- `run402 projects apply-expose <id> --file manifest.json` — apply from a JSON file
- `run402 projects get-expose <id>` — print the current manifest (`source: applied | introspected`)

Provisioning automatically sets the new project as the active project. Other commands that take `<id>` default to the active project when omitted.

SQL supports DDL + queries, returns JSON. REST uses PostgREST syntax (`select=`, `eq.`, `order=`, `limit=`).

User auth: password + Google OAuth. See "User Auth" section below.

### admin (platform-admin only, v1.57+)
- `run402 admin lease-perpetual <billing_account_id> --enable | --disable` — toggle the account-level escape hatch. When enabled, the account never advances past `active` regardless of lease expiry; every project on the account is pinned. Enabling on a grace-state account (past_due / frozen / dormant) reactivates inline (`reactivated: true` in the response). Replaces the v1.56 `run402 projects pin` (gateway endpoint /projects/v1/admin/:id/pin was removed in v1.57).
- `run402 admin archive <project_id> [--reason "..."]` — operator moderation. Sets `projects.archived_at = NOW()` on a single project; sibling projects on the same billing account keep serving. No-op when already archived (returns `note: "already archived"`).
- `run402 admin reactivate <project_id>` — un-archive a project (flips `archived_at` back to NULL). In v1.57 this was narrowed: it no longer touches account-level lifecycle. To reactivate a grace-state account, run `run402 tier set <tier>` (the tier flow runs the lifecycle advance inline) or enable `run402 admin lease-perpetual <ba_id> --enable`.

All admin subcommands require a platform-admin allowance wallet (or an admin OAuth session). Project owners with a non-admin wallet receive `403 admin_required`.

### deploy
- `run402 deploy apply --manifest app.json [--project <id>] [--quiet|--final-only] [--allow-warning <code> ...] [--allow-warnings]` — unified apply primitive (v1.34 unified deploy → v2.0 unified apply with `assets` slice support)
- `run402 deploy resume <operation_id> [--quiet]` — re-run a stuck operation forward
- `run402 deploy promote <release-id> [--project <id>] [--allow-warning <code>] [--allow-warnings]` — operator pointer-swap (re-point live release without re-running the apply pipeline); v1.58+
- `run402 deploy list [--project <id>] [--limit <n>]` — list recent deploy operations
- `run402 deploy events <operation_id> [--project <id>]` — fetch the recorded event stream for an operation
- `run402 deploy release get <release_id> [--project <id>] [--site-limit <n>]` — fetch release inventory
- `run402 deploy release active [--project <id>] [--site-limit <n>]` — fetch current-live release inventory
- `run402 deploy release diff --from <empty|active|release_id> --to <active|release_id> [--project <id>] [--limit <n>]` — diff release targets
- `run402 deploy diagnose [--project <id>] <url> [--method GET]` — URL-first public deploy diagnostics
- `run402 deploy resolve [--project <id>] (--url <url> | --host <host> [--path /x]) [--method GET]` — lower-level resolver parity; `--url` cannot be combined with `--host`/`--path`

Requires active tier and a provisioned project. Deploys to an existing project: runs migrations, applies the authorization manifest (from a `manifest.json` entry in `files[]`), deploys functions, deploys static site, and claims subdomain. Secret values are write-only: set them with `printf %s "$OPENAI_API_KEY" | run402 secrets set <id> OPENAI_API_KEY --stdin` or `--file <path>` before deploy, then use value-free `secrets.require` in `deploy apply` manifests. `deploy apply` stops before upload/commit on confirmation-required warnings unless each warning is covered by repeatable `--allow-warning <code>` or the broad reviewed `--allow-warnings`. The manifest must include `project_id` (or use `--project` flag, or omit both to use the active project).

Inside GitHub Actions, `deploy apply` automatically uses OIDC credentials when `GITHUB_ACTIONS=true`, `ACTIONS_ID_TOKEN_REQUEST_URL`, and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` are present. In that mode, project id resolution is `--project`, then `manifest.project_id`, then the local active project if present, then `RUN402_PROJECT_ID`.

### ci
- `run402 ci link github [--project <id>] [--manifest <path>] [--repo <owner/repo>] [--branch <name> | --environment <name>] [--repository-id <id>] [--workflow <path>] [--expires-at <iso>] [--route-scope <pattern> ...] [--force]` — create a GitHub Actions OIDC deploy binding and write a workflow
- `run402 ci list [--project <id>]` — list CI bindings for a project
- `run402 ci revoke <binding_id>` — revoke a binding

`link github` requires a local allowance because it signs the delegation. The generated workflow does not require an allowance file or service key in GitHub; it uses GitHub's OIDC token with `id-token: write`. Use repeatable `--route-scope` only when CI should deploy route declarations; no scopes means no CI route authority.

### transfer (v1.59 two-party wallet handoff; v1.78 email->org handoff)
One noun, two rails: a **wallet** recipient is a two-party wallet transfer; an **email** recipient is an email->org handoff (the recipient claims it into an org). Both ride the same transfer rail and share a `transfer_id`.
- `run402 transfer init --to <wallet|email> [--project <id>] [--billing-policy migrate] [--message <text>] [--kysigned <record_id>]` — initiate (owner-only). `--to` routes by recipient kind: a wallet starts a transfer, an email starts a handoff. Returns `{ transfer_id, expires_at, ... }`.
- `run402 transfer preview <transfer_id> [--handoff]` — fetch the preview document (either party); `--handoff` previews an email->org handoff. Lists custom domains, subdomains, function names, secret NAMES (never values), CI bindings that will be revoked on accept, mailbox summary, billing implications.
- `run402 transfer list [--incoming | --outgoing | --handoffs] [--limit N] [--offset N]` — `--incoming` (default) shows wallet transfers OFFERED TO you; `--outgoing` shows transfers you initiated; `--handoffs` shows incoming email->org handoffs. Each entry includes `preview_path`.
- `run402 transfer accept <transfer_id>` — accept a WALLET transfer (recipient). Atomically flips ownership, revokes the previous owner's CI bindings on the project, and stamps a `secrets_rotation_advised` advisory. Secret VALUES are inherited; the response returns `secret_names_inherited[]`.
- `run402 transfer claim <transfer_id> [--into <billing_account_id>]` — claim an incoming EMAIL handoff into an org you own (omit `--into` to claim into a brand-new org). The handoff analog of `accept`.
- `run402 transfer cancel <transfer_id> [--reason <text>] [--handoff]` — cancel (either party); `--handoff` cancels an email->org handoff.

While a transfer is `pending` (72h TTL), owner-side mutations on the project return `409 PROJECT_HAS_PENDING_TRANSFER` with `details.transfer_id` and a `next_actions[]` cancel route. Data-plane (`/rest/v1/*`, function invocation, mailbox send/receive) keeps serving; payment-path routes (tier renew, billing) keep working; the `transfer cancel` route is intentionally unblocked so the owner can always recover. After accept, rotate every inherited secret with `run402 secrets set <project> <name> <value>` — the `secrets_rotation_advised` advisory on `tier status` clears once every previously-inherited name has been re-written.

What does NOT transfer: tier lease (stays with the original owner's billing account; no Phase 1A proration), KMS contract wallets (wallet-scoped, not project-scoped), GitHub repo ownership (handle out of band), or on-chain balance on any wallet. Phase 1A supports only `--billing-policy migrate` — the project moves into the recipient's billing account; if they have no active billing account yet, accept returns `409 RECIPIENT_ACCOUNT_NOT_ACTIVE`.

### org / grants (v1.77+ org-owned control plane; first-class orgs v1.82)
A wallet AUTHENTICATES; an org owns projects. Authorization is an org membership role (`owner > admin > developer > billing > viewer`) or a per-project grant — never `wallet == signer`. Member/invite changes require an active `owner`. Members and invites are grouped sub-resources (`org member …`, `org invite …`). Memberships carry `org_id` + `display_name`. Create/rename/member/invite mutations are step-up gated for control-plane sessions.
- `run402 org create [--name <label>]` — create an empty org on the prototype tier; you become owner. `--name` is an optional free-text label (non-unique, not an id; no tier at create). The soft per-owner free-org cap may return `FREE_ORG_OWNER_LIMIT_EXCEEDED`.
- `run402 org get <org>` — read one org: `{ org_id, display_name, tier, role }`. Any active member; a non-member (incl. a guessed id) gets the same non-revealing 403.
- `run402 org rename <org> <display_name>` (or `--clear`) — owner-only; set or clear the org's free-text label.
- `run402 org whoami` — resolve your control-plane principal + org memberships (GET `/agent/v1/whoami`). The REMOTE identity; for local wallet/profile state use `run402 status`.
- `run402 org list` — orgs you are a member of (`org_id`, `display_name`, role, status each).
- `run402 org audit <org> [--limit N] [--before <cursor>]` — control-plane audit trail for the org (admin+); newest-first, page with `--before`.
- `run402 org member list <org>` — members + roles of an org.
- `run402 org member add <org> <wallet> [--role <role>]` — add a member BY WALLET (a new wallet is provisioned as a `human` principal); `--role` defaults to `developer`.
- `run402 org member role <org> <principal_id> <role>` — change a member's role.
- `run402 org member rm <org> <principal_id>` — revoke a member.
- `run402 org invite list <org>` — pending email invites.
- `run402 org invite create <org> <email> [--role <role>] [--ttl-hours N]` — invite a person by email; `--role` defaults to `developer`. The invite is **claimed automatically** when the recipient first signs in via that verified email (`run402 operator login --loopback`, or any hosted email/OAuth login) — it then surfaces as an active membership in the login output and `org member list`. There's no invitee-side "accept" step. Owner/admin invites only claim once the recipient has enrolled a passkey; lower roles claim on any login.
- `run402 org invite rm <org> <principal_id>` — revoke a pending invite.
- `run402 grants create <project_id> <wallet> <capability> [--policy <json>] [--expires <iso8601>]` — issue a per-project capability grant (e.g. `deploy`, `functions:write`) to an agent/CI principal. Requires owner of the project's org.
- `run402 grants revoke <project_id> <grant_id>` — revoke a grant.

`org member role`/`org member rm` that would drop the org's only active owner fail with `409 LAST_OWNER` — promote another member to `owner` first. Principal ids (`prn_…`) come from `run402 org member list`.

### functions
Node 22 runtime. Must export `default async (req: Request) => Response`.
Built-in helper: `import { auth, db, adminDb, email, ai, assets } from '@run402/functions'`
- `auth.user()` — `Actor | null`. Triggers cache-bypass taint. `Actor` carries `{ id, projectId, sessionId, email, emailVerified, authTime, amr, amrTimes }`; note `id`, NOT `userId`, as the canonical public field. Hallucinated names (`getUser`, `getSession`, `currentUser`, `getServerSession`, `auth.protect`, `auth.signIn`, `auth.logout`, …) throw `R402_AUTH_UNKNOWN_EXPORT` at runtime AND fail `run402 doctor` source scan at deploy.
- `auth.requireUser()` — `Actor`. 303 → `/auth/sign-in?returnTo=` (HTML) or 401 envelope (JSON) on anonymous. Don't catch — the platform handles redirect-vs-envelope automatically.
- `auth.requireRole<const R>(role: R)` / `auth.requireMembership<const M>(m: M)` — gate helpers; imply `requireUser`; return `{ user, role }` / `{ user, membership }`. Always read fresh server-side grant state (no positive cache, so revocation is instant across tasks).
- `auth.requireFresh({ maxAge, amr? })` — per-AMR step-up. Reads `Actor.amrTimes`; a recent password proof does NOT satisfy `{amr: ["passkey"]}`.
- `auth.fetch(input, init?)` — same-origin-only fetch with synchronous URL validation; `redirect: "manual"` default; never forwards cookies or actor headers across origin hops.
- `auth.csrfToken()` / `auth.csrfField()` — double-submit token for hosted forms (renders `<input type="hidden" name="_csrf" value="...">`).
- `auth.sessions.createResponseFromIdentity({ provider, subject, proof, amr, createUser? })` — custom identity proof bridge. Platform verifies the proof end-to-end; raw-userId session minting is NOT in the public API.
- `auth.sessions.endResponse()` — sign-out: revokes the active session row + returns Set-Cookie clear.
- `auth.identities.link({ provider, subject, proof })` — atomic nonce consumption + identity INSERT; 409 R402_AUTH_IDENTITY_LINK_CONFLICT on duplicate.
- `db(req?)` — caller-context DB client. Inside an SSR request with a verified actor, mints a 60s actor JWT (`sub`, `project_id`, `session_id`, `authz_version`) so `run402.current_user_id()` resolves in RLS without any client-side header plumbing. Routes to `/rest/v1/*`. Use this by default; RLS handles `WHERE user_id = current` automatically — adding `.eq("user_id", user.id)` deploy-fails with `R402_AUTH_REDUNDANT_USER_FILTER` unless `// run402-allow-user-filter:` annotated.
- `adminDb()` — BYPASSRLS DB client. Uses the project's service_key. Routes to `/admin/v1/rest/*` (the gateway rejects `role=service_role` on `/rest/v1/*`). Use ONLY when the function acts on behalf of the platform, not the caller — audit logs, webhook handlers, cron cleanup.
- `getUserId(req)` / `getRole(req)` — gateway-injected `x-run402-user-id` / `x-run402-user-role` header readers for the function-level `requireAuth` / `requireRole` gate flow (v1.51+, distinct from the v3.0 `auth.*` cookie-session flow above). Both throw `R402_AUTH_UNKNOWN_EXPORT` if imported from `@run402/functions` directly — they were removed as bare exports in v3.0; use `auth.*` for the cookie-session flow or read the headers manually for the gate flow.
- `email.send(opts)` — send email from the project's mailbox (see email section below)
- `ai.generateImage({ prompt, aspect? })` — live image generation from deployed functions using project billing authority, not local allowance/x402 signing. Aspects: `square`, `landscape`, `portrait`; result: `{ image, content_type, aspect }`. Add app auth/rate limits before calling it from public routed functions.
- `assets.put(key, source, opts?)` — upload bytes to the project's blob store from inside a deployed function. Uses the same CAS substrate as deploy-time assets. `source` is a string, `Uint8Array`, or `{ content | bytes }` object. Options: `contentType`, `visibility` (`"public"` | `"private"`, default `"public"`), `immutable` (default `true`). Returns an `AssetRef` with `url`, `immutableUrl`, `cdnUrl`, `sha256`, `size_bytes`, etc. (camelCase aliases included). Use for user-uploaded content, generated images, runtime-produced files.
- `assets.fromRef(raw)` (v2.7+) — re-hydrate a stored AssetRef (JSONB column read from your DB) into the typed `AssetRef` shape with camelCase aliases + variant map. Pure-local, no network — safe in SSR render paths. The recommended persistence pattern is to store the full `AssetRef` returned by `r.assets.put` as a JSONB column so variant SHAs + immutable URLs survive the round-trip (they can't be re-derived from `(source_sha, key)` alone). Tolerant of partial inputs: pre-v1.49 blobs come back without `variants` / `width_px` than synthesizing them. Throws only on null/undefined or non-object input.
- `getRun402Context(req)` (v2.7+) — zero-dependency reader for the full per-request context the gateway populates as `x-run402-*` headers. Returns `{ requestId, projectId, releaseId, host, locale, defaultLocale }` (all `string | null`). Use in non-Astro functions (plain webhook handlers, auth endpoints) instead of hand-rolling `req.headers.get('x-run402-...')` per field — the helper papers over `Request` / `Headers` / plain-object header shapes and any future gateway header renames. Same return shape as `Astro.locals.run402`. Never throws; missing headers come back as `null`.

TypeScript types: `npm install @run402/functions@^3` to get full autocomplete for the `auth.*` namespace, `db(req?)`, `adminDb()`, `getRun402Context()`, `email.send()`, `ai.translate()`, `ai.generateImage()`, `assets.put()`, and `assets.fromRef()`. Works in any Node.js/TypeScript project (Astro, Next.js, plain TS). For static site generation, use `adminDb().from()` at build time with `RUN402_SERVICE_KEY` + `RUN402_PROJECT_ID` in your `.env`.

#### db(req).from(table) — caller-context, RLS applies

PostgREST-style queries scoped to the caller's JWT role. Returns a plain array of row objects. Unauthenticated callers resolve to `role=anon` and see only what anon policies allow.

Reads:
- `.select(cols?)` — columns to return (default `"*"`)
- `.eq(col, val)`, `.neq()`, `.gt()`, `.lt()`, `.gte()`, `.lte()` — filters
- `.like(col, pattern)`, `.ilike(col, pattern)` — pattern match
- `.in(col, [values])` — IN clause
- `.order(col, { ascending? })` — sort (default ascending)
- `.limit(n)`, `.offset(n)` — pagination

```
export default async (req: Request) => {
  // Runs with the caller's JWT — RLS decides what they see.
  const myItems = await db(req).from('items').select('title, done').limit(10);
  return new Response(JSON.stringify(myItems), { headers: { 'content-type': 'application/json' } });
};
```

Writes (also return an array of affected rows):
- `.insert(obj | obj[])` — insert one or many rows
- `.update(obj)` — update matched rows (combine with `.eq()`)
- `.delete()` — delete matched rows (combine with `.eq()`)

```
// All three run as the caller — RLS policies decide if the write is allowed.
const created = await db(req).from('items').insert({ title: 'New', done: false });
await db(req).from('items').update({ done: true }).eq('id', 1);
await db(req).from('items').delete().eq('id', 1);
```

Column narrowing works with writes: `.insert({...}).select('id, title')` returns only those columns.

#### adminDb().from(table) — BYPASSRLS, opt-in

Identical fluent surface to `db(req).from(...)` but uses the service_key. Returns all rows regardless of RLS. Use for server-side work where the function itself is the principal.

```
// Audit log — must capture every event regardless of who called the function.
await adminDb().from('audit_log').insert({ event: 'payment_succeeded', user_id: userId });

// Cron cleanup — no caller context.
await adminDb().from('sessions').delete().lt('expires_at', new Date().toISOString());
```

#### adminDb().sql(query, params?) — raw SQL, always BYPASSRLS

Returns `{ status, schema, rows, rowCount }`.
- SELECT: `rows` = matching rows, `rowCount` = row count
- INSERT/UPDATE/DELETE: `rows` = `[]`, `rowCount` = affected rows
- Parameterized: `adminDb().sql('SELECT * FROM t WHERE id = $1', [42])`

```
const result = await adminDb().sql('SELECT * FROM users WHERE active = true');
// { status: "ok", schema: "p0001", rows: [{ id: 1, name: "Alice" }], rowCount: 1 }
const rows = result.rows;
```

`db` is a request-scoped function. Use `db(req).from(...)` for caller-context RLS or `adminDb().from(...)` / `adminDb().sql(...)` for service-key work.

#### Calling functions from the browser

Functions are accessible via HTTP at `https://api.run402.com/functions/v1/<name>`. This direct invoke path remains API-key protected even when deploy-v2 web routes expose browser paths to the same function. Use the project's `anon_key` as the `apikey` header. For authenticated calls, also pass the user's `access_token`:

```javascript
const res = await fetch('https://api.run402.com/functions/v1/my-function', {
  method: 'POST',
  headers: {
    apikey: ANON_KEY,
    Authorization: 'Bearer ' + session.access_token,  // optional, for authenticated calls
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ key: 'value' })
});
```

- `run402 functions deploy <id> <name> --file <file> [--deps "<spec,...>"] [--timeout <s>] [--memory <mb>] [--schedule "<cron>"]`
- `run402 functions invoke <id> <name> [--body '<json>'] [--method <GET|POST|...>] [--raw]` — default emits a JSON envelope `{ http_status, body, duration_ms }` (HTTP status surfaced as `http_status` to avoid colliding with the reserved top-level `status` sentinel on stderr). Safe to pipe to jq even when the function returns `text/plain`. `--raw` skips the envelope: string body → text + newline, JSON body → pretty-printed JSON. Useful when piping a CSV / binary-blob response straight to a file.
- `run402 functions logs <id> <name> [--tail <n>] [--since <iso-timestamp>] [--request-id <req_...>] [--follow]` — `--tail` defaults to 50 and is capped at 1000. Non-follow mode emits a single `{ logs: [...] }` JSON object; `--follow` mode emits **NDJSON** (one log entry per line) so streaming consumers can parse incrementally without a wrapping envelope.
- `run402 functions update <id> <name> [--schedule "<cron>"] [--schedule-remove] [--timeout <s>] [--memory <mb>]`
- `run402 functions rebuild <id> <name>` / `run402 functions rebuild <id> --all` — opt-in refresh of a deployed function onto the platform's current runtime/entry-wrapper. Re-bundles from the **stored source** with deps pinned to the recorded exact versions, so the source `code_hash` is unchanged and no new release is created — only the platform wrapper/runtime changes. This is how a gateway-side wrapper fix (e.g. an SSR `auth.*` fix) reaches an already-deployed function: a plain redeploy with unchanged source does **not** pick it up. Single returns `{ name, rebuilt, old_fingerprint, new_fingerprint, runtime_version_before, runtime_version_after, code_hash }`; `--all` returns `{ rebuilt_count, total, results: [...] }` where each result is a rebuild record or `{ name, rebuilt: false, code?, error }`. Functions deployed before dependency locking return `CANNOT_REBUILD_UNLOCKED_DEPS` (HTTP 409 for single, a per-function entry for `--all`) — redeploy them from source instead. Wallet-authed; allowed during billing grace (`past_due` / `frozen` / `dormant`).
- `run402 functions <list|delete> <id> [<name>]`

`run402 doctor` surfaces a `runtime_staleness` check (warning) listing any deployed functions on an older platform runtime, with the `run402 functions rebuild --all` remediation. Staleness is read-only — observing it never mutates a function.

For routed browser 500s, copy `X-Run402-Request-Id` or the JSON `request_id` from the response and run `run402 functions logs <project> <function> --request-id req_...`. `--since` is validated locally and should be supplied for incidents older than the default recent lookup window.
`--tail` must be a positive safe integer no larger than 1000, and `--request-id` must match the routed request id shape (`req_...`). For updates, `--schedule` and `--schedule-remove` are mutually exclusive.

#### --deps semantics, runtime_version, deps_resolved

`--deps` is a comma-separated list of npm specs that the gateway installs and bundles into the function zip alongside the user code:
- Bare names (`lodash`) resolve to the latest published version at deploy time.
- Pinned (`lodash@4.17.21`) and range (`date-fns@^3.6.0`) specs are honored verbatim.
- Entries are trimmed; empty entries e.g. `--deps "lodash,,date-fns"` are rejected locally.
- `@run402/functions` (auto-bundled) and the legacy `run402-functions` name are rejected.
- Limits: max 30 entries, max 200 chars per spec.
- Native binary modules (sharp, canvas, native bcrypt, etc.) are rejected.

The deploy / list / update responses include two fields populated under bundling-at-deploy:
- `runtime_version` — the bundled `@run402/functions` version (e.g. `"1.48.0"`). Surface this as "Functions runtime version" — never bare "runtime", which already names the Node runtime (e.g. `node22`). `null` for legacy functions.
- `deps_resolved` — map of each `--deps` name to the -installed concrete version (e.g. `{"date-fns": "3.7.0"}` for a `^3.6.0` spec). Direct deps only; this is not a lockfile. `{}` for an empty `--deps`; `null` for legacy functions.

The deploy response also gains an optional top-level `warnings: string[]` (sibling to the function record, not inside it) for non-fatal deploy notes e.g. bundle-size advisories. Omitted or `[]` when there are no warnings.

#### Function authoring limits by tier

| | Prototype | Hobby | Team |
|---|---|---|---|
| Max timeout | 10s | 30s | 60s |
| Max memory | 128 MB | 256 MB | 512 MB |
| Max scheduled functions | 1 | 3 | 10 |
| Min interval | 15 min | 5 min | 1 min |

`run402 deploy apply` preflights literal unified-deploy function specs against these caps before plan/upload when the values are known. Gateway validation remains authoritative; `run402 tier status` includes live function caps and current scheduled usage when returned.

Secrets available as `process.env` (see secrets below).

### secrets
Injected as `process.env` in functions. Values are write-only — `list` returns keys and timestamps only, never values or value-derived hashes. Prefer `--file` or `--stdin` for real values so they do not land in shell history. `--file -` and `--file /dev/stdin` read stdin too.

- `run402 secrets set <id> <KEY> [<VALUE>] [--file <path>|--stdin]`
- `run402 secrets <list|delete> <id> [<KEY>]`

### jobs
Fixed platform-managed jobs. This is not arbitrary Docker execution: submit a gateway-shaped request for the delivered `job_type`, then inspect status, logs, or cancel the run. The SDK supplies the required idempotency header; the CLI does not expose it.

- `run402 jobs submit --file job.json [--project <id>]`
- `run402 jobs submit --stdin [--project <id>]`
- `run402 jobs get <job_id> [--project <id>]`
- `run402 jobs logs <job_id> [--project <id>] [--tail <n>] [--since <epoch_ms>]`
- `run402 jobs cancel <job_id> [--project <id>]`
- `run402 jobs artifacts get <job_id> <file> --output <path> [--project <id>]`

Submit request shape:

```json
{
  "job_type": "kysigned.fflonk_prove.v0_17_0",
  "input": { "input.json": {} },
  "max_cost_usd_micros": 50000
}
```

Artifacts: when a job completes, `jobs get` returns an `artifacts` map keyed by
filename. Each value is an object — `{ "url", "content_type", "sha256",
"size_bytes" }` — not a bare ref string (the old, never-resolvable
`run402://storage/...` scheme was retired). `sha256`/`size_bytes` are omitted
for jobs created before this change; the `url` still serves. Download the bytes
with `run402 jobs artifacts get <job_id> <file> --output <path>` (auth is the
project service key, same as the rest of the jobs API). The recorded filenames
are `proof.json`, `public.json`, `prove-output.log`, `prove-time.log`, and
`verify-output.log`; a 404 means the job has not completed or the filename was
not recorded for that run.

### assets (primary storage API)

Direct-to-S3 asset storage. Works for any size from 1 byte up to 5 TiB. No bucket concept — assets live in a flat key namespace per project. Renamed from `blob` in v2.0 alongside the unified-apply rename.

For bulk directory work, use `run402 deploy apply` with an `assets` slice in the manifest (see [Unified Deploy](#unified-deploy)) — additive batches via `assets: { put: [...] }`, declarative sync with confirm-token semantics via `assets: { put: [...], sync: { prefix, prune: true, confirm? } }`. There is no `run402 assets sync` subcommand — the apply path is the canonical bulk surface so a single transaction can stage HTML + new asset URLs together.

- `run402 assets put <file> [files...] [--project <id>] [--key <dest>] [--content-type <mime>] [--private] [--immutable] [--meta <k=v>] [--exif-policy keep|strip] [--concurrency N] [--no-resume] [--stream]` — without `--stream`, stdout is the final results array (JSON). With `--stream`, stdout is NDJSON per-file progress events. `--json` is a deprecated alias for `--stream` (writes a deprecation warning to stderr).
- `run402 assets get <key> --output <file> [--project <id>]`
- `run402 assets ls [--project <id>] [--prefix <p>] [--limit <n>] [--sort key:asc|createdAt:asc|createdAt:desc] [--filter <k=v> ...]`
- `run402 assets rm <key> [--project <id>]`
- `run402 assets sign <key> [--project <id>] [--ttl <seconds>]` — signed URL TTL must be an integer from 60 to 604800 seconds.
- `run402 assets diagnose <url> [--project <id>]` — inspect live CDN state for a public URL
- `run402 cdn wait-fresh <url> --sha <hex> [--timeout <secs>] [--project <id>]` — poll a mutable URL until it serves the expected SHA-256

`put` flags (v1.50):
- `--meta key=value` — repeatable. Attach caller-supplied metadata to the asset. Coercion: pure digits (with optional `-` / `.`) become a number, `true`/`false` become a boolean, values containing `,` become a `string[]`, everything else is a string. Total serialized size ≤ 4 KB; nested objects are not expressible from the CLI. Rejected client-side with `INVALID_ASSET_METADATA` when the resulting bag is structurally invalid.
- `--exif-policy keep|strip` — EXIF retention policy for image uploads. Default `keep`. `strip` discards EXIF bytes from the stored object and the `image_exif` response field. Other values are rejected with `INVALID_EXIF_POLICY`.

`ls` flags (v1.50):
- `--sort key:asc|createdAt:asc|createdAt:desc` — result ordering. Default `key:asc` (legacy bare-key cursor). The `createdAt:*` variants use a base64url JSON `{s, ts, key}` cursor; reusing a cursor across sort keys returns `400 INVALID_CURSOR_FOR_SORT`.
- `--filter key=value` — repeatable media-picker filter. Allowed keys: `uploaded_by`, `tag`, `format`, `is_image` (`true`/`false`), `min_width`, `max_width`, `min_height`, `max_height` (non-negative ints). Unknown keys are rejected client-side with `INVALID_FILTER_KEY`.

Examples:

```
run402 assets put ./artifact.tgz --project prj_abc123
run402 assets put ./hero.jpg --project prj_abc123 --meta uploaded_by=agent_abc --meta version=3 --meta tags=hero,banner --exif-policy strip
run402 assets put ./dist/**/*.png --project prj_abc123 --key assets/
run402 assets put ./asset --project prj_abc123 --key assets/logo --content-type image/svg+xml
run402 assets put huge.bin --project prj_abc123 --immutable
run402 assets get images/logo.png --output /tmp/logo.png --project prj_abc123
run402 assets ls --project prj_abc123 --prefix images/
run402 assets ls --project prj_abc123 --sort createdAt:desc --filter is_image=true --filter min_width=320 --filter format=webp
run402 assets ls --project prj_abc123 --filter uploaded_by=agent_abc --filter tag=hero
run402 assets diagnose https://app.run402.com/_blob/avatar.png --project prj_abc123
run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha ba78... --timeout 120
```

`put` response (an `AssetRef`) — the agent-DX way:

```js
const asset = await client.assets.put(projectId, key, { bytes });  // v1.45 defaults to immutable: true
html += asset.scriptTag();             // <script src=... defer integrity=... crossorigin></script>
html += asset.linkTag();               // <link rel="stylesheet" href=... integrity=... crossorigin>
html += asset.imgTag("Company logo");  // <img src=... alt="Company logo" width=... height=... loading="lazy" decoding="async">
html += asset.imgTagWithSrcSet({ alt: "Hero", sizes: "(max-width: 800px) 100vw, 1920px" });
// → <picture><source type="image/webp" srcset="<thumb> 320w, <medium> 800w, <large> 1920w" sizes="…">
//             <img src="<display_url>" alt="Hero" width="…" height="…" loading="lazy" decoding="async"></picture>
```

`immutable: true` is the default since v1.45 — the SDK computes the SHA-256 client-side and the gateway returns a content-addressed URL paired with SRI. The resulting URL never needs cache invalidation, never breaks on re-deploys, never needs `cdn wait-fresh` follow-up. The SDK and CLI always compute and send the object SHA-256 because upload sessions require it; pass `{ immutable: false }` only when you need mutable URL/cache semantics. In that case the tag emitters throw because there's no immutable URL/SRI to bind. The tag emitters also bake in modern best-practice attributes — `defer` on `<script>`, `loading="lazy"` + `decoding="async"` on `<img>` — so the agent doesn't have to remember.

Other AssetRef fields for advanced use:
- `cdnUrl` — the content-addressed URL the emitters use directly. `https://pr-<public_id>.run402.com/_blob/<key-without-ext>-<8hex>.<ext>`. Served via the v1.33 CDN; guaranteed-reachable.
- `cdnMutableUrl` — mutable URL on the auto-subdomain. Eventual-consistency caveats; prefer `cdnUrl` in code.
- `url` / `immutableUrl` (preferred-host forms) — URL on the project's pretty host (claimed subdomain / custom domain when configured). Currently NOT served through the CDN — keep using for direct-API consumers (e.g. `run402 assets get`), not in `<script>`/`<img>` embeds.
- `etag` — strong `"sha256-<hex>"` ETag (when `immutable`).
- `sri` — `sha256-<base64>` for `<script integrity={sri}>` if you must construct tags by hand.
- `contentDigest` — RFC 9530 `sha-256=:<base64>:` for HTTP integrity.
- `cacheKind` — `"immutable" | "mutable" | "private"`.
- `cdn.{version,invalidationId,invalidationStatus,ready,hint}` — CloudFront invalidation envelope; `cdn.ready === true` for immutable uploads.

Image-variant fields (v1.49+ gateway, `@run402/sdk@2.3.0+`, populated for image MIMEs ≥ 320×320):
- `width_px`, `height_px` — display-oriented dimensions (post-EXIF rotate). `imgTag` emits these as `<img width height>` attributes when present (eliminates CLS).
- `blurhash` — ~30-byte LQIP placeholder; decode client-side with the `blurhash` npm package to render a placeholder before the real image is ready.
- `variant_spec_version` — pins URL identity to the encoder generation. Bumping (gateway-side) produces new URLs without invalidating older ones.
- `display_url` / `display_immutable_url` — browser-displayable URL. For jpeg/png/webp/avif sources this equals `cdn_url`. For HEIC/HEIF sources this points at a JPEG `display_jpeg` variant so `<img src>` renders correctly without HEIC-specific app code. HEIC source bytes are preserved verbatim in CAS (uploaded SHA == stored SHA). The `imgTag` / `imgTagWithSrcSet` helpers default `<img src>` to `display_url` so HEIC just works.
- `variants.thumb` / `variants.medium` / `variants.large` — three WebP variants (320w / 800w / 1920w), each with `url`, `cdn_url`, `width_px`, `height_px`, `format: "webp"`, `sha256`. Use `variants.thumb.cdn_url` in MediaPicker-style admin grids to avoid downloading full-res originals.
- `variants.display_jpeg` — only present for HEIC/HEIF sources. Full-res JPEG, quality 90, sRGB-converted.
- `thumbUrl` (SDK convenience, v2.3+) — `variants.thumb.cdn_url ?? displayUrl` for image refs; `undefined` for non-image AssetRefs. Single field for grid thumbnails — TypeScript narrows so `<img src={pdfRef.thumbUrl}>` is a compile error than a broken thumbnail at runtime.
- `displayUrl` (SDK convenience, v2.3+) — `display_url ?? cdn_url` for image refs; `undefined` for non-images. Use for hero / single-image render paths.
- `imgTagWithSrcSet(opts)` (SDK helper, v2.3+) — emits `<picture>` with WebP-only `<source>` (three sizes) and `display_url` as the `<img>` fallback. Throws at call time on missing `opts.sizes` (browsers over-fetch the largest candidate without it) OR missing `variants` (use `imgTag()` instead — no silent fallback). AVIF deferred from v1 (`<picture>` type-precedence footgun: AVIF must land at all three sizes simultaneously or via a separate `imgTagHero()` helper).
- Both write paths produce identical `AssetRef` shapes: `r.assets.put(...)` and `r.project(id).apply({ assets: { put: [...] } })`. Pickers can use either entry point.
- Encoder errors surface as HTTP 422 `IMAGE_DECODE_FAILED`, 413 `IMAGE_INPUT_TOO_LARGE` (>40 MP or >12000 px any axis), 504 `IMAGE_ENCODE_TIMEOUT`, 429 `TOO_MANY_ENCODES_QUEUED` (encoder semaphore full — retry after 2s).

Metadata + EXIF policy + intrinsics fields (v1.50+ gateway, `@run402/sdk@2.4.0+`):
- `metadata` — caller-provided flat metadata bag. Values are `string | number | boolean | string[]`. Total ≤ 4 KB serialized. `null` when none was set. Nested objects are rejected client-side with `INVALID_ASSET_METADATA` so a bad upload never reaches the gateway.
- `image_format` — decoded image format (`jpeg`/`png`/`webp`/`avif`/`heic`/`tiff`/`svg`/`bmp`). `null` for non-image rows.
- `image_info` — server-extracted intrinsics: `has_alpha`, `color_space`, `animated`, `frame_count`, `bit_depth`, `orientation`. `null` for non-image rows. Future gateway versions may add keys — treat as opaque.
- `image_exif` — server-extracted EXIF block. `null` for non-image rows, for stripped uploads (`image_exif_policy === "strip"`), and for image formats without EXIF (SVG/BMP).
- `image_exif_policy` — echo of the EXIF policy applied: `"keep"` (default) or `"strip"`. `null` for non-image rows.
- These fields ride alongside the v1.49 `width_px` / `height_px` / `blurhash` / `variants` additions — same FLAT shape, NOT wrapped under `image: {}`.

Shape-contract fields (v1.54+ gateway, `@run402/sdk@2.12.0+`, populated atomically with variants at upload time):
- `blurhash_data_url` — pre-decoded PNG data URL (~600-1200 bytes typical at 16×16) computed once at upload from the canonical pinned BlurHash decoder. Embed directly as `background-image` for the placeholder — zero render-time decode, no client-side blurhash library needed. `null` only when the decoder failed on otherwise-valid input (rare). Absent for pre-v1.54 uploads.
- `asset_schema` — semver shape-contract stamp recording the highest contract this row's fields satisfy (`"v1.49"` | `"v1.50"` | `"v1.54"` | `null`). `null` marks partial-shape rows (e.g., HEIC sources missing `display_jpeg`). Strict-mode consumers read this to skip legacy rows without per-field existence branching. Absent for pre-v1.54 uploads.
- The v1.54 substrate enables the `<Run402Image>` component in `@run402/astro@1.0+`: pre-decoded placeholder + WebP-ladder responsive `<picture>` + width/height for zero-CLS, with optional `imageDefaults.strict: { onSchema: ">=v1.49" }` to hard-fail on legacy rows during the rollout that follows every schema migration. Astro + React entries; byte-identical HTML output across both.

Typed errors a caller can branch on (`catch (e) { if (e.code === "...") }`):
- `INVALID_ASSET_METADATA` (HTTP 400 or `LocalError` pre-network)
- `INVALID_EXIF_POLICY` (HTTP 400 or `LocalError` pre-network)
- `INVALID_FILTER_KEY` (HTTP 400 or `LocalError` pre-network)
- `INVALID_SORT` (HTTP 400 or `LocalError` pre-network)
- `INVALID_CURSOR_FOR_SORT` (HTTP 400 — cross-sort cursor reuse)
- `IMAGE_DECODE_FAILED` (HTTP 422 — no partial row written)

**Agent loop pattern (mutable URL only):** if you must use a stable mutable URL across re-uploads, `run402 cdn wait-fresh <mutable-url> --sha <new-sha>` blocks until the CDN serves the new SHA. Don't call wait-fresh on immutable URLs — they're correct from the moment of upload.

Resume: removed in v2.1.0. The CLI now delegates to `sdk.assets.put`, which routes through the unified-apply hero (`apply/v1/plans → content/v1/plans → S3 PUT → commit`). The `--concurrency` and `--no-resume` flags are accepted for backward compatibility but ignored — resume semantics now live at the apply-plan level (24h plan TTL).

Private blobs (`--private`): no CDN URL returned; read via authenticated gateway path `GET /storage/v1/blob/<key>` with apikey, or via `run402 assets sign` for time-boxed external sharing.

Content-Type: `blob put` infers MIME from the destination key extension. Use `--content-type <mime>` for extensionless assets, uncommon file types, or deliberate overrides; the value applies to every file in the invocation.

`diagnose` exit codes are shell-loop-friendly: `0` when the CDN serves the gateway's expected SHA, `1` otherwise. So `until run402 assets diagnose <url>; do sleep 1; done` blocks until the CDN catches up. Vantage: probes are single-region (us-east-1); the `# probed once from gateway-us-east-1; not a global view` line on stderr is the explicit caveat.

#### Uploading from Node/agent code

```javascript
import { run402, dir } from "@run402/sdk/node";

const client = run402();

// Single key — bytes/string source.
const asset = await client.assets.put(projectId, "uploads/report.pdf", { bytes });
// asset.cdnUrl is the preferred content-addressed URL for public blobs.

// Whole directory in one apply (atomic with site/functions/secrets if combined).
const manifest = await client.assets.uploadDir("./assets", {
  project: projectId,
  prefix: "static/",
});
console.log(manifest.byKey["static/logo.png"].cdn_url);

// Or as part of a release apply (assets promote inside the same activation
// transaction that flips live_release_id).
await client.deploy.apply({
  project: projectId,
  assets: { put: [{ key: "static/logo.png", source: bytes }] },
  site: dir("./dist"),
});
```

### sites
- `run402 sites deploy --manifest <file> [--project <id>]`
- `run402 sites deploy-dir <path> [--project <id>] [--quiet] [--dry-run] [--confirm-prune]`

`--project` defaults to the active project. Manifest: `{"files":[{"file":"index.html","data":"..."},{"file":"style.css","data":"..."}]}`. Must include `index.html`. Free with active tier. If the project already has a subdomain, redeploying auto-reassigns it to the new deployment (response includes `subdomain_urls`).

To inspect deploy status, use `run402 deploy events <operation_id>` or `run402 deploy list --project <id>` instead of polling a deployment artifact.

CAS-backed transport: Both `sites deploy` and `sites deploy-dir` hash each file locally and only PUT bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`.

Dry-run: `run402 sites deploy-dir ./dist --project prj_... --dry-run` calls the gateway's `POST /apply/v1/plans?dry_run=true`, prints `{status:"ok", dry_run:true, plan_id:null, operation_id:null, manifest_digest, diff, warnings, expected_events, missing_content_count}`, and exits without uploading bytes or committing a release. Use it to preview the server-authoritative plan/diff envelope.

Progress events: `sites deploy` and `sites deploy-dir` stream unified `DeployEvent` JSON lines to stderr by default; the final result payload (release/deployment metadata, no `status` wrapper) still goes to stdout. Pipe streams separately: `run402 sites deploy-dir ./dist --project p > result.json 2> events.log`. Pass `--quiet` to suppress events (stdout still gets the result payload).

### subdomains
- `run402 subdomains claim <name> [--deployment <id>] [--project <id>]`
- `run402 subdomains list [--project <id>]`
- `run402 subdomains delete <name> --confirm [--project <id>]` — `--confirm` required (irreversible release).

All options default to the active project. `claim` also defaults to the project's last deployment. Names: 3-63 chars, lowercase alphanumeric + hyphens. Creates `<name>.run402.com`.

Subdomain auto-reassignment: You only need to `claim` a subdomain once. Every subsequent `run402 sites deploy` or `run402 deploy` to the same project automatically updates the subdomain to point to the new deployment. The response includes `subdomain_urls` showing which subdomains were reassigned. No need to re-claim after each deploy.

### domains
- `run402 domains add <domain> <subdomain_name> [--project <id>]`
- `run402 domains list [--project <id>]`
- `run402 domains status <domain> [--project <id>]`
- `run402 domains delete <domain> --confirm [--project <id>]` — `--confirm` required (irreversible release).

Point a custom domain (e.g. `example.com`) at a Run402 subdomain. The human must already own the domain.

**Setup flow:**
1. `run402 domains add example.com myapp` — registers the domain, returns DNS instructions
2. Human configures DNS at their registrar (CNAME to `domains.run402.com`, or ALIAS + TXT for apex domains)
3. `run402 domains status example.com` — poll until status is `active` (DNS propagation ~60s)
4. Traffic to `example.com` now serves the same site as `myapp.run402.com`

When the linked subdomain is redeployed, the custom domain automatically serves the new deployment.

### apps
- `run402 apps browse [--tag <tag>]`
- `run402 apps fork <version_id> <name> [--subdomain <name>] [--bootstrap '<json>']`
- `run402 apps inspect <version_id>`
- `run402 apps publish <id> [--description "..."] [--tags a,b] [--visibility <public|private>] [--fork-allowed]`
- `run402 apps <versions|delete> <id> [<version_id>]`
- `run402 apps update <id> <version_id> [--description "..."] [--tags a,b]`

Forking clones schema, site, and functions into a new project. If the app includes a `bootstrap` function, it runs automatically with the provided variables — use it for first-admin setup, demo data seeding, or app configuration. Response includes `bootstrap_result` (the function's return value) or `bootstrap_error` if it failed. Use `run402 apps inspect` to see what `bootstrap_variables` an app expects.

### image
$0.03 per image.

- `run402 image generate "<prompt>" [--aspect <square|landscape|portrait>] [--output <file>]`

Without `--output`, returns `{"aspect":"...","content_type":"image/png","image":"<base64>"}`.

### ai
Built-in AI helpers. Translation requires the AI Translation add-on on the project. Moderation is free for all projects.

- `run402 ai translate <id> "<text>" --to <lang> [--from <lang>] [--context "<hint>"]` — translate text to a target language (ISO 639-1 codes). Source language auto-detected if `--from` omitted. Context hint guides tone/register (max 200 chars).
- `run402 ai moderate <id> "<text>"` — run content moderation. Returns flagged status and per-category scores.
- `run402 ai usage <id>` — check translation word quota for the current billing period (used, included, remaining).

### email
Up to 5 mailboxes per project (flat across tiers). When a project has more than one mailbox, pass `--mailbox <slug|id>` to pick which one (slug or `mbx_…` id); omitting it on a multi-mailbox project returns an ambiguity error naming the available slugs. Two send modes: template (predefined templates) and raw HTML (arbitrary subject + HTML body). Single recipient per send. Rate limits by tier: prototype 10/day, hobby 50/day, team 500/day. Unique recipient cap per lease: prototype 25, hobby 200, team 1000.

Templates: `project_invite` (project_name, invite_url), `magic_link` (project_name, link_url, expires_in), `notification` (project_name, message max 500 chars).

- `run402 email create <slug> [--project <id>]` — create mailbox at `<slug>@mail.run402.com`. NOT idempotent: a conflict (slug already in use, address in cooldown, or the project already has 5 mailboxes) returns a 409 error rather than an existing mailbox.
- `run402 email status [--mailbox <slug|id>] [--project <id>]` — show mailbox info (ID, address, slug)
- `run402 email send --template <name> --to <email> [--var key=value ...] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
- `run402 email send --to <email> --subject <subject> --html <html> [--text <text>] [--attach <path>[:content-type] ...] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
- `run402 email list [--direction <inbound|outbound>] [--mailbox <slug|id>] [--project <id>]` — lists BOTH sent + received by default; `--direction inbound` lists received replies (the reconciliation backstop if a reply_received webhook is lost)
- `run402 email get <message_id> [--mailbox <slug|id>] [--project <id>]`
- `run402 email reply <message_id> --html <html> [--text <text>] [--subject <subject>] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]` — reply to an inbound message (threads via In-Reply-To)
- `run402 email get-raw <message_id> --output <file> [--mailbox <slug|id>] [--project <id>]` — fetch raw RFC-822 bytes of an inbound message (for DKIM/zk-email verification). `--output` is required: bytes are written to the file; stdout receives a JSON envelope `{ message_id, bytes, output }` so the CLI stays pipeable. Inbound only; outbound returns 404.
- `run402 email delete [<slug|mailbox_id>] --confirm [--project <id>]` — delete a mailbox (irreversible). Target a specific mailbox by slug or id; on a project with one mailbox the target may be omitted.
- `run402 email webhooks list [--mailbox <slug|id>] [--project <id>]` — list all webhooks registered on the mailbox
- `run402 email webhooks get <webhook_id> [--mailbox <slug|id>] [--project <id>]` — get webhook details
- `run402 email webhooks delete <webhook_id> [--mailbox <slug|id>] [--project <id>]` — delete a webhook
- `run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>] [--project <id>]` — update webhook URL and/or events
- `run402 email webhooks register --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]` — register a new webhook. Valid events: delivery, bounced, complained, reply_received
- `run402 email webhooks deliveries [--status <pending|in_flight|delivered|failed_permanent>] [--mailbox <slug|id>] [--project <id>]` — list durable delivery rows. Delivery is at-least-once with bounded retries + backoff; `failed_permanent` is the dead-letter queue. The delivered body is the canonical envelope `{ id, type, created_at, schema_version, idempotency_key, payload }` — consumers MUST dedupe on `idempotency_key`.
- `run402 email webhooks redrive <delivery_id> [--mailbox <slug|id>] [--project <id>]` — re-queue a dead-lettered (failed_permanent) delivery for another attempt

Raw HTML: `--subject` (max 998 chars) + `--html` (max 1MB). Plaintext auto-generated from HTML if `--text` omitted. `--attach <path>[:content-type]` attaches a file (raw HTML mode only; repeatable, max 5, ≤ 7 MB total; content-type inferred from the extension when the suffix is omitted). `--from-name` sets display name on From header (both modes): `"My App" <slug@mail.run402.com>`.

Slug rules: 3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens. `--project` defaults to the active project.

Using email from functions: Import `email` from `@run402/functions` — no need to manage mailbox IDs or service keys manually:
```js
import { email } from '@run402/functions';

// Template mode
await email.send({ to: "user@example.com", template: "notification", variables: { project_name: "My App", message: "Hello!" } });

// Raw HTML mode
await email.send({ to: "user@example.com", subject: "Welcome!", html: "<h1>Hi</h1>", from_name: "My App" });
```
Discovers the mailbox automatically. Throws on errors (rate limit, suppression, no mailbox).

### auth
Manage project user authentication: magic links, trusted invites, passwords, passkeys, and auth settings.

- `run402 auth magic-link --email <addr> --redirect <url> [--intent signin|invite|claim|recovery] [--state <value>] [--project <id>]` — send a magic link email
- `run402 auth verify --token <token> [--project <id>]` — exchange a magic link token for access_token + refresh_token
- `run402 auth create-user --email <addr> [--admin <true|false>] [--invite] [--redirect <url>] [--project <id>]` — service-key create/update auth user
- `run402 auth invite-user --email <addr> --redirect <url> [--admin <true|false>] [--project <id>]` — create/update user and send trusted invite
- `run402 auth set-password --token <bearer> --new <password> [--current <password>]` — change, reset, or set password
- `run402 auth settings [--allow-password-set <true|false>] [--preferred <method|null>] [--public-signup <policy>] [--require-admin-passkey <true|false>] [--allowed-email-domains <csv|none>] [--project <id>]` — update auth settings (requires service_key). `--allowed-email-domains` is a comma-separated list restricting hosted Google sign-in to those domains (enforced at token issuance); `none` clears it; empty = unrestricted.
- `run402 auth passkey-register-options --token <bearer> --app-origin <origin> [--project <id>]` — create WebAuthn registration options
- `run402 auth passkey-register-verify --token <bearer> --challenge <id> --response <json> [--label <text>] [--project <id>]` — verify and store passkey registration
- `run402 auth passkey-login-options --app-origin <origin> [--email <addr>] [--project <id>]` — create WebAuthn login options
- `run402 auth passkey-login-verify --challenge <id> --response <json> [--project <id>]` — verify passkey login and return session tokens
- `run402 auth passkeys --token <bearer> [--project <id>]` — list authenticated user's passkeys
- `run402 auth delete-passkey --token <bearer> --id <passkey_id> [--project <id>]` — delete one passkey
- `run402 auth providers [--project <id>]` — list available auth providers
- `run402 auth scaffold-roles [--table <name>] [--user-col <col>] [--role-col <col>] [--roles <csv>] [--cache-ttl <secs>]` — offline generator: emits a role-table migration + `requireRole` gate snippet + first-operator bootstrap (JSON out; no project/network). Pipe through `jq` (e.g. `| jq -r .migration`).

Magic link flow: request → user clicks email link → frontend extracts token → verify → authenticated. Token expires in 15 minutes, single-use. Rate limited: 5 per email/hour, plus per-project limits by tier.

### sender-domain
Manage custom email sender domain. Send from your own brand instead of `@mail.run402.com`.

- `run402 sender-domain register <domain> [--project <id>]` — register domain, returns DNS records to add
- `run402 sender-domain status [--project <id>]` — check verification status (pending/verified)
- `run402 sender-domain remove [--project <id>]` — remove custom domain, revert to mail.run402.com
- `run402 sender-domain inbound-enable <domain> [--project <id>]` — enable inbound email on custom domain (requires DKIM-verified), returns MX record to add
- `run402 sender-domain inbound-disable <domain> [--project <id>]` — disable inbound email on custom domain

Flow: register → add DKIM CNAME records to DNS → poll status until verified → email auto-sends from your domain.
Inbound (opt-in): inbound-enable → add MX record to DNS → replies to `<slug>@<your-domain>` route through run402.

### billing
Email-based billing accounts, Stripe tier checkout, and email packs. Pay run402 with credit cards instead of crypto, or scale email sending beyond tier caps.

- `run402 billing create-email <email>` — create an email-based billing account (Stripe-only, no wallet). Sends a verification email. Idempotent.
- `run402 billing link-wallet <account_id> <wallet>` — link a wallet to an email account for hybrid Stripe + x402 access. Response includes a `pool_implications` block (account `tier`, `projects_in_pool_count`, `account_api_calls_current`, `account_storage_bytes_current`, `tier_limits`, `over_limit`) — inspect `over_limit` before linking a wallet whose usage might push the merged pool past the tier cap.
- `run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]` — subscribe/renew/upgrade a tier (prototype $0.10 / hobby $5 / team $20) via Stripe. Returns a checkout URL.
- `run402 billing buy-email-pack [--email <e> | --wallet <w>]` — buy a $5 email pack (10,000 emails, never expire). Returns a Stripe checkout URL.
- `run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]` — auto-repurchase $5 packs when credits drop below threshold. Requires saved Stripe payment method.
- `run402 billing balance <account-id | wallet | email>` — balance + email_credits_remaining + tier + lease + auto_recharge state (response includes `billing_account_id`). A wallet/email is resolved to its account via `GET /billing/v1/accounts?wallet=|?email=`; an account id (UUID) reads `GET /billing/v1/accounts/:account_id` directly.
- `run402 billing history <account-id | wallet | email> [--limit <n>]` — ledger history. Keyed by account id: a wallet/email is resolved to its `billing_account_id` first, then `GET /billing/v1/accounts/:account_id/history`.

Auth: account reads (`balance`, `history`) require SIWX from a wallet **linked to** the account (membership), or an admin key; the wallet→account lookup requires SIWX matching the queried wallet (email lookups are admin-only). `link-wallet` requires the body wallet's SIWX (or admin); `auto-recharge` a linked wallet's SIWX. The CLI signs automatically from the local allowance, so these only work when the agent's allowance wallet is on the account being queried/linked/billed. A non-member (or someone guessing an account id) gets 403 with no existence leak. Checkout-creation commands (`create-email`, `tier-checkout`, `buy-email-pack`) remain unauthenticated.

Email packs only activate when the tier daily limit is exhausted AND the project has a verified custom sender domain (spam protection for `mail.run402.com`).

### contracts
KMS contract wallets — provision AWS KMS-backed Ethereum wallets per project for signing and broadcasting smart-contract transactions. Private keys never leave KMS. **Pricing: $0.04/day rental + $0.000005 per call**. Wallet creation requires $1.20 in cash credit (30 days of rent). Non-custodial — see https://run402.com/humans/terms.html#non-custodial-kms-wallets.

- `run402 contracts provision-wallet --chain <base-mainnet|base-sepolia> [--recovery-address 0x...]` — provision a KMS wallet ($0.04/day rental, requires $1.20 in cash credit at creation). Prompts for confirmation if the project already has ≥1 active wallet.
- `run402 contracts get-wallet <wallet_id>` — get wallet metadata + live native balance + USD value (free)
- `run402 contracts list-wallets` — list all wallets owned by the project, including deleted ones (free)
- `run402 contracts set-recovery <wallet_id> [--address 0x... | --clear]` — set/clear the optional recovery address used for auto-drain on day-90 deletion (free)
- `run402 contracts set-alert <wallet_id> --threshold-wei <n>` — set the low-balance alert threshold (free; alerts billed via existing email infra)
- `run402 contracts call --wallet <id> --to 0x... --abi <json> --fn <name> --args <json> [--value-wei <n>] [--idempotency-key <k>]` — submit a contract write call (gas at-cost + $0.000005 KMS sign fee). Returns `{ call_id, tx_hash, status }`.
- `run402 contracts deploy <project_id> <wallet_id> --bytecode 0x... [--chain <base-mainnet|base-sepolia>] [--value-wei <n>] [--idempotency-key <k>]` — deploy a contract from the KMS wallet (gas at-cost + $0.000005 KMS sign fee). `--bytecode` is the full creation calldata (creation bytecode + ABI-encoded constructor args, concatenated client-side via viem/ethers; ≤ 128 KB). Returns `{ call_id, tx_hash, status, contract_address }` — the deterministic CREATE address is known synchronously. run402 does NOT compile Solidity.
- `run402 contracts read --chain <chain> --to 0x... --abi <json> --fn <name> --args <json>` — read-only contract call (free, no signing, no billing)
- `run402 contracts status <call_id>` — get call status, gas used, gas cost USD-micros, receipt, error (free)
- `run402 contracts drain <wallet_id> --to 0x... --confirm` — drain native balance to a destination address (gas at-cost + $0.000005 KMS sign fee). Works on suspended wallets — the safety valve.
- `run402 contracts delete <wallet_id> --confirm` — schedule the KMS key for deletion (7-day window). Refused if balance ≥ dust — drain first.

### message
- `run402 message send "<text>"`

### agent
- `run402 agent contact --name <name> [--email <email>] [--webhook <url>]`
- `run402 agent status`
- `run402 agent verify-email`
- `run402 agent passkey enroll`

`contact` returns `email_verification_status`, `passkey_binding_status`, and `assurance_level`. New or changed emails start a reply challenge and stay `email_pending` until the mailbox owner replies. `passkey enroll` requires `email_verified` and emails the enrollment link to the verified contact email; the token is not printed.

### operator
The **operator** is YOU, the human, identified by email — distinct from the **agent** (your wallet / SIWX identity). One browser login spans every wallet that verified your email, so `operator overview` returns the cross-wallet union. For a single wallet's account state, use `run402 status` (that IS the wallet's view; there is no `operator status`).

- `run402 operator login [--no-open]` — browser-delegated sign-in for the **read** session (device-authorization, RFC 8628, the `aws sso login` model). Prints a verification URL + short user code to stderr and (on a TTY) opens the browser; you approve via the existing magic-link OR passkey web flow. Polls until approved, then caches the session at `{base}/operator-session.json` (0600, base config dir — shared across named wallets). Stdout JSON on success: `{ logged_in, email, wallets, wallet_count, expires_at, absolute_expires_at, expires_in_seconds }`.
- `run402 operator login --loopback [--no-open]` / `run402 operator login --step-up` — the **write-capable** control-plane login (loopback-PKCE, RFC 8252). Starts a `127.0.0.1` server, opens the browser to the passkey ceremony on run402's origin, and on approval mints a passkey-fresh, write-capable session (`provenance=loopback_pkce`) cached at `{base}/control-plane-session.json` (0600; stdout is metadata-only — the token is never printed). `--step-up` re-mints a fresh session to satisfy a `STEP_UP_REQUIRED` challenge on this same client. `operator whoami` surfaces it and `operator logout` clears it. Stdout also includes `memberships[]` — the orgs you belong to, including any **invites auto-claimed by this login** (best-effort; omitted if the post-login lookup fails). The browser-interactive hosted logins (email magic-link / passkey / Google / GitHub) are console-side and exposed in the SDK (`r.operator.session.*`), not the CLI — the loopback flow above delegates the whole browser ceremony, so the CLI never needs them.
- `run402 operator overview` — account view across ALL wallets controlling your email. Sends the cached operator-session bearer to `GET /agent/v1/operator/overview`. **Requires login** — returns `OPERATOR_LOGIN_REQUIRED` (no SIWX fallback) when there is no live session, and clears the cache + returns `OPERATOR_SESSION_INVALID` on a 401/403 (revoked or expired).
- `run402 operator whoami` — local, no network. Prints the cached session (`logged_in`, email, wallets, expiry) or `{ logged_in: false, reason: "no_session" | "expired" }` with a non-zero exit.
- `run402 operator logout` — revokes the session server-side (`POST /agent/v1/operator/session/revoke`) then clears the local cache. Idempotent; best-effort revoke (always clears locally). Stdout: `{ revoked, cleared }`.
- `run402 operator claim-wallet-org [--org <id>] [--name <label>]` — claim an org owned by your wallet's `agent` principal INTO your human (console) identity — an ownership transfer (v1.82). The wallet authenticator stays on the agent (no authority amplification); the agent is downgraded owner→developer. Dual proof: a **write-capable control-plane session** (`operator login --loopback` first) AND a fresh wallet signature over a server nonce from the active wallet. Runs challenge → sign → submit. Success → `{ claimed: true, org_id, display_name, role, already_owned }`. If your wallet's agent owns more than one org → `{ claimed: false, selectable_orgs: [{ org_id, display_name, tier }] }`; re-run with `--org <id>` (the server reuses the same nonce/proof). A stale session returns `STEP_UP_REQUIRED` — run `operator login --step-up`, then retry. `--name` optionally labels the claimed org.

The session is email-scoped (~30m access TTL, ~12h absolute cap), so it is cached once at the base dir and reused regardless of the active `--wallet`. Login/overview/logout require the gateway device-authorization bridge (kychee-com/run402-private#443); `whoami` is local and works today. Not exposed as MCP tools by design — MCP authenticates as the agent (wallet), and the human session must not be handed to the agent.

### service
Public service-level status. No allowance, no auth, no keystore required — works on a fresh install. Reports on the Run402 service (uptime, capabilities, operator); for your account state use `run402 status`.
- `run402 service status` — public availability report (24h/7d/30d uptime per capability, operator, deployment, schema `run402-status-v1`)
- `run402 service health` — liveness check with per-dependency results (postgres, postgrest, s3, cloudfront) and service version

### cache
SSR origin-cache inspection + invalidation. Capability `ssr-isr-cache` (gateway v1.52+, paired with `@run402/astro` v1.0+). Cache is scoped per-project; cross-project hosts return `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`.

- `run402 cache inspect <url> [--locale <code>] [--release-id <id>]` — read the cache row state for a URL. Stdout is JSON: `{ status: "HIT" | "MISS", host, path, locale, releaseId, cachedAt, expiresAt, writtenUnderGeneration, contentSha256, headers }`. `status` is NEVER `BYPASS` — inspect does not issue a request, so it cannot evaluate runtime bypass conditions. Defaults to active release + default locale; pass `--locale` / `--release-id` to inspect non-default rows. (The legacy `--json` flag is removed — JSON is the default.)
- `run402 cache invalidate <url>` — invalidate a single absolute URL. Stdout: `{ deleted, host, path, generation }`.
- `run402 cache invalidate --prefix <p> --host <h>` — invalidate all rows under a path prefix on a specific host.
- `run402 cache invalidate --all --host <h>` — entire-host purge (catastrophic content changes; nav restructure; layout-wide updates).

Every invalidate returns `{ deleted, generation, host, path? }`. `generation` is the post-increment per-(project, host) counter — it gates in-flight MISS renders from overwriting after invalidation completed.

### doctor
Health + config diagnostics. Agent-DX entrypoint — agents run this first to verify environment before attempting anything else.

- `run402 doctor [--verbose] [--no-scan] [--scan-dir <D>]` — checks: config dir presence, allowance + rail, keystore wallet count, API base reachability, active tier + lifecycle state, operator health snapshot (binding state + per-attempt verification failure detail since v2.4 / gateway v1.56), **source scan** (auth-aware-ssr). Exit 0 on all-pass, 1 on any failure. Stdout is JSON `{ ok: boolean, checks: [{ name, status, value?, hint?, message? }] }`. When operator email verification is `pending`, the doctor surfaces the per-reason hint from `email_verification.last_challenge.hint` along with `attempt_count` / `remaining_attempts` so the operator sees what to fix. The source scan walks `<cwd>/src` and flags hallucinated SDK auth names (`R402_AUTH_UNKNOWN_EXPORT`), state-changing GET handlers (`R402_AUTH_STATE_CHANGING_GET`), `auth.*` calls in `export const prerender = true` pages (`R402_AUTH_PRERENDERED`), and direct mutation of `internal.sessions.authz_version` (`R402_AUTH_AUTHZ_VERSION_PROHIBITED`). `--no-scan` skips the scan (config-only checks). `--scan-dir <D>` overrides the scan root. `run402 deploy apply` runs the scan as pre-flight and refuses to deploy on any `error`-severity finding (bypass with `RUN402_DEPLOY_SKIP_SCAN=1`). (The legacy `--json` flag is removed — JSON is the default.)

### dev
Astro dev wrapper. Loads `.env.local`, verifies `RUN402_PROJECT_ID` + `RUN402_SERVICE_KEY`, then spawns `astro dev` with the env inherited.

- `run402 dev [--port <n>] [--host <h>] [--project <id>]`

SDK calls (`db`, `getUser`, `cache.invalidate`, `assets.put`) hit the LIVE Run402 project at `https://api.run402.com` — no local DB/S3/KMS setup required. This is shape-parity with production. Offline emulator mode is deferred to v1.5.

### init astro
Project scaffolder. Subroute of `init` (alongside `init` rail setup).

- `run402 init astro [<dir>] [--force]` — creates a deployable Astro project with `package.json` (dev/deploy scripts), `astro.config.mjs` (one-line `@run402/astro` preset), `src/pages/{index,[slug]}.astro` (the latter demonstrates the full DB-backed dynamic page pattern with cache directive), `src/layouts/Layout.astro` (title + og + canonical), `src/pages/api/save-page.ts` (admin save endpoint with `db().upsert() → cache.invalidate()`), `.env.example`, `.gitignore`. Refuses non-empty dirs without `--force`. Stdout is JSON `{ dir, files_created, created, next_steps }`; progress lines go to stderr. (The legacy `--json` flag is removed — JSON is the default.)

### logs
Fetch function logs by request id. Top-level shortcut — for fine-grained per-function control, `run402 functions logs <project> <name>` still works.

- `run402 logs --request-id <req_...> [--function <name>] [--project <id>] [--tail <n>]` — stdout is JSON `{ ok, request_id, project_id, scanned, entries, errors? }`. (The legacy `--json` flag is removed — JSON is the default.)

When an SSR response returns a 5xx, the response headers include `x-run402-error-code: R402_SSR_RUNTIME_ERROR` and `x-run402-request-id: req_...`. Copy the request id and run `run402 logs --request-id req_...` to fetch the full stack trace. Scans every function in the project in parallel and aggregates entries timestamp-ascending unless `--function` narrows the scope.

---
## R402_* SSR Runtime Error Codes (cache + Astro adapter, gateway v1.52+)

Stable error codes for the Astro SSR runtime. Each carries `code`, `message`, `suggestedFix`, `docs`, and (when statically determinable) `file`, `line`. Codes are protocol-stable and emitted as the exact uppercase string in JSON envelopes, response headers, logs, and CLI output.

**Build / deploy:**

- `R402_ASTRO_BUILD_FAILED` — Astro's own compiler threw an unrecovered error. Suggested fix: read the build log + address the underlying compiler error.
- `R402_ASTRO_UNSUPPORTED_OUTPUT` — `output: '...'` is not supported. Use `output: 'server'` (default) and opt-in per route via `export const prerender = true;`.
- `R402_ASTRO_MIDDLEWARE_UNSUPPORTED` — middleware ran but a specific pattern hit a snag. Move auth-gating to page frontmatter or API endpoints.
- `R402_ASTRO_SERVER_ISLAND_UNSUPPORTED` — `server:defer` / `server:only` detected. Use client islands (`client:load`, `client:idle`, `client:visible`) instead; server islands deferred to v1.5.
- `R402_ASTRO_SESSIONS_UNSUPPORTED` — `Astro.session.*` or `experimental.session` detected. Use signed cookies via `Astro.cookies` or DB-backed sessions.
- `R402_ASTRO_DYNAMIC_IMAGE_UNSUPPORTED` — `<Image src={expr}>` where `expr` is a runtime value (DB row, function call, env var). Use `<Run402Picture asset={page.hero_asset}>` for CMS images; static-import binding `<Image src={hero}>` is allowed.
- `R402_ASTRO_VERSION_UNSUPPORTED` — installed Astro outside the adapter's pinned peer range.
- `R402_BUNDLE_UNRESOLVED_IMPORT` — bundler couldn't resolve a function-file import. Check package presence in `dependencies`.
- `R402_BUNDLE_NATIVE_DEP_UNSUPPORTED` — bundle contains native binary deps (`sharp`, `better-sqlite3`, etc.). Replace with Run402 primitives (`r.assets.put` for image processing, `r.ai.*` for ML).

**Runtime / SnapStart:**

- `R402_SNAPSTART_INIT_IO` — module-scope IO detected during SnapStart snapshot capture. Move SDK calls inside the request handler.
- `R402_SDK_OUTSIDE_REQUEST_CONTEXT` — SDK function called outside an active request context (module scope or post-response timer). Move into handler scope.
- `R402_SSR_RUNTIME_ERROR` — uncaught exception during render. The public response carries `requestId` + `releaseId` (no stack trace); full stack via `run402 logs --request-id <req>`.

**Cache layer:**

- `R402_CACHE_UNSUPPORTED_VARY` — response `Vary` references something other than `Accept-Language`. Bypass header emitted; response delivered normally but not cached.
- `R402_CACHE_AUTH_TAINTED` — informational diagnostic (not an `ok: false` error). Emitted via `x-run402-cache-reason: auth` when render called `auth.user()` (or any other `auth.*` helper) or a payment primitive. This is the expected uncacheable-by-design behavior.

**Auth-aware SSR (auth-aware-ssr, v3.0):**

22 codes covering the browser-session / actor-context / hosted-UI / SDK surface. See run402.com/llms-full.txt for the full table with per-code fix-it hints. Highlights:

- `R402_AUTH_REQUIRED` — 401 (JSON) / 303 → `/auth/sign-in?returnTo=` (HTML). Auth helper called from an anonymous request.
- `R402_AUTH_INSUFFICIENT_ROLE` / `R402_AUTH_INSUFFICIENT_MEMBERSHIP` — 403. Authenticated user lacks the named grant; platform does NOT redirect to sign-in (the user IS signed in).
- `R402_AUTH_FRESHNESS_REQUIRED` — 401 / 303 → `/auth/re-auth`. Per-AMR step-up needed.
- `R402_AUTH_SESSION_EXPIRED` / `R402_AUTH_SESSION_INVALID` — cookie cleared on response; user re-signs-in.
- `R402_AUTH_CSRF_ORIGIN_MISMATCH` — 403. Cookie-authenticated unsafe-method request with mismatched / missing Origin and Referer.
- `R402_AUTH_CSRF_TOKEN_MISMATCH` — 403. Hosted-auth form missing or mismatching the platform CSRF token.
- `R402_AUTH_BEARER_COOKIE_MISMATCH` / `R402_AUTH_INVALID_BEARER` — 400 / 401. Cookie + Bearer disagree, or valid cookie + malformed Bearer.
- `R402_AUTH_UNKNOWN_EXPORT` — 500. Hallucinated SDK name (`getUser`, `getSession`, `auth.protect`, …). `details.canonical_name` carries the replacement.
- `R402_AUTH_PRERENDERED` — 500. `auth.*` called from a prerendered page. Convert to SSR or use a server island.
- `R402_AUTH_FETCH_ABSOLUTE_URL` — 500. `auth.fetch` rejected a cross-origin / embedded-creds / javascript:/data: / protocol-relative / subdomain-spoof / port-mismatch URL.
- `R402_AUTH_RETURN_TO_INVALID` — 400. Hosted-auth route got a `returnTo` that's not path-relative or same-origin absolute.
- `R402_AUTH_IDENTITY_LINK_CONFLICT` — 409. `(project_id, provider, subject)` already linked to another user.
- `R402_AUTH_SESSION_BRIDGE_UNVERIFIED` — 401. Custom identity proof failed verification, OR consumer accessed the internal-only session-creation primitive.
- `R402_AUTH_UNKNOWN_IDENTITY` — 401. `createResponseFromIdentity` couldn't resolve identity AND `createUser: true` not set.
- `R402_AUTH_DOMAIN_NOT_ALLOWED` — 403. Hosted Google sign-in rejected at token issuance: the verified email's domain isn't in the project's `allowed_email_domains` (or the email is unverified). Set/clear the allowlist with `run402 auth settings --allowed-email-domains <csv|none>`. Empty allowlist = unrestricted.
- `R402_AUTH_TENANT_SUFFIX_REQUIRED` — gateway refuses session cookies on `*.run402.com` for non-allowlisted projects. PSL-registered `*.run402.app` + verified custom domains are always allowed.
- `R402_AUTH_ACTOR_HEADER_SPOOF` — client-supplied reserved actor header was stripped at ingress; diagnostic only.
- `R402_AUTH_REDUNDANT_USER_FILTER` — deploy-fail (or runtime warn). `.eq("user_id", user.id)` against an RLS-bound table. Add `// run402-allow-user-filter: <reason>` if intentional.
- `R402_AUTH_AUTHZ_VERSION_PROHIBITED` — deploy-fail. Consumer migration mutates `internal.sessions.authz_version` directly.
- `R402_CACHE_INVALIDATION_HOST_REQUIRED` — `cache.invalidate('/path')` called outside a request context. Use absolute URL form OR move into a request handler.
- `R402_CACHE_INVALIDATION_HOST_FORBIDDEN` — cross-project host. Use a host attached to your project (`run402 domains list`).

**Deploy:**

- `R402_DEPLOY_STAGE_FAILED` — apply-v1 state machine failure at a specific stage (`validate` / `stage` / `migrate` / `schema_settling` / `activating` / `snapstart_validate`).

---
## REST API (for generated frontend code)

The CLI's `run402 projects rest` command is great for terminal use. But when generating HTML/JS that runs in the browser, use the REST API directly:

Base URL: `https://api.run402.com/rest/v1/{table}`

Auth header: `apikey: {key}` — the gateway auto-forwards as `Authorization: Bearer` to PostgREST. Any valid project JWT works:
- `anon_key` → read-only by default (SELECT). Safe to embed in frontend code. No expiry -- permanent project identifier. If you apply `public_read_write_UNRESTRICTED` RLS to a table, anon_key gains INSERT/UPDATE/DELETE on that table — use this for browser-side writes without login (only on intentionally public tables).
- `service_key` → full admin (bypasses RLS). Server-side only. No expiry -- lease enforcement server-side.
- `access_token` (from login) → user-scoped read/write (subject to RLS).

For explicit control, send both `apikey` (project key) and `Authorization: Bearer <access_token>`.

CORS: The API allows all origins (`Access-Control-Allow-Origin: *`). Browser `fetch()` calls work from any domain -- no proxy needed.

PostgREST query syntax: `?select=col1,col2`, `?column=eq.value`, `?order=col.desc`, `?limit=N`, `?offset=N`

`Prefer` header (controls write responses):
- `Prefer: return=representation` → return the inserted/updated row(s) as JSON. Use this to get server-generated fields (`id`, `created_at`) without a second query.
- `Prefer: return=minimal` → empty body (default). Faster when you don't need the result.

Frontend fetch examples:

```javascript
const API = 'https://api.run402.com';
const ANON_KEY = 'your_anon_key';  // from run402 projects list

// Read rows (public, uses anon_key)
const items = await fetch(API + '/rest/v1/items?select=id,title&done=eq.false&order=id.desc&limit=20', {
  headers: { apikey: ANON_KEY }
}).then(r => r.json());

// Insert a row and get it back (Prefer: return=representation returns the new row with id, created_at, etc.)
const [newItem] = await fetch(API + '/rest/v1/items', {
  method: 'POST',
  headers: { apikey: ANON_KEY, 'Content-Type': 'application/json', Prefer: 'return=representation' },
  body: JSON.stringify({ title: 'New item', done: false })
}).then(r => r.json());

// Bulk insert — pass an array body
const newItems = await fetch(API + '/rest/v1/items', {
  method: 'POST',
  headers: { apikey: ANON_KEY, 'Content-Type': 'application/json', Prefer: 'return=representation' },
  body: JSON.stringify([{ title: 'Item A', done: false }, { title: 'Item B', done: false }])
}).then(r => r.json());

// Update rows matching a filter
await fetch(API + '/rest/v1/items?id=eq.5', {
  method: 'PATCH',
  headers: { apikey: ANON_KEY, 'Content-Type': 'application/json', Prefer: 'return=representation' },
  body: JSON.stringify({ done: true })
}).then(r => r.json());

// Delete rows matching a filter
await fetch(API + '/rest/v1/items?id=eq.5', {
  method: 'DELETE',
  headers: { apikey: ANON_KEY }
});
```

### Complete HTML example

A working single-file app. Uses `public_read_write_UNRESTRICTED` RLS so the `anon_key` handles all reads and writes — no login required. (This template is intentionally open; only apply it to tables where anyone on the internet is allowed to write anything, like guestbooks.)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Guestbook</title>
  <style>
    body { font-family: system-ui; max-width: 480px; margin: 2rem auto; padding: 0 1rem; }
    .entry { border-bottom: 1px solid #eee; padding: 0.5rem 0; }
    .entry .name { font-weight: bold; }
    .entry .time { color: #888; font-size: 0.85em; }
    form { display: flex; gap: 0.5rem; margin-bottom: 1.5rem; }
    input { flex: 1; padding: 0.4rem; }
    button { padding: 0.4rem 1rem; }
  </style>
</head>
<body>
  <h1>Guestbook</h1>
  <form id="form">
    <input name="name" placeholder="Your name" required>
    <input name="message" placeholder="Say something..." required>
    <button type="submit">Post</button>
  </form>
  <div id="entries"></div>

  <script>
    const API = 'https://api.run402.com';
    const ANON_KEY = 'YOUR_ANON_KEY';  // safe to embed — read-only by default, write-enabled here via public_read_write_UNRESTRICTED RLS

    async function loadEntries() {
      const rows = await fetch(API + '/rest/v1/guestbook?order=created_at.desc&limit=50', {
        headers: { apikey: ANON_KEY }
      }).then(r => r.json());
      document.getElementById('entries').innerHTML = rows.map(r =>
        `<div class="entry"><span class="name">${esc(r.name)}</span> <span class="time">${new Date(r.created_at).toLocaleString()}</span><p>${esc(r.message)}</p></div>`
      ).join('');
    }

    document.getElementById('form').onsubmit = async (e) => {
      e.preventDefault();
      const fd = new FormData(e.target);
      await fetch(API + '/rest/v1/guestbook', {
        method: 'POST',
        headers: { apikey: ANON_KEY, 'Content-Type': 'application/json', Prefer: 'return=representation' },
        body: JSON.stringify({ name: fd.get('name'), message: fd.get('message') })
      });
      e.target.reset();
      loadEntries();
    };

    function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }

    loadEntries();
  </script>
</body>
</html>
```

Setup for this example (run once via CLI or service_key):
```bash
# Create table
run402 projects sql $PROJECT_ID "CREATE TABLE guestbook (id serial PRIMARY KEY, name text NOT NULL, message text NOT NULL, created_at timestamptz DEFAULT now())"

# Expose guestbook so anon_key can insert. Write manifest.json:
# {"version":"1",
#  "tables":[{"name":"guestbook","expose":true,"policy":"public_read_write_UNRESTRICTED","i_understand_this_is_unrestricted":true}],
#  "views":[],"rpcs":[]}
run402 projects apply-expose $PROJECT_ID --file manifest.json
```

---
## User Auth (for apps with login)

Two auth methods: password (email + password) and Google OAuth (social login). Both return the same `access_token` + `refresh_token`. Google OAuth is on for all projects automatically — zero config.

### Password auth

```javascript
const API = 'https://api.run402.com';
const ANON_KEY = 'your_anon_key';

// Sign up
await fetch(API + '/auth/v1/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', apikey: ANON_KEY },
  body: JSON.stringify({ email: 'user@example.com', password: 'secret123' })
});

// Log in (returns access_token + refresh_token)
const session = await fetch(API + '/auth/v1/token?grant_type=password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', apikey: ANON_KEY },
  body: JSON.stringify({ email: 'user@example.com', password: 'secret123' })
}).then(r => r.json());
// session = { access_token, refresh_token, user: { id, email, ... } }
```

Signup does not return an access token. Call `/auth/v1/token` to log in. Returns `access_token` (1h JWT) and `refresh_token` (30d, one-time use).

### Google OAuth (recommended for user-facing apps)

Google sign-in is on for all projects with zero config. When a user signs in with Google, Run402 creates a project-scoped user with their Google name, email, and avatar.

Allowed redirect origins: `http://localhost:*` (any port) + any claimed subdomain (`https://{name}.run402.com`). No manual config needed.

Flow: Frontend generates PKCE verifier + challenge → calls `/auth/v1/oauth/google/start` → navigates to Google → user picks account → Google redirects back to your app with `#code=xxx&state=yyy` → frontend exchanges code for tokens.

Full JavaScript example:

```javascript
const API = 'https://api.run402.com';
const ANON_KEY = 'your_anon_key';

// --- PKCE helpers ---
function generateVerifier() {
  const arr = new Uint8Array(32);
  crypto.getRandomValues(arr);
  return btoa(String.fromCharCode(...arr))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}
async function generateChallenge(verifier) {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// --- Step 1: Start login (call on button click) ---
async function signInWithGoogle() {
  const verifier = generateVerifier();
  const challenge = await generateChallenge(verifier);
  localStorage.setItem('pkce_verifier', verifier);

  const res = await fetch(API + '/auth/v1/oauth/google/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', apikey: ANON_KEY },
    body: JSON.stringify({
      redirect_url: window.location.origin + '/',
      mode: 'redirect',
      code_challenge: challenge,
      code_challenge_method: 'S256',
    }),
  });
  const { authorization_url } = await res.json();
  window.location.href = authorization_url;  // navigate to Google
}

// --- Step 2: Handle callback (call on page load) ---
async function handleOAuthCallback() {
  const params = new URLSearchParams(window.location.hash.substring(1));
  const code = params.get('code');
  if (!code) return false;

  window.history.replaceState(null, '', window.location.pathname);
  const verifier = localStorage.getItem('pkce_verifier');
  localStorage.removeItem('pkce_verifier');

  const res = await fetch(API + '/auth/v1/token?grant_type=authorization_code', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', apikey: ANON_KEY },
    body: JSON.stringify({ code, code_verifier: verifier }),
  });
  const session = await res.json();
  // session = { access_token, refresh_token, user: { id, email, display_name, avatar_url, ... } }
  return session;
}
```

### Using access_token with the REST API

Once a user is logged in, use their `access_token` as the apikey to make user-scoped requests subject to RLS:

```javascript
// User-scoped read/write (subject to RLS policies)
const todos = await fetch(API + '/rest/v1/todos?order=id.desc', {
  headers: { apikey: ANON_KEY, Authorization: 'Bearer ' + session.access_token }
}).then(r => r.json());
```

### Token refresh

```javascript
const refreshed = await fetch(API + '/auth/v1/token?grant_type=refresh_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', apikey: ANON_KEY },
  body: JSON.stringify({ refresh_token: session.refresh_token })
}).then(r => r.json());
```

### Account behavior

- New Google user → new project user created (null password, Google name + avatar stored)
- Returning Google user → signed in to existing account
- Same email as existing password user → returns `account_exists_requires_link` error (no auto-merge for security)
- Social-only users cannot use password login (helpful error message returned)

### Useful endpoints

- `GET /auth/v1/providers` (with `apikey` header) — list available auth methods (password, google). Useful for dynamic login UIs.
- `GET /auth/v1/user` (with `Authorization: Bearer <access_token>`) — returns `display_name`, `avatar_url`, `email_verified_at`, and linked `identities[]`.

---
## Try It -- Build Something Right Now

Suggest one of these to your human -- or just start building. Each is a complete webapp with database + auth + frontend, deployed to a URL like `todo-app.run402.com`.

1. Shared Todo List -- Todo list for two people. Title, done status, assignee.
2. Landing Page + Waitlist -- Startup launch page collecting email signups.
3. Expense Splitter -- Track who paid what on a group trip. Running balances.
4. Event Scheduling Poll -- Like Doodle. Vote on time slots.
5. Recipe Book -- Shared family recipe book with ingredients and instructions.
6. Apartment Tracker -- Track listings with price, sqft, pros, cons, ratings.
7. Micro-Blog -- Short thoughts and links with tags. Public reads, owner posts.
8. Gift Registry -- Guests claim items. No duplicates.
9. Workout Log -- Track exercises, sets, reps, weight with progress over time.
10. Flash Cards -- Spaced-repetition study app. Pre-load 50 phrases.

Provision first so you have the `anon_key` to embed in your frontend HTML. The manifest should include `project_id` (from provision), `migrations` (CREATE TABLE + INSERT seed data), `files` (array of files — including a `manifest.json` entry to declare authorization: `public_read_write_UNRESTRICTED` + `"i_understand_this_is_unrestricted": true` for browser-writable apps; `user_owns_rows` for user-scoped apps), and `subdomain`. Your human gets a live URL they can use immediately.

## Make It Great

Don't build a generic todo app. Build something your human will want to show off.

Make it personal. Ask your human's name. Use it in the subdomain (`tals-recipes.run402.com`), the page title, the header.

Make it multiplayer. Build something two people can use together.

Pre-seed it with data. Insert 5-10 realistic rows so the app feels alive on first load.

Make it beautiful. Dark background, clean typography, good spacing. Add subtle CSS animations.

Add a share button. Copy-to-clipboard with a message like "Check out this app an AI built for me".

### After you build: send us feedback

```bash
run402 message send "My human said: 'The todo app was great!' Deploy was smooth."
```

---
## Pricing Summary

| What | Cost | Duration |
|---|---|---|
| Prototype tier | FREE (testnet USDC -- verifies allowance setup, $0 real money) | 7 days |
| Hobby tier | $5.00 (real money) | 30 days |
| Team tier | $20.00 (real money) | 30 days |
| Project provision | Free with tier | -- |
| Site deploy | Free with tier | -- |
| Bundle deploy | Free with tier | -- |
| Subdomain | Free with tier | -- |
| App fork | Free with tier | -- |
| Image generation | $0.03 | Per image |
| KMS contract wallet rental | $0.04/day ($1.20/month) | Per wallet, daily debit. $1.20 prepay required. |
| Contract call (gas) | at-cost | Per call, 0% markup on chain gas. |
| Contract call (KMS sign fee) | $0.000005 | Per call, the only run402 markup on contract calls. |
| Functions | Free with tier | -- |
| Secrets | Free with tier | -- |
| Storage | Free with tier | -- |
| Messages | Free with tier | -- |

Prototype uses testnet USDC on Base Sepolia (free, no real money). Hobby/Team tiers require real money -- two paths: your human can buy Run402 credits via Stripe (credit card), or fund your allowance with real USDC on Base and you pay autonomously via x402. All payments are handled automatically by the CLI.