@williamthorsen/kb 0.6.2 → 0.8.0

package/dist/esm/cli/commands/check.d.ts

@@ -1,20 +1,42 @@
+/** The outcome of a command run: the exit code plus the streams to write. */
 export interface CommandOutput {
+    /** Process exit code: 0 clean, 1 error-severity findings, 2 usage/config error. */
     exitCode: 0 | 1 | 2;
     stdout: string;
     stderr: string;
 }
-export declare const CHECK_HELP = "Usage: kb check [paths...] [options]\n\nValidate notes in a knowledge base against its tag aliases and cross-note\nlink and path rules. With no path arguments, every note is checked.\nCross-note rules always resolve against the whole vault.\n\nTargeting (mutually exclusive):\n  [paths...]    Check only the notes matching the given glob patterns, files,\n                or directories. Quote globs so kb expands them itself. A\n                directory checks every note beneath it. A path that matches no\n                note is a usage error unless it names a real non-note.\n  --vs <ref>    Check only the notes changed between the working tree and the\n                merge-base of <ref> and HEAD: follows renames, includes\n                uncommitted edits, excludes deletions.\n\nOptions:\n  --kb <name>   Check the named store from the kb.yaml registry. Without it,\n                the nearest ancestor .kb/ directory is used.\n  --json        Emit a JSON report instead of human-readable output.\n  -h, --help    Show this help.\n\nExit codes:\n  0  no error-severity findings in the checked notes (warnings allowed)\n  1  one or more error-severity findings in the checked notes\n  2  usage error, unresolvable store or --vs ref, a path matching no note, or\n     malformed config or aliases\n";
+/** Usage text for `kb check`. */
+export declare const CHECK_HELP = "Usage: kb check [paths...] [options]\n\nValidate notes in a knowledge base against its tag aliases and cross-note\nlink and path rules. With no path arguments, every note is checked.\nCross-note rules always resolve against the whole store; a [[store:Target]]\nlink resolves against the store its prefix names in the kb.yaml registry.\n\nTargeting (mutually exclusive):\n  [paths...]    Check only the notes matching the given glob patterns, files,\n                or directories. Quote globs so kb expands them itself. A\n                directory checks every note beneath it. A path that matches no\n                note is a usage error unless it names a real non-note.\n  --vs <ref>    Check only the notes changed between the working tree and the\n                merge-base of <ref> and HEAD: follows renames, includes\n                uncommitted edits, excludes deletions.\n\nOptions:\n  --kb <name>   Check the named store from the kb.yaml registry. Without it,\n                the nearest ancestor .kb/ directory is used.\n  --json        Emit a JSON report instead of human-readable output.\n  -h, --help    Show this help.\n\nExit codes:\n  0  no error-severity findings in the checked notes (warnings allowed)\n  1  one or more error-severity findings in the checked notes\n  2  usage error, unresolvable store or --vs ref, a path matching no note, or\n     malformed config or aliases\n";
+/**
+ * Runs `kb check`: parses options, resolves the store, runs the shared `check`, and formats the report.
+ *
+ * Store resolution composes the package's own exports inline — `findKbRoot` for the default ancestor-walk and
+ * `tryLoadKbRegistry` for an explicit `--kb <name>`. The lookup is read-only, so a store's registry `readonly` flag
+ * is ignored. A malformed `.kb/config.yaml`/`tag-aliases.yaml` surfaces as a `KbLoaderError` from `check`, which maps
+ * to exit 2; any other error from `check` propagates to the caller as a real crash.
+ */
 export declare function runCheck(input: {
     argv: readonly string[];
     cwd: string;
     home?: string;
 }): Promise<CommandOutput>;
+/** Parsed `kb check` options. */
 interface CheckOptions {
+    /** Explicit store name from `--kb`, or `null` for ancestor-walk discovery. */
     kb: string | null;
+    /** Whether `--json` was supplied. */
     json: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
+    /** Positional glob/path/directory arguments selecting which notes to check; empty for a whole-vault run. */
     patterns: string[];
+    /** The `--vs` ref to diff against, or `null` when not supplied. */
     vs: string | null;
 }
