@canonical/pragma-cli 0.35.0 → 0.36.0

package/src/capabilities/sources/installSkills.ts

@@ -26,9 +26,20 @@
  * accurate; the composed Task performs only the symlink/delete effects.
  */
 
-import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readlinkSync,
+  statSync,
+} from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { ResolvedPackage } from "../../kernel/runtime/refs/index.js";
+// The ownership test, imported rather than reimplemented: `setup skills` and
+// this module must not be able to disagree about which links belong to pragma.
+// `setupSkills.ts` reaches `@canonical/harnesses` only through a DYNAMIC
+// import, so this edge adds no static one (`capabilities/lazy.test.ts`).
+import { withinAnyRoot } from "../setup/operations/setupSkills.js";
 import { installedSkillsDir } from "../skill/discover.js";
 
 /** One planned skill symlink into the installed-skills root. */
@@ -94,7 +105,11 @@ function packageSkillDirs(root: string): string[] {
   for (const name of names) {
     const dir = join(skillsDir, name);
     try {
-      if (lstatSync(dir).isDirectory() && existsSync(join(dir, "SKILL.md"))) {
+      // `stat`, not `lstat`: a package that ships `skills/<name>` as a SYMLINK
+      // — the ordinary pnpm / monorepo / `file:` layout — contributed nothing
+      // at all, silently, because `lstat` reports the link and not the
+      // directory behind it. Discovery uses `stat`; so does this now.
+      if (statSync(dir).isDirectory() && existsSync(join(dir, "SKILL.md"))) {
         out.push(dir);
       }
     } catch {
@@ -176,10 +191,17 @@ export function planSkillInstall(
       seen.add(folderName);
       const linkPath = resolve(dest, folderName);
       const state = linkState(linkPath);
+      // Already correct means the link RESOLVES to the skill dir, not that its
+      // raw `readlink` string equals an absolute path. A relative link was
+      // therefore never "already correct": it was torn down and rebuilt on
+      // every single update, and the sibling planner reported it as drift.
+      const resolvesToSkill =
+        state.kind === "symlink" &&
+        resolve(dest, state.target) === resolve(skillDir);
       const action: SkillLinkAction["action"] =
         state.kind === "absent"
           ? "created"
-          : state.kind === "symlink" && state.target === skillDir
+          : resolvesToSkill
             ? "skipped"
             : state.kind === "symlink"
               ? "replaced"
@@ -199,3 +221,159 @@ export function planSkillInstall(
   actions.push(...planStaleLinkPrunes(dest, seen));
   return actions;
 }
+
+/**
+ * One planned link action in a HARNESS skills directory (layer 2).
+ *
+ * Layer 1 (`<installedSkillsDir>/<name>` → the package's folder) is what
+ * {@link planSkillInstall} owns. This is the layer above it: the links inside
+ * `~/.claude/skills` and `~/.agents/skills` that point AT layer 1 — a link to a
+ * link — and that `setup skills` owns.
+ */
+export interface HarnessLinkAction {
+  readonly target: string;
+  readonly linkPath: string;
+  readonly action: "created" | "replaced" | "pruned";
+  readonly folderName: string;
+  /** The harness directory's display name, for the progress line. */
+  readonly dirName: string;
+  /**
+   * The target the link ALREADY holds, recorded only for a `replaced` action so
+   * its undo can put that link back. Without it the undo could only delete what
+   * the forward run created, which restores an ABSENT path — a state that never
+   * existed — instead of the link the run overwrote.
+   *
+   * Stored as `readlink` returned it, not resolved: a relative link is relative
+   * to its own directory, which for a candidate of `dir` is `dir` itself, so
+   * re-linking the raw value reproduces the link exactly as found.
+   */
+  readonly previousTarget?: string;
+}
+
+/**
+ * Plan the CONVERGE-ONLY refresh of the global scope's harness skill links.
+ *
+ * The reported bug lives here. `sources update` installed and pruned layer 1
+ * and stopped, so a new pack skill reached no harness directory until the user
+ * separately ran `setup skills`, and a dropped one left its layer-2 link
+ * dangling with nothing that would ever clear it. This closes the loop, under
+ * two rules that are the entire safety argument:
+ *
+ * 1. CONVERGE-ONLY. `dirs` are directories that already exist — this function
+ *    never creates one, and the caller composes no `mkdir`. A `sources update`
+ *    that materialised `~/.claude/skills` would be litter, and would silently
+ *    opt the user into linking they never asked for.
+ * 2. OWNERSHIP, by the SAME test `setup skills` uses. A path is this command's
+ *    to touch only when it holds a symlink resolving INSIDE one of the global
+ *    scope's roots (`withinAnyRoot`, a pure path-SEGMENT test that reads nothing
+ *    — so it still answers correctly after the layer-1 target is gone, which is
+ *    exactly the stale case). A real directory is a hand-installed skill; a
+ *    symlink pointing anywhere else is the user's own; a `<root>-backup/foo`
+ *    sibling is not "inside" despite sharing a string prefix. None is removed.
+ *
+ *    THE SET, NOT JUST THE INSTALLED ROOT, and that is what keeps precedence
+ *    true one layer up. A harness link left pointing at the BUNDLED snapshot
+ *    for a skill this update has just installed for real is owned, so it is
+ *    `replaced` onto the installed copy. Tested against the installed root
+ *    alone it read as "someone else's link" and was skipped — and the user who
+ *    deliberately ran `sources update` would have kept running the shipped copy.
+ *
+ * The plan is derived from the layer-1 plan rather than from a filesystem
+ * re-read, because at planning time the layer-1 writes have not happened yet:
+ * `surviving` is the post-update truth, and reading the disk would see the
+ * pre-update state. That is also why a surviving name always targets
+ * `roots[0]`: layer 1 is about to hold it, whether or not it does now.
+ *
+ * A RETIRED NAME IS NOT AUTOMATICALLY DEBRIS any more. The fallback roots
+ * (today: the bundled snapshot) are NOT written by this update, so their
+ * contents ARE readable at plan time — and a skill the packages dropped that
+ * the shipped snapshot still carries is still discoverable, still listed by
+ * `skill list`, and so still belongs in the harness directory. Such a link is
+ * RETARGETED onto the surviving root rather than pruned; only a name no root
+ * provides at all is deleted.
+ *
+ * @param dirs - The EXISTING global link directories.
+ * @param roots - The global scope's source roots in PRECEDENCE order.
+ *   `roots[0]` is the installed root (layer 1) every surviving name targets;
+ *   the rest are fallbacks a retired name may still resolve in. The whole set
+ *   is the ownership set.
+ * @param surviving - Folder names layer 1 will hold after this update.
+ * @param retired - Folder names layer 1 is pruning in this update.
+ * @returns The layer-2 actions, for the plan and its effects.
+ * @note Impure — lstats each candidate link path, and stats the fallback roots
+ *   for each retired name.
+ */
+export function planHarnessSkillLinks(
+  dirs: readonly { dir: string; name: string }[],
+  roots: readonly string[],
+  surviving: readonly string[],
+  retired: readonly string[],
+): HarnessLinkAction[] {
+  const dest = resolve(roots[0] as string);
+  /** The first FALLBACK root that still holds `folderName`, if any. */
+  const fallback = (folderName: string): string | undefined =>
+    roots
+      .slice(1)
+      .map((root) => resolve(root, folderName))
+      .find((candidate) => existsSync(candidate));
+  const out: HarnessLinkAction[] = [];
+  for (const { dir, name } of dirs) {
+    for (const folderName of surviving) {
+      const linkPath = resolve(dir, folderName);
+      const target = resolve(dest, folderName);
+      const state = linkState(linkPath);
+      if (state.kind === "other") continue; // A hand-placed entry — never ours.
+      if (state.kind === "absent") {
+        out.push({
+          target,
+          linkPath,
+          action: "created",
+          folderName,
+          dirName: name,
+        });
+        continue;
+      }
+      if (resolve(dir, state.target) === target) continue; // Already correct.
+      // A symlink pointing outside every scope root is the user's own link into
+      // their own checkout. Unplanned does not make it ours to replace.
+      if (!withinAnyRoot(roots, linkPath, state.target)) continue;
+      out.push({
+        target,
+        linkPath,
+        action: "replaced",
+        folderName,
+        dirName: name,
+        previousTarget: state.target,
+      });
+    }
+    for (const folderName of retired) {
+      const linkPath = resolve(dir, folderName);
+      const state = linkState(linkPath);
+      if (state.kind !== "symlink") continue;
+      if (!withinAnyRoot(roots, linkPath, state.target)) continue;
+      const surviving = fallback(folderName);
+      if (surviving !== undefined) {
+        // Dropped upstream, still shipped: retarget rather than delete. Already
+        // correct is nothing to do.
+        if (resolve(dir, state.target) === surviving) continue;
+        out.push({
+          target: surviving,
+          linkPath,
+          action: "replaced",
+          folderName,
+          dirName: name,
+          previousTarget: state.target,
+        });
+        continue;
+      }
+      out.push({
+        target: resolve(dir, state.target),
+        linkPath,
+        action: "pruned",
+        folderName,
+        dirName: name,
+      });
+    }
+  }
+  return out;
+}

package/src/capabilities/sources/runUpdate.ts

@@ -49,8 +49,12 @@ import {
   redactUrl,
   resolvePackage,
 } from "../../kernel/runtime/refs/index.js";
-import { installedSkillsDir } from "../skill/discover.js";
-import { planSkillInstall } from "./installSkills.js";
+// The global scope's EXISTING link directories, from the module that owns the
+// scope covenant — so `sources update` cannot drift away from what
+// `setup skills --global` links, or widen the scope on its own.
+import { existingGlobalSkillDirs } from "../setup/operations/setupSkills.js";
+import { globalSkillRoots, installedSkillsDir } from "../skill/discover.js";
+import { planHarnessSkillLinks, planSkillInstall } from "./installSkills.js";
 import type { SourcesUpdateData } from "./types.js";
 
 /** Generic-core prefixes; config `prefixes` merge over them (config wins). */
@@ -343,6 +347,45 @@ export async function buildUpdateTask(
       `Removing ${staleLinks.length} skill link(s) no longer provided by any package`,
     );
 
+  // Converge the GLOBAL scope (layer 2). Layer 1 above is the installed root;
+  // the harness directories link AT it, and until now nothing here touched
+  // them — a new pack skill reached no harness directory until the user
+  // separately ran `setup skills`, and a dropped one left a dangling link that
+  // nothing would ever clear. That two-step was the reported bug.
+  //
+  // CONVERGE-ONLY, and this is a policy line, not an optimisation:
+  // `existingGlobalSkillDirs` returns only directories that ALREADY EXIST, and
+  // nothing below composes a `mkdir`. `sources update` is `mcp: {expose:true}`
+  // with `mutates: true` and `needsNetwork: true`, so creating directories here
+  // would mean an agent, over MCP, after a network fetch, conjuring
+  // `~/.claude/skills` into being and opting the user into linking they never
+  // asked for. Refresh what is there; never bring a directory into existence.
+  //
+  // Ownership is the SAME `withinAnyRoot` test `setup skills` applies, over the
+  // SAME root set (`globalSkillRoots`), so a real directory, a still-resolving
+  // link into the user's own checkout, and a `<root>-backup/foo` sibling are all
+  // left exactly as found — while a link still pointing at the BUNDLED snapshot
+  // for a skill this update just installed is ours, and is moved onto it.
+  const harnessPlan = planHarnessSkillLinks(
+    await existingGlobalSkillDirs(runtime.cwd),
+    globalSkillRoots(),
+    skillPlan
+      .filter((link) => link.action !== "pruned")
+      .map((link) => link.folderName),
+    staleLinks.map((link) => link.folderName),
+  );
+  const harnessLinks = harnessPlan.filter((link) => link.action !== "pruned");
+  const harnessStale = harnessPlan.filter((link) => link.action === "pruned");
+  if (harnessLinks.length > 0)
+    report?.(
+      `Linking ${harnessLinks.length} skill(s) into your harness folders`,
+    );
+  if (harnessStale.length > 0)
+    report?.(`Removing ${harnessStale.length} stale harness skill link(s)`);
+  if (verbose)
+    for (const link of harnessPlan)
+      report?.(`  ${link.action} ${link.folderName} in ${link.dirName}`);
+
   report?.(`Pointing ${runtime.cwd} at pack ${built.contentHash.slice(0, 12)}`);
   return gen(function* () {
     yield* $(writeFile(path, built.contentHash, { undo }));
@@ -376,6 +419,39 @@ export async function buildUpdateTask(
         }),
       );
     }
+    // Layer 2, in the same Task and so under the same `--undo`. Still no
+    // `mkdir`: every directory here was proven to exist at plan time, and
+    // creating one is the thing converge-only exists to forbid.
+    for (const link of harnessLinks) {
+      // A `created` link undoes by deletion — absent IS the state it replaced.
+      // A `replaced` one does not: the path held a link, and the delete above
+      // carries no undo of its own, so deleting what the symlink created would
+      // leave the path ABSENT rather than pointing where it pointed before.
+      // Its undo is therefore the same delete-then-relink shape the prunes
+      // below use, against the target detection recorded — and it clears the
+      // path first because undo collection MOCKS forward effects, so the link
+      // may still be there and `fs.symlink` refuses an existing path.
+      const previous = link.previousTarget;
+      const undoLink =
+        link.action === "replaced" && previous !== undefined
+          ? gen(function* () {
+              yield* $(deleteFile(link.linkPath));
+              yield* $(symlink(previous, link.linkPath));
+            })
+          : deleteFile(link.linkPath);
+      if (link.action === "replaced") yield* $(deleteFile(link.linkPath));
+      yield* $(symlink(link.target, link.linkPath, { undo: undoLink }));
+    }
+    for (const stale of harnessStale) {
+      yield* $(
+        deleteFile(stale.linkPath, {
+          undo: gen(function* () {
+            yield* $(deleteFile(stale.linkPath));
+            yield* $(symlink(stale.target, stale.linkPath));
+          }),
+        }),
+      );
+    }
     return data;
   });
 }

package/src/capabilities/sources/sources.test.ts

@@ -714,14 +714,25 @@ describe("sources update — installs package skills (U10)", () => {
     return pkg;
   }
 
+  let savedHome: string | undefined;
+  let home: string;
+
   beforeEach(() => {
     savedDataHome = process.env.XDG_DATA_HOME;
     dataHome = tmp("pragma-datahome-");
     process.env.XDG_DATA_HOME = dataHome;
+    // HOME is isolated because an update now converges the GLOBAL scope, and
+    // the global scope's link directories live under it. A test that read the
+    // real home would be writing into the developer's own harness folders.
+    savedHome = process.env.HOME;
+    home = tmp("pragma-home-");
+    process.env.HOME = home;
   });
   afterEach(() => {
     if (savedDataHome === undefined) delete process.env.XDG_DATA_HOME;
     else process.env.XDG_DATA_HOME = savedDataHome;
+    if (savedHome === undefined) delete process.env.HOME;
+    else process.env.HOME = savedHome;
   });
 
   it("symlinks a package skill into the installed root so `skill list` finds it", async () => {
@@ -920,6 +931,223 @@ describe("sources update — installs package skills (U10)", () => {
 
     expect(readdirSync(join(dataHome, "pragma", "skills"))).toEqual(["foo"]);
   });
+
+  it("sees a package that ships `skills/<name>` as a SYMLINK", async () => {
+    // `lstat().isDirectory()` reports the LINK, not the directory behind it, so
+    // a pnpm / monorepo / `file:` layout contributed nothing at all, silently.
+    const real = tmp("pragma-realskill-");
+    mkdirSync(join(real, "linked-skill"), { recursive: true });
+    writeFileSync(
+      join(real, "linked-skill", "SKILL.md"),
+      "---\nname: linked-skill\ndescription: Behind a link.\n---\n",
+    );
+    const pkg = filePackage();
+    mkdirSync(join(pkg, "skills"), { recursive: true });
+    symlinkSync(
+      join(real, "linked-skill"),
+      join(pkg, "skills", "linked-skill"),
+    );
+
+    const cwd = tmp("pragma-proj-");
+    await runTask(
+      await buildUpdateTask(
+        runtimeFor(cwd, [{ name: "pkg-a", source: `file://${pkg}` }]),
+      ),
+    );
+    expect(discoverSkills(cwd).map((s) => s.name)).toContain("linked-skill");
+  });
+});
+
+describe("sources update — converges the global scope (converge-only)", () => {
+  let savedDataHome: string | undefined;
+  let savedHome: string | undefined;
+  let dataHome: string;
+  let home: string;
+
+  /** A local package that also ships `skills/<name>/SKILL.md`. */
+  function skillPackage(...skillNames: string[]): string {
+    const pkg = filePackage();
+    for (const skillName of skillNames) {
+      const skillDir = join(pkg, "skills", skillName);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(
+        join(skillDir, "SKILL.md"),
+        `---\nname: ${skillName}\ndescription: From a package.\n---\nBody.`,
+      );
+    }
+    return pkg;
+  }
+
+  beforeEach(() => {
+    savedDataHome = process.env.XDG_DATA_HOME;
+    savedHome = process.env.HOME;
+    dataHome = tmp("pragma-datahome-");
+    home = tmp("pragma-home-");
+    process.env.XDG_DATA_HOME = dataHome;
+    process.env.HOME = home;
+  });
+  afterEach(() => {
+    if (savedDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = savedDataHome;
+    if (savedHome === undefined) delete process.env.HOME;
+    else process.env.HOME = savedHome;
+  });
+
+  /** The installed root (layer 1). */
+  const installedRoot = (): string => join(dataHome, "pragma", "skills");
+  /** The cross-client harness dir (layer 2), created so it is convergeable. */
+  const harnessDir = (): string => {
+    const dir = join(home, ".agents", "skills");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  };
+  /** Retire a skill from the package IN PLACE — how a pack upgrade drops one. */
+  const dropSkill = (pkg: string, name: string): void => {
+    rmSync(join(pkg, "skills", name), { recursive: true, force: true });
+  };
+  const update = async (pkg: string, cwd: string): Promise<void> => {
+    await runTask(
+      await buildUpdateTask(
+        runtimeFor(cwd, [{ name: "design-system", source: `file://${pkg}` }]),
+      ),
+    );
+  };
+
+  it("a NEW pack skill reaches the harness folder in one step", async () => {
+    // The two-step: `sources update` wrote layer 1 and stopped, so a new pack
+    // skill appeared in no harness directory until the user separately ran
+    // `setup skills`.
+    const dir = harnessDir();
+    await update(skillPackage("added"), tmp("pragma-proj-"));
+    expect(readlinkSync(join(dir, "added"))).toBe(
+      join(installedRoot(), "added"),
+    );
+  });
+
+  it("a DROPPED pack skill has its harness link removed (the reported case)", async () => {
+    const dir = harnessDir();
+    const cwd = tmp("pragma-proj-");
+    const pkg = skillPackage("kept", "dropped");
+    // 0.1.2 shipped both...
+    await update(pkg, cwd);
+    expect(existsSync(join(dir, "dropped"))).toBe(true);
+    // ...0.2.0 drops one, in place, so the layer-1 link now dangles and its
+    // prune fires. Layer 2 must follow it.
+    dropSkill(pkg, "dropped");
+    await update(pkg, cwd);
+    // `existsSync` FOLLOWS a link, so a dangling one false-negatives — lstat.
+    expect(() => lstatSync(join(dir, "dropped"))).toThrow();
+    expect(readlinkSync(join(dir, "kept"))).toBe(join(installedRoot(), "kept"));
+  });
+
+  it("CONVERGE-ONLY: a machine that never ran `setup skills` gets no new dirs", async () => {
+    // The operator ruling, and the reason this is safe to expose over MCP:
+    // `sources update` is `mutates: true` AND `expose: true`, so an agent must
+    // not be able to make it conjure `~/.claude/skills` into existence.
+    await update(skillPackage("added"), tmp("pragma-proj-"));
+    expect(existsSync(join(home, ".agents"))).toBe(false);
+    expect(existsSync(join(home, ".claude"))).toBe(false);
+    // Layer 1 is still installed — only the scope convergence stood down.
+    expect(existsSync(join(installedRoot(), "added"))).toBe(true);
+  });
+
+  it("SAFETY: a real dir, a resolving user link and a `-backup` sibling all survive", async () => {
+    const dir = harnessDir();
+    const cwd = tmp("pragma-proj-");
+    const pkg = skillPackage("kept", "dropped");
+    await update(pkg, cwd);
+
+    // A hand-placed skill directory, at a name the pack also provides.
+    const real = join(dir, "hand-placed");
+    mkdirSync(real, { recursive: true });
+    writeFileSync(join(real, "SKILL.md"), "hand-placed\n");
+    // Someone's own link into their own checkout.
+    const mine = join(tmp("pragma-mine-"), "mine");
+    mkdirSync(mine, { recursive: true });
+    symlinkSync(mine, join(dir, "mine"));
+    // A link into a SIBLING whose name merely EXTENDS the root's — the old
+    // string-prefix bug classified this as ours and deleted it.
+    const backup = join(`${installedRoot()}-backup`, "dropped");
+    mkdirSync(backup, { recursive: true });
+    rmSync(join(dir, "dropped"));
+    symlinkSync(backup, join(dir, "dropped"));
+
+    dropSkill(pkg, "dropped"); // retired upstream
+    await update(pkg, cwd);
+
+    expect(readFileSync(join(real, "SKILL.md"), "utf-8")).toBe("hand-placed\n");
+    expect(readlinkSync(join(dir, "mine"))).toBe(mine);
+    // Not ours despite sharing a string prefix with the installed root.
+    expect(readlinkSync(join(dir, "dropped"))).toBe(backup);
+  });
+
+  it("is idempotent — a second update re-links nothing", async () => {
+    const dir = harnessDir();
+    const cwd = tmp("pragma-proj-");
+    const pkg = skillPackage("stable");
+    await update(pkg, cwd);
+    const before = lstatSync(join(dir, "stable")).mtimeMs;
+    await update(pkg, cwd);
+    expect(lstatSync(join(dir, "stable")).mtimeMs).toBe(before);
+  });
+
+  it("is reversible — undo RESTORES a replaced harness link's old target", async () => {
+    // The `created` case below undoes by deletion, because absent is the state
+    // it replaced. A `replaced` link's is not: the path already held a link,
+    // the forward delete carries no undo, and deleting what the symlink
+    // created therefore left the path ABSENT — a state it was never in. So the
+    // undo must delete-then-relink the target detection recorded.
+    const dir = harnessDir();
+    const cwd = tmp("pragma-proj-");
+    const pkg = skillPackage("kept", "other");
+    await update(pkg, cwd);
+
+    // Drift the harness link for `kept` onto a SIBLING inside the installed
+    // root: still owned (so the next plan is entitled to fix it), wrong target
+    // (so the plan calls it `replaced`).
+    const link = join(dir, "kept");
+    const previous = join(installedRoot(), "other");
+    rmSync(link);
+    symlinkSync(previous, link);
+
+    // Two tasks off the SAME pre-run state: `gen` drives one iterator, so a
+    // task that has been run forward cannot also be walked for its undos, and
+    // re-planning after the forward run would see a converged tree with
+    // nothing left to reverse.
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    const forward = await buildUpdateTask(runtime);
+    const reverse = await buildUpdateTask(runtime);
+
+    await runTask(forward);
+    expect(readlinkSync(link)).toBe(join(installedRoot(), "kept")); // repointed
+
+    const { runUndo } = await import("@canonical/task/node");
+    await runUndo(reverse);
+
+    // `existsSync` FOLLOWS a link and would false-negative on a dangling one —
+    // and, more to the point here, an existence check alone passes the buggy
+    // shape too. The TARGET is the assertion.
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(link)).toBe(previous);
+  });
+
+  it("is reversible — undo removes the harness link it created", async () => {
+    const dir = harnessDir();
+    const { runUndo } = await import("@canonical/task/node");
+    await runUndo(
+      await buildUpdateTask(
+        runtimeFor(tmp("pragma-proj-"), [
+          {
+            name: "design-system",
+            source: `file://${skillPackage("added")}`,
+          },
+        ]),
+      ),
+    );
+    expect(existsSync(join(dir, "added"))).toBe(false);
+  });
 });
 
 describe("sources status — entityCount from the manifest (A10)", () => {

package/src/capabilities/sources/update.verb.ts

@@ -25,12 +25,12 @@ export const updateVerb: VerbSpec<
 > = {
   path: ["sources", "update"],
   summary: "Resolve configured packs and build the local store from them.",
-  doc: "Resolves each configured pack (git/file/npm) and builds one content-addressed pack, which every later boot reads with no network access. Pin a revision by putting a commit SHA in the pack's source ref.",
+  doc: "Resolves each configured pack (git, file, or npm) and builds one local pack from them, which every later run reads without touching the network. Put a commit SHA in a pack source ref to pin it to that revision.",
   params: [
     {
       kind: "boolean",
       name: "skipInvalid",
-      doc: "Skip sources that fail to parse (warning about each) and build from the rest, instead of failing the whole update.",
+      doc: "Build from the sources that parse, warning about each one that does not, instead of failing the whole update.",
     },
   ],
   output: { formatters: updateFormatters },
@@ -38,7 +38,7 @@ export const updateVerb: VerbSpec<
     { cmd: `${BIN_NAME} sources update`, note: "resolve and build" },
     {
       cmd: `${BIN_NAME} sources update --skip-invalid`,
-      note: "build from the parseable sources, warning about any dropped",
+      note: "build from the sources that parse, and name the ones dropped",
     },
   ],
   capability: {

package/src/capabilities/surface.test.ts

@@ -257,8 +257,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
   it("emits setup as a mixed self+sub noun (self is a tool, sub-verbs are mcp:false)", () => {
     // The one covenant noun both directly runnable AND with sub-verbs. The self
     // verb is the `setup` tool; the four installers are CLI-only (mcp:false).
-    // The band-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
-    // flags; completions/lsp are single-band installers with no scope.
+    // The scope-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
+    // flags; completions/lsp are single-scope installers with no scope.
     expect(emitted.nouns.setup?.verbs).toEqual([
       {
         v: "setup",