@williamthorsen/kb 0.3.0 → 0.4.0

package/README.md

@@ -5,18 +5,22 @@ 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.3.0 (2026-08-04)
+## Release notes — v0.4.0 (2026-08-07)
 
 ### 🎉 Features
 
-- Make codeassembly and kb CLI tools publishable (#1164)
+- Add the .kb/taxonomy.yaml format with drift reporting and back-fill (#1210)
 
-  The `codeassembly` CLI now installs from npm, and its `install` and `sync` commands deploy the rulebooks, skills, and subagents it ships into any consuming project. The knowledge-base library `@williamthorsen/kb` and the session-lifecycle event package `codeassembly-lifecycle` are published alongside it.
+  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.
 <!-- /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                                                                    |
 | ------------------- | ------------------------------------------------------------------------------ |
@@ -27,9 +31,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.
@@ -120,6 +126,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';
 
@@ -128,7 +136,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';
@@ -136,7 +144,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`
 
@@ -157,9 +167,39 @@ 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
 
@@ -221,15 +261,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/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.startsWith('--')) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return next;
+}

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

@@ -0,0 +1,14 @@
+import type { StoreRef } from './format.js';
+export type ResolveStoreOutcome = {
+    ok: true;
+    store: StoreRef;
+    readonly: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function resolveStore(input: {
+    explicitKb: string | null;
+    cwd: string;
+    home?: string;
+}): Promise<ResolveStoreOutcome>;

package/dist/esm/cli/resolve-store.js

@@ -0,0 +1,25 @@
+import { findKbRoot } from "../discovery/find-kb-root.js";
+import { tryLoadKbRegistry } from "../discovery/load-registry.js";
+export async function resolveStore(input) {
+    const { config } = await tryLoadKbRegistry({
+        projectDir: input.cwd,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (input.explicitKb !== null) {
+        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 }, readonly: match.readonly ?? false };
+    }
+    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' };
+    }
+    const registered = config.entries.find((entry) => entry.path === discovered.path);
+    return {
+        ok: true,
+        store: { name: registered?.name ?? null, path: discovered.path },
+        readonly: registered?.readonly ?? false,
+    };
+}

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

@@ -1,6 +1,6 @@
 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\nRun \"kb <command> --help\" for command options.\n";
+export declare const HELP = "Usage: kb <command> [options]\n\nCommands:\n  check        Validate a knowledge base, optionally scoped to selected notes.\n  create       Scaffold a new knowledge base and register it in the kb.yaml registry.\n  set-default  Set, clear, or choose the default knowledge base.\n  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.\n\nRun \"kb <command> --help\" for command options.\n";
 export declare function run(input: {
     argv: readonly string[];
     cwd: string;

package/dist/esm/cli/run.js

@@ -1,12 +1,14 @@
 import { runCheck } from "./commands/check.js";
 import { runCreate } from "./commands/create.js";
 import { runSetDefault } from "./commands/set-default.js";
+import { runTaxonomy } from "./commands/taxonomy.js";
 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.
   set-default  Set, clear, or choose the default knowledge base.
+  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.
 
 Run "kb <command> --help" for command options.
 `;
@@ -26,6 +28,9 @@ export async function run(input) {
             ...(input.selectKb !== undefined && { selectKb: input.selectKb }),
         });
     }
+    if (command === 'taxonomy') {
+        return runTaxonomy({ argv: rest, cwd: input.cwd, ...(input.home !== undefined && { home: input.home }) });
+    }
     if (command === 'set-default') {
         return runSetDefault({
             argv: rest,

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

@@ -1 +1 @@
-export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, } from './store-layout.js';
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, TAXONOMY_FILE, } from './store-layout.js';

package/dist/esm/layout/index.js

@@ -1 +1 @@
-export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, } from "./store-layout.js";
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, TAXONOMY_FILE, } from "./store-layout.js";

package/dist/esm/layout/store-layout.d.ts

