docs: split llms.txt; add per-surface llms-{sdk,mcp,cli}.txt set

Restructures the agent-facing reference docs. The site previously
served a single llms.txt that conflated wayfinder duties with API
reference; that file is now split:

- llms.txt (root, NEW): high-level wayfinder. Vision, what we offer,
  the four integration surfaces (SDK ⭐ recommended, CLI, MCP, raw
  HTTP), pricing summary, 30-second start, links to each surface's
  deep reference. ~130 lines.
- sdk/llms-sdk.txt (NEW): comprehensive SDK reference. Two entry
  points, all 19 namespaces with method signatures, the four patterns,
  full Run402Error hierarchy with Run402DeployError envelope,
  ReleaseSpec shape, stability + lockstep notes. ~560 lines.
- llms-mcp.txt (root, NEW): comprehensive MCP reference. Every tool
  with parameters, the four patterns, error-envelope branching,
  troubleshooting, install per host. ~420 lines.
- cli/llms-cli.txt (existing): unchanged — already the canonical
  comprehensive CLI reference.

All four are served from run402.com via the private-repo deploy
pulling them. The wayfinder points at the three sub-references plus
llms-full.txt (still in the private repo, the HTTP API reference).

documentation.md restructure:
- Adds rows for the three new files in the public-repo table.
- Removes deploy-pulled mirror rows (site/llms-cli.txt, site/SKILL.md)
  and site/llms.txt from the private-repo section — the public-repo
  source rows are authoritative; their site copies refresh on deploy.
