@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/block.shipped.exec.test.ts

@@ -0,0 +1,282 @@
+/**
+ * The `block` story's declared vocabulary, EXECUTED against the shipped pack
+ * (PROTECTED).
+ *
+ * `block.parity.test.ts` asserts the story's semantics over a FIXTURE graph the
+ * repository writes. That is a real check, but it can only ever prove the story
+ * agrees with the fixture — and when the two drifted apart, that is exactly
+ * what happened: the story read `ds:whenToUse`/`ds:whenNotToUse`, the fixture
+ * obligingly declared them, the suite stayed green, and every real install
+ * rendered `block lookup` with no usage narrative at all, because the ontology
+ * had long since retired both terms in favour of a single `ds:usage`. Nothing
+ * in the pipeline treats that as an error: the GraphQL projection omits a name
+ * it cannot express the way OPTIONAL omits an unbound variable, and the
+ * renderer skips a section with no value. Silence all the way down.
+ *
+ * So this file boots the SHIPPED graph and asserts what a fixture structurally
+ * cannot. It distinguishes two failures that look identical in the output but
+ * are not the same defect:
+ *
+ * - a declared property the ontology does not define is a STORY bug — the CLI
+ *   is asking for a name the schema can never answer, and no upstream content
+ *   edit can ever make it render. That is this defect, and it is forbidden here.
+ * - a declared property the ontology defines but no instance asserts yet is a
+ *   CONTENT gap upstream (`ds:figmaLink` is one today). The story is correct and
+ *   degrades gracefully; that is not this suite's business.
+ *
+ * The `graph/examples.exec.test.ts` precedent: an example is a promise to a
+ * stranger, and only running it against what actually ships reads it as one. A
+ * declared property is the same kind of promise.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  isNestedExpand,
+  type PackExpandSelect,
+} from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
+import { declaredStories, storyModules } from "./distribution.js";
+
+const story = declaredStories.get("block");
+if (!story?.lookup) {
+  throw new Error('pragma.conf.ts declares no "block" lookup');
+}
+const blockLookup = story.lookup;
+
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
+const lookupVerb = blockModule.verbs.find(
+  (v) => verbKey(v.path) === "block lookup",
+) as VerbSpec;
+
+/**
+ * The block classes the lookup addresses, read from the story rather than
+ * retyped — a class added there widens these checks with it.
+ */
+const TYPE_VALUES = (blockLookup.types ?? []).join(" ");
+
+/** One graph term the story names, paired with the site that declares it. */
+interface DeclaredTerm {
+  readonly what: string;
+  readonly property: string;
+}
+
+/**
+ * Every term an `expand.select` names, to whatever depth it nests.
+ *
+ * WALKED, not listed. A hand-maintained enumeration would carry this file's own
+ * defect one level down: `ds:hasModifier`, `ds:propertyType` and `ds:optional`
+ * could be retired exactly the way `ds:whenToUse` was, and `block lookup` would
+ * quietly lose its modifier values and its property table while a list nobody
+ * thought to update stayed green. Recursing over the declaration instead means
+ * a term added to any `select` is covered the moment it is declared, by the
+ * author who declares it and without their help.
+ */
+function selectedTerms(
+  site: string,
+  select: readonly PackExpandSelect[],
+): readonly DeclaredTerm[] {
+  return select.flatMap((entry) =>
+    isNestedExpand(entry)
+      ? [
+          {
+            what: `${site} → nested expand "${entry.name}"`,
+            property: entry.relation,
+          },
+          ...selectedTerms(`${site} → "${entry.name}"`, entry.select),
+        ]
+      : [
+          {
+            what: `${site} → field "${entry.name}"`,
+            property: entry.property,
+          },
+        ],
+  );
+}
+
+/**
+ * Every property the story names in the graph, read from the declaration.
+ *
+ * The identity property, fields, sections, expand relations and everything
+ * selected beneath them all name graph vocabulary and all fail the same silent
+ * way, so all of them are held to the same standard. `by` is included because a
+ * lookup whose identity property the ontology has retired resolves NOTHING —
+ * the loudest form of the same defect, and the one no rendering test would
+ * reach, since there would be no entity to render.
+ *
+ * One case per declaration SITE rather than per distinct term: `ds:name` is
+ * named at six of them, and a failure that names the site it was declared at
+ * is the one a reader can act on.
+ */
+const DECLARED_PROPERTIES: readonly DeclaredTerm[] = [
+  { what: "lookup `by`", property: blockLookup.by },
+  ...(blockLookup.fields ?? []).map((f) => ({
+    what: `field "${f.name}"`,
+    property: f.property,
+  })),
+  ...(blockLookup.sections ?? []).map((s) => ({
+    what: `section "${s.name}"`,
+    property: s.property,
+  })),
+  ...(blockLookup.expand ?? []).flatMap((e) => [
+    { what: `expand "${e.name}"`, property: e.relation },
+    ...selectedTerms(`expand "${e.name}"`, e.select),
+  ]),
+];
+
+/** The IRI of the block whose usage narrative is asserted on below. */
+const BUTTON = "https://ds.canonical.com/global.component.button";
+
+// ONE store for the file — booting the shipped pack is the expensive part, and
+// this package already contends under parallel runs.
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  rt = bootRuntime(TEST_FLAGS);
+  // Load the shipped store HERE, once. `it.each` splits the vocabulary check
+  // into one small case per declared property, and whichever ran first would
+  // otherwise pay the whole lazy-load cost and time out under contention.
+  await rt.store.get();
+}, 60_000);
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/** One scalar from the shipped graph, queried directly. */
+async function scalar(query: string): Promise<string | undefined> {
+  const result = await rt.query.sparql(query);
+  if (result.type !== "select") return undefined;
+  const row = result.bindings[0];
+  return row === undefined ? undefined : Object.values(row)[0];
+}
+
+/** The `llm` rendering of `block lookup <value>`. */
+async function renderLookup(value: string): Promise<string> {
+  const out = (await lookupVerb.run({ name: [value] }, rt)) as never;
+  return lookupVerb.output.formatters.llm(out);
+}
+
+describe("the `block` story declares vocabulary the shipped ontology defines (PROTECTED)", () => {
+  it("declares at least one property to check", () => {
+    expect(DECLARED_PROPERTIES.length).toBeGreaterThan(0);
+  });
+
+  it.each(
+    DECLARED_PROPERTIES,
+  )("$what reads $property, which the shipped ontology defines", async ({
+    what,
+    property,
+  }) => {
+    const result = await rt.query.sparql(
+      [
+        "ASK {",
+        `  ${property} a ?kind .`,
+        "  VALUES ?kind { owl:DatatypeProperty owl:ObjectProperty }",
+        "}",
+      ].join("\n"),
+    );
+    expect(result.type).toBe("ask");
+    expect(
+      result.type === "ask" ? result.result : false,
+      `${what} reads ${property}, which the shipped ontology does not define — it can never render, for any block, on any install`,
+    ).toBe(true);
+  });
+});
+
+describe("the shipped graph carries the usage narrative on every block (PROTECTED)", () => {
+  it("asserts ds:usage on every block, and neither retired term on any", async () => {
+    const blocks = await scalar(
+      [
+        "SELECT (COUNT(DISTINCT ?b) AS ?n) WHERE {",
+        `  VALUES ?class { ${TYPE_VALUES} }`,
+        "  ?b a ?class .",
+        "}",
+      ].join("\n"),
+    );
+    const withUsage = await scalar(
+      [
+        "SELECT (COUNT(DISTINCT ?b) AS ?n) WHERE {",
+        `  VALUES ?class { ${TYPE_VALUES} }`,
+        "  ?b a ?class ; ds:usage ?u .",
+        "}",
+      ].join("\n"),
+    );
+    expect(Number(blocks)).toBeGreaterThan(0);
+    expect(withUsage).toBe(blocks);
+
+    // The retirement itself, pinned: reading these again would reintroduce the
+    // defect, silently, exactly as before.
+    for (const retired of ["ds:whenToUse", "ds:whenNotToUse"]) {
+      const result = await rt.query.sparql(`ASK { ?s ${retired} ?o }`);
+      expect(
+        result.type === "ask" ? result.result : true,
+        `${retired} is asserted somewhere in the shipped graph`,
+      ).toBe(false);
+    }
+  });
+});
+
+describe("block lookup renders the usage narrative from the shipped graph (PROTECTED)", () => {
+  it("renders a Usage section carrying the graph's own literal", async () => {
+    const usage = await scalar(`SELECT ?u WHERE { <${BUTTON}> ds:usage ?u }`);
+    expect(usage?.trim().length ?? 0).toBeGreaterThan(0);
+
+    const llm = await renderLookup(BUTTON);
+    expect(llm).toContain("### Usage");
+    // The narrative itself, not just its heading: the first prose line of the
+    // literal is read FROM the graph rather than retyped here, so editing the
+    // content upstream cannot leave this asserting yesterday's copy.
+    const firstProseLine = (usage ?? "")
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line.length > 0 && !line.startsWith("#")) as string;
+    expect(llm).toContain(firstProseLine);
+  });
+
+  it("nests the literal's own headings UNDER the Usage heading", async () => {
+    // The live literals carry their own `### When to use` / `### When not to
+    // use` sub-sections. Left at `###` they would be siblings of the section
+    // heading, which reads as an empty Usage section; the renderer demotes them.
+    const heading = await scalar(
+      [
+        "SELECT ?h WHERE {",
+        `  <${BUTTON}> ds:usage ?u .`,
+        '  BIND(REPLACE(STR(?u), "(?s)^.*?\\\\n### ([^\\\\n]+)\\\\n.*$", "$1") AS ?h)',
+        "}",
+      ].join("\n"),
+    );
+    expect(
+      heading,
+      "the Button usage literal carries no `### ` heading",
+    ).toBeDefined();
+
+    const llm = await renderLookup(BUTTON);
+    expect(llm).toContain(`#### ${heading}`);
+    expect(llm).not.toContain(`\n### ${heading}\n`);
+  });
+
+  it("prints no Usage heading for a block whose usage literal is empty", async () => {
+    // Roughly half the shipped blocks assert `ds:usage ""`. An empty literal
+    // must render as no section at all, never as a heading with nothing below.
+    const uri = await scalar(
+      [
+        "SELECT ?b WHERE {",
+        `  VALUES ?class { ${TYPE_VALUES} }`,
+        "  ?b a ?class ; ds:usage ?u .",
+        '  FILTER(STR(?u) = "")',
+        "}",
+        "ORDER BY ?b",
+        "LIMIT 1",
+      ].join("\n"),
+    );
+    expect(uri, "no shipped block carries an empty ds:usage").toBeDefined();
+
+    expect(await renderLookup(uri as string)).not.toContain("### Usage");
+  });
+});

