@williamthorsen/kb 0.4.0 → 0.6.0

package/README.md

@@ -5,17 +5,13 @@ Provides knowledge-base discovery, registry loading, frontmatter parsing and wri
 It underpins the knowledge-base skills — among them `kb-retrieve` (assertion recall) and `kb-retrieve-events` (event recall), `kb-add`, `kb-curate`, `capture-event`, and `kb-update-events` — and the planned `@williamthorsen/kb-mcp` server.
 
 <!-- section:release-notes -->
-## Release notes — v0.4.0 (2026-08-07)
+## Release notes — v0.6.0 (2026-08-13)
 
 ### 🎉 Features
 
-- Add the .kb/taxonomy.yaml format with drift reporting and back-fill (#1210)
+- Attach causes to kb's loader errors and retire its lint deferral (#1272)
 
-  Introduces `.kb/taxonomy.yaml`, in which a knowledge base declares the structure of its assertions. `kb check` now reports three kinds of drift between that declaration and the folders on disk: a folder that holds notes nothing declares, a declared area that holds no notes, and a declared area whose parent is undeclared. A knowledge base that already holds notes can adopt a declaration in one pass with the new `kb taxonomy init`, and `--merge` adds only what an existing declaration omits.
-
-- Guide kb-add note placement with the store's declared taxonomy (#1223)
-
-  Improves classification of captured knowledge-base notes by aligning with the domains declared by the KB's taxonomy rather than looking to the directory structure. If a note is filed in a folder not covered by a domain, that folder is now added to the base's taxonomy. A domain added without confirmation is recorded as awaiting review.
+  Errors `kb` raises on malformed input now carry the underlying parse error as their cause. Callers constructing one of these errors themselves can attach a cause. When `kb` reports a thrown error that carries no message, the diagnostic now names the error's class instead of trailing off empty.
 <!-- /section:release-notes -->
 
 ## Exports
@@ -206,9 +202,10 @@ The package ships a `kb` bin with four subcommands: `check`, `create`, `set-defa
 `kb create` scaffolds a new knowledge base in the current directory and registers it in the user-global `~/.agents/kb.yaml`.
 
 ```bash
-kb create                # scaffold the current directory, register under its name
-kb create --name coding  # register under an explicit name
-kb create --no-register  # scaffold without writing the registry
+kb create                                 # scaffold the current directory, register under its name
+kb create --name coding                   # register under an explicit name
+kb create --description "Coding notes"    # describe the registry entry
+kb create --no-register                   # scaffold without writing the registry
 ```
 
 It creates these files and directories:
@@ -221,7 +218,7 @@ It creates these files and directories:
 
 The config seed is serialized from the in-package `defaultKbConfig`, so a new store cannot drift from the bundled default.
 
-The name defaults to the directory's base name; `--name` overrides it and `--no-register` scaffolds without writing the registry. The registry write preserves any existing comments in `kb.yaml`. `kb create` refuses to clobber: it exits 2 if the directory already contains a `.kb/` store, or if the chosen name is already registered.
+The name defaults to the directory's base name; `--name` overrides it and `--no-register` scaffolds without writing the registry. `--description` sets the new entry's description, and requires registration: combining it with `--no-register` is a usage error. The registry write preserves any existing comments in `kb.yaml` and leaves the `kbs:` entries alphabetically ordered, so a registry that has drifted out of order is tidied as stores are added. `kb create` refuses to clobber: it exits 2 if the directory already contains a `.kb/` store, or if the chosen name is already registered.
 
 `kb create` also keeps a default knowledge base set. When the registry's top-level `default_kb` pointer is unset and the new store is the only registered KB, it becomes the default. When other KBs are already registered with no default, `kb create` prompts you to choose one on an interactive terminal — or, when stdin is not interactive, points you to `kb set-default`. An existing `default_kb` is never overwritten.
 
@@ -285,7 +282,7 @@ Without `--merge`, a store that already declares a taxonomy is left untouched an
 
 ## Error and exception model
 
-The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`, `loadTaxonomy`) **throw** a typed `KbLoaderError` on structural defects or malformed YAML, with the offending file path named in the message. `KbLoaderError` (exported from `@williamthorsen/kb/config`) carries a `kind: 'KbLoaderError'` discriminant — and an `isKbLoaderError` type guard — so a caller can distinguish a recoverable config or alias defect from any other throw. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
+The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`, `loadTaxonomy`) **throw** a typed `KbLoaderError` on structural defects or malformed YAML, with the offending file path named in the message. `KbLoaderError` (exported from `@williamthorsen/kb/config`) carries a `kind: 'KbLoaderError'` discriminant — and an `isKbLoaderError` type guard — so a caller can distinguish a recoverable config or alias defect from any other throw. An underlying failure, such as a YAML parse error, is attached as the thrown error's `cause`. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
 
 ## MCP wrappability
 

package/bin/kb.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+// Imports only node builtins: a top-level import resolves before the gate below runs, so an
+// unresolvable dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
 import { existsSync } from 'node:fs';
 
 // Thin wrapper so pnpm can symlink the bin at install time, before `dist/` exists.

package/dist/esm/check/enumerate.js

@@ -1,6 +1,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createNoteScopeMatcher } from "../config/note-scope.js";
 import { readNoteContent } from "../note-io/read-note.js";
 import { isGlobSegment } from "./glob-segments.js";
@@ -26,8 +27,7 @@ export async function enumerateNotes(input) {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`kb: warning: could not read note ${path}; skipping: ${message}\n`);
+            process.stderr.write(`kb: warning: could not read note ${path}; skipping: ${describeError(error)}\n`);
         }
     }
     return notes;
@@ -58,8 +58,7 @@ async function walk(input) {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`kb: warning: could not read directory ${dir}; skipping: ${message}\n`);
+        process.stderr.write(`kb: warning: could not read directory ${dir}; skipping: ${describeError(error)}\n`);
         return;
     }
     const atRoot = dir === root;

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

@@ -1,3 +1,4 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { check } from "../../check/check.js";
 import { isKbLoaderError } from "../../config/kb-loader-error.js";
 import { formatHuman, formatJson, summarize } from "../format.js";
@@ -119,8 +120,7 @@ export function parseCheckArgs(argv) {
     return { kb, json, help, patterns, vs };
 }
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb check: ${message}\n${CHECK_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb check: ${describeError(error)}\n${CHECK_HELP}` };
 }
 async function resolveSelection(input) {
     const { options, store, result } = input;

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

@@ -1,6 +1,6 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
-export declare const CREATE_HELP = "Usage: kb create [options]\n\nScaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.\n\nWhen the registry has no default knowledge base, the new store becomes the default.\nIf other knowledge bases are already registered, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  content/, content/events/\n\nOptions:\n  --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, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  content/, content/events/\n\nOptions:\n  --description <text>  Description for the registry entry; cannot be combined with --no-register.\n  --name <name>         Registry name for the store. Defaults to the directory name.\n  --no-register         Scaffold without writing the kb.yaml registry entry.\n  -h, --help            Show this help.\n\nExit codes:\n  0  store created\n  2  usage error, an existing .kb/ in the directory, or an already-registered name\n";
 export declare function runCreate(input: {
     argv: readonly string[];
     cwd: string;
@@ -8,6 +8,7 @@ export declare function runCreate(input: {
     selectKb?: SelectKbPrompt;
 }): Promise<CommandOutput>;
 interface CreateOptions {
+    description: string | null;
     name: string | null;
     noRegister: boolean;
     help: boolean;

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

@@ -1,11 +1,15 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { create } from "../../create/create.js";
+import { takeInlineValue, takeValue } from "../parse-flag-value.js";
 import { runSetDefault } from "./set-default.js";
 export const CREATE_HELP = `Usage: kb create [options]
 
 Scaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.
 
+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").
 
@@ -15,9 +19,10 @@ Creates:
   content/, content/events/
 
 Options:
-  --name <name>   Registry name for the store. Defaults to the directory name.
-  --no-register   Scaffold without writing the kb.yaml registry entry.
-  -h, --help      Show this help.
+  --description <text>  Description for the registry entry; cannot be combined with --no-register.
+  --name <name>         Registry name for the store. Defaults to the directory name.
+  --no-register         Scaffold without writing the kb.yaml registry entry.
+  -h, --help            Show this help.
 
 Exit codes:
   0  store created
@@ -38,7 +43,12 @@ export async function runCreate(input) {
     const base = { targetDir: input.cwd, ...(options.name !== null && { name: options.name }) };
     const outcome = options.noRegister
         ? await create({ ...base, register: false })
-        : await create({ ...base, register: true, registryPath });
+        : await create({
+            ...base,
+            register: true,
+            registryPath,
+            ...(options.description !== null && { description: options.description }),
+        });
     if (!outcome.ok) {
         return { exitCode: 2, stdout: '', stderr: `kb create: ${outcome.message}\n` };
     }
@@ -57,6 +67,7 @@ export async function runCreate(input) {
     return { exitCode: 0, stdout: summary + selection.stdout, stderr: selection.stderr };
 }
 export function parseCreateArgs(argv) {
+    let description = null;
     let name = null;
     let noRegister = false;
     let help = false;
@@ -68,35 +79,38 @@ export function parseCreateArgs(argv) {
             help = true;
             continue;
         }
+        if (arg === '--description') {
+            description = takeValue(argv, index, '--description');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--description=')) {
+            description = takeInlineValue(arg, '--description=');
+            continue;
+        }
         if (arg === '--no-register') {
             noRegister = true;
             continue;
         }
         if (arg === '--name') {
-            const next = argv[index + 1] ?? null;
-            if (next === null || next.startsWith('--')) {
-                throw new Error('--name requires a value');
-            }
-            name = next;
+            name = takeValue(argv, index, '--name');
             index += 1;
             continue;
         }
         if (arg.startsWith('--name=')) {
-            const value = arg.slice('--name='.length);
-            if (value === '') {
-                throw new Error('--name requires a value');
-            }
-            name = value;
+            name = takeInlineValue(arg, '--name=');
             continue;
         }
         throw new Error(`unknown flag: ${arg}`);
     }
-    return { name, noRegister, help };
+    if (noRegister && description !== null) {
+        throw new Error('--description cannot be combined with --no-register');
+    }
+    return { description, name, noRegister, help };
 }
 const UNSET_DEFAULT_HINT = 'Multiple knowledge bases are registered and no default is set. Run `kb set-default` to choose one.\n';
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb create: ${message}\n${CREATE_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb create: ${describeError(error)}\n${CREATE_HELP}` };
 }
 function formatCreated(created, registryPath) {
     const lines = [`Created knowledge base "${created.name}" at ${created.storePath}`];
@@ -104,6 +118,9 @@ function formatCreated(created, registryPath) {
         lines.push(`  ${path}`);
     }
     lines.push(created.registered ? `Registered in ${registryPath}` : 'Not registered (--no-register).');
+    if (created.description !== undefined) {
+        lines.push(`Description: ${created.description}`);
+    }
     if (created.defaultKb === 'set') {
         lines.push('Set as the default knowledge base.');
     }

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

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 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]
@@ -38,11 +39,11 @@ export async function runSetDefault(input) {
     if (error !== undefined) {
         return { exitCode: 2, stdout: '', stderr: `kb set-default: ${error}\n` };
     }
-    const entries = config.entries;
     if (options.none) {
         await clearDefaultKb({ registryPath });
         return { exitCode: 0, stdout: 'The default knowledge base has been cleared.\n', stderr: '' };
     }
+    const entries = config.entries;
     if (options.name !== null) {
         if (entries.length === 0) {
             return { exitCode: 2, stdout: '', stderr: buildNoStoresMessage() };
@@ -118,6 +119,5 @@ function buildSetConfirmation(name) {
     return `Default knowledge base has been set to "${name}".\n`;
 }
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb set-default: ${message}\n${SET_DEFAULT_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb set-default: ${describeError(error)}\n${SET_DEFAULT_HELP}` };
 }

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

@@ -1,3 +1,4 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { enumerateNotes } from "../../check/enumerate.js";
 import { isKbLoaderError } from "../../config/kb-loader-error.js";
 import { loadKbConfig } from "../../config/load-config.js";
@@ -34,8 +35,7 @@ export async function runTaxonomy(input) {
         options = parseTaxonomyArgs(input.argv);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${message}\n${TAXONOMY_HELP}` };
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${describeError(error)}\n${TAXONOMY_HELP}` };
     }
     if (options.help) {
         return { exitCode: 0, stdout: TAXONOMY_HELP, stderr: '' };

package/dist/esm/cli/index.js

@@ -1,4 +1,5 @@
 import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { run } from "./run.js";
 import { readlineSelectKbPrompt } from "./select-kb-prompt.js";
 async function main() {
@@ -12,8 +13,7 @@ async function main() {
         });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`kb: unexpected error: ${message}\n`);
+        process.stderr.write(`kb: unexpected error: ${describeError(error)}\n`);
         process.exit(2);
     }
     if (output.stdout !== '')

package/dist/esm/cli/parse-flag-value.js

@@ -7,7 +7,7 @@ export function takeInlineValue(arg, prefix) {
 }
 export function takeValue(argv, index, flag) {
     const next = argv[index + 1] ?? null;
-    if (next === null || next.startsWith('--')) {
+    if (next === null || next === '' || next.startsWith('--')) {
         throw new Error(`${flag} requires a value`);
     }
     return next;

package/dist/esm/cli/run.js

@@ -12,9 +12,10 @@ Commands:
 
 Run "kb <command> --help" for command options.
 `;
+const HELP_COMMANDS = new Set([undefined, '--help', '-h']);
 export async function run(input) {
     const [command, ...rest] = input.argv;
-    if (command === undefined || command === '--help' || command === '-h') {
+    if (HELP_COMMANDS.has(command)) {
         return { exitCode: 0, stdout: HELP, stderr: '' };
     }
     if (command === 'check') {

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

@@ -14,7 +14,7 @@ export function parseSelection(answer, kbCount) {
     if (answer === '')
         return { kind: 'cancel' };
     const choice = Number(answer);
-    if (!Number.isInteger(choice))
+    if (!Number.isSafeInteger(choice))
         return null;
     if (choice >= 1 && choice <= kbCount)
         return { kind: 'kb', index: choice - 1 };

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

@@ -1,6 +1,7 @@
 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";
 export function resolveChangedPaths(input) {
     const { storeRoot, ref } = input;
@@ -37,7 +38,7 @@ function extractGitErrorMessage(error) {
     if (isRecord(error) && typeof error.stderr === 'string' && error.stderr.trim() !== '') {
         return error.stderr.trim();
     }
-    return error instanceof Error ? error.message : String(error);
+    return describeError(error);
 }
 function tryGit(storeRoot, args) {
     try {

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

@@ -1,5 +1,5 @@
 export declare class KbLoaderError extends Error {
     readonly kind: "KbLoaderError";
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export declare function isKbLoaderError(error: unknown): error is KbLoaderError;

package/dist/esm/config/kb-loader-error.js

@@ -1,7 +1,7 @@
 export class KbLoaderError extends Error {
     kind = 'KbLoaderError';
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'KbLoaderError';
     }
 }

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { parse } from 'yaml';
 import { CONFIG_FILE } from "../layout/index.js";
 import { isEnoent } from "../type-guards.js";
@@ -22,8 +23,7 @@ export async function loadKbConfig(input) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(error)}`, { cause: error });
     }
     const result = configFileShape.safeParse(parsed ?? {});
     if (!result.success) {

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

@@ -2,6 +2,7 @@ export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
 export interface CreatedStore {
     name: string;
     storePath: string;
+    description?: string;
     registered: boolean;
     created: readonly string[];
     defaultKb?: DefaultKbOutcome;
@@ -14,6 +15,7 @@ export type CreateInput = {
 } | {
     register: true;
     registryPath: string;
+    description?: string;
 });
 export type CreateOutcome = {
     ok: true;

package/dist/esm/create/create.js

@@ -22,12 +22,13 @@ export async function create(input) {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const created = await scaffold(storePath);
-    const result = await registerStore({ registryPath, name, storePath });
+    const described = input.description !== undefined && { description: input.description };
+    const result = await registerStore({ registryPath, name, storePath, ...described });
     if (result.status === 'already-present') {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const defaultKb = await ensureDefaultKb({ registryPath, name, before });
-    return { ok: true, created: { name, storePath, registered: true, created, defaultKb } };
+    return { ok: true, created: { name, storePath, ...described, registered: true, created, defaultKb } };
 }
 async function ensureDefaultKb(input) {
     if (input.before.defaultKb !== undefined) {

package/dist/esm/discovery/load-registry.js

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { parse } from 'yaml';
 import { isEnoent } from "../type-guards.js";
 import { kbRegistryFileSchema } from "./kb-registry-schema.js";
@@ -36,8 +38,7 @@ export async function tryLoadKbRegistry(input = {}) {
         return { config: await loadKbRegistry(input) };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { config: { entries: [], sources: {} }, error: message };
+        return { config: { entries: [], sources: {} }, error: describeError(error) };
     }
 }
 function expandTilde(value, home) {
@@ -65,8 +66,7 @@ async function loadRegistryFile(path, source, home) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`${path}: malformed YAML — ${message}`);
+        throw chainError(`${path}: malformed YAML`, error);
     }
     if (parsed === null || parsed === undefined) {
         return { entries: [] };
@@ -77,7 +77,8 @@ async function loadRegistryFile(path, source, home) {
     }
     const configDir = dirname(path);
     const entries = [];
-    for (const [name, fileEntry] of Object.entries(result.data.kbs ?? {})) {
+    const fileEntries = Object.entries(result.data.kbs ?? {});
+    for (const [name, fileEntry] of fileEntries) {
         entries.push({
             name,
             path: resolvePath(fileEntry.path, configDir, home),
@@ -96,7 +97,7 @@ function mergeEntries(userEntries, projectEntries) {
     for (const entry of projectEntries) {
         byName.set(entry.name, entry);
     }
-    return [...byName.values()];
+    return byName.values().toArray();
 }
 function resolveDefaultKb(entries, name, sourcePath) {
     if (name === undefined) {

package/dist/esm/discovery/register-store.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { isMap, isScalar } from 'yaml';
 import { kbRegistryFileSchema } from "./kb-registry-schema.js";
 import { loadRegistryDocument } from "./registry-document.js";
 export async function registerStore(input) {
@@ -11,11 +12,12 @@ export async function registerStore(input) {
     if (doc.hasIn(['kbs', input.name])) {
         return { status: 'already-present' };
     }
-    const entry = { path: input.storePath };
-    if (input.description !== undefined) {
-        entry.description = input.description;
-    }
+    const entry = {
+        ...(input.description !== undefined && { description: input.description }),
+        path: input.storePath,
+    };
     doc.setIn(['kbs', input.name], entry);
+    sortRegistryEntries(doc);
     const result = kbRegistryFileSchema.safeParse(doc.toJS());
     if (!result.success) {
         throw new Error(`${input.registryPath}: cannot register "${input.name}" — ${result.error.issues[0]?.message ?? 'invalid entry'}`);
@@ -24,3 +26,20 @@ export async function registerStore(input) {
     await writeFile(input.registryPath, doc.toString(), 'utf8');
     return { status: 'added' };
 }
+function compareRegistryNames(left, right) {
+    const caseInsensitive = left.localeCompare(right, 'en', { sensitivity: 'base' });
+    return caseInsensitive === 0 ? left.localeCompare(right) : caseInsensitive;
+}
+function sortRegistryEntries(doc) {
+    const kbs = doc.getIn(['kbs'], true);
+    if (!isMap(kbs)) {
+        return;
+    }
+    kbs.items.sort((left, right) => compareRegistryNames(readName(left.key), readName(right.key)));
+}
+function readName(key) {
+    if (isScalar(key)) {
+        return String(key.value);
+    }
+    return typeof key === 'string' ? key : '';
+}

package/dist/esm/frontmatter/parse-note.js

@@ -91,7 +91,7 @@ function toFrontmatter(doc) {
                 tags = stringList(item.value);
                 break;
             default:
-                extra[key] = key in plainRecord ? plainRecord[key] : null;
+                extra[key] = Object.hasOwn(plainRecord, key) ? plainRecord[key] : null;
         }
     }
     return { title, recordType, created, updated, tags, extra };

package/dist/esm/note-io/write-note.js

@@ -15,7 +15,11 @@ export async function writeNote(path, fields, body) {
         await rename(tempPath, path);
     }
     catch (error) {
-        await unlink(tempPath).catch(() => { });
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+        }
         throw error;
     }
 }

package/dist/esm/records/event.js

@@ -1,6 +1,7 @@
 import { asStringList, isValidDate } from "../note-io/field-validators.js";
 export const EVENT_IMPACT_LEVELS = ['low', 'medium', 'high', 'critical'];
 const IMPACT_LEVEL_SET = new Set(EVENT_IMPACT_LEVELS);
+const NOT_SUPPLIED_VALUES = new Set([undefined, null, '']);
 export function isEventImpact(value) {
     return typeof value === 'string' && IMPACT_LEVEL_SET.has(value);
 }
@@ -110,7 +111,7 @@ function readListField(value, field, errors) {
     return list;
 }
 function readOptionalNonEmptyString(value, field, errors) {
-    if (value === undefined || value === null || value === '') {
+    if (NOT_SUPPLIED_VALUES.has(value)) {
         return undefined;
     }
     if (typeof value === 'string') {

package/dist/esm/tags/load-aliases.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { parse } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
 import { ALIASES_FILE } from "../layout/index.js";
@@ -20,8 +22,7 @@ export async function loadAliases(input) {
         return parseAliases(text, path);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(message);
+        throw new KbLoaderError(describeError(error), { cause: error });
     }
 }
 export function parseAliases(text, contextLabel = 'tag-aliases') {
@@ -30,8 +31,7 @@ export function parseAliases(text, contextLabel = 'tag-aliases') {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`${contextLabel}: malformed YAML — ${message}`);
+        throw chainError(`${contextLabel}: malformed YAML`, error);
     }
     if (!isRecord(parsed)) {
         throw new Error(`${contextLabel}: top-level must be a mapping`);

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { parse } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
 import { TAXONOMY_FILE } from "../layout/index.js";
@@ -22,8 +23,7 @@ export async function loadTaxonomy(input) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(error)}`, { cause: error });
     }
     const result = taxonomyFileShape.safeParse(parsed ?? {});
     if (!result.success) {

package/dist/esm/taxonomy/write-taxonomy.js

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isMap, isPair, isScalar, parseDocument } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
 import { TAXONOMY_FILE } from "../layout/index.js";
@@ -98,7 +99,7 @@ async function readDocument(path) {
     const document = parseDocument(text);
     const firstError = document.errors[0];
     if (firstError !== undefined) {
-        throw new KbLoaderError(`${path}: malformed YAML — ${firstError.message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(firstError)}`, { cause: firstError });
     }
     if (document.contents !== null && !isMap(document.contents)) {
         throw new KbLoaderError(`${path}: top-level must be a mapping`);
@@ -136,7 +137,11 @@ async function writeAtomic(path, content) {
         await rename(tempPath, path);
     }
     catch (error) {
-        await unlink(tempPath).catch(() => { });
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+        }
         throw error;
     }
 }

package/dist/esm/vault-integrity/check-vault-integrity.js

@@ -6,7 +6,7 @@ export function checkVaultIntegrity(notes) {
 }
 function basenameFindings(vaultIndex) {
     const findings = [];
-    for (const key of [...vaultIndex.keys()].toSorted()) {
+    for (const key of vaultIndex.keys().toArray().toSorted()) {
         const paths = vaultIndex.get(key);
         if (paths === undefined || paths.size < 2)
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -19,6 +19,7 @@
   },
   "license": "ISC",
   "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -96,6 +97,7 @@
     "dist"
   ],
   "dependencies": {
+    "@williamthorsen/toolbelt.errors": "0.3.0",
     "picomatch": "4.0.5",
     "yaml": "2.9.0",
     "zod": "4.4.3"
@@ -109,7 +111,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "nmr compile"
-  }
+  "scripts": {}
 }