@canonical/pragma-cli 0.35.0 → 0.36.0

package/src/kernel/render/vocabulary.ts

@@ -0,0 +1,276 @@
+/**
+ * The rendering vocabulary — the ONE place a state and the word for it meet.
+ *
+ * `doctor` reports states, `setup` plans and applies them, and both speak to
+ * the same reader about the same machine. For as long as each surface spelled
+ * the states itself — three glyph tables, two scope-label maps, two indent
+ * constants — the type layer and the copy layer were free to disagree, and a
+ * copy pass could rename a scope in every sentence while the model underneath
+ * kept the old word. This module ends that freedom: the statuses, their
+ * glyphs, the scope names, and the shared layout markers are each defined
+ * once, here, and every renderer reads them.
+ *
+ * The SCOPES are **global** and **local project**, chosen because they are the
+ * words the user already typed: `--global` and `--local`. Reading `Local
+ * project` above a row whose fix is `pragma setup mcp --local` is the whole
+ * point — the report names the flag that repairs it. (Earlier these surfaces
+ * said MACHINE/PROJECT, and later "global band"/"project band": a third and a
+ * fourth term for the same two things, and "band" is a word nobody outside
+ * this repository has ever used for a config scope. The type layer carried
+ * "band" longest — `ScopeBand`, `PlanRow.band`, a `bands.ts` — and the render
+ * tests now guard against either spelling coming back.)
+ *
+ * The GLYPHS are one small alphabet with fixed meanings, so the same mark
+ * never says two things: `✓` is work done or verified, `✗` is a real fault,
+ * `◇` is available-but-not-set-up, `○` is inert (nothing to act on), and `·`
+ * is neutral punctuation — a sub-item bullet, or a row that never ran. Doctor
+ * and setup map their own status tiers onto that alphabet below, which is what
+ * keeps a failed setup row and a failed doctor row — the same finding seen
+ * twice — wearing the same mark.
+ *
+ * This is the RENDERING vocabulary; the graph-domain vocabulary a distribution
+ * declares (`kernel/vocabulary.ts`) is a different thing with the same good
+ * reason for existing. Like the rest of `kernel/render/`, this module is
+ * statically reachable from the `--help`/`__complete` fast paths, so it
+ * imports NOTHING — it is inert data plus two pure one-line functions.
+ */
+
+// =============================================================================
+// Scopes
+// =============================================================================
+
+/**
+ * One of the two config scopes: the per-user/home `global` scope or the
+ * per-repository `project` scope. Mirrors `@canonical/harnesses`' `ScopeBand`
+ * STRUCTURALLY (pinned by `scopeTypeSync.test.ts`) but is declared here so the
+ * statically-reachable type modules never pull the harnesses runtime onto the
+ * fast-path module graph — and under pragma's own name for the concept, the
+ * one the `--global`/`--local` flags and every rendered sentence use.
+ */
+export type Scope = "project" | "global";
+
+/**
+ * The resolved scope selection: which scope(s) a run touches. `global` is the
+ * DEFAULT — the user/home scope a machine-level installer configures;
+ * `project` is the opt-in per-repository scope; `both` is the explicit "run
+ * each scope in one invocation". Structurally mirrors the harnesses
+ * `ScopeSelection` (same pin).
+ */
+export type ScopeSelection = Scope | "both";
+
+/** The user-facing display label for each of the two config scopes. */
+export const SCOPE_LABELS: Record<Scope, string> = {
+  global: "Global",
+  project: "Local project",
+};
+
+/**
+ * The scope phrase in running text — the lowercase form of
+ * {@link SCOPE_LABELS}, plus the word for "both". Authored here rather than
+ * lowercased at the call site so a reader grepping for either spelling lands
+ * in one file.
+ */
+export const SCOPE_PHRASES: Record<ScopeSelection, string> = {
+  global: "global",
+  project: "local project",
+  both: "global and local project",
+};
+
+// =============================================================================
+// The glyph alphabet
+// =============================================================================
+
+/**
+ * The five marks, by meaning. Uncolored — every glyph is tinted at render
+ * time, never baked at module load. `summon-core`'s Ink wizard renders the
+ * same `success`/`failure` marks for the same meanings; the two packages
+ * cannot share this module (the dependency runs the other way, and the
+ * fast-path covenants forbid the import), so `renderVocabularySync.test.ts`
+ * pins the two alphabets to byte equality instead.
+ */
+export const GLYPHS = {
+  /** Work done, or a state verified healthy. */
+  success: "✓",
+  /** A real fault — something set up that no longer works, or a failed row. */
+  failure: "✗",
+  /** Detected and installable, but not set up — an invitation, not a fault. */
+  available: "◇",
+  /** Inert: nothing to act on here, and nothing wrong either. */
+  inert: "○",
+  /** Neutral punctuation — a sub-item bullet, or a row that never ran. */
+  neutral: "·",
+} as const;
+
+/** The arrow in front of an inline instruction (`↳ fix: …`). */
+export const FIX_ARROW = "↳";
+
+/** The bullet a check's indented sub-items carry. */
+export const SUB_BULLET = GLYPHS.neutral;
+
+/**
+ * The marker for a row that carries NO outcome — one the user deselected, so
+ * it was neither done nor skipped-for-cause. It must not be a ✓: a green check
+ * against work that never ran is the same lie the old recap told when it
+ * reported "Setup complete" over a target it had dropped.
+ */
+export const NOT_RUN_GLYPH = GLYPHS.neutral;
+
+// =============================================================================
+// Indents
+// =============================================================================
+
+/** One indent step — every list body row starts two spaces in. */
+export const INDENT = "  ";
+
+/**
+ * The indent that aligns a check's sub-lines under its name: the row's own
+ * {@link INDENT}, plus one glyph column, plus the two-space gap after it.
+ */
+export const SUB_INDENT = "     ";
+
+// =============================================================================
+// Doctor's status tiers
+// =============================================================================
+
+/**
+ * Status of a doctor check or one of its sub-items.
+ *
+ * `available` is the tier between fail and skip that keeps the report honest:
+ * an opt-in integration (MCP registration, skills symlinks, a completion
+ * script) that is detected and installable but that the user has not set up.
+ * Nothing is broken — a fresh install is HEALTHY with several availables — so
+ * reporting these as `fail` would teach users that the failure count is noise.
+ * `fail` stays reserved for a real fault: something set up that no longer
+ * works, or an environment the CLI cannot run correctly in. `skip` remains
+ * "nothing to check here" (no shell detected, no harnesses present).
+ */
+export type CheckStatus = "pass" | "fail" | "available" | "skip";
+
+/**
+ * Each check status's mark. `available` gets its own glyph, distinct from ✗:
+ * an opt-in integration that is not set up is not a fault, and rendering it as
+ * one would train users to ignore the failure count. The glyph pairs with the
+ * word in the tally, so the distinction survives with color stripped.
+ */
+export const CHECK_GLYPHS: Record<CheckStatus, string> = {
+  pass: GLYPHS.success,
+  fail: GLYPHS.failure,
+  available: GLYPHS.available,
+  skip: GLYPHS.inert,
+};
+
+/**
+ * The word in front of a check row's instruction, chosen by what the row IS.
+ *
+ * A `fail` and an `available` are things to repair or switch on, so they read
+ * `fix`. A `skip` is neither — nothing is wrong and nothing is off; the row
+ * simply has nothing to act on yet — so labelling its instruction `fix` would
+ * be the same "a skip is a fault" reading the `available` glyph exists to
+ * prevent. It reads `next`, which is what the line actually is.
+ */
+export const checkRemedyWord = (status: CheckStatus): "fix" | "next" =>
+  status === "skip" ? "next" : "fix";
+
+// =============================================================================
+// Setup's outcome tiers
+// =============================================================================
+
+/**
+ * How one setup row ended. `skipped` is NOT a failure — see
+ * `setup/plan.ts#planExitFailed`, which states the exit rule once.
+ */
+export type OutcomeStatus =
+  | "done"
+  | "noop"
+  | "skipped"
+  | "failed"
+  | "removed"
+  | "kept";
+
+/**
+ * Each outcome's mark. The three ways work can be complete — `done`, `noop`
+ * (already current), `removed` — all read ✓; the two ways a row can stand
+ * aside — `kept`, `skipped` — read the inert ○; only `failed` earns ✗.
+ */
+export const OUTCOME_GLYPHS: Record<OutcomeStatus, string> = {
+  done: GLYPHS.success,
+  noop: GLYPHS.success,
+  removed: GLYPHS.success,
+  kept: GLYPHS.inert,
+  skipped: GLYPHS.inert,
+  failed: GLYPHS.failure,
+};
+
+/**
+ * The word in front of a row outcome's instruction — `fix` for a row that
+ * failed, `next` for one that skipped. Same rule as {@link checkRemedyWord}: a
+ * skip is not a fault, and labelling its instruction as a repair is what
+ * teaches a reader to treat skips as failures.
+ */
+export const outcomeRemedyWord = (status: OutcomeStatus): "fix" | "next" =>
+  status === "failed" ? "fix" : "next";
+
+// =============================================================================
+// Install-source states
+// =============================================================================
+
+/**
+ * How the running CLI got onto the machine — the state `info`, `upgrade`, and
+ * doctor's `pragma version` row all report, so its words live here with the
+ * other shared states. Only a `global` install has a sanctioned update
+ * command; the type layer in `capabilities/shared/packageManager.ts` makes the
+ * others structurally command-less, and {@link INSTALL_UPDATE_GUIDANCE} is
+ * what those states say instead. `linked` in particular must never be handed
+ * an install command: `npm i -g` against a linked checkout would overwrite the
+ * link to the development tree the user is working in.
+ */
+export type InstallKind =
+  | "global"
+  | "workspace"
+  | "linked"
+  | "ephemeral"
+  | "unknown";
+
+/** The install kinds that carry NO update command (everything but `global`). */
+export type NoCommandInstallKind = Exclude<InstallKind, "global">;
+
+/**
+ * The display label for an install source, e.g. `npm (global)`, `bun link
+ * (development checkout)`, `npx (ephemeral)`, `unknown (node runtime)`. The
+ * `via` word is the manager/runner/runtime name the detector resolved —
+ * absent only for a `workspace`/`linked` install whose manager could not be
+ * told, which then reads as the bare state.
+ */
+export const installSourceLabel = (kind: InstallKind, via?: string): string => {
+  switch (kind) {
+    case "global":
+      return `${via} (global)`;
+    case "workspace":
+      return via ? `${via} (local project)` : "local project dependency";
+    case "linked":
+      return via
+        ? `${via} link (development checkout)`
+        : "linked (development checkout)";
+    case "ephemeral":
+      return `${via} (ephemeral)`;
+    case "unknown":
+      return `unknown (${via} runtime)`;
+  }
+};
+
+/**
+ * What each command-less install state says when a newer release exists —
+ * honest guidance in place of a command that would be wrong to run. The
+ * `linked` sentence is the load-bearing one: it replaces the `npm i -g` that
+ * would clobber the development link.
+ */
+export const INSTALL_UPDATE_GUIDANCE: Record<NoCommandInstallKind, string> = {
+  workspace:
+    "Installed as a project dependency — update it through the project's package.json.",
+  linked:
+    "Linked development checkout — update it from its source tree, or unlink it before installing a release.",
+  ephemeral:
+    "Ephemeral run — invoke it again with an explicit @latest version to pick up the newest release.",
+  unknown:
+    "The install method cannot be determined — update it the same way it was installed.",
+};