package/src/capabilities/block.tierRank.exec.test.ts

@@ -0,0 +1,300 @@
+/**
+ * Which block a SHARED name means, EXECUTED against the shipped pack
+ * (PROTECTED).
+ *
+ * 25 of the design system's block names are carried by two or three blocks
+ * apiece, across tiers. `block lookup` used to answer each of them with whichever
+ * IRI sorted first and say nothing about the rest, so `button` returned
+ * Launchpad's Button — `apps_launchpad…` sorts before `global…` — and an agent
+ * had no way to learn that the block everybody means also existed.
+ *
+ * Two properties, both asserted here: EVERY block the name reaches comes back,
+ * and they come back RANKED. Either alone leaves a caller stuck — a better
+ * arbitrary pick is still arbitrary, and an unordered list of two makes the
+ * reader do the ranking the graph already knows how to do.
+ *
+ * This suite is deliberately NOT fixture-backed, and that is the whole point of
+ * it. The two nearest specimens in this package show why: `journeys.livePack`
+ * is NAMED for ordering determinism and its fixture contains one Button, and
+ * the ambiguity fixture in `blockGraph.ts` pits two tiers that do not outrank
+ * each other, so neither graph can be wrong about the ranking in the way the
+ * live graph was. A fixture written alongside a ranking rule agrees with the
+ * rule by construction. The shipped pack does not.
+ *
+ * So every case here READS the collisions out of the store it is judging. There
+ * is no list of block names in this file to fall out of date — add a tier
+ * upstream, rename one, retire a duplicate, and these assertions follow.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
+import { declaredStories, storyModules } from "./distribution.js";
+
+const story = declaredStories.get("block");
+if (!story?.lookup)
+  throw new Error('pragma.conf.ts declares no "block" lookup');
+const blockLookup = story.lookup;
+
+const blockModule = storyModules.get("block");
+if (!blockModule) throw new Error('pragma.conf.ts declares no "block" story');
+
+const verbFor = (verb: string): VerbSpec =>
+  blockModule.verbs.find(
+    (v) => verbKey(v.path) === `block ${verb}`,
+  ) as VerbSpec;
+const lookupVerb = verbFor("lookup");
+const listVerb = verbFor("list");
+
+/** The block classes the story addresses, read from the story rather than retyped. */
+const TYPE_VALUES = (blockLookup.types ?? []).join(" ");
+
+/**
+ * The scope declaration under test, read from the config it lives in.
+ *
+ * Reading `falloff` here rather than writing `0.2` is what keeps this suite a
+ * check on the RULE instead of on one tuning of it: change the number in
+ * `pragma.conf.ts` and these cases still assert that a shallower tier outranks
+ * a deeper one, which is the judgement that was signed off.
+ */
+const scope = blockLookup.scopeWeight;
+if (!scope) throw new Error('the "block" lookup declares no scopeWeight');
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  rt = bootRuntime(TEST_FLAGS);
+  await rt.store.get();
+}, 60_000);
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/** Rows from the shipped store, as plain records. */
+async function rows(query: string): Promise<Record<string, string>[]> {
+  const result = await rt.query.sparql(query);
+  return result.type === "select"
+    ? (result.bindings as Record<string, string>[])
+    : [];
+}
+
+/** One `block lookup <name>`: the IRI it answered with, and the ones it did not. */
+async function lookup(
+  name: string,
+): Promise<{ chosen: string; others: string[] }> {
+  const out = (await lookupVerb.run({ name: [name] }, rt)) as {
+    results: { uri?: string }[];
+  };
+  // Every entity the name reached, best first. `chosen` is simply the head —
+  // the ranking orders the answer now, it does not select it.
+  const [chosen, ...others] = out.results.map((entity) => String(entity.uri));
+  return { chosen: String(chosen), others };
+}
+
+/**
+ * Every block name the shipped graph gives to more than one block, with each
+ * block's IRI, its tier's declared name and whether it is a subcomponent.
+ *
+ * Read with the SAME `LCASE` the resolve filters by, so a pair that collides
+ * only for a lookup (`Button` vs `button`) is in this set too.
+ */
+async function collisions(): Promise<
+  Map<string, { uri: string; tier: string; part: boolean }[]>
+> {
+  const found = await rows(
+    [
+      "SELECT ?uri ?key ?tierName ?part WHERE {",
+      `  VALUES ?class { ${TYPE_VALUES} }`,
+      "  ?uri a ?class .",
+      `  ?uri ${blockLookup.by} ?name .`,
+      `  OPTIONAL { ?uri ${scope.via} ?tier . ?tier ${scope.by} ?tn . }`,
+      "  BIND(LCASE(STR(?name)) AS ?key)",
+      '  BIND(COALESCE(?tn, "") AS ?tierName)',
+      "  BIND(EXISTS { ?uri a ds:Subcomponent } AS ?part)",
+      "}",
+    ].join("\n"),
+  );
+  const byName = new Map<
+    string,
+    { uri: string; tier: string; part: boolean }[]
+  >();
+  for (const row of found) {
+    const key = String(row.key);
+    const entry = {
+      uri: String(row.uri),
+      tier: String(row.tierName ?? ""),
+      part: String(row.part) === "true",
+    };
+    const seen = byName.get(key);
+    if (seen) {
+      if (!seen.some((e) => e.uri === entry.uri)) seen.push(entry);
+    } else byName.set(key, [entry]);
+  }
+  return new Map([...byName].filter(([, entries]) => entries.length > 1));
+}
+
+/** A tier's depth: the separator count in its DECLARED name, +1. */
+const depthOf = (tierName: string): number =>
+  tierName === "" ? 1 : tierName.split("/").length;
+
+describe("a shared block name reaches every block that carries it (PROTECTED)", () => {
+  it("finds shared names in the shipped graph at all", async () => {
+    // The guard on every other case in this file: if the graph ever stops
+    // sharing names, these assertions become vacuous and must be told to go.
+    expect((await collisions()).size).toBeGreaterThan(1);
+  });
+
+  it("answers `button` with the GLOBAL Button, and names the other", async () => {
+    // The reported defect, exactly as reported. Two components of equal kind,
+    // separated by their tiers alone: Global is depth 1, Apps/Launchpad depth 2.
+    const out = await lookup("button");
+    expect(out.chosen).toBe("https://ds.canonical.com/global.component.button");
+    expect(out.others).toEqual([
+      "https://ds.canonical.com/apps_launchpad.component.button",
+    ]);
+  });
+
+  it("answers `TextInput` with the LAUNCHPAD one — a whole block beats a part", async () => {
+    // The case that stops the plausible wrong fix. A rule of "global wins", or
+    // a tier tiebreak ABOVE the type weight, would answer with the global
+    // SUBcomponent here. As a product it does not: 0.6 × 1 < 1 × 0.8. The
+    // editorial rule that a subcomponent is a PART of a block, never the block
+    // someone means, survives the tier ranking being added on top of it.
+    const out = await lookup("TextInput");
+    expect(out.chosen).toBe(
+      "https://ds.canonical.com/apps_launchpad.component.text_input",
+    );
+    expect(out.others).toEqual([
+      "https://ds.canonical.com/global.subcomponent.text_input",
+    ]);
+  });
+
+  it("answers a name shared by two EQUALLY deep tiers deterministically", async () => {
+    // `ThemeSwitcher` is Apps/Anbox against Apps/WorkplaceEngineering — same
+    // depth, so the ranking has nothing to say and the total order's final key
+    // decides. This is the residual the ranking does NOT resolve, asserted as
+    // such: the claim is not that the right one wins, it is that the same one
+    // wins every time and the other is never left unmentioned.
+    const runs = await Promise.all([
+      lookup("ThemeSwitcher"),
+      lookup("themeswitcher"),
+      lookup("ThemeSwitcher"),
+    ]);
+    for (const out of runs) {
+      expect(out.chosen).toBe(runs[0]?.chosen);
+      expect(out.others).toEqual(runs[0]?.others);
+      expect(out.others).toHaveLength(1);
+      // Equal rank, so the order's final key decides — the same key, the same
+      // way, as everywhere else in it.
+      expect([out.chosen, ...out.others].sort()).toEqual([
+        out.chosen,
+        ...out.others,
+      ]);
+    }
+  });
+
+  it("never leaves a block a shared name reaches unmentioned", async () => {
+    // Swept over the whole collision set, not a chosen few: the silent discard
+    // is the defect, and it was invisible precisely because it looked like a
+    // normal answer. Every block the name reaches is either the answer or named
+    // beside it — and named as an IRI, the one address that reaches it.
+    for (const [name, entries] of await collisions()) {
+      const out = await lookup(name);
+      expect(
+        [out.chosen, ...out.others].sort(),
+        `block lookup ${name}`,
+      ).toEqual(entries.map((entry) => entry.uri).sort());
+    }
+  });
+
+  it("ranks the winner's tier no worse than every loser's", async () => {
+    // The invariant, COMPUTED from the pack rather than listed. It holds for
+    // every shared name at once and cannot be satisfied by hard-coding an
+    // answer, so it survives a new tier, a renamed one, and a new collision.
+    //
+    // Stated over WHOLE BLOCKS only. A subcomponent is deliberately allowed to
+    // lose to a shallower-ranked component AND to a deeper-ranked one — that is
+    // the product, and `TextInput` above is the case that pins it.
+    for (const [name, entries] of await collisions()) {
+      const blocks = entries.filter((entry) => !entry.part);
+      if (blocks.length < 2) continue;
+      const { chosen } = await lookup(name);
+      const winner = blocks.find((entry) => entry.uri === chosen);
+      if (!winner) continue;
+      for (const loser of blocks) {
+        expect(
+          depthOf(winner.tier),
+          `block lookup ${name} led with ${winner.uri} (${winner.tier}) over ${loser.uri} (${loser.tier})`,
+        ).toBeLessThanOrEqual(depthOf(loser.tier));
+      }
+    }
+  });
+});
+
+describe("`block list` orders its ties totally (PROTECTED)", () => {
+  /** The entity IRIs of one `block list` run, in the order it printed them. */
+  async function listOrder(): Promise<string[]> {
+    const data = (await listVerb.run({}, rt)) as { uri?: string }[];
+    return data.map((row) => String(row.uri));
+  }
+
+  it("repeats the same order across runs", async () => {
+    // The half that looks like the whole defect and is not: across runs the
+    // store's scan order can change (a repack, another machine).
+    const [first, second] = await Promise.all([listOrder(), listOrder()]);
+    expect(first).toEqual(second);
+    expect(first.length).toBeGreaterThan(1);
+  });
+
+  it("orders EVERY tie the same way, within one run", async () => {
+    // The half that was actually broken. In ONE output `Button` came
+    // launchpad-first while `CheckboxInput` came global-first — not flakiness
+    // between runs, an inconsistency inside a single answer, because SPARQL
+    // says nothing about tied rows and the query's ORDER BY ended at `?name`.
+    //
+    // Asserted as a RULE over every shared name rather than on the two that
+    // happened to disagree: shallower tier leads, and equal depths fall back to
+    // a key that cannot tie.
+    const order = await listOrder();
+    const position = new Map(order.map((uri, index) => [uri, index]));
+    const shared = await collisions();
+    expect(shared.size).toBeGreaterThan(1);
+    for (const [name, entries] of shared) {
+      const group = [...entries].sort(
+        (a, b) => (position.get(a.uri) ?? -1) - (position.get(b.uri) ?? -1),
+      );
+      expect(
+        group.map((entry) => position.get(entry.uri)),
+        `block list rows for ${name}`,
+      ).not.toContain(undefined);
+      for (const [index, entry] of group.entries()) {
+        const next = group[index + 1];
+        if (!next) continue;
+        const keys = [
+          [depthOf(entry.tier), entry.uri],
+          [depthOf(next.tier), next.uri],
+        ] as const;
+        expect(
+          keys[0][0] < keys[1][0] ||
+            (keys[0][0] === keys[1][0] && keys[0][1] < keys[1][1]),
+          `block list printed ${entry.uri} (${entry.tier}) before ${next.uri} (${next.tier}) for "${name}"`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("keeps every shared name's rows adjacent, one per block", async () => {
+    // The ordering above would also be satisfied by a list that lost a row, so
+    // the population is checked with it: the tie-break decides the order of the
+    // rows, never how many there are.
+    const order = await listOrder();
+    for (const [name, entries] of await collisions()) {
+      const present = entries.filter((entry) => order.includes(entry.uri));
+      expect(present, `block list rows for ${name}`).toHaveLength(
+        entries.length,
+      );
+    }
+  });
+});

package/src/capabilities/capabilities/capabilities.render.ts

@@ -7,7 +7,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { CapabilitiesData, ToolCategory } from "./types.js";
 
 /** Category display order for grouped tool listings. */

package/src/capabilities/capabilities/capabilities.verb.ts

@@ -23,7 +23,7 @@
 
 import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { capabilitiesFormatters } from "./capabilities.render.js";
 import type { CapabilitiesData } from "./types.js";
 

package/src/capabilities/capabilities/catalog.ts

@@ -15,8 +15,8 @@
  */
 
 import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../constants.js";
-import { emitSurface } from "../../kernel/spec/emitSurface.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { emitSurface } from "../../kernel/spec/index.js";
 import { TOOL_HINTS } from "./hints.js";
 import type {
   CapabilitiesData,
@@ -91,7 +91,7 @@ export function buildDiscoverySequence(
       stage: 2,
       tool: "sources_status",
       purpose:
-        "See which pack is answering. A fresh install answers reads from the snapshot embedded in the binary and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
+        "See which pack is answering. A fresh install answers reads from the snapshot shipped with the CLI and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
     },
     {
       stage: 3,