@cstart/coldstart 2.0.0

package/dist/kb/lookup.d.ts

@@ -0,0 +1,55 @@
+/**
+ * kb lookup — everything the notebook knows at an exact (path[, symbol])
+ * address. This is the read side of the address-based dedup story: before
+ * recording a file-anchored fact, an agent looks the address up; the same
+ * surface answers "what do we know about this file?" during navigation.
+ *
+ * Flow back-links are DERIVED here at read time from flow steps (which already
+ * carry {path, symbols}) — nothing is stored on the file note, so the links
+ * can never go stale and there is nothing for a writer to forget.
+ */
+import type { AnchorState, Facet, Feature, FileCharacter, LessonKind } from './types.js';
+export interface LookupFileNote {
+    id: string;
+    character?: FileCharacter;
+    summary?: string;
+    /** All facets, or just the addressed one when a symbol was given. */
+    facets: Facet[];
+    /** Manual part-of pointers recorded on the note itself. */
+    features: Feature[];
+    state: AnchorState;
+}
+export interface LookupFlowHit {
+    id: string;
+    title: string;
+    /** 1-based step positions in the flow that touch the address. */
+    steps: {
+        index: number;
+        role: string;
+        symbols?: string[];
+    }[];
+    /** True when the flow matched ONLY because the address is one of its anchors
+     *  (its freshness contract) and it has no step at this exact path. Without
+     *  this, a flow that watches a file but narrates its story elsewhere would be
+     *  invisible to the pre-edit gate — a real false-negative (see arches: ~14%
+     *  of flows anchor a file they have no step at). */
+    viaAnchor?: boolean;
+}
+export interface LookupLessonHit {
+    id: string;
+    kind?: LessonKind;
+    title: string;
+    gist: string;
+}
+export interface LookupResult {
+    path: string;
+    symbol?: string;
+    fileNote: LookupFileNote | null;
+    flows: LookupFlowHit[];
+    lessons: LookupLessonHit[];
+    warnings: string[];
+}
+export declare function kbLookup(root: string, rawPath: string, symbol?: string): LookupResult;
+/** CLI text view. Empty result → a single "nothing recorded" line. */
+export declare function renderLookup(r: LookupResult): string;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/kb/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/kb/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKzF,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC7D;;;;wDAIoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAkDrF;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CA2BpD"}

package/dist/kb/lookup.js

