docs(reference): reference IA completeness, README truth, and CLI verb coverage

.llm/runs/docs-1377-content--leaf/audit.md

@@ -0,0 +1,48 @@
+# Full-changeset documentation audit — PR #1541
+
+## Verdict
+
+**PASS after in-place documentation corrections.**
+
+This was the opposite-family `docs_audit` pass over `cd24e1679..f3893df5b` as one changeset,
+followed by a complete rerun with the audit fixes applied and focused reruns after the
+orchestrator's xref-registry and plugin/core canonical-location findings. The generator's worklog
+and PR claims were treated as input only. Evidence below came from this Codex session's commands
+against the checked-out public package, CLI, and documentation wiring surfaces.
+
+## Gate log
+
+| Gate | Command(s) | Scope | Result | Findings | Proceeded |
+| --- | --- | --- | --- | --- | --- |
+| 1. Links | `rtk proxy deno task docs:links` | Full documentation tree with the complete PR-C changeset and audit fixes applied | **PASS** — exit 0; `docs=102 broken-links=0 broken-anchors=0 orphans=0` | No dangling links, anchors, or reported orphans. | Yes — continued to the remaining gates. |
+| 2. Site build | `(cd docs/site && rtk proxy deno task build)` | Full Lume site, including all four new core-reference routes and changed navigation copy | **PASS** — exit 0; source format OK; Lume generated 630 files; rendered-output check passed for 224 HTML files with four documented syntax allowances | The recurring warning that `docs/site/deno.json` is outside the root workspace is non-fatal and pre-existing. | Yes — no build fix required. |
+| 3. Internal wording | `git diff --unified=0 cd24e1679 -- README.md packages/sdk/README.md docs/site`; changed-line extraction with `sed`; internal-term scan with `rg` | Changed public lines only, including audit corrections | **PASS after fix** — no internal identifier/process leak remains; the sole final lexical hit is public phrase “test harness” | Found `(US-2)` and “tracked separately” in the changed reference index. The whole-site comparison also exposed legacy `US-2`/`US-8` wording on reference claims touched while reconciling Gate 9. | Yes — removed internal story/process wording in place. |
+| 4. Versioned specifiers | Changed-line and whole-changed-file `rg` scans for bare `jsr:@netscript/<package>`; `rg 'releaseSpecifier' docs/site/cli-reference.md`; `(cd /tmp && deno info jsr:@netscript/cli@0.0.5)` | All original public files in the PR-C changeset, plus root install instructions | **PASS** — no newly introduced bare pinnable package specifier; site commands concatenate `releaseSpecifier`; root README explicitly requires substituting `<version>`; registry resolution of current `0.0.5` succeeded | The root README is static Markdown, so `<version>` cannot use the site data variable; its substitution instruction and live release/JSR links make the placeholder explicit. | Yes — no specifier correction required; retained the explicit placeholder. |
+| 5. Command/API accuracy | `deno run --no-lock --allow-read --allow-run=deno .llm/tmp/1377-doc-surface-audit.ts`; fresh `deno doc --json` for every declared subpath and `deno doc --filter` checks for the described root semantics; live `deno run -A packages/cli/bin/netscript.ts … --help` matrix; `deploy list --json`; router-source inspection; targeted CLI tests (10 passed); SDK query-factory tests (3 passed); `rtk proxy deno task docs:accuracy` | Every subpath/count and root table on the four exhaustive pages; all six newly documented CLI verbs, seven routed deploy families, deploy registry/router intersection, SDK query dialect, root README install target | **PASS after fixes** — exact package results: sagas 19/19 entrypoints and 41/41 root symbols; streams 4/4 and 51/51; triggers 12/12 and 106/106; workers 17/17 and 32/32; zero missing/extra entrypoints or symbols, count mismatches, or kind mismatches. CLI behavior tests: 10/10; SDK query tests: 3/3; docs accuracy PASS. | Found five documentation defects: nonexistent host-level `plugin ai --help`; `deploy list` advertised operations described as callable operations; desktop package target/default and release flags incomplete; jobs/tasks falsely split into handler-only versus entrypoint-only; root `createWorkersRuntime` falsely described as dependency-injected. Re-derived deploy surface as router intersection: Docker/Compose five verbs; five cloud targets three; `emit` advertised but unrouted. | Yes — fixed all five in place, including exact desktop flags/defaults and the root-versus-`/runtime` workers distinction. Source defect `emit` remains out of scope. |
+| 6. Template/generated drift | `rtk proxy deno task check:assets-barrel`; immediate `git diff` of generated barrels and `rtk git status --short` | Repo-owned generated asset barrels affected by documentation/README assets | **PASS** — exit 0 and no generated-barrel diff | The gate did not alter any generated assets. A later targeted CLI invocation added one incidental `deno.lock` integrity row. | Yes — removed the incidental lock entry and retained no cache/lock change. |
+| 7. Nav/front matter | Front-matter inspection for the four new pages; publishable-page inventory; `_config.ts`/`_data.ts` nav-source inspection; `deno eval` comparison of `docs/site/reference/` directories with exported `ref:` keys; Gates 1–2 rerun after the registry fix | New core pages, folder-derived navigation, xref registry, front matter, and path convention | **PASS after follow-up fix** — all four pages have `layout: layouts/base.vto` and exact package titles; Lume rendered all four; 35 publishable workspace members have pages; all 36 reference directories have exactly 36 registered `ref:` keys, with zero missing or extra entries | The initial audit verified folder-derived nav but missed the separate hand-maintained `REFERENCE_UNITS` registry. The four new `plugin-*-core` pages lacked xref keys. `_data.ts` no longer contains a mirrored executable list; it explicitly delegates `ref:` keys to `_data/xref.ts`. Two comments in `xref.ts` also carried stale counts (`32` and `28`) and one retained false “generated” provenance. | Yes — registered all four missing units, corrected both counts to 36, and documented that nav is independently folder-derived while the xref registry must stay aligned with `docs/site/reference/`. |
+| 8. Prose quality | `deno run --no-lock --allow-read docs/site/_plugins/check-source-format.ts .`; heading-level Deno scan; `deno fmt --check README.md packages/sdk/README.md`; `git diff --check cd24e1679`; changed-line filler/callout/command scans; live command checks from Gate 5 | All changed public prose, headings, tables, callouts, and shown commands | **PASS after fixes** — source formatting OK; 45 changed Markdown files, zero heading jumps; both READMEs formatted; diff check clean | The shown `netscript plugin ai --help` command failed because the host pass-through does not own `--help`. Root README still contained separate hardcoded plugin-file/helper totals. Desktop wording omitted explicit-target behavior. | Yes — removed the invalid shown command, removed all hardcoded root-README file/directory/helper totals, qualified host targeting as the default, and added exact release setup flags. |
+| 9. Cross-page contradiction | Whole-tree `rg` for generated-reference claims, deploy verb claims, SDK query shapes, scaffold totals, internal identifiers, and obsolete plugin/core convention statements; focused repo search for a reference writer; comparison to live surfaces from Gate 5; `rtk proxy deno task docs:accuracy` | Every changed claim against the rest of the public documentation tree | **PASS after follow-up fixes** — no obsolete “not a separate top-level reference entry,” “single-page internals convention,” or “not part of the public plugin contract” claim remains; docs accuracy exits 0 | The rewritten index said reference pages are hand-written, while many existing public pages still called them generated. A later polish pass found a second contradiction the initial audit missed: the four deployable-plugin pages duplicated their core packages' exhaustive surfaces, and the sagas/streams pages denied those separate core references should exist. Historical `_plan/` files retain their original planning language and are not public documentation. | Yes — selected one publishable package/one canonical reference page, retained focused cross-package examples, replaced four duplicated core tables with links to the canonical `plugin-*-core` pages, recorded the rule and rationale in the index, and retained the saga `spawn(...): never` contract required by the accuracy gate. The `Group F`/`T1` descriptions remain unchanged because they match authoritative published JSDoc and are tracked in #1554. |
+
+## Fix disposition
+
+Fixed in place:
+
+- removed internal `(US-2)` / process wording from the changed reference index;
+- corrected the CLI reference for the `plugin ai` pass-through, deploy registry versus routed verbs,
+  desktop package/release flags and defaults, and five-versus-three routed deploy surface;
+- corrected workers builder and runtime-composition claims against `deno doc` and the live types;
+- removed all hardcoded file/directory/helper totals from the root README;
+- reconciled public “generated reference” wording with the verified hand-maintained Markdown model;
+- changed the public Reference-lane subtitle to “Every published symbol”; and
+- registered the four new core-reference pages in the hand-maintained `ref:` xref surface, verified
+  exact 36-directory/36-key parity, and corrected its stale count/provenance comments;
+- made each separately published `plugin-*-core` page canonical for its own exports, replacing the
+  four deployable-plugin pages' duplicated exhaustive tables with links and recording the convention
+  in the reference index; and
+- removed incidental `deno.lock` churn.
+
+Flagged but not fixed: none. The unrouted adapter `emit` operation remains the separately owned
+source defect and was not changed. Historical files under `docs/site/_plan/` are retained as records,
+not treated as current public claims. The published-JSDoc terms `Group F` and `T1` remain in the
+triggers-core page pending the separately filed source correction #1554.

