@williamthorsen/kb 0.8.0 → 0.8.1

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

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

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

@@ -73,7 +73,7 @@ async function loadRegistryFile(path, source, home) {
     }
     const result = kbRegistryFileSchema.safeParse(parsed);
     if (!result.success) {
-        throw new Error(`${path}: invalid kb.yaml — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new Error(`${path}: invalid kb.yaml: ${result.error.issues[0]?.message ?? 'unknown error'}`);
     }
     const configDir = dirname(path);
     const entries = [];

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

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

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

@@ -7,7 +7,7 @@ export async function registerStore(input) {
     const doc = await loadRegistryDocument(input.registryPath);
     const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
     if (!existing.success) {
-        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new Error(`${input.registryPath}: invalid kb.yaml: ${existing.error.issues[0]?.message ?? 'unknown error'}`);
     }
     if (doc.hasIn(['kbs', input.name])) {
         return { status: 'already-present' };
@@ -20,7 +20,7 @@ export async function registerStore(input) {
     sortRegistryEntries(doc);
     const result = kbRegistryFileSchema.safeParse(doc.toJS());
     if (!result.success) {
-        throw new Error(`${input.registryPath}: cannot register "${input.name}" — ${result.error.issues[0]?.message ?? 'invalid entry'}`);
+        throw new Error(`${input.registryPath}: cannot register "${input.name}": ${result.error.issues[0]?.message ?? 'invalid entry'}`);
     }
     await mkdir(dirname(input.registryPath), { recursive: true });
     await writeFile(input.registryPath, doc.toString(), 'utf8');

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

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

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

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

package/dist/esm/discovery/set-default-kb.js

@@ -7,7 +7,7 @@ export async function clearDefaultKb(input) {
     const doc = await loadRegistryDocument(input.registryPath);
     const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
     if (!existing.success) {
-        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new Error(`${input.registryPath}: invalid kb.yaml: ${existing.error.issues[0]?.message ?? 'unknown error'}`);
     }
     if (!doc.has('default_kb')) {
         return;
@@ -19,7 +19,7 @@ export async function setDefaultKb(input) {
     const doc = await loadRegistryDocument(input.registryPath);
     const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
     if (!existing.success) {
-        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new Error(`${input.registryPath}: invalid kb.yaml: ${existing.error.issues[0]?.message ?? 'unknown error'}`);
     }
     if (!doc.hasIn(['kbs', input.name])) {
         throw new Error(`${input.registryPath}: "${input.name}" is not a registered knowledge base`);
@@ -27,7 +27,7 @@ export async function setDefaultKb(input) {
     doc.set('default_kb', input.name);
     const result = kbRegistryFileSchema.safeParse(doc.toJS());
     if (!result.success) {
-        throw new Error(`${input.registryPath}: cannot set default_kb — ${result.error.issues[0]?.message ?? 'invalid registry'}`);
+        throw new Error(`${input.registryPath}: cannot set default_kb: ${result.error.issues[0]?.message ?? 'invalid registry'}`);
     }
     await mkdir(dirname(input.registryPath), { recursive: true });
     await writeFile(input.registryPath, doc.toString(), 'utf8');

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

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

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

@@ -1,14 +1,14 @@
 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;
+ * Reads a note from disk and parses 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.
+ * Parses a note from a literal string into a `ParsedNote` containing 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: {

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

@@ -1,14 +1,14 @@
 /**
  * Returns every path that git tracks under `root`, plus every untracked path that no ignore rule covers, as an
- * NFC-normalized set of root-relative, slash-separated paths. 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
+ * NFC-normalized set of root-relative, slash-separated paths. Returns `undefined` when git cannot list the paths,
+ * because `root` is 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.
+ * A tracked file stays in scope even when an ignore rule matches it, since every clone still contains it. That is why
+ * the function unions the two `ls-files` forms rather than running `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.
+ * Paths are normalized because git reports NFC but `readdir` reports NFD on macOS, and comparing the two forms
+ * unnormalized drops every path whose name contains a combining mark.
  */
 export declare function listGitScope(input: {
     root: string;

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

@@ -7,8 +7,8 @@ export type GitResult = {
     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".
+ * Runs `git -C cwd <args>` and returns its stdout, or a failure that contains git's own stderr. A git that cannot be
+ * spawned fails the same way as one that exits non-zero, so the caller receives both as one kind of failure.
  */
 export declare function runGit(input: {
     cwd: string;

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

@@ -4,17 +4,17 @@ export declare const KB_DIR = ".kb";
 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. */
+/** The editor and formatter settings. Located 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. */
+/**
+ * The formatting configuration. Located 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";

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

@@ -1,5 +1,5 @@
 import type { Finding } from '../types.js';
-/** The note fields the paths lint reads: its path and its full raw content. */
+/** The note fields that the paths lint reads: its path and its full raw content. */
 export interface PathsNote {
     path: string;
     content: string;

package/dist/esm/lints/paths.js

@@ -5,7 +5,7 @@ export function pathsFindings(note) {
         line: countNewlines(note.content, match.index) + 1,
         rule: 'paths.user-home',
         severity: 'error',
-        message: `hardcoded "${match[0]}" — replace with ~/`,
+        message: `hardcoded "${match[0]}"; replace with ~/`,
     }));
     return findings;
 }

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

@@ -1,5 +1,5 @@
 import type { AliasMap, Finding } from '../types.js';
-/** The note fields the tag-alias lint reads: its path and its raw frontmatter field map. */
+/** The note fields that the tag-alias lint reads: its path and its raw frontmatter field map. */
 export interface TagAliasNote {
     path: string;
     fields: Record<string, unknown>;

package/dist/esm/lints/tag-alias.js

@@ -14,7 +14,7 @@ export function tagAliasFindings(note, aliases) {
             path: note.path,
             rule: 'tag-alias',
             severity: 'warning',
-            message: `tag "${tag}" is an alias — use canonical form "${canonical}"`,
+            message: `tag "${tag}" is an alias; use canonical form "${canonical}"`,
         });
     }
     return findings;

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

@@ -1,22 +1,23 @@
 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. */
+/** The note fields that 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.
+ * Reports each disagreement between a store's assertion folders and its declared taxonomy: `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. All are vault-scoped: A run narrowed to selected notes still reports 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.
+ * domains. The rules therefore report nothing for a store that has not adopted a taxonomy, rather than flagging
+ * every folder that the store 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.
+ * Because the observed structure comes from the enumerated notes' own paths rather than a directory listing, the rules
+ * add no filesystem traversal and consider exactly the notes that the run's `targets` and `exclude` admitted.
  */
 export declare function taxonomyFindings(input: {
     notes: readonly TaxonomyNote[];

package/dist/esm/lints/taxonomy.js

@@ -18,14 +18,14 @@ export function taxonomyFindings(input) {
     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`));
+            findings.push(buildFinding(taxonomyPath, 'undeclared', `folder "${domain}" contains 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`));
+        findings.push(buildFinding(taxonomyPath, 'unused', `domain "${domain}" is declared but contains no notes`));
     }
     for (const domain of declared) {
         const parent = resolveParent(domain);

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

@@ -1,6 +1,6 @@
 /**
  * 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).
+ * when the value is absent, or `null` when the value is present but not list-shaped (so that a parser can flag it).
  */
 export declare function asStringList(value: unknown): string[] | null;
 /**

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

@@ -1,4 +1,4 @@
-/** The outcome of splitting a note: its frontmatter field map, its body, the body's start line, and any parse error. */
+/** A note split into its frontmatter field map and its body. */
 export interface ReadNote {
     fields: Record<string, unknown>;
     body: string;
@@ -10,6 +10,6 @@ export interface ReadNote {
 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.
+ * reported in `error` (never thrown), with the full content returned as the body so that a caller can still show it.
  */
 export declare function readNoteContent(content: string): ReadNote;

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

@@ -1,11 +1,8 @@
 /**
  * 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.
+ * then the body. A single leading newline on the body is dropped so that 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.
- */
+/** Atomically writes a note to `path`. 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/records/event.d.ts

@@ -1,4 +1,4 @@
-/** The impact levels an event may carry, ordered lowest to highest. */
+/** The impact levels that an event may declare, 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];
@@ -31,8 +31,8 @@ export type ParseEventResult = {
 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.
+ * empty `session` is omitted like an absent one, mirroring {@link parseEvent}: The two forms of "no session" have one
+ * representation on both parse and render, so no record can reacquire the empty field on a write.
  */
 export declare function renderEvent(record: KbEvent): {
     fields: Record<string, unknown>;

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

@@ -1,6 +1,6 @@
 /**
- * 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
+ * The formatting option that every store sets and that `.editorconfig` cannot express. Defined 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: {
@@ -10,7 +10,7 @@ export declare const canonicalPrettierConfig: {
 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. */
+/** Renders `.editorconfig`: the editor and formatter settings that 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

@@ -12,7 +12,7 @@ const CONFIG_HEADER = `# Check configuration for this knowledge store.
 # Every key is optional and falls back to the default 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. \`visibility\` declares how widely the store is
-# published, which decides what may link into it: a \`[[store:Note title]]\` link resolves only into a store as
+# published, which decides what may link into it: A \`[[store:Note title]]\` link resolves only into a store as
 # shareable as its own or more so.
 #
 `;
@@ -36,7 +36,7 @@ const PRETTIER_HEADER = `# Formatting configuration for this knowledge store.
 #
 # \`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.
+# the note. 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.
 #

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

@@ -1,21 +1,20 @@
 /**
- * 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.
+ * What {@link scaffold} did about one canonical path: `created` when it was absent, `present` when it was left as
+ * found, `replaced` when `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. */
+    /** The store-relative path, directories with 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.
+ * Writes the canonical files and directories that every knowledge-base store contains, 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.
+ * The function asserts nothing about the store: A caller that requires one to exist, or requires one not to, checks
+ * that itself.
  */
 export declare function scaffold(input: {
     storePath: string;

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

@@ -1,15 +1,14 @@
 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.
+ * The thin I/O wrapper around {@link parseAliases}; on a structural defect it throws, naming the file path.
  */
 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.
+ * Aliases are lowercased on insertion so that callers can look up case-insensitively.
+ * Throws on malformed YAML and on any structural defect, with `contextLabel` prefixed onto every message.
  */
 export declare function parseAliases(text: string, contextLabel?: string): AliasMap;

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

@@ -1,13 +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.
+ * Derives every domain implied by a note set: each note's domain, plus each of that domain's ancestors, sorted.
+ * A grouping domain that contains 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.
+ * Derives a note's domain, or `undefined` when the note is not an assertion or is at the assertions root.
+ * Scoping to the assertions root 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. */
+/** Derives a slash-path's parent, or `undefined` when it has no separator and so is at the top level. */
 export declare function resolveParent(path: string): string | undefined;

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

@@ -3,10 +3,10 @@ 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.
+ * off the entry that 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.
+ * 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;

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

@@ -53,8 +53,8 @@ function collectBlock(input) {
 function describeIssueLocation(error) {
     const issue = error.issues[0];
     if (issue === undefined) {
-        return ' — unknown error';
+        return ': unknown error';
     }
     const location = issue.path.length > 0 ? ` at ${issue.path.join('.')}` : '';
-    return `${location} — ${issue.message}`;
+    return `${location}: ${issue.message}`;
 }

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

@@ -2,12 +2,11 @@ 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.
+ * author meant.
  */
 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;
@@ -18,11 +17,11 @@ export interface TaxonomyEntry {
  * 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.
+ * loads as declaring nothing rather than failing. YAML reads such a header as null, and it is the state left behind by
+ * promoting the last entry out of a block.
  *
- * 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.
+ * Because a description may likewise be null, 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>>>>;

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

@@ -1,9 +1,8 @@
 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. */
+    /** The one-line description; when absent or empty, `writeTaxonomy` writes the key bare, with no description. */
     description?: string;
     /** Whether to declare under `provisional:` rather than `domains:`. */
     provisional: boolean;
@@ -12,13 +11,13 @@ export interface TaxonomyDeclaration {
  * 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.
+ * survive; a plain parse-and-stringify round trip would discard every comment in a hand-curated file. New keys
+ * are appended 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.
+ * A path already declared by either block is skipped rather than overwritten. A repeat call adds nothing, and 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

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

@@ -4,7 +4,7 @@
  */
 export declare function isEnoent(error: unknown): boolean;
 /**
- * Returns true when `error` carries the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
+ * Returns true when `error` has the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
  * @internal
  */
 export declare function isErrorCode(error: unknown, code: string): boolean;