@monoes/monomindcli 2.13.0 → 2.14.1

package/dist/src/knowledge/citation.js

@@ -0,0 +1,252 @@
+/**
+ * Paragraph-level citation (RCL-10).
+ *
+ * A search hit already knows WHICH document it came from. A citation has to
+ * know WHERE IN IT: the character span of the chunk against the extracted
+ * text, an anchor that survives being written down, and a way back to the
+ * live page at that passage.
+ *
+ * Three pieces, deliberately separate:
+ *
+ *  - `span:<start>-<end>` — a tag written next to every chunk at ingest, so a
+ *    search result carries offsets without re-reading the document.
+ *  - the ANCHOR `<hash12>#<start>-<end>` — offsets bound to the content hash
+ *    of the exact version they were measured against. Quoting an offset range
+ *    without the version it belongs to is how citations rot: the document is
+ *    re-captured, the text shifts, and the quote silently points at other
+ *    words. A stale anchor here is DETECTED (`stale: true`), never served as
+ *    if it were still true.
+ *  - a W3C text fragment (`#:~:text=`) — the link a human clicks, which lands
+ *    on the sentence even though the site never had an id there.
+ *
+ * Everything above `resolveCitation` is pure and synchronous so the pipeline
+ * can use it while ingesting. `resolveCitation` reaches back into the
+ * document-pipeline through a DYNAMIC import: the pipeline imports this
+ * module statically, and a static import back would close the cycle.
+ *
+ * @module v1/cli/knowledge/citation
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const SPAN_TAG_PREFIX = 'span:';
+/** The tag written beside a chunk at ingest: `span:<start>-<end>`. */
+export function spanTag(startChar, endChar) {
+    return `${SPAN_TAG_PREFIX}${startChar}-${endChar}`;
+}
+/** Offsets from a chunk's tag list, or null when it predates span tags. */
+export function parseSpanTag(tags) {
+    for (const tag of tags ?? []) {
+        if (typeof tag !== 'string' || !tag.startsWith(SPAN_TAG_PREFIX))
+            continue;
+        const m = /^span:(\d+)-(\d+)$/.exec(tag);
+        if (!m)
+            continue;
+        const startChar = Number(m[1]);
+        const endChar = Number(m[2]);
+        if (endChar < startChar)
+            continue;
+        return { startChar, endChar };
+    }
+    return null;
+}
+const ANCHOR_HASH_CHARS = 12;
+/** `<hash12>#<start>-<end>` — offsets bound to the version they were measured against. */
+export function citationAnchor(contentHash, startChar, endChar) {
+    return `${(contentHash || '').slice(0, ANCHOR_HASH_CHARS)}#${startChar}-${endChar}`;
+}
+export function parseCitationAnchor(anchor) {
+    const m = /^([0-9a-f]{4,64})#(\d+)-(\d+)$/.exec((anchor || '').trim());
+    if (!m)
+        return null;
+    const startChar = Number(m[2]);
+    const endChar = Number(m[3]);
+    if (endChar < startChar)
+        return null;
+    return { hashPrefix: m[1], startChar, endChar };
+}
+/** True when the anchor was cut against this document version. */
+export function anchorMatchesHash(anchor, contentHash) {
+    const parsed = parseCitationAnchor(anchor);
+    if (!parsed)
+        return false;
+    return (contentHash || '').startsWith(parsed.hashPrefix);
+}
+// ── Quotes and links ───────────────────────────────────────────────
+const QUOTE_MAX_CHARS = 320;
+const CONTEXT_PREFIX_RE = /^(§ [^\n]*\n)+/;
+const HEADING_LINE_RE = /^\s{0,3}#{1,6}\s+/;
+/**
+ * One line of markdown as the words a reader sees.
+ *
+ * This matters more than it looks: a text fragment built from `# Pricing ##
+ * Starter Nine dollars` matches NOTHING on the live page, because the page
+ * never contained a `#`. The link is only worth having if it is made of the
+ * prose the site actually renders.
+ */
+function stripMarkdown(line) {
+    return line
+        .replace(HEADING_LINE_RE, '')
+        .replace(/^\s{0,3}>\s?/, '')
+        .replace(/^\s{0,3}([-*+]|\d+\.)\s+/, '')
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+        .replace(/`{1,3}([^`]*)`{1,3}/g, '$1')
+        .replace(/(\*\*|__)(.*?)\1/g, '$2')
+        .replace(/(\*|_)(?=\S)(.*?)(?<=\S)\1/g, '$2')
+        .trim();
+}
+/**
+ * The prose of a passage: § context prefixes gone, markdown syntax gone,
+ * whitespace collapsed.
+ *
+ * `skipHeadings` drops heading lines as well, which is what a text fragment
+ * wants — a heading is usually its own element on the page, so starting a
+ * range there matches less reliably than starting at the paragraph. It falls
+ * back to including them when the passage is nothing but headings.
+ */
+export function passageProse(passage, skipHeadings = false) {
+    const lines = String(passage ?? '')
+        .replace(CONTEXT_PREFIX_RE, '')
+        .split('\n');
+    const keep = (only) => lines
+        .filter((l) => !only || !HEADING_LINE_RE.test(l))
+        .map(stripMarkdown)
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const body = keep(skipHeadings);
+    return body || keep(false);
+}
+/** The head of a passage as a quotable sentence or two — the words a reader
+ *  would see on the page, not the markdown we stored. */
+export function passageQuote(passage, maxChars = QUOTE_MAX_CHARS) {
+    const text = passageProse(passage);
+    if (text.length <= maxChars)
+        return text;
+    const window = text.slice(0, maxChars);
+    const stop = Math.max(window.lastIndexOf('. '), window.lastIndexOf('? '), window.lastIndexOf('! '));
+    return stop > maxChars * 0.4 ? window.slice(0, stop + 1) : `${window.trimEnd()}…`;
+}
+/** `,` and `-` are syntax inside a text fragment, so they cannot be left raw. */
+function encodeFragmentPart(text) {
+    return encodeURIComponent(text).replace(/-/g, '%2D').replace(/,/g, '%2C');
+}
+const FRAGMENT_WORDS = 8;
+/**
+ * A W3C scroll-to-text fragment for this passage.
+ *
+ * Long passages use the `textStart,textEnd` form rather than the whole
+ * paragraph: the spec matches across the range, and a shorter pair survives
+ * the site re-flowing its markup between capture and click.
+ */
+export function textFragment(passage) {
+    const text = passageProse(passage, true).slice(0, 2000);
+    if (!text)
+        return '';
+    const words = text.split(' ').filter(Boolean);
+    if (words.length <= FRAGMENT_WORDS * 2)
+        return `:~:text=${encodeFragmentPart(text)}`;
+    const start = words.slice(0, FRAGMENT_WORDS).join(' ');
+    const end = words.slice(-FRAGMENT_WORDS).join(' ');
+    return `:~:text=${encodeFragmentPart(start)},${encodeFragmentPart(end)}`;
+}
+/** The captured page's URL, pointed at the passage. Returns undefined when
+ *  there is no URL — a citation into a local file has no link to give. */
+export function citationUrl(url, passage) {
+    if (!url)
+        return undefined;
+    const fragment = textFragment(passage);
+    if (!fragment)
+        return url;
+    const hash = url.indexOf('#');
+    const base = hash === -1 ? url : url.slice(0, hash);
+    return `${base}#${fragment}`;
+}
+function fileEntry(absolutePath) {
+    const stat = fs.statSync(absolutePath);
+    return {
+        path: absolutePath,
+        absolutePath,
+        extension: path.extname(absolutePath).toLowerCase(),
+        size: stat.size,
+        modified: stat.mtime,
+        created: stat.birthtime,
+    };
+}
+/**
+ * Resolve a citation back to the passage it came from.
+ *
+ * `target` is whatever the caller has written down: an indexed file path, a
+ * capture's `canonicalUrl`, or the `<scope>:<path>` docId. Throws with a
+ * message meant for a human when the document is not indexed, its file is
+ * gone, or the chunk does not exist — a citation that cannot be checked must
+ * fail loudly, not resolve to an empty string.
+ */
+export async function resolveCitation(target, opts = {}) {
+    const pipeline = await import('./document-pipeline.js');
+    const { extractText } = await import('../capabilities/cap-documents.js');
+    const rootDir = opts.rootDir ?? pipeline.getKnowledgeRoot(opts.scope);
+    const scope = opts.scope;
+    const record = pipeline.findDocumentRecord(rootDir, target, scope);
+    if (!record)
+        throw new Error(`not indexed: ${target}`);
+    if (!fs.existsSync(record.filePath)) {
+        throw new Error(`source file is gone: ${record.filePath} (re-ingest the capture to cite it)`);
+    }
+    const text = await extractText(fileEntry(record.filePath));
+    if (!text)
+        throw new Error(`no text could be extracted from ${record.filePath}`);
+    const hash = crypto.createHash('sha256').update(text).digest('hex');
+    let startChar;
+    let endChar;
+    let chunkIndex;
+    const parsedAnchor = opts.anchor ? parseCitationAnchor(opts.anchor) : null;
+    if (opts.anchor && !parsedAnchor)
+        throw new Error(`malformed citation anchor: ${opts.anchor}`);
+    if (parsedAnchor) {
+        startChar = Math.min(parsedAnchor.startChar, text.length);
+        endChar = Math.min(parsedAnchor.endChar, text.length);
+        const spans = await pipeline.chunkSpans(text);
+        chunkIndex = spans.findIndex((s) => s.startChar === startChar);
+        if (chunkIndex === -1) {
+            chunkIndex = spans.findIndex((s) => s.startChar <= startChar && startChar < s.endChar);
+        }
+    }
+    else {
+        chunkIndex = opts.chunkIndex ?? 0;
+        const spans = await pipeline.chunkSpans(text);
+        const span = spans[chunkIndex];
+        if (!span) {
+            throw new Error(`chunk ${chunkIndex} is out of range: ${path.basename(record.filePath)} has ${spans.length} chunk(s)`);
+        }
+        startChar = span.startChar;
+        endChar = span.endChar;
+    }
+    const passage = text.slice(startChar, endChar);
+    const url = record.canonicalUrl ?? record.provenance?.canonicalUrl ?? record.provenance?.url;
+    const stale = parsedAnchor
+        ? !anchorMatchesHash(opts.anchor, hash)
+        : hash !== record.contentHash;
+    return {
+        docId: `${record.scope}:${record.filePath}`,
+        filePath: record.filePath,
+        scope: record.scope,
+        chunkIndex: chunkIndex === -1 ? 0 : chunkIndex,
+        startChar,
+        endChar,
+        contentHash: hash,
+        anchor: citationAnchor(hash, startChar, endChar),
+        passage,
+        quote: passageQuote(passage),
+        ...(stale ? { stale: true } : {}),
+        ...(record.version ? { version: record.version } : {}),
+        ...(record.provenance?.title ? { title: record.provenance.title } : {}),
+        ...(url ? { url, citeUrl: citationUrl(url, passage) } : {}),
+        ...(record.provenance?.capturedAt ? { capturedAt: record.provenance.capturedAt } : {}),
+        ...(record.provenance?.source ? { source: record.provenance.source } : {}),
+        ...(record.provenance ? { provenance: record.provenance } : {}),
+    };
+}
+//# sourceMappingURL=citation.js.map

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

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

