@hraness/wordcell 0.22.3 → 0.22.5

package/dist/{support-vm8fw4yc.js → support-jf9v10j7.js}

@@ -2,12 +2,12 @@
 import {
   parseArguments as parseArguments2,
   parseUrlMetadataArguments
-} from "./index-yx6p1vzc.js";
+} from "./index-8bgnhjgq.js";
 import"./index-bcknqxrq.js";
 import {
   parsePdfArguments
 } from "./index-054mb7d3.js";
-import"./index-bqtqeak3.js";
+import"./index-h2qn3y3f.js";
 import"./index-j4zgmzjr.js";
 import"./index-de2w8crk.js";
 import"./index-6jcz0m1c.js";
@@ -28,34 +28,34 @@ import"./index-mxxxytys.js";
 import"./index-23z4zxgg.js";
 import"./index-pj501bh1.js";
 import"./index-9rf81m0p.js";
-import"./index-1k595z6v.js";
-import"./index-q7tbg07z.js";
+import"./index-1r5rnkfr.js";
+import"./index-42tb8qqp.js";
 import"./index-adx6khj5.js";
-import"./index-rr9kzq4n.js";
+import"./index-n57tewfr.js";
 import"./index-4j3tt0c3.js";
 import"./index-j70m75wd.js";
 import"./index-b88v3vtm.js";
-import"./index-djrcc1yf.js";
-import"./index-jk1sgx36.js";
-import"./index-xv80vzfp.js";
-import"./index-tf4wzjew.js";
+import"./index-gtwqye5a.js";
+import"./index-qdb8f8va.js";
+import"./index-f75zmmdr.js";
+import"./index-pz2b2x0y.js";
 import"./index-1gwbassd.js";
-import"./index-vnybgywh.js";
+import"./index-aer0jdrq.js";
 import"./index-1xxnjn0d.js";
-import"./index-a3j61wz9.js";
-import"./index-233z9wmn.js";
+import"./index-xzvcw9ga.js";
+import"./index-8v6k9h4r.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-4knsp9qj.js";
 import"./index-66pshdtx.js";
-import"./index-3agn8scn.js";
+import"./index-23m6bbjt.js";
 import"./index-hya40gb2.js";
 import"./index-5vwpzb5a.js";
 import"./index-x3fthpsc.js";
-import"./index-ecqpgr5y.js";
+import"./index-f7fnww7a.js";
 import"./index-3rm7cz6h.js";
-import"./index-qbssx940.js";
+import"./index-zy7an84p.js";
 import"./index-z1w83f81.js";
 
 // src/support.ts

package/dist/workflows/decision-context.js

@@ -1,27 +1,27 @@
 // @bun
 import {
   decisionContextWorkflow
-} from "../index-76dbn6pe.js";
+} from "../index-n9kwenpt.js";
 import"../index-h170byqw.js";
-import"../index-q7tbg07z.js";
+import"../index-42tb8qqp.js";
 import"../index-adx6khj5.js";
-import"../index-rr9kzq4n.js";
+import"../index-n57tewfr.js";
 import"../index-4j3tt0c3.js";
 import"../index-j70m75wd.js";
-import"../index-djrcc1yf.js";
-import"../index-jk1sgx36.js";
-import"../index-xv80vzfp.js";
-import"../index-tf4wzjew.js";
+import"../index-gtwqye5a.js";
+import"../index-qdb8f8va.js";
+import"../index-f75zmmdr.js";
+import"../index-pz2b2x0y.js";
 import"../index-1gwbassd.js";
-import"../index-vnybgywh.js";
+import"../index-aer0jdrq.js";
 import"../index-1xxnjn0d.js";
-import"../index-233z9wmn.js";
+import"../index-8v6k9h4r.js";
 import"../index-d13v9ckt.js";
 import"../index-48pz4jpc.js";
 import"../index-06c9ctr6.js";
 import"../index-5vwpzb5a.js";
 import"../index-3rm7cz6h.js";