.llm/runs/docs-1377-content--leaf/context-pack.md

@@ -0,0 +1,85 @@
+# Context pack — docs-1377-content--leaf
+
+Resumable summary. Read with `supervisor.md`, `worklog.md`, `drift.md`.
+
+## What this run is
+
+PR-C of #1377 — the **content** half. Documentation authoring only. The gate half (a
+`publish-readiness.ts` reference-page check that currently runs over zero packages, a
+command-coverage gate, and the reference path-convention decision) is PR-D and is **out of scope**.
+
+`Refs #1377`, never `Closes` — the issue's gate acceptance rows are not this PR's to complete.
+
+## Coordinates
+
+| Field | Value |
+| --- | --- |
+| Worktree | `/home/codex/repos/ns006-1377-content` |
+| Branch | `docs/1377-reference-ia-readme-truth` |
+| Baseline | `cd24e1679` |
+| PR | **#1541** (draft) |
+| Run dir | `.llm/runs/docs-1377-content--leaf/` |
+
+Push with an explicit refspec: `git push origin HEAD:refs/heads/docs/1377-reference-ia-readme-truth`.
+
+## Slices
+
+| Slice | Commit | State |
+| --- | --- | --- |
+| S1 four `-core` reference pages + reference index | `e22a2f952` | landed, gated, commented |
+| S2 `packages/sdk/README.md` query dialect | `68cf6f2e5` | landed, gated, commented |
+| S3 root `README.md` scaffold count + specifier | `617b74884` | landed, gated, commented |
+| S4 CLI reference — six verbs + two wrong claims | `f3893df5b` | landed, gated, commented |
+| Audit corrections | `077a75716`, `13b6d118a`, `ef2b05670` | landed, gated, commented |
+| Plugin/core canonical-location follow-up | this commit | four deployable-plugin pages point to canonical `plugin-*-core` pages; gated |
+
+## Measurements that must not be re-derived
+
+- **Alias row of #1377 is already satisfied.** `@contracts`, `@/lib/`, `api-clients` are at zero
+  under `docs/site/`, and `check-accuracy-and-discoverability.ts:57-58` actively forbids them. Tick
+  on measurement; do not "fix".
+- **Reference pages: 35 effective-publish members, 0 missing** after S1 (was 4 missing).
+- **Path convention:** 31 name-exact, 4 exceptions — the *deployable* plugins drop `plugin-`.
+- **No generator writes into `docs/site/reference/`.** Pages are hand-written.
+- **Reference xref registry:** navigation is folder-derived, but `_data/xref.ts` separately registers
+  all 36 reference directories. The audit follow-up restored exact 36-directory/36-key parity and
+  added the four new `plugin-*-core` keys.
+- **Canonical reference location:** each separately published `plugin-*-core` page owns its
+  exhaustive exported-API documentation. The corresponding deployable-plugin page owns manifest and
+  integration coverage, links to the core page, and may retain focused cross-package examples. This
+  removes the prior duplicated tables and obsolete single-page-internals claims.
+- **Deploy target operations, measured from source:**
+
+  | Target(s) | Class | Operations |
+  | --- | --- | --- |
+  | `compose`, `docker` | `AspireComposeDeployTarget:64` | plan · emit · up · down · status · logs (**6**) |
+  | `kubernetes`, `azure-aca`, `azure-app-service`, `azure-aks`, `cloud-run` | `AspireCloudDeployTarget:125` | plan · emit · up · down (**4**) |
+  | `deno-deploy` | `deno-deploy-target.ts:57` | plan · up · down · status · logs (5) |
+  | `windows-service`, `linux-service` | `service-deploy-target.ts:21` | plan · emit · up · down · status · logs (6), +`rollback` with an `ActivationPort`, +`secrets` with a `SecretsStorePort` |
+
+  Verb subcommands are generated from the target's `operations`
+  (`target-deploy-command.ts:58-66`), so both wrong claims are decidable from these arrays.
+- **Six verbs confirmed undocumented** in `docs/site/`: `agent drift`, `deploy desktop`,
+  `deploy package-cli`, `deploy list`, `config list` → zero occurrences; `plugin ai` → one, at
+  `reference/plugin-ai/index.md:311`, absent from both command references.
+
+## Hard boundaries
+
+- **Do not open** the nine `docs/site` Tier-1 files PR-B is editing concurrently: `quickstart.vto`,
+  `index.vto`, `services-sdk/sdk.md`, `services-sdk/how-to/add-a-service.md`, and
+  `web-layer/{query,examples,interactive,form,query-bridge}.md`.
+- No gate code, no checkers, no negative tests — PR-D.
+- No `packages/**` or `plugins/**` change except `README.md`.
+- Do not mark ready for review. Do not merge. A separate opposite-family Codex audit runs after this,
+  then a Fable prose polish.
+
+## Gate commands for this run
+
+```text
+deno task docs:links
+deno task docs:accuracy
+deno task quality:gate
+deno task publish:dry-run
+cd docs/site && deno run --no-lock --allow-read _plugins/check-source-format.ts .
+deno fmt <README paths>          # docs/site/**/*.md is excluded — see drift DR-4
+```