@williamthorsen/kb 0.6.1 → 0.7.0

package/dist/esm/filesystem/write-atomic.d.ts

@@ -1 +1,6 @@
+/**
+ * Atomically writes `content` to `path` via a temp file plus `rename`, so a concurrent reader never sees a partial
+ * write. The temp file is a sibling of the target, keeping the rename within one filesystem, where it is atomic. On
+ * failure the temp file is cleaned up best-effort and the error re-thrown.
+ */
 export declare function writeAtomic(path: string, content: string): Promise<void>;

package/dist/esm/frontmatter/parse-note.d.ts

@@ -1,7 +1,16 @@
 import type { ParsedNote } from '../types.js';
+/**
+ * Reads a note from disk and parse it into a `ParsedNote`. I/O errors (e.g. a missing file) are thrown;
+ * YAML parse errors are not.
+ */
 export declare function parseNote(input: {
     path: string;
 }): Promise<ParsedNote>;
+/**
+ * Parse a note from a literal string into a `ParsedNote` carrying typed frontmatter.
+ * Parse errors are recorded in `frontmatterRaw.parseError`, never thrown — the rule layer decides how to report them.
+ * `path` defaults to `<string>` and labels the result for diagnostics.
+ */
 export declare function parseNoteContent(input: {
     content: string;
     path?: string;

package/dist/esm/git/list-git-scope.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns every path git accounts for under `root` as an NFC-normalized set of root-relative, slash-separated paths:
+ * tracked files, plus untracked ones that no ignore rule covers. Returns `undefined` where git holds no opinion,
+ * because `root` lies outside a working tree or git cannot be run at all, so a caller keeps its own scope instead of
+ * reading an empty set as "git ignores everything".
+ *
+ * A tracked file stays in scope even where an ignore rule matches it, since every clone still sees it. That is why
+ * the scope unions the two `ls-files` forms rather than asking `git check-ignore`, which would report it ignored.
+ *
+ * Paths are normalized because git reports NFC where `readdir` reports NFD on macOS, and comparing the two forms
+ * unnormalized drops every path whose name carries a combining mark.
+ */
+export declare function listGitScope(input: {
+    root: string;
+}): ReadonlySet<string> | undefined;

package/dist/esm/git/list-git-scope.js

@@ -0,0 +1,22 @@
+import { runGit } from "./run-git.js";
+export function listGitScope(input) {
+    const tracked = runGit({ cwd: input.root, args: ['ls-files', '-z'], maxBuffer: GIT_MAX_BUFFER });
+    if (!tracked.ok)
+        return undefined;
+    const unignored = runGit({
+        cwd: input.root,
+        args: ['ls-files', '-z', '--others', '--exclude-standard'],
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+    if (!unignored.ok)
+        return undefined;
+    const scope = new Set();
+    for (const stdout of [tracked.stdout, unignored.stdout]) {
+        for (const path of stdout.split('\0')) {
+            if (path !== '')
+                scope.add(path.normalize('NFC'));
+        }
+    }
+    return scope;
+}
+const GIT_MAX_BUFFER = 64 * 1_024 * 1_024;

package/dist/esm/git/run-git.d.ts

@@ -0,0 +1,17 @@
+/** The outcome of one git invocation: its stdout, or git's failure message. */
+export type GitResult = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Runs `git -C cwd <args>` and returns its stdout, or a failure carrying git's own stderr. A git that cannot be
+ * spawned fails the same way as one that exits non-zero, so both reach the caller as a single "git did not answer".
+ */
+export declare function runGit(input: {
+    cwd: string;
+    args: readonly string[];
+    maxBuffer?: number;
+}): GitResult;

package/dist/esm/git/run-git.js

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isRecord } from "../type-guards.js";
+export function runGit(input) {
+    try {
+        const stdout = execFileSync('git', ['-C', input.cwd, ...input.args], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            ...(input.maxBuffer !== undefined && { maxBuffer: input.maxBuffer }),
+        });
+        return { ok: true, stdout };
+    }
+    catch (error) {
+        return { ok: false, message: extractGitErrorMessage(error) };
+    }
+}
+function extractGitErrorMessage(error) {
+    if (isRecord(error) && typeof error.stderr === 'string' && error.stderr.trim() !== '') {
+        return error.stderr.trim();
+    }
+    return describeError(error);
+}

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, TAXONOMY_FILE, } from './store-layout.js';
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EDITORCONFIG_FILE, EVENTS_DIR, KB_DIR, PRETTIER_CONFIG_FILE, 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, TAXONOMY_FILE, } from "./store-layout.js";
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EDITORCONFIG_FILE, EVENTS_DIR, KB_DIR, PRETTIER_CONFIG_FILE, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, TAXONOMY_FILE, } from "./store-layout.js";

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