+/**
+ * Parses `kb check` options. `--kb` and `--vs` each accept both the space (`--kb x`) and equals (`--kb=x`) forms;
+ * non-flag arguments are collected as selection patterns. Unknown flags, a missing `--kb`/`--vs` value, or combining
+ * patterns with `--vs` throw with a usage-style message.
+ */
 export declare function parseCheckArgs(argv: readonly string[]): CheckOptions;
 export {};

package/dist/esm/cli/commands/check.js

@@ -10,7 +10,8 @@ export const CHECK_HELP = `Usage: kb check [paths...] [options]
 
 Validate notes in a knowledge base against its tag aliases and cross-note
 link and path rules. With no path arguments, every note is checked.
-Cross-note rules always resolve against the whole vault.
+Cross-note rules always resolve against the whole store; a [[store:Target]]
+link resolves against the store its prefix names in the kb.yaml registry.
 
 Targeting (mutually exclusive):
   [paths...]    Check only the notes matching the given glob patterns, files,
@@ -55,7 +56,11 @@ export async function runCheck(input) {
     const store = resolved.store;
     let result;
     try {
-        result = await check({ kbRoot: store.path });
+        result = await check({
+            kbRoot: store.path,
+            cwd: input.cwd,
+            ...(input.home !== undefined && { home: input.home }),
+        });
     }
     catch (error) {
         if (isKbLoaderError(error)) {

package/dist/esm/cli/commands/create.d.ts

@@ -1,17 +1,35 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
-export declare const CREATE_HELP = "Usage: kb create [options]\n\nScaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.\n\nRegistering leaves the registry's entries in alphabetical order, preserving its comments and formatting.\n\nWhen the registry has no default knowledge base, the new store becomes the default.\nIf other knowledge bases are already registered, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  content/, content/events/\n\nOptions:\n  --description <text>  Description for the registry entry; cannot be combined with --no-register.\n  --name <name>         Registry name for the store. Defaults to the directory name.\n  --no-register         Scaffold without writing the kb.yaml registry entry.\n  -h, --help            Show this help.\n\nExit codes:\n  0  store created\n  2  usage error, an existing .kb/ in the directory, or an already-registered name\n";
+/** Usage text for `kb create`. */
+export declare const CREATE_HELP = "Usage: kb create [options]\n\nScaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.\n\nRegistering leaves the registry's entries in alphabetical order, preserving its comments and formatting.\n\nWhen the registry has no default knowledge base, the new store becomes the default.\nIf other knowledge bases are already registered, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .editorconfig          editor and formatter settings (width, indent, line endings)\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  .prettierrc.yaml       formatting configuration (commented)\n  content/, content/events/\n\nOptions:\n  --description <text>  Description for the registry entry; cannot be combined with --no-register.\n  --name <name>         Registry name for the store. Defaults to the directory name.\n  --no-register         Scaffold without writing the kb.yaml registry entry.\n  -h, --help            Show this help.\n\nExit codes:\n  0  store created\n  2  usage error, an existing .kb/ in the directory, or an already-registered name\n";
+/**
+ * Runs `kb create`: parses options, scaffolds a store in `cwd`, and (unless `--no-register`) registers it in the
+ * user-global `~/.agents/kb.yaml`. After registering, it ensures a default knowledge base: the new store becomes the
+ * default when none is set and it is the only KB; when other KBs already exist with no default, it delegates to
+ * `kb set-default`'s picker (or, with no `selectKb` on a non-interactive stdin, points the user there). A precondition
+ * failure from `create` — an existing `.kb/` or an already-registered name — maps to exit 2; a genuine I/O error
+ * propagates to the caller.
+ */
 export declare function runCreate(input: {
     argv: readonly string[];
     cwd: string;
     home?: string;
     selectKb?: SelectKbPrompt;
 }): Promise<CommandOutput>;
+/** Parsed `kb create` options. */
 interface CreateOptions {
+    /** Description from `--description`, or `null` to write the entry without one. */
     description: string | null;
+    /** Explicit registry name from `--name`, or `null` to default to the directory name. */
     name: string | null;
+    /** Whether `--no-register` was supplied. */
     noRegister: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
 }
+/**
+ * Parses `kb create` options. Each value-taking flag accepts both the space form and the equals form. Unknown flags, a
+ * missing value, or a description supplied alongside `--no-register` throw with a usage-style message.
+ */
 export declare function parseCreateArgs(argv: readonly string[]): CreateOptions;
 export {};

package/dist/esm/cli/commands/create.js

@@ -14,8 +14,10 @@ When the registry has no default knowledge base, the new store becomes the defau
 If other knowledge bases are already registered, you are prompted to choose one (or set it later with "kb set-default").
 
 Creates:
+  .editorconfig          editor and formatter settings (width, indent, line endings)
   .kb/config.yaml        check configuration (commented; defaults apply)
   .kb/tag-aliases.yaml   tag-alias map (empty)
+  .prettierrc.yaml       formatting configuration (commented)
   content/, content/events/
 
 Options:

package/dist/esm/cli/commands/scaffold.d.ts

@@ -0,0 +1,30 @@
+import type { CommandOutput } from './check.js';
+/** Usage text for `kb scaffold`. */
+export declare const SCAFFOLD_HELP = "Usage: kb scaffold [options]\n\nWrite into an existing knowledge base any canonical file that it lacks, so a store\ncreated before a given file existed can acquire it. An existing file is left\nuntouched unless --force is given.\n\nWrites:\n  .editorconfig          editor and formatter settings (width, indent, line endings)\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  .prettierrc.yaml       formatting configuration (commented)\n  content/, content/events/\n\n.kb/taxonomy.yaml is not part of this set: \"kb taxonomy init\" derives it from\nthe notes that the store already holds. Use \"kb create\" to make a new store.\n\nOptions:\n  --force       Replace an existing canonical file with a fresh seed. A\n                directory has no content to replace and is left as it is.\n  --kb <name>   Use the named store from the kb.yaml registry. Without it, the\n                nearest ancestor .kb/ directory is used.\n  -h, --help    Show this help.\n\nExit codes:\n  0  every canonical file is present, whether it was written or already there\n  2  usage error, unresolvable store, a store marked readonly in kb.yaml, or a\n     resolved path holding no .kb/\n";
+/**
+ * Runs `kb scaffold`: parses options, resolves the store, and writes the canonical files it lacks.
+ *
+ * Store resolution matches `kb check`. A store the registry marks `readonly` is refused, as `kb taxonomy init` does.
+ * A resolved path holding no `.kb/` is refused too: the command back-fills a store rather than creating one, and a
+ * registry entry names a path without proving a store is there.
+ */
+export declare function runScaffold(input: {
+    argv: readonly string[];
+    cwd: string;
+    home?: string;
+}): Promise<CommandOutput>;
+/** Parsed `kb scaffold` options. */
+interface ScaffoldOptions {
+    /** Whether `--force` was supplied. */
+    force: boolean;
+    /** Whether `--help`/`-h` was supplied. */
+    help: boolean;
+    /** Explicit store name from `--kb`, or `null` for ancestor-walk discovery. */
+    kb: string | null;
+}
+/**
+ * Parses `kb scaffold` options. `--kb` accepts both the space (`--kb x`) and equals (`--kb=x`) forms. An unknown flag,
+ * a positional argument, or a missing `--kb` value throws with a usage-style message.
+ */
+export declare function parseScaffoldArgs(argv: readonly string[]): ScaffoldOptions;
+export {};

package/dist/esm/cli/commands/scaffold.js

@@ -0,0 +1,108 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { directoryExists } from "../../filesystem/exists.js";
+import { KB_DIR, resolveKbDir } from "../../layout/index.js";
+import { scaffold } from "../../scaffold/scaffold.js";
+import { takeInlineValue, takeValue } from "../parse-flag-value.js";
+import { resolveStore } from "../resolve-store.js";
+export const SCAFFOLD_HELP = `Usage: kb scaffold [options]
+
+Write into an existing knowledge base any canonical file that it lacks, so a store
+created before a given file existed can acquire it. An existing file is left
+untouched unless --force is given.
+
+Writes:
+  .editorconfig          editor and formatter settings (width, indent, line endings)
+  .kb/config.yaml        check configuration (commented; defaults apply)
+  .kb/tag-aliases.yaml   tag-alias map (empty)
+  .prettierrc.yaml       formatting configuration (commented)
+  content/, content/events/
+
+.kb/taxonomy.yaml is not part of this set: "kb taxonomy init" derives it from
+the notes that the store already holds. Use "kb create" to make a new store.
+
+Options:
+  --force       Replace an existing canonical file with a fresh seed. A
+                directory has no content to replace and is left as it is.
+  --kb <name>   Use the named store from the kb.yaml registry. Without it, the
+                nearest ancestor .kb/ directory is used.
+  -h, --help    Show this help.
+
+Exit codes:
+  0  every canonical file is present, whether it was written or already there
+  2  usage error, unresolvable store, a store marked readonly in kb.yaml, or a
+     resolved path holding no ${KB_DIR}/
+`;
+export async function runScaffold(input) {
+    let options;
+    try {
+        options = parseScaffoldArgs(input.argv);
+    }
+    catch (error) {
+        return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${describeError(error)}\n${SCAFFOLD_HELP}` };
+    }
+    if (options.help) {
+        return { exitCode: 0, stdout: SCAFFOLD_HELP, stderr: '' };
+    }
+    const resolved = await resolveStore({
+        explicitKb: options.kb,
+        cwd: input.cwd,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (!resolved.ok) {
+        return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${resolved.message}\n` };
+    }
+    const store = resolved.store;
+    const label = store.name ?? store.path;
+    if (resolved.readonly) {
+        return buildRefusal(`knowledge base "${label}" is marked readonly in kb.yaml; scaffold is refused`);
+    }
+    if (!(await directoryExists(resolveKbDir(store.path)))) {
+        return buildRefusal(`no ${KB_DIR}/ directory at ${store.path}; run "kb create" to make a store there`);
+    }
+    const entries = await scaffold({ storePath: store.path, force: options.force });
+    return { exitCode: 0, stdout: formatScaffolded(store, entries), stderr: '' };
+}
+export function parseScaffoldArgs(argv) {
+    let force = false;
+    let help = false;
+    let kb = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--force') {
+            force = true;
+            continue;
+        }
+        if (arg === '--kb') {
+            kb = takeValue(argv, index, '--kb');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--kb=')) {
+            kb = takeInlineValue(arg, '--kb=');
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`unknown flag: ${arg}`);
+        }
+        throw new Error(`unexpected argument: ${arg}`);
+    }
+    return { force, help, kb };
+}
+const ACTION_WIDTH = 8;
+function buildRefusal(message) {
+    return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${message}\n` };
+}
+function formatScaffolded(store, entries) {
+    const named = store.name === null ? '' : ` "${store.name}"`;
+    const lines = [`Scaffolded knowledge base${named} at ${store.path}`];
+    for (const entry of entries) {
+        lines.push(`  ${entry.action.padEnd(ACTION_WIDTH)} ${entry.path}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/esm/cli/commands/set-default.d.ts

@@ -1,15 +1,30 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
+/** Usage text for `kb set-default`. */
 export declare const SET_DEFAULT_HELP = "Usage: kb set-default [name] [options]\n\nSet, clear, or interactively choose the user-global default knowledge base \u2014\nthe top-level default_kb pointer in ~/.agents/kb.yaml.\n\n  kb set-default <name>   Set default_kb to the named registered KB.\n  kb set-default --none   Clear default_kb.\n  kb set-default          List the registered KBs and prompt for a choice\n                          (including a \"(none)\" option to clear).\n\nOptions:\n  --none        Clear the default knowledge base.\n  -h, --help    Show this help.\n\nExit codes:\n  0  default set or cleared, or the selection was cancelled\n  2  usage error, an unregistered name, no registered KBs, or no name supplied\n     when stdin is not interactive\n";
+/**
+ * Runs `kb set-default`: sets, clears, or interactively selects the user-global `default_kb`. Resolution reads the
+ * user-global registry only (no project overlay), so the chosen default resolves in every project context. The picker
+ * is injected via `selectKb`, keeping the dispatcher free of terminal I/O; its absence means stdin is non-interactive,
+ * making the no-argument form a usage error rather than a hang.
+ */
 export declare function runSetDefault(input: {
     argv: readonly string[];
     home?: string;
     selectKb?: SelectKbPrompt;
 }): Promise<CommandOutput>;
+/** Parsed `kb set-default` options. */
 interface SetDefaultOptions {
+    /** The positional KB name, or `null` when none was supplied (interactive form). */
     name: string | null;
+    /** Whether `--none` was supplied. */
     none: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
 }
+/**
+ * Parses `kb set-default` options. At most one positional name is accepted; `--none` clears. A name combined with
+ * `--none`, a second positional, or an unknown flag throws with a usage-style message.
+ */
 export declare function parseSetDefaultArgs(argv: readonly string[]): SetDefaultOptions;
 export {};

package/dist/esm/cli/commands/taxonomy.d.ts

@@ -1,15 +1,33 @@
 import type { CommandOutput } from './check.js';
+/** Usage text for `kb taxonomy`. */
 export declare const TAXONOMY_HELP = "Usage: kb taxonomy init [options]\n\nDerive a starting taxonomy from the notes a knowledge base already holds, so a\ntaxonomy can be introduced to a populated store without every folder reporting\nas undeclared. Every folder holding notes is declared, along with each of its\nancestors, under \"provisional:\" with no description: the command cannot invent\ndescriptions, and provisional already means \"declared, not yet reviewed\".\n\nOptions:\n  --kb <name>   Use the named store from the kb.yaml registry. Without it, the\n                nearest ancestor .kb/ directory is used.\n  --merge       Add only the domains an existing taxonomy does not declare.\n                Without it, a store that already has a taxonomy is left\n                untouched.\n  -h, --help    Show this help.\n\nExit codes:\n  0  the taxonomy was written, or already declared every derived domain\n  2  usage error, unresolvable store, a store marked readonly in kb.yaml,\n     malformed config or taxonomy, or an existing taxonomy without --merge\n";
+/**
+ * Runs `kb taxonomy`: parses options, resolves the store, derives the domains its notes imply, and declares them.
+ *
+ * The derivation reads the same enumeration `kb check` does, so a store back-filled by this command reports no
+ * taxonomy drift. A store the registry marks `readonly` is refused, matching `kb-curate --apply`. A malformed
+ * `.kb/config.yaml` or `.kb/taxonomy.yaml` surfaces as a `KbLoaderError` and maps to exit 2; any other error
+ * propagates to the caller as a real crash.
+ */
 export declare function runTaxonomy(input: {
     argv: readonly string[];
     cwd: string;
     home?: string;
 }): Promise<CommandOutput>;
+/** Parsed `kb taxonomy` options. */
 interface TaxonomyOptions {
+    /** The subcommand to run, or `null` when none was given. */
     subcommand: 'init' | null;
+    /** Explicit store name from `--kb`, or `null` for ancestor-walk discovery. */
     kb: string | null;
+    /** Whether `--merge` was supplied. */
     merge: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
 }
+/**
+ * Parses `kb taxonomy` options. `--kb` accepts both the space (`--kb x`) and equals (`--kb=x`) forms. An unknown flag,
+ * an unknown subcommand, a missing `--kb` value, or a second subcommand throws with a usage-style message.
+ */
 export declare function parseTaxonomyArgs(argv: readonly string[]): TaxonomyOptions;
 export {};

package/dist/esm/cli/format.d.ts

@@ -1,24 +1,45 @@
 import type { Finding } from '../types.js';
+/** A resolved store's identity, surfaced in both human and JSON output. */
 export interface StoreRef {
+    /** The store's display name, or `null` for a `.kb/`-discovered store with no registry entry. */
     name: string | null;
+    /** Absolute path to the store root. */
     path: string;
 }
+/** Severity-partitioned counts over a finding set, plus the note total checked. */
 export interface CheckSummary {
+    /** Notes enumerated and checked. */
     notes: number;
+    /** Total findings. */
     total: number;
+    /** Findings with `severity: 'error'`. */
     errors: number;
+    /** Findings with `severity: 'warning'`. */
     warnings: number;
 }
+/** Which selection produced a report, controlling the wording of the zero-match line. */
 export type CheckScope = 'vault' | 'patterns' | 'vs';
+/**
+ * Renders the default human output. Findings are grouped by file in path order, each line reading
+ * `<severity> <rule> (line N): message`. A clean run (notes checked, no findings) prints `✓ no findings (N notes
+ * checked)`; a run that checked nothing prints a zero-match line worded for its `scope` (naming the config targets for
+ * a whole-vault run, and a scope-appropriate line for a targeted one) without the `✓`, since no check ran.
+ *
+ * A run can check no notes and still carry vault-scoped findings, which describe the store rather than any note. The
+ * zero-match line then heads the report instead of replacing it: it explains why no note was checked, and the findings
+ * follow.
+ */
 export declare function formatHuman(input: {
     summary: CheckSummary;
     findings: readonly Finding[];
     targets: readonly string[];
     scope: CheckScope;
 }): string;
+/** Renders the `--json` payload: store identity, summary counts, and the raw findings. */
 export declare function formatJson(input: {
     store: StoreRef;
     summary: CheckSummary;
     findings: readonly Finding[];
 }): string;
+/** Partitions a finding set into total, error, and warning counts over `noteCount` notes. */
 export declare function summarize(findings: readonly Finding[], noteCount: number): CheckSummary;

package/dist/esm/cli/parse-flag-value.d.ts

@@ -1,2 +1,7 @@
+/** Reads the value from an inline flag (`--kb=x`), throwing when it is empty. */
 export declare function takeInlineValue(arg: string, prefix: string): string;
+/**
+ * Reads the value after a space-form flag (`--kb x`), throwing when it is missing, empty, or looks like another flag.
+ * An empty value is rejected on both forms, so the two spellings of a flag accept the same set of values.
+ */
 export declare function takeValue(argv: readonly string[], index: number, flag: string): string;

package/dist/esm/cli/resolve-store.d.ts

@@ -1,4 +1,5 @@
 import type { StoreRef } from './format.js';
+/** The store-resolution outcome: a resolved store, or a categorical failure message for exit 2. */
 export type ResolveStoreOutcome = {
     ok: true;
     store: StoreRef;
@@ -7,6 +8,17 @@ export type ResolveStoreOutcome = {
     ok: false;
     message: string;
 };
+/**
+ * Resolves the store a command runs against. An explicit `--kb <name>` is looked up in the merged registry
+ * (`tryLoadKbRegistry` with `projectDir: cwd`, so project-local `.agents/kb.yaml` entries join the user-global
+ * registry); without a flag, the nearest ancestor `.kb/` directory is used. An unknown `--kb` name or a missing `.kb/`
+ * fails for exit 2.
+ *
+ * The registry's `readonly` flag is reported rather than enforced: a command that writes into the store refuses on it,
+ * and a read-only command ignores it. It is kept off {@link StoreRef}, which carries the identity a report renders. A
+ * discovered store is cross-referenced against the registry by path, so a vault marked readonly is reported as such
+ * however it was named; one with no registry entry has no metadata to consult and is reported writable.
+ */
 export declare function resolveStore(input: {
     explicitKb: string | null;
     cwd: string;

package/dist/esm/cli/run.d.ts

@@ -1,6 +1,14 @@
 import { type CommandOutput } from './commands/check.js';
 import type { SelectKbPrompt } from './select-kb-prompt.js';
-export declare const HELP = "Usage: kb <command> [options]\n\nCommands:\n  check        Validate a knowledge base, optionally scoped to selected notes.\n  create       Scaffold a new knowledge base and register it in the kb.yaml registry.\n  set-default  Set, clear, or choose the default knowledge base.\n  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.\n\nRun \"kb <command> --help\" for command options.\n";
+/** Top-level usage text for the `kb` bin. */
+export declare const HELP = "Usage: kb <command> [options]\n\nCommands:\n  check        Validate a knowledge base, optionally scoped to selected notes.\n  create       Scaffold a new knowledge base and register it in the kb.yaml registry.\n  scaffold     Write into an existing knowledge base any canonical file that it lacks.\n  set-default  Set, clear, or choose the default knowledge base.\n  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.\n\nRun \"kb <command> --help\" for command options.\n";
+/**
+ * Dispatches a `kb` subcommand and returns its {@link CommandOutput} without touching `process`, so tests drive the
+ * command directly. `check`, `create`, `scaffold`, `set-default`, and `taxonomy` are the subcommands; a bare
+ * invocation or `--help`/`-h` prints top-level usage (exit 0), and an unknown command prints usage to stderr (exit 2).
+ * The optional `selectKb` picker is forwarded to `set-default`'s interactive form and to `create`'s ambiguous
+ * default-KB prompt; `cli/index.ts` supplies it only when stdin is a TTY.
+ */
 export declare function run(input: {
     argv: readonly string[];
     cwd: string;

package/dist/esm/cli/run.js

@@ -1,5 +1,6 @@
 import { runCheck } from "./commands/check.js";
 import { runCreate } from "./commands/create.js";
+import { runScaffold } from "./commands/scaffold.js";
 import { runSetDefault } from "./commands/set-default.js";
 import { runTaxonomy } from "./commands/taxonomy.js";
 export const HELP = `Usage: kb <command> [options]
@@ -7,6 +8,7 @@ export const HELP = `Usage: kb <command> [options]
 Commands:
   check        Validate a knowledge base, optionally scoped to selected notes.
   create       Scaffold a new knowledge base and register it in the kb.yaml registry.
+  scaffold     Write into an existing knowledge base any canonical file that it lacks.
   set-default  Set, clear, or choose the default knowledge base.
   taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.
 
@@ -29,6 +31,9 @@ export async function run(input) {
             ...(input.selectKb !== undefined && { selectKb: input.selectKb }),
         });
     }
+    if (command === 'scaffold') {
+        return runScaffold({ argv: rest, cwd: input.cwd, ...(input.home !== undefined && { home: input.home }) });
+    }
     if (command === 'taxonomy') {
         return runTaxonomy({ argv: rest, cwd: input.cwd, ...(input.home !== undefined && { home: input.home }) });
     }

package/dist/esm/cli/select-kb-prompt.d.ts

@@ -1,4 +1,5 @@
 import type { KbRegistryEntry } from '../types.js';
+/** The user's choice from the interactive default-KB picker. */
 export type SelectKbChoice = {
     kind: 'kb';
     index: number;
@@ -7,10 +8,27 @@ export type SelectKbChoice = {
 } | {
     kind: 'cancel';
 };
+/**
+ * Presents the registered KBs and resolves the user's choice. Injected into `runSetDefault` so the dispatcher itself
+ * stays free of terminal I/O and remains directly testable; the real implementation is {@link readlineSelectKbPrompt}.
+ */
 export type SelectKbPrompt = (input: {
     entries: readonly KbRegistryEntry[];
     currentDefaultName?: string;
 }) => Promise<SelectKbChoice>;
+/**
+ * Renders the numbered selection list: each registered KB (marking the current default) followed by a trailing
+ * `(none)` option numbered `entries.length + 1`. When no default is set, `(none)` carries the current marker instead.
+ */
 export declare function formatKbSelection(entries: readonly KbRegistryEntry[], currentDefaultName?: string): string;
+/**
+ * Maps a trimmed answer to a {@link SelectKbChoice}: an empty line cancels, `1..kbCount` selects that KB, and
+ * `kbCount + 1` clears the default. Any other value returns `null`, signalling the caller to re-prompt.
+ */
 export declare function parseSelection(answer: string, kbCount: number): SelectKbChoice | null;
+/**
+ * A readline-backed {@link SelectKbPrompt}: it prints the selection list, reads a line, and re-prompts until the answer
+ * resolves to a choice. This is the feature's sole interactive seam — `cli/index.ts` supplies it only when stdin is a
+ * TTY, and other commands (e.g. `kb create`) can reuse it for their own interactive default-KB selection.
+ */
 export declare const readlineSelectKbPrompt: SelectKbPrompt;

package/dist/esm/cli/targeting/resolve-changed-paths.d.ts

@@ -1,3 +1,4 @@
+/** The outcome of resolving a `--vs` ref to its changed-note paths: the store-relative paths, or a failure message. */
 export type ChangedPathsResult = {
     ok: true;
     paths: string[];
@@ -5,6 +6,15 @@ export type ChangedPathsResult = {
     ok: false;
     message: string;
 };
+/**
+ * Resolves the notes changed between `ref` and the working tree to store-relative paths.
+ *
+ * The change set is `git diff` of the working tree against `merge-base(ref, HEAD)` with `--diff-filter=AMR`, so it
+ * follows renames (reporting the destination), includes uncommitted edits to tracked files, and excludes deletions.
+ * Git emits toplevel-relative paths and resolves symlinks, so each path is rebased onto the real store root — a no-op
+ * when the store is the repository root, correct when it is nested. A git failure (unknown ref, not a repository)
+ * returns `{ ok: false }` for the caller to surface as a usage error rather than throwing.
+ */
 export declare function resolveChangedPaths(input: {
     storeRoot: string;
     ref: string;

package/dist/esm/cli/targeting/resolve-changed-paths.js

@@ -1,28 +1,20 @@
-import { execFileSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
-import { describeError } from '@williamthorsen/toolbelt.errors';
-import { isRecord } from "../../type-guards.js";
+import { runGit } from "../../git/run-git.js";
 export function resolveChangedPaths(input) {
     const { storeRoot, ref } = input;
-    const mergeBase = tryGit(storeRoot, ['merge-base', ref, 'HEAD']);
+    const mergeBase = runGit({ cwd: storeRoot, args: ['merge-base', ref, 'HEAD'] });
     if (!mergeBase.ok) {
         return { ok: false, message: `could not resolve ref "${ref}": ${mergeBase.message}` };
     }
-    const toplevel = tryGit(storeRoot, ['rev-parse', '--show-toplevel']);
+    const toplevel = runGit({ cwd: storeRoot, args: ['rev-parse', '--show-toplevel'] });
     if (!toplevel.ok) {
         return { ok: false, message: toplevel.message };
     }
-    const diff = tryGit(storeRoot, [
-        'diff',
-        '--name-only',
-        '-z',
-        '--diff-filter=AMR',
-        '--find-renames',
-        mergeBase.stdout.trim(),
-        '--',
-        '.',
-    ]);
+    const diff = runGit({
+        cwd: storeRoot,
+        args: ['diff', '--name-only', '-z', '--diff-filter=AMR', '--find-renames', mergeBase.stdout.trim(), '--', '.'],
+    });
     if (!diff.ok) {
         return { ok: false, message: diff.message };
     }
@@ -34,21 +26,3 @@ export function resolveChangedPaths(input) {
         .map((entry) => relative(realStoreRoot, join(repoRoot, entry)).split(sep).join('/'));
     return { ok: true, paths };
 }
-function extractGitErrorMessage(error) {
-    if (isRecord(error) && typeof error.stderr === 'string' && error.stderr.trim() !== '') {
-        return error.stderr.trim();
-    }
-    return describeError(error);
-}
-function tryGit(storeRoot, args) {
-    try {
-        const stdout = execFileSync('git', ['-C', storeRoot, ...args], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        return { ok: true, stdout };
-    }
-    catch (error) {
-        return { ok: false, message: extractGitErrorMessage(error) };
-    }
-}

package/dist/esm/cli/targeting/select-notes.d.ts

@@ -1,8 +1,21 @@
 import type { EnumeratedNote } from '../../check/enumerate.js';
+/** The outcome of resolving selection patterns against an enumerated vault. */
 export interface SelectionResult {
+    /** Notes matched by at least one pattern, in enumeration order, deduplicated. */
     selected: EnumeratedNote[];
+    /** Patterns that matched no validatable note and are backed by no real on-disk path — likely typos. */
     unmatched: string[];
 }
+/**
+ * Resolves selection patterns against an already-enumerated note set, returning the matched notes plus the patterns
+ * that matched nothing real.
+ *
+ * Each pattern is matched as a `picomatch` glob against the notes' store-relative paths, so the store's
+ * `targets`/`exclude` filtering is inherited and a quoted glob behaves the same as a shell-expanded one. A bare
+ * directory expands to its subtree. A pattern matching no note is reported in `unmatched` unless a real on-disk path
+ * backs it (a non-validatable file such as a README, an excluded subtree, or an empty directory), in which case it is
+ * dropped silently — distinguishing a typo from a legitimately out-of-scope target.
+ */
 export declare function selectNotes(input: {
     notes: readonly EnumeratedNote[];
     patterns: readonly string[];

package/dist/esm/cli/targeting/select-notes.js

@@ -5,13 +5,14 @@ import { leadingLiteralPrefix } from "../../check/glob-segments.js";
 import { isEnoent } from "../../type-guards.js";
 export async function selectNotes(input) {
     const { notes, storeRoot } = input;
-    const relativePaths = new Set(notes.map((entry) => entry.relativePath));
+    const pathsByComposedForm = new Map(notes.map((entry) => [entry.relativePath.normalize('NFC'), entry.relativePath]));
     const selectedPaths = new Set();
     const unmatched = [];
     for (const rawPattern of input.patterns) {
         const pattern = normalizePattern(rawPattern);
-        if (relativePaths.has(pattern)) {
-            selectedPaths.add(pattern);
+        const exactPath = pathsByComposedForm.get(pattern.normalize('NFC'));
+        if (exactPath !== undefined) {
+            selectedPaths.add(exactPath);
             continue;
         }
         const direct = matchPaths(notes, pattern);