docspack 0.3.0 → 1.0.0

package/src/artifact.ts

@@ -0,0 +1,110 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { IndexedChunk } from "./db.js";
+import { chunkId, estimateTokens, packageId } from "./spec.js";
+import { declarationsIn, type ExportedSymbol, readPublicSurface } from "./surface.js";
+
+/**
+ * A package derived from an installed library rather than published by its author.
+ *
+ * Half of a well-documented library's exported names are mentioned nowhere in its own
+ * documentation (see `docs/design/beyond-retrieval.md`), and almost all of them are declared in
+ * the type declarations sitting in `node_modules`. Those declarations are the answer a
+ * documentation site cannot serve, because the site is not the artifact.
+ */
+export interface ArtifactPackage {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly chunks: readonly IndexedChunk[];
+  /**
+   * Every exported name, mapped to the chunk carrying its declaration — or to an empty string
+   * when the package exports the name without declaring it anywhere this can read.
+   *
+   * Recording those too is what keeps `changed` honest: a name re-exported from a file with no
+   * declaration in it would otherwise look like a name the release removed.
+   */
+  readonly symbols: ReadonlyMap<string, string>;
+}
+
+/** Beyond this a package is generated machinery, and indexing it would drown the prose. */
+const MAX_SYMBOLS = 2000;
+
+/** How much of a declaration is carried. Long enough for a signature, short enough to rank. */
+const DECLARATION_LIMIT = 400;
+
+/**
+ * Derives chunks from an installed library: one per exported name, carrying the import a caller
+ * writes and the declaration as the installed build states it.
+ *
+ * Returns nothing when the package ships no type declarations. That is the common case across a
+ * dependency tree and is not a problem worth reporting.
+ */
+export async function readArtifact(dir: string): Promise<ArtifactPackage | undefined> {
+  const surface = await readPublicSurface(dir);
+  if (surface === undefined || surface.name.length === 0 || surface.version.length === 0) {
+    return undefined;
+  }
+
+  const id = packageId(surface.name, surface.version);
+  const declared = new Map<string, Map<string, string>>();
+  const chunks: IndexedChunk[] = [];
+  const symbols = new Map<string, string>();
+
+  for (const symbol of surface.symbols.values()) {
+    symbols.set(symbol.name, "");
+    if (chunks.length >= MAX_SYMBOLS) continue;
+
+    let declarations = declared.get(symbol.file);
+    if (declarations === undefined) {
+      try {
+        declarations = declarationsIn(
+          await readFile(join(dir, symbol.file), "utf8"),
+          DECLARATION_LIMIT,
+        );
+      } catch {
+        declarations = new Map();
+      }
+      declared.set(symbol.file, declarations);
+    }
+
+    const declaration = declarations.get(symbol.name);
+    // A name that only appears in an `export { … }` list has no declaration to show. The import
+    // line alone would say nothing the name did not already say, so it is left out.
+    if (declaration === undefined) continue;
+
+    const content = render(symbol, declaration);
+    const chunk = chunkId(id, symbol.name);
+    chunks.push({
+      chunkId: chunk,
+      filePath: symbol.file,
+      tokens: estimateTokens(content),
+      content,
+      // The name is the tag, and tags are weighted 3× against prose in the ranking.
+      tags: [symbol.name, symbol.from],
+    });
+    symbols.set(symbol.name, chunk);
+  }
+
+  if (symbols.size === 0) return undefined;
+  return { id, name: surface.name, version: surface.version, chunks, symbols };
+}
+
+/**
+ * What an agent receives. The import line is first because it is the part a caller gets wrong
+ * most often — a name that exists at a subpath nobody guessed is the same failure as a name that
+ * does not exist.
+ */
+function render(symbol: ExportedSymbol, declaration: string): string {
+  return [
+    `# ${symbol.name}`,
+    "",
+    `Declared by \`${symbol.from}\`. This is the installed build's own declaration, not prose.`,
+    "",
+    "```ts",
+    `import { ${symbol.name} } from "${symbol.from}";`,
+    "",
+    declaration.trim(),
+    "```",
+  ].join("\n");
+}