-import"../index-qbssx940.js";
+import"../index-zy7an84p.js";
 import"../index-z1w83f81.js";
 export {
   decisionContextWorkflow

package/dist/workflows/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   decisionContextWorkflow
-} from "../index-76dbn6pe.js";
+} from "../index-n9kwenpt.js";
 import {
   explainChangeWorkflow
 } from "../index-e4fagfjz.js";
@@ -9,25 +9,25 @@ import {
   planRadarWorkflow
 } from "../index-rdd5f7jj.js";
 import"../index-h170byqw.js";
-import"../index-q7tbg07z.js";
+import"../index-42tb8qqp.js";
 import"../index-adx6khj5.js";
-import"../index-rr9kzq4n.js";
+import"../index-n57tewfr.js";
 import"../index-4j3tt0c3.js";
 import"../index-j70m75wd.js";
-import"../index-djrcc1yf.js";
-import"../index-jk1sgx36.js";
-import"../index-xv80vzfp.js";
-import"../index-tf4wzjew.js";
+import"../index-gtwqye5a.js";
+import"../index-qdb8f8va.js";
+import"../index-f75zmmdr.js";
+import"../index-pz2b2x0y.js";
 import"../index-1gwbassd.js";
-import"../index-vnybgywh.js";
+import"../index-aer0jdrq.js";
 import"../index-1xxnjn0d.js";
-import"../index-233z9wmn.js";
+import"../index-8v6k9h4r.js";
 import"../index-d13v9ckt.js";
 import"../index-48pz4jpc.js";
 import"../index-06c9ctr6.js";
 import"../index-5vwpzb5a.js";
 import"../index-3rm7cz6h.js";
