@williamthorsen/kb 0.6.2 → 0.8.0

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

@@ -1,10 +1,39 @@
 import { z } from 'zod';
+/**
+ * The on-disk `.kb/config.yaml` shape. Every field is optional so a file may override only the key 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 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`. 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: the glob target set, the glob exclude set, and the store's visibility. */
 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;
 }
-export declare const defaultKbConfig: KbConfig;
+/** How widely a store is published: `shared` reaches collaborators through a remote, `private` reaches nobody else. */
+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,5 +1,13 @@
+/**
+ * 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
+ * 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";
     constructor(message: string, options?: ErrorOptions);
 }
+/** Type guard narrowing an unknown throw to a {@link KbLoaderError} via its `kind` discriminant. */
 export declare function isKbLoaderError(error: unknown): error is KbLoaderError;

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

@@ -1,5 +1,12 @@
 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 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.
+ */
 export declare function loadKbConfig(input: {
     kbRoot: KbRoot;
 }): Promise<KbConfig>;

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

@@ -32,5 +32,6 @@ export async function loadKbConfig(input) {
     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,7 +1,20 @@
 import type { KbConfig } from './config-schema.js';
+/** The note-membership predicates a {@link KbConfig} defines, all matching KB-root-relative, slash-separated paths. */
 export interface NoteScopeMatcher {
+    /** True when the path matches a `targets` glob. */
     isTarget(relativePath: string): boolean;
+    /** True when the path matches an `exclude` glob. */
     isExcluded(relativePath: string): boolean;
+    /** True when the path is a note: matched by `targets` and not `exclude`d. The `.md` gate is the caller's. */
     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`.
+ *
+ * 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 `targets`/`exclude` alone, the one place the two tools previously disagreed.
+ */
 export declare function createNoteScopeMatcher(config: KbConfig): NoteScopeMatcher;

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

@@ -1,12 +1,30 @@
+/**
+ * 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.
+ */
 export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
+/** A successfully created store and a record of what was written. */
 export interface CreatedStore {
+    /** The store's registry name (the directory's base name unless overridden). */
     name: string;
+    /** Absolute path to the store root. */
     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[];
+    /** What happened to the registry's `default_kb` pointer; absent when the store was not registered. */
     defaultKb?: DefaultKbOutcome;
 }
+/**
+ * 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.
+ */
 export type CreateInput = {
     targetDir: string;
     name?: string;
@@ -17,6 +35,7 @@ export type CreateInput = {
     registryPath: string;
     description?: string;
 });
+/** The outcome of a {@link create} call: a created store, or a categorical precondition failure. */
 export type CreateOutcome = {
     ok: true;
     created: CreatedStore;
@@ -25,4 +44,10 @@ export type CreateOutcome = {
     reason: 'kb-exists' | 'name-registered';
     message: string;
 };
+/**
+ * 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.
+ */
 export declare function create(input: CreateInput): Promise<CreateOutcome>;

package/dist/esm/create/create.js

@@ -1,11 +1,10 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { loadKbRegistry } from "../discovery/load-registry.js";
 import { registerStore } from "../discovery/register-store.js";
 import { setDefaultKb } from "../discovery/set-default-kb.js";
 import { pathExists } from "../filesystem/exists.js";
-import { ALIASES_FILE, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveEventsDir, resolveKbDir, } from "../layout/index.js";
-import { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";
+import { KB_DIR, resolveKbDir } from "../layout/index.js";
+import { scaffold } from "../scaffold/scaffold.js";
 export async function create(input) {
     const storePath = resolve(input.targetDir);
     const name = input.name ?? basename(storePath);
@@ -13,7 +12,7 @@ export async function create(input) {
         return { ok: false, reason: 'kb-exists', message: `a ${KB_DIR}/ store already exists at ${storePath}` };
     }
     if (!input.register) {
-        const created = await scaffold(storePath);
+        const created = await writeCanonicalSet(storePath);
         return { ok: true, created: { name, storePath, registered: false, created } };
     }
     const { registryPath } = input;
@@ -21,7 +20,7 @@ export async function create(input) {
     if (before.entries.some((entry) => entry.name === name)) {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
-    const created = await scaffold(storePath);
+    const created = await writeCanonicalSet(storePath);
     const described = input.description !== undefined && { description: input.description };
     const result = await registerStore({ registryPath, name, storePath, ...described });
     if (result.status === 'already-present') {
@@ -43,10 +42,7 @@ async function ensureDefaultKb(input) {
 function nameRegisteredMessage(name, registryPath) {
     return `a store named "${name}" is already registered in ${registryPath}`;
 }
-async function scaffold(storePath) {
-    await mkdir(resolveKbDir(storePath), { recursive: true });
-    await writeFile(join(storePath, CONFIG_FILE), renderConfigSeed(), 'utf8');
-    await writeFile(join(storePath, ALIASES_FILE), renderAliasesSeed(), 'utf8');
-    await mkdir(resolveEventsDir(storePath), { recursive: true });
-    return [CONFIG_FILE, ALIASES_FILE, `${CONTENT_DIR}/`, `${EVENTS_DIR}/`];
+async function writeCanonicalSet(storePath) {
+    const entries = await scaffold({ storePath });
+    return entries.filter((entry) => entry.action !== 'present').map((entry) => entry.path);
 }

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

@@ -1,3 +1,2 @@
 export type { CreatedStore, CreateInput, CreateOutcome } from './create.js';
 export { create } from './create.js';
-export { renderAliasesSeed, renderConfigSeed } from './render-seeds.js';

package/dist/esm/create/index.js

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

package/dist/esm/discovery/find-kb-root.d.ts

@@ -1,4 +1,8 @@
 import type { KbRoot } from '../types.js';
+/**
+ * Walks up the directory tree from `startDir` & returns the first ancestor containing a `.kb/` directory as a `KbRoot`.
+ * Returns `null` when the walk reaches the filesystem root without a hit.
+ */
 export declare function findKbRoot(input: {
     startDir: string;
 }): Promise<KbRoot | null>;

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

@@ -1,9 +1,11 @@
 import { z } from 'zod';
+/** Schema for a single KB entry as written in `kb.yaml`. */
 export declare const kbRegistryFileEntrySchema: z.ZodObject<{
     path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     readonly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/** Schema for the full `kb.yaml` file. */
 export declare const kbRegistryFileSchema: z.ZodObject<{
     default_kb: z.ZodOptional<z.ZodString>;
     kbs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -12,5 +14,7 @@ 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,36 @@
 import type { KbRegistry } from '../types.js';
+/**
+ * Load and merge 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.
+ * Malformed YAML, a structural defect, or a `default_kb` that names no registered KB throw.
+ */
 export declare function loadKbRegistry(input?: {
     userConfigPath?: string;
     projectDir?: string;
     home?: string;
 }): Promise<KbRegistry>;
+/** The outcome of a no-throw registry load: the resolved config plus a captured error message when loading failed. */
 export interface KbRegistryLoadResult {
+    /** The merged registry, or an empty config when loading threw. */
     config: KbRegistry;
+    /** The thrown error's message, present only when `loadKbRegistry` failed. */
     error?: string;
 }
+/**
+ * Load 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.
+ */
 export declare function tryLoadKbRegistry(input?: {
     userConfigPath?: string;
     projectDir?: string;

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

@@ -1,6 +1,17 @@
+/** 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';
 }
+/**
+ * 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
+ * direct caller, throws rather than being written), never producing a corrupt file.
+ */
 export declare function registerStore(input: {
     registryPath: string;
     name: string;

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

@@ -1,2 +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`).
+ */
 export declare function loadRegistryDocument(path: string): Promise<Document>;

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

@@ -1,6 +1,18 @@
+/**
+ * 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.
+ */
 export declare function clearDefaultKb(input: {
     registryPath: string;
 }): Promise<void>;
+/**
+ * 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.
+ */
 export declare function setDefaultKb(input: {
     registryPath: string;
     name: string;

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

@@ -1,6 +1,19 @@
+/** 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.
+     * 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`.
+     */
     treatErrorsAsAbsent?: boolean;
 }
+/** Returns true when `path` exists and is a directory. See {@link ExistsOptions} for the absence policy. */
 export declare function directoryExists(path: string, options?: ExistsOptions): Promise<boolean>;
+/** Returns true when something exists at `path`. See {@link ExistsOptions} for the absence policy. */
 export declare function pathExists(path: string, options?: ExistsOptions): Promise<boolean>;

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