@williamthorsen/kb 0.8.0 → 0.8.1

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

@@ -11,11 +11,11 @@ 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 store; a [[store:Target]]
-link resolves against the store its prefix names in the kb.yaml registry.
+link resolves against the store named by its prefix in the kb.yaml registry.
 
 Targeting (mutually exclusive):
   [paths...]    Check only the notes matching the given glob patterns, files,
-                or directories. Quote globs so kb expands them itself. A
+                or directories. Quote globs so that kb expands them itself. A
                 directory checks every note beneath it. A path that matches no
                 note is a usage error unless it names a real non-note.
   --vs <ref>    Check only the notes changed between the working tree and the

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

@@ -1,13 +1,12 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
-/** 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";
+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, the command prompts for a choice (or \"kb set-default\" sets one later).\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
+ * 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
+ * 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: {
@@ -16,15 +15,12 @@ export declare function runCreate(input: {
     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;
 }
 /**

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

@@ -11,7 +11,7 @@ Scaffold a new knowledge base in the current directory and register it in the us
 Registering leaves the registry's entries in alphabetical order, preserving its comments and formatting.
 
 When the registry has no default knowledge base, the new store becomes the default.
-If other knowledge bases are already registered, you are prompted to choose one (or set it later with "kb set-default").
+If other knowledge bases are already registered, the command prompts for a choice (or "kb set-default" sets one later).
 
 Creates:
   .editorconfig          editor and formatter settings (width, indent, line endings)

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

@@ -1,23 +1,19 @@
 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";
+export declare const SCAFFOLD_HELP = "Usage: kb scaffold [options]\n\nWrite into an existing knowledge base any canonical file that it lacks, so that\na store created before a given file existed can acquire it. An existing file is\nleft untouched 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 contains. 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 containing no .kb/\n";
 /**
- * Runs `kb scaffold`: parses options, resolves the store, and writes the canonical files it lacks.
+ * Runs `kb scaffold`: parses options, resolves the store, and writes the canonical files that 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.
+ * A store that the registry marks `readonly` is refused. A resolved path containing 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;

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

@@ -6,9 +6,9 @@ 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.
+Write into an existing knowledge base any canonical file that it lacks, so that
+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)
@@ -18,7 +18,7 @@ Writes:
   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.
+the notes that the store already contains. Use "kb create" to make a new store.
 
 Options:
   --force       Replace an existing canonical file with a fresh seed. A
@@ -30,7 +30,7 @@ Options:
 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}/
+     resolved path containing no ${KB_DIR}/
 `;
 export async function runScaffold(input) {
     let options;

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

@@ -1,7 +1,6 @@
 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";
+export declare const SET_DEFAULT_HELP = "Usage: kb set-default [name] [options]\n\nSet, clear, or interactively choose the user-global default knowledge base:\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
@@ -13,13 +12,10 @@ export declare function runSetDefault(input: {
     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;
 }
 /**

package/dist/esm/cli/commands/set-default.js

@@ -5,7 +5,7 @@ import { tryLoadKbRegistry } from "../../discovery/load-registry.js";
 import { clearDefaultKb, setDefaultKb } from "../../discovery/set-default-kb.js";
 export const SET_DEFAULT_HELP = `Usage: kb set-default [name] [options]
 
-Set, clear, or interactively choose the user-global default knowledge base —
+Set, clear, or interactively choose the user-global default knowledge base:
 the top-level default_kb pointer in ~/.agents/kb.yaml.
 
   kb set-default <name>   Set default_kb to the named registered KB.

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

@@ -1,12 +1,11 @@
 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";
+export declare const TAXONOMY_HELP = "Usage: kb taxonomy init [options]\n\nDerive a starting taxonomy from the notes that a knowledge base already\ncontains, so that a taxonomy can be introduced to a populated store without\nevery folder reporting as undeclared. Every folder containing notes is\ndeclared, along with each of its ancestors, under \"provisional:\" with no\ndescription: The command cannot invent descriptions, and provisional already\nmeans \"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 that an existing taxonomy does not\n                declare. Without it, a store that already has a taxonomy is\n                left 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.
+ * Runs `kb taxonomy`: parses options, resolves the store, derives the domains implied by its notes, 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
+ * The derivation reads the same enumeration as `kb check`, so a store back-filled by this command reports no
+ * taxonomy drift. A store that the registry marks `readonly` is refused. The loaders throw a `KbLoaderError` for a
+ * malformed `.kb/config.yaml` or `.kb/taxonomy.yaml`, and the command maps that error to exit 2; any other error
  * propagates to the caller as a real crash.
  */
 export declare function runTaxonomy(input: {
@@ -14,15 +13,11 @@ export declare function runTaxonomy(input: {
     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;
 }
 /**

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

@@ -10,18 +10,19 @@ import { takeInlineValue, takeValue } from "../parse-flag-value.js";
 import { resolveStore } from "../resolve-store.js";
 export const TAXONOMY_HELP = `Usage: kb taxonomy init [options]
 
-Derive a starting taxonomy from the notes a knowledge base already holds, so a
-taxonomy can be introduced to a populated store without every folder reporting
-as undeclared. Every folder holding notes is declared, along with each of its
-ancestors, under "provisional:" with no description: the command cannot invent
-descriptions, and provisional already means "declared, not yet reviewed".
+Derive a starting taxonomy from the notes that a knowledge base already
+contains, so that a taxonomy can be introduced to a populated store without
+every folder reporting as undeclared. Every folder containing notes is
+declared, along with each of its ancestors, under "provisional:" with no
+description: The command cannot invent descriptions, and provisional already
+means "declared, not yet reviewed".
 
 Options:
   --kb <name>   Use the named store from the kb.yaml registry. Without it, the
                 nearest ancestor .kb/ directory is used.
-  --merge       Add only the domains an existing taxonomy does not declare.
-                Without it, a store that already has a taxonomy is left
-                untouched.
+  --merge       Add only the domains that an existing taxonomy does not
+                declare. Without it, a store that already has a taxonomy is
+                left untouched.
   -h, --help    Show this help.
 
 Exit codes:
@@ -117,7 +118,7 @@ async function initTaxonomy(input) {
     const notes = await enumerateNotes({ kbRoot: kbRoot.path, config });
     const domains = deriveDomains(notes.map((note) => note.relativePath));
     if (domains.length === 0) {
-        return { exitCode: 0, stdout: `no assertion folders hold notes; ${TAXONOMY_FILE} not written\n`, stderr: '' };
+        return { exitCode: 0, stdout: `no assertion folders contain notes; ${TAXONOMY_FILE} not written\n`, stderr: '' };
     }
     const { added } = await writeTaxonomy({
         kbRoot,

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

@@ -1,5 +1,5 @@
 import type { Finding } from '../types.js';
-/** A resolved store's identity, surfaced in both human and JSON output. */
+/** A resolved store's identity, shown 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;
@@ -10,23 +10,21 @@ export interface StoreRef {
 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.
+ * Renders the default human output. Findings are grouped by file, in the order in which each file first appears, 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
+ * A run can check no notes and still include 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: {

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

@@ -9,15 +9,15 @@ export type ResolveStoreOutcome = {
     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.
+ * Resolves the store against which a command runs. An explicit `--kb <name>` is looked up in the merged registry
+ * (`tryLoadKbRegistry` with `projectDir: cwd`, so the registry includes project-local `.agents/kb.yaml` entries as
+ * well as user-global ones); 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.
+ * 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 contains the identity that 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;

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

@@ -1,13 +1,11 @@
 import { type CommandOutput } from './commands/check.js';
 import type { SelectKbPrompt } from './select-kb-prompt.js';
-/** 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";
+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 that it already contains.\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.
+ * command directly. 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.
  */
 export declare function run(input: {
     argv: readonly string[];

package/dist/esm/cli/run.js

@@ -10,7 +10,7 @@ Commands:
   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.
+  taxonomy     Derive a knowledge base's taxonomy from the notes that it already contains.
 
 Run "kb <command> --help" for command options.
 `;

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

@@ -9,8 +9,9 @@ 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}.
+ * Presents the registered KBs and resolves the user's choice. A command takes it as an injected dependency, so that the
+ * command stays free of terminal I/O and remains directly testable; the real implementation is
+ * {@link readlineSelectKbPrompt}.
  */
 export type SelectKbPrompt = (input: {
     entries: readonly KbRegistryEntry[];
@@ -18,7 +19,8 @@ export type SelectKbPrompt = (input: {
 }) => 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.
+ * `(none)` option numbered `entries.length + 1`. When no default is set, the current marker appears on `(none)`
+ * instead.
  */
 export declare function formatKbSelection(entries: readonly KbRegistryEntry[], currentDefaultName?: string): string;
 /**
@@ -28,7 +30,6 @@ export declare function formatKbSelection(entries: readonly KbRegistryEntry[], c
 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.
+ * resolves to a choice.
  */
 export declare const readlineSelectKbPrompt: SelectKbPrompt;

package/dist/esm/cli/select-kb-prompt.js

@@ -7,7 +7,7 @@ export function formatKbSelection(entries, currentDefaultName) {
         lines.push(`  ${String(index + 1)}) ${entry.name}${suffix}`);
     }
     const noneSuffix = currentDefaultName === undefined ? '  (current)' : '';
-    lines.push(`  ${String(entries.length + 1)}) (none) — no default${noneSuffix}`);
+    lines.push(`  ${String(entries.length + 1)}) (none): no default${noneSuffix}`);
     return `${lines.join('\n')}\n`;
 }
 export function parseSelection(answer, kbCount) {

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

@@ -11,9 +11,9 @@ export type ChangedPathsResult = {
  *
  * 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.
+ * Because git emits toplevel-relative paths and resolves symlinks, the function rebases each path 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 report as a usage error rather than throwing.
  */
 export declare function resolveChangedPaths(input: {
     storeRoot: string;

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

@@ -3,7 +3,7 @@ import type { EnumeratedNote } from '../../check/enumerate.js';
 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. */
+    /** Patterns that matched no validatable note and are backed by no real on-disk path: likely typos. */
     unmatched: string[];
 }
 /**
@@ -14,7 +14,7 @@ export interface SelectionResult {
  * `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.
+ * dropped silently, which distinguishes a typo from a legitimately out-of-scope target.
  */
 export declare function selectNotes(input: {
     notes: readonly EnumeratedNote[];

package/dist/esm/config/config-schema.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 /**
- * The on-disk `.kb/config.yaml` shape. Every field is optional so a file may override only the key it cares about; an
- * absent field falls back to {@link defaultKbConfig}.
+ * The on-disk `.kb/config.yaml` shape. Every field is optional so that a file may override only the key that it cares
+ * about; an absent field falls back to {@link defaultKbConfig}.
  */
 export declare const configFileShape: z.ZodObject<{
     targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -12,21 +12,20 @@ export declare const configFileShape: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 /**
- * The configuration applied when `.kb/config.yaml` is absent or omits a field. Targets the `content/`-scoped layout
- * the owner's stores use; with `picomatch` `dot:false`, dot-directories (`.kb`, `.git`, `.agents`) are excluded
- * implicitly, so the default exclude only names `node_modules`. Visibility defaults to the safer of the two values, so
- * a store that has not declared itself never widens what may link into it.
+ * The configuration applied when `.kb/config.yaml` is absent or omits a field. The default exclude names `node_modules`
+ * alone, because `createNoteScopeMatcher` already excludes dot-directories. Visibility defaults to the safer of the two
+ * values, so a store that has not declared itself never widens what may link into it.
  */
 export declare const defaultKbConfig: KbConfig;
 /**
  * Whether a link from a store of `source` visibility may resolve into one of `target` visibility. A link never
- * increases disclosure: it may point at a store as shareable as its own or more so, never at a less shareable one.
+ * increases disclosure: It may point at a store as shareable as its own or more so, never at a less shareable one.
  */
 export declare function isAtLeastAsShareable(input: {
     source: StoreVisibility;
     target: StoreVisibility;
 }): boolean;
-/** The effective check configuration: the glob target set, the glob exclude set, and the store's visibility. */
+/** The effective check configuration, in which a default fills every field that `.kb/config.yaml` omits. */
 export interface KbConfig {
     /** Glob patterns (slash-separated, kbRoot-relative) selecting which notes `check` enumerates. */
     targets: readonly string[];
@@ -35,5 +34,7 @@ export interface KbConfig {
     /** How widely the store is published, which decides what may link into it. */
     visibility: StoreVisibility;
 }
-/** How widely a store is published: `shared` reaches collaborators through a remote, `private` reaches nobody else. */
+/**
+ * How widely a store is published: `shared` is available to collaborators through a remote, `private` to nobody else.
+ */
 export type StoreVisibility = NonNullable<z.infer<typeof configFileShape>['visibility']>;

package/dist/esm/config/kb-loader-error.d.ts

@@ -1,12 +1,12 @@
 /**
- * The typed error thrown by the KB loaders (`loadKbConfig`, `loadAliases`) on a structural defect: malformed YAML or
- * wrong types. The `kind` discriminant lets a caller distinguish a recoverable config or alias defect from any other
+ * The typed error thrown by the loaders and writers of a KB's YAML files on a structural defect, such as malformed YAML
+ * or wrong types. The `kind` discriminant lets a caller distinguish a recoverable defect in such a file from any other
  * throw (an enumeration or detection crash) without matching on message text or relying on `instanceof` surviving a
  * bundle boundary.
  */
 export declare class KbLoaderError extends Error {
-    /** Discriminant for narrow catch boundaries; survives serialization and bundling unlike `instanceof`. */
     readonly kind: "KbLoaderError";
+    /** Names the error after its class. */
     constructor(message: string, options?: ErrorOptions);
 }
 /** Type guard narrowing an unknown throw to a {@link KbLoaderError} via its `kind` discriminant. */

package/dist/esm/config/load-config.d.ts

@@ -4,8 +4,8 @@ import { type KbConfig } from './config-schema.js';
  * Loads the effective check configuration for a KB root. Returns {@link defaultKbConfig} verbatim when no
  * `.kb/config.yaml` exists; a file present but omitting a field inherits that field's default.
  *
- * Mirrors {@link loadAliases}: a single plain-object input, structural defects (malformed YAML, wrong types) throw a
- * {@link KbLoaderError} naming the file. I/O errors other than a missing file propagate.
+ * Structural defects (malformed YAML, wrong types) throw a {@link KbLoaderError} naming the file. I/O errors other than
+ * a missing file propagate.
  */
 export declare function loadKbConfig(input: {
     kbRoot: KbRoot;

package/dist/esm/config/load-config.js

@@ -27,7 +27,7 @@ export async function loadKbConfig(input) {
     }
     const result = configFileShape.safeParse(parsed ?? {});
     if (!result.success) {
-        throw new KbLoaderError(`${path}: invalid config.yaml — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new KbLoaderError(`${path}: invalid config.yaml: ${result.error.issues[0]?.message ?? 'unknown error'}`);
     }
     return {
         targets: result.data.targets ?? defaultKbConfig.targets,

package/dist/esm/config/note-scope.d.ts

@@ -1,5 +1,7 @@
 import type { KbConfig } from './config-schema.js';
-/** The note-membership predicates a {@link KbConfig} defines, all matching KB-root-relative, slash-separated paths. */
+/**
+ * The note-membership predicates defined by a {@link KbConfig}, all matching KB-root-relative, slash-separated paths.
+ */
 export interface NoteScopeMatcher {
     /** True when the path matches a `targets` glob. */
     isTarget(relativePath: string): boolean;
@@ -9,12 +11,10 @@ export interface NoteScopeMatcher {
     isNote(relativePath: string): boolean;
 }
 /**
- * Builds the note-membership predicates for a KB config — the single definition of "a note" shared by
- * `enumerateNotes` (which `kb check`/`kb-curate` drive) and `kb-retrieve`. Both axes match with `picomatch`'s
- * `dot:false`, so dot-directories (`.kb`, `.git`, `.agents`) are excluded implicitly without naming them in `exclude`.
+ * Builds the note-membership predicates for a KB config, the single definition of "a note". Both axes match with
+ * `picomatch`'s `dot:false`, so dot-directories (`.kb`, `.git`, `.agents`) are excluded implicitly without naming them
+ * in `exclude`.
  *
- * The `.md` extension gate is deliberately left to the caller: `enumerateNotes` applies its own `.endsWith('.md')`
- * during the walk, and `kb-retrieve` constrains ripgrep with `--glob '*.md'`. Keeping it out of `isNote` lets this
- * matcher govern `targets`/`exclude` alone, the one place the two tools previously disagreed.
+ * The matcher applies `targets` and `exclude` alone: Each caller applies its own `.md` extension gate.
  */
 export declare function createNoteScopeMatcher(config: KbConfig): NoteScopeMatcher;

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

@@ -1,8 +1,8 @@
 /**
  * What `create` did about the registry's `default_kb` pointer when registering a store:
- * `set` — it was unset and the new store was the only KB, so the store became the default;
- * `unchanged` — a default was already set and left untouched;
- * `needs-selection` — it was unset but other KBs exist, so the caller should prompt for a choice.
+ * - `set`: It was unset and the new store was the only KB, so the store became the default.
+ * - `unchanged`: A default was already set and left untouched.
+ * - `needs-selection`: It was unset but other KBs exist; the caller should prompt for a choice.
  */
 export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
 /** A successfully created store and a record of what was written. */
@@ -13,7 +13,6 @@ export interface CreatedStore {
     storePath: string;
     /** The description written into the registry entry; absent when none was supplied. */
     description?: string;
-    /** Whether the store was registered in the kb.yaml registry. */
     registered: boolean;
     /** Store-relative paths created by the scaffold. */
     created: readonly string[];
@@ -21,7 +20,7 @@ export interface CreatedStore {
     defaultKb?: DefaultKbOutcome;
 }
 /**
- * Inputs for {@link create}. `registryPath` and `description` belong to the registering form alone: a description is
+ * Inputs for {@link create}. `registryPath` and `description` belong to the registering form alone: A description is
  * only ever written into a registry entry, so supplying one without registering is a type error rather than a value
  * that would be silently discarded.
  */
@@ -46,8 +45,9 @@ export type CreateOutcome = {
 };
 /**
  * Scaffolds a new knowledge-base store in `targetDir` and, unless `register` is false, registers it in the kb.yaml
- * registry. Both preconditions — an existing `.kb/`, and (when registering) an already-registered name — are checked
- * before anything is written, so a precondition failure leaves the filesystem untouched. Genuine I/O failures
- * propagate.
+ * registry. Both preconditions, an existing `.kb/` and (when registering) an already-registered name, are checked
+ * before anything is written. A precondition failure leaves the filesystem untouched. A name collision that the
+ * registry writer detects only at write time also returns `name-registered`, after the scaffold is written. Genuine
+ * I/O failures propagate.
  */
 export declare function create(input: CreateInput): Promise<CreateOutcome>;

package/dist/esm/discovery/kb-registry-schema.d.ts

@@ -14,7 +14,5 @@ export declare const kbRegistryFileSchema: z.ZodObject<{
         readonly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-/** The validated on-disk entry shape. */
 export type KbRegistryFileEntry = z.infer<typeof kbRegistryFileEntrySchema>;
-/** The validated on-disk file shape. */
 export type KbRegistryFile = z.infer<typeof kbRegistryFileSchema>;