dsh-plugin-guide 0.4.3 → 0.4.4

package/docs/boost.md

@@ -21,35 +21,63 @@ The canonical text is
 
 ## Evidence, not a badge
 
+<a id="thirteen-fields"></a>
 An evidence card is per practice, per plugin, with a baseline and an after
-measurement. Example shape:
-
-```yaml
-practice: LEV-6
-plugin: "@acme/dsh-hello@0.1.0"
-baseline:
-  startupMs: 180
-  tokensPerTurn: 1200
-after:
-  startupMs: 150
-  tokensPerTurn: 900
-environment:
-  dsh: 0.2.2-alpha.3
-  cordis: 4.0.6-alpha.2
-  node: 24.9
-command: "node bench/hello.mjs"
-result: "startup 180→150 ms; tokens 1200→900"
-negativeControl: "same bench with the plugin disabled"
-generatedAt: "2026-11-03"
-expiresAt: "2027-05-03"
-recordHash: "sha256:<64 hex of this record>"
-claimLevel: "self-assessed"               # self-reported | self-assessed | host-reviewed | independent | reference
-issuer: "author"
-selfAssessed: true
+measurement. The audit is strict about the field names, so use exactly these
+thirteen:
+
+```json
+{
+  "LEV-1": {
+    "status": "measured",
+    "evidenceCard": {
+      "subject": "@acme/dsh-hello@0.1.0",
+      "host": "dsh 0.2.2-alpha.2 / cordis 4.0.6-alpha.1 / node 24.9.0 / linux-x64",
+      "method": "count timers and listeners before and after dispose; 20 runs",
+      "scope": "LEV-1 reversible effects — timer and watcher in apply()",
+      "command": "node bench/effects.mjs",
+      "result": "effects 3 → 0 after dispose; effect count 3 → 3 after restart",
+      "negativeControl": "the same bench with the plugin disabled",
+      "generatedAt": "2026-11-06",
+      "expiresAt": "2027-05-06",
+      "recordHash": "sha256:<64 lowercase hex over this card>",
+      "claimLevel": "self-assessed",
+      "issuer": "author",
+      "selfAssessed": true
+    }
+  }
+}
 ```
 
-All thirteen fields are required. A missing or malformed field makes the card
-`not-measured`; a status word alone is not evidence.
+| Field | Validator | What to put there |
+|---|---|---|
+| `subject` | non-empty string | what was measured, `name@version` — not the repo name |
+| `host` | non-empty string | DSH / Cordis / Node versions and the platform |
+| `method` | non-empty string | how it was measured, including the run count or comparator |
+| `scope` | non-empty string | which LEV practice and which part of the plugin |
+| `command` | non-empty string | the exact command that produced the result |
+| `result` | non-empty string | numbers, `before → after`; no adjectives |
+| `negativeControl` | non-empty string | the same measurement with the plugin disabled |
+| `generatedAt` | `YYYY-MM-DD` | the day it was run |
+| `expiresAt` | `YYYY-MM-DD`, not before `generatedAt` | when the measurement stops being current (180 days is a reasonable cap) |
+| `recordHash` | `sha256:` + 64 lowercase hex | sha256 over the card JSON without this field; the validator checks the shape, a reviewer recomputes it |
+| `claimLevel` | `self-reported` \| `self-assessed` \| `host-reviewed` \| `independent` \| `reference` | be honest; anything stronger is not self-declared |
+| `issuer` | non-empty string | who ran it (`author`, an org, a CI job) |
+| `selfAssessed` | boolean | `true` only when the author ran and judged it |
+
+How the audit treats a card:
+
+- Missing or malformed field → the practice is `not-measured`; a `status` word
+  alone is not evidence.
+- `expiresAt` before `generatedAt` → invalid card, `not-measured`.
+- `expiresAt` in the past (compared to today) → `stale`, and the whole BOOST
+  result is `stale`; refresh the card.
+- A `claimLevel` outside the five values → invalid card.
+- All eight practices need a valid card for `measured`; one card is
+  `1/8 practices have valid measured evidence cards`, not a pass.
+- `status: "failed"` is `failed` whether or not a card exists.
+- The card may also sit directly under `evidence` as an object, but
+  `evidenceCard` is unambiguous; a string `evidence` is only a note.
 
 If an effect cannot be measured (developer hours, maintenance cost, “fewer
 pitfalls”), record it as a WARN or a note. Do not invent a number.
@@ -69,9 +97,11 @@ npx -p dsh-standards dsh-levels ./my-plugin \
   --boost-evidence boost.json --format json
 ```
 