package/src/kernel/spec/emitReference.ts

@@ -541,7 +541,7 @@ const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
   logo: {
     type: "string[] (optional)",
     notes:
-      "Distribution-only — see below. ASCII-art wordmark lines shown above the header on root `--help`, tinted with the terminal palette's orange slot. Declared content, not code: a wordmark spells the distribution's name, so a fork ships its own art or omits the field and gets no wordmark. Omit or leave empty for a bare header.",
+      "Distribution-only — see below. ASCII-art wordmark lines shown above the header on root `--help`, tinted with the terminal palette's orange slot. Shown to a HUMAN reader only: the front door omits the art for MACHINE-ORIENTED output — `--format llm` or `--format json`, plus the `llm` a non-interactive stdout auto-infers — so a piped `--help` spends none of an agent's budget on a picture of the name it just typed. The gate is the output SHAPE, not whether stdout is a terminal, and explicit beats inferred in both directions: `--format plain` keeps the art down a pipe (as does `PRAGMA_NO_AUTO_LLM`, which turns the inference off), and `--format llm` drops it on a TTY. Declared content, not code: a wordmark spells the distribution's name, so a fork ships its own art or omits the field and gets no wordmark. Omit or leave empty for a bare header.",
   },
   colophon: {
     type: "object (optional)",

package/src/kernel/spec/types.ts

@@ -149,11 +149,40 @@ export type ParamSpec =
  * list-shaped formatters read it; `llm` (the byte-frozen agent contract) and
  * `json` (the envelope) never see it.
  *
- * `emptyNotice` is the empty-state seam: when the data amounts to zero
- * records, return the calm notice — the dispatcher routes it to STDERR with
- * exit 0, keeping the stdout data stream free of human sentences a pipe
- * would read as records. Return `undefined` (or omit the member) for data
- * that has content; only the plain mode routes it.
+ * `notice` is the seam for what the DATA cannot say about itself. Return the
+ * calm sentence when the payload would otherwise misrepresent the read; return
+ * `undefined` (or omit the member) when it speaks for itself.
+ *
+ * Two shapes qualify, and they are the same failure. A zero-record result
+ * ("empty ≠ silence"): an unbuilt store, a mistyped filter and a genuinely empty
+ * result were all `{"ok":true,"data":[],"meta":{}}`. And a result that is one of
+ * several it could have been — a `lookup` whose name reached more entities than
+ * the one it answers with. A caller shown Launchpad's `Button` has no way to
+ * discover the global one from a payload that looks exactly like an unambiguous
+ * hit; the notice names the IRIs the answer did not take, which is the only
+ * address that reaches them.
+ *
+ * It was called `emptyNotice` while emptiness was the only case. The channel is
+ * unchanged — same key, same three surfaces — so this is one seam covering both,
+ * not a second one grown beside it.
+ *
+ * Three surfaces route it, each in its own register — it is one seam, not a
+ * plain-mode courtesy:
+ * - `plain`: the dispatcher writes it to STDERR with exit 0, keeping the stdout
+ *   data stream free of human sentences a pipe would read as records. `--quiet`
+ *   mutes it (success-path guidance).
+ * - `--format json` AND the MCP tool result: it rides the envelope as
+ *   `meta.notice` (`project/cli/dispatch.ts#renderData`,
+ *   `project/mcp/registerVerb.ts#emptyMeta` — the same key from the same seam,
+ *   so the two MACHINE surfaces stay byte-equal). `data` keeps its uniform empty
+ *   shape; `[]` stays `[]`. Without it an agent could not tell an unbuilt store,
+ *   a mistyped filter and a genuinely empty result apart — all three were
+ *   `{"ok":true,"data":[],"meta":{}}`.
+ * - `llm` (the byte-frozen agent contract) is the ONE mode that still ignores
+ *   it: it renders one stream and its bytes are frozen.
+ *
+ * The formatters themselves never see the notice: `json(d)` renders the data
+ * alone, and the ENVELOPE layer carries the notice beside it.
  */
 export interface Formatters<T> {
   readonly plain: (
@@ -162,7 +191,7 @@ export interface Formatters<T> {
   ) => string;
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
-  readonly emptyNotice?: (d: T) => string | undefined;
+  readonly notice?: (d: T) => string | undefined;
 }
 
 /** A usage example shown in verb help. */

package/src/testing/PARITY_GAPS.ts

@@ -42,13 +42,13 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "read-meta-always-empty",
     area: "envelope",
     description:
-      "`dispatch.ts#executeVerb`'s read branch always renders with `meta: {}` — there is no `meta.count`/`meta.total` field on a list/lookup envelope (verified empirically). An empty (possibly filtered) list is `{ok:true, data:[], meta:{}}`; the only way to know it's empty is `data.length === 0`, not a meta field.",
+      "NARROWED: a read envelope still carries no `meta.count`/`meta.total` — the only way to know a list is empty is `data.length === 0`, not a count field. But `meta` is no longer ALWAYS `{}` on a read. A zero-record read now carries the verb's own `notice` as `meta.notice` on BOTH machine surfaces (`project/cli/dispatch.ts#renderData` for `--format json`, `project/mcp/registerVerb.ts#emptyMeta` for MCP — one seam, the same key, so the two stay byte-equal). `data` keeps its uniform empty shape; `[]` is still `[]`. The divergence this entry records is the ABSENCE of counts, not the emptiness of `meta`: without the notice an agent could not tell an unbuilt store, a mistyped filter and a genuinely empty result apart, all three being `{ok:true,data:[],meta:{}}`.",
   },
   {
     id: "no-empty-hook-on-free-filter",
     area: "pack list / empty-state",
     description:
-      "A zero-row pack list — whether narrowed by a declared filter, an unmatched `--search`, or unconditionally empty — returns `ok:true, data:[], meta:{}` at exit 0 with a calm `emptyMessage`/`emptyHint`; pragma v2 never raises a typed EMPTY_RESULTS error for an empty list. (U5 removed the former enum-filter-only `buildListEmptyError` hook, making the empty-state uniform across every list verb.)",
+      "STILL TRUE OF EMPTINESS, NARROWED ON BAD ARGUMENTS. A zero-row pack list — narrowed by a declared filter, by an unmatched `--search`, or unconditionally empty — is a SUCCESS: `ok:true, data:[]` at exit 0 with a calm notice (stderr in plain mode, `meta.notice` on the machine surfaces). pragma v2 still never raises EMPTY_RESULTS for an empty list, and U5's removal of the enum-filter-only `buildListEmptyError` hook stands. What is no longer true is that an UNMATCHED free-filter value stays successful: a value-free filter now rejects a value its vocabulary does not admit with INVALID_INPUT and the admissible values as `validOptions`, the same courtesy a declared-`values` filter always extended (`packs/sparql/applyFilters.ts`). The vocabulary is the graph's, not the returned rows' — a filter declares where it lives (`PackFilter.vocabulary`), so a real value that happens to match no row (a category with zero standards, a `ds:ConceptType` no concept uses) is a calm empty list, and only a value the graph does not know is an error.",
   },
   {
     id: "raw-iri-in-data",
@@ -84,7 +84,7 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "block-lookup-not-tier-scoped",
     area: "block",
     description:
-      "`block lookup` resolves by `ds:name` GLOBALLY, with no tier or channel filtering. A same-named block declared at two tiers cannot be disambiguated by plain name (the old shell's tier-scoped lookup disambiguation has no v2 equivalent) — address it by prefixed IRI instead. Since L-OPEN-9 NOTHING is tier/channel-aware: the hand-written, tier-chain-filtered `block list` was removed with its `tierChain.ts`.",
+      "CLOSED, by REVERSAL of the entry it used to be. This gap read: `block lookup` resolves by `ds:name` globally, a same-named block at two tiers cannot be disambiguated by plain name, address it by prefixed IRI instead. That was accepted while the answer was merely arbitrary; it stopped being acceptable once measured — 25 live block names are carried by 2–3 blocks, and EVERY one of them was answered with whichever IRI sorted first and no sign the others existed (`block lookup button` returned Launchpad's Button, because `apps_launchpad…` precedes `global…`). 'Address it by IRI' is not a recovery an agent can reach when nothing tells it there is a second block to address. Two things replace it, and neither is a change of arity — one name still answers with one entity, and a glob is still the declared multi-entity form. (1) The discard is no longer SILENT: the resolve is unlimited, the winner is answered with, and the IRIs it outranked ride the verb's `notice` — the same seam a zero-record read uses (stderr in plain mode, `meta.notice` on `--format json` and MCP), because an ambiguous hit is the same failure as an empty one, a result that misrepresents itself. `LookupOutput.ambiguous` carries them in `data` for the machine surfaces, and is ABSENT (not `[]`) when nothing was ambiguous, so every unambiguous read keeps the payload it had. Note the recovery is not reachable any other way: a glob expands over DISTINCT names, so `block lookup 'Butt*'` returned Launchpad's Button and ButtonLink and the global Button appeared nowhere. (2) The order is a declared, derived RANKING (`PackLookup.scopeWeight` in `pragma.conf.ts`, generated by `packs/sparql/buildLookupQuery.ts#rankingClause`): a tier's depth comes from the `/` count in its OWN `ds:name` (`\"Apps/Launchpad\"` → 2, never from the `_` in `ds:apps_launchpad`), and it MULTIPLIES the existing type weight rather than tiebreaking above it, so a whole component in a nested tier still outranks a global SUBcomponent (`TextInput`). Nothing is enumerated, so a tier added upstream is placed without an edit here; an asserted `ds:tierRank` would take precedence over the derived depth and retire the config declaration with no code change. WHAT REMAINS a gap: `lookup` is still not tier-SCOPED — there is no way to ask for one tier's answer only, the ranking merely decides which comes first — and since L-OPEN-9 nothing is tier/channel-FILTERED (the hand-written `block list` went with its `tierChain.ts`; see `block-list-unfiltered`). Two top-level tiers still cannot be ordered against each other by depth alone, which today leaves `Navigation` (`global` vs `apps`) and `InfoTable` (`global` vs `sites`) decided by the IRI fallback; naming a precedence among the depth-1 tiers is an ontology question, deliberately NOT invented here.",
   },
   {
     id: "block-list-unfiltered",
@@ -182,4 +182,10 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     description:
       "The native MCP `prompts/list` (and the `prompt_list`/`prompt_lookup` content tools) project `ds:Prompt` KG entities read from the ACTIVE pack index (`kernel/project/mcp/prompts/source.ts#listPromptSummaries`) — project-supplied data, NOT shipped in the embedded/bundled pack. A bare install (no project-authored `ds:Prompt`) advertises the prompts capability but lists ZERO prompts, never booting the store on the list path. Non-empty listings are exercised only against the seeded fixture graph (`testing/fixtures/graph/canonical.ts`); the storeless empty-by-default case is pinned by `prompts.test.ts` ('lists zero prompts … when no prompt entities exist').",
   },
+  {
+    id: "scope-not-band-in-machine-output",
+    area: "setup / doctor `--format json`",
+    description:
+      "A setup plan row and a doctor check carry their config scope under the key `scope` (values `global`/`project`), not `band`. The old shell's type layer said `band` (`ScopeBand`, `PlanRow.band`, `CheckResult.band`) while every user-facing string had already moved to the scope vocabulary the `--global`/`--local` flags use; the type-layer rename (kernel/render/vocabulary.ts) finished the move, and `--format json`/MCP emit the model verbatim, so the machine key moved with it. Any consumer reading `.band` off `setup --format json` or `doctor --format json` reads `.scope` now — `setup.render.test.ts` pins that neither spelling of `band` can return through any render, JSON included.",
+  },
 ] as const;