package/dist/src/knowledge/document-pipeline.d.ts

@@ -4,6 +4,8 @@
  *
  * @module v1/cli/knowledge/document-pipeline
  */
+import { type CaptureProvenance } from './capture-envelope.js';
+import { type ChunkSpan } from './citation.js';
 export interface IngestResult {
     filePath: string;
     chunksIndexed: number;
@@ -15,6 +17,16 @@ export interface IngestResult {
      *  none), and re-ingesting repairs it. Absent means the ingest was complete —
      *  a caller must not read `chunksIndexed > 0` alone as success. */
     partial?: boolean;
+    /** RCL-06: the document was already indexed at this exact extracted-text
+     *  hash, so nothing was written. Reported as "unchanged" rather than as a
+     *  skip with an error, because nothing went wrong. */
+    unchanged?: boolean;
+    /** RCL-06: 1 for a first ingest, incremented for each stored revision. */
+    version?: number;
+    /** RCL-06: contentHash of the version this one replaced, when there was one. */
+    supersedes?: string;
+    /** RCL-07: provenance read from the capture envelope's `meta.json`. */
+    provenance?: CaptureProvenance;
 }
 export interface BatchIngestResult {
     filesProcessed: number;
@@ -35,6 +47,16 @@ export interface KnowledgeExcerpt {
      *  re-ingested (its contentHash is no longer the file's current one). Only
      *  ever set when the caller opted into `includeSuperseded`. */
     superseded?: boolean;
+    /** RCL-07: capture provenance, when the document came from a capture
+     *  envelope — this is what lets a result cite the page it came from
+     *  instead of a path under `~/.monomind/inbox`. */
+    provenance?: CaptureProvenance;
+    /** RCL-10: the chunk's character span against the extracted text. Absent
+     *  for chunks stored before span tags existed — re-ingest to get them. */
+    startChar?: number;
+    endChar?: number;
+    /** RCL-10: `<hash12>#<start>-<end>`, resolvable with `monomind doc cite`. */
+    anchor?: string;
 }
 export interface DocumentMeta {
     filePath: string;
@@ -43,6 +65,16 @@ export interface DocumentMeta {
     indexedAt: string;
     scope: string;
     size: number;
+    /** RCL-06: identity URL for a captured page (`canonicalUrl`, else `url`,
+     *  fragment stripped). Absent for ordinary files on disk. */
+    canonicalUrl?: string;
+    /** RCL-06: 1 for a first ingest, +1 per stored revision. */
+    version?: number;
+    /** RCL-06: contentHash of the version this record replaced. Walk it back
+     *  through `listDocumentVersions` to reach the older ones. */
+    supersedes?: string;
+    /** RCL-07: the capture envelope's `meta.json`, normalized. */
+    provenance?: CaptureProvenance;
 }
 export declare function ingestDocument(filePath: string, scope?: string, rootDir?: string, _metadataCache?: DocumentMeta[]): Promise<IngestResult>;
 export declare function ingestDirectory(dirPath: string, scope?: string, opts?: {
@@ -85,6 +117,34 @@ export declare function searchKnowledge(query: string, opts?: {
     skipRerank?: boolean;
 }): Promise<KnowledgeExcerpt[]>;
 export declare function listDocuments(rootDir?: string, scope?: string): DocumentMeta[];
+/**
+ * Every recorded version of one document, oldest first (RCL-06).
+ *
+ * `target` is either an indexed file path or a capture's `canonicalUrl`. Read
+ * from the append-only log rather than the last-wins view, which is how a
+ * superseded version stays addressable after its record has been replaced or
+ * tombstoned.
+ *
+ * Best-effort by design: `readMetadata` compacts the log once it passes 1MB
+ * and keeps only live records, so history older than a compaction is gone.
+ * The `supersedes` pointer on each record is the durable part.
+ */
+export declare function listDocumentVersions(rootDir?: string, target?: string, scope?: string): DocumentMeta[];
+/** The store root for a scope: the global brain for `global`, else the project. */
+export declare function getKnowledgeRoot(scope?: string, rootDir?: string): string;
+/** Chunk spans for a text, using the SAME chunker the ingest used — this is
+ *  what makes a chunk index resolvable back to a character range without
+ *  storing the text twice. */
+export declare function chunkSpans(text: string): Promise<ChunkSpan[]>;
+/**
+ * The indexed record for whatever a caller wrote down: a file path, a
+ * capture's `canonicalUrl` (fragment ignored), or the `<scope>:<path>` docId.
+ *
+ * Live records win. A superseded version is only reached through the
+ * append-only log, and only when nothing live matches — otherwise citing a
+ * re-captured page would resolve against the version it replaced.
+ */
+export declare function findDocumentRecord(rootDir?: string, target?: string, scope?: string): DocumentMeta | undefined;
 export declare function removeDocument(filePath: string, scope?: string, rootDir?: string): Promise<void>;
 /**
  * True for macOS AppleDouble sidecars (`._name`).

package/dist/src/knowledge/document-pipeline.d.ts.map

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

package/dist/src/knowledge/document-pipeline.js

@@ -14,6 +14,8 @@ import { DOC_EXTENSIONS, extractText } from '../capabilities/cap-documents.js';
 // be duplicated — two copies of "which directory is this project" is exactly the
 // bug this default exists to fix.
 import { getProjectRoot } from '../memory/memory-bridge.js';
+import { captureIdentityUrl, ENVELOPE_DOCUMENTS, ENVELOPE_READABLE_FILE, envelopePrimaryDocument, readCaptureProvenance, } from './capture-envelope.js';
+import { citationAnchor, parseSpanTag, spanTag } from './citation.js';
 const DEFAULT_CHUNK_SIZE = 3200;
 const DEFAULT_OVERLAP = 400;
 // Head-of-chunk cap for text served by searchKnowledge — chunks are
@@ -311,6 +313,26 @@ function metadataPath(rootDir) {
     fs.mkdirSync(dir, { recursive: true });
     return path.join(dir, METADATA_FILE);
 }
+/** Every record ever appended, in order, including superseded versions and
+ *  removal tombstones. Reads the path directly instead of via `metadataPath`,
+ *  which mkdir's. */
+function readMetadataLog(rootDir) {
+    const file = path.join(rootDir, '.monomind', 'knowledge', METADATA_FILE);
+    if (!fs.existsSync(file))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(file, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* torn line */
+        }
+    }
+    return out;
+}
 function readMetadata(rootDir) {
     const file = metadataPath(rootDir);
     if (!fs.existsSync(file))
@@ -443,9 +465,41 @@ export async function ingestDocument(filePath, scope = 'shared', rootDir = getPr
             error: 'file too large (>50MB)',
         };
     }
+    // RCL-01/RCL-06: one capture envelope is ONE document, whichever of its
+    // members the caller points at. `page.html`/`page.mhtml` need no guard —
+    // extraction already redirects them to `readable.md`, so they hash
+    // identically and fall out as "unchanged" below. `page.pdf` does not: its
+    // text differs from the readable pass, so ingesting it alongside would
+    // version-flip the same page back and forth on every sweep.
+    const envelopePrimary = envelopePrimaryDocument(path.dirname(resolved));
+    if (envelopePrimary && envelopePrimary !== resolved) {
+        const isMember = ENVELOPE_DOCUMENTS.includes(path.basename(resolved));
+        const redirectsToPrimary = path.basename(envelopePrimary) === ENVELOPE_READABLE_FILE &&
+            (ext === '.html' || ext === '.htm' || ext === '.xhtml' || ext === '.mhtml' || ext === '.mht');
+        if (isMember && !redirectsToPrimary) {
+            return {
+                filePath: resolved,
+                chunksIndexed: 0,
+                scope,
+                skipped: true,
+                error: `capture envelope: ${path.basename(envelopePrimary)} is this capture's document`,
+            };
+        }
+    }
     rootDir = effectiveRoot(scope, rootDir);
     const meta = _metadataCache ?? readMetadata(rootDir);
-    const existing = meta.find((m) => m.filePath === resolved && m.scope === scope);
+    // RCL-07: provenance is read before extraction so it is recorded even when a
+    // later step degrades. Absent, truncated or wrong-typed `meta.json` yields
+    // null and never throws — see capture-envelope.
+    const provenance = readCaptureProvenance(resolved);
+    const canonicalUrl = captureIdentityUrl(provenance);
+    // RCL-06: identity is the PAGE, not the path. A re-capture lands in a new
+    // timestamped directory, so matching on filePath alone would file every
+    // capture of one article as a separate document.
+    const existing = meta.find((m) => m.filePath === resolved && m.scope === scope) ??
+        (canonicalUrl
+            ? meta.find((m) => m.scope === scope && m.canonicalUrl === canonicalUrl)
+            : undefined);
     let fullContent;
     try {
         const entry = toFileEntry(resolved);
@@ -464,9 +518,21 @@ export async function ingestDocument(filePath, scope = 'shared', rootDir = getPr
         };
     }
     const hash = contentHash(fullContent);
+    // RCL-06: same page, same extracted text — a no-op, not a duplicate row and
+    // not an error. `unchanged` is what a caller reports to the user.
     if (existing && existing.contentHash === hash) {
-        return { filePath: resolved, chunksIndexed: existing.chunkCount, scope, skipped: true };
+        return {
+            filePath: resolved,
+            chunksIndexed: existing.chunkCount,
+            scope,
+            skipped: true,
+            unchanged: true,
+            ...(existing.version ? { version: existing.version } : {}),
+            ...(provenance ? { provenance } : {}),
+        };
     }
+    const version = (existing?.version ?? (existing ? 1 : 0)) + 1;
+    const supersedes = existing?.contentHash || undefined;
     // NOTE: the previous version's metadata record is deliberately NOT tombstoned
     // here. `readMetadata` is last-wins per (filePath, scope), so appending the
     // new record below already supersedes the old one — the tombstone was a no-op
@@ -488,7 +554,15 @@ export async function ingestDocument(filePath, scope = 'shared', rootDir = getPr
                     value: chunk.text,
                     namespace: namespace(scope),
                     generateEmbeddingFlag: true,
-                    tags: ['document', ext, `src:${resolved}`],
+                    tags: [
+                        'document',
+                        ext,
+                        `src:${resolved}`,
+                        // RCL-10: the chunk's span against the extracted text, so a search
+                        // hit can cite a passage without re-reading the document.
+                        spanTag(chunk.startChar, chunk.endChar),
+                        ...(canonicalUrl ? [`url:${canonicalUrl}`] : []),
+                    ],
                     upsert: true,
                     dbPath: storeDbPath(scope),
                 });
@@ -522,13 +596,31 @@ export async function ingestDocument(filePath, scope = 'shared', rootDir = getPr
             indexedAt: new Date().toISOString(),
             scope,
             size: stat.size,
+            version,
+            ...(supersedes ? { supersedes } : {}),
+            ...(canonicalUrl ? { canonicalUrl } : {}),
+            ...(provenance ? { provenance } : {}),
         });
+        // A re-capture of the same page arrives at a NEW path, so the previous
+        // version's record is a different (filePath, scope) key and survives
+        // last-wins — leaving its contentHash live and its chunks answering
+        // searches forever. Tombstone it so it leaves the live-hash set, which is
+        // exactly how a same-path re-ingest already retires its predecessor.
+        //
+        // AFTER the append, never before: retiring the old version before the
+        // replacement is known to have landed is the failure mode the partial-store
+        // fix above exists to prevent.
+        if (existing && existing.filePath !== resolved) {
+            removeMetadataEntry(rootDir, existing.filePath, scope);
+        }
     }
     return {
         filePath: resolved,
         chunksIndexed: indexed,
         scope,
         skipped: false,
+        ...(complete ? { version, ...(supersedes ? { supersedes } : {}) } : {}),
+        ...(provenance ? { provenance } : {}),
         ...(complete
             ? {}
             : indexed > 0
@@ -716,8 +808,12 @@ export async function searchKnowledge(query, opts) {
         if (!result?.success || !result.results.length)
             return [];
         const hashToFile = new Map();
-        for (const m of meta)
+        const hashToProvenance = new Map();
+        for (const m of meta) {
             hashToFile.set(m.contentHash, m.filePath);
+            if (m.provenance)
+                hashToProvenance.set(m.contentHash, m.provenance);
+        }
         const kept = includeSuperseded
             ? result.results
             : result.results.filter((r) => !isSupersededKey(String(r.key ?? ''), live, hasMeta));
@@ -730,6 +826,10 @@ export async function searchKnowledge(query, opts) {
             // content, and goes empty when a re-ingested file's hash changed.
             const srcTag = (r.tags ?? []).find((tag) => tag.startsWith('src:'));
             const superseded = includeSuperseded && isSupersededKey(String(r.key ?? ''), live, hasMeta);
+            // RCL-10: offsets ride on the chunk's own `span:` tag, so citing a hit
+            // costs nothing here. Chunks stored before span tags simply have none,
+            // and `doc cite --chunk` recomputes them from the document.
+            const span = parseSpanTag(r.tags);
             return {
                 id: r.id,
                 filePath: srcTag ? srcTag.slice(4) : (hashToFile.get(hash) ?? ''),
@@ -743,6 +843,17 @@ export async function searchKnowledge(query, opts) {
                 chunkIndex: Number.isNaN(idx) ? 0 : idx,
                 scope: t.label,
                 ...(superseded ? { superseded: true } : {}),
+                // RCL-07: only LIVE versions carry provenance here — a superseded
+                // chunk's record is no longer in the live metadata. Its `url:` tag
+                // still identifies the page it came from.
+                ...(hashToProvenance.has(hash) ? { provenance: hashToProvenance.get(hash) } : {}),
+                ...(span
+                    ? {
+                        startChar: span.startChar,
+                        endChar: span.endChar,
+                        anchor: citationAnchor(hash, span.startChar, span.endChar),
+                    }
+                    : {}),
             };
         });
     }));
@@ -756,6 +867,79 @@ export function listDocuments(rootDir = getProjectRoot(), scope) {
     const all = readMetadata(rootDir);
     return scope ? all.filter((m) => m.scope === scope) : all;
 }
+/**
+ * Every recorded version of one document, oldest first (RCL-06).
+ *
+ * `target` is either an indexed file path or a capture's `canonicalUrl`. Read
+ * from the append-only log rather than the last-wins view, which is how a
+ * superseded version stays addressable after its record has been replaced or
+ * tombstoned.
+ *
+ * Best-effort by design: `readMetadata` compacts the log once it passes 1MB
+ * and keeps only live records, so history older than a compaction is gone.
+ * The `supersedes` pointer on each record is the durable part.
+ */
+export function listDocumentVersions(rootDir = getProjectRoot(), target, scope) {
+    const resolved = target ? path.resolve(target) : undefined;
+    return readMetadataLog(rootDir)
+        .filter((m) => m.chunkCount >= 0)
+        .filter((m) => !scope || m.scope === scope)
+        .filter((m) => !target || m.filePath === resolved || m.filePath === target || m.canonicalUrl === target)
+        .sort((a, b) => (a.version ?? 0) - (b.version ?? 0) || a.indexedAt.localeCompare(b.indexedAt));
+}
+// ── Citation / lookup helpers (RCL-10) ─────────────────────────────
+/** The store root for a scope: the global brain for `global`, else the project. */
+export function getKnowledgeRoot(scope = 'shared', rootDir = getProjectRoot()) {
+    return effectiveRoot(scope, rootDir);
+}
+/** Chunk spans for a text, using the SAME chunker the ingest used — this is
+ *  what makes a chunk index resolvable back to a character range without
+ *  storing the text twice. */
+export async function chunkSpans(text) {
+    const chunks = await chunkDocument('cite', text);
+    return chunks.map((c) => ({
+        chunkIndex: c.chunkIndex,
+        startChar: c.startChar,
+        endChar: c.endChar,
+    }));
+}
+/**
+ * The indexed record for whatever a caller wrote down: a file path, a
+ * capture's `canonicalUrl` (fragment ignored), or the `<scope>:<path>` docId.
+ *
+ * Live records win. A superseded version is only reached through the
+ * append-only log, and only when nothing live matches — otherwise citing a
+ * re-captured page would resolve against the version it replaced.
+ */
+export function findDocumentRecord(rootDir = getProjectRoot(), target = '', scope) {
+    const raw = target.trim();
+    if (!raw)
+        return undefined;
+    // `<scope>:<path>` — but not `https://…`, whose colon is a URL scheme.
+    const scoped = /^([a-z][a-z0-9_-]*):(?!\/\/)(.+)$/i.exec(raw);
+    const candidates = scoped ? [raw, scoped[2]] : [raw];
+    const hash = raw.indexOf('#');
+    if (hash > 0)
+        candidates.push(raw.slice(0, hash));
+    const resolvedPaths = new Set(candidates.map((c) => path.resolve(c)));
+    const wanted = new Set(candidates);
+    const scopeFilter = scope ?? (scoped ? scoped[1] : undefined);
+    const matches = (m) => {
+        if (scopeFilter && m.scope !== scopeFilter && !wanted.has(m.filePath))
+            return false;
+        if (wanted.has(m.filePath) || resolvedPaths.has(path.resolve(m.filePath)))
+            return true;
+        return !!m.canonicalUrl && wanted.has(m.canonicalUrl);
+    };
+    const live = readMetadata(rootDir).filter(matches);
+    if (live.length) {
+        return live.sort((a, b) => (b.version ?? 0) - (a.version ?? 0))[0];
+    }
+    const historical = readMetadataLog(rootDir)
+        .filter((m) => m.chunkCount >= 0)
+        .filter(matches);
+    return historical.sort((a, b) => (b.version ?? 0) - (a.version ?? 0))[0];
+}
 export async function removeDocument(filePath, scope = 'shared', rootDir = getProjectRoot()) {
     removeMetadataEntry(rootDir, path.resolve(filePath), scope);
     // SQLite cleanup: bridge doesn't expose delete-by-key, so metadata removal is sufficient.