@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/skill/bundledSkills.test.ts

@@ -0,0 +1,347 @@
+/**
+ * The BUNDLED skills snapshot — the third discovery root, last in precedence.
+ *
+ * `scripts/bundle.ts` already resolved every declared pack to read its TTL into
+ * `pack.generated.ts`; it now also copies each pack's `skills/<name>/` into the
+ * committed `bundled-skills/` directory at the package root. So a fresh install
+ * lists skills for the same reason it answers `block lookup`: the release
+ * carries a snapshot of what its packs shipped.
+ *
+ * WHAT THESE CELLS SAMPLE. Every expectation about skill CONTENT is read out of
+ * the committed artifact rather than written into a fixture beside the code.
+ * Inventing "a bundled skill" here would prove that a directory this test wrote
+ * can be discovered — which is already covered — while a snapshot that shipped
+ * empty, shipped a folder with no `SKILL.md`, or was dropped from `files` would
+ * stay green. The artifact is real upstream data; it is what has to work.
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dryRun } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { BIN_NAME } from "../../constants.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { runCli } from "../../testing/helpers/runCli.js";
+import { scopedChecks } from "../doctor/checks/targetHealth.js";
+import {
+  composeSkills,
+  detectSkills,
+  staleSkillLinks,
+} from "../setup/operations/setupSkills.js";
+import {
+  bundledSkillsDir,
+  discoverSkills,
+  globalSkillRoots,
+  installedSkillsDir,
+  parseFrontmatter,
+} from "./discover.js";
+
+const packageRoot = fileURLToPath(new URL("../../../", import.meta.url));
+
+/** The snapshot's folder → declared `name`, read from the shipped bytes. */
+function shippedSkills(): { folder: string; name: string }[] {
+  const root = bundledSkillsDir();
+  if (root === undefined) return [];
+  return readdirSync(root)
+    .map((folder) => {
+      const skillMd = join(root, folder, "SKILL.md");
+      if (!existsSync(skillMd)) return undefined;
+      const frontmatter = parseFrontmatter(readFileSync(skillMd, "utf-8"));
+      return frontmatter ? { folder, name: frontmatter.name } : undefined;
+    })
+    .filter((entry): entry is { folder: string; name: string } => !!entry);
+}
+
+/** A FRESH INSTALL's environment: nothing of this machine is inherited. */
+function freshInstallEnv(): Record<string, string> {
+  const home = mkdtempSync(join(tmpdir(), "pragma-fresh-home-"));
+  return {
+    HOME: home,
+    USERPROFILE: home,
+    XDG_CONFIG_HOME: mkdtempSync(join(tmpdir(), "pragma-fresh-cfg-")),
+    XDG_DATA_HOME: mkdtempSync(join(tmpdir(), "pragma-fresh-data-")),
+    XDG_STATE_HOME: mkdtempSync(join(tmpdir(), "pragma-fresh-state-")),
+    XDG_CACHE_HOME: mkdtempSync(join(tmpdir(), "pragma-fresh-cache-")),
+  };
+}
+
+describe("bundled skills — the shipped snapshot", () => {
+  it("the committed artifact is a real, well-formed skills root", () => {
+    const root = bundledSkillsDir();
+    expect(root).toBeDefined();
+    const entries = readdirSync(root as string);
+    // Not merely non-empty: EVERY entry must be a discoverable skill. A folder
+    // the copy pass half-wrote (or a stray file) would be skipped silently by
+    // discovery, which is exactly how a thinned snapshot ships unnoticed.
+    expect(entries.length).toBeGreaterThan(0);
+    expect(
+      shippedSkills()
+        .map((s) => s.folder)
+        .sort(),
+    ).toEqual([...entries].sort());
+  });
+
+  it("is the LAST discovery root, after project and installed", () => {
+    const roots = globalSkillRoots();
+    expect(roots[0]).toBe(installedSkillsDir());
+    expect(roots.at(-1)).toBe(bundledSkillsDir());
+  });
+});
+
+describe("bundled skills — a fresh install, through the shipped entry", () => {
+  it("lists the packs' skills with no `sources update` (REGRESSION)", () => {
+    // THE DEFECT. A fresh install had zero skills and a two-command, network-
+    // dependent recovery (`sources update` then `setup skills`) for content the
+    // release had already resolved at bundle time. Isolated HOME + all four XDG
+    // roots, so anything answered here was answered from the package itself.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-fresh-proj-"));
+    const outcome = runCli(["skill", "list", "--format", "json"], {
+      cwd,
+      env: freshInstallEnv(),
+    });
+    expect(outcome.exitCode).toBe(0);
+    const envelope = JSON.parse(outcome.stdout) as {
+      data: { name: string }[];
+    };
+    const listed = envelope.data.map((skill) => skill.name).sort();
+    expect(listed.length).toBeGreaterThan(0);
+    // Every skill the snapshot ships is listed — not just "some skills".
+    expect(listed).toEqual(
+      expect.arrayContaining(
+        shippedSkills()
+          .map((s) => s.name)
+          .sort(),
+      ),
+    );
+    expect(outcome.stderr).not.toContain("No skills found");
+  });
+
+  it("`setup --dry-run` OFFERS a skills row instead of skipping it", () => {
+    // The other half of the same defect: the global scope's only source was the
+    // installed root, so a fresh machine's setup plan skipped skills entirely
+    // and pointed at `sources update` as the remedy.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-fresh-setup-"));
+    const outcome = runCli(["setup", "--dry-run", "--global"], {
+      cwd,
+      env: freshInstallEnv(),
+    });
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toMatch(/skills\s+link\s+\d+ skills? →/);
+    expect(outcome.stdout).not.toContain("no skills installed");
+  });
+});
+
+describe("bundled skills — precedence", () => {
+  let previousDataHome: string | undefined;
+  let dataHome: string;
+  let cwd: string;
+
+  /** The first skill the snapshot ships — the name both overrides reuse. */
+  const shadowed = (): { folder: string; name: string } => {
+    const first = shippedSkills()[0];
+    if (first === undefined) throw new Error("no bundled skills to shadow");
+    return first;
+  };
+
+  /** Write a `SKILL.md` for `name` under `root/folder`, with a marker body. */
+  const writeSkill = (root: string, folder: string, name: string): void => {
+    mkdirSync(join(root, folder), { recursive: true });
+    writeFileSync(
+      join(root, folder, "SKILL.md"),
+      `---\nname: ${name}\ndescription: OVERRIDE.\n---\n`,
+    );
+  };
+
+  beforeEach(() => {
+    previousDataHome = process.env.XDG_DATA_HOME;
+    dataHome = mkdtempSync(join(tmpdir(), "pragma-prec-data-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    cwd = mkdtempSync(join(tmpdir(), "pragma-prec-proj-"));
+  });
+
+  afterEach(() => {
+    process.env.XDG_DATA_HOME = previousDataHome;
+  });
+
+  it("an INSTALLED skill of the same name wins over the bundled copy", () => {
+    // The rule someone who ran `sources update` is relying on: the update they
+    // asked for must reach them, never the copy frozen at release time.
+    const { folder, name } = shadowed();
+    writeSkill(installedSkillsDir(), folder, name);
+    const found = discoverSkills(cwd).find((skill) => skill.name === name);
+    expect(found?.description).toBe("OVERRIDE.");
+    expect(found?.sourcePath).toBe(join(installedSkillsDir(), folder));
+  });
+
+  it("a PROJECT skill wins over both", () => {
+    const { folder, name } = shadowed();
+    writeSkill(installedSkillsDir(), folder, name);
+    writeSkill(join(cwd, ".pragma", "skills"), folder, `${name}`);
+    const found = discoverSkills(cwd).find((skill) => skill.name === name);
+    expect(found?.sourcePath).toBe(join(cwd, ".pragma", "skills", folder));
+  });
+
+  it("shadowing REPLACES rather than duplicates the name", () => {
+    const { folder, name } = shadowed();
+    writeSkill(installedSkillsDir(), folder, name);
+    const matches = discoverSkills(cwd).filter((skill) => skill.name === name);
+    expect(matches).toHaveLength(1);
+  });
+});
+
+describe("bundled skills — the upgrade hazard", () => {
+  // THE HAZARD, spelled out. Every other link `setup skills` writes points into
+  // a directory pragma controls; a bundled one points into the package
+  // directory, which the PACKAGE MANAGER owns. `npm i -g` reuses the same path,
+  // but a pnpm / npx / versioned layout does not — so an upgrade can leave a
+  // harness link dangling at a package directory that no longer exists.
+  //
+  // The design turns on whether the EXISTING reconcile repairs that or leaves
+  // it, and that is answered here by construction rather than by reading the
+  // code: a link to a plausible previous release's path is planted in the
+  // harness directory, and the forward plan is inspected.
+  const FLAGS: GlobalFlags = {
+    format: "plain",
+    color: false,
+    quiet: false,
+    verbose: false,
+  };
+
+  let prevHome: string | undefined;
+  let prevDataHome: string | undefined;
+  let home: string;
+
+  beforeEach(() => {
+    prevHome = process.env.HOME;
+    prevDataHome = process.env.XDG_DATA_HOME;
+    home = mkdtempSync(join(tmpdir(), "pragma-upgrade-home-"));
+    process.env.HOME = home;
+    // An empty installed root, so the bundled snapshot is the scope's only
+    // source — exactly a fresh install that has never run `sources update`.
+    process.env.XDG_DATA_HOME = mkdtempSync(
+      join(tmpdir(), "pragma-upgrade-data-"),
+    );
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) delete process.env.HOME;
+    else process.env.HOME = prevHome;
+    if (prevDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = prevDataHome;
+  });
+
+  it("repairs a link into a REPLACED package directory (REGRESSION)", async () => {
+    const first = shippedSkills()[0];
+    if (first === undefined) throw new Error("no bundled skills");
+    // The harness directory as an upgrade would leave it: a link at the right
+    // name pointing into the version-stamped path of the release before this
+    // one, which no longer exists.
+    const harnessDir = join(home, ".agents", "skills");
+    mkdirSync(harnessDir, { recursive: true });
+    const linkPath = join(harnessDir, first.folder);
+    symlinkSync(
+      join(tmpdir(), "pragma-cli@0.34.0", "bundled-skills", first.folder),
+      linkPath,
+    );
+    expect(lstatSync(linkPath).isSymbolicLink()).toBe(true); // present…
+    expect(existsSync(linkPath)).toBe(false); // …and dangling.
+
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-upgrade-proj-"));
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "global");
+
+    // Planned as `replaced` — NOT skipped as somebody else's link, and NOT
+    // swept as an orphan: the per-skill pass covers the path, so the sweep
+    // never sees it. Both halves matter; either one alone would lose the link.
+    const action = detected.actions.find((a) => a.linkPath === linkPath);
+    expect(action?.action).toBe("replaced");
+    expect(action?.skillName).toBe(first.name);
+    expect(staleSkillLinks(detected).map((a) => a.linkPath)).not.toContain(
+      linkPath,
+    );
+
+    // And the forward run is delete-then-relink onto the CURRENT package, so
+    // one `setup skills` after an upgrade converges the harness.
+    expect(
+      dryRun(composeSkills(detected)).effects.map((e) => e._tag),
+    ).toContain("DeleteFile");
+    await runTask(composeSkills(detected));
+    expect(existsSync(linkPath)).toBe(true);
+    expect(readFileSync(join(linkPath, "SKILL.md"), "utf-8")).toContain(
+      `name: ${first.name}`,
+    );
+  });
+
+  it("doctor makes the upgrade window VISIBLE, with the command that closes it", async () => {
+    // The residual risk is the gap between an upgrade and the next
+    // `setup skills`: the link dangles and the harness sees a broken skill.
+    // One command converges it (above) — so what has to be true is that
+    // something TELLS the user to run it. This is that assertion. Without it
+    // the window is real but silent, which is the "doctor blind to orphans"
+    // shape sitting on a path an upgrade reaches routinely.
+    const first = shippedSkills()[0];
+    if (first === undefined) throw new Error("no bundled skills");
+    const harnessDir = join(home, ".agents", "skills");
+    mkdirSync(harnessDir, { recursive: true });
+    symlinkSync(
+      join(tmpdir(), "pragma-cli@0.34.0", "bundled-skills", first.folder),
+      join(harnessDir, first.folder),
+    );
+
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-upgrade-doctor-"));
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), BIN_NAME);
+    const row = rows.find((r) => r.name === "skills" && r.scope === "global");
+    expect(row?.status).toBe("fail");
+    expect(row?.detail).toContain("point elsewhere");
+    // No AUTHORED remedy on this branch: the row takes the derived one, which
+    // is exactly the command proven to repair it in the cell above.
+    expect(row?.remedy).toBe(`${BIN_NAME} setup skills`);
+  });
+
+  it("discovery itself cannot degrade on an upgrade", () => {
+    // The other half of the worry — that a moved package directory would make
+    // the snapshot vanish from DISCOVERY too, silently returning the CLI to the
+    // skips-everything state this change removes. It cannot: `bundledSkillsDir`
+    // walks up from `import.meta.url`, so it resolves against whichever copy of
+    // the package is EXECUTING, which is the new one by definition. There is no
+    // recorded path anywhere that an upgrade could invalidate.
+    expect((bundledSkillsDir() as string).startsWith(packageRoot)).toBe(true);
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-upgrade-disc-"));
+    expect(discoverSkills(cwd).length).toBeGreaterThan(0);
+  });
+});
+
+describe("bundled skills — packaging", () => {
+  // Generous timeout: this shells out to the real packer over ~950 files.
+  it("the snapshot is in the published tarball (`files` allowlist)", () => {
+    // `files` allowlists are exactly the kind of thing that looks right and
+    // ships nothing: the directory would exist in the repo, every test above
+    // would pass from the source tree, and a consumer's install would carry no
+    // skills at all. Only the packer's own answer settles it.
+    const packed = spawnSync(
+      "npm",
+      ["pack", "--dry-run", "--json", "--ignore-scripts"],
+      { cwd: packageRoot, encoding: "utf-8", timeout: 120_000 },
+    );
+    expect(packed.status).toBe(0);
+    const files = (
+      JSON.parse(packed.stdout) as { files: { path: string }[] }[]
+    )[0]?.files.map((file) => file.path);
+    for (const { folder } of shippedSkills()) {
+      expect(files).toContain(`bundled-skills/${folder}/SKILL.md`);
+    }
+  }, 120_000);
+});