package/src/testing/behavioral/docExamples.test.ts

@@ -164,9 +164,11 @@ const READ_CASES: readonly ReadCase[] = [
   },
   { command: "pragma standard list", key: "standard list", params: {} },
   {
-    command: "pragma standard list --category react",
+    // The doc's headline example, and the one the roll-up is about: a parent
+    // category answering for its whole branch.
+    command: "pragma standard list --category testing",
     key: "standard list",
-    params: { category: ["react"] },
+    params: { category: ["testing"] },
   },
   {
     command: "pragma standard categories",

package/src/testing/behavioral/errorMatrix.mcp.test.ts

@@ -11,10 +11,16 @@
  *    a total miss; only a PARTIAL batch reports the miss while staying
  *    `ok:true` (that shape is B1's job, `agentSession.mcp.test.ts`). See
  *    PARITY_GAPS `single-lookup-miss-fails-batch-partial-reports`.
- * 2. A filtered list narrowed to zero rows is `{ok:true, data:[], meta:{}}` —
- *    there is no `meta.count` field on any read envelope (`dispatch.ts`
- *    always renders reads with `meta:{}`). See PARITY_GAPS
- *    `read-meta-always-empty`.
+ * 2. A filtered list narrowed to zero rows is `{ok:true, data:[]}` — there is
+ *    still no `meta.count` field on any read envelope, which is the divergence
+ *    `read-meta-always-empty` now records (it no longer claims `meta` is always
+ *    `{}`: a zero-record read carries the list's own `notice` as
+ *    `meta.notice` on both machine surfaces, asserted below).
+ * 3. A value-free filter given a value its vocabulary does not admit is
+ *    INVALID_INPUT, not a successful empty list — the narrowing recorded in
+ *    PARITY_GAPS `no-empty-hook-on-free-filter`. Emptiness itself is still a
+ *    success: a value the GRAPH admits but no row carries (a category with zero
+ *    standards) is a calm empty list, asserted below.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -88,7 +94,22 @@ describe("lookup miss — total miss fails the call (B3, adapted)", () => {
   });
 });
 
