@williamthorsen/kb 0.6.1 → 0.7.0

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);

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

@@ -1,10 +1,22 @@
 import { z } from 'zod';
+/**
+ * The on-disk `.kb/config.yaml` shape. Both fields are optional so a file may override only the dimension it cares
+ * about; an absent field falls back to {@link defaultKbConfig}.
+ */
 export declare const configFileShape: z.ZodObject<{
     targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** The effective check configuration: the glob target set and the glob exclude set. */
 export interface KbConfig {
+    /** Glob patterns (slash-separated, kbRoot-relative) selecting which notes `check` enumerates. */
     targets: readonly string[];
+    /** Glob patterns excluded from enumeration even when a target matches. */
     exclude: readonly string[];
 }
+/**
+ * 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`.
+ */
 export declare const defaultKbConfig: KbConfig;

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

@@ -1,5 +1,13 @@
+/**
+ * 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
+ * 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";
     constructor(message: string, options?: ErrorOptions);
 }
+/** Type guard narrowing an unknown throw to a {@link KbLoaderError} via its `kind` discriminant. */
 export declare function isKbLoaderError(error: unknown): error is KbLoaderError;

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

@@ -1,5 +1,12 @@
 import type { KbRoot } from '../types.js';
 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 `targets` or `exclude` 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.
+ */
 export declare function loadKbConfig(input: {
     kbRoot: KbRoot;
 }): Promise<KbConfig>;

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

@@ -1,7 +1,20 @@
 import type { KbConfig } from './config-schema.js';
+/** The note-membership predicates a {@link KbConfig} defines, all matching KB-root-relative, slash-separated paths. */
 export interface NoteScopeMatcher {
+    /** True when the path matches a `targets` glob. */
     isTarget(relativePath: string): boolean;
+    /** True when the path matches an `exclude` glob. */
     isExcluded(relativePath: string): boolean;
+    /** True when the path is a note: matched by `targets` and not `exclude`d. The `.md` gate is the caller's. */
     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`.
+ *
+ * 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 only the `targets`/`exclude` dimension, the one place the two tools previously disagreed.
+ */
 export declare function createNoteScopeMatcher(config: KbConfig): NoteScopeMatcher;

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

@@ -1,12 +1,30 @@
+/**
+ * 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.
+ */
 export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
+/** A successfully created store and a record of what was written. */
 export interface CreatedStore {
+    /** The store's registry name (the directory's base name unless overridden). */
     name: string;
+    /** Absolute path to the store root. */
     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[];
+    /** What happened to the registry's `default_kb` pointer; absent when the store was not registered. */
     defaultKb?: DefaultKbOutcome;
 }
+/**
+ * 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.
+ */
 export type CreateInput = {
     targetDir: string;
     name?: string;
@@ -17,6 +35,7 @@ export type CreateInput = {
     registryPath: string;
     description?: string;
 });
+/** The outcome of a {@link create} call: a created store, or a categorical precondition failure. */
 export type CreateOutcome = {
     ok: true;
     created: CreatedStore;
@@ -25,4 +44,10 @@ export type CreateOutcome = {
     reason: 'kb-exists' | 'name-registered';
     message: string;
 };
+/**
+ * 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.
+ */
 export declare function create(input: CreateInput): Promise<CreateOutcome>;

package/dist/esm/create/create.js

@@ -1,11 +1,10 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { loadKbRegistry } from "../discovery/load-registry.js";
 import { registerStore } from "../discovery/register-store.js";
 import { setDefaultKb } from "../discovery/set-default-kb.js";
 import { pathExists } from "../filesystem/exists.js";
-import { ALIASES_FILE, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveEventsDir, resolveKbDir, } from "../layout/index.js";
-import { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";
+import { KB_DIR, resolveKbDir } from "../layout/index.js";
+import { scaffold } from "../scaffold/scaffold.js";
 export async function create(input) {
     const storePath = resolve(input.targetDir);
     const name = input.name ?? basename(storePath);
@@ -13,7 +12,7 @@ export async function create(input) {
         return { ok: false, reason: 'kb-exists', message: `a ${KB_DIR}/ store already exists at ${storePath}` };
     }
     if (!input.register) {
-        const created = await scaffold(storePath);
+        const created = await writeCanonicalSet(storePath);
         return { ok: true, created: { name, storePath, registered: false, created } };
     }
     const { registryPath } = input;
@@ -21,7 +20,7 @@ export async function create(input) {
     if (before.entries.some((entry) => entry.name === name)) {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
-    const created = await scaffold(storePath);
+    const created = await writeCanonicalSet(storePath);
     const described = input.description !== undefined && { description: input.description };
     const result = await registerStore({ registryPath, name, storePath, ...described });
     if (result.status === 'already-present') {
@@ -43,10 +42,7 @@ async function ensureDefaultKb(input) {
 function nameRegisteredMessage(name, registryPath) {
     return `a store named "${name}" is already registered in ${registryPath}`;
 }
-async function scaffold(storePath) {
-    await mkdir(resolveKbDir(storePath), { recursive: true });
-    await writeFile(join(storePath, CONFIG_FILE), renderConfigSeed(), 'utf8');
-    await writeFile(join(storePath, ALIASES_FILE), renderAliasesSeed(), 'utf8');
-    await mkdir(resolveEventsDir(storePath), { recursive: true });
-    return [CONFIG_FILE, ALIASES_FILE, `${CONTENT_DIR}/`, `${EVENTS_DIR}/`];
+async function writeCanonicalSet(storePath) {
+    const entries = await scaffold({ storePath });
+    return entries.filter((entry) => entry.action !== 'present').map((entry) => entry.path);
 }

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

@@ -1,3 +1,2 @@
 export type { CreatedStore, CreateInput, CreateOutcome } from './create.js';
 export { create } from './create.js';
-export { renderAliasesSeed, renderConfigSeed } from './render-seeds.js';

package/dist/esm/create/index.js

@@ -1,2 +1 @@
 export { create } from "./create.js";
-export { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";

package/dist/esm/discovery/find-kb-root.d.ts

@@ -1,4 +1,8 @@
 import type { KbRoot } from '../types.js';
+/**
+ * Walks up the directory tree from `startDir` & returns the first ancestor containing a `.kb/` directory as a `KbRoot`.
+ * Returns `null` when the walk reaches the filesystem root without a hit.
+ */
 export declare function findKbRoot(input: {
     startDir: string;
 }): Promise<KbRoot | null>;

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

@@ -1,9 +1,11 @@
 import { z } from 'zod';
+/** Schema for a single KB entry as written in `kb.yaml`. */
 export declare const kbRegistryFileEntrySchema: z.ZodObject<{
     path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     readonly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/** Schema for the full `kb.yaml` file. */
 export declare const kbRegistryFileSchema: z.ZodObject<{
     default_kb: z.ZodOptional<z.ZodString>;
     kbs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -12,5 +14,7 @@ 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>;

package/dist/esm/discovery/load-registry.d.ts

@@ -1,13 +1,36 @@
 import type { KbRegistry } from '../types.js';
+/**
+ * Load and merge the user-global (`~/.agents/kb.yaml`) and project-local
+ * (`.agents/kb.yaml`) KB registries into a normalized `KbRegistry`.
+ *
+ * Project entries replace user entries by name on collision and append new names. The top-level `default_kb`
+ * pointer resolves by name against the merged entries (the project's value overriding the user's); the resolved
+ * entry is exposed as `defaultKb`.
+ * Within a single file, relative `path` values resolve against that file's directory and a leading `~/` expands
+ * against `$HOME`. Both files are optional; when neither exists the result has no entries.
+ * Malformed YAML, a structural defect, or a `default_kb` that names no registered KB throw.
+ */
 export declare function loadKbRegistry(input?: {
     userConfigPath?: string;
     projectDir?: string;
     home?: string;
 }): Promise<KbRegistry>;
+/** The outcome of a no-throw registry load: the resolved config plus a captured error message when loading failed. */
 export interface KbRegistryLoadResult {
+    /** The merged registry, or an empty config when loading threw. */
     config: KbRegistry;
+    /** The thrown error's message, present only when `loadKbRegistry` failed. */
     error?: string;
 }
+/**
+ * Load the merged `kb.yaml` registry without throwing, capturing any failure message instead of presenting it.
+ *
+ * On success — including the legitimate "no registry files present" case, which `loadKbRegistry` already returns as an
+ * empty config — `error` is absent. On a malformed file, a schema violation, an unresolvable `default_kb`, or a
+ * non-ENOENT read failure, the result degrades to an empty config and carries the thrown message in `error`. Each
+ * caller decides whether and how to surface that message; this wrapper neither writes to stderr nor builds a
+ * diagnostic.
+ */
 export declare function tryLoadKbRegistry(input?: {
     userConfigPath?: string;
     projectDir?: string;

package/dist/esm/discovery/register-store.d.ts

@@ -1,6 +1,17 @@
+/** The outcome of a registry write. */
 export interface RegisterStoreResult {
+    /** `added` when a new entry was written; `already-present` when an entry of the same name already existed. */
     status: 'added' | 'already-present';
 }
+/**
+ * Inserts a knowledge-base entry under `kbs:` in a `kb.yaml` registry, creating the file and its parent directory when
+ * absent and preserving any existing comments and formatting. Every write leaves the `kbs:` entries alphabetically
+ * ordered, so a registry that has already drifted converges rather than merely staying sorted. An existing entry of the
+ * same name is left untouched and reported as `already-present`; that path writes nothing, so re-registering never
+ * reorders the file. The registry is validated against its schema both before mutation (so an already-corrupt file
+ * throws rather than being silently extended) and after (so an invalid entry, such as an empty `storePath` from a
+ * direct caller, throws rather than being written), never producing a corrupt file.
+ */
 export declare function registerStore(input: {
     registryPath: string;
     name: string;

package/dist/esm/discovery/registry-document.d.ts

@@ -1,2 +1,7 @@
 import { Document } from 'yaml';
+/**
+ * Reads and parses a `kb.yaml` registry as a `yaml` Document, returning a fresh empty document when the file is absent
+ * or empty. Parsing through `parseDocument` preserves comments and formatting so registry writers can mutate in place
+ * without discarding them. Shared by every registry writer (`registerStore`, `setDefaultKb`, `clearDefaultKb`).
+ */
 export declare function loadRegistryDocument(path: string): Promise<Document>;

package/dist/esm/discovery/set-default-kb.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Removes the top-level `default_kb` pointer from a `kb.yaml` registry, preserving existing comments and formatting. A
+ * no-op when no default is set (or the file is absent): the file is left untouched rather than rewritten, so clearing is
+ * idempotent and never reformats. Validates an existing registry against its schema first, so a corrupt file throws
+ * rather than being rewritten.
+ */
 export declare function clearDefaultKb(input: {
     registryPath: string;
 }): Promise<void>;
+/**
+ * Sets the top-level `default_kb` pointer in a `kb.yaml` registry to `name`, creating the file and its parent directory
+ * when absent and preserving existing comments and formatting. Validates the registry against its schema before mutating
+ * (so an already-corrupt file throws rather than being rewritten) and asserts `name` is registered under `kbs` in the
+ * file (a `default_kb` naming no registered KB would fail every subsequent load), then re-validates the result.
+ */
 export declare function setDefaultKb(input: {
     registryPath: string;
     name: string;

package/dist/esm/filesystem/exists.d.ts

@@ -1,6 +1,19 @@
+/** Controls which `stat` failures a filesystem-existence check treats as "absent". */
 export interface ExistsOptions {
+    /**
+     * Stat-error codes treated as "absent" (the helper returns `false`). Any other failure is re-thrown so a genuine
+     * error — most importantly a permission denial on a path that does exist — is not silently read as absence.
+     * Defaults to `['ENOENT']`.
+     */
     absentCodes?: readonly string[];
+    /**
+     * When `true`, every `stat` failure is treated as "absent" (`false`), including permission errors.
+     * Reserved for best-effort probes such as an ancestor walk, where an unreadable path should be skipped rather than
+     * abort the operation. Takes precedence over `absentCodes`.
+     */
     treatErrorsAsAbsent?: boolean;
 }
+/** Returns true when `path` exists and is a directory. See {@link ExistsOptions} for the absence policy. */
 export declare function directoryExists(path: string, options?: ExistsOptions): Promise<boolean>;
+/** Returns true when something exists at `path`. See {@link ExistsOptions} for the absence policy. */
 export declare function pathExists(path: string, options?: ExistsOptions): Promise<boolean>;