@@ -1,16 +1,36 @@
+/** The store's metadata directory. Its presence marks a directory as a KB root. */
 export declare const KB_DIR = ".kb";
+/** The directory holding the store's notes. */
 export declare const CONTENT_DIR = "content";
+/** The `content/` subdirectory holding assertion records. Named on its own because a caller may need to recognize the segment, not just the path. */
 export declare const ASSERTIONS_SEGMENT = "assertions";
+/** The tag-alias map. */
 export declare const ALIASES_FILE = ".kb/tag-aliases.yaml";
+/** The directory holding the store's assertion records. */
 export declare const ASSERTIONS_DIR = "content/assertions";
+/** The check configuration. */
 export declare const CONFIG_FILE = ".kb/config.yaml";
+/** The editor and formatter settings. Sits at the store root, where every tool that reads it looks. */
+export declare const EDITORCONFIG_FILE = ".editorconfig";
+/** The directory holding the store's event records. */
 export declare const EVENTS_DIR = "content/events";
+/** The formatting configuration. Sits at the store root rather than under `.kb/`, because Prettier discovers it there. */
+export declare const PRETTIER_CONFIG_FILE = ".prettierrc.yaml";
+/** The declared assertion taxonomy. */
 export declare const TAXONOMY_FILE = ".kb/taxonomy.yaml";
+/**
+ * Builds an event record's store-relative path. Posix-separated, so it serves as the path half of a git object spec
+ * (`@{upstream}:content/events/<id>.md`) as well as an argument to `join`.
+ */
 export declare function buildEventPath(id: string): string;
+/** Resolves the absolute path of a store's assertions directory. */
 export declare function resolveAssertionsDir(storePath: string): string;
+/** Resolves an event record's absolute path within a store. */
 export declare function resolveEventPath(input: {
     storePath: string;
     id: string;
 }): string;
+/** Resolves the absolute path of a store's events directory. */
 export declare function resolveEventsDir(storePath: string): string;
+/** Resolves the absolute path of a store's metadata directory. */
 export declare function resolveKbDir(storePath: string): string;

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

@@ -5,7 +5,9 @@ export const ASSERTIONS_SEGMENT = 'assertions';
 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 EDITORCONFIG_FILE = '.editorconfig';
 export const EVENTS_DIR = `${CONTENT_DIR}/events`;