@@ -0,0 +1,92 @@
+import { fileNoteId } from './ids.js';
+import { loadAll } from './store.js';
+import { stampAnchors } from './freshness.js';
+const normPath = (p) => p.replace(/^\.\//, '');
+export function kbLookup(root, rawPath, symbol) {
+    const path = normPath(rawPath);
+    const { notes, warnings } = loadAll(root);
+    const result = { path, ...(symbol ? { symbol } : {}), fileNote: null, flows: [], lessons: [], warnings };
+    const fnote = notes.find((n) => n.id === fileNoteId(path) && n.status === 'active');
+    if (fnote) {
+        const facets = symbol ? fnote.facets.filter((f) => f.symbol === symbol) : fnote.facets;
+        result.fileNote = {
+            id: fnote.id,
+            ...(fnote.character ? { character: fnote.character } : {}),
+            ...(fnote.summary ? { summary: fnote.summary } : {}),
+            facets,
+            features: fnote.features,
+            state: stampAnchors(root, fnote.anchors.filter((a) => normPath(a.path) === path))[0]?.state ?? 'unverified',
+        };
+    }
+    for (const n of notes) {
+        if (n.status !== 'active')
+            continue;
+        if (n.type === 'flow') {
+            // A step with no declared symbols can't be ruled out for a symbol query —
+            // include it (surface, don't steer); symbol-declared steps must overlap.
+            const steps = n.steps
+                .map((s, i) => ({ s, index: i + 1 }))
+                .filter(({ s }) => normPath(s.path) === path && (!symbol || !s.symbols?.length || s.symbols.includes(symbol)))
+                .map(({ s, index }) => ({ index, role: s.role, ...(s.symbols?.length ? { symbols: s.symbols } : {}) }));
+            if (steps.length) {
+                result.flows.push({ id: n.id, title: n.title, steps });
+            }
+            else {
+                // No step at this exact path — but the flow may still ANCHOR it (its
+                // freshness contract). Surface it as an anchor-only hit so the pre-edit
+                // gate never hides a flow that depends on the file being edited.
+                const anchored = n.anchors.some((a) => normPath(a.path) === path && (!symbol || !a.symbols?.length || a.symbols.includes(symbol)));
+                if (anchored)
+                    result.flows.push({ id: n.id, title: n.title, steps: [], viaAnchor: true });
+            }
+        }
+        else if (n.type === 'lesson') {
+            const hit = n.anchors.some((a) => normPath(a.path) === path && (!symbol || !a.symbols?.length || a.symbols.includes(symbol)));
+            if (hit) {
+                result.lessons.push({
+                    id: n.id,
+                    ...(n.kind ? { kind: n.kind } : {}),
+                    title: n.title,
+                    gist: (n.body ?? '').split('\n')[0].slice(0, 160),
+                });
+            }
+        }
+    }
+    return result;
+}
+/** CLI text view. Empty result → a single "nothing recorded" line. */
+export function renderLookup(r) {
+    const addr = r.symbol ? `${r.path} :: ${r.symbol}` : r.path;
+    if (!r.fileNote && !r.flows.length && !r.lessons.length) {
+        return `no notebook knowledge at ${addr} — nothing recorded yet.`;
+    }
+    const out = [addr];
+    if (r.fileNote) {
+        const f = r.fileNote;
+        out.push(`file note: ${f.id}${f.character ? ` (${f.character})` : ''} [${f.state}]`);
+        if (f.summary && (!r.symbol || f.character !== 'hub'))
+            out.push(`  ${f.summary.split('\n')[0]}`);
+        for (const facet of f.facets) {
+            out.push(`  facet ${facet.symbol}: ${facet.detail}${facet.flows?.length ? ` — flows: ${facet.flows.map((x) => `[[${x}]]`).join(' ')}` : ''}`);
+        }
+        for (const feat of f.features)
+            out.push(`  part of [[${feat.concept_id}]]${feat.role ? ` — ${feat.role}` : ''}`);
+    }
+    if (r.flows.length) {
+        out.push(`flows touching ${addr}:`);
+        for (const fl of r.flows) {
+            if (fl.viaAnchor)
+                out.push(`  [[${fl.id}]] — depends on this file (no step here; re-verify the flow if you change it)`);
+            else
+                for (const s of fl.steps)
+                    out.push(`  [[${fl.id}]] step ${s.index} — ${s.role}`);
+        }
+    }
+    if (r.lessons.length) {
+        out.push(`lessons anchored here:`);
+        for (const l of r.lessons)
+            out.push(`  [[${l.id}]]${l.kind ? ` (${l.kind})` : ''} — ${l.title}${l.gist ? `: ${l.gist}` : ''}`);
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=lookup.js.map

package/dist/kb/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../src/kb/lookup.ts"],"names":[],"mappings":"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"}

package/dist/kb/notes-index.d.ts

@@ -0,0 +1,31 @@
+import type { CodebaseIndex } from '../types.js';
+export declare const KB_NOTES_INDEX_VERSION = 1;
+export interface KbAbsenceStamp {
+    /** Echo of the terms that were re-run — a reader ignores the stamp when the
+     *  note's scope.terms have changed since the keeper last looked. */
+    terms: string[];
+    /** Live matches after the note's glob filter. Empty = the absence holds. */
+    matches: string[];
+    checkedAt: number;
+}
+export interface KbNotesIndex {
+    v: typeof KB_NOTES_INDEX_VERSION;
+    builtAt: number;
+    /** anchored path → symbol names declared in that file (per the code index) */
+    anchors: Record<string, string[]>;
+    /** absence-note id → verdict stamp */
+    absence: Record<string, KbAbsenceStamp>;
+}
+export declare function kbNotesIndexPath(rootDir: string, baseCacheDir?: string): string;
+/** Does this stamp cover the note's CURRENT terms? Order-insensitive — the
+ *  search semantics don't depend on term order, so a reordering edit must not
+ *  invalidate an otherwise-valid stamp. */
+export declare function stampCoversTerms(stamp: KbAbsenceStamp | undefined, terms: string[]): stamp is KbAbsenceStamp;
+/** Derive the notes index from the live code index + the folded notebook. */
+export declare function buildKbNotesIndex(index: CodebaseIndex, rootDir: string): Promise<KbNotesIndex>;
+/** Atomic write (temp + rename) — a reader never sees a half-written index. */
+export declare function saveKbNotesIndex(rootDir: string, kb: KbNotesIndex, baseCacheDir?: string): Promise<void>;
+/** Sync read for the query surfaces. null = absent/corrupt/wrong version —
+ *  callers degrade (no lane 2, absence prints "not re-verified"). */
+export declare function loadKbNotesIndex(rootDir: string, baseCacheDir?: string): KbNotesIndex | null;
+//# sourceMappingURL=notes-index.d.ts.map

package/dist/kb/notes-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes-index.d.ts","sourceRoot":"","sources":["../../src/kb/notes-index.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAGxC,MAAM,WAAW,cAAc;IAC7B;wEACoE;IACpE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACzC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;2CAE2C;AAC3C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,cAAc,CAI5G;AAYD,6EAA6E;AAC7E,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAyBpG;AAED,+EAA+E;AAC/E,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9G;AAED;qEACqE;AACrE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQ5F"}

package/dist/kb/notes-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes-index.js","sourceRoot":"","sources":["../../src/kb/notes-index.ts"],"names":[],"mappings":"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"}

package/dist/kb/raw-log.d.ts

@@ -0,0 +1,34 @@
+import type { NewRecordInput, RawRecord } from './types.js';
+export declare const KB_RAW_VERSION = 1;
+/** Repo-relative notes dir — the openable-path pointer printed on query
+ *  surfaces (find Summary: line, kb search results). Agents run from the repo
+ *  root, so `<NOTES_REL>/<id>.md` is directly Read-able. */
+export declare const NOTES_REL = ".coldstart/notebook/notes";
+export declare function notebookDir(root: string): string;
+export declare function rawDir(root: string): string;
+export declare function rawPath(root: string, id: string): string;
+export interface AppendOptions {
+    /** Fail with EEXIST if the log already exists (O_EXCL). Used when a freshly
+     *  COINED flow/lesson id is first written: two concurrent sessions can coin
+     *  the same id (both list the dir before either creates the file), and
+     *  without exclusivity their records silently merge into one note. The
+     *  caller catches EEXIST and re-coins. Never used for file notes — their id
+     *  is derived from the path, so concurrent writers SHOULD share one log. */
+    exclusive?: boolean;
+}
+/**
+ * Stamp `v`/`ts`, inject hashes for `verified` paths, append one line.
+ * Returns the record as written. Throws on an invalid envelope — append is the
+ * write gate; tolerance belongs to the READ side.
+ */
+export declare function appendRecord(root: string, input: NewRecordInput, opts?: AppendOptions): RawRecord;
+export interface ReadLogResult {
+    /** Parsed objects in file order — structural validation happens in fold(). */
+    records: unknown[];
+    warnings: string[];
+}
+/** Tolerant line-by-line read. Missing file → empty log (not an error). */
+export declare function readLog(root: string, id: string): ReadLogResult;
+/** All note ids present in the raw dir (one log file per note). */
+export declare function listIds(root: string): string[];
+//# sourceMappingURL=raw-log.d.ts.map

package/dist/kb/raw-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-log.d.ts","sourceRoot":"","sources":["../../src/kb/raw-log.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAU,MAAM,YAAY,CAAC;AAKpE,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;4DAE4D;AAC5D,eAAO,MAAM,SAAS,8BAA8B,CAAC;AAErD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AACD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;gFAK4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,GAAE,aAAkB,GAAG,SAAS,CAyBrG;AAED,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAoB/D;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW9C"}

package/dist/kb/raw-log.js

@@ -0,0 +1,106 @@
+/**
+ * The `.raw` log — append + tolerant read of `.coldstart/notebook/.raw/<id>.jsonl`.
+ *
+ * Append is the ONLY writer of records; it stamps `v` and `ts` and injects a
+ * live hash for every path the agent marked `verified` (the agent never writes
+ * a hash). Read is tolerant: bad JSON lines and structurally-invalid records
+ * are skipped with a warning, never a hard error — the log is a forever-format
+ * shared across coldstart versions and git branches.
+ */
+import { readFileSync, appendFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { hashFile } from './freshness.js';
+import { gitHeadSha } from './git.js';
+import { isValidId } from './ids.js';
+export const KB_RAW_VERSION = 1;
+/** Repo-relative notes dir — the openable-path pointer printed on query
+ *  surfaces (find Summary: line, kb search results). Agents run from the repo
+ *  root, so `<NOTES_REL>/<id>.md` is directly Read-able. */
+export const NOTES_REL = '.coldstart/notebook/notes';
+export function notebookDir(root) {
+    return join(root, '.coldstart', 'notebook');
+}
+export function rawDir(root) {
+    return join(notebookDir(root), '.raw');
+}
+export function rawPath(root, id) {
+    return join(rawDir(root), `${id}.jsonl`);
+}
+/**
+ * Stamp `v`/`ts`, inject hashes for `verified` paths, append one line.
+ * Returns the record as written. Throws on an invalid envelope — append is the
+ * write gate; tolerance belongs to the READ side.
+ */
+export function appendRecord(root, input, opts = {}) {
+    if (!input.id || !isValidId(input.id))
+        throw new Error(`invalid note id: ${JSON.stringify(input.id)}`);
+    if (!['file', 'flow', 'lesson'].includes(input.type))
+        throw new Error(`invalid note type: ${JSON.stringify(input.type)}`);
+    if (!['put', 'retract', 'supersede'].includes(input.op))
+        throw new Error(`invalid op: ${JSON.stringify(input.op)}`);
+    const record = { ...input, v: KB_RAW_VERSION, ts: new Date().toISOString() };
+    // Provenance stamp — tool-supplied like ts; an agent-written head is overridden.
+    const head = gitHeadSha(root);
+    if (head)
+        record.head = head;
+    else
+        delete record.head;
+    if (record.op === 'put' && Array.isArray(record.verified) && record.verified.length) {
+        const anchors = Array.isArray(record.anchors) ? record.anchors.map((a) => ({ ...a })) : [];
+        for (const rel of record.verified) {
+            const hash = hashFile(root, rel);
+            const existing = anchors.find((a) => a.path === rel);
+            if (existing) {
+                existing.hash = hash;
+                if (head)
+                    existing.head = head;
+            }
+            else
+                anchors.push({ path: rel, hash, ...(head ? { head } : {}) });
+        }
+        record.anchors = anchors;
+    }
+    mkdirSync(rawDir(root), { recursive: true });
+    appendFileSync(rawPath(root, record.id), JSON.stringify(record) + '\n', opts.exclusive ? { flag: 'ax' } : undefined);
+    return record;
+}
+/** Tolerant line-by-line read. Missing file → empty log (not an error). */
+export function readLog(root, id) {
+    const records = [];
+    const warnings = [];
+    let text = '';
+    try {
+        text = readFileSync(rawPath(root, id), 'utf8');
+    }
+    catch {
+        return { records, warnings };
+    }
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            warnings.push(`${id}.jsonl line ${i + 1}: unparseable JSON — skipped`);
+        }
+    }
+    return { records, warnings };
+}
+/** All note ids present in the raw dir (one log file per note). */
+export function listIds(root) {
+    let entries = [];
+    try {
+        entries = readdirSync(rawDir(root));
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((f) => f.endsWith('.jsonl'))
+        .map((f) => f.slice(0, -'.jsonl'.length))
+        .sort();
+}
+//# sourceMappingURL=raw-log.js.map

package/dist/kb/raw-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-log.js","sourceRoot":"","sources":["../../src/kb/raw-log.ts"],"names":[],"mappings":"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"}

package/dist/kb/render.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Render — FoldedNote → derived markdown (never load-bearing for retrieval;
+ * search consumes the FoldedNote directly, so this file is the human/Obsidian
+ * view and what recall inlines).
+ *
+ * Dual layer: frontmatter = machine contract (OKF-conformant: `type` present,
+ * unknown fields preserved), body = agent prose (grepped, never parsed).
+ * Anchors render as one JSON object per line (valid YAML flow mapping, and
+ * trivially machine-readable back). Freshness is NEVER rendered — it is
+ * computed at read time; a rendered stamp would be stale-at-write.
+ *
+ * Ecosystem conventions: `aliases` (Obsidian frontmatter), `[[wikilink]]`
+ * concept references in prose.
+ */
+import type { FoldedNote } from './types.js';
+export declare function renderNote(note: FoldedNote): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/kb/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/kb/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAqCnD"}

package/dist/kb/render.js

@@ -0,0 +1,101 @@
+const yamlStr = (s) => JSON.stringify(String(s));
+export function renderNote(note) {
+    const fm = ['---'];
+    fm.push(`id: ${note.id}`);
+    fm.push(`type: ${note.type}`);
+    if (note.character)
+        fm.push(`character: ${note.character}`);
+    if (note.kind)
+        fm.push(`kind: ${note.kind}`);
+    fm.push(`title: ${yamlStr(note.title)}`);
+    if (note.aliases.length)
+        fm.push(`aliases: [${note.aliases.map(yamlStr).join(', ')}]`);
+    if (note.anchors.length) {
+        fm.push('anchors:');
+        for (const a of note.anchors)
+            fm.push(`  - ${JSON.stringify(a)}`);
+    }
+    if (note.scope)
+        fm.push(`scope: ${JSON.stringify(note.scope)}`);
+    fm.push(`status: ${note.status}`);
+    if (note.supersededBy)
+        fm.push(`superseded_by: ${note.supersededBy}`);
+    fm.push(`updated: ${note.updated}`);
+    fm.push(`edits: ${note.edits}`);
+    // Tolerant reader: unknown record fields survive into the frontmatter.
+    for (const [k, v] of Object.entries(note.extra)) {
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k))
+            fm.push(`${k}: ${JSON.stringify(v)}`);
+    }
+    fm.push('---');
+    const body = ['', `# ${note.title}`, ''];
+    if (note.status === 'superseded' && note.supersededBy) {
+        body.push(`> Superseded by [[${note.supersededBy}]].`, '');
+    }
+    if (note.status === 'retracted') {
+        body.push(`> Retracted — kept for history; do not rely on this note.`, '');
+    }
+    if (note.type === 'file')
+        renderFileBody(note, body);
+    else if (note.type === 'flow')
+        renderFlowBody(note, body);
+    else
+        renderLessonBody(note, body);
+    return fm.join('\n') + '\n' + body.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+function renderFileBody(note, body) {
+    if (note.summary)
+        body.push(note.summary, '');
+    if (note.facets.length) {
+        body.push('## Facets', '');
+        for (const f of note.facets) {
+            const flows = f.flows?.length ? ` — ${f.flows.map((x) => `[[${x}]]`).join(' ')}` : '';
+            body.push(`- **${f.symbol}** — ${f.detail}${flows}`);
+        }
+        body.push('');
+    }
+    if (note.behaviors.length) {
+        body.push('## Behaviors', '');
+        for (const b of note.behaviors) {
+            const sym = b.symbols?.length ? ` (\`${b.symbols.join('`, `')}\`)` : '';
+            body.push(`- **${b.concept_id}**${sym} — ${b.detail}`);
+        }
+        body.push('');
+    }
+    if (note.features.length) {
+        body.push('## Part of', '');
+        for (const f of note.features)
+            body.push(`- [[${f.concept_id}]]${f.role ? ` — ${f.role}` : ''}`);
+        body.push('');
+    }
+}
+function renderFlowBody(note, body) {
+    if (note.summary)
+        body.push(note.summary, '');
+    if (note.steps.length) {
+        body.push('## Steps', '');
+        note.steps.forEach((s, i) => {
+            const sym = s.symbols?.length ? ` (\`${s.symbols.join('`, `')}\`)` : '';
+            body.push(`${i + 1}. \`${s.path}\`${sym} — ${s.role}`);
+        });
+        body.push('');
+    }
+    if (note.invariants.length) {
+        body.push('## Invariants', '');
+        for (const inv of note.invariants)
+            body.push(`- ${inv}`);
+        body.push('');
+    }
+}
+function renderLessonBody(note, body) {
+    if (note.body)
+        body.push(note.body, '');
+    if (note.scope) {
+        body.push('## Scope (absence — freshness = re-run this search)', '');
+        body.push(`- terms: ${note.scope.terms.map((t) => `\`${t}\``).join(', ')}`);
+        if (note.scope.globs?.length)
+            body.push(`- globs: ${note.scope.globs.map((g) => `\`${g}\``).join(', ')}`);
+        body.push('');
+    }
+}
+//# sourceMappingURL=render.js.map

package/dist/kb/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/kb/render.ts"],"names":[],"mappings":"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"}

package/dist/kb/search.d.ts

@@ -0,0 +1,110 @@
+/**
+ * kb search — the 3rd core tool. A cold agent arrives with WORDS, no filenames;
+ * this is tried before `find`.
+ *
+ * Lane 1 (words→notes): task words vs title/aliases (weight 3), anchor
+ * paths+symbols+facet symbols (weight 2), prose incl. facet details (weight 1)
+ * — scored by in-house BM25 over the NOTE corpus (idf · tf-saturation · length
+ * normalization; defaults k1=1.2 b=0.75, weights tuned on real corpora).
+ * Lane 2 (code→notes): a term naming a symbol DECLARED in an anchored file
+ * surfaces the note even when the note never stored the symbol — resolved via
+ * the keeper-maintained notes index (per-anchor symbol inventories), never by
+ * scanning the code index here (C1 decoupling).
+ *
+ * Results carry freshness computed NOW (never trusted from write time);
+ * absence notes print the keeper's re-run verdict stamp. Active+fresh
+ * notes outrank stale/superseded ones as a hard tier, score within tier.
+ *
+ * Every zero-hit query is appended to the miss-log — the alias bet's failure
+ * mode is SILENT (the agent just falls through to `find`), so the miss-log is
+ * the health metric and the future source of real aliases.
+ */
+import type { FoldedNote, StampedAnchor } from './types.js';
+import { type KbNotesIndex } from './notes-index.js';
+export interface KbSearchOptions {
+    /** Keeper-maintained notes index for lane 2, absence stamps, and the
+     *  convergence implant gate. Load via loadKbNotesIndex(root) — a plain
+     *  sidecar read, safe in hook mode too. Omit → those channels degrade. */
+    notesIndex?: KbNotesIndex | null;
+    maxResults?: number;
+    /** Where the query came from — recorded in the miss-log. */
+    source?: 'tool' | 'hook';
+    /** Suppress miss-log writes (used by write-time candidate matching). */
+    noMissLog?: boolean;
+    /**
+     * Precision mode for the recall hook, whose "query" is an arbitrary user
+     * sentence: match AND score on the name/alias/anchor channels only (body
+     * coverage is trivially satisfied by long prompts sharing the repo's domain
+     * vocabulary — phase-1 arches: 12/12 body-graze injections, all irrelevant,
+     * and body coverage let padding outrank the true hit), then drop hits far
+     * below the best one (padding, not signal). Explicit tool calls stay loose
+     * (the agent chose its terms).
+     */
+    strongOnly?: boolean;
+}
+export interface KbSearchHit {
+    note: FoldedNote;
+    score: number;
+    /** 0 = active+all-anchors-fresh · 1 = active but stale · 2 = superseded/retracted */
+    tier: number;
+    stamped: StampedAnchor[];
+    /** Absence-note re-run verdict line, when applicable. */
+    absence?: string;
+    /** A code-shaped query term is DECLARED (per the keeper's per-anchor symbol
+     *  inventory) in one of this note's anchor files — the code index agreeing
+     *  with the text match. The high-precision implant gate; false when the
+     *  notes index wasn't provided. */
+    convergence: boolean;
+    /** Distinct eligible query terms that hit this note's NAME/ANCHOR channels.
+     *  In hook mode only eligible (minority + shape-ok) terms count, so this is
+     *  a scale-free convergence measure: a boilerplate graze shares ONE word
+     *  with the top note; a task that names a mechanism lands several. */
+    strongTerms: number;
+}
+export interface KbSearchResult {
+    hits: KbSearchHit[];
+    terms: string[];
+    warnings: string[];
+    /** Hits the cap dropped that still cleared the results floor — a real second
+     *  page, not tail grazes. The number the --max footer advertises; absent/0
+     *  means nothing was worth widening for. */
+    omitted?: number;
+    /** The cap actually applied (opts.maxResults ?? default) — the base for the
+     *  footer's suggested --max value. */
+    maxUsed?: number;
+}
+export declare function kbSearch(root: string, query: string, opts?: KbSearchOptions): Promise<KbSearchResult>;
+/** Implant gate — should the TOP hit's full body ride in the injection?
+ *
+ *  Layered, no absolute score constant (27q calibration, 2026-07-05):
+ *  1. convergence — a code-shaped query term is a declared symbol in the
+ *     note's anchor files (index agrees with text): 11/11 precise at rank 0.
+ *  2. dominance — sole surviving hit, or top score ≥ 1.8× the runner-up. A
+ *     scale-free ratio within one query's own result list; unlike an absolute
+ *     cut it doesn't drift with notebook size or repo vocabulary.
+ *  Together: 22/23 relevant implanted, zero false implants on that corpus.
+ *  Neither fires → gist tier, which is the pre-implant behavior. */
+export declare function shouldImplantTop(result: KbSearchResult): boolean;
+/** Hook-mode page — PREVIEW GRADE, never full-body (structural ruling
+ *  2026-07-06, after the boilerplate-poisoning incident: a wrong full-body
+ *  implant demotes the right notes; a wrong preview costs one glance).
+ *  Every hit renders as title + freshness + `→ open:` path + the same
+ *  ~340-char wrapped preview as the kb search results page (2026-07-08:
+ *  a lone surgical gist gave the agent nothing to judge it against — q14
+ *  wrong-prime; candidates with previews let it pick or reject). Full depth
+ *  is one Read of the open: path. shouldImplantTop stays exported for a
+ *  future injection A/B. Injected context is re-read every turn, so the
+ *  page stays small. */
+export declare function renderCompactPage(query: string, result: KbSearchResult): string;
+/** Tool-mode results page — search-engine shape (user ruling 2026-07-08):
+ *  many ranked results, each title + live freshness + an OPENABLE note-file
+ *  path + a ~3-line preview. Depth is one Read away, so breadth is cheap and
+ *  a ranker miss costs a glance, not the answer. The relative score floor
+ *  drops tail grazes (a generic path segment matching one anchor) that a
+ *  wider page would otherwise pad with. */
+export declare function renderResultsPage(query: string, result: KbSearchResult): string;
+/** Full-body page: every hit inlined whole. Kept for `--json` (programmatic
+ *  consumers get the complete page per hit) — tool mode now renders the
+ *  search-engine page above. */
+export declare function renderSearchPage(root: string, query: string, result: KbSearchResult): string;
+//# sourceMappingURL=search.d.ts.map

package/dist/kb/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/kb/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOvE,MAAM,WAAW,eAAe;IAC9B;;8EAE0E;IAC1E,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAgBD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;uCAGmC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB;;;0EAGsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;gDAE4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;0CACsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAsJD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2I/G;AASD;;;;;;;;;oEASoE;AACpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAKhE;AA4BD;;;;;;;;;wBASwB;AACxB,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAO/E;AAED;;;;;2CAK2C;AAC3C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAoC/E;AAeD;;gCAEgC;AAChC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAkB5F"}