@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/vocabulary.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+import { dataNq } from "./runtime/graphpack/embedded/pack.generated.js";
+import { embeddedManifest } from "./runtime/graphpack/embedded.js";
+import type { DeclaredVocabulary } from "./vocabulary.js";
+import { parseVocabulary, VOCABULARY } from "./vocabulary.js";
+
+/** A valid declaration, cloned per case so one field can be made hostile. */
+const createValidDeclaration = (): DeclaredVocabulary => ({
+  altName: "ex:name",
+  prompt: {
+    type: "ex:Prompt",
+    body: "ex:body",
+    argument: "ex:argument",
+    argName: "ex:argName",
+    argRequired: "ex:argRequired",
+  },
+});
+
+/** The bindings `createValidDeclaration`'s terms resolve against. */
+const BOUND = { ex: "https://ex.test/" };
+
+describe("parseVocabulary", () => {
+  it("returns the same declaration when every term is readable", () => {
+    const declaration = createValidDeclaration();
+    expect(parseVocabulary(declaration, BOUND, "x.conf.ts")).toBe(declaration);
+  });
+
+  it("rejects an absolute IRI, naming the field and the file", () => {
+    // The defect this validator exists for. An absolute IRI written bare is a
+    // SPARQL parse error; caught at the read site it becomes "this graph has no
+    // prompts", indistinguishable from an empty graph. Here it is a startup
+    // CONFIG_ERROR that says which term is wrong and where.
+    let caught: unknown;
+    try {
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "https://ex.test/name" },
+        BOUND,
+        "x.conf.ts",
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const { message } = caught as { message: string };
+    expect(message).toContain("altName");
+    expect(message).toContain("x.conf.ts");
+    expect(message).toContain("https://ex.test/name");
+  });
+
+  it("rejects a term whose prefix nothing binds, naming that prefix", () => {
+    // The likelier malformation, and the one the shape check alone lets past.
+    // A one-character typo passes `prefix:local` and then makes every read of
+    // that term fail — the index silently loses `altNames`, and the prompt
+    // SELECT fails in a way a caller cannot tell from an empty graph. So the
+    // binding is checked here, where the file that declares both is one place.
+    let caught: unknown;
+    try {
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "exx:name" },
+        BOUND,
+        "x.conf.ts",
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const { message, recovery } = caught as {
+      message: string;
+      recovery?: { message: string };
+    };
+    expect(message).toContain("altName");
+    expect(message).toContain("exx:");
+    expect(recovery?.message).toContain("exx");
+  });
+
+  it("rejects a nested prompt term whose prefix nothing binds", () => {
+    const declaration = createValidDeclaration();
+    expect(() =>
+      parseVocabulary(
+        {
+          ...declaration,
+          prompt: { ...declaration.prompt, type: "other:Prompt" },
+        },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/prompt\.type/);
+  });
+
+  it("rejects a term naming an inherited Object property as its prefix", () => {
+    // `prefixes` is a plain record, so an unbound prefix must be UNBOUND, not
+    // whatever the prototype chain answers. Without an own-key check
+    // `constructor:name` passes and expands to a stringified function.
+    expect(() =>
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "constructor:name" },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/constructor:/);
+  });
+
+  it("rejects a nested prompt term, naming its path", () => {
+    const declaration = createValidDeclaration();
+    expect(() =>
+      parseVocabulary(
+        {
+          ...declaration,
+          prompt: { ...declaration.prompt, body: "<ex:body>" },
+        },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/prompt\.body/);
+  });
+
+  it("rejects an empty, unprefixed, whitespace-bearing or malformed term", () => {
+    for (const term of ["", "name", "ex:", ":name", "ex: name", "ex:na me"]) {
+      expect(() =>
+        parseVocabulary(
+          { ...createValidDeclaration(), altName: term },
+          BOUND,
+          "x.conf.ts",
+        ),
+      ).toThrow(/altName/);
+    }
+  });
+});
+
+describe("the shipped declaration", () => {
+  it("declares the name property entities are addressed by", () => {
+    expect(VOCABULARY.altName).toBe("ds:name");
+  });
+
+  it("names a property the shipped pack actually carries", () => {
+    // The declaration and the committed pack are produced independently, and
+    // NOTHING makes the pack follow the declaration: `contentHash` covers pack
+    // sources only, and `buildPack` reuses any complete cache directory, so
+    // editing `altName` here re-mints no index and `sources update` cannot
+    // repair the mismatch. Left silent, the CLI would offer the old property's
+    // tokens from the index and match the new one in every lookup.
+    //
+    // So expand the declared term through the pack's OWN manifest and look for
+    // it as a predicate in the pack's data. The prompt terms get no such check
+    // — they are a read contract, and this graph carries no prompt entities.
+    const [prefix, local] = VOCABULARY.altName.split(":");
+    const namespace = embeddedManifest().prefixes[prefix ?? ""];
+    expect(namespace, `pack binding for \`${prefix}:\``).toBeDefined();
+    expect(
+      dataNq.includes(` <${namespace}${local}> `),
+      `\`${VOCABULARY.altName}\` used as a predicate in the shipped pack`,
+    ).toBe(true);
+  });
+
+  it("declares the prompt entity shape, value for value", () => {
+    expect(VOCABULARY.prompt).toEqual({
+      type: "ds:Prompt",
+      body: "ds:promptBody",
+      argument: "ds:promptArgument",
+      argName: "ds:argName",
+      argRequired: "ds:argRequired",
+    });
+  });
+});

package/src/kernel/vocabulary.ts

@@ -0,0 +1,146 @@
+/**
+ * The domain vocabulary this distribution declares, validated once at load.
+ *
+ * The kernel reads a graph whose vocabulary it must not name. Two of its reads
+ * need domain terms: the pack index projects an alternative-name property into
+ * `altNames` (what a family is addressed by, hence what completes and what a
+ * lookup resolves), and the MCP prompt surface materializes prompt entities
+ * with a generated SELECT. Both take their terms from here, and the bundled
+ * capability packs that query the same terms read the same declaration — so
+ * complete and resolve cannot drift apart.
+ *
+ * A DISTRIBUTION DECLARATION, not a config layer field, and deliberately so.
+ * Both readers sit where the config layer is unreachable: the storeless
+ * `__complete` fast path builds a completion ref at module load, and the index
+ * is built inside the pack builder. Made layerable, a user setting it in their
+ * project config would change nothing anywhere — silence, which is the exact
+ * failure a dead config field is. A fork ships its own binary: it edits the
+ * declaration and rebuilds.
+ *
+ * Terms must be PREFIXED NAMES whose prefix the distribution BINDS, and
+ * {@link parseVocabulary} rejects anything else by name. They are interpolated
+ * into SPARQL, where an absolute IRI written bare is a parse error and an
+ * unbound prefix is either a parse error or a silently empty result — and a
+ * failed read is indistinguishable from an empty graph, which is how a
+ * malformed declaration would otherwise surface as "this distribution has no
+ * prompts". Both halves matter: rejecting the shape alone still lets a
+ * one-character typo (`ds:name` → `dss:name`) pass startup and then drop every
+ * `altNames` from the index while reporting a built store as unbuilt. Failing
+ * at module load is correct for a compiled-in build defect: the distribution
+ * config's own layer validation (`config/defaults.ts`) already throws the same
+ * way.
+ *
+ * Standard vocabulary (`rdfs:label`, `rdfs:comment`) is deliberately absent —
+ * it is the same in every graph, and the index already treats it as universal.
+ */
+
+import conf, { vocabulary } from "../../pragma.conf.js";
+import { PragmaError } from "./error/PragmaError.js";
+
+/** The domain terms the kernel reads a distribution's graph with. */
+export interface DeclaredVocabulary {
+  /**
+   * The property an entity family is addressed by, beside `rdfs:label` — the
+   * tokens the index offers as candidates and a bespoke lookup matches on.
+   */
+  readonly altName: string;
+  /** The prompt entity shape the MCP prompt surface reads. */
+  readonly prompt: {
+    /** The class every prompt entity carries. */
+    readonly type: string;
+    /** The template body, with `{{arg}}` placeholders. */
+    readonly body: string;
+    /** Links a prompt to one of its declared arguments. */
+    readonly argument: string;
+    /** An argument's name. */
+    readonly argName: string;
+    /** Whether an argument is required. */
+    readonly argRequired: string;
+  };
+}
+
+/** A prefixed name — `prefix:local`, the only form a generated query can read. */
+const PREFIXED_NAME = /^[A-Za-z][A-Za-z0-9_-]*:[A-Za-z_][A-Za-z0-9_.-]*$/;
+
+/**
+ * The distribution config file, quoted in the diagnostics.
+ *
+ * The literal, not `${BIN_NAME}.conf.ts`: the import above names this file, and
+ * so do four other modules, so a fork CANNOT rename it — deriving the name from
+ * the fork's would send its maintainer to a path that is not on disk.
+ * `config/defaults.ts` names the same file for the same reason.
+ */
+const CONF_FILE = "pragma.conf.ts";
+
+/**
+ * Hold one declared term to a form a generated query can actually read: the
+ * `prefix:local` shape, AND a prefix the distribution binds.
+ *
+ * @param field - The term's path in the declaration, for the message.
+ * @param term - The declared value.
+ * @param prefixes - The distribution's declared namespace bindings.
+ * @param source - The file the declaration was read from.
+ * @throws PragmaError CONFIG_ERROR when the term is not `prefix:local`, or
+ *   names a prefix `prefixes` does not bind.
+ */
+function assertReadableTerm(
+  field: string,
+  term: string,
+  prefixes: Readonly<Record<string, string>>,
+  source: string,
+): void {
+  const reject = (problem: string, fix: string): never => {
+    throw PragmaError.configError(
+      `Invalid vocabulary in ${source}: \`${field}\` ${problem}, not ${JSON.stringify(term)}.`,
+      { recovery: { message: `In ${source}, ${fix}` } },
+    );
+  };
+  if (!PREFIXED_NAME.test(term)) {
+    reject(
+      "must be a prefixed name like `ex:thing`",
+      `write \`${field}\` as \`<prefix>:<local>\`. These terms are interpolated into queries, which cannot read an absolute IRI here.`,
+    );
+  }
+  const prefix = term.slice(0, term.indexOf(":"));
+  if (!Object.hasOwn(prefixes, prefix)) {
+    reject(
+      `must use a prefix \`prefixes\` binds, and nothing binds \`${prefix}:\``,
+      `either bind \`${prefix}\` under \`prefixes\` or write \`${field}\` with a prefix that is bound. An unbound prefix makes the generated query fail, which a read cannot tell apart from an empty graph.`,
+    );
+  }
+}
+
+/**
+ * Validate a declared vocabulary.
+ *
+ * @param raw - A distribution's `vocabulary` export.
+ * @param prefixes - That distribution's `prefixes`, which must bind every
+ *   prefix the terms use.
+ * @param source - The file it was declared in, quoted in errors.
+ * @returns The same declaration, once every term is readable.
+ * @throws PragmaError CONFIG_ERROR naming the offending field and its value.
+ */
+export function parseVocabulary(
+  raw: DeclaredVocabulary,
+  prefixes: Readonly<Record<string, string>>,
+  source: string,
+): DeclaredVocabulary {
+  assertReadableTerm("altName", raw.altName, prefixes, source);
+  for (const [term, value] of Object.entries(raw.prompt)) {
+    assertReadableTerm(`prompt.${term}`, value, prefixes, source);
+  }
+  return raw;
+}
+
+/**
+ * This distribution's validated vocabulary.
+ *
+ * The declaration is type-checked at this call — a fork that drops or mistypes
+ * a term fails `tsc`, and one that writes an unreadable term fails here at
+ * startup rather than at the read that would have swallowed it.
+ */
+export const VOCABULARY = parseVocabulary(
+  vocabulary,
+  conf.prefixes ?? {},
+  CONF_FILE,
+);

package/src/testing/PARITY_GAPS.ts

@@ -78,13 +78,19 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "generic-renderers-not-bespoke-templates",
     area: "render",
     description:
-      "Every noun's plain/llm output — including the one hand-written verb, `block list` — renders through the SAME generic list/lookup renderer (`kernel/render/renderers.ts`), driven by declarative column/field/section metadata. There are no per-noun hand-authored render templates left to keep in parity.",
+      "Every noun's plain/llm output renders through the SAME generic list/lookup renderer (`kernel/render/renderers.ts`), driven by declarative column/field/section metadata. There are no per-noun hand-authored render templates left to keep in parity (the last hand-written verb, `block list`, became declared content in L-OPEN-9).",
   },
   {
     id: "block-lookup-not-tier-scoped",
     area: "block",
     description:
-      "`block lookup` resolves by `ds:name` GLOBALLY, with no tier or channel filtering — only the hand-written `block list` is tier/channel-aware (PR3 Risk5, `capabilities/block/tierChain.ts`). A same-named block declared at two tiers cannot be disambiguated by `block lookup` alone (the old shell's tier-scoped lookup disambiguation has no v2 equivalent).",
+      "`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`.",
+  },
+  {
+    id: "block-list-unfiltered",
+    area: "block",
+    description:
+      "L-OPEN-9 (owner-signed): `block list` is the block story's compiled, UNFILTERED list — it shows every block, including experimental/alpha ones, for everyone, until filtering returns in declared form. The old tier-chain inheritance, channel visibility, and `--all-tiers` escape were hand-written filtering the pack grammar has no term for, and the ruling removed them rather than growing the grammar to keep them. `config.tier` consequently scopes nothing (reported by `config show`/`info` only); `config.channel` keeps only its npm dist-tag role for `upgrade`/`info`.",
   },
   {
     id: "graph-query-deferred",

package/src/testing/behavioral/README.md

@@ -40,7 +40,7 @@ the emitted set legitimately grows PR-by-PR.
 | `agentSession.mcp.test.ts` | A multi-step agent MCP session (list → pick → lookup) + the SPARQL escape hatch. |
 | `mcpSurface.test.ts` | Every MCP tool the live catalog exposes is callable and well-formed — the "surface ⊆ covenant, exercised" proof. |
 | `disclosure.test.ts` | The cross-noun disclosure sweep (mechanism itself is PR3's/kernel's protected unit test — this only sweeps the noun SET). |
-| `journeys.cli.test.ts` | The `block list` tier-chain/channel journey (the one hand-written verb). |
+| `journeys.cli.test.ts` | The `block list` journey — since L-OPEN-9 it pins that the declared list is UNFILTERED: four tier/channel configs, one answer. |
 | `completion.test.ts` | The THIN main-line `__complete` candidate contract (§6 — see "Completion" below). |
 
 Plus `testing/eval/` (the eval harness + seed cases) and `testing/PARITY_GAPS.ts`
@@ -71,7 +71,7 @@ import { CANONICAL_TTL, CANONICAL_CONFIG } from "../fixtures/graph/canonical.js"
 
 const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL, config: CANONICAL_CONFIG });
 try {
-  // fixture.cwd carries a REAL pragma.lock.json — bootRuntime(flags, fixture.cwd),
+  // fixture.cwd is pointed at a REAL built pack — bootRuntime(flags, fixture.cwd),
   // executeVerb(...), projectMcp(modules, fixture.cwd), and (if you must)
   // runCli(args, { cwd: fixture.cwd }) all resolve the SAME cached pack.
 } finally {
@@ -80,7 +80,7 @@ try {
 ```
 
 Use `packRuntime.ts#buildFixtureRuntime` (PR3's helper) instead when you only
-need ONE surface (a direct `verb.run()` call) — it's cheaper (no lock file).
+need ONE surface (a direct `verb.run()` call) — it's cheaper (no real build).
 Reach for `bootFixtureRuntime` specifically when you need CLI and MCP (or a
 spawn) to agree on the same store.
 

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

@@ -4,7 +4,7 @@
  * The full completion engine (`kernel/completion`: parse → resolve → rank, the
  * spec-derived model, the entity seam) owns the unit-level guarantees; this
  * pins the behaviour end-to-end against the LIVE capabilities and — for the
- * entity tier — against a REAL built pack index on disk (the locked-pack branch
+ * entity tier — against a REAL built pack index on disk (the built-pack branch
  * of the storeless reader, which the engine's own tests exercise only via the
  * embedded fallback). Parameterized over the live read surface so noun/verb
  * renames never churn it.
@@ -89,21 +89,34 @@ describe("flags are kebab-cased at emission (the live, testable guarantee)", ()
   });
 });
 
