@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/spec/types.ts

@@ -11,7 +11,7 @@
  * other param is a kebab-cased flag.
  */
 
-import type { Task } from "@canonical/task";
+import type { Effect, Task } from "@canonical/task";
 import type { PragmaRuntime } from "../runtime/types.js";
 
 /** MCP tool annotations mirrored onto exposed verbs. */
@@ -111,6 +111,14 @@ export type ParamSpec =
       default?: unknown;
       positional?: boolean;
       complete?: ParamComplete;
+      /**
+       * A repeatable flag ACCUMULATES: `--category css --category git` is
+       * the union, never last-wins (repetition is the sanctioned multi-value
+       * form, and silently dropping all but the last value is data loss).
+       * CLI-side only: the MCP arg schema keeps its scalar shape, and the
+       * run body accepts one value or many.
+       */
+      repeatable?: true;
     }
   | {
       kind: "enum";
@@ -121,6 +129,8 @@ export type ParamSpec =
       default?: string;
       positional?: boolean;
       complete?: ParamComplete;
+      /** See the string variant — repeated occurrences accumulate. */
+      repeatable?: true;
     }
   | {
       kind: "string[]";
@@ -131,11 +141,57 @@ export type ParamSpec =
       complete?: ParamComplete;
     };
 
-/** The three output modes every verb must render. */
+/**
+ * The three output modes every verb must render.
+ *
+ * `plain` takes an optional {@link RenderContext} — the dispatcher's
+ * presentation facts (`--no-headers`, whether stdout is a terminal). Only
+ * list-shaped formatters read it; `llm` (the byte-frozen agent contract) and
+ * `json` (the envelope) never see 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: (d: T) => string;
+  readonly plain: (
+    d: T,
+    context?: import("../render/contracts.js").RenderContext,
+  ) => string;
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
+  readonly notice?: (d: T) => string | undefined;
 }
 
 /** A usage example shown in verb help. */
@@ -176,7 +232,38 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
   readonly summary: string;
   readonly doc?: string;
   readonly params: readonly ParamSpec[];
-  readonly output: { schema?: unknown; formatters: Formatters<R> };
+  readonly output: {
+    schema?: unknown;
+    formatters: Formatters<R>;
+    /**
+     * OPTIONAL dry-run seam. A `--dry-run` normally renders the raw effect
+     * dump — one `describeEffect` bullet per effect, absolute paths repeated
+     * per line, interpreter internals included — which is debug material, not a
+     * preview a user was meant to read. A verb that has stashed structured plan
+     * data on the runtime (`PragmaRuntime.planData`) can render that instead.
+     *
+     * ABSENT BY DEFAULT, and absent is exactly today's render: a verb that does
+     * not declare this is untouched. The honest preview still runs underneath
+     * either way, so a dry run still fails exactly when the run would.
+     *
+     * The previewed `effects` and the run's verbosity arrive BESIDE the stashed
+     * data, because a plan is not always known before the Task runs: `setup`
+     * computes its target table up front and renders that, while `create` has
+     * nothing to stash — its plan IS the effects the generator produced, which
+     * only exist once the preview interpreter has walked the Task. One seam
+     * serves both by handing the renderer everything the branch knows.
+     *
+     * MAY be async: a renderer whose formatting rules live in another package
+     * loads them behind a dynamic `import()` rather than putting them on the
+     * capabilities barrel's static graph, which every `--help` and
+     * `__complete` spawn pays for. The kernel awaits whatever it returns.
+     */
+    formatPlan?: (
+      planData: unknown,
+      effects: readonly Effect[],
+      verbose: boolean,
+    ) => string | Promise<string>;
+  };
   readonly examples?: readonly Example[];
   readonly disclosure?: DisclosureSpec;
   readonly capability: Capability;
@@ -185,6 +272,52 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
   readonly hidden?: boolean;
 }
 