+export const PRETTIER_CONFIG_FILE = '.prettierrc.yaml';
 export const TAXONOMY_FILE = `${KB_DIR}/taxonomy.yaml`;
 export function buildEventPath(id) {
     return `${EVENTS_DIR}/${id}.md`;

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

@@ -1,6 +1,13 @@
 import type { Finding } from '../types.js';
+/** The note fields the paths lint reads: its path and its full raw content. */
 export interface PathsNote {
     path: string;
     content: string;
 }
+/**
+ * Flags hardcoded `/Users/{name}/` paths anywhere in the note (`paths.user-home`, error), reporting each occurrence at
+ * its line. The convention is `~/` for portability and to avoid leaking local usernames. Scans the full raw content,
+ * including frontmatter and code blocks, so a `/Users/{name}/` path inside a fenced or inline code example is flagged
+ * too.
+ */
 export declare function pathsFindings(note: PathsNote): Finding[];

package/dist/esm/lints/tag-alias.d.ts

@@ -1,6 +1,12 @@
 import type { AliasMap, Finding } from '../types.js';
+/** The note fields the tag-alias lint reads: its path and its raw frontmatter field map. */
 export interface TagAliasNote {
     path: string;
     fields: Record<string, unknown>;
 }
+/**
+ * Warns when a note's `tags` list contains a known alias, naming the canonical form, in list order (`tag-alias`,
+ * warning). Unknown tags (neither canonical nor alias) are new vocabulary and are not flagged; a `tags` value that is
+ * absent or not a list yields no findings. Each finding points at the note, not a specific tag line.
+ */
 export declare function tagAliasFindings(note: TagAliasNote, aliases: AliasMap): Finding[];

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

@@ -1,12 +1,27 @@
 import type { KbConfig } from '../config/config-schema.js';
 import type { Taxonomy } from '../taxonomy/taxonomy-schema.js';
 import type { Finding } from '../types.js';
+/** The note fields the taxonomy rules read. */
 export interface TaxonomyNote {
+    /** The note's path relative to the KB root, slash-separated. */
     relativePath: string;
 }
+/**
+ * Reports where a store's assertion folders and its declared taxonomy disagree: `taxonomy.undeclared` for a folder
+ * holding notes that no domain declares, `taxonomy.unused` for a declared domain holding no note at or beneath it, and
+ * `taxonomy.orphan` for a declared domain whose parent is undeclared. All are warnings, so drift is reported without
+ * failing the run, and all are vault-scoped, so a run narrowed to selected notes still sees them.
+ *
+ * A taxonomy declaring nothing disables all three, whether because the file is absent or because it declares no
+ * domains. A store that has not adopted a taxonomy is therefore silent rather than reporting every folder it owns.
+ *
+ * The observed structure comes from the enumerated notes' own paths rather than a directory listing, so the rules add
+ * no filesystem traversal and see exactly the notes the run's `targets` and `exclude` admitted.
+ */
 export declare function taxonomyFindings(input: {
     notes: readonly TaxonomyNote[];
     taxonomy: Taxonomy;
     config: KbConfig;
+    /** Absolute path of `.kb/taxonomy.yaml`, which every finding is reported against. */
     taxonomyPath: string;
 }): Finding[];

package/dist/esm/note-io/field-validators.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Coerces a frontmatter field value to a string list: the array's string members when it is a sequence, an empty list
+ * when the value is absent, or `null` when the value is present but not list-shaped (so a parser can flag it).
+ */
 export declare function asStringList(value: unknown): string[] | null;
+/**
+ * Reports whether a value is a real UTC instant in either bare `YYYY-MM-DD` or second-precision `YYYY-MM-DDTHH:MM:SSZ`
+ * form. An unmarked or offset timestamp matches neither pattern; an unreal calendar date or clock time fails the
+ * `Date.UTC` round-trip.
+ */
 export declare function isValidDate(value: string): boolean;

package/dist/esm/note-io/read-note.d.ts

@@ -1,8 +1,15 @@
+/** The outcome of splitting a note: its frontmatter field map, its body, the body's start line, and any parse error. */
 export interface ReadNote {
     fields: Record<string, unknown>;
     body: string;
+    /** 1-based file line where the body begins (line 1 when there is no frontmatter block). */
     bodyStartLine: number;
     error?: string;
 }
+/** Reads a note file from disk and splits it into a frontmatter field map and body. I/O errors are thrown. */
 export declare function readNote(path: string): Promise<ReadNote>;
+/**
+ * Splits note content into a frontmatter field map and body. A missing frontmatter block or a YAML parse error is
+ * reported in `error` (never thrown), with the full content returned as the body so callers can still surface it.
+ */
 export declare function readNoteContent(content: string): ReadNote;

package/dist/esm/note-io/write-note.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Renders a field map and body to note content: the opening fence, the frontmatter, the closing fence, one blank line,
+ * then the body. A single leading newline on the body is dropped so the blank line is not doubled, keeping the output
+ * stable across read/write cycles.
+ */
 export declare function renderNote(fields: Record<string, unknown>, body: string): string;
+/**
+ * Atomically writes a note to `path`, so a concurrent reader never sees a partial write. See {@link writeAtomic} for
+ * the guarantee and its failure behavior.
+ */
 export declare function writeNote(path: string, fields: Record<string, unknown>, body: string): Promise<void>;

package/dist/esm/note-io/yaml-fields.d.ts

@@ -1,5 +1,10 @@
+/**
+ * Parses frontmatter text (the YAML between the fences) into an insertion-ordered field map. A YAML parse error is
+ * returned rather than thrown; a block that is not a map yields an empty field map.
+ */
 export declare function parseFrontmatterFields(text: string): {
     fields: Record<string, unknown>;
     error?: string;
 };
+/** Renders a field map to frontmatter text (no fences), one `key: value` line per entry, in insertion order. */
 export declare function renderFrontmatterFields(fields: Record<string, unknown>): string;

package/dist/esm/records/assertion.d.ts

@@ -1,3 +1,4 @@
+/** A parsed `assertion` record: its typed fields, the body, and any other frontmatter preserved in `extra`. */
 export interface KbAssertion {
     recordType: 'assertion';
     title: string;
@@ -11,6 +12,7 @@ export interface KbAssertion {
     extra: Record<string, unknown>;
     body: string;
 }
+/** The outcome of parsing frontmatter as an assertion: the typed record, or the validation errors that blocked it. */
 export type ParseAssertionResult = {
     ok: true;
     record: KbAssertion;
@@ -18,7 +20,9 @@ export type ParseAssertionResult = {
     ok: false;
     errors: string[];
 };
+/** Validates a frontmatter field map as an assertion and projects it onto a {@link KbAssertion}, accumulating every error. */
 export declare function parseAssertion(fields: Record<string, unknown>, body: string): ParseAssertionResult;
+/** Projects an assertion back to a frontmatter field map (typed fields first, then preserved `extra`) plus its body. */
 export declare function renderAssertion(record: KbAssertion): {
     fields: Record<string, unknown>;
     body: string;

package/dist/esm/records/event.d.ts

@@ -1,10 +1,15 @@
+/** The impact levels an event may carry, ordered lowest to highest. */
 export declare const EVENT_IMPACT_LEVELS: readonly ["low", "medium", "high", "critical"];
+/** An event's impact: the author's subjective, revisable rating of how much addressing the event matters. */
 export type EventImpact = (typeof EVENT_IMPACT_LEVELS)[number];
+/** Reports whether a value is one of the declared {@link EVENT_IMPACT_LEVELS}. */
 export declare function isEventImpact(value: unknown): value is EventImpact;
+/** A parsed `event` record: its declared fields, the body, and any other frontmatter preserved in `extra`. */
 export interface KbEvent {
     recordType: 'event';
     id: string;
     capturedAt: string;
+    /** Harness-dependent provenance: absent when the harness that captured the event exposes no session id. */
     session?: string;
     cwd: string;
     summary: string;
@@ -14,6 +19,7 @@ export interface KbEvent {
     extra: Record<string, unknown>;
     body: string;
 }
+/** The outcome of parsing frontmatter as an event: the typed record, or the validation errors that blocked it. */
 export type ParseEventResult = {
     ok: true;
     record: KbEvent;
@@ -21,7 +27,13 @@ export type ParseEventResult = {
     ok: false;
     errors: string[];
 };
+/** Validates a frontmatter field map as an event and projects it onto a {@link KbEvent}, accumulating every error. */
 export declare function parseEvent(fields: Record<string, unknown>, body: string): ParseEventResult;
+/**
+ * Projects an event back to a frontmatter field map (declared fields first, then preserved `extra`) plus its body. An
+ * empty `session` is omitted like an absent one, mirroring {@link parseEvent}: the two spellings of "no session" have a
+ * single representation on both edges of the module, so no record can reacquire the empty field on a write.
+ */
 export declare function renderEvent(record: KbEvent): {
     fields: Record<string, unknown>;
     body: string;

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

@@ -0,0 +1,2 @@
+export { renderAliasesSeed, renderConfigSeed } from './render-seeds.js';
+export { scaffold, type ScaffoldAction, type ScaffoldEntry } from './scaffold.js';

package/dist/esm/scaffold/index.js

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

package/dist/esm/scaffold/render-seeds.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The formatting option every store carries that `.editorconfig` cannot express. Held here rather than in the seed
+ * prose, so that the file that a store receives cannot diverge from the value that kb documents. See
+ * {@link renderPrettierSeed}'s header for what it prevents.
+ */
+export declare const canonicalPrettierConfig: {
+    embeddedLanguageFormatting: string;
+};
+/** Renders `.kb/tag-aliases.yaml`: an empty `aliases: {}` map under an explanatory header. */
+export declare function renderAliasesSeed(): string;
+/** Renders `.kb/config.yaml`: a fully-commented stub whose example values are the live `defaultKbConfig`. */
+export declare function renderConfigSeed(): string;
+/** Renders `.editorconfig`: the editor and formatter settings every store shares. */
+export declare function renderEditorconfigSeed(): string;
+/** Renders `.prettierrc.yaml`: the canonical formatting option under a header explaining why it is set. */
+export declare function renderPrettierSeed(): string;

package/dist/esm/scaffold/render-seeds.js

@@ -0,0 +1,63 @@
+import { stringify } from 'yaml';
+import { defaultKbConfig } from "../config/config-schema.js";
+const ALIASES_HEADER = `# Tag aliases for this knowledge store.
+#
+# Map each canonical tag to the aliases that should resolve to it, for example:
+#   aliases:
+#     typescript: [ts, type-script]
+# The \`aliases:\` key is required even when empty.
+`;
+const CONFIG_HEADER = `# Check configuration for this knowledge store.
+#
+# Both keys are optional and fall back to the defaults shown below; an absent file uses these defaults too. Uncomment
+# and edit to override. \`targets\` selects which notes \`kb check\` enumerates and \`exclude\` removes matches;
+# patterns are slash-separated and relative to the store root.
+#
+`;
+const EDITORCONFIG_SEED = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = 120
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+`;
+const PRETTIER_HEADER = `# Formatting configuration for this knowledge store.
+#
+# The single option here is not stylistic. It prevents a specific failure, so read this before removing it.
+#
+# \`embeddedLanguageFormatting: off\` leaves a note's YAML frontmatter unformatted. Formatted, a long \`tags\` or
+# \`addressed-by\` list breaks across several lines, which the note writer puts back onto one the next time it writes
+# the note, so the formatter and the writer would rewrite each other's output without end.
+#
+# Width, indentation, and line endings are set in \`.editorconfig\`, which Prettier reads and every editor reads too.
+#
+`;
+export const canonicalPrettierConfig = {
+    embeddedLanguageFormatting: 'off',
+};
+export function renderAliasesSeed() {
+    return `${ALIASES_HEADER}aliases: {}\n`;
+}
+export function renderConfigSeed() {
+    return `${CONFIG_HEADER}${commentBlock(stringify(defaultKbConfig))}\n`;
+}
+export function renderEditorconfigSeed() {
+    return EDITORCONFIG_SEED;
+}
+export function renderPrettierSeed() {
+    return `${PRETTIER_HEADER}${stringify(canonicalPrettierConfig)}`;
+}
+function commentBlock(text) {
+    return text
+        .trimEnd()
+        .split('\n')
+        .map((line) => (line === '' ? '#' : `# ${line}`))
+        .join('\n');
+}

package/dist/esm/scaffold/scaffold.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What {@link scaffold} did about one canonical path: `created` where it was absent, `present` where it was left as
+ * found, `replaced` where `force` overwrote it.
+ */
+export type ScaffoldAction = 'created' | 'present' | 'replaced';
+/** One canonical path and what the scaffold did about it. */
+export interface ScaffoldEntry {
+    /** The store-relative path, directories carrying a trailing slash. */
+    path: string;
+    action: ScaffoldAction;
+}
+/**
+ * Writes the canonical files and directories every knowledge-base store holds, leaving an existing file as it found it
+ * unless `force` is set. Directories are ensured either way, since a directory has no content to replace.
+ *
+ * The function asserts nothing about the store: a caller that requires one to exist, or requires one not to, checks
+ * that itself. `create` calls it on a directory it has just confirmed holds no store, and `kb scaffold` on one it has
+ * just confirmed does.
+ */
+export declare function scaffold(input: {
+    storePath: string;
+    force?: boolean;
+}): Promise<readonly ScaffoldEntry[]>;

package/dist/esm/scaffold/scaffold.js

@@ -0,0 +1,35 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathExists } from "../filesystem/exists.js";
+import { writeAtomic } from "../filesystem/write-atomic.js";
+import { ALIASES_FILE, CONFIG_FILE, CONTENT_DIR, EDITORCONFIG_FILE, EVENTS_DIR, PRETTIER_CONFIG_FILE, } from "../layout/index.js";
+import { renderAliasesSeed, renderConfigSeed, renderEditorconfigSeed, renderPrettierSeed } from "./render-seeds.js";
+export async function scaffold(input) {
+    const { storePath, force = false } = input;
+    const entries = [];
+    for (const file of CANONICAL_FILES) {
+        const absolutePath = join(storePath, file.path);
+        const exists = await pathExists(absolutePath);
+        if (exists && !force) {
+            entries.push({ path: file.path, action: 'present' });
+            continue;
+        }
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeAtomic(absolutePath, file.render());
+        entries.push({ path: file.path, action: exists ? 'replaced' : 'created' });
+    }
+    for (const directory of CANONICAL_DIRECTORIES) {
+        const absolutePath = join(storePath, directory);
+        const exists = await pathExists(absolutePath);
+        await mkdir(absolutePath, { recursive: true });
+        entries.push({ path: `${directory}/`, action: exists ? 'present' : 'created' });
+    }
+    return entries;
+}
+const CANONICAL_DIRECTORIES = [CONTENT_DIR, EVENTS_DIR];
+const CANONICAL_FILES = [
+    { path: EDITORCONFIG_FILE, render: renderEditorconfigSeed },
+    { path: CONFIG_FILE, render: renderConfigSeed },
+    { path: ALIASES_FILE, render: renderAliasesSeed },
+    { path: PRETTIER_CONFIG_FILE, render: renderPrettierSeed },
+];

package/dist/esm/tags/canonicalize.d.ts

@@ -1,3 +1,11 @@
 import type { AliasMap } from '../types.js';
+/**
+ * Returns the canonical form of a tag. Lookups are case-insensitive.
+ * Unknown tags and tags that are already canonical pass through unchanged.
+ */
 export declare function canonicalize(tag: string, aliases: AliasMap): string;
+/**
+ * Returns the canonical form of a tag only when the input is a known alias; otherwise `null`.
+ * Distinguishes drift (an alias is present) from canonical or new-vocabulary tags.
+ */
 export declare function findAliasFor(tag: string, aliases: AliasMap): string | null;

package/dist/esm/tags/load-aliases.d.ts

@@ -1,5 +1,15 @@
 import type { AliasMap, KbRoot } from '../types.js';
+/**
+ * Loads `.kb/tag-aliases.yaml` from a KB root into a typed `AliasMap`, returning an empty map when the file is absent.
+ * The thin I/O wrapper around {@link parseAliases}; structural defects throw with the file path included.
+ */
 export declare function loadAliases(input: {
     kbRoot: KbRoot;
 }): Promise<AliasMap>;
+/**
+ * Parses a tag-aliases registry from a string into an `AliasMap`.
+ * Aliases are lowercased on insertion so callers can look up case-insensitively.
+ * Throws on any structural defect — non-object top level, missing `aliases` key, non-string entries, self-aliases,
+ * or cross-canonical collisions — with `contextLabel` prefixed onto every message.
+ */
 export declare function parseAliases(text: string, contextLabel?: string): AliasMap;

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

@@ -1,3 +1,13 @@
+/**
+ * Derives every domain a note set implies: the domain each note sits in, plus each of that domain's ancestors, sorted.
+ * A grouping domain that holds only subfolders is included, because the rules treat it as in use and would otherwise
+ * report a back-filled taxonomy's own entries as unused.
+ */
 export declare function deriveDomains(relativePaths: Iterable<string>): string[];
+/**
+ * Derives the domain a note sits in, or `undefined` when the note is not an assertion or sits at the assertions root.
+ * Scoping to the assertions root is what keeps event records from registering as domains.
+ */
 export declare function resolveDomain(relativePath: string): string | undefined;
+/** Derives a slash-path's parent, or `undefined` when it has no separator and so sits at the top level. */
 export declare function resolveParent(path: string): string | undefined;

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

@@ -1,5 +1,13 @@
 import type { KbRoot } from '../types.js';
 import { type Taxonomy } from './taxonomy-schema.js';
+/**
+ * Loads `.kb/taxonomy.yaml` into a single keyed map, returning an empty taxonomy when the file is absent or declares
+ * nothing. The two on-disk blocks are a file-format concern: a consumer looks a domain up once and reads `provisional`
+ * off the entry it finds.
+ *
+ * Mirrors {@link loadKbConfig}: structural defects (malformed YAML, a wrong type, a malformed key, a path declared in
+ * both blocks) throw a {@link KbLoaderError} naming the file. I/O errors other than a missing file propagate.
+ */
 export declare function loadTaxonomy(input: {
     kbRoot: KbRoot;
 }): Promise<Taxonomy>;

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

@@ -1,10 +1,29 @@
 import { z } from 'zod';
+/**
+ * Describes why a domain key cannot be used, or returns `undefined` when the key is well-formed. Keys are relative to
+ * the assertions root, so a restated `content/assertions/` prefix would declare the domain a level deeper than the
+ * author meant; `kb-add` refuses the same mistake on the note-write path.
+ */
 export declare function describeKeyDefect(key: string): string | undefined;
+/** A knowledge base's declared assertion structure, keyed by assertions-root-relative slash-path. */
 export type Taxonomy = ReadonlyMap<string, TaxonomyEntry>;
+/** A single declared domain. */
 export interface TaxonomyEntry {
+    /** The domain's one-line description; empty when it was declared without one. */
     description: string;
+    /** Whether the domain was declared under `provisional:` rather than `domains:`. */
     provisional: boolean;
 }
+/**
+ * The on-disk `.kb/taxonomy.yaml` shape.
+ *
+ * Both blocks are optional and nullable, so a file may declare only one, and a block header left with nothing under it
+ * loads as declaring nothing rather than failing. YAML reads such a header as null, and it is the state promoting the
+ * last entry out of a block leaves behind.
+ *
+ * A description may likewise be null, so a key written bare (`engineering/tooling:`) loads: that is what a hand editor
+ * types and what a domain declared without a description round-trips to.
+ */
 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>>>>;

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

@@ -1,9 +1,29 @@
 import type { KbRoot } from '../types.js';
+/** A domain to declare. */
 export interface TaxonomyDeclaration {
+    /** The domain's assertions-root-relative slash-path. */
     path: string;
+    /** The one-line description; absent or empty writes the key bare, with no description. */
     description?: string;
+    /** Whether to declare under `provisional:` rather than `domains:`. */
     provisional: boolean;
 }
+/**
+ * Declares domains in `.kb/taxonomy.yaml`, creating the file and either block as needed, and returns the paths added.
+ *
+ * Edits the parsed document rather than re-serializing a plain object, so existing comments, key order, and formatting
+ * survive; a plain parse-and-stringify round trip would discard every comment in a hand-curated file. New keys append
+ * to the end of their block in path order, and a block header left with nothing under it is filled in place rather
+ * than moved.
+ *
+ * A path either block already declares is skipped rather than overwritten, so a repeat call adds nothing; when nothing
+ * is left to add, the file is not opened for writing at all. The write goes through the shared `writeAtomic` helper,
+ * so an interrupted call cannot truncate the taxonomy.
+ *
+ * Throws a {@link KbLoaderError} on a malformed key, or on an existing file that cannot be safely appended to: one
+ * that fails to parse, one whose top level is not a mapping, and one whose `domains` or `provisional` block holds
+ * something other than a mapping. Other I/O errors propagate.
+ */
 export declare function writeTaxonomy(input: {
     kbRoot: KbRoot;
     declarations: readonly TaxonomyDeclaration[];

package/dist/esm/type-guards.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Checks whether an error is an ENOENT (no such file or directory) filesystem error.
+ * @internal
+ */
 export declare function isEnoent(error: unknown): boolean;
+/**
+ * Returns true when `error` carries the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
+ * @internal
+ */
 export declare function isErrorCode(error: unknown, code: string): boolean;
+/**
+ * Type guard for a non-null, non-array object.
+ *
+ * @internal
+ */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;