-describe("entity params resolve from a real built pack index (B10)", () => {
-  it("a lookup's entity positional completes from the built pack index", async () => {
+describe("entity params resolve from the project's built pack, not the embedded snapshot (B10)", () => {
+  it("a lookup's entity positional offers the built pack's subjects and none of the snapshot's", async () => {
     const fixture = await bootFixtureRuntime({
       ttl: CANONICAL_TTL,
       config: ALL_VISIBLE_CONFIG,
     });
     try {
-      // The locked-pack branch of the storeless reader: a real index.json on
+      // The built-pack branch of the storeless reader: a real index.json on
       // disk under the fixture cwd, read without booting the store.
       const all = await runComplete(
         ["block", "lookup", ""],
         capabilities,
         indexCompletionEnv(fixture.cwd),
       );
-      expect(all.length).toBeGreaterThan(0);
+      // The four `ds:Component` subjects the canonical fixture declares
+      // (`blockGraph.ts`'s Button/Modal plus `canonical.ts`'s LXD Panel and
+      // Beta Widget) — the fixture's own data, not a recomputation. Stating
+      // the SET is what makes the distribution's own snapshot names provably
+      // absent: a pointer read that regressed to the embedded fallback would
+      // complete another graph's names while every read answered correctly,
+      // and the old `narrowed.length < all.length` heuristic only noticed by
+      // the accident that no snapshot name contains `ds:b`.
+      expect([...all].sort()).toEqual([
+        "ds:betaWidget",
+        "ds:button",
+        "ds:lxdPanel",
+        "ds:modal",
+      ]);
 
       const narrowed = await runComplete(
         ["block", "lookup", "ds:b"],
@@ -111,7 +124,7 @@ describe("entity params resolve from a real built pack index (B10)", () => {
         indexCompletionEnv(fixture.cwd),
       );
       // Every ranked candidate carries the partial (case-insensitive), and the
-      // filter is strictly narrowing — the index tier really ran.
+      // filter is strictly narrowing — the ranker really ran over this index.
       expect(
         narrowed.every((name) => name.toLowerCase().includes("ds:b")),
       ).toBe(true);

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,19 @@ const READ_CASES: readonly ReadCase[] = [
     params: { name: ["Button"] },
   },
   { command: "pragma standard list", key: "standard list", params: {} },
+  {
+    command: "pragma standard list --category react",
+    key: "standard list",
+    params: { category: ["react"] },
+  },
+  {
+    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

@@ -32,9 +32,10 @@ import { listVerbs, lookupVerbs } from "./liveReadSurface.js";
 
 /**
  * List verbs with a STRING or ENUM (narrowable, non-boolean) flag — e.g.
- * `standard_list --category`. Excludes boolean escape hatches like `block
- * list --all-tiers`, which reject a string value at the schema layer rather
- * than narrowing to an empty result.
+ * `standard_list --category`. Boolean flags are excluded: they reject a string
+ * value at the schema layer rather than narrowing to an empty result. (`block
+ * list --all-tiers` used to be the example; it retired with the hand-written
+ * filtering in L-OPEN-9.)
  */
 const filteredListVerbs = listVerbs
   .map((v) => {
@@ -109,9 +110,9 @@ describe("list — a narrowing filter to zero rows is a plain empty list (B3, ad
   });
 });
 
-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/errorMatrix.storeless.test.ts

@@ -61,7 +61,7 @@ const MATRIX: readonly {
   },
   {
     label: "recovery (mcp-only, no cli)",
-    error: PragmaError.storeUnavailable("no lock", {
+    error: PragmaError.storeUnavailable("the store has not been built", {
       recovery: { message: "Please report this issue." },
     }),
   },

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

@@ -37,14 +37,15 @@ describe("exit-code covenant, spawn-observed (A4, e2e)", () => {
     expect(result.stderr).toContain('Invalid format "yaml"');
   });
 
-  it("3 — store unavailable (configured packages, never built)", () => {
+  it("3 — store unavailable (configured packs, never built)", () => {
     const cwd = mkdtempSync(join(tmpdir(), "pragma-exit3-"));
-    // A pragma.config.ts with custom `packages` flips `origins.packages` to
-    // "project" — with no `pragma.lock.json`, resolveSources refuses to boot
-    // (no network probing) rather than fall back to the embedded pack.
+    // A pragma.config.ts with custom `packs` flips `origins.packs` to
+    // "project" — with nothing built for this project, resolveSources refuses
+    // to boot (no network probing) rather than serve the embedded pack, which
+    // is a DIFFERENT graph from the one this project asked for.
     writeFileSync(
       join(cwd, "pragma.config.ts"),
-      'export default { packages: [{ name: "never-built", source: "file:///nonexistent" }] };\n',
+      'export default { packs: [{ name: "never-built", source: "file:///nonexistent" }] };\n',
     );
     const result = runCli(["block", "list"], { cwd });
     expect(result.exitCode).toBe(3);

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/harness.foundation.test.ts

@@ -2,8 +2,8 @@
  * Harness-foundation smoke tests (commit 1).
  *
  * Validates the framework pieces PR4 adds — NOT per-noun behavior (that's
- * commits 2/4's job). Proves: (1) `bootFixtureRuntime` boots a real,
- * lock-backed store that BOTH the CLI and MCP surfaces resolve identically
+ * commits 2/4's job). Proves: (1) `bootFixtureRuntime` boots a real, built-pack
+ * store that BOTH the CLI and MCP surfaces resolve identically
  * (via the shared canonical graph, one real lookup); (2) the compiler/runtime
  * is ontology-agnostic — a pack over the foreign `ex:` recipe namespace
  * registers its 2 tools and resolves on both surfaces; (3) `runCli` can spawn
@@ -12,7 +12,7 @@
 
 import { homedir, tmpdir } from "node:os";
 import { describe, expect, it } from "vitest";
-import { blockModule } from "../../capabilities/block/index.js";
+import { storyModules } from "../../capabilities/distribution.js";
 import { VERSION } from "../../constants.js";
 import { compilePack } from "../../kernel/packs/compile.js";
 import { verbKey } from "../../kernel/packs/uniqueness.js";
@@ -31,8 +31,13 @@ import { plain } from "../helpers/golden.js";
 import { assertCliMcpParity } from "../helpers/parity.js";
 import { runCli } from "../helpers/runCli.js";
 
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
 describe("bootFixtureRuntime — the shared canonical graph (commit-1 smoke)", () => {
-  it("boots a lock-backed store both CLI and MCP resolve identically", async () => {
+  it("boots a built-pack store both CLI and MCP resolve identically", async () => {
     const fixture = await bootFixtureRuntime({
       ttl: CANONICAL_TTL,
       config: CANONICAL_CONFIG,
@@ -68,7 +73,11 @@ describe("foreign-namespace generic-pack proof (compiler is DS-agnostic)", () =>
     try {
       const recipeModule: CapabilityModule = {
         name: "recipe",
-        verbs: compilePack(recipePack, "test:recipe", RECIPE_PREFIXES),
+        verbs: compilePack(
+          recipePack,
+          { label: "test:recipe", origin: "package" },
+          RECIPE_PREFIXES,
+        ),
       };
       expect(recipeModule.verbs.map((v) => verbKey(v.path)).sort()).toEqual([
         "recipe list",