@williamthorsen/kb 0.7.0 → 0.8.1

package/dist/esm/check/enumerate.d.ts

@@ -1,10 +1,7 @@
 import type { KbConfig } from '../config/config-schema.js';
-/**
- * A note reduced to the fields the check pipeline and curate consume: its paths, its frontmatter field map, its body
- * and body-start line (for file-absolute link lines), its full content (for the paths lint), and any parse error.
- */
+/** A note read and parsed once, so that every check in a run shares the result. */
 export interface EnumeratedNote {
-    /** Absolute path the note was read from. */
+    /** Absolute path from which the note was read. */
     path: string;
     /** The note's path relative to the KB root, slash-separated. */
     relativePath: string;
@@ -22,9 +19,10 @@ export interface EnumeratedNote {
 /**
  * Walks a KB root and returns the KB-root-relative path of every note {@link enumerateNotes} selects, opening none of
  * them. Scope selection runs through the same matcher and the same pruning, so a caller that needs only the note set's
- * shape — which folders hold notes, and how many — sees exactly what the check pipeline admits.
+ * shape (which folders contain notes, and how many) sees exactly what the check pipeline admits.
  *
- * A note whose content cannot be read still contributes its path here, where `enumerateNotes` drops it with a warning.
+ * A note whose content cannot be read still contributes its path here, whereas `enumerateNotes` drops it with a
+ * warning.
  */
 export declare function enumerateNotePaths(input: {
     kbRoot: string;
@@ -34,20 +32,19 @@ export declare function enumerateNotePaths(input: {
  * Walks a KB root and parses every note whose KB-root-relative path matches a `config.targets` glob and no
  * `config.exclude` glob into an {@link EnumeratedNote}.
  *
- * Matching uses `picomatch` with `dot:false`, so dot-prefixed directories (`.kb`, `.git`, `.agents`) are excluded
+ * Because matching uses `picomatch` with `dot:false`, dot-prefixed directories (`.kb`, `.git`, `.agents`) are excluded
  * implicitly without naming them in `exclude`. The walk prunes the tree to each target's leading literal segment
  * (`content/**` descends only into `content/`); a target with no leading literal (e.g. `**\/*.md`) falls back to a
- * full walk. Excludes are honored during descent so an excluded subtree is never entered.
+ * full walk. Excludes are honored during descent so that an excluded subtree is never entered.
  *
- * Where the store sits in a git working tree, scope narrows further to what git accounts for: tracked notes plus
- * untracked ones that no ignore rule covers. A note that the repository ignores is therefore neither enumerated nor available
+ * If the store is in a git working tree, the enumeration keeps only the notes that git tracks and the untracked
+ * notes that no ignore rule covers. A note that the repository ignores is therefore neither enumerated nor available
  * as a wikilink target, so a link pointing at one resolves to nothing. A store outside a working tree, or a machine
- * carrying no git, keeps the walk's own scope.
+ * with no git, keeps what the walk alone found.
  *
- * Notes with malformed or absent frontmatter are kept — `readNoteContent` records the parse error in `error` and
- * returns an empty field map rather than throwing, so they remain valid wikilink targets. A note that cannot be read,
- * or a directory that cannot be listed, is skipped with a `kb:` stderr warning rather than aborting the walk. Each
- * note's `path` is absolute; `relativePath` is the slash-separated path from the KB root.
+ * Notes with malformed or absent frontmatter are kept: `readNoteContent` records the parse error in `error` and
+ * returns an empty field map rather than throwing, so that they remain valid wikilink targets. A note that cannot be
+ * read, or a directory that cannot be listed, is skipped with a `kb:` stderr warning rather than aborting the walk.
  */
 export declare function enumerateNotes(input: {
     kbRoot: string;

package/dist/esm/check/glob-segments.d.ts

@@ -3,6 +3,6 @@ export declare function isGlobSegment(segment: string): boolean;
 /**
  * Returns the leading run of literal (non-glob) segments of a slash-separated pattern, slash-joined. A pattern whose
  * first segment is a glob yields the empty string; a fully literal pattern yields itself. Locates the deepest concrete
- * path a glob is anchored to, e.g. `content/notes/**` yields `content/notes`.
+ * path to which a glob is anchored, e.g. `content/notes/**` yields `content/notes`.
  */
 export declare function leadingLiteralPrefix(pattern: string): string;

package/dist/esm/check/resolve-foreign-stores.d.ts

@@ -0,0 +1,25 @@
+import { type StoreVisibility } from '../config/config-schema.js';
+import type { KbRegistry } from '../types.js';
+import type { ForeignStore } from '../vault-integrity/check-vault-integrity.js';
+/**
+ * Collects the distinct store names that a note set's wikilinks qualify, so that a check run consults only the stores
+ * that its own links name. It reads {@link scanWikilinks}, the same walk that later evaluates the links, so a
+ * store-shaped prefix inside a code sample selects no store and the two cannot disagree on what counts as a qualified
+ * link.
+ */
+export declare function collectStorePrefixes(notes: readonly {
+    body: string;
+}[]): Set<string>;
+/**
+ * Resolves each store name that a run's links qualify against the merged registry, reading only note paths and each
+ * store's own `.kb/config.yaml`: A foreign store is enumerated under its own `targets`/`exclude` and its own
+ * repository's ignore rules, as it would be under its own check run, and no foreign note is opened.
+ *
+ * A store that cannot be read (absent from this machine, or with a config file that will not load) resolves
+ * `unavailable` rather than throwing, so that one unrelated store cannot fail the run.
+ */
+export declare function resolveForeignStores(input: {
+    prefixes: Iterable<string>;
+    registry: KbRegistry;
+    sourceVisibility: StoreVisibility;
+}): Promise<Map<string, ForeignStore>>;

package/dist/esm/check/resolve-foreign-stores.js

@@ -0,0 +1,50 @@
+import { stat } from 'node:fs/promises';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isAtLeastAsShareable } from "../config/config-schema.js";
+import { loadKbConfig } from "../config/load-config.js";
+import { resolveKbDir } from "../layout/index.js";
+import { buildVaultIndex } from "../vault-integrity/build-vault-index.js";
+import { scanWikilinks } from "../vault-integrity/wikilink-parse.js";
+import { enumerateNotePaths } from "./enumerate.js";
+export function collectStorePrefixes(notes) {
+    const prefixes = new Set();
+    for (const note of notes) {
+        for (const { store } of scanWikilinks(note.body)) {
+            if (store !== undefined)
+                prefixes.add(store);
+        }
+    }
+    return prefixes;
+}
+export async function resolveForeignStores(input) {
+    const resolved = new Map();
+    for (const prefix of input.prefixes) {
+        resolved.set(prefix, await resolveOne(prefix, input.registry, input.sourceVisibility));
+    }
+    return resolved;
+}
+async function resolveOne(prefix, registry, sourceVisibility) {
+    const entry = registry.entries.find((candidate) => candidate.name === prefix);
+    if (entry === undefined)
+        return { status: 'unknown' };
+    try {
+        const stats = await stat(entry.path);
+        if (!stats.isDirectory())
+            return { status: 'unavailable', reason: `${entry.path} is not a directory` };
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: `${entry.path} could not be read: ${describeError(error)}` };
+    }
+    let config;
+    try {
+        config = await loadKbConfig({ kbRoot: { path: entry.path, kbDir: resolveKbDir(entry.path) } });
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: describeError(error) };
+    }
+    if (!isAtLeastAsShareable({ source: sourceVisibility, target: config.visibility })) {
+        return { status: 'disallowed', visibility: config.visibility };
+    }
+    const paths = await enumerateNotePaths({ kbRoot: entry.path, config });
+    return { status: 'resolved', index: buildVaultIndex(paths.map((path) => ({ path }))) };
+}

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

@@ -1,32 +1,26 @@
-/** 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;
 }
-/** 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 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";
+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 named by its prefix 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 that 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.
+ * The command writes nothing to the store, so it ignores the registry's `readonly` flag. `check` throws a
+ * `KbLoaderError` for a structural defect in a store file that it loads, and the command maps that error 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[];

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

@@ -10,11 +10,12 @@ 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 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
@@ -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,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[];