klypix-mcp 1.94.0 → 1.96.0

package/FORMAT.md

@@ -170,6 +170,26 @@ writing, so two copies of an identical card differ in it. Any comparison that de
 learned this the hard way: a byte-compare spawned conflict twins for cards nobody
 touched. `mergeBrains` exports `sameMeaning(a, b)` as the single correct comparison.
 
+**A saved reading is DERIVED — not content either.** KLYPIX keeps what it read from a
+card's file on the card: `derivedText`, with `derivedTextKind` (`document-text`,
+`audio-transcript`, `video-transcript`, `video-analysis`, `image-understanding`),
+`derivedTextSource` (`local` | `cloud`) and, depending on the kind, `derivedTextAt`,
+`derivedTextVisuals` and `derivedTextSha`. A reading is made again from the bytes whenever
+it is missing, so `sameMeaning` strips these fields too: two copies that differ only in
+their reading are one card (no conflict twin), and a reading made on one side never brings
+back a card the other side deleted. A merge still keeps readings. Of two such copies it
+writes the one with the better reading: a current one first, then one with visuals, then one
+made by cloud AI, then the longer text. When one side's edit wins, the other side's reading
+is carried onto it as long as it is still a reading of the card's bytes. Identities do not
+change: `itemSignature`, and with it bin-entry ids (`rid`), conflict-twin ids and revived ids,
+hashes the card with its reading, exactly as before.
+
+A document's reading (`derivedTextKind: "document-text"`, on a `file` card) carries
+`derivedTextSha`: the card's `assetSha`, else its `assetId`, when it was read. It is current
+only while that still names the card's bytes; a reader must not serve a reading of earlier
+bytes as what the file says. A credential file's reading (`.env`, `.pem`, `.key`, `.npmrc` …)
+is never served — KLYPIX does not keep one.
+
 ## Bytes: when they are embedded vs referenced
 
 **Embedded** — the bytes live inside the ZIP under `assets/`, and the item JSON

package/README.md

@@ -707,6 +707,12 @@ the KLYPIX app). Pass the ids `read_canvas` prints; every card with something in
 | Folder | Its file list. Add `entry_paths` (up to 8 file paths from the list) to get those files the same way. Paths that would leave the folder are refused; an entry over 64 MB, or one that inflates more than 200 times its stored size, is refused with its size. A folder kept on disk (not embedded) is read from where it is, never outside it. |
 | Audio, video | The reading KLYPIX saved, when there is one. Otherwise a local path and a plain statement that nothing in the answer says what it contains; a video's saved poster frame is attached and labelled as one frame. |
 
+A PDF, Office or text file that KLYPIX has already read also comes back with the text KLYPIX
+saved from it, first (`method: document_text`), and the file by path beside it. That text is
+used only while the card still holds the file it was read from: a reading of an earlier version
+of the file is never served, shown by `read_canvas` or matched by `search_canvases`, and the
+file itself is handed over as above.
+
 Limits, and why:
 
 - **One answer stays under 1 MB.** Claude Desktop refuses a whole tool result over 1 MB, so the images
@@ -1137,6 +1143,15 @@ independently validated.
   0.43, top-1 33%. The stratum that matters most is the honest one: **paraphrase questions that share
   no words with their card reach recall@5 44%**; status, temporal and multi-hop questions sit at
   81–93% because they still share vocabulary. Lexical-only scores 0% on the same set.
+- **The caller's words (`brain_ask`, 1.96).** A question can end with one more line,
+  `Also: <words a card answering it would likely use>`; the calling agent is itself a model, so it
+  can guess the card's wording at no extra cost. The words join the meaning query only. Measured
+  2026-10-11 on the same brain grown to 3,829 cards (102 of the frozen questions still answerable),
+  with words written by Gemini 2.5 Flash as a stand-in for the calling agent: recall@5 54% → 59%
+  (8 found, 3 lost), recall@8 61% → 68%, recall@20 68% → 76%, MRR 0.375 → 0.424. With no local
+  model (a fresh install, the Claude plugin) the words count as extra keywords at half weight:
+  recall@5 19% → 24% (5 found, none lost), recall@10 25% → 31%. Without the line, ranking is
+  unchanged byte for byte.
 - **Second brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
   paraphrases, first cross-brain run): recall@5 **42%** (CI 23–64), top-1 11%, MRR 0.25. Paraphrase
   recall transfers between brains; the ranker is not tuned to the brain it was built on. It is

package/bin/klypix-worker.mjs