-Without evidence, the result is `not-measured`, not a pass. See
-[`40-checker`](https://github.com/PerryLink/dsh-standards/tree/main/40-checker)
-for the evidence schema and examples.
+Without evidence, the result is `not-measured`, not a pass. The card is
+validated by
+[`40-checker/scripts/level-audit.mjs`](https://github.com/PerryLink/dsh-standards/blob/main/40-checker/scripts/level-audit.mjs);
+keep the raw logs next to the card so a reviewer can re-run `command` and
+recompute `recordHash`.
 
 ## Author checklist
 

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

package/docs/recipes.md

@@ -0,0 +1,251 @@
+# Recipes: copy these, then re-run the checker
+
+<a id="before-you-copy"></a>
+## Before you copy
+
+Every block below was run against `dsh-standards` `40-checker` (`0.1.0`,
+anchor `ce7073d51254`, default runtime `0.2.2-alpha.2`). The package name
+`@acme/dsh-hello` is a placeholder — replace it everywhere, including the patch
+row. The numbers in the verify sections are what the checker printed here; if
+your output differs, the diff line is your fix.
+
+<a id="minimal-packagejson"></a>
+## Minimal `package.json`
+
+A plugin that exports `apply`, registers one tool, and can also be composed as
+a bundle row.
+
+```json
+{
+  "name": "@acme/dsh-hello",
+  "version": "0.1.0",
+  "description": "Minimal DSH plugin that registers one tool.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": ["index.js", "cordis.patch.yml"],
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": ">=0.2.2-0 <0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.2.2-0 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh": { "optional": true }
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "capabilities": ["tools:register"],
+    "labels": []
+  }
+}
+```
+
+| Field | What it buys | Check |
+|---|---|---|
+| `name` + exact `version` | a resolvable identity; a range or tag here is a FAIL | `C-1.1` |
+| `exports["."]` (or `main`) | the entry must resolve to a file inside the package | `C-1.2` |
+| `files` including the entry and patch | not checked, but `npm pack` can otherwise ship a manifest whose entry is absent | — |
+| `engines.dsh` | the only declaration that decides compatibility alone; `workspace:` is a FAIL | `C-2.1`/`C-2.3` |
+| `license` | avoids the `C-1.5` WARN; SPDX string | `C-1.5` |
+| `dsh.bundle.patch` | the file a bundle layer composes; in-package relative path | `C-1.4` |
+| `dsh.capabilities` | declares the host surfaces you touch; closed set of 15 | `C-11.1` |
+| `dsh.labels` | declares high-risk categories; closed set of 5; `[]` is allowed | `C-13.1` |
+| `dsh.kind` | `plugin` gets L1; `bundle` gets G0–G3; a client is static-only | `DSC-14` |
+
+Notes that come from the checker, not taste:
+
+- `dsh.capabilities` and `dsh.labels` are **standard extensions**: this host
+  does not read them. They are declarations, not enforcement. Declaring them
+  does not make the plugin safe, and omitting them is a WARN today.
+- `dsh.manifestVersion`, `dsh.bundle`, `dsh.client` are host fields; keep
+  `manifestVersion: 1`.
+- `engines.node` is **not** checked by the checker. Keep it for humans, but do
+  not expect a check to fail without it.
+
+<a id="entry-module"></a>
+## The entry module
+
+`C-1.2` resolves the entry, so the file must exist. `DSC-10` and `DSC-06` both
+look at what runs when and how it is cleaned up.
+
+```js
+export const name = 'dsh-hello'
+export const inject = []
+
+export function apply(ctx) {
+  ctx.effect(() => {
+    const timer = setInterval(() => {}, 60_000)
+    return () => clearInterval(timer)
+  }, 'dsh-hello.timer')
+
+  ctx.tools.register({
+    name: 'hello',
+    description: 'Say hello.',
+    async run() {
+      return 'hello'
+    },
+  })
+}
+```
+
+- `inject` lists only services you read; the runner stubs them for L1.
+- `ctx.effect(fn, 'label')` gives the disposer a label, so `dispose()` can go
+  back to zero (`C-6.2`, `C-7.1`).
+- `ctx.tools.register(...)` is the static trigger that requires
+  `capabilities: ["tools:register"]`.
+
+<a id="cordispatchyml-insert"></a>
+## `cordis.patch.yml`: the insert row
+
+```yaml
+- insert:
+    - id: dsh-hello
+      name: '@acme/dsh-hello'
+```
+
+Rules the checker and the host care about:
+
+- `id` is the stable row identifier later layers use to override this row. Keep
+  it short and unique.
+- `name` is the module the loader imports. For the **package-root row** it must
+  be the package name exactly (`@acme/dsh-hello`), because G4 looks for a
+  composed row whose `name` equals `manifest.name`. An `id` alone is not a row.
+- An insert is required. An `override`-only patch adds nothing to the profile;
+  the plugin is never loaded (G1 reports no target rows, G3 reports no active
+  rows).
+- The patch file stays inside the package and uses a relative path; `..`,
+  absolute paths, `~`, and `$VAR` are rejected (`C-1.4`).
+- Do not enable `@deepseek-ai/dsh-plugin-manager/tools` in a patch unless you
+  mean to hand every session the ability to install code (`C-11.3`).
+- G0 parses, G1 composes rows, G2 runs the compatibility gate, G3 boots the
+  target rows. Only G3 `verified` is a start; a `partial` result is
+  `ERROR`/`not-run`, not a pass.
+
+<a id="client-entry-and-root-row"></a>
+## Client entry and the package-root row
+
+A client is a dual-face package: a server/`dsh` half that is loaded as a row,
+and a prebuilt browser bundle at `exports["./client"]`.
+
+```json
+{
+  "name": "@acme/dsh-panel",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./lib/client.js"
+  },
+  "files": ["index.js", "lib", "cordis.patch.yml"],
+  "engines": { "dsh": ">=0.2.2-0 <0.3.0" },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "client",
+    "client": { "platform": "web" },
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "capabilities": [],
+    "labels": []
+  }
+}
+```
+
+```yaml
+# cordis.patch.yml — the same package name as the manifest
+- insert:
+    - id: dsh-panel
+      name: '@acme/dsh-panel'
+```
+
+The server half only has to load as a row; the browser half is the built file:
+
+```js
+// index.js — the server half; lib/client.js is the browser half
+export const name = 'dsh-panel'
+export const inject = []
+
+export function apply() {}
+```
+
+What each piece is for:
+
+| Piece | Why it is required | Where it shows up |
+|---|---|---|
+| `dsh.client` (non-empty) | marks the package as having a browser face | `G4`, `C-1` |
+| `dsh.client.platform` | the host selects the Web consumer with `"web"`; the checker only requires `dsh.client` to be non-empty | host manifest type |
+| `exports["./client"]` | a string path, or an object with a string `default`; must point at a **built** file (the checker only fails when it is absent) | `G4` → `DSC-01` FAIL if missing |
+| root row (`name` = package name) | the client scanner reads the loader's rows; no active row means the bundle is never discovered | `G4` in the bundle smoke |
+| `dsh.client.inject` | informational package names, not Cordis injection | host only |
+| `dsh.client.external` | extra module-table requests; omit unless you need them | host build |
+
+`"capabilities": []` says the server half touches no host surface. The checker
+still WARNs (`C-11.1: dsh.capabilities is empty`) and the report's reason line
+says `advisory: DSC-11`; in ENTRY that WARN is advisory, so the status stays
+`pass`. If the server half does touch something, fill the array from the trigger
+table in [entry.md](entry.md#capability-triggers) — an empty array is not a
+substitute for the capabilities you actually use.
+
+Two failure shapes you will see, and how to tell them apart:
+
+```text
+G4: FAIL dsh.client exists but exports["./client"] is missing; a package-root row cannot resolve it
+```
+
+The message names both causes. Add `exports["./client"]` first; if the export
+already exists, the bundle smoke is telling you the composed root row is
+missing — check that the patch `name` equals `manifest.name` and that the row is
+`insert`ed.
+
+```text
+DSC-14  FAIL  C-14  L1  G4 failed: dsh.client has no package-root row or missing client export
+```
+
+That is the same condition on a runtime claim. Without `--host`, a client is
+`DSH-ENTRY recognized` at best, and `DSC-14` is `NA`: build-only is not runtime.
+
+<a id="verify"></a>
+## Verify what you copied
+
+```sh
+# recognition only (no runtime claim): expect status=pass, exit=0
+npx dsh-standards . --scope entry --entry-claim static
+
+# plugin runtime: expect DSC-14 PASS and level "DSH-ENTRY runtime"
+npx dsh-standards . --scope entry \
+  --runtime /path/to/cordis/lib/index.js
+
+# bundle: expect "G0-G3 verified; rows=1/1"
+npx dsh-standards . --scope entry \
+  --host /path/to/@deepseek-ai/dsh-app-boot/lib/index.js
+
+# machine-readable: read .conclusion.level and .g4
+npx dsh-standards . --format json
+```
+
+For the plugin recipe above, the static run prints:
+
+```text
+DSC-01  PASS  C-1    L0
+DSC-02  PASS  C-2    L0
+DSC-11  PASS  C-11   L0
+DSC-12  PASS  C-12   L0
+DSC-13  PASS  C-13   L0
+level: DSH-ENTRY recognized
+```
+
+For the client recipe, the same run ends `status=pass`, prints
+`level: DSH-ENTRY recognized`, and still shows
+`C-11.1: dsh.capabilities is empty` with `reason: advisory: DSC-11`. That is the
+transitional empty-array WARN, not a G4 failure. A `kind: client` package is
+static-only: `DSC-14` is `NA`, so `--host` cannot turn it into
+`DSH-ENTRY runtime`. Only a package installed as a bundle (`kind: bundle`)
+reaches runtime through G0–G3, and its G4 needs both the client export and the
+root row. If `G4` fails you get `exit=1` and no level — add the missing export
+or row, do not reword the report.

package/docs/rules.md

@@ -0,0 +1,99 @@
+# Rules: decode a check report in one table
+
+<a id="how-to-read"></a>
+## How to read one report line
+
+A DS-C report has one line per check: `id`, `result`, `clause`, `layer`,
+`reason`. The detail lines under it (`C-1.2`, `C-11.5`, `G4`) are what you
+actually fix.
+
+| Result | Meaning | What it does to the verdict |
+|---|---|---|
+| `PASS` | the check ran and found nothing | counts as pass |
+| `WARN` | ran, found something worth fixing | does not fail the run; `status` becomes `warn` (advisory checks excepted) |
+| `FAIL` | ran, found an attributable defect | `status=fail`, exit `1` |
+| `NA` | the check does not apply (wrong `dsh.kind`, no field, package profile) | allowed; not a pass |
+| `ERROR` | the check could not run (`coverage: not-run`, e.g. no `--runtime`/`--host`) | `status=incomplete`, exit `2` |
+
+Exit codes: `0` completed (pass or warn), `1` attributable FAIL, `2`
+incomplete/not-run, `3` usage error. `WARN` is not a clean pass and
+`incomplete` is not a pass — both are printed as such on purpose.
+
+The JSON report also carries a sibling `advice[]` array: one entry per live
+detail, with `title`, `why`, `fix`, `docsUrl`, `severity`, and `evidence`. It is
+additive and never changes the verdict (turn it off with `--no-advice`). The
+`docsUrl` is built from a release-pinned base (`v0.4.3` in the current rule
+table); if it points at an older page, this table is the current mapping.
+
+<a id="scope-matrix"></a>
+## Which checks run in which scope
+
+| Scope / profile | Mandatory checks | Notes |
+|---|---|---|
+| `--scope ds-c` (default), `package` | 01, 02, 04–09, 11, 12, 13 | 03 is `NA`, 10 is advisory, 14 is not run |
+| `--scope ds-c`, `listing` | + 03 | install spec / market index are now judged |
+| `--scope entry --entry-claim static` | 01, 02, 11, 12, 13 (+ 03 for listing) | 04–09 are attempted and printed (usually `ERROR`/`NA`), 14 is `NA`; a `DSC-11`/`DSC-12`/`DSC-13` FAIL is downgraded to `WARN` |
+| `--scope entry --entry-claim runtime` | + 14 | 14 carries the runtime verdict, not 04–09 |
+| `--scope mvp` | 01, 02, 04–09 | the MVP subset, labelled `MVP-13` |
+
+<a id="table"></a>
+## The check table
+
+| Check | Clause | Blocking or advice | One-line fix | Guide |
+|---|---|---|---|---|
+| **DSC-01** | C-1 manifest + entry | Blocking (ds-c, entry). C-1.3/C-1.5/C-1.6 are WARN/NA. A `G4` detail is reported here. | Exact `name`/`version`, `exports["."]` or `main` resolving to a file inside the package, in-package `dsh.bundle.patch` paths, and a `license`. | [entry.md § package shape](entry.md#package-shape) · [recipes](recipes.md#minimal-packagejson) |
+| **DSC-02** | C-2 version range | Blocking (ds-c). In ENTRY, a static claim downgrades the whole check to WARN; a runtime claim keeps `C-2.2`/`C-2.3` blocking. | Declare `engines.dsh` as a range that contains the host you target (`>=0.2.2-0 <0.3.0`); never publish `workspace:`. | [entry.md § package shape](entry.md#package-shape) |
+| **DSC-03** | C-3 install source | Blocking (listing only); `NA` in package profile. | Pin the source: exact version or verifiable tag, `#<40-hex>` for git, an in-package path, and a `format:1` market entry with pinned versions. | [entry.md § package shape](entry.md#package-shape) |
+| **DSC-04** | C-4 load to ACTIVE | Blocking (ds-c, when a runtime runs). | Make the entry import cleanly and reach `ACTIVE`: no throw at import, no module-scope work, declare `inject` or read `ctx.get()`, move work into `apply()`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-05** | C-5 declared provide | Blocking (ds-c). | Every name in `export const provide` must be registered by this plugin's own fiber via `ctx.provide(name, impl)`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-06** | C-6 effects | Blocking (ds-c); anonymous effects are WARN. | Wrap timers, watchers, sockets, and subprocesses in `ctx.effect(fn, 'label')`; never write `ctx.reflect.store` or `ctx.events._hooks`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-07** | C-7 unload residue | Blocking (ds-c). | Return a disposer from every effect so `dispose()` leaves `getEffects()===0`, the service store at baseline, and `registry.size` unchanged. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-08** | C-8 restart idempotence | Blocking (ds-c). | Make `restart()` re-enter `ACTIVE`, keep the effect count, advance revision/epoch, and succeed from a fresh `Context`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-09** | C-9 declared vs measured | Blocking (ds-c) for `C-9.1`; `C-9.2`/`C-9.3` are WARN. | Keep declarations equal to reality: provided ⊆ measured, measured ⊆ declared, and each declared `inject` is really read as `ctx.<service>`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-10** | C-10 import-time work | Advice only; never changes the verdict. | Move module-scope `await`, timers, `process.on`, fs writes, and spawns into `apply()` and clean up with `ctx.effect()`. | [entry.md § import-time side effects](entry.md#import-time-side-effects) |
+| **DSC-11** | C-11 capabilities | Blocking (ds-c); `WARN` in ENTRY, and a `WARN` here is advisory even in ds-c. | Declare `dsh.capabilities` from the closed set, add one entry per static trigger, and never enable `@deepseek-ai/dsh-plugin-manager/tools` in a patch. | [entry.md § capability triggers](entry.md#capability-triggers) |
+| **DSC-12** | C-12 credentials + seams | Blocking (ds-c); `WARN` in ENTRY. | Read credentials through `ctx.credentials`, declare `credentials:list` for `listRecords()` and `credentials:provider` for a provider, and never read the backing file. | [entry.md § credentials and seams](entry.md#credentials-and-seams) |
+| **DSC-13** | C-13 labels + mirror | Blocking (ds-c); `WARN` in ENTRY, advisory as a WARN. | Use only the five labels, add the label each capability requires, point `dsh.upstream` at an https URL that is not this package **and** add `mirror`, and drop endorsement words. | [entry.md § labels and mirror](entry.md#labels-and-mirror) |
+| **DSC-14** | C-14 entry run | Blocking only for a runtime claim (`--scope entry`). | Supply the real host: `--host` for a bundle (G0–G3) or `--runtime` for a plugin (L1); a client or preset cannot claim runtime. | [entry.md § runtime surface](entry.md#runtime-surface) |
+
+`DSC-14` has no `C-14` in the clause text; it is the ENTRY run-set gate
+(`ENT-14` in 31-DSH-ENTRY). Treat it as "did the thing actually start".
+
+<a id="warn"></a>
+## Two things that look like passes but are not
+
+**Advisory WARN.** `DSC-10` is always advisory. `DSC-11` and `DSC-13` become
+advisory whenever the check itself returns `WARN`, because the host does not
+read those fields yet. The effect is visible: this guide's own report prints
+`DSC-11 WARN`, `DSC-13 WARN`, yet `coverage.warn=0` and
+`reason: advisory: DSC-11, DSC-13`. Read the reason line, not only the coverage
+counts. A `FAIL` that ENTRY downgrades to `WARN` is a plain WARN and does stay
+in the counts.
+
+**`incomplete`.** If a mandatory check has `coverage: not-run` (no runtime, no
+host, a killed child, a partial AST parse), the status is `incomplete` and the
+exit code is `2`. The report prints `NOT A DS-C PASS`. Do not paste a
+`not-run` row into a README as a pass; write `not-run` or run the check.
+
+<a id="not-checked"></a>
+## What the checker does not check
+
+These are good practice but **not** evidence of a pass, because no check reads
+them:
+
+- `engines.node` (the 24.9 line is a guide recommendation; `DSC-02` looks at
+  `engines.dsh` and `@deepseek-ai/dsh*` peers only)
+- README install instructions, display metadata, keywords, `icon`
+- endorsement words in prose, `description`, or README — `C-13.4` scans only
+  the `dsh.labels` array
+- whether a `red-team` label was actually used for red-team work (`C-13.5`
+  only asks for `dsh.usageScope`)
+- browser rendering of a client bundle (`G4` is a static shape check)
+
+The checker's default `--runtime-version` is `0.2.2-alpha.2`. Pass
+`--runtime-version <the host you target>` when that differs, or `DSC-02` will
+judge your range against the wrong version.
+
+If a report FAILs and you cannot find the ID here, open
+[`docs/recipes.md`](recipes.md) for the copy-paste shape, then re-run the same
+command and compare the detail lines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "A practical guide to DSH plugin quality: ENTRY checks, FLOW checks, and BOOST guidance. Community guide; not official, not a certification, not a ranking.",
   "type": "module",
   "main": "index.js",