@monoes/monomindcli 2.14.0 → 2.15.0

package/dist/src/knowledge/profile-store.js

@@ -0,0 +1,237 @@
+/**
+ * Per-profile capture stores (the browser track's profile feature).
+ *
+ * mono-agent has profiles — work, personal, a client — and a page captured
+ * from the browser can name the one it belongs to (`meta.profile` on the
+ * capture envelope). The promise that makes that worth having is negative:
+ * a page saved into `work` must NOT come back from a search of `personal`.
+ *
+ * WHICH MECHANISM, AND WHY. A store here is three things — a vector db
+ * directory (`dbPath`), a namespace, and the root the `doc-metadata.jsonl`
+ * lives under — and `scope` already decides all three (see
+ * document-pipeline: `namespace()`, `effectiveRoot()`, `storeDbPath()`).
+ * `global` is the existing proof: one scope value routes to a directory
+ * outside any project. A profile is the same shape, so it is expressed the
+ * same way — a scope of `profile:<id>` — rather than as a second, parallel
+ * "which brain" parameter threaded through ingest, search, cite and
+ * related. Nothing here is a new concept; it is one more value of an
+ * existing one.
+ *
+ * WHERE THE DIRECTORY GOES. Inside the global brain
+ * (`~/.monomind/global-brain/profiles/<id>`), not beside it. That is not
+ * cosmetic: `memory-bridge.getDbPath` refuses any dbPath outside the
+ * project, the per-project data dir, or the global brain, and — this is the
+ * dangerous part — a refused path does not throw, it silently falls back to
+ * the DEFAULT store. A profile brain anywhere else would quietly put every
+ * profile's captures in one database, which is the exact failure this
+ * feature exists to prevent. Being inside the global brain also inherits
+ * its protection from `cleanup --data`, which prunes `~/.monomind/projects`
+ * and deliberately never touches its sibling.
+ *
+ * UNTRUSTED INPUT. The profile id arrives from a browser extension and
+ * becomes a directory name. `isValidProfileId` is the guard, kept
+ * deliberately identical to Go's `profiledir.ValidProfileID` — the two
+ * sides of this contract must reject exactly the same strings.
+ *
+ * @module v1/cli/knowledge/profile-store
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Scopes of the form `profile:<id>` address one profile's own store. */
+export const PROFILE_SCOPE_PREFIX = 'profile:';
+/** Where a profile's brain lives inside the global brain. */
+const PROFILE_BRAIN_DIR = 'profiles';
+/** Resolved lazily so a test's env override works whatever the import order. */
+const globalBrainRoot = () => process.env.MONOMIND_GLOBAL_BRAIN_DIR || path.join(os.homedir(), '.monomind', 'global-brain');
+/**
+ * The root mono-agent keeps profile directories under. Mirrors Go's
+ * `profiledir` (`~/.monoagent/profiles/<id>/`); the env override exists for
+ * tests on this side, since the Go side's own knob is `$HOME`.
+ */
+const profilesRoot = () => process.env.MONOAGENT_PROFILES_DIR || path.join(os.homedir(), '.monoagent', 'profiles');
+/**
+ * isValidProfileId mirrors `profiledir.ValidProfileID` (Go): non-empty, no
+ * path separator, no parent-directory component. Every other function here
+ * returns undefined for an id this rejects, so a hostile id can never
+ * become a path — not even a path that is then refused.
+ */
+export function isValidProfileId(id) {
+    if (typeof id !== 'string')
+        return false;
+    const value = id.trim();
+    if (!value)
+        return false;
+    if (value.includes('/') || value.includes('\\'))
+        return false;
+    if (value.includes('..'))
+        return false;
+    return true;
+}
+/** The scope value addressing one profile's store, or undefined. */
+export function profileScope(id) {
+    return isValidProfileId(id) ? `${PROFILE_SCOPE_PREFIX}${id.trim()}` : undefined;
+}
+/** The profile id inside a `profile:<id>` scope, or undefined for any other. */
+export function parseProfileScope(scope) {
+    if (typeof scope !== 'string' || !scope.startsWith(PROFILE_SCOPE_PREFIX))
+        return undefined;
+    const id = scope.slice(PROFILE_SCOPE_PREFIX.length);
+    return isValidProfileId(id) ? id.trim() : undefined;
+}
+/** True for a scope that names a profile. */
+export const isProfileScope = (scope) => parseProfileScope(scope) !== undefined;
+// Directories already materialized in this process. See profileBrainDir.
+const created = new Set();
+/**
+ * profileBrainDir is a profile's store directory — the value used BOTH as
+ * the dbPath and as the metadata root, exactly as the global brain uses one
+ * directory for both.
+ *
+ * It creates the directory, which a resolver would not normally do. The
+ * reason is specific: `memory-bridge.getDbPath` compares
+ * `fs.realpathSync(dbPath)` against `fs.realpathSync(globalBrainDir)`, and
+ * a path that does not exist yet cannot be realpath'd. On a machine where
+ * the home directory is reached through a symlink, the two sides would then
+ * resolve differently, the guard would reject the path, and — because that
+ * guard falls back instead of throwing — the profile's captures would land
+ * in the default store together with every other profile's. Creating the
+ * directory first makes both sides resolvable and the comparison honest.
+ */
+export function profileBrainDir(id) {
+    if (!isValidProfileId(id))
+        return undefined;
+    const dir = path.join(globalBrainRoot(), PROFILE_BRAIN_DIR, id.trim());
+    if (!created.has(dir)) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            created.add(dir);
+        }
+        catch {
+            // Best effort: an unwritable brain directory is the store layer's
+            // problem to report, not a reason to fail resolution here.
+        }
+    }
+    return dir;
+}
+/**
+ * profileStoreDir is profileBrainDir for a `profile:<id>` SCOPE, and
+ * undefined for every other scope — the single function
+ * `document-store`'s `effectiveRoot`/`storeDbPath` consult, so that the
+ * routing rule lives in one place and the pipeline keeps a two-line hook.
+ *
+ * DO NOT MOVE THIS DIRECTORY OUT OF THE GLOBAL BRAIN. The nesting looks
+ * arbitrary and is not: `memory-bridge.getDbPath` accepts a dbPath only
+ * inside the project, the per-project data dir, or the global brain, and a
+ * path it does not accept is NOT rejected — it SILENTLY RETURNS THE DEFAULT
+ * STORE. So a profile brain sited anywhere else (beside the global brain,
+ * under `~/.monoagent`, under the profile's own root) does not fail: every
+ * profile's captures quietly land in one database, `work` turns up in a
+ * `personal` search, and nothing anywhere reports a problem. The feature
+ * fails by succeeding. `src/__tests__/profile-store-dbpath.test.ts` holds
+ * both halves of that — this path surviving, and an outside path silently
+ * becoming the default.
+ */
+export function profileStoreDir(scope) {
+    const id = parseProfileScope(scope);
+    return id === undefined ? undefined : profileBrainDir(id);
+}
+/**
+ * profileInboxDir is where that profile's captures land, as the Go side
+ * writes them: `~/.monoagent/profiles/<id>/.monomind/inbox`.
+ *
+ * Keyed by profile id alone. mono-agent lets a profile's root be moved
+ * (`profiles.root_dir`), and the capture inbox deliberately does NOT follow
+ * it on either side — see `ProfileInbox` in `internal/capture/profile.go`
+ * for why. This path and that one are the same rule written twice, which is
+ * the cost of the two repos agreeing about a directory at all.
+ */
+export function profileInboxDir(id) {
+    if (!isValidProfileId(id))
+        return undefined;
+    return path.join(profilesRoot(), id.trim(), '.monomind', 'inbox');
+}
+/**
+ * profileInboxes lists the profile inboxes that exist on this machine, for
+ * a sweep that wants to ingest every profile's captures rather than only
+ * the shared inbox. Missing directories are simply absent; nothing here
+ * throws.
+ */
+export function profileInboxes() {
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(profilesRoot(), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isValidProfileId(entry.name))
+            continue;
+        const inbox = profileInboxDir(entry.name);
+        const scope = profileScope(entry.name);
+        if (!inbox || !scope)
+            continue;
+        try {
+            if (!fs.statSync(inbox).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push({ id: entry.name, inbox, scope });
+    }
+    return out;
+}
+/**
+ * captureScope is the routing rule, applied once per ingest: a capture
+ * whose envelope names a profile belongs to that profile's store, whatever
+ * scope the caller reached for.
+ *
+ * The envelope wins on purpose. The profile was chosen by a person at save
+ * time, in the browser, and every automatic caller (`doc ingest` on a path
+ * outside any project, the dashboard's watcher, an inbox sweep) picks its
+ * scope from where the FILE is rather than from what it holds. A caller
+ * that genuinely means a particular store says so by passing a
+ * `profile:<id>` scope, which is returned untouched.
+ */
+export function captureScope(scope, filePath) {
+    if (isProfileScope(scope))
+        return scope;
+    const id = envelopeProfile(filePath);
+    return id ? `${PROFILE_SCOPE_PREFIX}${id}` : scope;
+}
+/** How much `meta.json` is worth reading before deciding it is not one. */
+const MAX_META_BYTES = 1024 * 1024;
+/**
+ * envelopeProfile reads the `profile` out of the capture envelope holding
+ * `filePath`, if there is one. Defensive on the same terms as the rest of
+ * capture-envelope: `meta.json` is written by a browser extension on a
+ * machine we do not control, so every failure — absent, oversized,
+ * truncated, wrong-typed, or an id that could escape a directory — is
+ * "this capture names no profile", never a thrown error.
+ */
+export function envelopeProfile(filePath) {
+    try {
+        const metaPath = path.join(path.dirname(path.resolve(filePath)), 'meta.json');
+        if (!fs.existsSync(metaPath))
+            return undefined;
+        if (fs.statSync(metaPath).size > MAX_META_BYTES)
+            return undefined;
+        const raw = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return undefined;
+        const id = raw.profile;
+        return isValidProfileId(id) ? id.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A human-readable name for a scope, for a listing or a search result. */
+export function describeScope(scope) {
+    const id = parseProfileScope(scope);
+    return id ? `profile ${id}` : scope;
+}
+//# sourceMappingURL=profile-store.js.map

package/dist/src/knowledge/profile-store.js.map

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

package/dist/src/knowledge/related.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Related-at-save (RCL-03) — "3 things in your brain relate to this".
+ *
+ * The extension calls this on EVERY capture, while the user watches. That
+ * single fact sets every design decision here:
+ *
+ *  - it never throws. An empty store, a missing embedder, a URL that was
+ *    never captured — all of them are an empty list, because a capture must
+ *    not fail because the sidebar had nothing to say;
+ *  - it is bounded. The vector pass races a timeout (default 2s) and the
+ *    cheap signals — same URL, same site, read straight off the metadata log —
+ *    are computed first, so a slow or absent embedder degrades to a fast
+ *    answer instead of no answer;
+ *  - the target itself is never in its own results, by path AND by canonical
+ *    URL, so a re-capture does not "relate" to the version it replaced.
+ *
+ * Three signals, combined: exact URL (the same page, captured before),
+ * same site, and vector similarity over the chunks already embedded.
+ *
+ * @module v1/cli/knowledge/related
+ */
+export type RelatedReason = 'same-url' | 'same-site' | 'similar';
+export interface RelatedDocument {
+    filePath: string;
+    scope: string;
+    title: string;
+    url?: string;
+    site?: string;
+    /** 0–1. Exact-URL matches lead; similarity and site agreement compound. */
+    score: number;
+    reasons: RelatedReason[];
+    capturedAt?: string;
+    /** The most similar passage, when similarity is one of the reasons. */
+    excerpt?: string;
+    chunkIndex?: number;
+    anchor?: string;
+}
+export interface RelatedOptions {
+    rootDir?: string;
+    scope?: string;
+    limit?: number;
+    /** Budget for the vector pass. The metadata signals ignore it: they are
+     *  synchronous file reads. */
+    timeoutMs?: number;
+    minScore?: number;
+    store?: 'project' | 'global' | 'all';
+    /** Text to compare against, when the caller already has it (a capture that
+     *  has not been ingested yet). */
+    text?: string;
+}
+/**
+ * The documents most related to `target` (a URL, a docId, or an indexed path).
+ *
+ * Safe to call on every capture: bounded, and empty rather than thrown on any
+ * failure.
+ */
+export declare function relatedDocuments(target: string, opts?: RelatedOptions): Promise<RelatedDocument[]>;
+//# sourceMappingURL=related.d.ts.map

package/dist/src/knowledge/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../../src/knowledge/related.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC;sCACkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAwFD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAmH5B"}

package/dist/src/knowledge/related.js

@@ -0,0 +1,222 @@
+/**
+ * Related-at-save (RCL-03) — "3 things in your brain relate to this".
+ *
+ * The extension calls this on EVERY capture, while the user watches. That
+ * single fact sets every design decision here:
+ *
+ *  - it never throws. An empty store, a missing embedder, a URL that was
+ *    never captured — all of them are an empty list, because a capture must
+ *    not fail because the sidebar had nothing to say;
+ *  - it is bounded. The vector pass races a timeout (default 2s) and the
+ *    cheap signals — same URL, same site, read straight off the metadata log —
+ *    are computed first, so a slow or absent embedder degrades to a fast
+ *    answer instead of no answer;
+ *  - the target itself is never in its own results, by path AND by canonical
+ *    URL, so a re-capture does not "relate" to the version it replaced.
+ *
+ * Three signals, combined: exact URL (the same page, captured before),
+ * same site, and vector similarity over the chunks already embedded.
+ *
+ * @module v1/cli/knowledge/related
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { captureIdentityUrl, readCaptureProvenance } from './capture-envelope.js';
+import { passageQuote } from './citation.js';
+import { documentCapturedAt, documentSite } from './library.js';
+const DEFAULT_LIMIT = 3;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_MIN_SCORE = 0.25;
+const QUERY_CHARS = 1200;
+const SAME_URL_SCORE = 1;
+/** Ceiling for everything that is not literally the same page. */
+const NEAR_SCORE_CAP = 0.95;
+const SAME_SITE_SCORE = 0.45;
+const BOTH_SIGNALS_BONUS = 0.1;
+const EXCERPT_CHARS = 200;
+function stripFragment(url) {
+    const hash = url.indexOf('#');
+    return (hash === -1 ? url : url.slice(0, hash)).trim();
+}
+function looksLikeUrl(target) {
+    return /^https?:\/\//i.test(target.trim());
+}
+function hostOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Words a URL alone gives us — the fallback query when there is no text. */
+function urlWords(url) {
+    try {
+        const u = new URL(url);
+        return [u.hostname.replace(/^www\./, ''), ...u.pathname.split(/[/\-_.]+/)]
+            .filter((w) => w && !/^\d+$/.test(w) && w.length > 1)
+            .join(' ');
+    }
+    catch {
+        return url;
+    }
+}
+async function queryText(record, target, provided) {
+    if (provided?.trim())
+        return provided.slice(0, QUERY_CHARS);
+    const parts = [];
+    if (record?.provenance?.title)
+        parts.push(record.provenance.title);
+    if (record && fs.existsSync(record.filePath)) {
+        try {
+            const { extractText } = await import('../capabilities/cap-documents.js');
+            const stat = fs.statSync(record.filePath);
+            const text = await extractText({
+                path: record.filePath,
+                absolutePath: record.filePath,
+                extension: path.extname(record.filePath).toLowerCase(),
+                size: stat.size,
+                modified: stat.mtime,
+                created: stat.birthtime,
+            });
+            if (text)
+                parts.push(text.slice(0, QUERY_CHARS));
+        }
+        catch {
+            /* fall through to the URL words */
+        }
+    }
+    if (!parts.length)
+        parts.push(urlWords(looksLikeUrl(target) ? target : path.basename(target)));
+    return parts.join('\n').slice(0, QUERY_CHARS);
+}
+/** Resolve the vector pass or give up on time — whichever comes first. */
+function withTimeout(work, ms, fallback) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(fallback), ms);
+        work
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch(() => {
+            clearTimeout(timer);
+            resolve(fallback);
+        });
+    });
+}
+/**
+ * The documents most related to `target` (a URL, a docId, or an indexed path).
+ *
+ * Safe to call on every capture: bounded, and empty rather than thrown on any
+ * failure.
+ */
+export async function relatedDocuments(target, opts = {}) {
+    try {
+        const pipeline = await import('./document-pipeline.js');
+        const scope = opts.scope;
+        const rootDir = opts.rootDir ?? pipeline.getKnowledgeRoot(scope ?? 'shared');
+        const limit = opts.limit ?? DEFAULT_LIMIT;
+        const self = pipeline.findDocumentRecord(rootDir, target, scope);
+        // A capture that has been written but not yet ingested is the case this
+        // story exists for: the extension has the directory on disk and wants to
+        // know what it relates to BEFORE the ingest finishes. Its identity comes
+        // from the envelope's own meta.json.
+        const pending = !self && !looksLikeUrl(target) ? readCaptureProvenance(target) : null;
+        const selfUrl = self?.canonicalUrl ??
+            (looksLikeUrl(target) ? stripFragment(target) : captureIdentityUrl(pending));
+        const selfSite = hostOf(selfUrl);
+        const selfPaths = new Set([self?.filePath, looksLikeUrl(target) ? undefined : path.resolve(target)].filter((p) => !!p));
+        // Excluding by URL is right when the target IS that page — an indexed
+        // document, or a caller asking about the URL itself. It is wrong for a
+        // capture still sitting in the inbox: there the earlier capture of the
+        // same page is the single most related thing in the brain.
+        const excludeByUrl = !!self || looksLikeUrl(target);
+        const isSelf = (doc) => selfPaths.has(doc.filePath) || (excludeByUrl && !!selfUrl && doc.canonicalUrl === selfUrl);
+        const docs = pipeline.listDocuments(rootDir, scope).filter((d) => !isSelf(d));
+        const byPath = new Map(docs.map((d) => [d.filePath, d]));
+        const scored = new Map();
+        const put = (doc, reason, score, extra = {}) => {
+            const existing = scored.get(doc.filePath);
+            if (existing) {
+                if (!existing.reasons.includes(reason))
+                    existing.reasons.push(reason);
+                // Agreeing signals compound, but only the same page itself reaches 1 —
+                // otherwise a same-site neighbour that also embeds well would tie with
+                // the earlier capture of this very page and win on sort order.
+                const cap = existing.reasons.includes('same-url') ? SAME_URL_SCORE : NEAR_SCORE_CAP;
+                existing.score = Math.min(cap, Math.max(existing.score, score) + BOTH_SIGNALS_BONUS);
+                Object.assign(existing, extra);
+                return;
+            }
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl ?? doc.provenance?.url;
+            scored.set(doc.filePath, {
+                filePath: doc.filePath,
+                scope: doc.scope,
+                title: doc.provenance?.title ?? path.basename(doc.filePath),
+                ...(url ? { url } : {}),
+                ...(documentSite(doc) ? { site: documentSite(doc) } : {}),
+                score,
+                reasons: [reason],
+                ...(documentCapturedAt(doc) ? { capturedAt: documentCapturedAt(doc) } : {}),
+                ...extra,
+            });
+        };
+        // 1 + 2 — the cheap signals, straight off the metadata log.
+        for (const doc of docs) {
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl;
+            if (selfUrl && url && stripFragment(url) === selfUrl)
+                put(doc, 'same-url', SAME_URL_SCORE);
+            else if (selfSite && documentSite(doc) === selfSite)
+                put(doc, 'same-site', SAME_SITE_SCORE);
+        }
+        // 3 — similarity, bounded. A store with no embeddings comes back empty
+        // here and the metadata signals still stand.
+        // For a not-yet-ingested capture the text to compare against is the file
+        // the caller pointed at, read through the same extraction the ingest uses.
+        const queryRecord = self ?? (pending ? { filePath: path.resolve(target), provenance: pending } : undefined);
+        const query = await queryText(queryRecord, target, opts.text);
+        if (query.trim()) {
+            const hits = await withTimeout(pipeline.searchKnowledge(query, {
+                scope: scope ?? 'shared',
+                rootDir,
+                limit: Math.max(limit * 6, 12),
+                minScore: opts.minScore ?? DEFAULT_MIN_SCORE,
+                store: opts.store ?? 'all',
+            }), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, []);
+            const best = new Map();
+            for (const hit of hits) {
+                if (!hit.filePath || selfPaths.has(hit.filePath))
+                    continue;
+                const current = best.get(hit.filePath);
+                if (!current || hit.similarity > current.similarity)
+                    best.set(hit.filePath, hit);
+            }
+            for (const [filePath, hit] of best) {
+                const doc = byPath.get(filePath);
+                if (!doc || isSelf(doc))
+                    continue;
+                put(doc, 'similar', Math.min(1, hit.similarity), {
+                    excerpt: passageQuote(hit.text ?? '', EXCERPT_CHARS),
+                    chunkIndex: hit.chunkIndex,
+                    ...(hit.anchor ? { anchor: hit.anchor } : {}),
+                });
+            }
+        }
+        return [...scored.values()]
+            .sort((a, b) => b.score - a.score || (b.capturedAt ?? '').localeCompare(a.capturedAt ?? ''))
+            .slice(0, limit);
+    }
+    catch (err) {
+        // Called on every capture: an unexpected failure is "nothing related",
+        // never a broken save. It is still a bug when it is one of ours, so it is
+        // visible under DEBUG rather than only in an empty sidebar.
+        if (process.env.DEBUG || process.env.MONOMIND_DEBUG) {
+            console.error(`[relatedDocuments] ${target}:`, err);
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=related.js.map

package/dist/src/knowledge/related.js.map

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

package/dist/src/knowledge/section-diff.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic diff between two versions of a captured page (RCL-08).
+ *
+ * A character diff of a re-captured page is noise: the byline date moved, an
+ * ad slot re-rendered, the markdown re-wrapped. What a watcher actually wants
+ * to be told is WHICH SECTIONS changed and roughly how much — "Pricing gained
+ * a paragraph, Changelog got three new entries, everything else is the same".
+ *
+ * So the unit here is the markdown section (heading + body), keyed by its
+ * full heading path, and the measure is words and sentences rather than
+ * characters. Sentences are also what gives a change its sample line: the
+ * first sentence that is in the new version and was not in the old one is the
+ * most useful single thing to print.
+ *
+ * No dependency, no LLM: heading paths and sentence sets are enough to say
+ * what moved.
+ *
+ * @module v1/cli/knowledge/section-diff
+ */
+export interface Section {
+    /** Full heading path, e.g. `Pricing > Enterprise`. `(intro)` for text
+     *  before the first heading. */
+    key: string;
+    heading: string;
+    level: number;
+    body: string;
+}
+export interface SectionChange {
+    key: string;
+    addedWords: number;
+    removedWords: number;
+    /** First sentence present in the new version and absent from the old. */
+    sample?: string;
+}
+export interface SectionDiff {
+    added: string[];
+    removed: string[];
+    changed: SectionChange[];
+    unchanged: number;
+    /** One line, ready to print or to put in a notification. */
+    summary: string;
+}
+/** Split markdown into sections keyed by heading path. Duplicate paths get a
+ *  `#2` suffix so two "Notes" sections never collapse into one. */
+export declare function splitSections(text: string): Section[];
+/** What changed between two versions of the same page. */
+export declare function diffSections(oldText: string, newText: string): SectionDiff;
+//# sourceMappingURL=section-diff.d.ts.map

package/dist/src/knowledge/section-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-diff.d.ts","sourceRoot":"","sources":["../../../src/knowledge/section-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,OAAO;IACtB;oCACgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;mEACmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAmCrD;AA2DD,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAgC1E"}