@@ -508,7 +508,7 @@ server.registerTool('search_all_brains', {
 
 server.registerTool('brain_ask', {
   title: 'Ask the project brain a question (whole-brain, correction-aware answer)',
-  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card lexically, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh install is lexical; it degrades cleanly). INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Defaults to the project brain ("brain").',
+  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card lexically, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh install is lexical; it degrades cleanly). INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Cards are often worded differently from the question, so end the question with one more line, `Also: <8–14 words a card answering it would likely use: synonyms, feature, file or tool names>`; they widen the search while the question still leads (measured: right card in the top 5 for 60 of 102 test questions instead of 55; 24 instead of 19 when no local model is installed). Defaults to the project brain ("brain").',
   inputSchema: {
     question: z.string().describe('The natural-language question to answer from the brain.'),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.94.0",
+  "version": "1.96.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -86,7 +86,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",
@@ -96,7 +96,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "fractional-indexing": "^3.2.0",
     "jpeg-js": "^0.4.4",
     "jszip": "^3.10.1",

package/src/app-lease.mjs

@@ -181,7 +181,7 @@ export const TELL_USER = {
   // only, so a photo, a video or a file card needs a different human step.
   NOT_READ_IMAGE: 'Right-click the photo in KLYPIX and choose Extract text (OCR). After the canvas saves, ask me again.',
   NOT_READ_MEDIA: "Open the canvas in KLYPIX and ask KLYPIX's AI about that card; KLYPIX saves what it reads on the card. After the canvas saves, ask me again.",
-  NOT_READ_DOCUMENT: "KLYPIX does not save the text of a document card yet, so I can't read it from the saved canvas. Open it in KLYPIX if you need its text.",
+  NOT_READ_DOCUMENT: "Open the canvas in KLYPIX and ask KLYPIX's AI about that card; KLYPIX saves the text it reads from a document on the card. After the canvas saves, ask me again.",
 };
 
 export function tellUser(code, vars = {}) {

package/src/app-tools.mjs

@@ -30,8 +30,10 @@
 // runtime missing it degrades to file mode instead of losing these tools.
 //
 // P0 FILE MODE: both tools read what the KLYPIX app has already saved
-// into a canvas — transcripts on media cards (derivedText), Read contents result
-// cards, OCR cards, folder listings — and the lease file a running KLYPIX
+// into a canvas — transcripts on media cards (derivedText), a document's text
+// on its file card (derivedText, served only while its derivedTextSha names the
+// bytes the card holds), Read contents result cards, OCR cards, folder
+// listings — and the lease file a running KLYPIX
 // writes. Nothing here reads a page, a reel or a document itself: that is the
 // app's own value (its readers, keys, consents and credits), and from P1 an AI
 // tool reaches it through the app, never around it.
@@ -66,7 +68,7 @@ import {
 } from './app-lease.mjs';
 import { brainTarget, canvasTitleOf, resolveCanvasDetailed, walkVault } from './klypix-core.mjs';
 import {
-  classifyLinkTier, derivedReading, escapeInstructionLines, fenceContent, parseKlypix, readManifestCheap, recordedAuthor, savedReadingIndex, scopeLockedView,
+  classifyLinkTier, derivedReading, DOCUMENT_TEXT_KIND, escapeInstructionLines, fenceContent, parseKlypix, readManifestCheap, recordedAuthor, savedReadingIndex, scopeLockedView,
 } from './klypix-format.mjs';
 import {
   LIMITS, assetBytes, cacheBytes, dataUrlImage, decodeText, diskBytes, extOf, findZipEntry, fitImage, htmlPreviewToText,
@@ -407,6 +409,9 @@ function linkMethod(url, partial) {
   return { method: 'page_fetch', ranOn: 'this_pc' };
 }
 function derivedMethod(item, reading) {
+  // A document's text: derivedReading served it only because it is of the
+  // bytes the card holds now (savedDocumentText).
+  if (reading.kind === DOCUMENT_TEXT_KIND) return 'document_text';
   if (reading.kind === 'image-understanding') return 'image_understanding';
   if (reading.kind === 'video-transcript' || (item.type === 'video' && reading.visuals === false)) return 'audio_only_transcript';
   return 'media_transcript';
@@ -729,8 +734,11 @@ export async function readCardContents({ vault, canvas, card_ids, read_new, refr
     if (truncated) anyTruncated = true;
     const entry = { card_id: id, card_type: type, ...result, text: shown, truncated, file: fileInfo, ...(entries ? { entries } : {}), ...(frozenIds.has(id) ? { frozen: true } : {}) };
     if (cardSentence) { entry.code = notReadCode; entry.tell_user = cardSentence; sentences.push(cardSentence); }
-    // refresh: in file mode a fresh reading is the person's step in KLYPIX.
-    if (refresh === true && !['card_text', 'folder_listing', 'file_text', 'image', 'file_path', 'saved_preview'].includes(result.method)) {
+    // refresh: in file mode a fresh reading is the person's step in KLYPIX —
+    // but not for a document's text: it is served only while it is of the
+    // bytes the card holds, and a new read of those bytes gives the same
+    // words (the file itself goes by path beside it), so no step is sent.
+    if (refresh === true && !['card_text', 'folder_listing', 'file_text', 'image', 'file_path', 'saved_preview', 'document_text'].includes(result.method)) {
       const sentence = stepFor(item);
       if (sentence) { entry.tell_user = sentence; sentences.push(sentence); }
     }

package/src/klypix-core.mjs

@@ -30,7 +30,7 @@ import {
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
   selectGardenCandidates, applyGarden, detectContradictions,
   findDuplicatePartialNotes, collapseDuplicatePartialNotes,
-  rankForQuestion, questionContextToMarkdown, findLegacyShipCards,
+  rankForQuestion, splitAskWords, questionContextToMarkdown, findLegacyShipCards,
   challengeBrain, challengeContextToMarkdown, buildRenderSpec, structToBrief,
   brainLensData, lensToMarkdown, deathDateOfCard,
   statusContextToMarkdown, findFulfillmentCandidates, findStaleOpenCards, releaseFulfilledOpens, openStatusSummary, perAreaTableToMarkdown,
@@ -766,7 +766,9 @@ export async function opBrainTaskContext({
 }
 
 export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log = () => {} }) {
-  const q = String(question || '').trim();
+  // A last line `Also: <words>` is the caller's guess at the card's wording; it
+  // joins the meaning query only (splitAskWords in klypix-format.mjs).
+  const { question: q, words } = splitAskWords(question);
   if (!q) return err('brain_ask needs a question.');
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
@@ -783,9 +785,9 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   try {
     const pipe = await getEmbedderForUse(log, 20_000);
     if (pipe) {
-      const [qv] = await embedTexts(pipe, [q], { kind: 'query' });
+      const [qv] = await embedTexts(pipe, [words ? `${q}\n${words}` : q], { kind: 'query' });
       const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
-      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = 'semantic+lexical (on-device)'; }
+      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = `semantic+lexical (on-device)${words ? ' + your Also words' : ''}`; }
     }
   } catch { semantic = null; cardVecs = null; }
   // Parity with search_all_brains (8445e9c): never say "warming — retry" to a
@@ -799,6 +801,7 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   if (!semantic) {
     fallbackNotice = semanticFallbackNotice(false);
     if (fallbackNotice) mode = fallbackNotice.startsWith('LEXICAL ONLY') ? 'lexical-only (no semantic runtime)' : 'lexical (semantic warming)';
+    if (words) mode += ' + your Also words';
   }
   const kk = Math.max(1, Math.min(20, k || 10));
   const timeTravel = asOfTs != null;
@@ -811,7 +814,7 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   // vectors that rank the question, reused; null degrades pairing to its
   // lexical anchor/coverage fallback (works on every host, embeddings or not).
   const pairSim = cardVecs ? (a, b) => { const va = cardVecs.get(a), vb = cardVecs.get(b); return va && vb ? dot(va, vb) : null; } : null;
-  const result = rankForQuestion(struct, q, { semantic, k: wantRerank ? Math.max(kk, 50) : kk, as_of: timeTravel ? as_of : null, pairSim });
+  const result = rankForQuestion(struct, q, { semantic, k: wantRerank ? Math.max(kk, 50) : kk, as_of: timeTravel ? as_of : null, pairSim, words });
   if (wantRerank && result.hits.length > 1) {
     try {
       const reranked = await withRerankerForUse(log, 8_000, rr => rerankHits(rr, q, result.hits));

package/src/klypix-format.mjs

@@ -159,6 +159,27 @@ export const shard = (id) => id.replace(/^[a-z]+[_:]/i, '').toLowerCase().slice(
 // bearing: a real edit to any of them is still a real conflict.
 export const VOLATILE_ITEM_FIELDS = ['updatedAt', 'zIndex', 'editedAt'];
 
+// READING = a card's saved reading: the words KLYPIX's own readers took out of
+// the card's file — a document's text, a video's or a voice note's transcript
+// or analysis (the app's READING_FIELD_KEYS, items/documentReadingFields.ts).
+// Derived data, made again from the card's bytes whenever it is missing, so it
+// is no part of what a card MEANS (meaningSignature, sameMeaning):
+//   • two copies whose only difference is their reading are one card — no
+//     conflict twin, no content conflict;
+//   • a reading made on one side is not an edit, so it never brings back a
+//     card the other side deleted: the delete wins.
+// It IS part of a card's identity, exactly as in every engine up to 1.94:
+// itemSignature — and with it bin identities (fullEntryRid, receiptIdentity),
+// conflict-twin ids and revived ids — hashes the card with its reading, so a
+// receipt or a twin an older engine minted names the same bytes here. A check
+// of a copy against a stored identity also accepts the copy with a reading
+// KLYPIX made since (holdsEntryBytes).
+// A merge keeps a reading whenever it keeps the card: of two copies that mean
+// the same it writes the one with the better reading (pickReadingCopy), and
+// where one side's edit wins it carries the other side's reading onto it while
+// that reading is still of the bytes the card holds (carryReading).
+export const READING_ITEM_FIELDS = ['derivedText', 'derivedTextKind', 'derivedTextSource', 'derivedTextSha', 'derivedTextAt', 'derivedTextVisuals'];
+
 // Key-sorted JSON, so two writers' key orders can never fake a difference.
 const stableJson = (v) => JSON.stringify(v, (_k, val) =>
     (val && typeof val === 'object' && !Array.isArray(val))
@@ -184,28 +205,128 @@ export function pickThreeWay(o, t, b) {
  *  or any strings): true when the first wins. */
 export const canonicalFirst = (a, b) => a > b;
 
-/** A card's MEANING as a canonical string: parsed, volatile fields stripped,
- *  key-sorted. Unparseable JSON falls back to byte identity — a malformed item
- *  must never crash a merge. */
-export function itemSignature(json) {
+// ── Readings in a merge ──────────────────────────────────────────────────────
+// Which of two readings is the better one, best first: a reading with visuals
+// (a video analysis, or a transcript made with the frames), then one made by
+// cloud AI (it cost money; a local transcript can be made again for free), then
+// the longer text; two that tie on all three go by their key-sorted JSON. From
+// the two readings alone — never the base, never the side — so every machine
+// and both transports pick the same one, and a merge never trades a paid or a
+// richer reading for a poorer one.
+const readingRank = (f) => [
+    f.derivedTextKind === 'video-analysis' || f.derivedTextVisuals === true ? 1 : 0,
+    f.derivedTextSource === 'cloud' ? 1 : 0,
+    typeof f.derivedText === 'string' ? f.derivedText.length : 0,
+];
+/** True when reading fields `a` rank above the different reading fields `b`. */
+function readingBeats(a, b) {
+    const ra = readingRank(a), rb = readingRank(b);
+    for (let i = 0; i < ra.length; i++) if (ra[i] !== rb[i]) return ra[i] > rb[i];
+    return canonicalFirst(stableJson(a), stableJson(b));
+}
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const readingFieldsIn = (item) => {
+    const fields = {};
+    for (const f of READING_ITEM_FIELDS) if (item[f] !== undefined) fields[f] = item[f];
+    return fields;
+};
+// A card's reading fields, and whether that reading is current. Most cards have
+// none, so a JSON string that never names the field is not parsed.
+function readingFieldsOf(json) {
+    const none = { fields: {}, current: false };
+    if (typeof json !== 'string' || !json.includes('derivedText')) return none;
+    let item;
+    try { item = JSON.parse(json); } catch { return none; }
+    if (!isPlainObject(item)) return none;
+    return { fields: readingFieldsIn(item), current: readingIsCurrent(item) };
+}
+
+/** Of two copies of one card that mean the same (sameMeaning), the one a merge
+ *  writes: 'ours' or 'theirs'. They differ at most in volatile and reading
+ *  fields, and the reading is what AI tools are served, so the reading
+ *  decides — from the two copies alone, the same way on every machine
+ *  whichever side is ours (git and Brain Sync compare readings, so an
+ *  ours-first pick would hand two readings back and forth between the repo
+ *  and the cloud): a current reading (readingIsCurrent: a document's text only
+ *  while derivedTextSha names the bytes the card holds) beats none and beats
+ *  a stale one; then the better reading (readingBeats). Copies with the same
+ *  reading keep ours, as before: they differ in volatile fields only. */
+export function pickReadingCopy(o, t) {
+    if (o === t) return 'ours';
+    const ro = readingFieldsOf(o), rt = readingFieldsOf(t);
+    if (stableJson(ro.fields) === stableJson(rt.fields)) return 'ours';
+    if (ro.current !== rt.current) return ro.current ? 'ours' : 'theirs';
+    return readingBeats(ro.fields, rt.fields) ? 'ours' : 'theirs';
+}
+
+/** The copy a merge writes when `winner` — one side's copy of a card, kept
+ *  whole because that side changed the card — meets `donor`, the other side's
+ *  copy of it: the winner, with the donor's reading in place of its own when
+ *  the donor's is still a reading of the winner's bytes and is the better one.
+ *  A document's text goes over only while its derivedTextSha names the
+ *  winner's bytes (an edit that replaced the file leaves it behind as stale);
+ *  any other reading only between copies of one type holding the same asset
+ *  (assetId and assetSha). The edit is a person's and the reading is derived
+ *  from the bytes, so this keeps both: a paid reading (a cloud video analysis)
+ *  is not thrown away because the card was renamed on the other machine. The
+ *  result depends on the two copies alone, whichever side either is. */
+export function carryReading(winner, donor) {
+    if (typeof winner !== 'string' || typeof donor !== 'string' || winner === donor || !donor.includes('derivedText')) return winner;
+    let w, d;
+    try { w = JSON.parse(winner); d = JSON.parse(donor); } catch { return winner; }
+    if (!isPlainObject(w) || !isPlainObject(d) || w.type !== d.type) return winner;
+    const rw = readingFieldsIn(w), rd = readingFieldsIn(d);
+    if (stableJson(rw) === stableJson(rd)) return winner;
+    const carried = { ...w };
+    for (const f of READING_ITEM_FIELDS) delete carried[f];
+    Object.assign(carried, rd);
+    // Current on the WINNER's bytes: a document's text by its derivedTextSha
+    // (readingIsCurrent → savedDocumentText), any other reading by the asset.
+    const ofTheseBytes = readingIsCurrent(carried) && (carried.derivedTextKind === DOCUMENT_TEXT_KIND
+        || ((w.assetId ?? null) === (d.assetId ?? null) && (w.assetSha ?? null) === (d.assetSha ?? null)));
+    if (!ofTheseBytes) return winner;
+    if (readingIsCurrent(w) && readingBeats(rw, rd)) return winner;
+    return JSON.stringify(carried);
+}
+
+// A card as a canonical string: parsed, the given fields stripped, key-sorted.
+// Unparseable JSON falls back to byte identity — a malformed item must never
+// crash a merge.
+function signatureWithout(json, fieldLists) {
     if (json == null) return null;
     try {
         const obj = JSON.parse(json);
-        for (const f of VOLATILE_ITEM_FIELDS) delete obj[f];
+        for (const list of fieldLists) for (const f of list) delete obj[f];
         return stableJson(obj);
     } catch {
         return json;
     }
 }
 
-/** True when two item JSON strings mean the same thing (volatile fields aside).
+/** A card's IDENTITY as a canonical string: volatile fields stripped,
+ *  key-sorted — byte for byte what every engine since 1.86 hashes into bin
+ *  identities (fullEntryRid), conflict-twin ids and revived ids. Reading fields
+ *  stay in: an identity names exact bytes, and hashing anything else would
+ *  make every receipt and twin an older engine minted name different bytes. */
+export function itemSignature(json) {
+    return signatureWithout(json, [VOLATILE_ITEM_FIELDS]);
+}
+
+/** A card's MEANING as a canonical string: volatile AND reading fields
+ *  stripped, key-sorted. What sameMeaning compares. */
+export function meaningSignature(json) {
+    return signatureWithout(json, [VOLATILE_ITEM_FIELDS, READING_ITEM_FIELDS]);
+}
+
+/** True when two item JSON strings mean the same thing (volatile and reading
+ *  fields aside).
  *  The single definition of "did this card actually change": the git merge
  *  driver, the merge engine and the Brain Sync core all decide with it, so all
  *  three transports agree on what an edit is. */
 export const sameMeaning = (a, b) => {
     if (a === b) return true;           // fast path: byte-identical
     if (a == null || b == null) return false;
-    return itemSignature(a) === itemSignature(b);
+    return meaningSignature(a) === meaningSignature(b);
 };
 
 const compactText = (value, max = 140) => String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
@@ -286,6 +407,20 @@ const sha256Hex = (s) => crypto.createHash('sha256').update(String(s)).digest('h
 // An R receipt keeps its F's identity: those bytes are live again, nothing leaks.
 export const fullEntryRid = (id, json) => 'r_' + sha256Hex(`${id}\n${itemSignature(json) ?? ''}`).slice(0, 16);
 
+/** True when `json` holds the bytes a full entry's identity `rid` was minted
+ *  from (`id` is the card the entry was minted for): byte for byte, reading
+ *  fields included, as fullEntryRid mints it in every engine — or those bytes
+ *  with a reading KLYPIX made on the card since (the entry's bytes had none).
+ *  Every check of a copy against a stored rid ("is this the deleted card", "is
+ *  this what the restore put back") goes through here, so a copy is never
+ *  called edited only because KLYPIX read it. */
+export function holdsEntryBytes(id, json, rid) {
+    if (typeof rid !== 'string' || !rid || json == null) return false;
+    if (fullEntryRid(id, json) === rid) return true;
+    const meaning = meaningSignature(json);
+    return meaning !== itemSignature(json) && 'r_' + sha256Hex(`${id}\n${meaning ?? ''}`).slice(0, 16) === rid;
+}
+
 /** The identity of one bin entry: its stored rid, else the one it would have
  *  been minted with. A pre-rid F shares its identity with a new F of the same
  *  bytes; a Stage-1 P (no rid) gets one from fields every copy holds verbatim,
@@ -1091,6 +1226,8 @@ export function fenceContent({ cardId, source, author, text }) {
 // ── Saved readings (P0 agent parity) ─────────────────────────────────────────
 // What KLYPIX has already read, from the saved file alone:
 //   • derivedText on a media card (transcript / analysis / image understanding);
+//   • derivedText on a document's file card (its text, kind 'document-text'),
+//     only while its derivedTextSha names the bytes the card holds;
 //   • a Read contents result: a text card tagged `link` (+ `partial`), with an
 //     arrow FROM the link card TO it (KlypixCanvas readLinkContents);
 //   • an OCR result: a text card tagged `ocr`, arrowed from the image.
@@ -1147,16 +1284,78 @@ export function savedReadingIndex(parsed, hiddenIds = new Set()) {
     return { bySource, byResult };
 }
 
+// A DOCUMENT's reading (the KLYPIX app's agent/documentReading.ts): the text
+// KLYPIX extracted from a file card — PDF, Word, Excel, text, code — saved on
+// the card as derivedText with derivedTextKind 'document-text',
+// derivedTextSource 'local' and derivedTextSha: the bytes it was read from,
+// named by the card's assetSha, else its assetId (an asset id's bytes change
+// only through a repack, and a repack stamps assetSha). It carries no
+// derivedTextAt, so two machines reading the same bytes write the same fields.
+// The reading is CURRENT only while the card still holds those bytes. KLYPIX
+// drops it when the bytes change, but a file written by an older KLYPIX or by
+// another program can still carry one of earlier bytes, and no reader here
+// serves that as what the file says. These are the app's own rules
+// (items/documentReadingFields.ts), restated so this module stays standalone.
+export const DOCUMENT_TEXT_KIND = 'document-text';
+
+/** Which bytes a card holds, as two copies of the card name them: its
+ *  assetSha, else its assetId; null for a card with no bytes of its own. */
+export function documentBytesIdentity(item) {
+    if (!item) return null;
+    if (typeof item.assetSha === 'string' && item.assetSha) return item.assetSha;
+    if (typeof item.assetId === 'string' && item.assetId) return item.assetId;
+    return null;
+}
+
+const SECRET_FILE_EXTENSIONS = new Set(['env', 'pem', 'key', 'p12', 'pfx', 'keystore', 'npmrc', 'netrc', 'htpasswd']);
+/** A file whose words are credentials (.env, keys, .npmrc …). KLYPIX never
+ *  keeps its text on the card, and a reading one carries is never served. */
+export function isSecretBearingFile(item) {
+    if (!item) return false;
+    if (SECRET_FILE_EXTENSIONS.has(String(item.extension || '').toLowerCase().replace(/^\./, ''))) return true;
+    const base = (String(item.fileName || '').split(/[\\/]/).pop() || '').toLowerCase();
+    if (/^\.env(?:\..*)?$/.test(base)) return true;
+    if (/^\.?(?:npmrc|netrc|htpasswd)$/.test(base)) return true;
+    const dot = base.lastIndexOf('.');
+    return dot >= 0 && SECRET_FILE_EXTENSIONS.has(base.slice(dot + 1));
+}
+
+/** A document card's saved text when it was read from the bytes the card
+ *  holds now; null when there is none, when it is another kind of reading,
+ *  when the file changed after it was read (a stale reading), or when the
+ *  file is one whose text is never kept. */
+export function savedDocumentText(item) {
+    if (!item || item.type !== 'file' || item.isFolder) return null;
+    if (item.derivedTextKind !== DOCUMENT_TEXT_KIND) return null;
+    const text = item.derivedText;
+    if (typeof text !== 'string' || !text.trim()) return null;
+    if (isSecretBearingFile(item)) return null;
+    const identity = documentBytesIdentity(item);
+    return identity !== null && item.derivedTextSha === identity ? text : null;
+}
+
+/** True when a card carries a reading a reader may serve as current: a
+ *  document's text only while savedDocumentText says so; a transcript or any
+ *  other reading whenever it is there (those are not tied to the bytes). */
+export function readingIsCurrent(item) {
+    if (!item || typeof item.derivedText !== 'string' || !item.derivedText.trim()) return false;
+    if (item.derivedTextKind === DOCUMENT_TEXT_KIND) return savedDocumentText(item) !== null;
+    return true;
+}
+
 const DERIVED_KIND_LABEL = {
     'image-understanding': 'image understanding',
     'audio-transcript': 'audio transcript',
     'video-transcript': 'video transcript',
     'video-analysis': 'video analysis',
+    'document-text': 'document text',
 };
-/** A media card's saved reading (derivedText), normalised, or null. */
+/** A card's saved reading (derivedText), normalised, or null — null too for a
+ *  document's reading of bytes the card no longer holds (readingIsCurrent). */
 export function derivedReading(item) {
     const text = typeof item?.derivedText === 'string' ? item.derivedText : '';
     if (!text.trim()) return null;
+    if (!readingIsCurrent(item)) return null;
     const kind = typeof item.derivedTextKind === 'string' ? item.derivedTextKind : null;
     return {
         text,
@@ -1175,7 +1374,10 @@ export function notReadStep(item) {
     if (item.type === 'link') return 'select it in KLYPIX and press Enter (Read contents), then let the canvas save';
     if (item.type === 'image') return 'right-click it in KLYPIX and choose Extract text (OCR), then let the canvas save';
     if (item.type === 'video' || item.type === 'audio') return "ask KLYPIX's AI about it in KLYPIX (KLYPIX saves what it reads on the card), then let the canvas save";
-    if (item.type === 'file' && !item.isFolder) return 'KLYPIX does not save the text of document cards yet';
+    if (item.type === 'file' && !item.isFolder) {
+        // KLYPIX never keeps a credential file's text, so no step promises it.
+        return isSecretBearingFile(item) ? null : "ask KLYPIX's AI about it in KLYPIX (KLYPIX saves the text it reads from a document on the card), then let the canvas save";
+    }
     return null;
 }
 
@@ -3840,14 +4042,51 @@ export const deathDateOfCard = (card) => {
     const m = /(?:↩︎ superseded|↩ superseded|✅|⤵ consolidated) (\d{4}-\d{2}-\d{2})/.exec(String(c.text || ''));
     return m ? Date.parse(m[1]) : null;
 };
-export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), recentDays = 30, pairSim = null } = {}) {
+// THE CALLER'S WORDS (1.96.0). A question is worded the asker's way; the card
+// that answers it was worded the day it was written ("magnification controls"
+// vs a card that says "zoom"). The calling agent is itself a model, so brain_ask
+// invites it to add one last line `Also: <words a card answering this would
+// likely use>`. Those words join the MEANING query only (embedded together with
+// the question, one vector); the keyword anchor test, status shape and the
+// rendered question all stay the question's own. Measured 2026-10-11 on the
+// real 3,829-card brain, frozen v2 set (102 answerable), production embedder +
+// warm enrichment-aware vectors, model-written words: recall@5 55 → 60
+// (+8 −3), @8 62 → 69, @20 69 → 78, MRR .375 → .424. Fusing a separate words
+// vector by rank instead did less (+5 −2 at equal weight). Carried inside
+// `question` because no existing tool's input schema may change (see
+// test/tool-schema-freeze.mjs) — a new property would force every host to
+// reconnect; a line in the text works the moment the worker hot-swaps.
+export const ASK_WORDS_MAX = 240;
+// Keyword-only mode (no meaning model), same brain and set, words as extra
+// tokens, through splitAskWords: recall@5 19 → 24 of 102 at half weight with
+// none lost (@10 26 → 32); full weight lost a question the question alone
+// found. Measured 2026-10-11.
+export const ASK_WORDS_LEXICAL_WEIGHT = 0.5;
+export function splitAskWords(question) {
+    const whole = String(question || '').trim();
+    const lines = whole.split(/\r?\n/);
+    const last = lines.length > 1 ? /^\s*also\s*:\s*(.*)$/i.exec(lines[lines.length - 1]) : null;
+    const rest = last ? lines.slice(0, -1).join('\n').trim() : '';
+    // No words line, or nothing above it: the text is the question, untouched.
+    if (!last || !rest) return { question: whole, words: '' };
+    const words = last[1].replace(/\s+/g, ' ').trim().slice(0, ASK_WORDS_MAX).trim();
+    // An empty `Also:` line is dropped; words equal to the question add nothing.
+    return { question: rest, words: words.toLowerCase() === rest.toLowerCase() ? '' : words };
+}
+
+export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), recentDays = 30, pairSim = null, words = '' } = {}) {
     // Status-shaped questions score by their CONTENT tokens only — "remaining"
     // must never lexically select the stale cards that say "remaining:".
     const { content: tokens, statusShaped, strong: statusStrong, areaFamilies = [] } = splitQueryTokens(question);
+    // The caller's Also words (splitAskWords). With the meaning model they ride
+    // the query vector (opBrainAsk); WITHOUT it — a fresh install, the Claude
+    // plugin — they are extra keyword tokens at ASK_WORDS_LEXICAL_WEIGHT, after
+    // the question's own, so the question still leads.
+    const extra = words && !semantic ? splitQueryTokens(words).content.filter(t => !tokens.includes(t)) : [];
     // Area scope (1.85.0): this function HAS the struct, so it resolves the
     // prompt's static families to exact area titles for the status renderer.
     const areas = statusStrong ? areaHintsFromPrompt(struct, question) : null;
-    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !semantic)) return { hits: [], total: 0, tokens, statusShaped, statusStrong, areaFamilies, areas };
+    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !extra.length && !semantic)) return { hits: [], total: 0, tokens, statusShaped, statusStrong, areaFamilies, areas };
     const isArchived = (c) => /^archive$/i.test(c.area || '');
     const asOfTs = as_of ? Date.parse(as_of) : null;
     const timeTravel = asOfTs != null && Number.isFinite(asOfTs);
@@ -3885,6 +4124,10 @@ export function rankForQuestion(struct, question, { semantic = null, k = 10, as_
             else if (wordMatches(tagWords, tagStems, tok)) lex += 3;
             else if (wordMatches(bodyW, bodyStems, tok)) lex += lenNorm;
         }
+        for (const tok of extra) {
+            if (wordMatches(titleW, titleStems, tok) || wordMatches(tagWords, tagStems, tok)) lex += 3 * ASK_WORDS_LEXICAL_WEIGHT;
+            else if (wordMatches(bodyW, bodyStems, tok)) lex += lenNorm * ASK_WORDS_LEXICAL_WEIGHT;
+        }
         const sem = semantic ? (semantic.get(c.id) ?? null) : null;
         if (!semantic && lex <= 0) continue;
         if (semantic && lex <= 0 && sem == null) continue;
@@ -9381,13 +9624,17 @@ export function cardContentsHint(it, hasReading = false) {
         return hasReading ? "KLYPIX's whole saved reading" : `a local path to the ${it.type} file (no reading is saved yet, and ${it.type} cannot be attached)`;
     }
     if (it.type !== 'file') return null;
-    if (ext === 'pdf') return `a local path to the PDF to open with your file-reading tool${it.previewDataUrl ? ", and KLYPIX's saved image of page 1" : ''}`;
-    if (TEXT_FILE_EXT_RE.test(ext)) return "the file's text";
+    // A document KLYPIX has read comes back with its saved text first — only
+    // while that text is of the bytes the card holds — and the file by path.
+    const read = savedDocumentText(it) !== null;
+    const saved = read ? "KLYPIX's saved text of the document, and " : '';
+    if (ext === 'pdf') return `${saved}a local path to the PDF to open with your file-reading tool${it.previewDataUrl ? ", and KLYPIX's saved image of page 1" : ''}`;
+    if (TEXT_FILE_EXT_RE.test(ext)) return read ? `${saved}a local path to the file to open with your file-reading tool` : "the file's text";
     if (OFFICE_FILE_EXT_RE.test(ext)) {
-        const preview = it.previewSheet ? "KLYPIX's saved first rows of the sheet" : it.previewHtml ? "KLYPIX's saved opening text" : null;
-        return `a local path to the file to open with your file-reading tool${preview ? `, and ${preview}` : ''}`;
+        const preview = read ? null : it.previewSheet ? "KLYPIX's saved first rows of the sheet" : it.previewHtml ? "KLYPIX's saved opening text" : null;
+        return `${saved}a local path to the file to open with your file-reading tool${preview ? `, and ${preview}` : ''}`;
     }
-    return 'a local path to the file to open with your file-reading tool';
+    return `${saved}a local path to the file to open with your file-reading tool`;
 }
 
 /**

package/src/merge-brains.mjs

@@ -164,7 +164,7 @@ import { createHash } from 'node:crypto';
 import {
   parseKlypix, shard, sameMeaning, itemSignature, twinIdFor, binEntryFor,
   entryKind, receiptIdentity, revivedIdFor, pickBinEntry, contentFreeReceiptFor, PURGED_BODY, fullEntryRid,
-  pickThreeWay, canonicalFirst,
+  pickThreeWay, canonicalFirst, pickReadingCopy, carryReading, holdsEntryBytes,
 } from './klypix-format.mjs';
 import { generateKeyBetween } from 'fractional-indexing';
 
@@ -217,9 +217,9 @@ const ARCHIVE = /^archive$/i;
 // against 1.86 — the git driver, the API-5 KLYPIX sync core — import them from
 // this module, and the KLYPIX core reads the whole engine off this namespace.
 export {
-  sameMeaning, itemSignature, VOLATILE_ITEM_FIELDS, twinIdFor, revivedIdFor, receiptIdentity, entryKind,
-  isContentFreeReceipt, pickBinEntry, PURGED_BODY, binEntryFor, contentFreeReceiptFor, fullEntryRid,
-  pickThreeWay,
+  sameMeaning, itemSignature, meaningSignature, VOLATILE_ITEM_FIELDS, READING_ITEM_FIELDS, twinIdFor, revivedIdFor, receiptIdentity, entryKind,
+  isContentFreeReceipt, pickBinEntry, PURGED_BODY, binEntryFor, contentFreeReceiptFor, fullEntryRid, holdsEntryBytes,
+  pickThreeWay, pickReadingCopy, carryReading,
 } from './klypix-format.mjs';
 export { purgeGraveyard, restoreFromGraveyard, listGraveyard } from './brain-graveyard.mjs';
 
@@ -258,6 +258,7 @@ export const MERGE_ENGINE_FEATURES = Object.freeze({
   arrangeReceipts: true,             // arrangeBrain buries what it collapses, survivor from content and ids (E-8)
   revivalMap: true,                  // revivalMap, and brainDelta's lastKnown/collectLive, for the live watcher
   sideFreeTies: true,                // option modes: a tie between two sides is broken from the values alone (pickThreeWay)
+  derivedReadings: true,             // every caller: a card's saved reading (READING_ITEM_FIELDS) is no part of its meaning — no twin, no conflict, a delete wins; the better reading is kept (pickReadingCopy) and carried over a one-sided edit (carryReading); identities still hash it, as in 1.94 (holdsEntryBytes checks a copy against one)
   options: OPTION_VALUES,
 });
 
@@ -318,11 +319,31 @@ const sha12 = (s) => createHash('sha256').update(String(s)).digest('hex').slice(
 // list (updatedAt, zIndex, editedAt) — lives in klypix-format.mjs since 1.89,
 // so the bin identity (receiptIdentity) and twin ids hash exactly the meaning
 // this merge compares.
+//
+// A card's saved READING (READING_ITEM_FIELDS: derivedText and its kind,
+// source, sha, time and visuals — a document's text, a transcript) is no part
+// of its meaning: sameMeaning compares meaningSignature, which strips it. It is
+// derived from the card's bytes and made again when missing. Two machines that
+// read one card between syncs wrote those fields independently, and counted as
+// content they kept a conflict twin of the card (a media reading's time stamp
+// alone did it), or brought back a card the other side had deleted (a reading
+// counted as the edit the deleter never saw). Now a reading-only difference is
+// one card and a reading never beats a delete. The reading still decides which
+// copy is written — it is what AI tools are served, and git and Brain Sync
+// compare it: pickReadingCopy keeps the better reading, from the copies alone,
+// and carryReading moves a current reading over an edit the other side made.
+// IDENTITIES do not change: itemSignature, fullEntryRid, twinIdFor and
+// revivedIdFor hash the card with its reading, byte for byte as 1.94 does, so
+// the receipts and twins older engines minted keep naming the same bytes; a
+// copy is checked against a stored rid with holdsEntryBytes, which also
+// accepts the copy with a reading made since.
 
 // Load one .klypix buffer into a flat, comparison-friendly shape. Item JSON is
 // kept VERBATIM (the merge must write back exactly what a side held); whether
 // two versions actually differ is decided by sameMeaning(), never by these
-// bytes — see its note on volatile fields.
+// bytes — see its note on volatile fields. The one exception is carryReading:
+// a card one side edited, with the other side's saved reading in place of its
+// own, is a combination of the two copies (the same one on every machine).
 async function loadSide(buf) {
   if (!buf) return null;
   const { zip, canvas, manifest, struct } = await parseKlypix(buf);
@@ -631,7 +652,7 @@ function mergeUnion(B, O, T, del, deletedMeta) {
     if (inO && inT) {
       // Change + divergence are judged by MEANING, not bytes (see sameMeaning):
       // a restamped `updatedAt` is not an edit, and two copies of one card that
-      // differ only in volatile fields are not in conflict.
+      // differ only in volatile or reading fields are not in conflict.
       const oChg = !inB || !sameMeaning(O.items[id], baseItem(id));
       const tChg = !inB || !sameMeaning(T.items[id], baseItem(id));
       const diverged = !sameMeaning(O.items[id], T.items[id]);
@@ -642,7 +663,7 @@ function mergeUnion(B, O, T, del, deletedMeta) {
         const record = { id, kind: 'content', keptLive: 'ours', twin: null };
         conflicts.push(record);
         twinRequests.push({ k: id, v: T.items[id], srcPos: T.positions[id] || O.positions[id], record });
-      } else if (tChg && !oChg) { json = T.items[id]; side = 'theirs'; delta.updated.push(id); }
+      } else if (tChg && !oChg) { json = carryReading(T.items[id], O.items[id]); side = 'theirs'; delta.updated.push(id); }
       else if (!inB && diverged) {
         if (!B) {
           // With NO baseline we cannot prove which meaning is newer or whether
@@ -659,10 +680,23 @@ function mergeUnion(B, O, T, del, deletedMeta) {
           // can be present on both sides after live-apply and re-serialized with
           // slightly different bytes. It is one card, not a conflict — keep the
           // disk/agent bytes and never create the historical duplicate twin.
-          json = T.items[id]; side = 'theirs';
+          json = carryReading(T.items[id], O.items[id]); side = 'theirs';
         }
       }
-      else { json = O.items[id]; side = 'ours'; }
+      else if (!diverged) {
+        // One card: the copies differ in volatile and reading fields at most.
+        // The one with the better reading is written (pickReadingCopy) — the
+        // same copy whichever side is ours, so a reading theirs made is kept.
+        side = pickReadingCopy(O.items[id], T.items[id]);
+        json = side === 'ours' ? O.items[id] : T.items[id];
+        if (side === 'theirs') delta.updated.push(id);
+      }
+      else {
+        // Ours changed the card and theirs did not: ours' copy, with the
+        // reading theirs holds carried over while it is still of these bytes.
+        json = carryReading(O.items[id], T.items[id]); side = 'ours';
+        if (json !== O.items[id]) delta.updated.push(id);
+      }
     } else if (inT) {
       json = T.items[id]; side = 'theirs';
       if (!inB) delta.added.push(id);            // agent added since open — the anti-clobber core
@@ -794,7 +828,7 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
       // twin. Both are counted in purgedCopies.
       const via = reached.get(id);
       if (via && via.rid && E === via.entry) {
-        if (fullEntryRid(via.from, v) !== via.rid) conflicts.push({ id, kind: 'purge-vs-edit', side, purgedWith: via.root });
+        if (!holdsEntryBytes(via.from, v, via.rid)) conflicts.push({ id, kind: 'purge-vs-edit', side, purgedWith: via.root });
         else conflicts.push({ id, kind: 'purge-reached-restore', side, purgedWith: via.root });
       } else purgeVsEdit(side, id, v);
       return;
@@ -989,7 +1023,7 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
     const ownsFullEntry = (S) => { const e = S?.graveyard?.[x]; return !!e && entryKind(e.meta) === 'F'; };
     const keptByPurger = (root) => [O, T].some((S) => ownsPurge(S, root) && (live(S, x) || ownsFullEntry(S)));
     const via = [...(reachedVia?.rid ? [reachedVia] : []), ...(rootRestores.get(parent) || []).filter((c) => !keptByPurger(c.root))]
-      .find((c) => copies.every((v) => fullEntryRid(c.from, v) === c.rid));
+      .find((c) => copies.every((v) => holdsEntryBytes(c.from, v, c.rid)));
     if (via) reachedTwins.push([x, via]);
   }
   for (const [x, via] of reachedTwins) {
@@ -1098,7 +1132,7 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
     if (fate.get(y)?.entry !== via.entry) continue;
     const typedInto = [O, T].some((S) => {
       const F = live(S, y) ? null : eOf(S, y);
-      return !!F && entryKind(F.meta) === 'F' && !(via.rid && fullEntryRid(via.from, F.json) === via.rid);
+      return !!F && entryKind(F.meta) === 'F' && !(via.rid && holdsEntryBytes(via.from, F.json, via.rid));
     });
     if (!typedInto) continue;
     conflicts.push({ id: y, kind: 'purge-vs-edit', side: 'bin', purgedWith: via.root }); binEditsPurged++;
@@ -1178,7 +1212,7 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
     (restoredBytes.get(at) || restoredBytes.set(at, []).get(at)).push([d, e.meta.rid]);
     restoredHere.get(S)?.add(at);
   }
-  const asRestored = (id, v) => (restoredBytes.get(id) || []).some(([d, rid]) => fullEntryRid(d, v) === rid);
+  const asRestored = (id, v) => (restoredBytes.get(id) || []).some(([d, rid]) => holdsEntryBytes(d, v, rid));
   const repoint = (S, from, to) => {
     for (const c of S.connections) { if (c.fromId === from) c.fromId = to; if (c.toId === from) c.toId = to; }
     for (const [cid, p] of Object.entries(S.positions)) if (p && p.parentId === from) S.positions[cid] = { ...p, parentId: to };
@@ -1453,15 +1487,15 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
           // newer — unordered, so it is kept beside the card, never over it.
           json = O.items[id]; side = 'ours';
           twinOf(id, T.items[id], srcPos, 'content-unverified');
-        } else { json = T.items[id]; side = 'theirs'; delta.updated.push(id); }
+        } else { json = carryReading(T.items[id], O.items[id]); side = 'theirs'; delta.updated.push(id); }
       } else if (!cb && diverged && B && !unverified && editsItsRestore(id)) {
         // One restore made on both sides — the same deletion, so the same id —
         // is new on both since the base, yet its receipt names the bytes it
         // came back with: the side still holding them has not touched the
         // card, so the other side's text is an edit of it, not a conflict.
         // (With no base, both are kept as ever: such a copy may be a revert.)
-        if (asRestored(id, O.items[id])) { json = T.items[id]; side = 'theirs'; delta.updated.push(id); }
-        else { json = O.items[id]; side = 'ours'; }
+        if (asRestored(id, O.items[id])) { json = carryReading(T.items[id], O.items[id]); side = 'theirs'; delta.updated.push(id); }
+        else { json = carryReading(O.items[id], T.items[id]); side = 'ours'; if (json !== O.items[id]) delta.updated.push(id); }
       } else if (!cb && diverged) {
         if (!B) {
           json = O.items[id]; side = 'ours';
@@ -1472,7 +1506,21 @@ function mergeOptionMode(B, O, T, del, deletedMeta, opt) {
           // (S10, the app-save rule) would lose ours silently.
           json = O.items[id]; side = 'ours';
           twinOf(id, T.items[id], srcPos, 'content-new-both');
-        } else { json = T.items[id]; side = 'theirs'; }
+        } else { json = carryReading(T.items[id], O.items[id]); side = 'theirs'; }
+      } else if (!diverged && !unverified) {
+        // One card: the copies differ in volatile and reading fields at most.
+        // The one with the better reading is written (pickReadingCopy),
+        // decided from the two copies alone — never "ours", or git and Brain
+        // Sync would hand two readings back and forth. Foreign bytes
+        // (unverified) never replace our card, so there ours stays.
+        side = pickReadingCopy(O.items[id], T.items[id]);
+        json = side === 'ours' ? O.items[id] : T.items[id];
+        if (side === 'theirs') delta.updated.push(id);
+      } else if (!unverified) {
+        // Ours changed the card and theirs did not: ours' copy, with the
+        // reading theirs holds carried over while it is still of these bytes.
+        json = carryReading(O.items[id], T.items[id]); side = 'ours';
+        if (json !== O.items[id]) delta.updated.push(id);
       } else { json = O.items[id]; side = 'ours'; }
     } else if (inT) {
       json = T.items[id]; side = 'theirs';