@@ -5,6 +5,7 @@ export declare const ALIASES_FILE = ".kb/tag-aliases.yaml";
 export declare const ASSERTIONS_DIR = "content/assertions";
 export declare const CONFIG_FILE = ".kb/config.yaml";
 export declare const EVENTS_DIR = "content/events";
+export declare const TAXONOMY_FILE = ".kb/taxonomy.yaml";
 export declare function buildEventPath(id: string): string;
 export declare function resolveAssertionsDir(storePath: string): string;
 export declare function resolveEventPath(input: {

package/dist/esm/layout/store-layout.js

@@ -6,6 +6,7 @@ export const ALIASES_FILE = `${KB_DIR}/tag-aliases.yaml`;
 export const ASSERTIONS_DIR = `${CONTENT_DIR}/${ASSERTIONS_SEGMENT}`;
 export const CONFIG_FILE = `${KB_DIR}/config.yaml`;
 export const EVENTS_DIR = `${CONTENT_DIR}/events`;
+export const TAXONOMY_FILE = `${KB_DIR}/taxonomy.yaml`;
 export function buildEventPath(id) {
     return `${EVENTS_DIR}/${id}.md`;
 }

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

@@ -1,2 +1,3 @@
 export { pathsFindings, type PathsNote } from './paths.js';
 export { tagAliasFindings, type TagAliasNote } from './tag-alias.js';
+export { taxonomyFindings, type TaxonomyNote } from './taxonomy.js';

package/dist/esm/lints/index.js

@@ -1,2 +1,3 @@
 export { pathsFindings } from "./paths.js";
 export { tagAliasFindings } from "./tag-alias.js";
+export { taxonomyFindings } from "./taxonomy.js";

package/dist/esm/lints/taxonomy.d.ts

@@ -0,0 +1,12 @@
+import type { KbConfig } from '../config/config-schema.js';
+import type { Taxonomy } from '../taxonomy/taxonomy-schema.js';
+import type { Finding } from '../types.js';
+export interface TaxonomyNote {
+    relativePath: string;
+}
+export declare function taxonomyFindings(input: {
+    notes: readonly TaxonomyNote[];
+    taxonomy: Taxonomy;
+    config: KbConfig;
+    taxonomyPath: string;
+}): Finding[];

package/dist/esm/lints/taxonomy.js

@@ -0,0 +1,52 @@
+import { createNoteScopeMatcher } from "../config/note-scope.js";
+import { ASSERTIONS_DIR } from "../layout/index.js";
+import { resolveDomain, resolveParent } from "../taxonomy/domain-paths.js";
+export function taxonomyFindings(input) {
+    const { notes, taxonomy, config, taxonomyPath } = input;
+    const declared = taxonomy.keys().toArray().toSorted();
+    if (declared.length === 0) {
+        return [];
+    }
+    const observed = new Set();
+    for (const note of notes) {
+        const domain = resolveDomain(note.relativePath);
+        if (domain !== undefined) {
+            observed.add(domain);
+        }
+    }
+    const matcher = createNoteScopeMatcher(config);
+    const findings = [];
+    for (const domain of [...observed].toSorted()) {
+        if (!taxonomy.has(domain)) {
+            findings.push(buildFinding(taxonomyPath, 'undeclared', `folder "${domain}" holds notes but no domain declares it`));
+        }
+    }
+    for (const domain of declared) {
+        if (holdsNote(domain, observed) || matcher.isExcluded(`${ASSERTIONS_DIR}/${domain}`)) {
+            continue;
+        }
+        findings.push(buildFinding(taxonomyPath, 'unused', `domain "${domain}" is declared but holds no notes`));
+    }
+    for (const domain of declared) {
+        const parent = resolveParent(domain);
+        if (parent !== undefined && !taxonomy.has(parent)) {
+            findings.push(buildFinding(taxonomyPath, 'orphan', `domain "${domain}" is declared but its parent "${parent}" is not`));
+        }
+    }
+    return findings;
+}
+function buildFinding(taxonomyPath, rule, message) {
+    return { path: taxonomyPath, scope: 'vault', rule: `taxonomy.${rule}`, severity: 'warning', message };
+}
+function holdsNote(domain, observed) {
+    if (observed.has(domain)) {
+        return true;
+    }
+    const prefix = `${domain}/`;
+    for (const candidate of observed) {
+        if (candidate.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/esm/taxonomy/domain-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function deriveDomains(relativePaths: Iterable<string>): string[];
+export declare function resolveDomain(relativePath: string): string | undefined;
+export declare function resolveParent(path: string): string | undefined;

package/dist/esm/taxonomy/domain-paths.js

@@ -0,0 +1,23 @@
+import { ASSERTIONS_DIR } from "../layout/index.js";
+export function deriveDomains(relativePaths) {
+    const domains = new Set();
+    for (const relativePath of relativePaths) {
+        let domain = resolveDomain(relativePath);
+        while (domain !== undefined) {
+            domains.add(domain);
+            domain = resolveParent(domain);
+        }
+    }
+    return domains.values().toArray().toSorted();
+}
+export function resolveDomain(relativePath) {
+    const prefix = `${ASSERTIONS_DIR}/`;
+    if (!relativePath.startsWith(prefix)) {
+        return undefined;
+    }
+    return resolveParent(relativePath.slice(prefix.length));
+}
+export function resolveParent(path) {
+    const lastSlash = path.lastIndexOf('/');
+    return lastSlash === -1 ? undefined : path.slice(0, lastSlash);
+}

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

@@ -0,0 +1,4 @@
+export { resolveDomain, resolveParent } from './domain-paths.js';
+export { loadTaxonomy } from './load-taxonomy.js';
+export { describeKeyDefect, type Taxonomy, type TaxonomyEntry, taxonomyFileShape } from './taxonomy-schema.js';
+export { type TaxonomyDeclaration, writeTaxonomy } from './write-taxonomy.js';

package/dist/esm/taxonomy/index.js

@@ -0,0 +1,4 @@
+export { resolveDomain, resolveParent } from "./domain-paths.js";
+export { loadTaxonomy } from "./load-taxonomy.js";
+export { describeKeyDefect, taxonomyFileShape } from "./taxonomy-schema.js";
+export { writeTaxonomy } from "./write-taxonomy.js";

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

@@ -0,0 +1,5 @@
+import type { KbRoot } from '../types.js';
+import { type Taxonomy } from './taxonomy-schema.js';
+export declare function loadTaxonomy(input: {
+    kbRoot: KbRoot;
+}): Promise<Taxonomy>;

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

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { KbLoaderError } from "../config/kb-loader-error.js";
+import { TAXONOMY_FILE } from "../layout/index.js";
+import { isEnoent } from "../type-guards.js";
+import { describeKeyDefect, taxonomyFileShape } from "./taxonomy-schema.js";
+export async function loadTaxonomy(input) {
+    const path = join(input.kbRoot.path, TAXONOMY_FILE);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return new Map();
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+    }
+    const result = taxonomyFileShape.safeParse(parsed ?? {});
+    if (!result.success) {
+        throw new KbLoaderError(`${path}: invalid taxonomy.yaml${describeIssueLocation(result.error)}`);
+    }
+    const entries = new Map();
+    collectBlock({ entries, block: result.data.domains ?? undefined, provisional: false, path });
+    collectBlock({ entries, block: result.data.provisional ?? undefined, provisional: true, path });
+    return entries;
+}
+function collectBlock(input) {
+    const { entries, block, provisional, path } = input;
+    if (block === undefined) {
+        return;
+    }
+    for (const [key, description] of Object.entries(block)) {
+        const defect = describeKeyDefect(key);
+        if (defect !== undefined) {
+            throw new KbLoaderError(`${path}: domain "${key}" ${defect}`);
+        }
+        if (entries.has(key)) {
+            throw new KbLoaderError(`${path}: domain "${key}" is declared in both domains and provisional`);
+        }
+        entries.set(key, { description: description ?? '', provisional });
+    }
+}
+function describeIssueLocation(error) {
+    const issue = error.issues[0];
+    if (issue === undefined) {
+        return ' — unknown error';
+    }
+    const location = issue.path.length > 0 ? ` at ${issue.path.join('.')}` : '';
+    return `${location} — ${issue.message}`;
+}

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

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare function describeKeyDefect(key: string): string | undefined;
+export type Taxonomy = ReadonlyMap<string, TaxonomyEntry>;
+export interface TaxonomyEntry {
+    description: string;
+    provisional: boolean;
+}
+export declare const taxonomyFileShape: z.ZodObject<{
+    domains: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>>;
+    provisional: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>>;
+}, z.core.$strip>;

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

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { ASSERTIONS_DIR, ASSERTIONS_SEGMENT, CONTENT_DIR } from "../layout/index.js";
+export function describeKeyDefect(key) {
+    if (key === '') {
+        return 'is empty';
+    }
+    if (key.includes('\\')) {
+        return 'contains a backslash; domain paths are slash-separated';
+    }
+    if (key.startsWith('/') || key.endsWith('/')) {
+        return 'has a leading or trailing slash';
+    }
+    const segments = key.split('/');
+    if (segments.some((segment) => segment.trim() === '')) {
+        return 'has an empty segment';
+    }
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        return 'has a "." or ".." segment';
+    }
+    if (segments[0] === ASSERTIONS_SEGMENT || (segments[0] === CONTENT_DIR && segments[1] === ASSERTIONS_SEGMENT)) {
+        return `restates the ${ASSERTIONS_DIR}/ prefix, which every key implies`;
+    }
+    return undefined;
+}
+export const taxonomyFileShape = z.object({
+    domains: z.record(z.string(), z.string().nullable()).nullable().optional(),
+    provisional: z.record(z.string(), z.string().nullable()).nullable().optional(),
+});

package/dist/esm/taxonomy/write-taxonomy.d.ts

@@ -0,0 +1,12 @@
+import type { KbRoot } from '../types.js';
+export interface TaxonomyDeclaration {
+    path: string;
+    description?: string;
+    provisional: boolean;
+}
+export declare function writeTaxonomy(input: {
+    kbRoot: KbRoot;
+    declarations: readonly TaxonomyDeclaration[];
+}): Promise<{
+    added: string[];
+}>;

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

@@ -0,0 +1,142 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMap, isPair, isScalar, parseDocument } from 'yaml';
+import { KbLoaderError } from "../config/kb-loader-error.js";
+import { TAXONOMY_FILE } from "../layout/index.js";
+import { isEnoent, isRecord } from "../type-guards.js";
+import { describeKeyDefect } from "./taxonomy-schema.js";
+const BLOCKS = new Set(['domains', 'provisional']);
+export async function writeTaxonomy(input) {
+    const path = join(input.kbRoot.path, TAXONOMY_FILE);
+    for (const declaration of input.declarations) {
+        const defect = describeKeyDefect(declaration.path);
+        if (defect !== undefined) {
+            throw new KbLoaderError(`${path}: domain "${declaration.path}" ${defect}`);
+        }
+    }
+    const document = await readDocument(path);
+    const declared = readDeclaredPaths(document);
+    const added = [];
+    const byBlock = new Map();
+    for (const declaration of sortByPath(input.declarations)) {
+        if (declared.has(declaration.path)) {
+            continue;
+        }
+        declared.add(declaration.path);
+        added.push(declaration.path);
+        const block = declaration.provisional ? 'provisional' : 'domains';
+        const description = declaration.description ?? '';
+        const entries = byBlock.get(block) ?? [];
+        entries.push([declaration.path, description === '' ? null : description]);
+        byBlock.set(block, entries);
+    }
+    if (added.length === 0) {
+        return { added };
+    }
+    for (const [block, entries] of byBlock) {
+        declareInBlock({ document, block, entries });
+    }
+    await writeAtomic(path, document.toString({ nullStr: '' }));
+    return { added };
+}
+function assertBlocksAppendable(document, path) {
+    const contents = document.contents;
+    if (!isMap(contents)) {
+        return;
+    }
+    for (const pair of contents.items) {
+        if (!isPair(pair) || !isScalar(pair.key) || typeof pair.key.value !== 'string') {
+            continue;
+        }
+        if (!BLOCKS.has(pair.key.value) || isMap(pair.value) || isEmptyBlockValue(pair.value)) {
+            continue;
+        }
+        throw new KbLoaderError(`${path}: "${pair.key.value}" must be a mapping of domain paths to descriptions`);
+    }
+}
+function declareInBlock(input) {
+    const { document, block, entries } = input;
+    const emptied = findEmptyBlock(document, block);
+    if (emptied === undefined) {
+        for (const [path, description] of entries) {
+            document.setIn([block, path], description);
+        }
+        return;
+    }
+    const comment = isScalar(emptied.value) ? emptied.value.comment : undefined;
+    if (typeof comment === 'string' && isScalar(emptied.key)) {
+        emptied.key.comment = comment;
+    }
+    emptied.value = document.createNode(Object.fromEntries(entries));
+}
+function findEmptyBlock(document, block) {
+    const contents = document.contents;
+    if (!isMap(contents)) {
+        return undefined;
+    }
+    for (const pair of contents.items) {
+        if (isPair(pair) && isScalar(pair.key) && pair.key.value === block && isEmptyBlockValue(pair.value)) {
+            return pair;
+        }
+    }
+    return undefined;
+}
+function isEmptyBlockValue(value) {
+    return value === null || (isScalar(value) && value.value === null);
+}
+async function readDocument(path) {
+    let text = '';
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (!isEnoent(error)) {
+            throw error;
+        }
+    }
+    const document = parseDocument(text);
+    const firstError = document.errors[0];
+    if (firstError !== undefined) {
+        throw new KbLoaderError(`${path}: malformed YAML — ${firstError.message}`);
+    }
+    if (document.contents !== null && !isMap(document.contents)) {
+        throw new KbLoaderError(`${path}: top-level must be a mapping`);
+    }
+    assertBlocksAppendable(document, path);
+    return document;
+}
+function readDeclaredPaths(document) {
+    const paths = new Set();
+    const contents = document.toJS();
+    if (!isRecord(contents)) {
+        return paths;
+    }
+    for (const block of BLOCKS) {
+        const declarations = contents[block];
+        if (isRecord(declarations)) {
+            for (const path of Object.keys(declarations)) {
+                paths.add(path);
+            }
+        }
+    }
+    return paths;
+}
+function sortByPath(declarations) {
+    return declarations.toSorted((a, b) => {
+        if (a.path === b.path)
+            return 0;
+        return a.path < b.path ? -1 : 1;
+    });
+}
+async function writeAtomic(path, content) {
+    const tempPath = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    await writeFile(tempPath, content, 'utf8');
+    try {
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => { });
+        throw error;
+    }
+}

package/dist/esm/types.d.ts

@@ -42,6 +42,7 @@ export interface ParsedNote {
 export type FindingSeverity = 'error' | 'warning';
 export interface Finding {
     path: string;
+    scope?: 'note' | 'vault';
     line?: number;
     rule: string;
     severity: FindingSeverity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -76,6 +76,11 @@
       "types": "./dist/esm/tags/index.d.ts",
       "import": "./dist/esm/tags/index.js"
     },
+    "./taxonomy": {
+      "source": "./src/taxonomy/index.ts",
+      "types": "./dist/esm/taxonomy/index.d.ts",
+      "import": "./dist/esm/taxonomy/index.js"
+    },
     "./vault-integrity": {
       "source": "./src/vault-integrity/index.ts",
       "types": "./dist/esm/vault-integrity/index.d.ts",