package/src/build.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { Dirent } from "node:fs";
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
@@ -15,7 +16,9 @@ import {
   estimateTokens,
   LLMS_DIR,
   MANIFEST_FILE,
+  type PackageManifest,
   parseDocumentedLibrary,
+  parseManifest,
   serializeManifest,
 } from "./spec.js";
 import { STOPWORDS } from "./stopwords.js";
@@ -64,6 +67,8 @@ interface SourceDocument {
   readonly atomic?: boolean;
   readonly tags?: readonly string[];
   readonly entities?: readonly string[];
+  /** Libraries this document describes, when that is narrower than the package's `documents`. */
+  readonly documents?: readonly string[];
 }
 
 const DEFAULT_MAX_CHUNK_TOKENS = 800;
@@ -94,9 +99,12 @@ export async function buildPackage(input: BuildOptions): Promise<BuildResult> {
       { hint: "A chunk cannot be required to be bigger than it is allowed to be." },
     );
   }
-  const { chunks, files } = chunkDocuments(documents, maxTokens, minTokens);
+  const { chunks, files, collisions } = chunkDocuments(documents, maxTokens, minTokens);
 
   const llmsDir = join(options.out, LLMS_DIR);
+  // Read before the payload is removed: a chunk id is what `feedback add --chunk` pins and what
+  // an answer is headed with, so a rebuild that renames one silently orphans both.
+  warnings.push(...idWarnings(collisions, await departedChunkIds(llmsDir, chunks)));
   await rm(llmsDir, { recursive: true, force: true });
   await mkdir(join(llmsDir, CHUNKS_DIR), { recursive: true });
 
@@ -248,6 +256,7 @@ async function collectFromDirectory(dir: string): Promise<SourceDocument[]> {
       origin: relativePath,
       text: cleaned.text,
       ...(cleaned.tags.length === 0 ? {} : { tags: cleaned.tags }),
+      ...(cleaned.documents.length === 0 ? {} : { documents: cleaned.documents }),
     });
   }
   return documents;
