run402-mcp 4.93.1 → 4.94.0

package/README.md

@@ -18,13 +18,13 @@
 [![npm: @run402/functions](https://img.shields.io/npm/v/@run402/functions?label=%40run402%2Ffunctions)](https://www.npmjs.com/package/@run402/functions)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-**Run402 is open-source backend infrastructure for AI agents and coding agents** — a backend-as-a-service addressed to a machine rather than to a person. An autonomous agent provisions a Postgres database, user auth, file storage, serverless functions and site hosting, ships them through one staged deployment workflow, and pays for the usage itself. Comparable in surface to Supabase, Firebase or Vercel; different in that there is no dashboard to sign into and no human-issued API key to copy.
+**Run402 is open-source backend infrastructure for AI agents and coding agents** — a backend-as-a-service addressed to a machine rather than to a person. An autonomous agent provisions a Postgres database, user auth, file storage, serverless functions and site hosting, ships them through one staged deploy workflow, and pays for the usage itself. Comparable in surface to Supabase, Firebase or Vercel; different in that there is no dashboard you have to sign into to get started (the console exists for people; the agent never needs it) and no human-issued API key to copy.
 
-This is the backend Kychee's open products run on. We needed a layer an agent can drive end to end, with room for whatever each app turns out to need, and nothing off the shelf had all of it, so we built it and opened it the same way we open the apps: this repo holds the agent surfaces (MIT), [`run402-core`](https://github.com/kychee-com/run402-core) holds the full backend (Apache-2.0), and [kysigned](https://github.com/kychee-com/kysigned) is the first product running on it.
+This is the backend Kychee's open products run on. We needed a layer an agent can drive end to end, with room for whatever each app turns out to need, and nothing off the shelf had all of it, so we built it and opened it the same way we open the apps: this repo holds the agent surfaces (MIT), [`run402-core`](https://github.com/kychee-com/run402-core) holds the open self-hostable runtime slice (Apache-2.0; the managed Cloud control plane remains proprietary, see [CLOUD_VS_CORE.md](https://github.com/kychee-com/run402-core/blob/main/CLOUD_VS_CORE.md)), and [kysigned](https://github.com/kychee-com/kysigned) is the first product running on it.
 
-One call to [run402](https://run402.com) gives an agent a full Postgres database, REST API, user auth, content-addressed file storage, static site hosting, serverless functions, and image generation, paid with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning) — or Stripe credits. The prototype tier is free on testnet.
+One call to [run402](https://run402.com) gives an agent a full Postgres database, REST API, user auth, content-addressed file storage, static site hosting, serverless functions, and image generation, paid with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning) — or card-funded allowance. The prototype tier is free on testnet.
 
-**Run402 is agent-first because agents are first-class participants, not because people disappear.** A person or agent acts through its own Run402 principal and authenticator, and its actions remain attributable. Identity answers who acted; memberships, roles, grants, delegates, freshness, and spend policy determine what that principal may do.
+**Run402 is agent-first because agents are first-class participants, not because people disappear.** A person or agent acts through its own Run402 principal and authenticator, and its actions remain attributable. Identity answers who acted; memberships, roles, grants, grant keys (the CLI still says `delegates`; renamed next), freshness, and spend policy determine what that principal may do.
 
 An autonomous agent may remain the legitimate owner of the org-of-one it creates. People may join through explicit co-ownership. Agents entering somebody else's organization receive bounded authority instead of borrowing a human account. Different keys. Equal standing. Explicit authority.
 
@@ -35,7 +35,7 @@ This monorepo ships these interfaces:
 | Surface | Use when… |
 |---------|-----------|
 | [`run402` CLI](./cli/) | Terminal, scripts, CI, agent-controlled shells: JSON in, JSON out, exit code on failure |
-| [`@run402/sdk`](./sdk/) | Calling run402 from TypeScript: typed kernel, isomorphic (Node 22 / Deno / Bun / V8 isolates) with a Node entry that auto-loads the local keystore + allowance + x402 / Lightning fetch |
+| [`@run402/sdk`](./sdk/) | Calling run402 from TypeScript: typed kernel, isomorphic (Node 22 / Deno / Bun / V8 isolates) with a Node entry that auto-loads the local keystore + wallet + x402 / Lightning fetch |
 | [`run402-mcp`](./src/) | Claude Desktop, Cursor, Cline, Claude Code: core run402 operations as MCP tools |
 | [OpenClaw skill](./openclaw/) | OpenClaw agents (no MCP server required) |
 | [Run402 for Buzz](./buzz/) | Buzz people and agents: install from run402.com, preflight/link one agent's dedicated identities, deploy a contextual demo, then offer human co-ownership through a normal HTTPS/passkey handoff; Buzz remains unchanged |
@@ -44,7 +44,7 @@ This monorepo ships these interfaces:
 
 These interfaces share a single typed kernel where appropriate: `@run402/sdk`. MCP tools, CLI subcommands, and OpenClaw scripts are thin shims over SDK calls. `@run402/functions` is the in-function helper that runs inside deployed code; the npm package on the registry is the artifact Cloud bundles. `@run402/astro` layers the SDK and functions runtime into Astro's build and SSR flow. The HTTP API is the foundation; the SDK owns shared client workflows and orchestration; CLI and MCP expose them in machine-friendly forms. Native SDK/MCP references explain intentional alternatives.
 
-Deployment summaries share the SDK workflow view. CLI writes redacted detail under `.run402/diagnostics/`; MCP retains it through `expand_result`. Typed SDK callers keep the full result. Snapshot collection excludes platform runtime files automatically.
+Deploy summaries share the SDK workflow view. CLI writes redacted detail under `.run402/diagnostics/`; MCP retains it through `expand_result`. Typed SDK callers keep the full result. Snapshot collection excludes platform runtime files automatically.
 
 ## 30-second start
 
@@ -52,14 +52,14 @@ First create the complete `run402.json` and `index.html` from [Your first deploy
 
 ```bash
 npm install -g run402@latest
-run402 up --name my-app -y                           # bootstrap allowance/tier/project/link, then deploy manifest
+run402 up --name my-app -y                           # bootstrap wallet/tier/project/link, then deploy manifest
 run402 up verify                                     # rerun app HTTP verification without deploying
 run402 up --verify                                   # deploy, then wait for gateway/edge coherence
 ```
 
 That's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC.
 
-Buy from any x402 seller with the same allowance and a default $0.10 ceiling:
+Buy from any x402 seller with the same wallet and a default $0.10 ceiling:
 
 ```bash
 run402 pay https://seller.example/translate --method POST \
@@ -83,11 +83,11 @@ same payer and key. Never replace the key. The SDK and MCP can also re-present
 an ambiguous proof while their process remains alive; custom/arbitrary sellers
 remain ambiguous and require reconciliation.
 
-Prefer `run402 up` when a repo has `run402.deploy.json` or `app.json`. The CLI stays a thin shim over the Node SDK action runner (`r.actions.run(...)` / `r.up(...)`): it validates the manifest first, then recursively performs only the missing prerequisites. Project resolution is `--project`, `.run402/project.json`, manifest `project_id`, approved creation from `--name`; global active state never selects a deployment target. `--name` is project creation/link metadata only; it is not part of the deploy manifest and never renames an existing project. Use `--check` for local validation and `--plan` for gateway-reviewed intent before applying. Local validation covers every file the manifest references (migration `sql_path`/`sql_file`, function sources and `files`, site paths and `dir()` targets, `assets.put` sources): a missing one fails with `MANIFEST_FILE_MISSING` (`details.missing[]` of `{ field_path, path, kind }`, one `create_file` next action per file) before any gateway call, in every mode and in `deploy apply`. With no manifest in the working directory, `UP_MANIFEST_REQUIRED` looks one directory down and names what it found (`details.nearby_manifests[]`, a read-only `run_in_directory` action for a single candidate, or one unranked `select_application` action for multiple apps); `--manifest <path>` to a missing file is a typed `MANIFEST_NOT_FOUND`.
+Prefer `run402 up` when a repo has `run402.deploy.json` or `app.json`. The CLI stays a thin shim over the Node SDK action runner (`r.actions.run(...)` / `r.up(...)`): it validates the manifest first, then recursively performs only the missing prerequisites. Project resolution is `--project`, `.run402/project.json`, manifest `project_id`, approved creation from `--name`; global active state never selects a deploy target. `--name` is project creation/link metadata only; it is not part of the deploy manifest and never renames an existing project. Use `--check` for local validation and `--plan` for gateway-reviewed intent before applying. Local validation covers every file the manifest references (migration `sql_path`/`sql_file`, function sources and `files`, site paths and `dir()` targets, `assets.put` sources): a missing one fails with `MANIFEST_FILE_MISSING` (`details.missing[]` of `{ field_path, path, kind }`, one `create_file` next action per file) before any gateway call, in every mode and in `run402 deploy`. With no manifest in the working directory, `UP_MANIFEST_REQUIRED` looks one directory down and names what it found (`details.nearby_manifests[]`, a read-only `run_in_directory` action for a single candidate, or one unranked `select_application` action for multiple apps); `--manifest <path>` to a missing file is a typed `MANIFEST_NOT_FOUND`.
 
 If an app manifest defines `verify.http[]`, `run402 up` verifies those URLs after deploy. Fresh run402 edge sentinel misses are reported as `propagation_pending` rather than permanent failures while the binding is still converging; tune that wait with `--propagation-budget-s` (default 120) or return immediately with `--no-propagation-wait`. `run402 up verify` reruns the same HTTP checks without uploading, deploying, creating projects, or mutating resources.
 
-The CLI checks for newer `run402` releases opportunistically and fail-open. Success stdout stays the command result; stale-version notices are advisory JSON on stderr, or `cli.update_available` NDJSON events in `--json-stream`. `run402 doctor --refresh` is the explicit live npm check and reports the install context plus the safest upgrade command for local, global, or ephemeral installs. `run402 doctor` answers `{ ok, blocking[], warnings[], checks[] }`: `ok` is true exactly when `blocking[]` is empty, every check carries `severity: "blocking" | "advisory" | "info"`, advisory findings (an unbound passkey, a stale CLI, gitvault gaps, a tier-less own org that can still reach another org's projects: `TIER_MISSING_ON_OWN_ORG`) land in `warnings[]` without changing `ok` or the exit code, and the `tier` check's `status` is a fixed vocabulary (`ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error`, never a tier name; the name and raw lifecycle are in `value.tier` / `value.lifecycle`).
+The CLI checks for newer `run402` releases opportunistically and fail-open. Success stdout stays the command result; stale-version notices are advisory JSON on stderr, or `cli.update_available` NDJSON events in `--json-stream`. `run402 doctor --refresh` is the explicit live npm check and reports the install context plus the safest upgrade command for local, global, or ephemeral installs. `run402 doctor` answers `{ ok, blocking[], warnings[], checks[] }`: `ok` is true exactly when `blocking[]` is empty, every check carries `severity: "blocking" | "advisory" | "info"`, advisory findings (an unbound passkey, a stale CLI, vault gaps, a tier-less own org that can still reach another org's projects: `TIER_MISSING_ON_OWN_ORG`) land in `warnings[]` without changing `ok` or the exit code, and the `tier` check's `status` is a fixed vocabulary (`ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error`, never a tier name; the name and raw lifecycle are in `value.tier` / `value.lifecycle`).
 
 Typed deploy configs use the same commands. Executable configs are trusted local code, so v1 only runs them when passed explicitly:
 
@@ -97,7 +97,7 @@ run402 up --manifest run402.deploy.ts --plan
 run402 up --manifest run402.deploy.ts --require-plan plan_...
 ```
 
-`--check` and `--print-spec` are local-only (both verify that every referenced file exists). `--plan` asks the gateway for a reviewed plan with `plan_id`, `plan_fingerprint`, warnings, diff, and one next action. `--require-plan` reapplies only if the normalized spec and reviewed gateway facts still match.
+`--check` and `--print-spec` are local-only (both verify that every referenced file exists). `--plan` asks the gateway for a reviewed plan with `plan_id`, `plan_fingerprint`, warnings, diff, and one next action. `--require-plan` reapplies only if the normalized spec and reviewed gateway events still match.
 
 ```ts
 import { defineConfig, dir, nodeFunction, sqlFile } from "@run402/sdk/config";
@@ -159,7 +159,7 @@ Use `run402 projects validate-expose`  for a non-mutating feedback loop before a
 
 **Auth-as-SDLC:** put the same JSON under `database.expose` in your v2 `ReleaseSpec`. The gateway validates it against your migration SQL during deploy and rejects mismatches with a structured `errors` array listing every violation.
 
-### Directory deployment (advanced primitive)
+### Directory deploy (advanced primitive)
 
 For a standalone static directory on an existing project:
 
@@ -171,7 +171,7 @@ Use `run402 up` for a complete application with a deploy manifest. The SDK owns
 
 ### Same-origin web routes: static site + function ingress
 
-Apply-v1 routes and static public paths are release resources: the release pointer activates after the required deployment stages in `deploy apply`. Applied migrations and external side effects are not rolled back by changing that pointer. Release static asset paths such as `events.html` are distinct from browser-visible public static paths such as `/events`. Use `site.public_paths` for ordinary clean static URLs; keep routes for function ingress and exact, method-aware static aliases.
+Apply-v1 routes and static public paths are release resources: the release pointer activates after the required deploy stages in `run402 deploy`. Applied migrations and external side effects are not rolled back by changing that pointer. Release static asset paths such as `events.html` are distinct from browser-visible public static paths such as `/events`. Use `site.public_paths` for ordinary clean static URLs; keep routes for function ingress and exact, method-aware static aliases.
 
 ```json
 {
@@ -219,21 +219,21 @@ Function routes can charge a fixed tenant x402 price before the handler runs by
 
 Matching is exact or final-prefix-wildcard only. `/admin` and `/admin/` are exact trailing-slash equivalents; `/admin/*` matches children but not `/admin`, `/admin/`, `/admin.css`, or `/administrator`, so deploy both `/admin` and `/admin/*` for a routed section root. Query strings are ignored for matching and preserved in the handler's full public `req.url`. Exact routes beat prefix routes; longest prefix wins; method-compatible dynamic routes beat static assets. A `POST /login` route can coexist with static `GET /login` HTML. Unsafe method mismatch returns `405`, and matched dynamic route failures fail closed instead of falling back to static files.
 
-Routed functions use the Node 22 Fetch Request -> Response contract: `export default async function handler(req) { ... }`. `req.method` is the browser method, and `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Derive OAuth callbacks from it, for example `new URL("/admin/oauth/google/callback", new URL(req.url).origin)`. Append multiple cookies with `headers.append("Set-Cookie", value)`; redirects, cookies, and query strings are preserved. On priced routes, import `getRoutedPaymentContext` from `@run402/functions`, read `const paymentContext = getRoutedPaymentContext(req)`, and key app-side idempotency by `paymentContext.paymentId`. For a receipt-enabled route, return `payment.fulfilled(response)` only after the response represents completed delivery; the helper fails closed outside a settled, current, receipt-enabled routed invocation. The context helper reads gateway-confirmed `x-run402-payment-*` headers and returns `null` for unpriced or direct calls. The raw `run402.routed_http.v1` envelope is internal; do not write route handlers against it.
+Routed functions use the Node 22 Fetch Request -> Response contract: `export default async function handler(req) { ... }`. `req.method` is the browser method, and `req.url` is the full public URL on managed subdomains, hosts, and verified custom domains. Derive OAuth callbacks from it, for example `new URL("/admin/oauth/google/callback", new URL(req.url).origin)`. Append multiple cookies with `headers.append("Set-Cookie", value)`; redirects, cookies, and query strings are preserved. On priced routes, import `getRoutedPaymentContext` from `@run402/functions`, read `const paymentContext = getRoutedPaymentContext(req)`, and key app-side idempotency by `paymentContext.paymentId`. For a receipt-enabled route, return `payment.fulfilled(response)` only after the response represents completed delivery; the helper fails closed outside a settled, current, receipt-enabled routed invocation. The context helper reads gateway-confirmed `x-run402-payment-*` headers and returns `null` for unpriced or direct calls. The raw `run402.routed_http.v1` envelope is internal; do not write route handlers against it.
 
-**Recipe: static home page + SPA shell.** A SPA site ships `index.html` as the shell serving every unmatched route (match `spa_fallback`), so by default `GET /` serves the shell too. To serve a real static home page at `/` while keeping the shell for app routes, ship `home.html` at the site root alongside `index.html` and add an exact root static route alias: `"routes": { "replace": [ { "pattern": "/", "target": { "type": "static", "file": "home.html" } } ] }`. Route matching runs before all static resolution (including the implicit `/` -> `index.html` root mapping), and SPA-fallback derivation is independent of the route table, so `GET /` serves `home.html` (`route_static_alias`), unmatched app routes such as `/dashboard` still serve the shell (`spa_fallback`), and named static pages keep serving unchanged (`static_exact`). Expect two non-blocking plan lints: `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn: the alias overrides what `/` would otherwise serve; accurate and expected here) and `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info: `/home.html` stays directly reachable in implicit public-path mode; add `<link rel="canonical">` to `home.html` if duplicate-content SEO matters). Omitting `routes` on later deploys carries the alias forward; `routes.replace` is total, so a pipeline that sends it must include the alias every time. Verify with `run402 deploy resolve --url https://<your-site>/ --method GET` or `deploy_diagnose_url` and confirm `match: "route_static_alias"` with `target_file: "home.html"`.
+**Recipe: static home page + SPA shell.** A SPA site ships `index.html` as the shell serving every unmatched route (match `spa_fallback`), so by default `GET /` serves the shell too. To serve a real static home page at `/` while keeping the shell for app routes, ship `home.html` at the site root alongside `index.html` and add an exact root static route alias: `"routes": { "replace": [ { "pattern": "/", "target": { "type": "static", "file": "home.html" } } ] }`. Route matching runs before all static resolution (including the implicit `/` -> `index.html` root mapping), and SPA-fallback derivation is independent of the route table, so `GET /` serves `home.html` (`route_static_alias`), unmatched app routes such as `/dashboard` still serve the shell (`spa_fallback`), and named static pages keep serving unchanged (`static_exact`). Expect two non-blocking plan lints: `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn: the alias overrides what `/` would otherwise serve; accurate and expected here) and `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info: `/home.html` stays directly reachable in implicit public-path mode; add `<link rel="canonical">` to `home.html` if duplicate-content SEO matters). Omitting `routes` on later deploys carries the alias forward; `routes.replace` is total, so a pipeline that sends it must include the alias every time. Verify with `run402 deploy resolve --url https://<your-site>/ --method GET` or `deploy_resolve` and confirm `match: "route_static_alias"` with `target_file: "home.html"`.
 
 Avoid routing every static file, broad method lists by default, wildcard static route targets, leading-slash static files, directory shorthand, and one-static-route-target-per-page tables that exhaust route limits. Also watch wildcard function routes that shadow direct public static paths. Warning codes to handle include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and resolve diagnostics to distinguish the route pattern from the backing `asset_path`.
 
-Diagnose public URLs with the URL-first CLI or MCP/SDK equivalents:
+Resolve public URLs with the CLI or its MCP/SDK equivalents:
 
 ```bash
-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
+run402 deploy resolve https://example.com/events --project prj_123 --method GET
+run402 deploy resolve --url https://example.com/events?utm=x#hero --project prj_123 --method GET
+run402 deploy resolve --host example.com --path /events --project prj_123 --method GET
 ```
 
-`deploy_diagnose_url` and `r.project(id).apply.resolve({ url, method: "GET" })` return `would_serve`, `diagnostic_status`, `match`, normalized request data, warnings, full resolution JSON, `edge_propagation`, and next steps. 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. Stable-host diagnostics may also include `authorization_result`, `cas_object` (`sha256`, `exists`, `expected_size`, `actual_size`), hostname-specific `response_variant`, route/static fields such as `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`). Known `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 the diagnostic body status, not the HTTP status of the SDK call, so host misses can still be successful CLI/MCP/SDK calls with `would_serve: false`. Do not treat resolve/diagnose as a fetch, cache purge, or cache-policy oracle; route method misses should inspect `allow`, CAS authorization/health failures should inspect or redeploy the affected static asset, and fresh host misses should inspect `edge_propagation` or rerun `run402 up verify`. Branch on structured JSON fields such as `cache_class` and preserve unknown cache classes.
+`deploy_resolve` and `r.project(id).apply.resolve({ url, method: "GET" })` return `would_serve`, `diagnostic_status`, `match`, normalized request data, warnings, full resolution JSON, `edge_propagation`, and next steps. 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. Stable-host diagnostics may also include `authorization_result`, `cas_object` (`sha256`, `exists`, `expected_size`, `actual_size`), hostname-specific `response_variant`, route/static fields such as `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`). Known `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 the diagnostic body status, not the HTTP status of the SDK call, so host misses can still be successful CLI/MCP/SDK calls with `would_serve: false`. Do not treat resolve/diagnose as a fetch, cache purge, or cache-policy oracle; route method misses should inspect `allow`, CAS authorization/health failures should inspect or redeploy the affected static asset, and fresh host misses should inspect `edge_propagation` or rerun `run402 up verify`. Branch on structured JSON fields such as `cache_class` and preserve unknown cache classes.
 
 Release observability exposes stable asset identity and public reachability. Inventories include `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata` (`file_count`, `total_bytes`, `cache_classes`, `cache_class_sources`, `spa_fallback`), and `static_public_paths[]` when returned. `site.paths` lists release static assets; `static_public_paths[]` lists browser-visible public paths with `public_path`, `asset_path`, `reachability_authority`, `direct`, cache class, and content type. Plan and release diffs expose `static_assets` counters: unchanged/changed/added/removed, `newly_uploaded_cas_bytes`, `reused_cas_bytes`, `deployment_copy_bytes_eliminated`, `legacy_immutable_warnings`, `previous_immutable_failures`, and `cas_authorization_failures`.
 
@@ -241,7 +241,7 @@ Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED` (manifest
 
 ### GitHub Actions OIDC deploys: link once, deploy with the same CLI
 
-For repo-driven deploys, run402 does not need service keys or allowance files in GitHub secrets. Run a local link command once:
+For repo-driven deploys, run402 does not need service keys or wallet files in GitHub secrets. Run a local link command once:
 
 ```bash
 run402 ci link github --project prj_... --manifest run402.deploy.json
@@ -262,10 +262,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Deploy to run402
-        run: npx --yes run402@3.7.5 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'
+        run: npx --yes run402@3.7.5 deploy --manifest 'run402.deploy.json' --project 'prj_...'
 ```
 
-CI deploys are intentionally narrow: `site`, `functions`, `database`, absent/current `base`, and route declarations only when the binding has covering `--route-scope` patterns. Without route scopes, CI cannot ship `routes`. Keep secrets, domains, subdomains, checks, non-current base, and broader trust changes in a local allowance-backed deploy. If the gateway returns `CI_ROUTE_SCOPE_DENIED`, re-link with exact scopes like `/admin` or final-wildcard scopes like `/api/*`, or deploy locally. Manage bindings with `run402 ci list` and `run402 ci revoke`.
+CI deploys are intentionally narrow: `site`, `functions`, `database`, absent/current `base`, and route declarations only when the binding has covering `--route-scope` patterns. Without route scopes, CI cannot ship `routes`. Keep secrets, domains, subdomains, checks, non-current base, and broader trust changes in a local wallet-backed deploy. If the gateway returns `CI_ROUTE_SCOPE_DENIED`, re-link with exact scopes like `/admin` or final-wildcard scopes like `/api/*`, or deploy locally. Manage bindings with `run402 ci list` and `run402 ci revoke`.
 
 ### In-function helpers: caller-context vs BYPASSRLS
 
@@ -294,11 +294,11 @@ export default async (req: Request) => {
 };
 ```
 
-`adminDb().sql(query, params?)` runs raw parameterized SQL and always bypasses RLS. The current runtime returns the gateway envelope, including `rows` and `row_count`; read `result.rows`, not `result[0]`. Older helper typings incorrectly described a bare array. See the [owning runtime reference](https://github.com/kychee-com/run402-core/tree/main/packages/functions#admindbsqlquery-params--raw-sql-bypassrls) and match local helper types to the runtime version used by your deployment.
+`adminDb().sql(query, params?)` runs raw parameterized SQL and always bypasses RLS. The current runtime returns the gateway envelope, including `rows` and `row_count`; read `result.rows`, not `result[0]`. Older helper typings incorrectly described a bare array. See the [owning runtime reference](https://github.com/kychee-com/run402-core/tree/main/packages/functions#admindbsqlquery-params--raw-sql-bypassrls) and match local helper types to the runtime version used by your deploy.
 
 `@run402/functions` is auto-bundled into deployed code; install it in your editor for full TypeScript autocomplete (also works at build time for static-site generation with `RUN402_SERVICE_KEY` + `RUN402_PROJECT_ID` set).
 
-`ai.generateImage({ prompt, aspect? })` is available inside deployed functions for live app flows such as generated avatars or OG images. It calls the project runtime image endpoint with `RUN402_SERVICE_KEY`, so deployed functions do not need allowance wallets or x402 signing code. Aspects are `square`, `landscape`, and `portrait`; the result is `{ image, content_type, aspect }` with base64 image bytes. Runtime image generation is billed, rate-limited, and spend-capped against the project organization; public routed functions should authenticate/rate-limit their users before calling it.
+`ai.generateImage({ prompt, aspect? })` is available inside deployed functions for live app flows such as generated avatars or OG images. It calls the project runtime image endpoint with `RUN402_SERVICE_KEY`, so deployed functions do not need wallets or x402 signing code. Aspects are `square`, `landscape`, and `portrait`; the result is `{ image, content_type, aspect }` with base64 image bytes. Runtime image generation is billed, rate-limited, and spend-capped against the project organization; public routed functions should authenticate/rate-limit their users before calling it.
 
 `assets.put(key, source, opts?)` uploads bytes from inside a deployed function through the same CAS-backed apply substrate as deploy-time assets. It uses `RUN402_SERVICE_KEY`, accepts a string, `Uint8Array`, or `{ content | bytes }`, and returns an SDK-compatible `AssetRef` with mutable and immutable URLs.
 
@@ -328,7 +328,7 @@ git push -u origin main                       # publishes, encrypted before it l
 
 `origin` is claimed additively: when the directory has no `origin` yet, the scaffold names ours `origin` — `git push origin main` just works, no side-remote name to remember. An existing `origin` is never touched; the fallback is `run402` instead, and the response says which happened and why. An app that lives inside another repository (a monorepo workspace) is never scaffolded into that repository: the skip carries a `create_nested_repo` next action, and `run402 repos create --nested --project <id>` (or `run402 up --nested`) gives the app root its own nested repository and `run402` remote, appending exactly one line to the enclosing repository's local `.git/info/exclude` and touching nothing else there; `repos create` prints a `git push` next action only for a remote it actually added. The free path is the whole path — no slug, no fee, no ceremony. When you want pretty `run402::<org-slug>/<name>` addresses (clone-by-name, push-to-create), claim an org slug once — the optional named-address upgrade described below.
 
-**Named addressing.** `run402::<org-slug>/<name>` works alongside the id-form `run402::<org_id>/<project_id>` in the same slot — pick an org slug once (`run402 org slug <slug>`, owner-only, a small one-time claim fee), and every repo under it is `run402::<slug>/<name>`. Pushing a name that doesn't exist yet **push-to-creates** it: the project and vault are allocated atomically, and a losing concurrent pusher resolves cleanly to the winner's repo instead of erroring — its work is not lost, it just wasn't the creator. The first time a named remote resolves on a checkout, the resolved id is **pinned** into that checkout's local git config — every later push/fetch follows the pin directly, so a later rename of the org slug or repo name never breaks an existing clone. The id-form address needs no pin (a project id never changes) and stays the cold-restart path: an agent that lost its local state but still holds authority on the project can always fall back to `run402::<org_id>/<project_id>`.
+**Named addressing.** `run402::<org-slug>/<name>` works alongside the id-form `run402::<org_id>/<project_id>` in the same slot — pick an org slug once (`run402 org slug <slug>`, owner-only, a small one-time fee), and every repo under it is `run402::<slug>/<name>`. Pushing a name that doesn't exist yet **push-to-creates** it: the project and vault are allocated atomically, and a losing concurrent pusher resolves cleanly to the winner's repo instead of erroring — its work is not lost, it just wasn't the creator. The first time a named remote resolves on a checkout, the resolved id is **pinned** into that checkout's local git config — every later push/fetch follows the pin directly, so a later rename of the org slug or repo name never breaks an existing clone. The id-form address needs no pin (a project id never changes) and stays the cold-restart path: an agent that lost its local state but still holds authority on the project can always fall back to `run402::<org_id>/<project_id>`.
 
 **One thing to know up front: a vault has a writer set, not a single key.** Every admitted member or handoff recipient opens the vault and pushes under its OWN keystore key (`run402 repos access` lists them). A vault whose only admitted principal is this keystore is exactly as safe as this keystore — see "If you lose the keystore" below, or admit a second principal.
 
@@ -362,21 +362,21 @@ run402 repos fsck --budget 500
 git clone run402::<org_id>/<project_id> restored
 ```
 
-Cloning needs a Run402 principal on this machine — a wallet with an allowance and a keystore holding an envelope for this vault — this is encrypted git, not a shareable link.
+Cloning needs a Run402 principal on this machine — a wallet and a keystore holding an envelope for this vault — this is encrypted git, not a shareable link.
 
 A fresh clone installs local `refs/r402/retain/<oid>` refs for every retained deploy-capture tip no branch reaches, so a plain `git fsck` is silent — `git for-each-ref refs/r402/` lists what is retained. Clones made by a client older than this one (or a checkout whose ref write degraded) may still show dangling commits under `git fsck`; harmless, not corruption — one `run402 repos fsck` run installs the missing refs. A retained ref locally pins that history against `git gc` until the vault prunes the capture, at which point the next fetch retracts it.
 
 `repos snapshot` is the CAPTURE lane — the protocol deploy ref plus the HEAD target — because a dirty tree captures as a synthetic commit that sits on no branch. Your own branches and tags reach the vault through `git push origin <branch>`.
 
-**Allocating a vault does NOT gate the project's deploys.** `gitvault_policy` stays unset until you set it — a vault created by a first `git push` or `repos create` never silently changes how you deploy. A deploy against a vaulted, ungated project proceeds ungated and its result carries a typed `next_actions` entry offering `run402 repos policy required`; every later ungated deploy carries a `warnings[]` entry naming the drift, until the policy is set either way — never a block, never an interactive prompt. Once `gitvault_policy` is `required`, a deploy must present a vaulted capture at commit — `run402 deploy apply` produces one automatically on any machine holding the keystore; un-gate with `run402 repos policy grandfathered --reason "<why>"` (owner + step-up, audited, reversible with `run402 repos policy required`). Vaulting your source is never gated on a deploy, either way. `run402 doctor` reports the policy, whether this machine can satisfy it, and where the keystore lives.
+**Allocating a vault does NOT gate the project's deploys.** `gitvault_policy` stays unset until you set it — a vault created by a first `git push` or `repos create` never silently changes how you deploy. A deploy against a vaulted, ungated project proceeds ungated and its result carries a typed `next_actions` entry offering `run402 repos policy required`; every later ungated deploy carries a `warnings[]` entry naming the drift, until the policy is set either way — never a block, never an interactive prompt. Once `gitvault_policy` is `required`, a deploy must present a vaulted capture at commit — `run402 deploy` produces one automatically on any machine holding the keystore; un-gate with `run402 repos policy grandfathered --reason "<why>"` (owner + step-up, audited, reversible with `run402 repos policy required`). Vaulting your source is never gated on a deploy, either way. `run402 doctor` reports the policy, whether this machine can satisfy it, and where the keystore lives.
 
 Before `snapshot` reports that anything landed, the client compares every finalization receipt against its local expected manifest and reads the admitted head back from storage — a 200 alone is never enough. Maintenance is one verb, `run402 repos gc` — `git gc`'s own two halves (checkpoint publication + prune planning), never described as "exactly `git gc`" since the deletion ceremony is stricter: it plans locally, and submits only when handed both verifier receipts — one from this CLI, one from the independent `r402s-verify` — with `--submit --intent-core <path> --verifier-receipt <path>`; only the control-plane-signed completion says what was deleted.
 
 From the SDK, with identical semantics — vault reads run anywhere, and the verbs that touch a git working tree or the on-disk keystore are Node-only:
 
-For typed repository automation, see the [native SDK gitvault reference](https://docs.run402.com/sdk/resources/).
+For typed repository automation, see the [native SDK KyGit reference](https://docs.run402.com/sdk/resources/).
 
-**The encrypted second remote — the zero-migration pattern.** Keep GitHub/GitLab as the primary (collaboration, CI, reviews, unchanged) and add GitVault as the second remote: `git remote add gitvault run402::<org_id>/<project_id>` + `git push gitvault --all`, and a complete, continuously updated copy of your history exists that the storage provider itself cannot read. The reason this matters, said plainly and as capability rather than accusation: a host that can READ private repositories can — under a future policy, an acquisition, a training pipeline, a subpoena, or a breach — index them, train models on them, or hand them to someone who will. Run402 cannot decrypt your gitvault or repository history. Deployment artifacts remain a disclosed plaintext custody boundary.
+**The encrypted second remote — the zero-migration pattern.** Keep GitHub/GitLab as the primary (collaboration, CI, reviews, unchanged) and add KyGit as the second remote: `git remote add gitvault run402::<org_id>/<project_id>` + `git push gitvault --all`, and a complete, continuously updated copy of your history exists that the storage provider itself cannot read. The reason this matters, said plainly and as capability rather than accusation: a host that can READ private repositories can — under a future policy, an acquisition, a training pipeline, a subpoena, or a breach — index them, train models on them, or hand them to someone who will. Run402 cannot decrypt your gitvault or repository history. Deployment artifacts remain a disclosed plaintext custody boundary.
 
 **A vault-only project is first-class.** `run402 init` (or `run402 repos create <name>`), then `git push origin …`, then `gc` / `fsck` / `access`, and never a deploy — a supported shape, not a degraded one. One consequence is worth stating plainly: a vault-only project has no deploy lane, so the disclosed plaintext custody boundary is empty and there is consequently no custodial restore path.
 
@@ -394,22 +394,22 @@ run402 repos recovery-bundle --out ./bundle.json     # the member's no-keystore
 run402 repos recover ./mirror-copy --out ./restored --receipt ./recovery-receipt.json --bundle ./bundle.json
 ```
 
-**Handoff / resume — pass a working tree to another agent, dirty state and all.** `run402 repos handoff` captures the actual working tree — staged, unstaged, and untracked changes, exactly as `git stash push -u` would — and mints a single-use bearer key, `kgh1_…`, printed to stdout exactly once (`--json` still keeps it off stderr; there is no second place to find it if you lose it). Hand that key to another agent — another machine, another session, no shared keystore, no shared allowance — and `run402 repos resume kgh1_…` claims it, clones a fresh checkout, and reapplies the exact dirty state with `git stash apply --index`. The resuming agent also becomes a run402 wallet of its own on the way in: with no active tier, `resume` folds the same cold-start chain `create` does (allowance → faucet → one x402 prototype payment) before the claim; `--no-init` opts out, and the claim never waits on it. A Handoff Note rides alongside (a short JSON summary: what's done, what's in progress, what's failing, next steps) and renders as Markdown by default on `resume`. The key confers real authority — by default the sender's own org role — until it is claimed or its TTL (default 1h, `--ttl <seconds>`) expires; the mint response says so, and the CLI echoes the warning before printing the key. Sensitive untracked files (`.env`, `*.pem`, `*.key`, SSH/AWS/GPG directories, and 18 more patterns) are excluded from capture by default; opt one back in with `--include-sensitive <glob>`.
+**Handoff / resume — pass a working tree to another agent, dirty state and all.** `run402 repos handoff` captures the actual working tree — staged, unstaged, and untracked changes, exactly as `git stash push -u` would — and mints a single-use bearer key, `kgh1_…`, printed to stdout exactly once (`--json` still keeps it off stderr; there is no second place to find it if you lose it). Hand that key to another agent — another machine, another session, no shared keystore, no shared wallet — and `run402 repos resume kgh1_…` claims it, clones a fresh checkout, and reapplies the exact dirty state with `git stash apply --index`. The resuming agent also becomes a run402 wallet of its own on the way in: with no active tier, `resume` folds the same cold-start chain `create` does (wallet → faucet → one x402 prototype payment) before the claim; `--no-init` opts out, and the claim never waits on it. A Handoff Note rides alongside (a short JSON summary: what's done, what's in progress, what's failing, next steps) and renders as Markdown by default on `resume`. The key confers real authority — by default the sender's own org role — until it is claimed or its TTL (default 1h, `--ttl <seconds>`) expires; the mint response says so, and the CLI echoes the warning before printing the key. Sensitive untracked files (`.env`, `*.pem`, `*.key`, SSH/AWS/GPG directories, and 18 more patterns) are excluded from capture by default; opt one back in with `--include-sensitive <glob>`.
 
 ```bash
 run402 repos handoff --note-file handoff.json     # captures the working tree, mints the key, prints it ALONE to stdout
-run402 repos resume kgh1_…                         # on the other machine: claim it, clone, restore, print the note
+run402 repos resume kgh1_…                         # on the other machine: redeem it, clone, restore, print the note
 ```
 
 Neither verb has an MCP tool — `handoff` mints a bearer secret and `resume` mutates org membership, the same "mutating verbs are CLI-only" reasoning as `create`/`delete` above.
 
 **Writers, plural.** A vault admits heads from a SET of writer keys, each a member's own keystore identity (protocol rev 47). `resume` makes the recipient a writer before it returns — `git push` works at once, under the recipient's own key, and the sender's environment can be deleted afterwards. Any member added with `run402 org member add` (developer or above) becomes a writer the same way: the adder's client admits the new key inline when it can, and REFUSES the add (`GITVAULT_WRITER_NOT_ADMITTED`, `request_writer_sync`) when it cannot, so no member is ever left able to read but not push. `run402 repos view` lists `writers[]` and `pending_writers[]`; `run402 repos access sync` admits pending keys on demand; removing a member rides the next epoch rotation and that key can never be re-added. Nobody's seed is ever copied: a writer is admitted by a live writer's signature or by a sender-signed handoff grant the recipient completes with its own key.
 
-**Invite / join — bring a second agent into the exact work, dirty tree included, and talk in a shared room.** A Handoff passes the work on; an Invite grows the team. `run402 repos invite` captures the working tree exactly like `handoff` does — the inviter's own worktree, index, branch, refs, and access are all untouched, and it keeps pushing throughout — registers the inviter's own presence in a coordination room (the project's default room, or `--room <key>` for a named org room), mints a single-use bearer key, `kgi1_…`, printed to stdout exactly once, and posts ONE room message naming the checkpoint and the invite id (never the key). Minting requires an ACTIVE writer key, the same as `handoff` (`INVITE_MINT_REQUIRES_WRITER` names `run402 repos access sync` as the fix). Hand that key to another agent and `run402 repos join kgi1_…` pays its own way in — the joining agent folds the SAME cold-start chain `resume` does (allowance → faucet → one x402 prototype payment) before the claim, so it arrives as a paid-up run402 wallet of its own — clones a fresh checkout, **becomes a writer of the vault under its OWN key before the command returns** (nothing is copied from the inviter), restores the exact dirty state, pins the invite's room locally, registers its own presence, posts ONE arrival message, and reports who invited it (name, labels, whether they're still live), who else is in the room, and the last few messages. Both agents push, interleaved, each signing under its own key. From there `run402 messages wait` is the agent's ear: it blocks until the other side speaks (or a bounded timeout elapses) using the gateway's held read, never errors on silence, and reports who is still live either way. The minted role defaults to `developer` and never exceeds the inviter's own; the Invite Note (same shape as the Handoff Note) rides alongside and renders as Markdown by default on `join`. Taking access back is `run402 org member rm`, which rotates the vault's epoch so the removed key can no longer push while every remaining agent keeps working.
+**Invite / join — bring a second agent into the exact work, dirty tree included, and talk in a shared room.** A Handoff passes the work on; an Invite grows the team. `run402 repos invite` captures the working tree exactly like `handoff` does — the inviter's own worktree, index, branch, refs, and access are all untouched, and it keeps pushing throughout — registers the inviter's own presence in a coordination room (the project's default room, or `--room <key>` for a named org room), mints a single-use bearer key, `kgi1_…`, printed to stdout exactly once, and posts ONE room message naming the checkpoint and the invite id (never the key). Minting requires an ACTIVE writer key, the same as `handoff` (`INVITE_MINT_REQUIRES_WRITER` names `run402 repos access sync` as the fix). Hand that key to another agent and `run402 repos join kgi1_…` pays its own way in — the joining agent folds the SAME cold-start chain `resume` does (wallet → faucet → one x402 prototype payment) before the redemption, so it arrives as a paid-up run402 wallet of its own — clones a fresh checkout, **becomes a writer of the vault under its OWN key before the command returns** (nothing is copied from the inviter), restores the exact dirty state, pins the invite's room locally, registers its own presence, posts ONE arrival message, and reports who invited it (name, labels, whether they're still live), who else is in the room, and the last few messages. Both agents push, interleaved, each signing under its own key. From there `run402 messages wait` is the agent's ear: it blocks until the other side speaks (or a bounded timeout elapses) using the gateway's held read, never errors on silence, and reports who is still live either way. The minted role defaults to `developer` and never exceeds the inviter's own; the Invite Note (same shape as the Handoff Note) rides alongside and renders as Markdown by default on `join`. Taking access back is `run402 org member rm`, which rotates the vault's epoch so the removed key can no longer push while every remaining agent keeps working.
 
 ```bash
 run402 repos invite --note-file invite.json       # captures the working tree, mints the key, prints it ALONE to stdout
-run402 repos join kgi1_…                           # on the other machine: pay in, claim, become a writer, clone, restore
+run402 repos join kgi1_…                           # on the other machine: pay in, redeem, become a writer, clone, restore
 run402 messages wait                               # then: block until the other agent speaks (or the timeout elapses)
 ```
 
@@ -417,7 +417,7 @@ Like `handoff`/`resume`, neither `invite` nor `join` has an MCP tool — `invite
 
 **Verify it without trusting our client.** `r402s-verify` is an independent-lineage verifier for the same protocol — a separate language, separate authorship, and a separate primitive stack, deliberately sharing no implementation code with the SDK. That non-sharing is the point: a differential verifier that reuses the code it is checking verifies nothing. It lives on the `r402s-verify` branch of this repository with its own workflow, ships prebuilt release binaries, and also builds with `cargo build --release`. The full protocol specification and threat model it verifies against are published in [`docs/gitvault/`](docs/gitvault/README.md), and the frozen conformance vectors in [`test-vectors/r402s-v0/`](test-vectors/r402s-v0/README.md).
 
-**Cost.** There is no separate repos price — a vault's bytes count against the same organization-pooled storage budget your projects already share, charged once per unique object with a 4 KiB per-object accounting floor and a 1 MiB per-vault minimum.
+**Cost.** There is no separate repos price — a vault's bytes count against the organization-pooled vault quota (`sourceBytes`: prototype 1 GB, hobby 10 GB, team 50 GB), a separate pool from the storage your projects share, charged once per unique object with a 4 KiB per-object accounting floor and a 1 MiB per-vault minimum.
 
 ## SDK: `@run402/sdk`
 
@@ -428,7 +428,7 @@ npm install @run402/sdk
 Two entry points:
 
 - **`@run402/sdk`**: isomorphic. Bring your own `CredentialsProvider` (a session-token shim, a remote vault, anything that resolves project keys + auth headers). Works in Node 22, Deno, Bun, V8 isolates.
-- **`@run402/sdk/node`**: Node-only convenience. Reads local profile state plus the project-key credential cache (`credentials/project-keys.v1.json`) and signs x402 payments from one deterministic source: an explicit opaque `paymentSigner`, explicit `allowancePath`, the supplied provider's `readAllowance()`, or the default active-profile allowance. Auth and payer may intentionally differ; a selected payment source never falls back to an ambient wallet. `r.paymentPayer()` reports only safe public payer/source provenance. Also exposes `sites.deployDir(...)`, `fileSetFromDir(...)`, typed deploy-manifest helpers (`loadDeployManifest`, `normalizeDeployManifest`), and `resolveRun402TargetProfile()` for app build scripts that need the same Core/Cloud target the CLI uses.
+- **`@run402/sdk/node`**: Node-only convenience. Reads local profile state plus the project-key credential cache (`credentials/project-keys.v1.json`) and signs x402 payments from one deterministic source: an explicit opaque `paymentSigner`, explicit `walletPath`, the supplied provider's `readWallet()`, or the default active-profile wallet. Auth and payer may intentionally differ; a selected payment source never falls back to an ambient wallet. `r.paymentPayer()` reports only safe public payer/source provenance. Also exposes `sites.deployDir(...)`, `fileSetFromDir(...)`, typed deploy-manifest helpers (`loadDeployManifest`, `normalizeDeployManifest`), and `resolveRun402TargetProfile()` for app build scripts that need the same Core/Cloud target the CLI uses.
 
 ```ts
 import { run402 } from "@run402/sdk/node";
@@ -439,7 +439,7 @@ const result = await r.up({ name: "my-app", manifest: "run402.json" }, { approva
 console.log(result);
 ```
 
-The SDK is organised into focused namespaces: `actions` (Node recursive action runner), `pay` (bounded arbitrary-URL x402 buyer), `projects`, `snapshots`, `branches`, `archives`, `assets`, `cache`, `ci`, `sites`, `functions`, `jobs`, `secrets`, `subdomains`, `domains`, `email` (+ `webhooks`), `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `allowance`, `service`, `admin`, `operator` (the human/email operator session: browser-delegated `login` + `overview` across every wallet that verified your email), `wallets` (signed server-side wallet label), `orgs` (org-owned control plane + `r.org(id)` sub-client), `grants` (per-project capability grants), and `identityLinks` (public, protocol-discriminated human/agent Nostr attribution), plus `const project = await r.project(id); await project.apply(spec)` for staged multi-resource writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `PaymentBuyerError`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
+The SDK is organised into focused namespaces: `actions` (Node recursive action runner), `pay` (bounded arbitrary-URL x402 buyer), `projects`, `snapshots`, `branches`, `archives`, `assets`, `cache`, `ci`, `sites`, `functions`, `jobs`, `secrets`, `subdomains`, `domains`, `email` (+ `webhooks`), `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `wallets` (the local wallet: `status`, `create`, `export`, `faucet`; plus the server label), `service`, `admin`, `session` (a person's sign-in session: `run402 login` loopback and `--device` seams plus the browser surface), `writeApproval` (the passkey write approval behind `run402 approve`), `me` (account overview and status), `wallets` (signed server-side wallet label), `orgs` (org-owned control plane + `r.org(id)` sub-client), `grants` (per-project capability grants), and `identityLinks` (public, protocol-discriminated human/agent Nostr attribution), plus `const project = await r.project(id); await project.apply(spec)` for staged multi-resource writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `PaymentBuyerError`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
 
 ## Buzz/Nostr identity links
 
@@ -480,7 +480,7 @@ The file installation stage is inert. Continuing onboarding publishes a durable
 
 See the [`buzz/` guide](./buzz/README.md) for prerequisites, the no-secret signer model, released-client fixtures, migration guidance, and the full workflow, or inspect the exact [`run402-buzz` listing on skills.sh](https://skills.sh/kychee-com/run402/run402-buzz). The low-level CLI commands remain available for debugging, but they are not a competing onboarding path.
 
-The community control plane keeps four concepts separate: installing the skill is inert shared capability; installing a community associates a Buzz relay community with a Run402 organization after dual consent; human adoption records a terminal consent receipt, creates the human's public Buzz identity link, and adds an ordinary owner membership without demoting the founder agent; agent enrollment gives each later agent principal only bounded, expiring grants to named existing projects. The completed receipt, public attribution, and membership remain independent: revoking the link does not remove org authority, and removing the membership does not revoke the link or rewrite the receipt. Buzz itself remains unchanged: approval uses already-shipped browser-fragment/kind-1 behavior plus released NIP-11/NIP-43 evidence, while Run402 owns offers, organizations, descriptor discovery, and lifecycle. `run402 buzz status` capability-detects older gateways; MCP only renders exact HTTPS/CLI handoffs. See the [Fizz/Honey workflow](./buzz/references/community-control-plane.md).
+The community control plane keeps four concepts separate: installing the skill is inert shared capability; installing a community associates a Buzz relay community with a Run402 organization after dual consent; human adoption records a terminal consent receipt, creates the human's public Buzz identity link, and adds an ordinary owner membership without demoting the founder agent; agent enrollment gives each later agent principal only bounded, expiring grants to named existing projects. The completed receipt, public attribution, and membership remain independent: revoking the link does not remove org authority, and removing the membership does not revoke the link or rewrite the receipt. Buzz itself remains unchanged: approval uses already-shipped browser-fragment/kind-1 behavior plus released NIP-11/NIP-43 evidence, while Run402 owns offers, organizations, descriptor discovery, and lifecycle. `run402 buzz status` capability-detects older gateways; MCP only renders exact HTTPS/CLI next steps. See the [Fizz/Honey workflow](./buzz/references/community-control-plane.md).
 
 **Astro SSR + ISR cache.** For Astro apps, use `@run402/astro` 1.0+: `export default run402();` in `astro.config.mjs` returns an `AstroUserConfig` composing the SSR adapter (Lambda + SnapStart + ISR cache + AsyncLocalStorage request-context), image integration, and build-time detectors. Functions opt into the SSR class via `FunctionSpec.class: "ssr"` in `ReleaseSpec`; the gateway provisions SnapStart and caches HTML responses keyed by `(host, path, search, method, locale, release_id)`. Cache is bypass-by-default (no-store unless `Cache-Control` explicitly allows it AND no `Set-Cookie` AND no auth-taint flag from `auth.*` helpers / payment primitives). Invalidate from in-function code or out-of-band: `r.cache.invalidate(url)` / `r.cache.invalidatePrefix({ host, prefix })` / `r.cache.invalidateAll({ host })` (SDK), `run402 cache invalidate <url>` (CLI). Inspect cached state with `r.cache.inspect(url)` / `run402 cache inspect <url>`. Agent DX helpers also in the CLI: `run402 doctor` (5 health checks), `run402 dev` (Astro dev with `.env.local`), `run402 logs --request-id req_...` (correlate across functions). Full reference at [`astro/README.md`](./astro/README.md) and [`cli/llms-cli.txt`](./cli/llms-cli.txt) (R402_* SSR Runtime Error Codes section).
 
@@ -498,7 +498,7 @@ run402 up verify                          # rerun app HTTP verification without
 run402 up --nested -y                     # app root inside another repo: its own nested repo + encrypted remote
 run402 doctor                             # { ok, blocking[], warnings[], checks[] }: ok means this agent can ship
 run402 logs --request-id req_abc123       # every function in the project; app output only (--all for the raw stream)
-run402 init                              # one-shot allowance + faucet + tier check
+run402 init                              # one-shot wallet + faucet + tier check
 run402 pay https://seller.example/resource --max-usd 0.05 --require-receipt
 run402 status                            # organization snapshot (wallet, rail, balances, tier, projects)
 run402 projects provision --name my-app
@@ -507,9 +507,9 @@ run402 projects validate-expose <id> --file manifest.json
 run402 projects apply-expose <id> --file manifest.json
 run402 sites deploy-dir ./dist
 run402 deploy verify op_... --project <id> --wait  # confirm gateway/edge release coherence
-run402 deploy release active --project <id>  # inspect current-live release inventory
-run402 deploy diagnose --project <id> https://example.com/events --method GET
-run402 apply --manifest app.json --json      # rehearses automatically when a live release has migrations to protect
+run402 deploy releases active --project <id>  # inspect current-live release inventory
+run402 deploy resolve https://example.com/events --project <id> --method GET
+run402 deploy --manifest app.json --json     # deploy only; rehearses automatically when a live release has migrations to protect
 run402 snapshots list prj_...
 run402 branches create prj_... --ttl-days 7 --json
 run402 functions deploy <id> <name> --file fn.ts
@@ -520,9 +520,9 @@ run402 assets diagnose <url>             # inspect live CDN state for a public U
 run402 cdn wait-fresh <url> --sha <hex>  # poll until a mutable URL serves the new SHA
 ```
 
-`up` is the only compound CLI command: it calls the SDK action runner, emits `steps[]`, and writes `.run402/project.json` when it needs to remember the workspace project. Against run402 Core it skips Cloud allowance/tier prerequisites and fails closed if no Core project is selected.
+`up` is the only compound CLI command: it calls the SDK action runner, emits `steps[]`, and writes `.run402/project.json` when it needs to remember the workspace project. Against run402 Core it skips Cloud wallet/tier prerequisites and fails closed if no Core project is selected.
 
-Rehearsal is automatic: a migration-bearing `run402 up` / `run402 apply` against a project with a live release is rehearsed on a contained branch and committed only on a passing report (`result.deploy.rehearsal`); a first deploy has nothing to protect and commits directly (`reason: "no_live_release"`), and a redeploy whose migrations are all already applied with identical checksums is skipped as `migrations_unchanged`, so a page-only redeploy that still carries its migrations ships in seconds. `--no-rehearse` skips it. ADVANCED: `run402 deploy rehearse [<plan_id>] [--manifest <path>]` rehearses without committing — from a persisted plan, or from the manifest in the current directory (plan, upload, rehearse). Manual restore points live under `run402 snapshots create|list|get|restore|delete`; restore is a two-step plan/confirm flow. Branch projects live under `run402 branches create|list|renew|delete`, default to a 7-day TTL, use sandboxed email by default, and are marked noindex; a parent with no live release yields an empty branch.
+Rehearsal is automatic: a migration-bearing `run402 up` / `run402 deploy` against a project with a live release is rehearsed on a contained branch and committed only on a passing report (`result.deploy.rehearsal`); a first deploy has nothing to protect and commits directly (`reason: "no_live_release"`), and a redeploy whose migrations are all already applied with identical checksums is skipped as `migrations_unchanged`, so a page-only redeploy that still carries its migrations ships in seconds. `--no-rehearse` skips it. ADVANCED: `run402 deploy rehearse [<plan_id>] [--manifest <path>]` rehearses without committing — from a persisted plan, or from the manifest in the current directory (plan, upload, rehearse). Manual restore points live under `run402 snapshots create|list|get|restore|delete`; restore is a two-step plan/confirm flow. Branch projects live under `run402 branches create|list|renew|delete`, default to a 7-day TTL, use sandboxed email by default, and are marked noindex; a parent with no live release yields an empty branch.
 
 Your HTML never needs a pasted key: every Run402 host serves `/_run402/config.js` (`window.RUN402 = { project_id, api_base, anon_key }`) for the project it resolves to. `run402 up` also names this principal when it has none — `RUN402_AGENT_NAME` if your runtime declares one (it overrides an existing name), else a detected client (`claude-code`, `codex`, `cursor`, `grok`; `RUN402_CLIENT=<name>` declares a client with no marker of its own, checked first); when nothing is known nothing is written — so promotion credit names you; set it any time with `run402 org whoami --set-name <name>`. `result.identity` always reports `detected` (the client seen this run) and `detection: { applied, reason }`, where `name_already_set` means a client was detected but the principal already had a name. `projects provision` never touches git; `up` scaffolds a `run402` remote on the app root only, and an app root inside another repository is skipped with a `create_nested_repo` next action unless you pass `--nested`, which makes it its own nested repository (one line appended to the enclosing repository's local `.git/info/exclude`, nothing else touched).
 
@@ -559,7 +559,7 @@ RUN402_MCP_PROFILE=buyer npx -y run402-mcp
 | *(unset — default)* | 198 | ~43,200 |
 | `buyer` | **8** | **~740** |
 
-The eight: `generate_image` · `init` · `check_balance` · `allowance_status` · `lightning_wallet` · `allowance_export` · `request_faucet` · `redeem_voucher` — enough to bootstrap a wallet, fund it (from the faucet or a promo code), check it, and buy. **Local, so it can actually pay:** an x402 payment needs a signing key, so a wallet-less remote server cannot make one.
+The eight: `generate_image` · `init` · `check_balance` · `wallet_status` · `lightning_wallet` · `wallet_export` · `request_faucet` · `redeem_voucher` — enough to bootstrap a wallet, fund it (from the faucet or a promo code), check it, and buy. **Local, so it can actually pay:** an x402 payment needs a signing key, so a wallet-less remote server cannot make one.
 
 Default is unchanged when the variable is unset. An unknown profile name **exits 1** with the known-profile list rather than silently serving the full surface or nothing.
 
@@ -637,7 +637,7 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 | `get_schema` | Introspect tables, columns, types, constraints, RLS policies. |
 | `get_usage` | Per-project usage report (API calls, storage, lease expiry). |
 | `promote_user` / `demote_user` | Manage `project_admin` role on a project user. |
-| `delete_project` | Cascade purge: schema, Lambdas, S3 site files, deployments, secrets, published versions. Irreversible. |
+| `delete_project` | Cascade purge: schema, Lambdas, S3 site files, releases, secrets, published releases. Irreversible. |
 
 ### Asset storage (content-addressed CDN)
 
@@ -657,13 +657,13 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 |------|-------------|
 | `deploy_site` | Deploy a static site from inline file bytes. |
 | `deploy_site_dir` | Deploy a static site from a local directory. Routes through the unified apply primitive (CAS-backed); only uploads bytes the gateway doesn't have. |
-| `claim_subdomain` | Claim `<name>.run402.com` (idempotent; binds the live release unless `release_id` / `deployment_id` is given; reassigns to latest deployment on subsequent deploys). |
+| `add_subdomain` | Claim `<name>.run402.com` (idempotent; binds the live release unless `release_id` / `deployment_id` is given; reassigns to latest deploy on subsequent deploys). |
 | `list_subdomains` / `delete_subdomain` | Manage subdomains. |
 | `domains_ensure` / `domains_get` / `domains_list` / `domains_check` | Manage project-scoped web/email ProjectDomain desired state and health checks. |
 | `domains_apply` / `domains_repair` / `domains_test_receive` / `domains_activate` / `domains_disconnect` | Apply safe provider actions, repair run402-owned routing, verify inbound receive, activate mailbox addresses, or disconnect a domain. |
 | `deploy` / `deploy_resume` / `deploy_rehearse` / `deploy_list` / `deploy_events` / `deploy_verify_edge` | Apply (rehearsal is automatic when a live release has migrations to protect), resume, ADVANCED-rehearse a persisted plan on a contained branch, list, inspect deploy operations, and verify gateway/edge coherence. |
-| `deploy_release_get` / `deploy_release_active` / `deploy_release_diff` | Inspect release inventory and release-to-release diffs without starting a new deploy mutation. |
-| `deploy_diagnose_url` | URL-first deploy resolver diagnostics. Params: `project_id`, either `url` or `host`/`path`, optional `method`; returns `would_serve`, `diagnostic_status`, `match`, warnings, next steps, and fenced JSON. |
+| `deploy_releases_get` / `deploy_releases_active` / `deploy_releases_diff` | Inspect release inventory and release-to-release diffs without starting a new deploy mutation. |
+| `deploy_resolve` | Deploy resolver diagnostics for a public URL. Params: `project_id`, either `url` or `host`/`path`, optional `method`; returns `would_serve`, `diagnostic_status`, `match`, warnings, next steps, and fenced JSON. |
 
 ### Snapshots & branches
 
@@ -737,18 +737,18 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 | `get_app` | Inspect an app, including expected `bootstrap_variables`. |
 | `fork_app` | Clone schema + site + functions into a new project. Runs the app's `bootstrap` function with provided variables. |
 | `publish_app` | Publish a project as a forkable app. |
-| `list_versions` / `update_version` / `delete_version` | Manage published versions. |
+| `list_versions` / `update_version` / `delete_version` | Manage published releases. |
 
 ### Tier & billing
 
 | Tool | Description |
 |------|-------------|
-| `set_tier` | Subscribe / renew / upgrade a tier (auto-detects action). x402 or MPP payment. |
+| `tier_set` | Set the tier: start / renew / upgrade the lease (auto-detects action). x402 or MPP payment. |
 | `tier_status` | Current tier, lease expiry, usage, and function authoring caps when returned. |
 | `get_quote` | Tier pricing (free, no auth). |
 | `create_email_organization` / `link_wallet_to_organization` | Email-based organizations; hybrid Stripe + x402. |
 | `create_checkout` | Org checkout for balance top-ups, tiers, or email packs. |
-| `create_lightning_topup` | Top up the cash balance over Lightning: mints a bolt11 invoice; pay from any wallet. |
+| `create_lightning_topup` | Top up the allowance over Lightning: mints a bolt11 invoice; pay from any wallet. |
 | `get_topup` | Read a Lightning top-up (pending, paid, paid_late, expired). |
 | `billing_history` | Ledger history. |
 | `set_auto_recharge` | Auto-buy email packs when credits run low. |
@@ -766,17 +766,17 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 | `drain_signer` | Drain native balance (works on suspended signers, the safety valve). |
 | `delete_signer` | Schedule KMS key deletion (refused if balance ≥ dust). |
 
-### Allowance & organization
+### Wallet & organization
 
 | Tool | Description |
 |------|-------------|
-| `init` | One-shot setup: allowance + faucet + tier check + project list. |
-| `status` | Full organization snapshot (allowance, balance, tier, projects). |
-| `allowance_status` / `allowance_create` / `allowance_export` | Local allowance management. |
-| `lightning_wallet` | The Lightning allowance: mint the agent's budgeted wallet on Run402's Hub (pairing stored locally, Lightning becomes the default rail), read it, or revoke it. |
+| `init` | One-shot setup: wallet + faucet + tier check + project list. |
+| `status` | Full organization snapshot (wallet, allowance, tier, projects). |
+| `wallet_status` / `wallet_create` / `wallet_export` | Local wallet management. |
+| `lightning_wallet` | The Lightning wallet: mint the agent's budgeted wallet on Run402's Hub (pairing stored locally, Lightning becomes the default rail), read it, or revoke it. |
 | `request_faucet` | Request testnet USDC. |
-| `redeem_voucher` | Redeem a promo code for run402 prepaid credit. |
-| `check_balance` | USDC balance for an allowance address. |
+| `redeem_voucher` | Redeem a promo code into the organization's allowance. |
+| `check_balance` | The organization's allowance for a wallet address. |
 | `list_projects` | Named, domain-aware project inventory (name, site_url, custom_domains, org). Membership-scoped; supports `org_id` filter, `all` cross-wallet read, and pagination. |
 | `list_tenant_payments` | Redacted tenant x402 payment history for priced function routes on a project. |
 | `rename_project` | Rename a project to fix an auto-generated name (org admin / `project:write` grant). |
@@ -784,23 +784,25 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 | `project_get` / `project_use` | Server project detail and active-project selection. `project_use` validates through the server, then stores only an active id pointer. |
 | `project_key_cache_status` / `project_key_cache_export` | Explicit local project-key cache tools. `status` is redacted; `export` requires `reveal: true` and emits cached secret key material. |
 | `create_checkout` | Org checkout for balance top-ups, tiers, or email packs. |
-| `create_lightning_topup` | Top up the cash balance over Lightning: mints a bolt11 invoice; pay from any wallet. |
+| `create_lightning_topup` | Top up the allowance over Lightning: mints a bolt11 invoice; pay from any wallet. |
 | `get_topup` | Read a Lightning top-up (pending, paid, paid_late, expired). |
-| `send_feedback` | Send feedback to the run402 team. Write-only: no inbox, no reply path. Optional `project_id` + `handle` relay a deploy's promotion consent (`hand_to_operator` next action). |
-| `set_agent_contact` / `get_agent_contact_status` / `verify_agent_contact_email` | Register agent contact info, read assurance status, and start the operator email reply challenge. |
-| `start_operator_passkey_enrollment` | Email a run402 operator passkey enrollment link to the verified contact email. |
-| `get_operator_status` | Compact operator-health snapshot: contact assurance state, critical items, skipped notifications, organizations, projects, active thresholds. Read via `run402 doctor` or directly. |
-| `get_notification_preferences` / `set_notification_preferences` | Read/update operator notification preferences (cadence, channels, per-class toggles, locale, timezone). Cross-wallet effects require `email_verified`; webhook URL changes require `operator_passkey`. |
+| `send_feedback` | Send feedback to the run402 team. Write-only: no inbox, no reply path. Optional `project_id` + `handle` relay a deploy's promotion consent (`hand_to_member` next action). |
+| `set_agent_contact` / `get_agent_contact_status` / `verify_agent_contact_email` | Register agent contact info, read assurance status, and start the owner email reply challenge. |
+| `start_contact_passkey_enrollment` | Email a run402 passkey enrollment link to the verified contact email. |
+| `get_notification_preferences` / `set_notification_preferences` | Read/update owner notification preferences (cadence, channels, per-class toggles, locale, timezone). Cross-wallet effects require `email_verified`; webhook URL changes require `operator_passkey`. |
 | `list_notifications` | Per-delivery-attempt audit log. Paginated, filterable by event_type / since. |
 | `test_notification` | Fire a real test notification through the full worker pipeline. Audit row marked `is_test=true`. Rate-limited per wallet at 1/min. |
-| `rotate_webhook_secret` | Generate a new HMAC signing secret for the operator webhook (returned exactly once). Previous secret remains valid for 24h. Requires `operator_passkey`. |
-| `list_project_events` | Cursored project events feed — catch up on deploy activations, suspensions, transfers, lifecycle cliffs since your stored cursor. Also reads the org-wide union via `org_id`. Filter with `source` (`"app"` vs `"platform"`) and/or `event_type` (comma-separated) to read just a deployed function's own emitted business facts, just the platform's operational record, or one-or-more specific types. |
+| `rotate_webhook_secret` | Generate a new HMAC signing secret for the notification webhook (returned exactly once). Previous secret remains valid for 24h. Requires passkey assurance (`operator_passkey`). |
+| `list_project_events` | Cursored project events feed — catch up on deploy activations, suspensions, transfers, lifecycle cliffs since your stored cursor. Also reads the org-wide union via `org_id`. Filter with `source` (`"app"` vs `"platform"`) and/or `event_type` (comma-separated) to read just a deployed function's own emitted business events, just the platform's operational record, or one-or-more specific types. |
 | `errors_list` | Grouped error fingerprints + a release-baselined promote/revert verdict. Poll with `new_in` after a promote to gate on new error identities; pass `fingerprint_id` for one identity's full detail. |
 
 ### Agent messaging (coordination rooms)
 
 | Tool | Description |
 |------|-------------|
+| `list_rooms` | Which rooms this credential can reach in an org (`org_id`, or `project_id` for its owning org). Rooms are derived from use — a key nobody has written under is not listed. Returns `{rooms: [{org_id, room_key, project_id, live_presences, last_activity_at}]}`, newest activity first. |
+| `get_room` | Look at one room WITHOUT joining it: live presences and last activity. An unused key reads as empty, never 404. A room key is a label: a project id (`prj_…`) or any label matching `/^[a-z0-9][a-z0-9._-]{0,63}$/`. |
+| `leave_room` | Release this session's presence (or a named one of your own principal) so it stops reading as live and stops holding its claims. Idempotent: already gone reports `left: false`. |
 | `join_room` | Arrive in a project's coordination room: register this session's presence (`requested_name` honored-or-suffixed, `Opus` → `Opus-2`) and see who else is live, what they're working on, and what they've claimed. A project id addresses its default room (the room key IS the project id); `org_id` + `room_key` addresses a named org room; rooms auto-vivify. |
 | `send_room_message` | Durable room-visible message (markdown, ≤32 KiB). `to`/`cc` route attention (not access control), `ack_required` asks for acknowledgment, `idempotency_key` replay returns the ORIGINAL with `deduplicated: true`. Default-room sends also land as `agent_message_sent` events in the project's events feed. |
 | `read_room_messages` | Cursored catch-up on what the other agents said (opaque `mcr_…` cursor; stale cursor → `reset: true` + `earliest_cursor`, never an error), `unread`-only filtering, thread filtering, or one FULL message by `message_id`. `wait` (1..25 seconds) holds this ONE read until a matching message lands or the wait elapses — the agent's ear, one server-side hold, no client loop; answers the ordinary page either way plus `waited_ms` and `live_presences[]`. No MCP tool exists for `repos invite`/`repos join` (a bearer secret is minted/spent and org membership mutated — the CLI-only reasoning below) — `run402 messages wait` on the CLI is the blocking version for a coding harness that wants to poll less. |
@@ -808,7 +810,7 @@ The full MCP surface: every tool is a thin shim over an SDK call.
 | `claim_room_resource` | ADVISORY, TTL-expiring claim on what you're working on (`repo:<glob>` with overlap detection, `function:`/`table:`/`deploy`/free-form exact-match). Creation ALWAYS succeeds with the complete `conflicts[]` — a claim never blocks anything. |
 | `release_room_claim` | Release a claim you hold (idempotent; holder only). Pair with a `send_room_message` handoff note. |
 
-**Bringing a stranger's agent into the room (CLI/SDK only, no MCP tool).** `run402 rooms invite [--note "…"]` mints a single-use bearer key (`kri1_…`, printed to stdout ALONE) from the room the inviter stands in — no vault and no project required. `run402 rooms join kri1_…` folds a funded-wallet chain (allowance → faucet if the balance is zero → a brief settlement wait) and pays a one-cent testnet x402 seat to claim it — the payment IS the join — arriving as a permanent **`viewer`**, the narrowest membership that can message, never widened from this door (no `--role`, ever, and a viewer is never auto-admitted as a vault writer — bring a collaborator into the CODE with `run402 repos invite` instead). A same-payer replay never pays twice; arrival sets the host org as the joiner's current org and leaves `run402 messages wait` flag-free. Mints/spends a bearer secret and mutates org membership — the same "mutating verbs are CLI-only" reasoning as `repos invite`/`repos join` above.
+**Bringing a stranger's agent into the room (CLI/SDK only, no MCP tool).** `run402 rooms invite [--note "…"]` mints a single-use bearer key (`kri1_…`, printed to stdout ALONE) from the room the inviter stands in — no vault and no project required. `run402 rooms join kri1_…` folds a funded-wallet chain (wallet → faucet if the balance is zero → a brief settlement wait) and pays a one-cent testnet x402 fee to claim it — the payment IS the join — arriving as a permanent **`viewer`**, the narrowest membership that can message, never widened from this door (no `--role`, ever, and a viewer is never auto-admitted as a vault writer — bring a member into the CODE with `run402 repos invite` instead). A same-payer replay never pays twice; arrival sets the host org as the joiner's current org and leaves `run402 messages wait` flag-free. Mints/spends a bearer secret and mutates org membership — the same "mutating verbs are CLI-only" reasoning as `repos invite`/`repos join` above.
 
 ### Agent escalations (the hotline to a human)
 
@@ -823,10 +825,10 @@ Contact management (who gets paged) is CLI/SDK only by design — an agent raise
 
 | Tool | Description |
 |------|-------------|
-| `get_buzz_route` | One route's honest `health` (derived from route + credential state, never queue emptiness) with per-status delivery counts and the `revision` an update must echo — or the org's route list when the route id is omitted. A `pending_authorization` route prints the non-secret handoff (a Buzz community owner adds the `notification_pubkey` as a relay member) and the exact verify command. |
+| `get_buzz_route` | One route's honest `health` (derived from route + credential state, never queue emptiness) with per-status delivery counts and the `revision` an update must echo — or the org's route list when the route id is omitted. A `pending_authorization` route prints the non-secret step (a Buzz community owner adds the `notification_pubkey` as a relay member) and the exact verify command. |
 | `list_buzz_route_deliveries` | Did it actually land? Keyset newest-first delivery history — dead letters included, the signed envelope never. `queued`/`retryable` are in flight (the publisher tick runs ~every 60s; retries back off to 8 attempts / 48h, then `dead_letter`); `nostr_event_id` appears on delivered rows. |
 
-Route mutations (configure / test / pause / resume / rotate / revoke) are CLI/SDK only by design — they need owner step-up, and configure/rotate hand off a Buzz-side authorization a human completes: `run402 buzz notifications configure --org <uuid> --installation <buzzci_id> --name <route_name> --channel <nip29-channel-id> --project <id>`. No surface anywhere accepts or prints a signing secret. Buzz is never a deadman channel: mandatory operator notifications keep their human paths regardless of route state.
+Route mutations (configure / test / pause / resume / rotate / revoke) are CLI/SDK only by design — they need owner step-up, and configure/rotate hand off a Buzz-side authorization a human completes: `run402 buzz notifications configure --org <uuid> --installation <buzzci_id> --name <route_name> --channel <nip29-channel-id> --project <id>`. No surface anywhere accepts or prints a signing secret. Buzz is never a deadman channel: mandatory owner notifications keep their human paths regardless of route state.
 
 ### repos (read-only) — the host-blind encrypted git repo family
 
@@ -854,14 +856,14 @@ The repo's mutating verbs are deliberately CLI-only. `snapshot` / `create` write
 | `RUN402_API_BASE`        | `https://api.run402.com`         | API base URL (override for staging) |
 | `RUN402_CONFIG_DIR`      | `~/.config/run402`               | Local credential storage base directory (named wallets live under `profiles/<name>/`) |
 | `RUN402_WALLET`          | `default`                        | Active named wallet (profile). Overridden by `--wallet <name>` and per-directory `.run402.json`; `RUN402_PROFILE` is an alias. See `run402 wallets`. |
-| `RUN402_ALLOWANCE_PATH`  | `{config_dir}/allowance.json`    | Custom allowance file path |
+| `RUN402_WALLET_PATH`  | `{config_dir}/wallet.json`    | Custom wallet file path |
 | `RUN402_MCP_PROFILE`     | *(unset — all 198 tools)*        | `run402-mcp` only. `buyer` registers just the 6 tools a buy-only agent needs (~660 tokens instead of ~43,200). Unknown name exits 1. |
 
 Local state lives at:
 
 - profile `state.json`: active project pointer and profile state
 - profile `credentials/project-keys.v1.json` (`0600`): local anon/service key cache for explicit credential-required operations
-- `~/.config/run402/allowance.json` (`0600`): wallet for x402 / MPP signing
+- `~/.config/run402/wallet.json` (`0600`): wallet for x402 / MPP signing
 
 Legacy `projects.json` files are one-way migration input only. `anon_key` and `service_key` have no expiry; lease enforcement happens server-side. Inspect cache state with `run402 credentials project-keys status --project <id>` and export secrets only with `run402 credentials project-keys export --project <id> --reveal`.
 
@@ -875,7 +877,7 @@ npm run test:sync       # checks MCP/CLI/OpenClaw/SDK stay in sync
 npm run test:skill      # validates SKILL.md frontmatter + body
 ```
 
-Architecture: every tool / subcommand / skill script is a thin shim over an `@run402/sdk` call. `core/` holds Node-only filesystem primitives (keystore, allowance, SIWE signing) wrapped by the SDK's Node provider. See [`CLAUDE.md`](./CLAUDE.md) for the full layout.
+Architecture: every tool / subcommand / skill script is a thin shim over an `@run402/sdk` call. `core/` holds Node-only filesystem primitives (keystore, wallet, SIWE signing) wrapped by the SDK's Node provider. See [`CLAUDE.md`](./CLAUDE.md) for the full layout.
 
 ## Links
 

package/core/dist/config.d.ts

@@ -39,7 +39,7 @@ export declare function getProfilesDir(): string;
  * The effective config directory for the *active* wallet. The `default` wallet
  * resolves to the base dir (zero migration for existing single-wallet
  * installs); any named wallet resolves to `{base}/profiles/<name>`. Because
- * keystore, allowance, and meta paths all derive from this, switching the
+ * keystore, wallet, and meta paths all derive from this, switching the
  * profile env var moves the whole wallet bundle atomically — and the SDK/MCP
  * inherit profile selection for free.
  */
@@ -57,5 +57,19 @@ export declare function configureApiBase(apiBase: string, options?: Omit<ApiTarg
 export declare function getConfiguredApiBase(): string | null;
 export declare function getApiTargetKind(): ApiTargetKind;
 export declare function isCoreApiTarget(): boolean;
-export declare function getAllowancePath(): string;
+/**
+ * The file that holds a wallet's key, in the base config dir (the `default`
+ * wallet) and in each `profiles/<name>/` directory.
+ */
+export declare const WALLET_FILE_NAME = "wallet.json";
+/**
+ * One-time local move of the wallet key file to its current name: in the base
+ * config dir and every `profiles/<name>/` directory, `allowance.json` is
+ * renamed to `wallet.json` (an atomic same-directory rename) when
+ * `wallet.json` is absent, then tightened to 0600. A directory that already
+ * holds `wallet.json` is left untouched. Runs once per base dir per process;
+ * nothing reads the previous name afterwards.
+ */
+export declare function moveWalletFiles(): void;
+export declare function getWalletPath(): string;
 //# sourceMappingURL=config.d.ts.map