-describe("list — a narrowing filter to zero rows is a plain empty list (B3, adapted)", () => {
+/**
+ * CHANGED DELIBERATELY. This used to assert that ANY filter value narrowed to a
+ * plain `{"ok":true,"data":[],"meta":{}}`, which was written when no value-free
+ * filter could tell a typo from an empty answer. It could: the rows it is
+ * filtering carry the vocabulary. Over MCP the old shape made a mistyped
+ * `--category`, an unbuilt store and a genuinely empty category byte-identical —
+ * the silence a model has no way to recover from.
+ *
+ * A value the graph does not know is now INVALID_INPUT with the admissible
+ * values as `validOptions`, exactly as a filter declaring `values` has always
+ * behaved; the difference is that the vocabulary is READ FROM THE GRAPH rather
+ * than copied into the story. Zero rows for a value that DOES exist stays a calm
+ * empty list — that is a real answer, not a bad argument — and "exists" means
+ * the graph declares it, not that some returned row happened to carry it.
+ */
+describe("list — a filter value the graph does not carry is INVALID_INPUT (B3, adapted)", () => {
   it("has at least one filtered list verb to sweep", () => {
     // A guard, not a no-op: if this ever goes empty the sweep below silently
     // covers nothing, which would be a silent coverage loss worth noticing.
@@ -97,16 +118,98 @@ describe("list — a narrowing filter to zero rows is a plain empty list (B3, ad
 
   it.each(
     filteredListVerbs,
-  )("$tool: an unmatched filter value narrows to [] (no EMPTY_RESULTS)", async ({
+  )("$tool: an unobserved filter value is rejected, naming the observed ones", async ({
     tool,
     param,
   }) => {
     const result = await mcp.callTool(tool, {
       [param]: "zzz-definitely-not-a-real-value",
     });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string; validOptions?: string[] };
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions?.length).toBeGreaterThan(0);
+    expect(error.validOptions).not.toContain("zzz-definitely-not-a-real-value");
+  });
+
+  it.each(
+    filteredListVerbs,
+  )("$tool: every value the graph DOES carry narrows to a calm list", async ({
+    tool,
+    param,
+  }) => {
+    const rejected = await mcp.callTool(tool, { [param]: "zzz-nope" });
+    const admissible = (rejected.error as { validOptions: string[] })
+      .validOptions;
+    expect(admissible.length).toBeGreaterThan(0);
+    // EVERY admissible value is accepted, and at least one is populated. Not
+    // "the first one returns rows": the vocabulary is the graph's, so it can
+    // legitimately contain a value no row carries (a category with zero
+    // standards) — that value is a calm empty list, not a rejection, and the
+    // sweep would otherwise read a real answer as a failure.
+    let populated = 0;
+    for (const value of admissible) {
+      const result = await mcp.callTool(tool, { [param]: value });
+      expect(result.ok).toBe(true);
+      if ((result.data as unknown[]).length > 0) populated += 1;
+    }
+    expect(populated).toBeGreaterThan(0);
+  });
+
+  it("standard_list: a declared category with NO standards is a calm empty list", async () => {
+    // The case that separates "the graph is the vocabulary" from "the returned
+    // rows are the vocabulary". `standard_categories` publishes every declared
+    // slug with its count, zeros included, and tells the agent to pick one —
+    // so rejecting a zero-count slug as INVALID_INPUT tells it the slug the
+    // tool just handed it was a typo. Validity read off the rows did exactly
+    // that, because a category with no standards appears in no row.
+    const categories = await mcp.callTool("standard_categories");
+    const zero = (categories.data as { name: string; count: string }[]).filter(
+      (row) => Number(row.count) === 0,
+    );
+    expect(zero.length).toBeGreaterThan(0);
+    for (const row of zero) {
+      const result = await mcp.callTool("standard_list", {
+        category: row.name,
+      });
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
+      // And it is a real empty answer, so it carries the calm notice rather
+      // than passing in silence.
+      expect((result.meta as { notice?: string }).notice ?? "").not.toBe("");
+    }
+  });
+
+  it("standard_list: the rejection names the declared slugs, not just the used ones", async () => {
+    const result = await mcp.callTool("standard_list", {
+      category: "zzz-definitely-not-a-slug",
+    });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string; validOptions: string[] };
+    expect(error.code).toBe("INVALID_INPUT");
+    const categories = await mcp.callTool("standard_categories");
+    const declared = (categories.data as { name: string }[]).map((r) => r.name);
+    // Same vocabulary, both surfaces: whatever `standard_categories` lists is
+    // what `--category` accepts. Read from `cs:Category`/`cs:slug` on both
+    // sides, so the two cannot drift.
+    expect([...error.validOptions].sort()).toEqual([...declared].sort());
+  });
+});
+
+describe("empty ≠ silence on the machine surfaces", () => {
+  it("carries the list's empty-state guidance in the envelope meta", async () => {
+    // `notice` had exactly one consumer — the CLI dispatcher's stderr — so
+    // an agent received `{"ok":true,"data":[],"meta":{}}` and nothing else. The
+    // search path is the honest way to reach an empty list without a bad
+    // argument.
+    const result = await mcp.callTool("standard_list", {
+      search: "zzz-nothing-matches-this",
+    });
     expect(result.ok).toBe(true);
     expect(result.data).toEqual([]);
-    expect(result.meta).toEqual({});
+    const notice = (result.meta as { notice?: string }).notice ?? "";
+    expect(notice).toContain("No standard entries found.");
+    expect(notice).toContain("pragma standard categories");
   });
 });
 

package/src/testing/behavioral/journeys.firstInstall.test.ts

@@ -158,10 +158,15 @@ describe("first install — the surfaces say where the answers come from", () =>
     expect(status.entityCount).toBeGreaterThan(0);
   });
 
-  it("doctor passes, naming the embedded snapshot rather than the config", async () => {
+  it("doctor passes, saying the packs came with the CLI rather than from the config", async () => {
     const result = await checkPackageRefs(bootRuntime(JSON_FLAGS, emptyCwd()));
     expect(result.status).toBe("pass");
-    expect(result.detail).toContain("embedded snapshot @ ");
+    // What is pinned is the DISTINCTION — a fresh install reads packs it
+    // shipped with, not packs this project configured — and that the row says
+    // how to change that. The wording is the reader's ("shipped with the CLI"),
+    // not the build's ("embedded snapshot"); the per-pack revisions moved to
+    // the row's sub-items when each pack got its own line.
+    expect(result.detail).toContain("shipped with the CLI");
     expect(result.detail).toContain("pragma sources update");
   });
 });

package/src/testing/behavioral/journeys.packageStories.test.ts

@@ -138,12 +138,15 @@ describe("the two recoveries still run with bad stories in the pack", () => {
     // The pack DOES answer reads, so the check passes…
     expect(check?.status).toBe("pass");
     expect(check?.detail).toContain("2 stories ignored");
-    // …with the unusable stories named underneath it.
-    expect(check?.items?.map((item) => item.label).sort()).toEqual([
+    // …with the unusable stories named underneath it. The items also carry
+    // one PASSING row per pack the answer was built from, so this pins the
+    // FAILING ones: what a story problem contributes is a failing item, and
+    // that claim must not break every time provenance gains a row.
+    const failing = (check?.items ?? []).filter((i) => i.status === "fail");
+    expect(failing.map((item) => item.label).sort()).toEqual([
       "fixture/stories/broken.json",
       "fixture/stories/invalid.json",
     ]);
-    for (const item of check?.items ?? []) expect(item.status).toBe("fail");
   });
 });
 

package/src/testing/eval/__snapshots__/eval.test.ts.snap

@@ -63,7 +63,12 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "content-standard-list-length-equals-category-count-sum",
+    "id": "content-standard-category-counts-match-filtered-list",
+    "kind": "content",
+    "passed": true,
+  },
+  {
+    "id": "content-standard-category-rollup-keeps-the-direct-member",
     "kind": "content",
     "passed": true,
   },
@@ -172,6 +177,21 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-standard-list-empty-category-is-a-calm-empty-list",
+    "kind": "tool",
+    "passed": true,
+  },
+  {
+    "id": "tool-standard-list-names-are-addressable-by-lookup",
+    "kind": "tool",
+    "passed": true,
+  },
+  {
+    "id": "tool-standard-lookup-advertised-glob-matches",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-standard-lookup-has-dos-and-donts",
     "kind": "tool",
@@ -182,6 +202,11 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-token-lookup-addresses-only-what-list-publishes",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-token-noun-is-read-only",
     "kind": "tool",