+/**
+ * One slice of the index a module contributes to the MCP resource listing.
+ *
+ * Deliberately the vocabulary of {@link CompletionSourceRef} — a listing and a
+ * completion address the same index by the same three facts (which type, which
+ * box, what to yield), and a second vocabulary for that would be a second
+ * writing of one decision. The only source a listing can read is the index, so
+ * `from` is implied and absent.
+ */
+export interface McpListableRef {
+  /** Prefixed type filter (e.g. `ds:Component`) — empty = any type. */
+  readonly type?: string;
+  /** Restrict to schema (`tbox`) or individuals (`abox`); empty = both. */
+  readonly box?: "tbox" | "abox";
+  /**
+   * What the slice yields: `"collection"` lists ONE entry — the class entry
+   * for {@link type}, carrying its instance count — while `"entities"` lists
+   * every matching entity. Default `"entities"`.
+   */
+  readonly as?: "collection" | "entities";
+  /**
+   * Relative importance, 0–1 (default 1). Feeds MCP `annotations.priority` on
+   * the listed resource AND breaks ties in URI-completion ranking, so the two
+   * judgements about what matters most are ONE declaration rather than two
+   * constants in the kernel.
+   */
+  readonly weight?: number;
+}
+
+/**
+ * A module's declared contribution to the MCP resource listing.
+ *
+ * The listing is the UNION of every module's slices. It exists because
+ * `resources/list` has no working pagination in the SDK (the high-level
+ * `McpServer` list handler ignores `request.params.cursor` and never returns
+ * `nextCursor`), so the listing is curated rather than paged: every byte it
+ * spends on connect is context the agent cannot spend on the task.
+ *
+ * DERIVED wherever the module is compiled from a read story — a story already
+ * declares the type set it addresses (`PackLookup.type`/`types`), so its
+ * listing is read off that declaration, never authored a second time.
+ */
+export interface McpListable {
+  readonly sources: readonly McpListableRef[];
+}
+
 /**
  * An MCP resource provider — the ONE non-tool projection a module may add.
  *
@@ -192,11 +325,16 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
  * autocomplete are storeless over the pack index; a read is store-backed and
  * shares the CLI's entity reader). Resources are NOT tools, so they never enter
  * the emitted tool surface; the projector calls this per module that declares it.
+ *
+ * `register` receives the WHOLE effective module set, not just its own module:
+ * the listing a provider installs is the union of every module's
+ * {@link McpListable}, which no single module can see.
  */
 export interface McpResourceProvider {
   readonly register: (
     server: import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
     rt: PragmaRuntime,
+    modules: readonly CapabilityModule[],
   ) => void;
   /**
    * A static declaration of the resource template ids this provider installs
@@ -224,6 +362,132 @@ export interface McpPromptProvider {
   ) => Promise<void> | void;
 }
 
+/** A flag a mounted subcommand offers to completion (full `--token`). */
+export interface CompletionChildFlag {
+  /** The full flag token (`--no-with-styles`). */
+  readonly flag: string;
+  /** Whether the flag consumes a value. */
+  readonly takesValue: boolean;
+  /** Closed value set for the flag's value, when one exists. */
+  readonly values?: readonly string[];
+}
+
+/** A positional slot a mounted subcommand offers to completion. */
+export interface CompletionChildPositional {
+  /** The slot name (diagnostics only). */
+  readonly name: string;
+  /** Whether the positional is required. */
+  readonly required: boolean;
+  /** Closed value set (e.g. tree segments), when one exists. */
+  readonly values?: readonly string[];
+  /** True when the slot completes file paths natively. */
+  readonly files?: boolean;
+}
+
+/**
+ * The completion surface of one MOUNTED command node: its flags, its
+ * positional slots, and any deeper segment children — static data (it must
+ * pass the completion safety allowlist), never live module state.
+ */
+export interface CompletionChildSpec {
+  /** The command token at this node. */
+  readonly label: string;
+  /** Flags offered at this node. */
+  readonly flags: readonly CompletionChildFlag[];
+  /** Positional slots at this node, in order. */
+  readonly positionals: readonly CompletionChildPositional[];
+  /** Deeper segment children (each with its own flags/positionals/children). */
+  readonly children?: readonly CompletionChildSpec[];
+}
+
+/**
+ * The REGISTERED CLI spelling of one mounted verb — the single syntax seam
+ * every kernel emitter and gate consumes: the reference emitter (usage line
+ * + Args/Flags tables), `emitSurface` (the covenant's mounted-noun flag and
+ * positional tokens, L-CIS-2), and the `docExamples` gate's valid-token
+ * vocabulary. A mounted tree may register a different surface than the
+ * binding-level params suggest (tree segments as subcommands, a
+ * default-true boolean registered only as its `--no-` form), and all three
+ * surfaces must print what the CLI actually accepts — the module supplies
+ * it, the kernel renders it.
+ */
+export interface ReferenceCliSyntax {
+  /**
+   * The usage line after the bin name (e.g.
+   * `create application react [app-path] [options]`) — real tree segments,
+   * the registered positional token.
+   */
+  readonly usage: string;
+  /**
+   * The registered flag token per binding-level param name (e.g.
+   * `withStyles` → `--no-with-styles`). A param absent here renders with the
+   * default `--<kebab-name>` derivation.
+   */
+  readonly flagTokens: Readonly<Record<string, string>>;
+  /**
+   * The registered positional token per binding-level param name (e.g.
+   * `componentPath` → `[component-path]`) — the SAME token the usage line
+   * carries, so the Arguments table never contradicts its own synopsis. A
+   * param absent here renders with the default `<name>`/`[name]` derivation.
+   */
+  readonly positionalTokens?: Readonly<Record<string, string>>;
+}
+
+/** What the program hands a module mounting its own subtree. */
+export interface CliMountHost {
+  /** Global flags for this invocation (closed over by mounted actions). */
+  readonly globalFlags: import("../runtime/types.js").GlobalFlags;
+  /** The binary name (for messages the mounted tree prints). */
+  readonly programName: string;
+}
+
+/**
+ * A module-level CLI projection hook (precedented by `mcpResources`/
+ * `mcpPrompts`/`colophon` — module metadata, NOT a `VerbSpec` field, zero
+ * covenant impact): the module MOUNTS its noun's subtree onto the Commander
+ * parent itself, instead of the generic per-verb attachment. The module's
+ * verbs remain the binding-level grammar (surface, MCP, reference,
+ * completion labels); the mount owns everything beneath the noun.
+ */
+export interface CliProjection {
+  /**
+   * Load the mount's registration machinery, when it is deferred. The
+   * projection hook rides the capabilities barrel, which `--help` and
+   * `__complete` import on every spawn — so a mount whose registration needs
+   * heavy modules (a Commander adapter, shared decision logic) keeps them
+   * behind this async step instead of a static import, and only the one
+   * caller that actually builds the command tree (the bin, before
+   * `buildProgram`) awaits it. {@link mount} stays synchronous and throws
+   * when invoked unprepared, so a future caller cannot silently skip the
+   * step.
+   */
+  readonly prepare?: () => Promise<void>;
+  /** Populate this module's noun parent with its subcommands. */
+  readonly mount: (
+    parent: import("commander").Command,
+    host: CliMountHost,
+  ) => void;
+  /**
+   * The completion surface of the mounted tree, keyed by verb label —
+   * static data the completion model attaches as segment children.
+   */
+  readonly completionChildren: () => Readonly<
+    Record<string, CompletionChildSpec>
+  >;
+  /** Markdown inserted under the noun's heading in the generated reference. */
+  readonly referenceIntro?: string;
+  /**
+   * The registered CLI syntax for one of the noun's binding verbs — the
+   * MOUNTED spelling the reference must print (usage line with tree
+   * segments, flag tokens the CLI actually registers) instead of deriving
+   * tokens from binding-level param names the mounted tree may not register.
+   * Return `undefined` to keep the default rendering for that verb.
+   */
+  readonly referenceSyntax?: (
+    verbPath: VerbSpec["path"],
+  ) => ReferenceCliSyntax | undefined;
+}
+
 /** A capability module: a named bundle of verbs with optional boot/resources/prompts hooks. */
 export interface CapabilityModule {
   readonly name: string;
@@ -248,6 +512,15 @@ export interface CapabilityModule {
   readonly boot?: (rt: PragmaRuntime) => void;
   /** An optional MCP resource surface (NOT a VerbSpec field — a module hook). */
   readonly mcpResources?: McpResourceProvider;
+  /**
+   * The slices of the index this module contributes to the MCP resource
+   * listing (NOT a VerbSpec field — a module hook, like `mcpResources`). A
+   * story-compiled module gets it DERIVED from its lookup's declared types;
+   * only an authored module declares it by hand.
+   */
+  readonly mcpListable?: McpListable;
   /** An optional MCP prompt surface (NOT a VerbSpec field — a module hook). */
   readonly mcpPrompts?: McpPromptProvider;
+  /** An optional CLI mount for the module's noun (NOT a VerbSpec field). */
+  readonly cliProjection?: CliProjection;
 }

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

@@ -45,6 +45,8 @@ function readDoc(relPath: string): string {
 const HAND_WRITTEN_DOCS = [
   "../../../README.md",
   "../../../docs/getting-started.md",
+  "../../../docs/design-system.md",
+  "../../../docs/setup.md",
   "../../../docs/mcp-integration.md",
   "../../../docs/config-model.md",
   "../../../docs/architecture.md",
@@ -161,7 +163,21 @@ const READ_CASES: readonly ReadCase[] = [
     params: { name: ["Button"] },
   },
   { command: "pragma standard list", key: "standard list", params: {} },
+  {
+    // 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: ["testing"] },
+  },
+  {
+    command: "pragma standard categories",
+    key: "standard categories",
+    params: {},
+  },
+  { command: "pragma modifier list", key: "modifier list", params: {} },
   { command: "pragma token list", key: "token list", params: {} },
+  { command: "pragma prompt list", key: "prompt list", params: {} },
   { command: "pragma tier list", key: "tier list", params: {} },
   { command: "pragma ontology list", key: "ontology list", params: {} },
   { command: "pragma config show", key: "config show", params: {} },

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,22 +118,104 @@ 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");
   });
 });
 