package/src/capabilities/skill/discover.ts

@@ -4,15 +4,17 @@
  * A skill is a folder with a `SKILL.md` carrying YAML frontmatter (`name`,
  * `description`, and the #856 `prompt` flag among others). Skills are discovered
  * from conventional roots — project skills under `<cwd>/.pragma/skills`, which
- * take precedence, then installed skills under `$XDG_DATA_HOME/pragma/skills` —
- * with missing files and invalid frontmatter skipped gracefully. Reads only the
+ * take precedence, then installed skills under `$XDG_DATA_HOME/pragma/skills`,
+ * then the BUNDLED snapshot this package ships (`bundled-skills/`) — with
+ * missing files and invalid frontmatter skipped gracefully. Reads only the
  * filesystem, never the graph store, so `skill list`/`lookup` are storeless
  * (needsStore: false).
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { BIN_NAME } from "../../constants.js";
 
 /** Parsed SKILL.md frontmatter. */
@@ -120,15 +122,115 @@ export function installedSkillsDir(): string {
   return join(dataHome, BIN_NAME, "skills");
 }
 
+/**
+ * The project skills root: `<cwd>/.<bin>/skills` — skills that belong to THIS
+ * repository and travel with it. Named separately from {@link skillRoots}
+ * because the two roots are also the two setup SCOPES: `setup skills --local`
+ * links this root into the project's harness directories, while the global scope
+ * links {@link installedSkillsDir} into the user-level ones. Mixing them leaks
+ * machine state into a repository's directories, or applies one repository's
+ * skills machine-wide.
+ */
+export function projectSkillsDir(cwd: string): string {
+  return join(cwd, `.${BIN_NAME}`, "skills");
+}
+
+/**
+ * The directory name of the SNAPSHOT of pack skills this package ships, at its
+ * own root. Written by `scripts/bundle.ts` and COMMITTED, exactly as
+ * `src/kernel/runtime/graphpack/embedded/pack.generated.ts` is — see
+ * {@link bundledSkillsDir}.
+ */
+const BUNDLED_SKILLS_DIRNAME = "bundled-skills";
+
+/**
+ * How far above this module the package root can be. `src/capabilities/skill`
+ * is three levels up; the emitted `dist/src/capabilities/skill` is four. The
+ * bound exists so a tree that is MISSING the artifact stops at the package
+ * instead of walking to `/` and adopting an unrelated directory.
+ */
+const BUNDLED_SEARCH_DEPTH = 6;
+
+/**
+ * The BUNDLED-skills root: `<package root>/bundled-skills`, the snapshot of the
+ * declared packs' `skills/<name>/` that `scripts/bundle.ts` commits alongside
+ * the embedded graph — `undefined` when this build ships none.
+ *
+ * WHY IT EXISTS. The embedded pack (`pack.generated.ts`) is what lets a fresh
+ * install answer `block lookup` offline. The skills came out of the very same
+ * `resolvePackage` calls and were left on the build machine's disk, so the same
+ * fresh install listed ZERO skills and told the user to run `sources update`
+ * first — a network round trip and two commands for something already resolved
+ * at release time. This is the skills half of the snapshot the graph has had
+ * all along.
+ *
+ * WHY IT IS FOUND BY WALKING UP rather than by a fixed relative path. `files`
+ * ships BOTH `src` and `dist`, and `tsconfig.build.json` sets `rootDir: "."`,
+ * so this module runs from `src/capabilities/skill/` in a source or test run
+ * and from `dist/src/capabilities/skill/` in the shipped one — the package root
+ * is three levels up in one and four in the other, and no single
+ * `new URL("../../..")` is right for both. The walk anchors on the artifact's
+ * own name sitting NEXT TO a `package.json`, which is true only at the package
+ * root: `dist/` carries a `package.json` too (`resolveJsonModule` copies it)
+ * but never the snapshot.
+ *
+ * @returns The bundled root, or `undefined` when no ancestor holds one.
+ * @note Impure — stats up to {@link BUNDLED_SEARCH_DEPTH} ancestor directories.
+ *   Reached from the `__complete` fast path, so it stays `node:fs` /
+ *   `node:path` / `node:url` only and costs a handful of `stat`s.
+ */
+export function bundledSkillsDir(): string | undefined {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let up = 0; up < BUNDLED_SEARCH_DEPTH; up += 1) {
+    const candidate = join(dir, BUNDLED_SKILLS_DIRNAME);
+    if (existsSync(join(dir, "package.json")) && existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
 /**
  * The conventional roots skills are discovered from, in PRECEDENCE order: the
  * project root (`<cwd>/.<bin>/skills`) FIRST so a project-local skill overrides
  * an installed skill of the same name (`discoverSkills` dedups first-seen-wins),
  * then installed skills under `$XDG_DATA_HOME/<bin>/skills` (where package
- * skills land on `sources update`).
+ * skills land on `sources update`), then the BUNDLED snapshot
+ * ({@link bundledSkillsDir}).
+ *
+ * BUNDLED IS LAST, and that order is the whole contract. The snapshot is as old
+ * as the release; an installed skill came from a `sources update` the user ran
+ * deliberately, and a project skill is the repository's own. So someone who
+ * updates gets the CURRENT skill and never the shipped copy, while a fresh
+ * install — which has neither of the first two roots — still gets the packs'
+ * skills instead of an empty list and a two-command recovery.
  */
 export function skillRoots(cwd: string): string[] {
-  return [join(cwd, `.${BIN_NAME}`, "skills"), installedSkillsDir()];
+  return [projectSkillsDir(cwd), ...globalSkillRoots()];
+}
+
+/**
+ * The GLOBAL scope's source roots, in precedence order: the INSTALLED root
+ * (`sources update`'s output) first, then the BUNDLED snapshot.
+ *
+ * Named separately from {@link skillRoots} for the reason
+ * {@link projectSkillsDir} is: these are the two roots `setup skills --global`
+ * links into the user-level harness directories, and `skillRoots` is discovery,
+ * which spans both scopes. Reading the project root for the global scope is
+ * exactly the cross-scope leak the scope split exists to prevent.
+ *
+ * A BAND CAN HOLD MORE THAN ONE ROOT, and this is where that became true. The
+ * global scope's ownership test and its stale-link sweep therefore range over
+ * the SET (see `setup/operations/setupSkills.ts`), never over one path.
+ */
+export function globalSkillRoots(): string[] {
+  const bundled = bundledSkillsDir();
+  return bundled === undefined
+    ? [installedSkillsDir()]
+    : [installedSkillsDir(), bundled];
 }
 
 /** Immediate subdirectories of `root` (each a candidate skill folder). */
@@ -149,16 +251,24 @@ function subdirs(root: string): string[] {
 }
 
 /**
- * Discover every skill reachable from the conventional roots.
+ * Discover every skill reachable from an EXPLICIT list of roots, in precedence
+ * order (first-seen wins on a duplicate name).
  *
- * @param cwd - The project directory (project skills root).
+ * Split out of {@link discoverSkills} so a caller that owns one scope can read
+ * exactly that scope's root: `setup skills` links the project root into project
+ * harness directories and the installed root into user-level ones, and reading
+ * both roots for either scope is what used to mix the two.
+ *
+ * @param roots - The roots to read, in precedence order.
  * @returns Discovered skills, sorted by name; malformed ones are skipped.
  * @note Impure — reads SKILL.md files.
  */
-export function discoverSkills(cwd: string): DiscoveredSkill[] {
+export function discoverSkillsFrom(
+  roots: readonly string[],
+): DiscoveredSkill[] {
   const skills: DiscoveredSkill[] = [];
   const seen = new Set<string>();
-  for (const root of skillRoots(cwd)) {
+  for (const root of roots) {
     for (const dir of subdirs(root)) {
       let content: string;
       try {
@@ -182,3 +292,14 @@ export function discoverSkills(cwd: string): DiscoveredSkill[] {
     a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
   );
 }
+
+/**
+ * Discover every skill reachable from the conventional roots.
+ *
+ * @param cwd - The project directory (project skills root).
+ * @returns Discovered skills, sorted by name; malformed ones are skipped.
+ * @note Impure — reads SKILL.md files.
+ */
+export function discoverSkills(cwd: string): DiscoveredSkill[] {
+  return discoverSkillsFrom(skillRoots(cwd));
+}

package/src/capabilities/skill/index.ts

@@ -2,7 +2,7 @@
  * The `skill` capability module — storeless filesystem discovery.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { skillListVerb, skillLookupVerb } from "./verbs.js";
 
 /** The `skill` capability module (`list`, `lookup`). */

package/src/capabilities/skill/render.ts

@@ -3,7 +3,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 { DiscoveredSkill } from "./discover.js";
 import type { SkillLookup } from "./verbs.js";
 
@@ -12,15 +12,16 @@ const EMPTY_PLAIN = `No skills found.\nSkills come from design-system packs —
 const EMPTY_LLM = `## Skills (0)\n\nNo skills found. Skills come from design-system packs — add one to the project config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
 
 export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
+  // Zero skills: plain stdout stays empty — the guidance is `notice`,
+  // which the dispatcher routes to stderr (exit 0) so a pipe reads no prose.
   plain: (skills) =>
-    skills.length === 0
-      ? EMPTY_PLAIN
-      : skills
-          .map(
-            (s) =>
-              `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
-          )
-          .join("\n"),
+    skills
+      .map(
+        (s) =>
+          `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
+      )
+      .join("\n"),
+  notice: (skills) => (skills.length === 0 ? EMPTY_PLAIN : undefined),
   llm: (skills) =>
     skills.length === 0
       ? EMPTY_LLM

package/src/capabilities/skill/skill.test.ts

@@ -15,7 +15,11 @@ 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 type { DiscoveredSkill } from "./discover.js";
+import {
+  bundledSkillsDir,
+  type DiscoveredSkill,
+  discoverSkillsFrom,
+} from "./discover.js";
 import { skillModule } from "./index.js";
 import { skillListFormatters } from "./render.js";
 import type { SkillLookup } from "./verbs.js";
@@ -60,7 +64,16 @@ afterAll(() => {
 describe("skill list (storeless)", () => {
   it("discovers skills by name, carrying the prompt flag", async () => {
     const skills = (await listVerb.run({}, rt)) as DiscoveredSkill[];
-    expect(skills.map((s) => s.name)).toEqual(["docx", "pdf"]);
+    // The list is the project root's two skills UNION the bundled snapshot the
+    // package ships (`bundledSkills.test.ts` owns the snapshot's own cells).
+    // Derived from the shipped artifact rather than spelled out, so a release
+    // that changes which skills the packs provide does not rewrite this test.
+    const bundled = discoverSkillsFrom([bundledSkillsDir() as string]).map(
+      (s) => s.name,
+    );
+    expect(skills.map((s) => s.name)).toEqual(
+      [...new Set(["docx", "pdf", ...bundled])].sort(),
+    );
     expect(skills.find((s) => s.name === "pdf")?.frontmatter.prompt).toBe(true);
     expect(
       skills.find((s) => s.name === "docx")?.frontmatter.prompt,
@@ -85,11 +98,13 @@ describe("skill lookup (storeless)", () => {
 });
 
 describe("skill list empty-state (U5)", () => {
-  it("plain output is non-blank and guides toward package sources", () => {
-    const plain = skillListFormatters.plain([]);
-    expect(plain).not.toBe("");
-    expect(plain).toContain("No skills found");
-    expect(plain).toContain("pragma sources update");
+  it("the empty notice (stderr's text) guides toward package sources", () => {
+    // Zero skills: plain stdout is empty (a pipe reads no prose) and the
+    // guidance rides the dispatcher's stderr via `notice`.
+    expect(skillListFormatters.plain([])).toBe("");
+    const notice = skillListFormatters.notice?.([]);
+    expect(notice).toContain("No skills found");
+    expect(notice).toContain("pragma sources update");
   });
 
   it("llm output announces zero and guides, json stays []", () => {

package/src/capabilities/skill/verbs.ts

@@ -9,12 +9,11 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { BIN_NAME } from "../../constants.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
 import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.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 { type DiscoveredSkill, discoverSkills } from "./discover.js";
 import { skillListFormatters, skillLookupFormatters } from "./render.js";
 

package/src/capabilities/sources/collectStatus.ts

@@ -12,12 +12,17 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { PackDeclaration } from "../../kernel/config/types.js";
+import type { PackDeclaration } from "../../kernel/config/index.js";
+// DIRECT LEAF IMPORTS, not `graphpack/index.js`. The barrel re-exports
+// `build.ts`/`read.ts` (pulling `@canonical/ke` and `@canonical/ke-graphql`)
+// and `embedded.ts`, whose generated payload is ~1.9 MB. `sources status`
+// reads two manifests and prints them; routing that through the barrel
+// would make a status-only command initialise the whole pack stack.
 import { embeddedManifest } from "../../kernel/runtime/graphpack/embedded.js";
 import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
 import { INDEX_FILE } from "../../kernel/runtime/graphpack/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { resolveSources } from "../../kernel/runtime/resolveSources.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { SourcesStatusData } from "./types.js";
 
 const entryName = (entry: PackDeclaration): string =>