@williamthorsen/kb 0.7.0 → 0.8.1

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

@@ -1,22 +1,40 @@
 import { z } from 'zod';
 /**
- * The on-disk `.kb/config.yaml` shape. Both fields are optional so a file may override only the dimension it cares
+ * The on-disk `.kb/config.yaml` shape. Every field is optional so that a file may override only the key that it cares
  * about; an absent field falls back to {@link defaultKbConfig}.
  */
 export declare const configFileShape: z.ZodObject<{
     targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        shared: "shared";
+    }>>;
 }, z.core.$strip>;
-/** The effective check configuration: the glob target set and the glob exclude set. */
+/**
+ * The configuration applied when `.kb/config.yaml` is absent or omits a field. The default exclude names `node_modules`
+ * alone, because `createNoteScopeMatcher` already excludes dot-directories. Visibility defaults to the safer of the two
+ * values, so a store that has not declared itself never widens what may link into it.
+ */
+export declare const defaultKbConfig: KbConfig;
+/**
+ * Whether a link from a store of `source` visibility may resolve into one of `target` visibility. A link never
+ * increases disclosure: It may point at a store as shareable as its own or more so, never at a less shareable one.
+ */
+export declare function isAtLeastAsShareable(input: {
+    source: StoreVisibility;
+    target: StoreVisibility;
+}): boolean;
+/** The effective check configuration, in which a default fills every field that `.kb/config.yaml` omits. */
 export interface KbConfig {
     /** Glob patterns (slash-separated, kbRoot-relative) selecting which notes `check` enumerates. */
     targets: readonly string[];
     /** Glob patterns excluded from enumeration even when a target matches. */
     exclude: readonly string[];
+    /** How widely the store is published, which decides what may link into it. */
+    visibility: StoreVisibility;
 }
 /**
- * The configuration applied when `.kb/config.yaml` is absent or omits a field. Targets the `content/`-scoped layout
- * the owner's stores use; with `picomatch` `dot:false`, dot-directories (`.kb`, `.git`, `.agents`) are excluded
- * implicitly, so the default exclude only names `node_modules`.
+ * How widely a store is published: `shared` is available to collaborators through a remote, `private` to nobody else.
  */
-export declare const defaultKbConfig: KbConfig;
+export type StoreVisibility = NonNullable<z.infer<typeof configFileShape>['visibility']>;

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

@@ -3,8 +3,17 @@ import { CONTENT_DIR } from "../layout/index.js";
 export const configFileShape = z.object({
     targets: z.array(z.string()).optional(),
     exclude: z.array(z.string()).optional(),
+    visibility: z.enum(['private', 'shared']).optional(),
 });
 export const defaultKbConfig = {
     targets: [`${CONTENT_DIR}/**/*.md`],
     exclude: ['**/node_modules/**'],
+    visibility: 'private',
+};
+export function isAtLeastAsShareable(input) {
+    return VISIBILITY_RANK[input.target] >= VISIBILITY_RANK[input.source];
+}
+const VISIBILITY_RANK = {
+    private: 0,
+    shared: 1,
 };

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

@@ -1,4 +1,4 @@
-export { configFileShape, defaultKbConfig, type KbConfig } from './config-schema.js';
+export { configFileShape, defaultKbConfig, isAtLeastAsShareable, type KbConfig, type StoreVisibility, } from './config-schema.js';
 export { isKbLoaderError, KbLoaderError } from './kb-loader-error.js';
 export { loadKbConfig } from './load-config.js';
 export { createNoteScopeMatcher, type NoteScopeMatcher } from './note-scope.js';

package/dist/esm/config/index.js

@@ -1,4 +1,4 @@
-export { configFileShape, defaultKbConfig } from "./config-schema.js";
+export { configFileShape, defaultKbConfig, isAtLeastAsShareable, } from "./config-schema.js";
 export { isKbLoaderError, KbLoaderError } from "./kb-loader-error.js";
 export { loadKbConfig } from "./load-config.js";
 export { createNoteScopeMatcher } from "./note-scope.js";

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

@@ -1,12 +1,12 @@
 /**
- * The typed error thrown by the KB loaders (`loadKbConfig`, `loadAliases`) on a structural defect: malformed YAML or
- * wrong types. The `kind` discriminant lets a caller distinguish a recoverable config or alias defect from any other
+ * The typed error thrown by the loaders and writers of a KB's YAML files on a structural defect, such as malformed YAML
+ * or wrong types. The `kind` discriminant lets a caller distinguish a recoverable defect in such a file from any other
  * throw (an enumeration or detection crash) without matching on message text or relying on `instanceof` surviving a
  * bundle boundary.
  */
 export declare class KbLoaderError extends Error {
-    /** Discriminant for narrow catch boundaries; survives serialization and bundling unlike `instanceof`. */
     readonly kind: "KbLoaderError";
+    /** Names the error after its class. */
     constructor(message: string, options?: ErrorOptions);
 }
 /** Type guard narrowing an unknown throw to a {@link KbLoaderError} via its `kind` discriminant. */

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