-describe("ontology_show — an unknown prefix is INVALID_INPUT (B3)", () => {
+describe("ontology_lookup — an unknown prefix is INVALID_INPUT (B3)", () => {
   it("fails with the enumerated valid prefixes", async () => {
-    const result = await mcp.callTool("ontology_show", { prefix: "nope" });
+    const result = await mcp.callTool("ontology_lookup", { prefix: "nope" });
     expect(result.ok).toBe(false);
     const error = result.error as { code: string; validOptions: string[] };
     expect(error.code).toBe("INVALID_INPUT");

package/src/testing/behavioral/firstRun.e2e.test.ts

@@ -1,40 +1,40 @@
 /**
- * A1 — first-run onboarding, observed through the real compiled binary.
+ * First-run onboarding, observed through the real shipped entry.
  *
- * Unit mechanics (`ensureFirstRun`/`firstRunTask`) are PR1-protected
- * (`kernel/config/firstRun.test.ts`); this is the e2e pin: a fresh XDG config
- * home produces the greeting on STDERR (never stdout — command output must stay
- * uncorrupted), seeds `config.json`, and a second run is silent.
+ * The contract inverted: onboarding no longer WRITES. A read-only command must
+ * leave the config home empty, and the un-set-up hint belongs on the read-only
+ * front door — where the machine's state is discovered by looking, not by
+ * seeding a file and a marker ahead of any consent.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { freshXdgEnv, runCli } from "../helpers/runCli.js";
 
-describe("first-run onboarding (A1, e2e)", () => {
-  it("greets on stderr, seeds config.json, and stays silent on the second run", () => {
+describe("first-run onboarding (e2e)", () => {
+  it("hints on the front door and seeds nothing", () => {
     const env = freshXdgEnv();
     const configPath = join(env.XDG_CONFIG_HOME, "pragma", "config.json");
 
-    const first = runCli(["info"], {
+    // A read-only command writes NO config and carries no banner: the greeting
+    // used to interleave itself into the output of unrelated runs.
+    const read = runCli(["info"], {
       env: { ...env, PRAGMA_NO_AUTO_LLM: "1" },
     });
-    expect(first.exitCode).toBe(0);
-    expect(first.stderr).toContain("Hello!");
-    expect(first.stderr).toContain("pre-release");
-    expect(first.stderr).toContain(configPath);
-    // Command output stays on stdout, untouched by the greeting.
-    expect(first.stdout).not.toContain("Hello!");
-    expect(first.stdout).toContain("pragma v");
+    expect(read.exitCode).toBe(0);
+    expect(read.stdout).toContain("pragma v");
+    expect(read.stderr).not.toContain("pre-release");
+    expect(existsSync(configPath)).toBe(false);
 
-    expect(existsSync(configPath)).toBe(true);
-    expect(readFileSync(configPath, "utf-8")).toBe("{}\n");
-
-    const second = runCli(["info"], {
-      env: { ...env, PRAGMA_NO_AUTO_LLM: "1" },
-    });
-    expect(second.exitCode).toBe(0);
-    expect(second.stderr).toBe("");
+    // The front door is a read, so it is where the hint belongs — on stderr,
+    // leaving the front door's own output uncorrupted on stdout.
+    const door = runCli([], { env: { ...env, PRAGMA_NO_AUTO_LLM: "1" } });
+    expect(door.exitCode).toBe(0);
+    expect(door.stderr).toContain("pre-release");
+    expect(door.stderr).toContain("pragma setup");
+    expect(door.stdout).not.toContain("pre-release");
+    // Still nothing written: the hint is a probe, not a seed.
+    expect(existsSync(configPath)).toBe(false);
   });
 });

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

@@ -4,7 +4,7 @@
  * BACKING ADAPTATION: the plan lists this as "fixture + spawn"; the PR4 quality
  * bar (R7 — keep the spawn-e2e layer to exactly A1-A4/A7) overrides that, so
  * this drives `block list` through the REAL CLI dispatch path (`executeVerb`,
- * the same function the compiled binary's `dispatch()` calls) IN-PROCESS
+ * the same function the shipped entry's `dispatch()` calls) IN-PROCESS
  * against the fixture, rather than spawning. It still exercises the true CLI
  * seam (typed params -> dispatch -> render), just without forking a process.
  *