- Removes website-only rows (site/humans/*, site/use-cases/*,
  site/agent-allowance/) — out of scope per "this report doesn't
  look at the website."
- Keeps the genuinely-private docs: site/llms-full.txt (HTTP API
  reference), site/updates.txt, site/humans/changelog.md.
- Refreshes the change-trigger map and canonicality notes for the
  new structure (a new SDK method now flags llms-sdk.txt; a new MCP
  tool now flags llms-mcp.txt; etc.). Adds a "new integration
  surface" trigger.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

documentation.md

@@ -2,7 +2,7 @@
 
 Single source of truth for every agent- and developer-facing documentation surface in the run402 ecosystem. **Use this as a checklist when changing code:** for each surface you touched, scan the tables below and update every doc that mentions it.
 
-The same code change rarely lands in just one doc. A new MCP tool needs a row in [README.md](README.md) *and* a tools-by-category entry in [SKILL.md](SKILL.md) *and* a `SURFACE` entry in `sync.test.ts`. A new CLI subcommand belongs in [cli/llms-cli.txt](cli/llms-cli.txt) *and* the public-site `site/llms-cli.txt` (deploy-pulled). Don't ship without scanning.
+The same code change rarely lands in just one doc. A new MCP tool needs a row in [README.md](README.md) *and* a tools-by-category entry in [SKILL.md](SKILL.md) *and* a section in [llms-mcp.txt](llms-mcp.txt) *and* a `SURFACE` entry in `sync.test.ts`. A new CLI subcommand belongs in [cli/llms-cli.txt](cli/llms-cli.txt) *and* [openclaw/SKILL.md](openclaw/SKILL.md). A new SDK method belongs in [sdk/llms-sdk.txt](sdk/llms-sdk.txt). Don't ship without scanning.
 
 ## How to use
 
@@ -31,7 +31,10 @@ Status is a snapshot — refresh it whenever the underlying doc changes.
 | 🟢 | [`openclaw/SKILL.md`](openclaw/SKILL.md) | OpenClaw script-runtime agents | Same content as `SKILL.md` but every verb is `run402 <…>` (CLI shape). Frontmatter `install: run402` (the CLI). | A CLI subcommand is added/removed; a pattern changes; a troubleshooting case is discovered |
 | 🟢 | [`SKILL.test.ts`](SKILL.test.ts) | CI | Validates frontmatter + required CLI verbs / MCP tool names / banned regressions for **both** SKILL files | Whenever a "canonical" verb or tool name moves in/out of either skill |
 | 🟢 | [`cli/README.md`](cli/README.md) | Humans on GitHub + the [`run402` npm page](https://www.npmjs.com/package/run402) | 30-second start, common-command examples per category, state-on-disk note, **points at `llms-cli.txt` as authoritative** | Major CLI surface change; install flow change; new top-level command group |
-| 🟢 | [`cli/llms-cli.txt`](cli/llms-cli.txt) | AI agents fetching CLI reference (canonical) | Every subcommand, every flag, every flow, troubleshooting. Served at <https://run402.com/llms-cli.txt> via private-repo deploy pulling this file | **Any** CLI subcommand or flag added/removed/renamed |
+| 🟢 | [`llms.txt`](llms.txt) | AI agents fetching <https://run402.com/llms.txt> (entry point) | High-level wayfinder. Vision, what we offer, the four integration surfaces (SDK ⭐ recommended, CLI, MCP, raw HTTP), pricing summary, 30-second start, links to each surface's deep reference. Served at run402.com/llms.txt via private-repo deploy pulling this file | Vision / what-we-offer / pricing changes; new integration surface added; surface-recommendation order changes |
+| 🟢 | [`cli/llms-cli.txt`](cli/llms-cli.txt) | AI agents fetching <https://run402.com/llms-cli.txt> | Comprehensive CLI reference. Every subcommand, every flag, every flow, troubleshooting. Served via private-repo deploy pulling this file | **Any** CLI subcommand or flag added/removed/renamed |
+| 🟢 | [`sdk/llms-sdk.txt`](sdk/llms-sdk.txt) | AI agents fetching <https://run402.com/llms-sdk.txt> | Comprehensive SDK reference. Two entry points, all 19 namespaces with method signatures, the four patterns, full `Run402Error` hierarchy with `Run402DeployError` envelope, `ReleaseSpec` shape, stability + lockstep notes. Served via private-repo deploy pulling this file | Any SDK method or namespace added/changed; `ReleaseSpec` shape changes; new error class lands |
+| 🟢 | [`llms-mcp.txt`](llms-mcp.txt) | AI agents fetching <https://run402.com/llms-mcp.txt> | Comprehensive MCP reference. Every tool with parameters, the four patterns, error-envelope branching, troubleshooting, install snippets per host. Served via private-repo deploy pulling this file | Any MCP tool added/removed/renamed; pattern changes; new install host needs documenting |
 | 🟢 | [`sdk/README.md`](sdk/README.md) | TypeScript devs / agents using the SDK; the [`@run402/sdk` npm page](https://www.npmjs.com/package/@run402/sdk) | Two entry-point install matrix (Node vs isomorphic), full 19-namespace catalog table, paste-and-go AssetRef pattern, unified `r.deploy.apply` v1.34+ primitive (with three layers + `fileSetFromDir`), full error hierarchy including `Run402DeployError`, stability + lockstep notes | New SDK namespace / method; new error class; entry-point changes |
 | 🟢 | [`functions/README.md`](functions/README.md) | TypeScript devs / agents using `@run402/functions`; the [`@run402/functions` npm page](https://www.npmjs.com/package/@run402/functions) | In-function helper API — `db(req)` / `adminDb()` / `getUser()` / `email` / `ai` with examples, fluent surface, `adminDb().sql()` parameterized SQL, SSG build-time use, deploy-time bundling note ("don't list in `--deps`") | `db`/`adminDb`/`getUser`/`email`/`ai` surface changes; new in-function helper lands; bundling rules change |
 | 🟢 | [`openclaw/README.md`](openclaw/README.md) | Humans browsing the `openclaw/` folder on GitHub | Install instructions, the script-runtime mechanism (re-export from CLI), pointer at `openclaw/SKILL.md` for the full body, the SKILL.md (root) vs openclaw/SKILL.md split, modern patterns callout (paste-and-go / expose manifest / deploy-dir / db(req)), OpenClaw-vs-MCP comparison | Major skill or install-flow change; SKILL split changes |
@@ -41,38 +44,37 @@ Status is a snapshot — refresh it whenever the underlying doc changes.
 
 ## Private repo (`run402-private/site/`)
 
-These files live in the **private repo** at `~/Developer/run402-private/site/`. The site is deployed to <https://run402.com>. Some files are auto-pulled from this public repo at deploy time.
+Only listed here are files that **originate in the private repo** — i.e., authored and edited there directly. Deploy-pulled mirrors of public-repo files (the public-repo source rows above are authoritative — edit those, then redeploy the site to refresh) are deliberately omitted. Marketing / legal / topic pages are website concerns, also out of scope.
 
 | Status | File | Audience | What's there | Update when… |
 |:------:|------|----------|--------------|--------------|
-| 🔴 | `site/llms.txt` | AI agents fetching <https://run402.com/llms.txt> | Canonical HTTP API reference. Has the expose-manifest section. **Bug:** lines ~528–530 still tell agents to use `"inherit": true` — flag was removed in v1.32 (agents following the doc verbatim fail). **Missing:** AssetRef pattern, `@run402/sdk` package mention, deploy-dir, plan/commit transport | Fix the inherit bug; add AssetRef + SDK + deploy-dir + plan/commit sections; align with current public docs |
-| 🔴 | `site/llms-cli.txt` | (deploy-pulled copy of public `cli/llms-cli.txt`) | Currently 200+ lines behind the public source. **Bug:** line ~377 also has the removed `--inherit` flag | Auto-fixes on next site deploy. To trigger: deploy the site after merging `cli/llms-cli.txt` changes |
-| 🔴 | `site/llms-full.txt` | AI agents wanting deep / long-form reference | Header says "Long-Form Documentation", but body **only covers KMS contract wallets**. Misleading scope — none of v1.31–v1.46 (expose, AssetRef, deploy-dir, etc.) | Either expand to cover other deep-dive subsystems, or rename to `kms-wallets.txt` so its scope is honest |
-| 🟡 | `site/SKILL.md` | (deploy-pulled copy of public `SKILL.md`) | Stale copy from before the recent MCP-rewrite | Auto-fixes on next site deploy |
-| 🟡 | `site/updates.txt` | AI-readable changelog | Has 2026-04-28 (functions bundling) and 2026-04-29 (error envelopes) entries. **Missing backfill** for v1.31 expose-manifest, v1.32 plan/commit, v1.33 blob CDN, v1.34 unified deploy, v1.45 paste-and-go AssetRef, legacy storage shim sunset | Backfill the missing v1.31–v1.45 entries; new entries on every user-visible feature ship |
-| 🟡 | `site/humans/changelog.md` | Human-readable changelog (rendered to `/humans/changelog.html`) | Mirrors `updates.txt` — same gaps | Backfill in lockstep with `updates.txt` |
-| ⚪ | `site/index.md`, `site/humans/*.md`, `site/use-cases/*` | Marketing / legal / product pages | Pricing, terms, privacy, vision, FAQ, use-case landings — not audited in this pass | Pricing or legal changes; new positioning; new use case |
-| ⚪ | `site/agent-allowance/`, `site/billing/`, `site/apps/`, etc. | Topic-specific docs pages | Per-topic explainer + agent flow — not audited in this pass | Topic-specific feature changes |
+| 🔴 | `site/llms-full.txt` | AI agents fetching <https://run402.com/llms-full.txt> — the HTTP API reference | Comprehensive HTTP / `curl`-shaped reference: every endpoint, request/response shapes, auth header rules, pricing, lifecycle. Currently a symlink to `site/llms.txt` and historically scoped only to KMS contract wallets — **needs to be split out and rewritten as the canonical HTTP API reference** | API surface (HTTP routes, request/response shape, auth) changes; new endpoint ships |
+| 🟡 | `site/updates.txt` | AI-readable changelog (`/updates.txt`) | `## YYYY-MM-DD` headings, newest first. Has 2026-04-28 (functions bundling) and 2026-04-29 (error envelopes). **Missing backfill** for v1.31 expose-manifest, v1.32 plan/commit, v1.33 blob CDN, v1.34 unified deploy, v1.45 paste-and-go AssetRef, legacy storage shim sunset | Backfill the missing v1.31–v1.45 entries; new entry on every user-visible feature ship |
+| 🟡 | `site/humans/changelog.md` | Human-readable changelog (rendered to `/humans/changelog.html`) | Mirrors `updates.txt` in prose form — same gaps | Backfill in lockstep with `updates.txt` |
 
 ## Common change → docs to update
 
 When you… | Update at minimum…
 ---|---
-**Add or remove an MCP tool** | `src/index.ts` (registration), `sync.test.ts` (`SURFACE` + `SDK_BY_CAPABILITY`), [README.md](README.md) (tools table), [SKILL.md](SKILL.md) (tools by category), `cli/llms-cli.txt` if there's a sibling CLI subcommand
-**Add or remove a CLI subcommand** | `cli/lib/<group>.mjs` (impl), `sync.test.ts` (`SURFACE`), [cli/llms-cli.txt](cli/llms-cli.txt) (canonical reference), [openclaw/SKILL.md](openclaw/SKILL.md) (CLI verbs), [cli/README.md](cli/README.md) only if it's a new top-level group, mirror sibling MCP tool docs
-**Add an SDK namespace** | `sdk/src/namespaces/<name>.ts`, [sdk/README.md](sdk/README.md) (namespace list), [AGENTS.md](AGENTS.md) (architecture diagram namespace count), [README.md](README.md) (namespace count), `sync.test.ts` (`SDK_BY_CAPABILITY`)
-**Change `@run402/functions` surface** | `functions/src/`, `functions/README.md` (when it exists), [AGENTS.md](AGENTS.md) (Functions library section), [SKILL.md](SKILL.md) and [openclaw/SKILL.md](openclaw/SKILL.md) (in-function helpers section)
-**Rename / remove a tool, command, or flag** | All of the above + verify [SKILL.test.ts](SKILL.test.ts) banned-pattern list catches it; consider an `updates.txt` entry if user-visible
-**Change a pattern** (auth-as-SDLC, paste-and-go AssetRef, deploy-dir plan/commit, db(req) vs adminDb()) | [README.md](README.md) patterns section, both `SKILL.md` files, [cli/llms-cli.txt](cli/llms-cli.txt), private `site/llms.txt`, private `site/llms-full.txt` if it's a deep dive
-**Change an HTTP endpoint** | Private `site/llms.txt` (canonical HTTP reference), `site/openapi.json` if applicable
-**Ship a user-visible feature** | Private `site/updates.txt` AND `site/humans/changelog.md` (keep them in sync; new entry at the top)
-**Change pricing or limits** | [README.md](README.md), [SKILL.md](SKILL.md), [cli/llms-cli.txt](cli/llms-cli.txt), [openclaw/SKILL.md](openclaw/SKILL.md), private `site/llms.txt`, private `site/humans/*.md` (especially `terms.md` and any pricing pages)
+**Add or remove an MCP tool** | `src/index.ts` (registration), `sync.test.ts` (`SURFACE` + `SDK_BY_CAPABILITY`), [README.md](README.md) (tools table), [SKILL.md](SKILL.md) (tools by category), [llms-mcp.txt](llms-mcp.txt) (tools by category), `cli/llms-cli.txt` if there's a sibling CLI subcommand
+**Add or remove a CLI subcommand** | `cli/lib/<group>.mjs` (impl), `sync.test.ts` (`SURFACE`), [cli/llms-cli.txt](cli/llms-cli.txt), [openclaw/SKILL.md](openclaw/SKILL.md) (CLI verbs), [cli/README.md](cli/README.md) only if it's a new top-level group, mirror sibling MCP tool docs
+**Add an SDK namespace or method** | `sdk/src/namespaces/<name>.ts`, [sdk/llms-sdk.txt](sdk/llms-sdk.txt) (namespace section + signatures), [sdk/README.md](sdk/README.md) (namespace catalog table), [AGENTS.md](AGENTS.md) (namespace count + architecture diagram), [README.md](README.md) (namespace count), `sync.test.ts` (`SDK_BY_CAPABILITY`)
+**Change `@run402/functions` surface** | `functions/src/`, [functions/README.md](functions/README.md), [AGENTS.md](AGENTS.md) (Functions library section), [SKILL.md](SKILL.md), [llms-mcp.txt](llms-mcp.txt), [sdk/llms-sdk.txt](sdk/llms-sdk.txt), and [openclaw/SKILL.md](openclaw/SKILL.md) (in-function helpers section in each)
+**Rename / remove a tool, command, flag, or method** | All of the above + verify [SKILL.test.ts](SKILL.test.ts) banned-pattern list catches it; cross-repo: drop a private `site/updates.txt` entry if user-visible
+**Change a pattern** (auth-as-SDLC, paste-and-go AssetRef, deploy-dir plan/commit, db(req) vs adminDb()) | [README.md](README.md) patterns section, both `SKILL.md` files, [cli/llms-cli.txt](cli/llms-cli.txt), [sdk/llms-sdk.txt](sdk/llms-sdk.txt), [llms-mcp.txt](llms-mcp.txt), [llms.txt](llms.txt) wayfinder if the pattern is part of the pitch
+**Add a new integration surface** | [llms.txt](llms.txt) (the wayfinder is the source of truth for "what surfaces exist"), [README.md](README.md) integrations table, [AGENTS.md](AGENTS.md), a matching `llms-<surface>.txt` reference file
+**Change pricing or limits** | [README.md](README.md), [SKILL.md](SKILL.md), [cli/llms-cli.txt](cli/llms-cli.txt), [sdk/llms-sdk.txt](sdk/llms-sdk.txt), [llms-mcp.txt](llms-mcp.txt), [llms.txt](llms.txt), [openclaw/SKILL.md](openclaw/SKILL.md). Cross-repo: private `site/humans/*.md` (terms, pricing pages)
 **Change architecture (kernel, error hierarchy, build flow)** | [AGENTS.md](AGENTS.md) is the canonical place; reflect any user-visible consequences in the relevant skill / reference
+**Cross-repo (private repo)** — **change an HTTP endpoint, ship a user-visible feature, or change the API surface** | `site/llms-full.txt` (HTTP API reference), `site/openapi.json` if applicable, `site/updates.txt` + `site/humans/changelog.md` for user-visible features. Open a separate PR in `run402-private/`.
 
 ## Notes on canonicality
 
-- **`cli/llms-cli.txt`** is canonical for the CLI; the private site's copy is auto-pulled at deploy time. Edit the public one only.
-- **`SKILL.md`** is canonical for the MCP-host skill body; the private site's copy is auto-pulled at deploy time. Edit the public one only.
-- **`site/llms.txt`** is canonical for the HTTP API reference; **edit it directly in the private repo.**
-- **`site/updates.txt`** + `humans/changelog.md` are canonical for the changelog; both live in the private repo.
+- **`llms.txt`** (root) is canonical for the wayfinder — the entry-point document at `run402.com/llms.txt`. Deploy-pulled.
+- **`cli/llms-cli.txt`** is canonical for the comprehensive CLI reference. Deploy-pulled.
+- **`sdk/llms-sdk.txt`** is canonical for the comprehensive SDK reference. Deploy-pulled.
+- **`llms-mcp.txt`** (root) is canonical for the comprehensive MCP reference. Deploy-pulled.
+- **`SKILL.md`** (root) is canonical for the MCP-host skill body; the private site's copy is deploy-pulled.
+- **`openclaw/SKILL.md`** is canonical for the OpenClaw script-runtime skill body — bundled into the OpenClaw skill install.
 - **`AGENTS.md`** is canonical for repo architecture; `CLAUDE.md` just imports it.
+- **`site/llms-full.txt`** (private repo) is canonical for the HTTP API reference — edit directly there.
+- **`site/updates.txt`** + **`site/humans/changelog.md`** (private repo) are canonical for the changelog — edit directly there.