@@ -273,6 +282,13 @@ async function collectFromSource(
 
   const documents: SourceDocument[] = [];
   const links = fetchableLinks(parsed).slice(0, options.pages ?? 50);
+  // Two links can name the same document. `fetchableLinks` already drops a repeated URL and a
+  // repeated fragment, but a site whose index links anchors as a query — `/v4?id=codecs` — gets
+  // one entry per anchor, and each one fetches the whole page again. Left alone that packages
+  // the same text dozens of times: an index mostly made of duplicates, which is slower to search
+  // and ranks worse, because copies of one page crowd out the rest of the corpus.
+  const seen = new Set<string>();
+  let duplicates = 0;
 
   for (const link of links) {
     options.onProgress?.(`fetching ${link.url}`);
@@ -285,6 +301,12 @@ async function collectFromSource(
         warnings.push(`skipped ${link.url}: document was empty`);
         continue;
       }
+      const fingerprint = createHash("sha256").update(text).digest("hex");
+      if (seen.has(fingerprint)) {
+        duplicates += 1;
+        continue;
+      }
+      seen.add(fingerprint);
       documents.push({
         title: link.title.length > 0 ? link.title : (firstHeading(text) ?? link.url),
         origin: link.url,
@@ -298,6 +320,11 @@ async function collectFromSource(
     }
   }
 
+  if (duplicates > 0) {
+    warnings.push(
+      `skipped ${duplicates} of ${links.length} linked documents whose text repeated one already packaged`,
+    );
+  }
   if (fetchableLinks(parsed).length > links.length) {
     warnings.push(
       `packaged ${links.length} of ${fetchableLinks(parsed).length} linked documents (raise with --pages)`,
@@ -427,9 +454,14 @@ function chunkDocuments(
   documents: readonly SourceDocument[],
   maxTokens: number,
   minTokens: number | undefined,
-): { chunks: ChunkSpec[]; files: { path: string; contents: string }[] } {
+): {
+  chunks: ChunkSpec[];
+  files: { path: string; contents: string }[];
+  collisions: string[];
+} {
   const chunks: ChunkSpec[] = [];
   const files: { path: string; contents: string }[] = [];
+  const collisions: string[] = [];
   const taken = new Set<string>();
 
   for (const document of documents) {
@@ -442,7 +474,10 @@ function chunkDocuments(
     for (const section of sections) {
       const directives = readDirectives(section.body);
       const body = withoutDuplicateHeading(directives.body, section.heading);
-      const id = uniqueId(chunkSlug(document.title, section.heading), taken);
+      const derived = chunkSlug(document.title, section.heading);
+      const id = uniqueId(derived, taken);
+      if (id !== derived) collisions.push(derived);
+      const libraries = directives.documents.length > 0 ? directives.documents : document.documents;
       const contents = `# ${section.heading}\n\n<!-- docspack: from ${document.origin} -->\n\n${body}\n`;
       const file = `${CHUNKS_DIR}/${id}.md`;
 
@@ -463,11 +498,59 @@ function chunkDocuments(
             ...extractEntities(body),
           ]),
         ],
+        ...(libraries === undefined || libraries.length === 0
+          ? {}
+          : { documents: libraries.map(parseDocumentedLibrary) }),
       });
     }
   }
 
-  return { chunks, files };
+  return { chunks, files, collisions };
+}
+
+/**
+ * The two ways a chunk id moves without anyone deciding it should. Both are reported as one
+ * line each, however many ids are involved: a large package collides in dozens of places, and a
+ * warning per id is a wall of text nobody reads.
+ */
+function idWarnings(collisions: readonly string[], gone: readonly string[]): string[] {
+  const warnings: string[] = [];
+  if (collisions.length > 0) {
+    warnings.push(
+      `${plural(collisions.length, "derived chunk id")} collided and ${collisions.length === 1 ? "was" : "were"} given a numeric suffix: ${list(collisions)} — which section keeps the bare id depends on the order the sources were read in`,
+    );
+  }
+  if (gone.length > 0) {
+    warnings.push(
+      `${plural(gone.length, "chunk id")} the previous build published ${gone.length === 1 ? "is" : "are"} gone: ${list(gone)} — recorded feedback and published links pinned to ${gone.length === 1 ? "it" : "them"} no longer resolve`,
+    );
+  }
+  return warnings;
+}
+
+const plural = (count: number, noun: string): string => `${count} ${noun}${count === 1 ? "" : "s"}`;
+
+const list = (ids: readonly string[]): string =>
+  `${ids.slice(0, 5).join(", ")}${ids.length > 5 ? `, and ${ids.length - 5} more` : ""}`;
+
+/**
+ * Chunk ids the payload on disk carries that this build does not, or nothing when there is no
+ * previous payload to compare with. An unreadable manifest is not a finding: `build` is what
+ * replaces it.
+ */
+async function departedChunkIds(llmsDir: string, chunks: readonly ChunkSpec[]): Promise<string[]> {
+  let previous: PackageManifest;
+  try {
+    previous = parseManifest(
+      JSON.parse(await readFile(join(llmsDir, MANIFEST_FILE), "utf8")),
+      `${LLMS_DIR}/${MANIFEST_FILE}`,
+    );
+  } catch {
+    return [];
+  }
+
+  const current = new Set(chunks.map((chunk) => chunk.id));
+  return previous.chunks.map((chunk) => chunk.id).filter((id) => !current.has(id));
 }
 
 /** One piece of a document, before it becomes a chunk. */
@@ -661,26 +744,36 @@ function matchAll(text: string, pattern: RegExp): string[] {
 }
 
 /** One authored override under a heading: `<!-- docspack: tags=grid,columns -->`. */
-const DIRECTIVE = /^[ \t]*<!--[ \t]*docspack:[ \t]*(tags|entities)[ \t]*=([^>]*?)-->[ \t]*$/gim;
+const DIRECTIVE =
+  /^[ \t]*<!--[ \t]*docspack:[ \t]*(tags|entities|documents)[ \t]*=([^>]*?)-->[ \t]*$/gim;
 
 /**
  * Reads per-section directives and removes them from the body. Front matter belongs to a whole
  * document, so a page of eighty sections cannot aim any one of them; this is that lever.
  */
-function readDirectives(body: string): { body: string; tags: string[]; entities: string[] } {
-  const tags: string[] = [];
-  const entities: string[] = [];
+function readDirectives(body: string): {
+  body: string;
+  tags: string[];
+  entities: string[];
+  documents: string[];
+} {
+  const collected: Record<string, string[]> = { tags: [], entities: [], documents: [] };
 
   const text = body.replace(DIRECTIVE, (_line, key: string, value: string) => {
     const values = value
       .split(",")
       .map((item) => item.trim())
       .filter((item) => item.length > 0);
-    (key.toLowerCase() === "tags" ? tags : entities).push(...values);
+    collected[key.toLowerCase()]?.push(...values);
     return "";
   });
 
-  return { body: text.replace(/\n{3,}/g, "\n\n").trim(), tags, entities };
+  return {
+    body: text.replace(/\n{3,}/g, "\n\n").trim(),
+    tags: collected.tags ?? [],
+    entities: collected.entities ?? [],
+    documents: collected.documents ?? [],
+  };
 }
 
 /**

package/src/changed.ts

@@ -0,0 +1,99 @@
+import { identifiers } from "./coverage.js";
+import type { Store } from "./db.js";
+import { discoverLibraries, discoverPackages } from "./discovery.js";
+import { DocspackError } from "./errors.js";
+import { packageId } from "./spec.js";
+
+export interface SurfaceChange {
+  readonly library: string;
+  readonly from: string;
+  readonly to: string;
+  /** Names the newer release exports that the older one did not. */
+  readonly added: readonly string[];
+  /** Names the older release exported that the newer one does not. */
+  readonly removed: readonly string[];
+  /**
+   * Added names that no documentation package installed here mentions. These are the ones a
+   * model cannot know: too new for its training data, and absent from what the vendor published.
+   */
+  readonly undocumented: readonly string[];
+}
+
+export interface ChangedOptions {
+  readonly cwd: string;
+  readonly store: Store;
+  /** Library name, optionally with the version to compare against: `hono` or `hono@4.0.0`. */
+  readonly library: string;
+}
+
+/**
+ * What changed in a library's exported surface between two versions in the store.
+ *
+ * Both versions come from the local index, never the network: the store is global, so a version
+ * indexed for another project on this machine is already here. Measured across two libraries,
+ * upgrades are overwhelmingly additive — hono 3.12.12 to 4.13.3 removed three names and added
+ * 243 — so the useful report is what exists now that an older release did not have.
+ */
+export async function changedSurface(options: ChangedOptions): Promise<SurfaceChange> {
+  const [name, requested] = split(options.library);
+
+  const installed = (await discoverLibraries(options.cwd)).find((library) => library.name === name);
+  const indexed = options.store.versionsOf(name).filter((pkg) => pkg.kind === "artifact");
+  if (indexed.length === 0) {
+    throw new DocspackError(`No version of ${name} is indexed`, {
+      hint:
+        installed === undefined
+          ? `${name} is not a dependency of this project.`
+          : "Run `docspack sync` to index the installed version, then ask again.",
+    });
+  }
+
+  const to = installed?.version ?? indexed[indexed.length - 1]?.version;
+  if (to === undefined) throw new DocspackError(`No version of ${name} is indexed`);
+
+  const others = indexed.map((pkg) => pkg.version).filter((version) => version !== to);
+  const from = requested ?? others[others.length - 1];
+  if (from === undefined) {
+    throw new DocspackError(`Only ${name}@${to} is indexed, so there is nothing to compare`, {
+      hint: "Index another version by running `docspack sync` in a project that installs it. The store is shared across projects on this machine.",
+    });
+  }
+  if (!options.store.hasPackage(packageId(name, from))) {
+    throw new DocspackError(`${name}@${from} is not in the store`, {
+      hint: `Indexed versions: ${indexed.map((pkg) => pkg.version).join(", ")}`,
+    });
+  }
+
+  const before = new Set(options.store.symbolsOf(packageId(name, from)));
+  const after = new Set(options.store.symbolsOf(packageId(name, to)));
+  const added = [...after].filter((symbol) => !before.has(symbol)).sort();
+  const removed = [...before].filter((symbol) => !after.has(symbol)).sort();
+
+  const documented = await documentedNames(options);
+  return {
+    library: name,
+    from,
+    to,
+    added,
+    removed,
+    undocumented: added.filter((symbol) => !documented.has(symbol)),
+  };
+}
+
+/** Every identifier any documentation package installed here mentions. */
+async function documentedNames(options: ChangedOptions): Promise<Set<string>> {
+  const names = new Set<string>();
+  for (const pkg of (await discoverPackages(options.cwd)).packages) {
+    for (const chunk of options.store.chunksOf(pkg.id)) {
+      for (const identifier of identifiers(chunk.content)) names.add(identifier);
+    }
+  }
+  return names;
+}
+
+/** `hono@4.0.0` into its parts, keeping a scope's leading `@` out of it. */
+function split(spec: string): [name: string, version: string | undefined] {
+  const at = spec.lastIndexOf("@");
+  if (at <= 0) return [spec, undefined];
+  return [spec.slice(0, at), spec.slice(at + 1)];
+}

package/src/cli.ts

@@ -3,6 +3,9 @@ import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { applyAgentSetup, planAgentSetup } from "./agent.js";
+import { changedSurface } from "./changed.js";
+import { measureCoverage } from "./coverage.js";
 import { defaultStorePath, Store, silenceSqliteWarning } from "./db.js";
 import { discoverPackages } from "./discovery.js";
 import { type DoctorReport, runDoctor } from "./doctor.js";
@@ -27,6 +30,11 @@ const OPTIONS = {
   cwd: { type: "string" },
   store: { type: "string" },
   force: { type: "boolean" },
+  "no-artifacts": { type: "boolean" },
+  coverage: { type: "boolean" },
+  hooks: { type: "boolean" },
+  mcp: { type: "boolean" },
+  feedback: { type: "boolean" },
   package: { type: "string", short: "p" },
   limit: { type: "string" },
   "max-tokens": { type: "string" },
@@ -141,6 +149,12 @@ function reportDoctor(report: DoctorReport, quiet: boolean): void {
 }
 
 /** 0 when the query was answered; otherwise which of the two empty answers this was. */
+/** Names, capped. A hundred identifiers on one line is a wall, and `--json` has them all. */
+function listed(names: readonly string[], limit = 20): string {
+  if (names.length <= limit) return names.join(", ");
+  return `${names.slice(0, limit).join(", ")} … and ${names.length - limit} more (--json for all)`;
+}
+
 function queryExit(result: QueryResult): number {
   if (result.hits.length > 0) return 0;
   return result.unindexed.length > 0 ? EXIT_NOT_INDEXED : EXIT_NO_MATCH;
@@ -201,6 +215,7 @@ async function main(argv: readonly string[]): Promise<number> {
           cwd,
           store,
           ...(values.force === true ? { force: true } : {}),
+          ...(values["no-artifacts"] === true ? { artifacts: false } : {}),
           ...(quiet || json
             ? {}
             : {
@@ -218,8 +233,11 @@ async function main(argv: readonly string[]): Promise<number> {
         for (const pkg of result.packages) {
           const mark = pkg.status === "indexed" ? green("+") : dim("=");
           const trust = pkg.trusted ? "" : ` ${yellow("(community)")}`;
+          // Declarations read from an installed build are not documentation somebody wrote, and
+          // the listing says so rather than letting them pass for it.
+          const kind = pkg.kind === "artifact" ? ` ${dim("(declarations)")}` : "";
           process.stdout.write(
-            `${mark} ${bold(pkg.id)}  ${pkg.chunks} chunks  ${dim(pkg.status)}${trust}\n`,
+            `${mark} ${bold(pkg.id)}  ${pkg.chunks} chunks  ${dim(pkg.status)}${trust}${kind}\n`,
           );
         }
         for (const problem of result.problems) {
@@ -343,17 +361,38 @@ async function main(argv: readonly string[]): Promise<number> {
       const store = openStore(values);
       try {
         const { packages, problems } = await discoverPackages(cwd);
-        const rows = packages.map((pkg) => ({
-          id: pkg.id,
-          name: pkg.name,
-          version: pkg.version,
-          chunks: pkg.manifest.chunks.length,
-          trusted: pkg.trusted,
-          indexed: store.hasPackage(pkg.id),
-        }));
+        const wantCoverage = values.coverage === true || json;
+        const rows = [];
+        for (const pkg of packages) {
+          rows.push({
+            id: pkg.id,
+            name: pkg.name,
+            version: pkg.version,
+            chunks: pkg.manifest.chunks.length,
+            trusted: pkg.trusted,
+            indexed: store.hasPackage(pkg.id),
+            ...(wantCoverage
+              ? {
+                  coverage: await measureCoverage({
+                    packageDir: pkg.dir,
+                    llmsDir: pkg.llmsDir,
+                    manifest: pkg.manifest,
+                    cwd,
+                  }),
+                }
+              : {}),
+          });
+        }
+
+        const declarations = store
+          .listPackages()
+          .filter((pkg) => pkg.kind === "artifact")
+          .map((pkg) => ({ id: pkg.id, chunks: store.countChunks(pkg.id) }));
 
         if (json) {
-          process.stdout.write(`${JSON.stringify({ packages: rows, problems }, null, 2)}\n`);
+          process.stdout.write(
+            `${JSON.stringify({ packages: rows, declarations, problems }, null, 2)}\n`,
+          );
           return 0;
         }
         if (rows.length === 0) {
@@ -363,6 +402,24 @@ async function main(argv: readonly string[]): Promise<number> {
           const state = row.indexed ? green("indexed") : yellow("not indexed");
           const trust = row.trusted ? "" : ` ${yellow("(community)")}`;
           process.stdout.write(`${bold(row.id)}  ${row.chunks} chunks  ${state}${trust}\n`);
+          for (const library of row.coverage?.libraries ?? []) {
+            const percent =
+              library.names === 0 ? 0 : Math.round((100 * library.documented) / library.names);
+            process.stdout.write(
+              `  ${dim(`documents ${library.documented}/${library.names} (${percent}%) of ${library.library}'s exports`)}\n`,
+            );
+            if (library.uncovered.length > 0) {
+              process.stdout.write(`  ${dim(`missing: ${library.uncovered.join(", ")}`)}\n`);
+            }
+          }
+        }
+        if (declarations.length > 0 && !quiet) {
+          const chunks = declarations.reduce((total, row) => total + row.chunks, 0);
+          process.stdout.write(
+            dim(
+              `\n${declarations.length} installed libraries indexed by declaration, ${chunks} names in all.\n`,
+            ),
+          );
         }
         for (const problem of problems) process.stderr.write(`${yellow("!")} ${problem}\n`);
         return 0;
@@ -371,6 +428,106 @@ async function main(argv: readonly string[]): Promise<number> {
       }
     }
 
+    case "agent": {
+      const [sub = "install"] = rest;
+      if (sub !== "install" && sub !== "check") {
+        throw new DocspackError(`Unknown subcommand "${sub}"`, {
+          hint: "Usage: docspack agent <install|check>",
+        });
+      }
+
+      const plan = await planAgentSetup({
+        cwd,
+        ...(values.feedback === true ? { feedback: true } : {}),
+        ...(values.hooks === true ? { hooks: true } : {}),
+        ...(values.mcp === true ? { mcp: true } : {}),
+      });
+      const pending = plan.files.filter((file) => file.status !== "unchanged");
+
+      if (json) {
+        process.stdout.write(
+          `${JSON.stringify({ files: plan.files.map(({ contents, ...rest }) => rest) }, null, 2)}\n`,
+        );
+        return sub === "check" && pending.length > 0 ? 1 : 0;
+      }
+
+      // `check` is the CI half: it writes nothing and fails when the wiring is missing or stale,
+      // which is the only way a pasted instruction ever gets noticed after it drifts.
+      if (sub === "check") {
+        for (const file of plan.files) {
+          const mark = file.status === "unchanged" ? green("ok") : yellow(file.status);
+          process.stdout.write(`${mark} ${file.path}\n`);
+        }
+        if (pending.length > 0) {
+          process.stderr.write(
+            `\n${yellow("!")} ${plural(pending.length, "file")} out of date. Run \`docspack agent install\`.\n`,
+          );
+        }
+        return pending.length > 0 ? 1 : 0;
+      }
+
+      if (values["dry-run"] === true) {
+        for (const file of plan.files) {
+          process.stdout.write(
+            `${file.status === "unchanged" ? dim("=") : green("+")} ${bold(file.path)}  ${dim(file.reason)}\n`,
+          );
+        }
+        return 0;
+      }
+
+      const written = await applyAgentSetup({ cwd }, plan);
+      for (const file of plan.files) {
+        const mark = file.status === "unchanged" ? dim("=") : green("+");
+        process.stdout.write(
+          `${mark} ${bold(file.path)}  ${dim(file.status === "unchanged" ? "unchanged" : file.reason)}\n`,
+        );
+      }
+      if (written.length > 0 && !quiet) {
+        process.stdout.write(
+          `\n${dim("Commit these. Every agent working in this repository can now read the")}\n${dim("documentation of its dependencies, without anyone being told the command exists.")}\n`,
+        );
+      }
+      return 0;
+    }
+
+    case "changed": {
+      const library = rest[0];
+      if (library === undefined) {
+        throw new DocspackError("Usage: docspack changed <library>[@version]");
+      }
+
+      const store = openStore(values);
+      try {
+        const change = await changedSurface({ cwd, store, library });
+        if (json) {
+          process.stdout.write(`${JSON.stringify(change, null, 2)}\n`);
+          return 0;
+        }
+
+        process.stdout.write(
+          `${bold(`${change.library} ${change.from} → ${change.to}`)}  ${dim(
+            `${change.added.length} added, ${change.removed.length} removed`,
+          )}\n`,
+        );
+        if (change.removed.length > 0) {
+          process.stdout.write(`\n${yellow("gone")}  ${listed(change.removed)}\n`);
+        }
+        if (change.added.length > 0) {
+          process.stdout.write(`\n${green("new")}   ${listed(change.added)}\n`);
+        }
+        if (change.undocumented.length > 0) {
+          process.stdout.write(
+            `\n${dim(
+              `${plural(change.undocumented.length, "new name")} that no documentation package here mentions:`,
+            )}\n${listed(change.undocumented)}\n`,
+          );
+        }
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
     case "verify": {
       const report = await verifyProject({
         cwd,