@@ -2,10 +2,10 @@ import type { KbRoot } from '../types.js';
 import { type KbConfig } from './config-schema.js';
 /**
  * Loads the effective check configuration for a KB root. Returns {@link defaultKbConfig} verbatim when no
- * `.kb/config.yaml` exists; a file present but omitting `targets` or `exclude` inherits that field's default.
+ * `.kb/config.yaml` exists; a file present but omitting a field inherits that field's default.
  *
- * Mirrors {@link loadAliases}: a single plain-object input, structural defects (malformed YAML, wrong types) throw a
- * {@link KbLoaderError} naming the file. I/O errors other than a missing file propagate.
+ * Structural defects (malformed YAML, wrong types) throw a {@link KbLoaderError} naming the file. I/O errors other than
+ * a missing file propagate.
  */
 export declare function loadKbConfig(input: {
     kbRoot: KbRoot;

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

@@ -27,10 +27,11 @@ export async function loadKbConfig(input) {
     }
     const result = configFileShape.safeParse(parsed ?? {});
     if (!result.success) {
-        throw new KbLoaderError(`${path}: invalid config.yaml — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+        throw new KbLoaderError(`${path}: invalid config.yaml: ${result.error.issues[0]?.message ?? 'unknown error'}`);
     }
     return {
         targets: result.data.targets ?? defaultKbConfig.targets,
         exclude: result.data.exclude ?? defaultKbConfig.exclude,
+        visibility: result.data.visibility ?? defaultKbConfig.visibility,
     };
 }

package/dist/esm/config/note-scope.d.ts

@@ -1,5 +1,7 @@
 import type { KbConfig } from './config-schema.js';
-/** The note-membership predicates a {@link KbConfig} defines, all matching KB-root-relative, slash-separated paths. */
+/**
+ * The note-membership predicates defined by a {@link KbConfig}, all matching KB-root-relative, slash-separated paths.
+ */
 export interface NoteScopeMatcher {
     /** True when the path matches a `targets` glob. */
     isTarget(relativePath: string): boolean;
@@ -9,12 +11,10 @@ export interface NoteScopeMatcher {
     isNote(relativePath: string): boolean;
 }
 /**
- * Builds the note-membership predicates for a KB config — the single definition of "a note" shared by
- * `enumerateNotes` (which `kb check`/`kb-curate` drive) and `kb-retrieve`. Both axes match with `picomatch`'s
- * `dot:false`, so dot-directories (`.kb`, `.git`, `.agents`) are excluded implicitly without naming them in `exclude`.
+ * Builds the note-membership predicates for a KB config, the single definition of "a note". Both axes match with
+ * `picomatch`'s `dot:false`, so dot-directories (`.kb`, `.git`, `.agents`) are excluded implicitly without naming them
+ * in `exclude`.
  *
- * The `.md` extension gate is deliberately left to the caller: `enumerateNotes` applies its own `.endsWith('.md')`
- * during the walk, and `kb-retrieve` constrains ripgrep with `--glob '*.md'`. Keeping it out of `isNote` lets this
- * matcher govern only the `targets`/`exclude` dimension, the one place the two tools previously disagreed.
+ * The matcher applies `targets` and `exclude` alone: Each caller applies its own `.md` extension gate.
  */
 export declare function createNoteScopeMatcher(config: KbConfig): NoteScopeMatcher;

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

@@ -1,8 +1,8 @@
 /**
  * What `create` did about the registry's `default_kb` pointer when registering a store:
- * `set` — it was unset and the new store was the only KB, so the store became the default;
- * `unchanged` — a default was already set and left untouched;
- * `needs-selection` — it was unset but other KBs exist, so the caller should prompt for a choice.
+ * - `set`: It was unset and the new store was the only KB, so the store became the default.
+ * - `unchanged`: A default was already set and left untouched.
+ * - `needs-selection`: It was unset but other KBs exist; the caller should prompt for a choice.
  */
 export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
 /** A successfully created store and a record of what was written. */
@@ -13,7 +13,6 @@ export interface CreatedStore {
     storePath: string;
     /** The description written into the registry entry; absent when none was supplied. */
     description?: string;
-    /** Whether the store was registered in the kb.yaml registry. */
     registered: boolean;
     /** Store-relative paths created by the scaffold. */
     created: readonly string[];
@@ -21,7 +20,7 @@ export interface CreatedStore {
     defaultKb?: DefaultKbOutcome;
 }
 /**
- * Inputs for {@link create}. `registryPath` and `description` belong to the registering form alone: a description is
+ * Inputs for {@link create}. `registryPath` and `description` belong to the registering form alone: A description is
  * only ever written into a registry entry, so supplying one without registering is a type error rather than a value
  * that would be silently discarded.
  */
@@ -46,8 +45,9 @@ export type CreateOutcome = {
 };
 /**
  * Scaffolds a new knowledge-base store in `targetDir` and, unless `register` is false, registers it in the kb.yaml
- * registry. Both preconditions — an existing `.kb/`, and (when registering) an already-registered name — are checked
- * before anything is written, so a precondition failure leaves the filesystem untouched. Genuine I/O failures
- * propagate.
+ * registry. Both preconditions, an existing `.kb/` and (when registering) an already-registered name, are checked
+ * before anything is written. A precondition failure leaves the filesystem untouched. A name collision that the
+ * registry writer detects only at write time also returns `name-registered`, after the scaffold is written. Genuine
+ * I/O failures propagate.
  */
 export declare function create(input: CreateInput): Promise<CreateOutcome>;

package/dist/esm/discovery/kb-registry-schema.d.ts

@@ -14,7 +14,5 @@ export declare const kbRegistryFileSchema: z.ZodObject<{
         readonly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-/** The validated on-disk entry shape. */
 export type KbRegistryFileEntry = z.infer<typeof kbRegistryFileEntrySchema>;
-/** The validated on-disk file shape. */
 export type KbRegistryFile = z.infer<typeof kbRegistryFileSchema>;

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 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
+ * 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` 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>;