-import"../index-qbssx940.js";
+import"../index-zy7an84p.js";
 import"../index-z1w83f81.js";
 export {
   planRadarWorkflow,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.22.3",
-  "description": "A local Markdown knowledge base with superpowers. Save decisions, sources, and plans as files you own, then recover them through exact and semantic search, typed relationships, backlinks, and Git history.",
+  "version": "0.22.5",
+  "description": "A local Markdown knowledge base with superpowers. Save decisions, sources, and plans as files you own, then find them by exact words or, with an optional local model, by meaning.",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -381,6 +381,7 @@
     "src/evaluation-v2.ts",
     "src/evaluation.ts",
     "src/graph.ts",
+    "src/mention-index.ts",
     "src/index.ts",
     "src/init.ts",
     "src/navigation.ts",
@@ -479,8 +480,8 @@
     "check": "bun run check:worker && bun run check:effect && bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
     "prepack": "bun run check",
     "check:effect": "bun run scripts/check-effect-policy.ts",
-    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.2/hraness-wordcell-0.22.2.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
-    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.2/hraness-wordcell-0.22.2.tgz wordcell search --root kb --mode exact",
+    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
+    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz wordcell search --root kb --mode exact",
     "check:worker": "tsc -p worker/tsconfig.json --noEmit"
   },
   "dependencies": {

package/skills/wordcell/SKILL.md

@@ -56,7 +56,7 @@ missing:
 ```sh
 command -v wordcell >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz
 }
 wordcell --help
 ```

package/skills/wordcell/references/plan-structure.md

@@ -80,7 +80,7 @@ Add these when execution starts:
 ```md
 ## Execution evidence
 
-- YYYY-MM-DD — Result, command or artifact, and what it proved.
+- YYYY-MM-DD: result, command or artifact, and what it proved.
 
 ## Review findings
 

package/skills/wordcell/references/url-platforms.md

@@ -2,7 +2,7 @@
 
 Use the strongest available read route, then describe exactly what it retained. Every route is bounded by item count, tree depth, time, HTML bytes, per-asset bytes, and aggregate asset bytes.
 
-| Surface | Preferred route | Conversation behavior | Honest limit |
+| Surface | Preferred route | Conversation behavior | Limit |
 | --- | --- | --- | --- |
 | Generic articles and papers | Structured data or HTTP + Defuddle; rendered browser fallback | Captures the page body and any comments present in that representation | JavaScript-only or unusual layouts can remain partial |
 | X | Defuddle X extraction plus rendered text; public profile metadata as a separate reviewed surface; current tab or profile for signed-in views | Preserves the complete visible root post or long-form article, quote context, visible metrics, localized post media, and loaded replies while keeping author, continuation, and reply boundaries distinct | Virtualized or unloaded replies and missing trustworthy item trees remain partial; profile bios and links are never inferred from post prose |

package/src/cli-program.ts

@@ -162,7 +162,9 @@ import { MAX_RERANK_CANDIDATES, type SearchReranker } from "./rerank.js";
 import { createCliTypeSafeReranker } from "./rerank-credentials.js";
 import {
   refreshVault,
+  refreshVaultComplete,
   scanVault,
+  scanVaultComplete,
   type ScanVaultOptions,
   type VaultSnapshot,
 } from "./vault.js";
@@ -3871,8 +3873,8 @@ async function runVault(
   dependencies: CliDependencies,
 ): Promise<number> {
   const snapshot = command.kind === "refresh"
-    ? await (dependencies.refreshVault ?? refreshVault)(command.root, command.options)
-    : await (dependencies.scanVault ?? scanVault)(command.root, command.options);
+    ? await (dependencies.refreshVault ?? refreshVaultComplete)(command.root, command.options)
+    : await (dependencies.scanVault ?? (command.kind === "check" ? scanVaultComplete : scanVault))(command.root, command.options);
 
   if (command.kind === "refresh" || command.kind === "check") {
     const noCatalog = command.kind === "check" && command.noCatalog === true;

package/src/graph.ts

@@ -9,6 +9,8 @@ import {
   type Node,
 } from "yaml";
 import { parseQualifiedDocumentUri, type QualifiedDocumentUri } from "./portfolio-identity.js";
+import { cleanMentionBoundary, MentionIndexBudgetError, MentionMatcher, preflightMentionInput, type MentionIndexBudgetKind, type MentionIndexLimits } from "./mention-index.js";
+export type { MentionIndexLimits } from "./mention-index.js";
 
 export const catalogStart = "<!-- kb:catalog:start -->";
 export const catalogEnd = "<!-- kb:catalog:end -->";
@@ -22,7 +24,8 @@ export type VaultAnalysisBudgetKind =
   | "notes"
   | "connection-observations"
   | "mention-pairs"
-  | "mentions";
+  | "mentions"
+  | MentionIndexBudgetKind;
 
 /** A stable failure for callers that need to distinguish bounded graph work. */
 export class VaultAnalysisBudgetError extends RangeError {
@@ -214,6 +217,11 @@ export type AnalyzeVaultOptions = {
   catalogNoteId?: string;
 };
 
+/** Complete discovery indexes phrases instead of enumerating every note pair. */
+export type CompleteAnalyzeVaultOptions = AnalyzeVaultOptions & {
+  readonly mentionIndexLimits?: MentionIndexLimits;
+};
+
 export type VaultAnalysis = {
   noteCount: number;
   contextualLinks: readonly ResolvedLink[];
@@ -1015,17 +1023,10 @@ function compareRelationIssues(left: RelationIssue, right: RelationIssue): numbe
     || targetComparison;
 }
 
-const wordCharacter = (value: string): boolean => /[A-Za-z0-9]/.test(value);
-
 function phraseOffset(lowerHaystack: string, lowerPhrase: string): number {
   let offset = lowerHaystack.indexOf(lowerPhrase);
   while (offset !== -1) {
-    const before = offset === 0 ? "" : lowerHaystack[offset - 1] ?? "";
-    const afterIndex = offset + lowerPhrase.length;
-    const after = afterIndex >= lowerHaystack.length ? "" : lowerHaystack[afterIndex] ?? "";
-    const startsClean = !wordCharacter(lowerPhrase[0] ?? "") || !wordCharacter(before);
-    const endsClean = !wordCharacter(lowerPhrase.at(-1) ?? "") || !wordCharacter(after);
-    if (startsClean && endsClean) return offset;
+    if (cleanMentionBoundary(lowerHaystack, lowerPhrase, offset)) return offset;
     offset = lowerHaystack.indexOf(lowerPhrase, offset + 1);
   }
   return -1;
@@ -1093,6 +1094,33 @@ function checkedAnalysisLimit(
 export function analyzeVault(
   notes: readonly Note[],
   options: AnalyzeVaultOptions = {},
+): VaultAnalysis {
+  return analyzeVaultInternal(notes, options);
+}
+
+/**
+ * Return the same complete graph using a finite phrase index. maxMentionPairs
+ * counts matching source/target candidates; index work and repeated matches
+ * have separate aggregate limits. Exhaustion always throws, never truncates.
+ */
+export function analyzeVaultComplete(
+  notes: readonly Note[],
+  options: CompleteAnalyzeVaultOptions = {},
+): VaultAnalysis {
+  try {
+    return analyzeVaultInternal(notes, options, options.mentionIndexLimits ?? {});
+  } catch (error: unknown) {
+    if (error instanceof MentionIndexBudgetError) {
+      throw new VaultAnalysisBudgetError(error.kind, error.limit, error.message);
+    }
+    throw error;
+  }
+}
+
+function analyzeVaultInternal(
+  notes: readonly Note[],
+  options: AnalyzeVaultOptions,
+  mentionIndexLimits?: MentionIndexLimits,
 ): VaultAnalysis {
   const maxNotes = checkedAnalysisLimit(
     options.maxNotes,
@@ -1121,6 +1149,13 @@ export function analyzeVault(
       `Vault analysis exceeds the ${maxNotes} note limit.`,
     );
   }
+  const mentionInput = mentionIndexLimits === undefined ? undefined : preflightMentionInput((function* () {
+    for (const note of notes) {
+      yield note.searchableText;
+      yield note.title;
+      yield* note.aliases;
+    }
+  })(), mentionIndexLimits);
   const catalogNoteId = withoutMarkdownExtension(
     normalizeVaultPath(options.catalogNoteId ?? "index"),
   );
@@ -1332,7 +1367,42 @@ export function analyzeVault(
     : uniquePhrasesByTarget(suggestionNotes);
   const mentions: MentionCandidate[] = [];
   let mentionPairs = 0;
+  const matcher = mentionIndexLimits === undefined ? undefined : new MentionMatcher(
+    [...phrasesByTarget].flatMap(([targetId, phrases]) => phrases.map((phrase, rank) => ({ ...phrase, targetId, rank }))),
+    mentionIndexLimits,
+    mentionInput!.rawInputCodeUnits,
+    mentionInput!.work,
+  );
+  const targetsById = new Map<string, { readonly note: Note; readonly order: number }[]>();
+  if (matcher !== undefined) suggestionNotes.forEach((note, order) => {
+    const targets = targetsById.get(note.id) ?? [];
+    targets.push({ note, order });
+    targetsById.set(note.id, targets);
+  });
   for (const source of suggestionNotes) {
+    if (matcher !== undefined) {
+      if (scopedMentionNotes.length === 0) continue;
+      const found = matcher.scan(source.searchableText.toLocaleLowerCase("en-US"));
+      const targets = [...found].flatMap(([id, match]) => (targetsById.get(id) ?? []).map((target) => ({ ...target, match })))
+        .filter(({ note }) => source.id !== note.id && (options.mentionScope === undefined
+          || scopedMentionIds.has(source.id) || scopedMentionIds.has(note.id)))
+        .sort((left, right) => left.order - right.order);
+      let newlineOffsets: readonly number[] | undefined;
+      for (const { note: target, match } of targets) {
+        if (mentionPairs >= maxMentionPairs) throw new VaultAnalysisBudgetError(
+          "mention-pairs", maxMentionPairs, `Vault analysis exceeds the ${maxMentionPairs} mention-pair limit.`,
+        );
+        mentionPairs += 1;
+        if (linkedPairs.has(pairKey(source.id, target.id))) continue;
+        if (mentions.length >= maxMentions) throw new VaultAnalysisBudgetError(
+          "mentions", maxMentions, `Vault analysis exceeds the ${maxMentions} mention limit.`,
+        );
+        newlineOffsets ??= matcher.newlineOffsets(source.searchableText);
+        mentions.push({ source: source.path, target: target.path, phrase: match.pattern.phrase,
+          line: matcher.lineAt(newlineOffsets, match.offset) });
+      }
+      continue;
+    }
     const targets = options.mentionScope === undefined
       || scopedMentionIds.has(source.id)
       ? suggestionNotes

package/src/mention-index.ts

@@ -0,0 +1,194 @@
+/** Finite UTF-16 multi-pattern matching for complete vault analysis. */
+export type MentionIndexLimits = {
+  readonly maxNodes?: number;
+  readonly maxWork?: number;
+  readonly maxMatches?: number;
+  readonly maxInputCodeUnits?: number;
+};
+
+export const MENTION_INDEX_LIMITS = {
+  maxNodes: 262_144,
+  maxWork: 64 * 1_024 * 1_024,
+  maxMatches: 1_000_000,
+  maxInputCodeUnits: 256 * 1_024 * 1_024,
+} as const;
+
+export type MentionIndexBudgetKind =
+  | "mention-index-nodes"
+  | "mention-index-work"
+  | "mention-matches"
+  | "mention-input-code-units";
+
+export class MentionIndexBudgetError extends RangeError {
+  readonly kind: MentionIndexBudgetKind;
+  readonly limit: number;
+
+  constructor(kind: MentionIndexBudgetKind, limit: number) {
+    super(`Vault analysis exceeds the ${limit} ${kind} limit.`);
+    this.kind = kind;
+    this.limit = limit;
+  }
+}
+
+function checkedLimits(options: MentionIndexLimits): Record<keyof MentionIndexLimits, number> {
+  const limits: Record<keyof MentionIndexLimits, number> = { ...MENTION_INDEX_LIMITS };
+  for (const name of Object.keys(MENTION_INDEX_LIMITS) as (keyof MentionIndexLimits)[]) {
+    const value = options[name] ?? MENTION_INDEX_LIMITS[name];
+    if (!Number.isSafeInteger(value) || value < 0 || value > MENTION_INDEX_LIMITS[name]) {
+      throw new RangeError(`${name} must be a safe integer from 0 through ${MENTION_INDEX_LIMITS[name]}.`);
+    }
+    limits[name] = value;
+  }
+  return limits;
+}
+
+/** Admit original strings before trimming, normalizing, or indexing any phrase. */
+export function preflightMentionInput(inputs: Iterable<string>, options: MentionIndexLimits): { rawInputCodeUnits: number; work: number } {
+  const limits = checkedLimits(options);
+  let rawInputCodeUnits = 0, work = 0;
+  for (const input of inputs) {
+    rawInputCodeUnits += input.length;
+    if (rawInputCodeUnits > limits.maxInputCodeUnits) throw new MentionIndexBudgetError("mention-input-code-units", limits.maxInputCodeUnits);
+    work += input.length + 1;
+    if (work > limits.maxWork) throw new MentionIndexBudgetError("mention-index-work", limits.maxWork);
+  }
+  return { rawInputCodeUnits, work };
+}
+
+export type MentionPattern = {
+  readonly targetId: string;
+  readonly phrase: string;
+  readonly lowerPhrase: string;
+  readonly rank: number;
+};
+export type IndexedMention = { readonly pattern: MentionPattern; readonly offset: number };
+type TrieNode = {
+  readonly next: Map<number, number>;
+  failure: number;
+  output: number;
+  pattern: MentionPattern | undefined;
+};
+
+/** The legacy matcher uses ASCII word boundaries, even for Unicode phrases. */
+export function cleanMentionBoundary(text: string, phrase: string, offset: number): boolean {
+  const word = (value: string): boolean => /[A-Za-z0-9]/.test(value);
+  return (!word(phrase[0] ?? "") || !word(text[offset - 1] ?? ""))
+    && (!word(phrase.at(-1) ?? "") || !word(text[offset + phrase.length] ?? ""));
+}
+
+export class MentionMatcher {
+  private readonly limits: Record<keyof MentionIndexLimits, number>;
+  private readonly nodes: TrieNode[] = [];
+  private work = 0;
+  private matches = 0;
+  private input = 0;
+
+  constructor(patterns: readonly MentionPattern[], options: MentionIndexLimits = {}, rawInputCodeUnits = 0, preflightWork = 0) {
+    this.limits = checkedLimits(options);
+    if (!Number.isSafeInteger(preflightWork) || preflightWork < 0) throw new RangeError("Invalid mention preflight work.");
+    if (preflightWork > this.limits.maxWork) this.fail("mention-index-work", this.limits.maxWork);
+    this.work = preflightWork;
+    if (!Number.isSafeInteger(rawInputCodeUnits) || rawInputCodeUnits < 0) throw new RangeError("Invalid mention input length.");
+    if (rawInputCodeUnits > this.limits.maxInputCodeUnits) this.fail("mention-input-code-units", this.limits.maxInputCodeUnits);
+    this.node();
+    for (const pattern of patterns) {
+      this.inputUnits(pattern.lowerPhrase.length);
+      let state = 0;
+      for (let index = 0; index < pattern.lowerPhrase.length; index += 1) {
+        this.step();
+        const character = pattern.lowerPhrase.charCodeAt(index);
+        let next = this.nodes[state]!.next.get(character);
+        if (next === undefined) {
+          next = this.node();
+          this.nodes[state]!.next.set(character, next);
+        }
+        state = next;
+      }
+      if (pattern.lowerPhrase.length === 0 || this.nodes[state]!.pattern !== undefined) {
+        throw new TypeError("Mention index requires nonempty, uniquely owned normalized phrases.");
+      }
+      this.nodes[state]!.pattern = pattern;
+    }
+    const queue = [...this.nodes[0]!.next.values()];
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+      const state = queue[cursor]!;
+      for (const [character, child] of this.nodes[state]!.next) {
+        this.step();
+        let fallback = this.nodes[state]!.failure;
+        while (fallback !== 0 && !this.nodes[fallback]!.next.has(character)) {
+          this.step();
+          fallback = this.nodes[fallback]!.failure;
+        }
+        const failure = this.nodes[fallback]!.next.get(character) ?? 0;
+        this.nodes[child]!.failure = failure;
+        this.nodes[child]!.output = this.nodes[failure]!.pattern === undefined
+          ? this.nodes[failure]!.output : failure;
+        queue.push(child);
+      }
+    }
+  }
+
+  private fail(kind: MentionIndexBudgetKind, limit: number): never { throw new MentionIndexBudgetError(kind, limit); }
+  private step(): void {
+    if (this.work >= this.limits.maxWork) this.fail("mention-index-work", this.limits.maxWork);
+    this.work += 1;
+  }
+  private node(): number {
+    if (this.nodes.length >= this.limits.maxNodes) this.fail("mention-index-nodes", this.limits.maxNodes);
+    this.nodes.push({ next: new Map(), failure: 0, output: -1, pattern: undefined });
+    return this.nodes.length - 1;
+  }
+  private inputUnits(count: number): void {
+    this.input += count;
+    if (this.input > this.limits.maxInputCodeUnits) this.fail("mention-input-code-units", this.limits.maxInputCodeUnits);
+  }
+
+  newlineOffsets(originalText: string): readonly number[] {
+    const offsets: number[] = [];
+    for (let index = 0; index < originalText.length; index += 1) {
+      this.step();
+      if (originalText.charCodeAt(index) === 10) offsets.push(index);
+    }
+    return offsets;
+  }
+
+  lineAt(offsets: readonly number[], offset: number): number {
+    let low = 0, high = offsets.length;
+    while (low < high) {
+      this.step();
+      const middle = low + Math.floor((high - low) / 2);
+      if (offsets[middle]! < offset) low = middle + 1;
+      else high = middle;
+    }
+    return low + 1;
+  }
+
+  scan(lowerText: string): ReadonlyMap<string, IndexedMention> {
+    this.inputUnits(lowerText.length);
+    const result = new Map<string, IndexedMention>();
+    let state = 0;
+    for (let index = 0; index < lowerText.length; index += 1) {
+      this.step();
+      const character = lowerText.charCodeAt(index);
+      while (state !== 0 && !this.nodes[state]!.next.has(character)) {
+        this.step();
+        state = this.nodes[state]!.failure;
+      }
+      state = this.nodes[state]!.next.get(character) ?? 0;
+      let output = this.nodes[state]!.pattern === undefined ? this.nodes[state]!.output : state;
+      while (output !== -1) {
+        if (this.matches >= this.limits.maxMatches) this.fail("mention-matches", this.limits.maxMatches);
+        this.matches += 1; // Count overlapping/repeated outputs before deduplication or boundary filtering.
+        const pattern = this.nodes[output]!.pattern!;
+        const offset = index + 1 - pattern.lowerPhrase.length;
+        const existing = result.get(pattern.targetId);
+        if (cleanMentionBoundary(lowerText, pattern.lowerPhrase, offset)
+          && (existing === undefined || pattern.rank < existing.pattern.rank)) {
+          result.set(pattern.targetId, { pattern, offset });
+        }
+        output = this.nodes[output]!.output;
+      }
+    }
+    return result;
+  }
+}

package/src/publish-index.ts

@@ -1,6 +1,7 @@
 import { canonicalJson } from "@hraness/oh";
 
 import type { Note } from "./graph.js";
+import { projectMarkdownText } from "./publish-markdown.js";
 import {
   WORDCELL_SITE_DOCS_FORMAT_V1,
   WORDCELL_SITE_LIMITS_V1,
@@ -38,8 +39,8 @@ function bounded(value: string, maximumBytes: number): { text: string; truncated
 }
 
 function previewText(note: Note): string {
-  const basis = note.summary !== "" ? note.summary : note.searchableText;
-  const collapsed = basis.replace(/\s+/gu, " ").trim();
+  const display = projectMarkdownText(note.content, note.properties["description"]);
+  const collapsed = display.preview.replace(/\s+/gu, " ").trim();
   return bounded(collapsed, WORDCELL_SITE_LIMITS_V1.docPreviewBytes).text;
 }
 

package/src/publish-markdown.ts

@@ -108,6 +108,8 @@ type Footnotes = {
   definitions: number;
   references: number;
   disabled: boolean;
+  /** Plain display projections omit admitted citation navigation only. */
+  readonly plain?: true;
 };
 
 function footnoteLabel(raw: string): string | undefined {
@@ -136,6 +138,7 @@ function renderFootnoteReference(raw: string, label: string, footnotes: Footnote
   const id = `wordcell:footnote-ref:${number}:${note.references.length + 1}`;
   note.references.push(id);
   footnotes.references += 1;
+  if (footnotes.plain) return "";
   return `<sup><a id="${id}" href="#wordcell:footnote:${number}" role="doc-noteref" aria-label="Footnote ${number}">${number}</a></sup>`;
 }
 
@@ -820,6 +823,58 @@ export function renderMarkdownToHtml(content: string, ctx: PublishRenderContext)
   return `${body}${body === "" ? "" : "\n"}<section class="footnotes" aria-label="Footnotes"><ol>\n${notes}\n</ol></section>`;
 }
 
+export type PublishMarkdownText = {
+  readonly text: string;
+  readonly preview: string;
+};
+
+/**
+ * Readable display text, derived before truncation or case normalization.
+ * Shares the article grammar and footnote admission rules; it is not an index
+ * or a replacement for authored Markdown. Valid citation navigation disappears,
+ * while unresolved definitions/references, escaped text, and code stay literal.
+ */
+export function projectMarkdownText(content: string, description?: string): PublishMarkdownText {
+  const footnotes: Footnotes = { byLabel: new Map(), numbered: [], definitions: 0, references: 0, disabled: false, plain: true };
+  const blocks = parseMarkdownBlocks(content, footnotes, true);
+  // Display labels need no filesystem, URL fetch, or selected-note resolution.
+  // Unresolved local assets retain their authored alt text through renderInline.
+  const context: PublishRenderContext = {
+    source: "", resolveNote: () => undefined, resolveAsset: () => undefined, noteHref: () => "",
+  };
+  const inline = (text: string, state?: Footnotes): string => stripMarkup(renderInline(text, context, state));
+  const parts = (items: readonly MarkdownBlock[], state: Footnotes): string[] => items.map((block): string => {
+    switch (block.type) {
+      case "paragraph": case "heading": return inline(block.text, state);
+      case "literal": case "code": return block.text;
+      case "break": return "";
+      case "quote": return parts(block.blocks, state).join("\n\n");
+      case "table": return [block.header, ...block.rows].map((row) => row.map((cell) => inline(cell, state)).join(" ")).join("\n");
+      case "list": return block.parts.map((part) => part.type === "item" || part.type === "continuation" ? inline(part.text, state) : "").filter(Boolean).join("\n");
+      case "footnote": return state.disabled || block.note.invalid ? block.note.authored : "";
+    }
+  });
+  const rendered = parts(blocks, footnotes);
+  // The article orders valid definitions by first reference, then unreferenced
+  // definitions. Nested references in their bodies deliberately remain literal.
+  if (!footnotes.disabled) for (const note of footnotes.byLabel.values()) {
+    if (note !== null && !note.invalid) footnoteNumber(note, footnotes);
+  }
+  const text = [...rendered, ...footnotes.numbered.map((note) => inline(note.body.replaceAll("\n", " ")))].filter(Boolean).join("\n\n");
+  let preview = rendered.find((value, index) => blocks[index]?.type === "paragraph" && value.trim() !== "") ?? text;
+  if (description !== undefined && description.trim() !== "") {
+    // Resolve description citations against the same authored definitions, but
+    // never let preview rendering consume the article's citation allowance.
+    const state: Footnotes = {
+      byLabel: new Map([...footnotes.byLabel].map(([label, note]) => [label, note === null ? null : { body: note.body, authored: note.authored, invalid: note.invalid, references: [] }])),
+      numbered: [], definitions: footnotes.definitions, references: 0, disabled: footnotes.disabled, plain: true,
+    };
+    const authored = parts(parseMarkdownBlocks(description, state, false), state).filter(Boolean).join("\n\n");
+    if (authored.trim() !== "") preview = authored;
+  }
+  return { text, preview };
+}
+
 export function stripMarkup(html: string): string {
   // Scan literal tags first — escaped angle brackets (&lt;) decode to text,
   // never tag boundaries. The character scanner (not a regex) keeps CodeQL's