@williamthorsen/kb 0.3.1 → 0.5.0

package/README.md

@@ -4,11 +4,21 @@ Foundation library for knowledge-base tooling.
 Provides knowledge-base discovery, registry loading, frontmatter parsing and writing, tag canonicalization, and type-blind vault-integrity checks.
 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 --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.5.0 (2026-08-08)
+
+### 🎉 Features
+
+- Register a new store with a description and keep the registry sorted (#1237)
+
+  Adds a `--description` flag to `kb create`, so that a new knowledge base can be given a description as it is created. Alphabetical ordering of keys in `kb.yaml` is now enforced on every write.
+
+  Also fixes an issue where creating a knowledge base under an empty name could leave a stray registry entry. Across the CLI, a flag given an empty value is now refused.
+<!-- /section:release-notes -->
 
 ## Exports
 
-The package exposes ten subpath entries plus a root barrel:
+The package exposes twelve subpath entries plus a root barrel:
 
 | Entry               | Description                                                                    |
 | ------------------- | ------------------------------------------------------------------------------ |
@@ -19,9 +29,11 @@ The package exposes ten subpath entries plus a root barrel:
 | `./discovery`       | KB root discovery and `kb.yaml` registry loading, merging, and writing         |
 | `./filesystem`      | Filesystem-existence helpers with an explicit absence policy                   |
 | `./frontmatter`     | Note parsing into typed frontmatter and writing it back to YAML                |
+| `./layout`          | The store's on-disk layout: every path inside a `.kb/` store derives from here |
 | `./note-io`         | Type-blind note read/write as an ordered frontmatter field map                 |
 | `./records`         | The typed `assertion`/`event` record parsers and renderers                     |
 | `./tags`            | `.kb/tag-aliases.yaml` loading and tag canonicalization                        |
+| `./taxonomy`        | `.kb/taxonomy.yaml` loading, comment-preserving declaration, and path mapping  |
 | `./vault-integrity` | Type-blind `[[link]]` resolution and basename-uniqueness over a note set       |
 
 Every public function takes a single plain-object input so a future MCP wrapper can mechanically bind Zod-validated payloads.
@@ -112,6 +124,8 @@ missing files (when a path is given) throw.
 
 The type-blind per-note lints — `tagAliasFindings(note, aliases)` (`tag-alias`, warning) and `pathsFindings(note)` (`paths.user-home`, error) — catch what write-time record validation can't: alias-vocabulary drift and hardcoded `/Users/{name}/` paths in captured content.
 
+`taxonomyFindings({ notes, taxonomy, config, taxonomyPath })` reports where a store's assertion folders and its declared taxonomy disagree (see [`.kb/taxonomy.yaml`](#the-declared-structure-kbtaxonomyyaml)). Its findings carry `scope: 'vault'`: they describe the store rather than any one note, so a consumer that narrows a report to selected notes must keep them rather than filter them out by path.
+
 ```ts
 import { checkVaultIntegrity } from '@williamthorsen/kb/vault-integrity';
 
@@ -120,7 +134,7 @@ const findings = checkVaultIntegrity(notes);
 
 ## Checking a store
 
-`check({ kbRoot })` runs a store's full check in one call: it loads `.kb/config.yaml` and `.kb/tag-aliases.yaml`, enumerates the notes the config selects, and composes whole-vault integrity with the `tag-alias` and `paths` lints. It performs no frontmatter validation — record types own that at write time. It returns **both** the enumerated notes and the findings, so a consumer can layer its own detectors over the same enumeration without walking the store twice.
+`check({ kbRoot })` runs a store's full check in one call: it loads `.kb/config.yaml`, `.kb/tag-aliases.yaml`, and `.kb/taxonomy.yaml`, enumerates the notes the config selects, and composes whole-vault integrity and taxonomy drift with the `tag-alias` and `paths` lints. It performs no frontmatter validation — record types own that at write time. It returns **both** the enumerated notes and the findings, so a consumer can layer its own detectors over the same enumeration without walking the store twice.
 
 ```ts
 import { check } from '@williamthorsen/kb/check';
@@ -128,7 +142,9 @@ import { check } from '@williamthorsen/kb/check';
 const { notes, findings } = await check({ kbRoot });
 ```
 
-A structural defect in either loaded file throws a `KbLoaderError` (see below). Any other error from enumeration or the checks propagates unchanged.
+A structural defect in any loaded file throws a `KbLoaderError` (see below). Any other error from enumeration or the checks propagates unchanged.
+
+`enumerateNotes({ kbRoot, config })` performs the enumeration on its own, and `enumerateNotePaths({ kbRoot, config })` returns the same note set as store-root-relative paths without opening a single note. Both are exported from `@williamthorsen/kb/check`; the paths-only variant serves a caller that needs the note set's shape rather than its content.
 
 ### Which notes are checked: `.kb/config.yaml`
 
@@ -149,18 +165,49 @@ exclude:
 
 Matching uses dotfile-insensitive globbing, so dot-directories (`.kb`, `.git`, `.agents`) are skipped without naming them. The default targets the `content/`-scoped layout; a store with a different layout overrides `targets` to match. `loadKbConfig({ kbRoot })` returns the effective config and is exported from `@williamthorsen/kb/config`.
 
+### The declared structure: `.kb/taxonomy.yaml`
+
+`.kb/taxonomy.yaml` states where a store's assertions are meant to live. It is the source of truth for intended structure: folders on disk are derived from it, not the reverse. It governs `content/assertions/` only, since `content/events/` is flat and ULID-keyed.
+
+```yaml
+# .kb/taxonomy.yaml
+domains:
+  engineering: Software engineering practice
+  engineering/tooling: Build, test, and development tooling
+provisional:
+  engineering/tooling/versioning: Release and version management
+  languages:
+```
+
+Two disjoint maps of domain path to one-line description. `domains` holds reviewed declarations and `provisional` holds those declared but not yet reviewed; promotion is writing a description and moving the line up. A domain may be declared without a description, as `languages` is above.
+
+Keys are relative to `content/assertions/` and may nest to any depth. Parents are not implied: declaring `engineering/tooling` does not declare `engineering`. A path declared in both maps fails the load, as does a malformed key — one restating the `content/assertions/` prefix, or carrying a leading or trailing slash, an empty segment, or a `.`/`..` segment.
+
+An absent taxonomy, and one present but declaring nothing, are both valid and report nothing, so the rules apply only to a store that has adopted a taxonomy. Three warnings report drift once one has:
+
+| Rule                  | Meaning                                         |
+| --------------------- | ----------------------------------------------- |
+| `taxonomy.undeclared` | A folder holds notes but no domain declares it. |
+| `taxonomy.unused`     | A declared domain has no note at or beneath it. |
+| `taxonomy.orphan`     | A declared domain's parent is undeclared.       |
+
+A domain counts as used when any note lives at or beneath it, so a grouping domain that holds only subfolders is not reported unused. A domain inside a `config.exclude` subtree is exempt from `taxonomy.unused`, since its notes never enumerate.
+
+`loadTaxonomy({ kbRoot })` reads both blocks into one map of domain path to `{ description, provisional }`, and `writeTaxonomy({ kbRoot, declarations })` declares domains while preserving the file's existing comments, key order, and formatting. `resolveDomain(relativePath)` maps a store-root-relative note path to the domain it sits in (`undefined` for a non-assertion or a note at the assertions root), and `resolveParent(path)` yields a domain's parent (`undefined` at the top level); the drift rules and the back-fill both derive their answers from this pair, so a consumer that classifies notes against the taxonomy stays in agreement with what `kb check` reports. All four are exported from `@williamthorsen/kb/taxonomy`.
+
 ## The `kb` command
 
-The package ships a `kb` bin with three subcommands: `create`, `set-default`, and `check`.
+The package ships a `kb` bin with four subcommands: `check`, `create`, `set-default`, and `taxonomy`.
 
 ### kb create
 
 `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:
@@ -173,7 +220,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.
 
@@ -213,15 +260,31 @@ Because the exit code reflects only the selected notes, a per-batch or pre-commi
 
 Exit codes:
 
-| Code | Meaning                                                                                                                     |
-| ---- | --------------------------------------------------------------------------------------------------------------------------- |
-| `0`  | No error-severity findings in the checked notes (warnings are allowed). A run that selects no notes also exits 0.           |
-| `1`  | One or more error-severity findings in the checked notes.                                                                   |
-| `2`  | A usage error, an unresolvable store or `--vs` ref, a path matching no note, or a malformed `config` or `tag-aliases` file. |
+| Code | Meaning                                                                                                                                  |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | No error-severity findings in the checked notes (warnings are allowed). A run that selects no notes also exits 0.                        |
+| `1`  | One or more error-severity findings in the checked notes.                                                                                |
+| `2`  | A usage error, an unresolvable store or `--vs` ref, a path matching no note, or a malformed `config`, `tag-aliases`, or `taxonomy` file. |
+
+A finding carrying `scope: 'vault'` describes the store rather than any one note, so it is reported under every run, including a targeted one, a `--vs` one, and one that matched no notes at all. The taxonomy rules are the ones that produce them.
+
+### kb taxonomy
+
+`kb taxonomy init` derives a starting taxonomy from the notes a store already holds, so a taxonomy can be introduced to a populated store without every folder reporting as undeclared.
+
+```bash
+kb taxonomy init             # declare every folder holding notes, and its ancestors
+kb taxonomy init --kb coding # back-fill the named store from the kb.yaml registry
+kb taxonomy init --merge     # add only the domains an existing taxonomy omits
+```
+
+Every derived domain lands under `provisional:` with no description: the command cannot invent descriptions, and provisional already means "declared, not yet reviewed". Because the derivation reads the same enumeration `kb check` does, a back-filled store reports no taxonomy drift.
+
+Without `--merge`, a store that already declares a taxonomy is left untouched and the command exits 2.
 
 ## Error and exception model
 
-The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`) **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. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
 
 ## MCP wrappability
 

package/dist/esm/check/check.js

@@ -1,16 +1,24 @@
+import { join } from 'node:path';
 import { loadKbConfig } from "../config/load-config.js";
-import { resolveKbDir } from "../layout/index.js";
+import { resolveKbDir, TAXONOMY_FILE } from "../layout/index.js";
 import { pathsFindings } from "../lints/paths.js";
 import { tagAliasFindings } from "../lints/tag-alias.js";
+import { taxonomyFindings } from "../lints/taxonomy.js";
 import { loadAliases } from "../tags/load-aliases.js";
+import { loadTaxonomy } from "../taxonomy/load-taxonomy.js";
 import { checkVaultIntegrity } from "../vault-integrity/check-vault-integrity.js";
 import { enumerateNotes } from "./enumerate.js";
 export async function check(input) {
     const kbRoot = { path: input.kbRoot, kbDir: resolveKbDir(input.kbRoot) };
-    const [config, aliases] = await Promise.all([loadKbConfig({ kbRoot }), loadAliases({ kbRoot })]);
+    const [config, aliases, taxonomy] = await Promise.all([
+        loadKbConfig({ kbRoot }),
+        loadAliases({ kbRoot }),
+        loadTaxonomy({ kbRoot }),
+    ]);
     const notes = await enumerateNotes({ kbRoot: input.kbRoot, config });
     const findings = [
         ...checkVaultIntegrity(notes),
+        ...taxonomyFindings({ notes, taxonomy, config, taxonomyPath: join(input.kbRoot, TAXONOMY_FILE) }),
         ...notes.flatMap((note) => [...tagAliasFindings(note, aliases), ...pathsFindings(note)]),
     ];
     return { config, notes, findings };

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

@@ -8,6 +8,10 @@ export interface EnumeratedNote {
     bodyStartLine: number;
     error?: string;
 }
+export declare function enumerateNotePaths(input: {
+    kbRoot: string;
+    config: KbConfig;
+}): Promise<string[]>;
 export declare function enumerateNotes(input: {
     kbRoot: string;
     config: KbConfig;

package/dist/esm/check/enumerate.js

@@ -4,13 +4,41 @@ import process from 'node:process';
 import { createNoteScopeMatcher } from "../config/note-scope.js";
 import { readNoteContent } from "../note-io/read-note.js";
 import { isGlobSegment } from "./glob-segments.js";
+export async function enumerateNotePaths(input) {
+    const locations = await collectNoteLocations(input);
+    return locations.map((location) => location.relativePath);
+}
 export async function enumerateNotes(input) {
+    const locations = await collectNoteLocations(input);
+    const notes = [];
+    for (const { path, relativePath } of locations) {
+        try {
+            const content = await readFile(path, 'utf8');
+            const { fields, body, bodyStartLine, error: parseError } = readNoteContent(content);
+            notes.push({
+                path,
+                relativePath,
+                fields,
+                body,
+                content,
+                bodyStartLine,
+                ...(parseError !== undefined && { error: parseError }),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`kb: warning: could not read note ${path}; skipping: ${message}\n`);
+        }
+    }
+    return notes;
+}
+async function collectNoteLocations(input) {
     const { kbRoot, config } = input;
     const matcher = createNoteScopeMatcher(config);
     const topLevelDirs = leadingLiteralSegments(config.targets);
-    const notes = [];
-    await walk({ root: kbRoot, dir: kbRoot, matcher, topLevelDirs, out: notes });
-    return notes;
+    const locations = [];
+    await walk({ root: kbRoot, dir: kbRoot, matcher, topLevelDirs, out: locations });
+    return locations;
 }
 function leadingLiteralSegments(targets) {
     const dirs = new Set();
@@ -50,22 +78,6 @@ async function walk(input) {
             continue;
         if (!matcher.isNote(relativePath))
             continue;
-        try {
-            const content = await readFile(absolutePath, 'utf8');
-            const { fields, body, bodyStartLine, error: parseError } = readNoteContent(content);
-            out.push({
-                path: absolutePath,
-                relativePath,
-                fields,
-                body,
-                content,
-                bodyStartLine,
-                ...(parseError !== undefined && { error: parseError }),
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`kb: warning: could not read note ${absolutePath}; skipping: ${message}\n`);
-        }
+        out.push({ path: absolutePath, relativePath });
     }
 }

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

@@ -1,2 +1,2 @@
 export { check, type CheckResult } from './check.js';
-export { type EnumeratedNote, enumerateNotes } from './enumerate.js';
+export { type EnumeratedNote, enumerateNotePaths, enumerateNotes } from './enumerate.js';

package/dist/esm/check/index.js

@@ -1,2 +1,2 @@
 export { check } from "./check.js";
-export { enumerateNotes } from "./enumerate.js";
+export { enumerateNotePaths, enumerateNotes } from "./enumerate.js";

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

@@ -1,8 +1,8 @@
 import { check } from "../../check/check.js";
 import { isKbLoaderError } from "../../config/kb-loader-error.js";
-import { findKbRoot } from "../../discovery/find-kb-root.js";
-import { tryLoadKbRegistry } from "../../discovery/load-registry.js";
 import { formatHuman, formatJson, summarize } from "../format.js";
+import { takeInlineValue, takeValue } from "../parse-flag-value.js";
+import { resolveStore } from "../resolve-store.js";
 import { resolveChangedPaths } from "../targeting/resolve-changed-paths.js";
 import { selectNotes } from "../targeting/select-notes.js";
 export const CHECK_HELP = `Usage: kb check [paths...] [options]
@@ -142,38 +142,6 @@ async function resolveSelection(input) {
         return { ok: false, message: `no notes matched: ${selection.unmatched.join(', ')}` };
     }
     const selectedPaths = new Set(selection.selected.map((entry) => entry.path));
-    const findings = result.findings.filter((finding) => selectedPaths.has(finding.path));
+    const findings = result.findings.filter((finding) => finding.scope === 'vault' || selectedPaths.has(finding.path));
     return { ok: true, scope, notes: selection.selected, findings };
 }
