dsh-plugin-guide 0.4.3 → 0.4.5

package/docs/entry.md

@@ -16,6 +16,33 @@ market, index, or user hits.
 The exact rule IDs and evidence rules are in
 [`31-DSH-ENTRY`](https://github.com/PerryLink/dsh-standards/blob/main/31-DSH-ENTRY%E5%85%A5%E9%97%A8%E8%A7%84%E8%8C%83.md)
 and [`40-checker`](https://github.com/PerryLink/dsh-standards/tree/main/40-checker).
+Every ID is also listed in [rules.md](rules.md); the copy-paste shapes are in
+[recipes.md](recipes.md).
+
+<a id="package-shape"></a>
+## Package shape (DSC-01, DSC-02, DSC-03)
+
+`DSC-01` is one report line but six subitems; the detail lines say which one
+failed. `DSC-03` runs only in the listing profile — in the package profile it is
+`NA` with `install spec not supplied (package profile)`, which is allowed.
+
+| Detail | What the report says | Fix |
+|---|---|---|
+| `C-1.1` | `name must be a valid npm package name` / `version must be an exact SemVer version` | use a lowercase npm name and an exact `1.2.3` (or `1.2.3-beta.1`); a tag or range is not a version |
+| `C-1.2` | `no resolvable runtime entry` / `entry escapes the package` | point `exports["."]` or `main` at a file that exists inside the package; no `../` target |
+| `C-1.2` | `exports["."] points to a missing file` vs `entry not present in checkout; source/build hint exists` (WARN) | shipped packages need the built file; if the checker sees `src/index.ts` or a `build`/`prepare` script it downgrades to WARN, do not rely on that |
+| `C-1.2` | `patch-only bundle; no runtime entry by design` (`NA`) | fine: a package that only ships `dsh.bundle.patch` has no runtime entry and is not charged for it |
+| `C-1.3` | `no apply/default-class shape found by static scan` (WARN) | export `apply` (function plugin) or a default class (service plugin), not both; L1 is authoritative |
+| `C-1.4` | `patch path escapes the package` / `patch file is missing` | keep the patch inside the package and reference it relatively, e.g. `"./cordis.patch.yml"` |
+| `C-1.5` | `license is missing` (WARN) | add `"license": "MIT"` or another SPDX id |
+| `C-1.6` | `private:true; not publishable` (`NA`) | expected for a local profile package, not for a marketplace entry |
+| `G4` | `dsh.client exists but exports["./client"] is missing; a package-root row cannot resolve it` | add `exports["./client"]` and the package-root row — see [recipes.md](recipes.md#client-entry-and-root-row) |
+| `C-2.1` | `neither engines.dsh nor a @deepseek-ai/dsh* peer range is declared` | declare `"engines": { "dsh": ">=0.2.2-0 <0.3.0" }` |
+| `C-2.2` | `engines.dsh <range> does not satisfy runtime <v>` | widen the range to the host you target, or run the checker with `--runtime-version <v>` to judge against the right one |
+| `C-2.3` | `engines.dsh must not be a workspace: range` | publish a real SemVer range; `workspace:` must not reach a tarball |
+| `C-2.4` | `peer <name> range <range> conflicts with engines.dsh` (WARN) | the host decides on `engines.dsh` alone; align the peer anyway |
+| `C-3.1`/`C-3.2`/`C-3.5` | `install spec` / `source is pinned` / market entry | listing only: exact version or verifiable tag, `#<40-hex>` for git, and a `format:1` index entry with pinned versions |
+| `C-3.3`/`C-3.4` | `non-registry dependency` / `install-time build script present` (WARN) | pin git/url/file dependencies and declare what install scripts build |
 
 ## The two claims
 
@@ -28,6 +55,79 @@ and [`40-checker`](https://github.com/PerryLink/dsh-standards/tree/main/40-check
 entry; it needs G0–G3. A client-only package is build-only unless a browser
 probe exists.
 
+<a id="runtime-surface"></a>
+## Runtime surface (DSC-04 to DSC-09, DSC-14)
+
+These are the L1–L3 checks: load, provide, effects, unload, restart, and
+declared-vs-measured. They apply to `kind=plugin`; a `bundle` is verified by
+`--scope entry` G0–G3 instead (in `--scope ds-c` it is `NA`), and a client,
+preset, skill, theme, or MCP config is `NA` and must not claim runtime. `DSC-14`
+is the ENTRY run gate: for a plugin it mirrors L1, for a bundle it is G0–G3 and
+needs `--host`, and under `--entry-claim static` it is `NA`
+(`entry static claim: no runtime evidence`).
+
+| Detail | What the report says | Fix |
+|---|---|---|
+| `C-4.1`/`C-4.2` | `entry import failed: …` / `load failed: …` / `fiber state <n> is not ACTIVE (2)` | the entry must import and `apply()` without throwing; move timers, watchers, I/O, and subprocesses into `apply()` |
+| `C-4.3` | `plugin load timed out` / `killed after <n>ms; plugin blocked the event loop` | do not block on module-scope work or a top-level `await`; the L1 child is hard-killed |
+| — | `blocked by missing host dependency` (ERROR, `not-run`) | environment, not code: the plugin imports a bare package the fixture does not have. Install it or point `--runtime` at a complete host |
+| `C-5.1`/`C-5.2` | `no provide declaration` (`NA`) / `declared provide <x> was not registered` / `owned by another fiber` | register the service from this plugin's own fiber: `ctx.provide(name, impl)` or a `Service` |
+| `C-6.1` | `direct write to a Cordis private registration surface` | never assign into `ctx.events._hooks`, `ctx.reflect.store`, `ctx.registry._internal`, or `fiber._disposables` |
+| `C-6.2` | `no registered effects observed` / `all effects are anonymous` (WARN) | give every effect a label: `ctx.effect(fn, 'my-plugin.timer')` |
+| `C-7.1`–`C-7.3` | `getEffects().length=<n>` / `service store returned to baseline` / `registry.size <a> -> <b>` | every effect returns a disposer; `dispose()` must reach zero effects and restore the store and registry |
+| `C-7.5` | `dispose failed: …` | await quiescence; do not fire-and-forget cleanup |
+| `C-8.1`–`C-8.3` | `state after restart=<n>` / `effect count <a> -> <b>` / `revision … -> …` | `restart()` must re-enter `ACTIVE`, keep the effect count, advance revision/epoch, and work from a fresh `Context` |
+| `C-9.1`–`C-9.3` | `declared provide <x> is missing from measured services` / `measured service <x> is not declared` / `inject declares <x> but no static ctx.<x> read was found` | declarations must equal reality: provide ⊆ measured, measured ⊆ declared, and each `inject` is read |
+
+The runner stubs the services you declare in `inject` before it calls
+`ctx.plugin()`, so a plugin that only needs declared services can reach `ACTIVE`.
+Anything it cannot stub is reported as `ERROR`/`not-run`; that is not your
+defect and must not be written as a pass.
+
+```js
+export const name = 'hello'
+export const inject = ['tools']            // only what you read
+export const provide = ['hello']           // only what you register
+
+export function apply(ctx) {
+  ctx.provide('hello', { greet: () => 'hello' })   // C-5
+  ctx.effect(() => {                                // C-6, C-7
+    const timer = setInterval(poll, 60_000)
+    return () => clearInterval(timer)               // dispose → 0 effects
+  }, 'hello.timer')
+}
+```
+
+A bundle is verified by G0–G3, not by L1: G0 parses the patch, G1 composes the
+rows, G2 runs the host compatibility gate, G3 boots the target rows. A `partial`
+G3 is `ERROR`/`not-run`; only `G0-G3 verified; rows=<n>/<n>` with
+`DSC-14 PASS` is a runtime claim. G4 is a composition property: with
+`dsh.client`, the composed layer must contain a row whose `name` is the package
+name and `exports["./client"]` must resolve.
+
+<a id="client-files"></a>
+## Client files (G4)
+
+A client package is dual-face: the server half is loaded as a row, the browser
+half is a prebuilt file at `exports["./client"]`.
+
+- `dsh.client` must be a non-empty object; the host's Web consumer selects it
+  with `platform: "web"`.
+- `exports["./client"]` must be present. The host accepts a string, or an object
+  with a string `default`; the checker only fails when it is missing.
+- The composed config needs a **package-root row**: a patch `insert` whose
+  `name` equals `manifest.name`. Without an active row the client scanner never
+  sees the package, even though the export exists.
+- The client file must be a built artifact and must be included in `files`, or
+  the tarball ships a manifest that points at nothing.
+- G4 is static. It does not prove the browser bundle renders; that is a
+  build/browser probe and belongs in `limitations`, not in a runtime claim.
+
+The copy-paste client manifest and patch row are in
+[recipes.md](recipes.md#client-entry-and-root-row). A missing export or row is
+reported as `G4: FAIL` under `DSC-01` (or as `DSC-14` with `--host`), never as a
+pass.
+
 ## Run it
 
 ```sh
@@ -64,6 +164,7 @@ pass.
 
 ## Declaration fields
 
+<a id="declaration-fields"></a>
 Two optional fields become checks `DSC-11` and `DSC-13` once they exist:
 
 ```json
@@ -75,6 +176,11 @@ Two optional fields become checks `DSC-11` and `DSC-13` once they exist:
 }
 ```
 
+Both are **standard extensions**: this host does not read them yet. They are
+declarations plus UI disclosure, not a sandbox and not enforcement. Declaring
+`[]` and importing `node:fs` directly still passes `DSC-11`; the check only
+compares declarations with static triggers.
+
 Allowed `capabilities`: `fs:read`, `fs:write`, `shell`, `subprocess`,
 `network:egress`, `network:ingress`, `credentials:read`, `credentials:list`,
 `credentials:provider`, `llm:adapter`, `sessions:read`, `system-prompt:write`,
@@ -83,6 +189,95 @@ Allowed `capabilities`: `fs:read`, `fs:write`, `shell`, `subprocess`,
 Allowed `labels`: `prompt-modification`, `red-team`,
 `third-party-model-provider`, `remote-access`, `mirror`.
 
+<a id="capability-triggers"></a>
+## Capability triggers (DSC-11)
+
+`C-11.2` is the check authors hit most: if `dsh.capabilities` exists, every
+static trigger below must have its capability in the array, or the check FAILs
+with `static trigger <cap> is not declared in dsh.capabilities`.
+
+| Static trigger (source shape) | Declare |
+|---|---|
+| `ctx.webServer` / `ctx.webhookRuntime` | `network:ingress` |
+| `installBundle(` / `removeBundle(` | `plugin:install` |
+| `registerAdapter(` / `ctx.llm.register` | `llm:adapter` |
+| `ctx.systemPrompt.section(` / `.context(` / `.variable(` | `system-prompt:write` |
+| `ctx.tools.register(` | `tools:register` |
+| `@Remote(` / `@RemoteScope(` | `remote:expose` |
+| `.listRecords(` | `credentials:list` |
+| `ctx.sessions` / `ctx.sessionQuery` | `sessions:read` |
+| `ctx.shell` / `ctx.bash` | `shell` |
+| `ctx.subprocess` | `subprocess` |
+| `ctx.fs` | `fs:read` (a declared `fs:write` satisfies it) |
+| `ctx.web` / a bare `fetch(` | `network:egress` |
+
+Reading the other subitems:
+
+- `C-11.1`: an unknown capability id is a FAIL; an empty array is a WARN. A
+  missing field is a transitional WARN, and `C-11.2` is then **not evaluated** —
+  so an undeclared array hides the very failure you want to see.
+- `C-11.3`: a bundle patch that enables `@deepseek-ai/dsh-plugin-manager/tools`
+  without `disabled: true` is a FAIL.
+- `C-11.4`: a string literal that is exactly `danger-full-access` is a WARN; a
+  mention in a comment or a `console.log` description is not.
+- `C-11.5`: a declared capability with no matching trigger is a WARN (over-
+  declaration). Keep declarations to what the scan can see; a dynamic call may
+  not match.
+
+The scan covers `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, and `.jsx` files in the
+package, and skips `tests`, `docs`, `scripts`, `examples`, `fixtures`, `bench`,
+`tools`, and dot-directories, plus the other build and asset directories the
+walker ignores. A `fetch(` in `tests/` does not require `network:egress`; the
+same call in `lib/client.js` does.
+
+<a id="credentials-and-seams"></a>
+## Credentials and seams (DSC-12)
+
+`DSC-12` is a declaration-consistency check, not a security audit. It looks for
+direct access to the credential backing file and for global seam registration.
+
+| Detail | What the report says | Fix |
+|---|---|---|
+| `C-12.1` | `credential backing-file access near a file-read API without credentials:provider` (a path in text or UI is PASS) | read through `ctx.credentials`; if you really are a provider, declare `credentials:provider` |
+| `C-12.2` | `listRecords() used without credentials:list` | declare `credentials:list`, or stop enumerating records |
+| `C-12.3` | `global seam provider registration detected` (WARN) | do not provide `shell`/`credentials`/`sandboxPolicy`/`sandbox`/`deepSeekAccount` unless that is the plugin's purpose |
+| `C-12.4` | `danger-full-access/--add-dir literal` (WARN) | do not hard-code a sandbox bypass in a command or policy value |
+| `C-12.6` | `dsh.commitments` missing (`NA`) or `missing commitment: <id>` (WARN) | optional: a boolean for each of `no-session-upload`, `no-third-party-proxy`, `no-credential-enumeration`, `no-silent-prompt-rewrite`, `no-adapter-bypass`, `no-webhook-auto-session`, `no-security-seam-replacement`, `third-party-endpoint-disclosure`, `no-danger-full-access` |
+| `C-12.7` | `dsh.disclosure` missing (`NA`) or a shape WARN | optional: `endpoints` (https URLs), `retention` (string), `systemPrompt` (string) |
+
+```js
+// prefer: go through the seam
+export function apply(ctx) {
+  ctx.credentials.resolve('acme/api-key')
+}
+
+// avoid: the backing file is an implementation detail
+// readFileSync(join(process.env.DSH_HOME, '.credentials.yaml'))
+```
+
+<a id="labels-and-mirror"></a>
+## Labels and mirror (DSC-13)
+
+A label is a declaration, not an endorsement. `C-13.2` maps a **declared
+capability** to a required label:
+
+| Declared capability | Required label |
+|---|---|
+| `system-prompt:write` | `prompt-modification` |
+| `llm:adapter` **and** `network:egress` | `third-party-model-provider` |
+| `network:ingress` | `remote-access` |
+| `dsh.upstream` declared | `mirror` |
+
+- `C-13.1`: an unknown label is a FAIL; a missing `dsh.labels` is a transitional
+  WARN.
+- `C-13.3`: `dsh.upstream` must be an `https://` URL and must not point at this
+  package's own `repository`; a mirror also needs the `mirror` label.
+- `C-13.4`: `official`, `verified`, `certified`, `secure`, `audited` in
+  `dsh.labels` is a FAIL. The prose ban is separate: the checker does not scan
+  README or `description`, so keeping those words out is on you.
+- `C-13.5`: the `red-team` label should come with `dsh.usageScope`; without it
+  the check only WARNs.
+
 Do not label a plugin `official`, `verified`, `certified`, `secure`, or
 `audited` — those words are treated as an endorsement claim and fail `DSC-13`.
 

package/docs/flow.md

@@ -19,6 +19,134 @@ the first run, configuration, upgrade, and removal are understandable.
 The canonical text is
 [`32-DSH-FLOW`](https://github.com/PerryLink/dsh-standards/blob/main/32-DSH-FLOW%E9%A1%BA%E7%95%85%E8%A7%84%E8%8C%83.md).
 
+<a id="evidence-file"></a>
+## The evidence file: `dsh-flow-evidence/2`
+
+A journey row without a command, exit code, log hash, and timestamp is a claim,
+not evidence. The shape below is the evidence-file contract this guide
+recommends: one subject, one host, one entry per journey, and a chain pointer so
+a rewrite is detectable.
+
+```json
+{
+  "schema": "dsh-flow-evidence/2",
+  "evidenceId": "01JCM8Z6R4W1V2K3N4P5Q6R7S8",
+  "generatedAt": "2026-11-06T12:00:00Z",
+  "producer": { "kind": "local", "runner": "flow-collect 0.1.0", "runUrl": null, "actor": "author" },
+  "subject": {
+    "package": "@acme/dsh-hello",
+    "version": "0.1.0",
+    "source": "npm",
+    "integrity": "sha512-…",
+    "tarballSha256": "sha256:…",
+    "commit": "ce7073d51254c26cd63b22a60835b8f948deb447",
+    "treeSha256": "sha256:…"
+  },
+  "host": { "dsh": "0.2.2-alpha.2", "dshCommit": null, "cordis": "4.0.6-alpha.1", "node": "v24.11.0", "platform": "linux-x64" },
+  "journeys": {
+    "J1": {
+      "status": "pass",
+      "kind": "observed",
+      "checks": [
+        {
+          "id": "J1.install",
+          "status": "pass",
+          "command": ["dsh", "plugin", "add", "."],
+          "exitCode": 0,
+          "startedAt": "2026-11-06T11:00:01Z",
+          "endedAt": "2026-11-06T11:00:09Z",
+          "stdout": { "path": "logs/J1.install.out", "sha256": "sha256:…" },
+          "assertions": [{ "claim": "row visible in dump", "observed": true }]
+        }
+      ],
+      "limitations": []
+    },
+    "J8": { "status": "na", "reason": "no dsh.client" }
+  },
+  "totals": { "pass": 7, "na": 1, "fail": 0 },
+  "conclusion": "flow-pass",
+  "claims": { "claimLevel": "self-attested", "notClaimed": ["certification", "security audit"] },
+  "chain": { "seq": 12, "prev": "sha256:…", "entrySha256": "sha256:…" },
+  "signature": null
+}
+```
+
+| Field | Required | What belongs there |
+|---|---|---|
+| `schema`, `evidenceId`, `generatedAt` | yes | the version, a unique id, an ISO timestamp |
+| `producer` | yes | `kind` = `sandbox` / `ci` / `local`, the `runner`, a `runUrl` for CI, the `actor` |
+| `subject` | yes | `name@version` plus `integrity`, `tarballSha256`, `commit`, `treeSha256` — binds evidence to one artifact, so a copied file for another version is `stale` |
+| `host` | yes | `dsh`, `dshCommit`, `cordis`, `node`, `platform` — a pass on another host does not transfer |
+| `journeys.Jn` | yes, per run journey | `status` (`pass` / `fail` / `not-run` / `na`), `kind` (`observed` / `static` / `manual`), `checks[]`, `limitations[]`, and `reason` for a skip |
+| `journeys.Jn.checks[]` | yes, per check | `id` (`J1.install`), `command[]`, `exitCode`, `startedAt`, `endedAt`, `stdout.path` + `stdout.sha256`, `assertions[]` |
+| `totals`, `conclusion` | yes | counts and `flow-pass` / `flow-fail` / `flow-blocked` / `flow-warn` |
+| `claims` | yes | `claimLevel` (`self-attested`, `sandbox-attested`, …) and what is explicitly **not** claimed |
+| `chain` | when chained | `seq`, `prev`, `entrySha256` from the append-only evidence chain |
+| `signature` | optional | `null` unless you actually sign |
+
+Honesty rules for the file itself:
+
+- `kind: "static"` never counts as a FLOW pass. J5 and a client-only J8 are
+  static preflight; label them that way.
+- `na` is a skip with a reason (`no dsh.client`), not a pass.
+- A missing `command[]`, `exitCode`, or log hash means the row is not evidence.
+  Put the limitation in `limitations[]` instead of dropping the row.
+
+<a id="what-the-checker-reads"></a>
+### What reads this file today
+
+`dsh-levels --flow-evidence` does **not** read the nested v2 shape yet. Its
+reader wants a flat map and only reads `status`:
+
+```json
+{
+  "J1": { "status": "pass", "evidence": "add → dump → remove; logs/J1.*.out" },
+  "J2": { "status": "pass", "evidence": "same row id disable/enable; two dumps" }
+}
+```
+
+- Accepted values are `pass`, `fail`, `not-run`, `manual`. Anything else,
+  including `na` and `warn`, is silently downgraded to `not-run`.
+- FLOW becomes `runtime` only at **8/8 pass**. One `na` gives `7/8` and
+  `not-run` — which is the honest answer for a package with no client, but it
+  is not a pass.
+- The flat map has no binding, no hash, and no host. A hand-written 8-pass file
+  passes. That is why the v2 file above exists: keep the flat map as the
+  projection, and keep the v2 file plus logs as the thing you can defend.
+
+Project the v2 file to the flat map before running the audit:
+
+```sh
+node -e '
+const fs = require("node:fs");
+const evidence = require("./flow-evidence.json");
+const flat = {};
+for (const [id, journey] of Object.entries(evidence.journeys)) {
+  flat[id] = { status: journey.status, evidence: journey.reason ?? journey.checks?.[0]?.id ?? null };
+}
+fs.writeFileSync("flow-flat.json", JSON.stringify(flat, null, 2));
+'
+```
+
+<a id="minimum-evidence-per-journey"></a>
+## Minimum evidence per journey
+
+| Journey | Run and record | The row is a pass only when |
+|---|---|---|
+| **J1** install / remove | `dsh plugin add .` → config dump → `dsh plugin remove` → dump | the row appears and then disappears, with no hand-edited profile; record both dumps and their hashes |
+| **J2** enable / disable | disable and enable the same row id, dumping after each | the change is visible in the composed config under the same stable id |
+| **J3** configuration | boot with an empty config; boot with an invalid field; change a `volatile()` field | empty config boots; the invalid value fails loudly with a field path; the volatile change restarts 0 times |
+| **J4** first success | follow the README quickstart on a clean profile; also start with no credential | a five-minute first success, and the error names the cause, the next command, and the doc anchor; a no-key start stops at a clear credential boundary |
+| **J5** permissions | compare `capabilities`/`labels`/commitments/disclosure with the README | every declaration matches the README and no endorsement claim appears; static only, so `kind:"static"` and **not** counted as pass |
+| **J6** upgrade / rollback / uninstall | install `--previous`, upgrade, roll back, uninstall | the installed version changes and comes back, data survives, and no files or rows are left behind |
+| **J7** observability | boot normally, with a missing service, and with a port conflict | the startup line prints `name@version`, and each of the three cases is diagnosable from the log |
+| **J8** client / server | headless run, web run, client-disabled run | each mode works or is explicitly rejected; with no `dsh.client` the row is `na` with that reason; browser rendering goes in `limitations[]` |
+
+When a journey fails, quote the five things a reader needs: `Jn.<subcheck>`,
+the original `command[]`, `exitCode`, the last 20 lines of stderr, and the
+absolute log path. Then attach the clause anchor the journey maps to (for
+example `J2.toggle → 32-DSH-FLOW #R2`).
+
 ## Status, not a score
 
 | Status | Meaning |
@@ -27,26 +155,38 @@ The canonical text is
 | `failed` | at least one journey has an attributable FAIL |
 | `not-run` | no evidence, or fewer than eight journeys have pass evidence |
 
-Each journey is recorded as `pass` / `fail` / `not-run` / `manual`. There is no
-`flow-warn` status — a partial run is `not-run`, not a soft pass.
+Each journey is recorded as `pass` / `fail` / `not-run` / `manual`; the v2 file
+adds `na` for a justified skip, and the flat reader downgrades `na` (and `warn`)
+to `not-run`. There is no `flow-warn` **FLOW state** — a partial run is
+`not-run`, not a soft pass. The journey harness may print `flow-warn` or
+`flow-blocked` in its own `dsh-flow-runtime/1` conclusion; neither is `runtime`.
 
 `not-run` is never a pass. Do not publish a pass rate or a grade from FLOW.
 
 ## Current limit
 
-The runtime harness is still a draft. J1/J2/J4/J6 have runtime evidence on
-fixtures; J3/J7 have fixture-level runtime; J5/J8 have static preflight; browser
-rendering is not yet covered. The guide must state which journey was actually
-run.
+The harness is a draft, and this document is deliberately ahead of it:
+
+- The v2 shape above is the contract to record against. The audit's
+  `--flow-evidence` reader still consumes the flat map, so project v2 → flat
+  before you run it (see above). A v2 file fed to the audit directly reads as
+  `0/8` and `not-run`.
+- There is no shipped command that collects all eight journeys for you. J1 has
+  a runtime fixture (`journey-runtime.mjs`); the other journeys are recorded by
+  hand or by a fixture-level run. Browser rendering has no probe.
+- `na`, `manual`, and `static` rows cannot become `runtime`. If one journey is
+  `na`, FLOW stays `not-run` — write that, not a pass.
 
 The source harness lives in
 [`40-checker/scripts/journey.mjs`](https://github.com/PerryLink/dsh-standards/blob/main/40-checker/scripts/journey.mjs)
 and
-[`journey-runtime.mjs`](https://github.com/PerryLink/dsh-standards/blob/main/40-checker/scripts/journey-runtime.mjs).
+[`journey-runtime.mjs`](https://github.com/PerryLink/dsh-standards/blob/main/40-checker/scripts/journey-runtime.mjs);
+the audit is
+[`40-checker/scripts/level-audit.mjs`](https://github.com/PerryLink/dsh-standards/blob/main/40-checker/scripts/level-audit.mjs).
 The three-layer audit reads FLOW evidence through `--flow-evidence`:
 
 ```sh
-npx -p dsh-standards dsh-levels ./my-plugin --flow-evidence flow.json --format json
+npx -p dsh-standards dsh-levels ./my-plugin --flow-evidence flow-flat.json --format json
 ```
 
 ## Author checklist
@@ -56,4 +196,4 @@ npx -p dsh-standards dsh-levels ./my-plugin --flow-evidence flow.json --format j
 - Errors say what happened, what to run next, and where the doc is.
 - Permissions say what the plugin can/cannot do and how to turn it off.
 - Upgrade and uninstall are tested against real data, not only a clean install.
-- No “certified”, “official”, or “secure” wording.
+- No “certified”, “verified”, “audited”, “official”, “secure”, or “ranked” wording.

package/docs/levels.md

@@ -11,6 +11,20 @@
 
 > **Current baseline (2026-11-04):** DSH `0.2.2-alpha.3` (npm `alpha`), Node `>=24.9.0` (since 0.2.2-alpha.2), Cordis `4.0.6-alpha.2`. `engines.dsh`, when declared, decides alone since 0.2.1-alpha.4; `ctx.menus` is gone in 0.2.2-alpha.3; Typert codecs use `create()` since 0.1.6-alpha.2; `@deepseek-ai/dsh-client-runtime` was removed in 0.1.2-alpha.1 and has no 0.2.x.
 
+## Where to go next
+
+| You have | Read |
+|---|---|
+| a report line with a `DSC-nn` or `C-n.m` ID | [rules.md](rules.md) — every check, whether it blocks, and the one-line fix |
+| a FAIL to fix right now | [recipes.md](recipes.md) — copy-paste `package.json`, `cordis.patch.yml`, and client entry |
+| an ENTRY question | [entry.md](entry.md) — package shape, runtime surface, declarations |
+| a FLOW journey to record | [flow.md](flow.md) — the `dsh-flow-evidence/2` file and J1–J8 evidence |
+| a BOOST practice to evidence | [boost.md](boost.md) — the thirteen-field evidence card |
+
+The two reference docs exist because a report ID alone does not tell you what to
+change: [rules.md](rules.md) maps IDs to fixes, and [recipes.md](recipes.md)
+holds the shapes those fixes need.
+
 ## ENTRY
 
 ENTRY is the compatibility floor. It checks the package shape, entry points,
@@ -24,6 +38,8 @@ made — an actual start.
 
 Start here: [ENTRY guide](entry.md) and the canonical
 [31-DSH-ENTRY](https://github.com/PerryLink/dsh-standards/blob/main/31-DSH-ENTRY%E5%85%A5%E9%97%A8%E8%A7%84%E8%8C%83.md).
+Then fix by ID: [rules.md `DSC-01`–`DSC-14`](rules.md#table) and
+[recipes.md](recipes.md).
 
 ## FLOW
 
@@ -33,11 +49,13 @@ modes.
 
 - The current FLOW harness is a draft. Some J1–J8 checks have runtime evidence;
   others are static preflight or `not-run`.
-- `flow-warn`, `flow-fail`, and `flow-not-run` are real outcomes. Do not turn a
-  missing run into a pass.
+- `runtime`, `failed`, and `not-run` are the FLOW statuses. A partial run is
+  `not-run`, never a soft pass.
 
 Start here: [FLOW guide](flow.md) and the canonical
 [32-DSH-FLOW](https://github.com/PerryLink/dsh-standards/blob/main/32-DSH-FLOW%E9%A1%BA%E7%95%85%E8%A7%84%E8%8C%83.md).
+The evidence file shape and the J1–J8 minimum are in
+[flow.md § the evidence file](flow.md#evidence-file).
 
 ## BOOST
 
@@ -52,6 +70,8 @@ parallel/jobs, and composition.
 
 Start here: [BOOST guide](boost.md) and the canonical
 [33-DSH-BOOST](https://github.com/PerryLink/dsh-standards/blob/main/33-DSH-BOOST%E5%8A%A0%E9%80%9F%E5%AE%9E%E8%B7%B5.md).
+The card fields are in
+[boost.md § evidence, not a badge](boost.md#thirteen-fields).
 
 ## Run the checks
 
@@ -75,4 +95,4 @@ The legacy build skill/CLI is [`dsh-primer`](https://github.com/PerryLink/dsh-pr
 - `not-run` ≠ `pass`
 - `boost-evidenced` ≠ plugin grade
 - `A–D` grades (where they exist) are orthogonal to ENTRY/FLOW/BOOST
-- No official, certified, secure, recommended, or ranked claim
+- No official, certified, verified, audited, secure, recommended, or ranked claim