-async function resolveStore(input) {
-    if (input.explicitKb !== null) {
-        const { config } = await tryLoadKbRegistry({
-            projectDir: input.cwd,
-            ...(input.home !== undefined && { home: input.home }),
-        });
-        const match = config.entries.find((entry) => entry.name === input.explicitKb);
-        if (match === undefined) {
-            return { ok: false, message: `--kb "${input.explicitKb}" does not match any registered knowledge base` };
-        }
-        return { ok: true, store: { name: match.name, path: match.path } };
-    }
-    const discovered = await findKbRoot({ startDir: input.cwd });
-    if (discovered === null) {
-        return { ok: false, message: 'no .kb/ directory found in the current directory or any ancestor' };
-    }
-    return { ok: true, store: { name: null, path: discovered.path } };
-}
-function takeInlineValue(arg, prefix) {
-    const value = arg.slice(prefix.length);
-    if (value === '') {
-        throw new Error(`${prefix.replace(/=$/, '')} requires a value`);
-    }
-    return value;
-}
-function takeValue(argv, index, flag) {
-    const next = argv[index + 1] ?? null;
-    if (next === null || next.startsWith('--')) {
-        throw new Error(`${flag} requires a value`);
-    }
-    return next;
-}

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,14 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 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 +18,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 +42,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 +66,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,30 +78,34 @@ 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) {
@@ -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/taxonomy.d.ts

@@ -0,0 +1,15 @@
+import type { CommandOutput } from './check.js';
+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 function runTaxonomy(input: {
+    argv: readonly string[];
+    cwd: string;
+    home?: string;
+}): Promise<CommandOutput>;
+interface TaxonomyOptions {
+    subcommand: 'init' | null;
+    kb: string | null;
+    merge: boolean;
+    help: boolean;
+}
+export declare function parseTaxonomyArgs(argv: readonly string[]): TaxonomyOptions;
+export {};

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

@@ -0,0 +1,130 @@
+import { enumerateNotes } from "../../check/enumerate.js";
+import { isKbLoaderError } from "../../config/kb-loader-error.js";
+import { loadKbConfig } from "../../config/load-config.js";
+import { resolveKbDir, TAXONOMY_FILE } from "../../layout/index.js";
+import { deriveDomains } from "../../taxonomy/domain-paths.js";
+import { loadTaxonomy } from "../../taxonomy/load-taxonomy.js";
+import { writeTaxonomy } from "../../taxonomy/write-taxonomy.js";
+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".
+
+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.
+  -h, --help    Show this help.
+
+Exit codes:
+  0  the taxonomy was written, or already declared every derived domain
+  2  usage error, unresolvable store, a store marked readonly in kb.yaml,
+     malformed config or taxonomy, or an existing taxonomy without --merge
+`;
+export async function runTaxonomy(input) {
+    let options;
+    try {
+        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}` };
+    }
+    if (options.help) {
+        return { exitCode: 0, stdout: TAXONOMY_HELP, stderr: '' };
+    }
+    if (options.subcommand === null) {
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: no subcommand given\n${TAXONOMY_HELP}` };
+    }
+    const resolved = await resolveStore({
+        explicitKb: options.kb,
+        cwd: input.cwd,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (!resolved.ok) {
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${resolved.message}\n` };
+    }
+    if (resolved.readonly) {
+        const name = resolved.store.name ?? resolved.store.path;
+        const message = `knowledge base "${name}" is marked readonly in kb.yaml; taxonomy init is refused`;
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${message}\n` };
+    }
+    const kbRoot = { path: resolved.store.path, kbDir: resolveKbDir(resolved.store.path) };
+    try {
+        return await initTaxonomy({ kbRoot, merge: options.merge });
+    }
+    catch (error) {
+        if (isKbLoaderError(error)) {
+            return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${error.message}\n` };
+        }
+        throw error;
+    }
+}
+export function parseTaxonomyArgs(argv) {
+    let subcommand = null;
+    let kb = null;
+    let merge = false;
+    let help = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--merge') {
+            merge = true;
+            continue;
+        }
+        if (arg === '--kb') {
+            kb = takeValue(argv, index, '--kb');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--kb=')) {
+            kb = takeInlineValue(arg, '--kb=');
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`unknown flag: ${arg}`);
+        }
+        if (arg !== 'init') {
+            throw new Error(`unknown subcommand: ${arg}`);
+        }
+        if (subcommand !== null) {
+            throw new Error('only one subcommand may be given');
+        }
+        subcommand = arg;
+    }
+    return { subcommand, kb, merge, help };
+}
+async function initTaxonomy(input) {
+    const { kbRoot, merge } = input;
+    const existing = await loadTaxonomy({ kbRoot });
+    if (existing.size > 0 && !merge) {
+        const message = `${TAXONOMY_FILE} already declares ${existing.size} domains; pass --merge to add the missing ones`;
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${message}\n` };
+    }
+    const config = await loadKbConfig({ kbRoot });
+    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: '' };
+    }
+    const { added } = await writeTaxonomy({
+        kbRoot,
+        declarations: domains.map((path) => ({ path, provisional: true })),
+    });
+    if (added.length === 0) {
+        return { exitCode: 0, stdout: `${TAXONOMY_FILE} already declares every derived domain\n`, stderr: '' };
+    }
+    return { exitCode: 0, stdout: `declared ${added.length} domains in ${TAXONOMY_FILE}\n`, stderr: '' };
+}

package/dist/esm/cli/format.js

@@ -1,12 +1,15 @@
 export function formatHuman(input) {
     const { summary, findings, targets, scope } = input;
-    if (summary.notes === 0) {
+    if (summary.notes === 0 && findings.length === 0) {
         return `${zeroMatchLine(scope, targets)}\n`;
     }
     if (findings.length === 0) {
         return `✓ no findings (${summary.notes} notes checked)\n`;
     }
     const lines = [];
+    if (summary.notes === 0) {
+        lines.push(zeroMatchLine(scope, targets), '');
+    }
     for (const [path, group] of groupByPath(findings)) {
         lines.push(path);
         for (const finding of group) {

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

@@ -0,0 +1,2 @@
+export declare function takeInlineValue(arg: string, prefix: string): string;
+export declare function takeValue(argv: readonly string[], index: number, flag: string): string;

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

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