diff --git a/CHANGELOG.md b/CHANGELOG.md
index bde3018c..57333592 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.27.0
+
+Saved articles retain the evidence behind their metadata. PDF capture improves reading order and reports uncertain layout.
+
+- Keep observed titles, authors, dates, descriptions, standard page tags and bounded JSON-LD claims with their sources and selection rules. Dates without a timezone remain explicitly uncertain.
+- Read separated PDF columns in order, preserve simple aligned tables and basic superscripts, and report layout losses as partial captures. Keep the original PDF for reference.
+- Add public PDF bundle inspection and verification for source, Markdown, page references and image hashes, with bounded reads and typed capture errors.
+
 ## 0.26.3
 
 SDK consumers can augment Node environment types without breaking isolated subprocesses.
diff --git a/README.md b/README.md
index ac48ed69..47a150fa 100644
--- a/README.md
+++ b/README.md
@@ -74,14 +74,14 @@ Wordcell keeps the record in Markdown files you own, rebuilds every index from t
 The CLI and TypeScript SDK run with Bun. Install the versioned GitHub archive:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 wordcell --help
 ```
 
 Prefer npm? The same release is [mirrored there](https://www.npmjs.com/package/@hraness/wordcell):
 
 ```sh
-npm install --global --ignore-scripts @hraness/wordcell@0.26.3
+npm install --global --ignore-scripts @hraness/wordcell@0.27.0
 wordcell --help
 ```
 
@@ -145,7 +145,7 @@ After trying the CLI, install the public Agent Skill into a compatible agent,
 such as Claude Code, Codex, Cursor, or GitHub Copilot:
 
 ```sh
-bunx skills add hraness/wordcell#v0.26.3 --skill wordcell
+bunx skills add hraness/wordcell#v0.27.0 --skill wordcell
 ```
 
 Then ask:
@@ -361,7 +361,7 @@ exist. [Graph queries and proof limits](https://github.com/hraness/wordcell/blob
 Add the same immutable release to a Bun project:
 
 ```sh
-bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 ```
 
 The SDK provides read-only vault sessions, metadata queries, search, graph
diff --git a/bun.lock b/bun.lock
index f92b3ba6..3e180bc3 100644
--- a/bun.lock
+++ b/bun.lock
@@ -13,6 +13,7 @@
         "agent-browser": "0.32.3",
         "defuddle": "0.19.1",
         "effect": "3.22.1",
+        "entities": "7.0.1",
         "yaml": "^2.9.0",
         "zod": "^4.4.3",
       },
diff --git a/dist/capture.js b/dist/capture.js
index 62036e88..00014340 100644
--- a/dist/capture.js
+++ b/dist/capture.js
@@ -5,19 +5,23 @@ import {
   captureSummary,
   main,
   runCapture
-} from "./index-h9vyd03z.js";
-import"./index-hacpnaew.js";
-import"./index-k86wepd8.js";
+} from "./index-58azscg5.js";
+import"./index-fd8j527z.js";
+import"./index-h2w7syy2.js";
 import {
   adapterCapabilities,
   inspectClipEnvironment,
   renderDoctorReport
-} from "./index-nd8v7r0z.js";
+} from "./index-sp43012q.js";
 import"./index-hnvx7m1j.js";
-import"./index-ncwzmsge.js";
-import"./index-cd75vky9.js";
+import"./index-nwdzhj1h.js";
+import"./index-jbtyp6q5.js";
 import"./index-2gv8y733.js";
-import"./index-mxxxytys.js";
+import"./index-g63d3937.js";
+import {
+  extractArticleMetadata,
+  parseArticleMetadata
+} from "./index-e2wstc7t.js";
 import"./index-w2zc0vwa.js";
 import"./index-e5fbsywq.js";
 import"./index-gh719d91.js";
@@ -38,11 +42,15 @@ var inspectClipEnvironment2 = (...arguments_) => inspectClipEnvironment(...argum
 var parseCaptureArguments = (...arguments_) => parseArguments(...arguments_);
 var renderDoctorReport2 = (...arguments_) => renderDoctorReport(...arguments_);
 var runCapture2 = (...arguments_) => runCapture(...arguments_);
+var extractArticleMetadata2 = (...arguments_) => extractArticleMetadata(...arguments_);
+var parseArticleMetadata2 = (...arguments_) => parseArticleMetadata(...arguments_);
 export {
   runCapture2 as runCapture,
   renderDoctorReport2 as renderDoctorReport,
   parseCaptureArguments,
+  parseArticleMetadata2 as parseArticleMetadata,
   inspectClipEnvironment2 as inspectClipEnvironment,
+  extractArticleMetadata2 as extractArticleMetadata,
   clipMain,
   captureSummary2 as captureSummary,
   captureSucceeded2 as captureSucceeded,
diff --git a/dist/cli-bin.js b/dist/cli-bin.js
index 04a7ff97..daf19df8 100755
--- a/dist/cli-bin.js
+++ b/dist/cli-bin.js
@@ -2,7 +2,7 @@
 // @bun
 import {
   runWordcellBin
-} from "./index-6c8xhred.js";
+} from "./index-k9yzc4vn.js";
 import"./index-3t0v457d.js";
 import"./index-t4hjm1kk.js";
 import"./index-4knsp9qj.js";
diff --git a/dist/cli.js b/dist/cli.js
index 50317080..78a5d35a 100755
--- a/dist/cli.js
+++ b/dist/cli.js
@@ -6,22 +6,23 @@ import {
   parseArguments,
   runExecutable,
   usage
-} from "./index-878bh2f1.js";
-import"./index-5h5awwh4.js";
-import"./index-m9p2a4mj.js";
+} from "./index-30v9w4cy.js";
+import"./index-b40e2dkx.js";
+import"./index-my50xsa3.js";
 import"./index-3hts6yy9.js";
-import"./index-j4zgmzjr.js";
-import"./index-npg9z1a4.js";
-import"./index-h9vyd03z.js";
-import"./index-hacpnaew.js";
-import"./index-k86wepd8.js";
-import"./index-nd8v7r0z.js";
+import"./index-8djdwjjd.js";
+import"./index-xn5q4kne.js";
+import"./index-58azscg5.js";
+import"./index-fd8j527z.js";
+import"./index-h2w7syy2.js";
+import"./index-sp43012q.js";
 import"./index-hnvx7m1j.js";
 import"./index-t4hjm1kk.js";
-import"./index-ncwzmsge.js";
-import"./index-cd75vky9.js";
+import"./index-nwdzhj1h.js";
+import"./index-jbtyp6q5.js";
 import"./index-2gv8y733.js";
-import"./index-mxxxytys.js";
+import"./index-g63d3937.js";
+import"./index-e2wstc7t.js";
 import"./index-w2zc0vwa.js";
 import"./index-e5fbsywq.js";
 import"./index-gh719d91.js";
@@ -65,7 +66,7 @@ import {
 
 // src/cli.ts
 async function runStandaloneCli(args = process.argv.slice(2)) {
-  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-hd4754m4.js");
+  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-s059eytv.js");
   const env = standaloneSupportEnvironment();
   if (args[0] === "support") {
     return await runProductSupportCommand(args.slice(1), { env });
diff --git a/dist/clip/acquire.js b/dist/clip/acquire.js
index 619e417c..240f4c0a 100644
--- a/dist/clip/acquire.js
+++ b/dist/clip/acquire.js
@@ -22,10 +22,11 @@ import {
   mergeRenderedTextSnapshots,
   readBrowserExpansionTelemetry,
   seedOwnedBrowserCookies
-} from "../index-ncwzmsge.js";
-import"../index-cd75vky9.js";
+} from "../index-nwdzhj1h.js";
+import"../index-jbtyp6q5.js";
 import"../index-2gv8y733.js";
-import"../index-mxxxytys.js";
+import"../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-w2zc0vwa.js";
 import"../index-e5fbsywq.js";
 import"../index-gh719d91.js";
diff --git a/dist/clip/bundle-reader.js b/dist/clip/bundle-reader.js
index 4b1a1036..63853325 100644
--- a/dist/clip/bundle-reader.js
+++ b/dist/clip/bundle-reader.js
@@ -2,8 +2,9 @@
 import {
   readCaptureBundle,
   verifyCaptureBundle
-} from "../index-npg9z1a4.js";
-import"../index-mxxxytys.js";
+} from "../index-xn5q4kne.js";
+import"../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-1xxnjn0d.js";
 import"../index-z1w83f81.js";
 export {
diff --git a/dist/clip/cli.js b/dist/clip/cli.js
index 4363f2ec..05ff0729 100755
--- a/dist/clip/cli.js
+++ b/dist/clip/cli.js
@@ -5,15 +5,16 @@ import {
   captureSucceeded,
   captureSummary,
   main
-} from "../index-h9vyd03z.js";
-import"../index-hacpnaew.js";
-import"../index-k86wepd8.js";
-import"../index-nd8v7r0z.js";
+} from "../index-58azscg5.js";
+import"../index-fd8j527z.js";
+import"../index-h2w7syy2.js";
+import"../index-sp43012q.js";
 import"../index-hnvx7m1j.js";
-import"../index-ncwzmsge.js";
-import"../index-cd75vky9.js";
+import"../index-nwdzhj1h.js";
+import"../index-jbtyp6q5.js";
 import"../index-2gv8y733.js";
-import"../index-mxxxytys.js";
+import"../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-w2zc0vwa.js";
 import"../index-e5fbsywq.js";
 import"../index-gh719d91.js";
diff --git a/dist/clip/defuddle-worker.js b/dist/clip/defuddle-worker.js
index aaab7313..d6882af7 100644
--- a/dist/clip/defuddle-worker.js
+++ b/dist/clip/defuddle-worker.js
@@ -1,4 +1,7 @@
 // @bun
+import {
+  extractArticleMetadata
+} from "../index-e2wstc7t.js";
 import"../index-z1w83f81.js";
 
 // src/clip/defuddle-worker.ts
@@ -161,7 +164,7 @@ workerGlobal.onmessage = async (event) => {
       useAsync: false,
       removeImages: false
     });
-    const enriched = typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value, captureVideoPosters: videoPosters } : value;
+    const enriched = typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value, captureVideoPosters: videoPosters, metadata: await extractArticleMetadata(request.html, request.url, value) } : value;
     workerGlobal.postMessage({ ok: true, value: enriched });
   } catch {
     workerGlobal.postMessage({ ok: false, message: "Defuddle could not parse this acquisition." });
diff --git a/dist/clip/doctor.js b/dist/clip/doctor.js
index 8b25b8b8..232d54b7 100644
--- a/dist/clip/doctor.js
+++ b/dist/clip/doctor.js
@@ -9,11 +9,12 @@ import {
   renderAdapterCapabilities,
   renderDoctorReport,
   runDiagnosticCommand
-} from "../index-nd8v7r0z.js";
-import"../index-ncwzmsge.js";
-import"../index-cd75vky9.js";
+} from "../index-sp43012q.js";
+import"../index-nwdzhj1h.js";
+import"../index-jbtyp6q5.js";
 import"../index-2gv8y733.js";
-import"../index-mxxxytys.js";
+import"../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-w2zc0vwa.js";
 import"../index-e5fbsywq.js";
 import"../index-gh719d91.js";
diff --git a/dist/clip/jobs.js b/dist/clip/jobs.js
index d9aac11b..8747c658 100644
--- a/dist/clip/jobs.js
+++ b/dist/clip/jobs.js
@@ -1,7 +1,8 @@
 // @bun
 import {
   redactSensitiveText
-} from "../index-mxxxytys.js";
+} from "../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import {
   sanitizeTerminalLine,
   sanitizeTerminalText
diff --git a/dist/clip/persist.js b/dist/clip/persist.js
index f137d25c..3938b48b 100644
--- a/dist/clip/persist.js
+++ b/dist/clip/persist.js
@@ -12,7 +12,8 @@ import {
   sanitizeArtifactUrl,
   sanitizeSourceHtml,
   writeCaptureBundle
-} from "../index-mxxxytys.js";
+} from "../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-1xxnjn0d.js";
 import"../index-z1w83f81.js";
 export {
diff --git a/dist/clip/refresh.js b/dist/clip/refresh.js
index 9b5eebef..cb8fb8cc 100644
--- a/dist/clip/refresh.js
+++ b/dist/clip/refresh.js
@@ -1,9 +1,10 @@
 // @bun
 import {
   diffCaptureBundle
-} from "../index-j4zgmzjr.js";
-import"../index-npg9z1a4.js";
-import"../index-mxxxytys.js";
+} from "../index-8djdwjjd.js";
+import"../index-xn5q4kne.js";
+import"../index-g63d3937.js";
+import"../index-e2wstc7t.js";
 import"../index-1gwbassd.js";
 import"../index-1xxnjn0d.js";
 import"../index-z1w83f81.js";
diff --git a/dist/evaluation-builder-bin.js b/dist/evaluation-builder-bin.js
index 5c734861..57475e66 100755
--- a/dist/evaluation-builder-bin.js
+++ b/dist/evaluation-builder-bin.js
@@ -2,7 +2,7 @@
 // @bun
 import {
   runWordcellBin
-} from "./index-6c8xhred.js";
+} from "./index-k9yzc4vn.js";
 import"./index-3t0v457d.js";
 import"./index-t4hjm1kk.js";
 import"./index-4knsp9qj.js";
diff --git a/dist/index-878bh2f1.js b/dist/index-30v9w4cy.js
similarity index 99%
rename from dist/index-878bh2f1.js
rename to dist/index-30v9w4cy.js
index f2ba02cb..f04f5c82 100644
--- a/dist/index-878bh2f1.js
+++ b/dist/index-30v9w4cy.js
@@ -3,10 +3,10 @@ import {
   backfillSavedUrlMetadata,
   createRustMetadataSearchProvider,
   savedSourceProblem
-} from "./index-5h5awwh4.js";
+} from "./index-b40e2dkx.js";
 import {
   main as main2
-} from "./index-m9p2a4mj.js";
+} from "./index-my50xsa3.js";
 import {
   MAX_AUTHORIZED_VAULTS,
   auditKnowledgePortfolio,
@@ -16,13 +16,13 @@ import {
 } from "./index-3hts6yy9.js";
 import {
   diffCaptureBundle
-} from "./index-j4zgmzjr.js";
+} from "./index-8djdwjjd.js";
 import {
   verifyCaptureBundle
-} from "./index-npg9z1a4.js";
+} from "./index-xn5q4kne.js";
 import {
   main
-} from "./index-h9vyd03z.js";
+} from "./index-58azscg5.js";
 import {
   advancedHelp,
   closestMatch,
@@ -43,11 +43,11 @@ import {
   symbol,
   terminalOutput,
   terminalStyle
-} from "./index-cd75vky9.js";
+} from "./index-jbtyp6q5.js";
 import {
   redactSensitiveText,
   sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   initVault
 } from "./index-23z4zxgg.js";
diff --git a/dist/index-h9vyd03z.js b/dist/index-58azscg5.js
similarity index 99%
rename from dist/index-h9vyd03z.js
rename to dist/index-58azscg5.js
index 3adf068f..240bd3e3 100644
--- a/dist/index-h9vyd03z.js
+++ b/dist/index-58azscg5.js
@@ -2,7 +2,7 @@
 import {
   acquireArchiveTodaySnapshot,
   discoverArchiveTodaySnapshot
-} from "./index-hacpnaew.js";
+} from "./index-fd8j527z.js";
 import {
   canonicalizeUrl,
   chooseBestExtraction,
@@ -12,13 +12,13 @@ import {
   localizeAssets,
   scoreExtraction,
   sniffImage
-} from "./index-k86wepd8.js";
+} from "./index-h2w7syy2.js";
 import {
   adapterCapabilities,
   inspectClipEnvironment,
   renderAdapterCapabilities,
   renderDoctorReport
-} from "./index-nd8v7r0z.js";
+} from "./index-sp43012q.js";
 import {
   cloneBrowserProfile
 } from "./index-hnvx7m1j.js";
@@ -34,7 +34,7 @@ import {
   renderCookiePermissionNotice,
   renderCookiePermissionRecovery,
   setCookiePermissionReporter
-} from "./index-ncwzmsge.js";
+} from "./index-nwdzhj1h.js";
 import {
   CONTENT_REWRITE_TRUNCATION_WARNING,
   buildClipMarkdown,
@@ -51,7 +51,7 @@ import {
   stderrStyle,
   terminalOutput,
   writesToTerminal
-} from "./index-cd75vky9.js";
+} from "./index-jbtyp6q5.js";
 import {
   MAX_COOKIE_BYTES,
   filterCookieProviderResult,
@@ -68,7 +68,7 @@ import {
   redactSensitiveTextWithCount,
   sanitizeArtifactUrl,
   writeCaptureBundle
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   startNetworkProxy
 } from "./index-w2zc0vwa.js";
@@ -2285,6 +2285,7 @@ async function runCapture(rawOptions, dependencies = {}) {
       const finalWarnings = finalizedWarnings(combinedWarnings, redactedMarkdown.count);
       const includeSource = options.evidence === "source" || options.evidence === "all";
       const manifestInput = {
+        ...article.metadata === undefined ? {} : { metadata: article.metadata },
         sourceUrl,
         canonicalUrl: best.canonicalUrl.href,
         capturedAt,
diff --git a/dist/index-j4zgmzjr.js b/dist/index-8djdwjjd.js
similarity index 99%
rename from dist/index-j4zgmzjr.js
rename to dist/index-8djdwjjd.js
index 1fb5c360..a262dfc3 100644
--- a/dist/index-j4zgmzjr.js
+++ b/dist/index-8djdwjjd.js
@@ -1,7 +1,7 @@
 // @bun
 import {
   readCaptureBundle
-} from "./index-npg9z1a4.js";
+} from "./index-xn5q4kne.js";
 import {
   runGitCommand
 } from "./index-1gwbassd.js";
diff --git a/dist/index-5h5awwh4.js b/dist/index-b40e2dkx.js
similarity index 99%
rename from dist/index-5h5awwh4.js
rename to dist/index-b40e2dkx.js
index 4a28c50a..fccf60d4 100644
--- a/dist/index-5h5awwh4.js
+++ b/dist/index-b40e2dkx.js
@@ -5,10 +5,10 @@ import {
   parseArchiveTodayMementoUrl,
   parseMetadataSearchResponse,
   rankMetadataSearchResults
-} from "./index-hacpnaew.js";
+} from "./index-fd8j527z.js";
 import {
   sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   assertSafeNetworkUrl,
   isPrivateHostname,
diff --git a/dist/index-e2wstc7t.js b/dist/index-e2wstc7t.js
new file mode 100644
index 00000000..f9c8b51b
--- /dev/null
+++ b/dist/index-e2wstc7t.js
@@ -0,0 +1,323 @@
+// @bun
+// src/clip/metadata.ts
+import { decodeHTML } from "entities";
+var metadataLimits = { htmlBytes: 8 * 1024 * 1024, claims: 256, value: 8192, totalBytes: 256 * 1024, jsonBytes: 128 * 1024, jsonNodes: 2048, jsonDepth: 12 };
+var record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var sources = new Set(["html-title", "html-meta", "html-link", "html-language", "json-ld", "extractor"]);
+var warningKinds = new Set(["input-limit", "claim-limit", "value-limit", "json-limit", "json-invalid"]);
+var credentialName = /(?:csrf|xsrf|token|nonce|password|secret|session|authorization|api[-_]?key|signature)/i;
+var urlFields = new Set(["canonical", "alternate", "image", "url"]);
+var dateFields = new Set(["published", "modified"]);
+function publicUrl(value, base) {
+  try {
+    const url = new URL(value, base);
+    if (!/^https?:$/.test(url.protocol))
+      return null;
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+function cleanText(value) {
+  return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "").replace(/https?:\/\/[^\s<>"']+/giu, (url) => publicUrl(url) ?? "[invalid URL]").replace(/\s+/gu, " ").trim();
+}
+function dateValue(value) {
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+  const zoned = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
+  const local = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/.test(value);
+  const parsed = Date.parse(dateOnly ? value + "T00:00:00Z" : local ? value + "Z" : value);
+  const validDay = Number.isFinite(parsed) && new Date(Date.UTC(Number(value.slice(0, 4)), Number(value.slice(5, 7)) - 1, Number(value.slice(8, 10)))).toISOString().slice(0, 10) === value.slice(0, 10);
+  if (!dateOnly && !zoned && !local || !validDay)
+    return { value, datePrecision: "invalid", timezone: "unknown" };
+  if (dateOnly)
+    return { value, datePrecision: "date", timezone: "not-applicable" };
+  return { value: zoned ? new Date(parsed).toISOString() : value, datePrecision: "datetime", timezone: zoned ? "explicit" : "unknown" };
+}
+function rank(claim) {
+  if (claim.datePrecision === "invalid")
+    return 1000;
+  if (claim.source === "json-ld")
+    return claim.rule.includes("jsonld-type=WebPage") ? 15 : 10;
+  if (claim.source === "html-link")
+    return 5;
+  if (claim.locator.includes("property=article:"))
+    return 20;
+  if (claim.locator.includes("property=og:"))
+    return 30;
+  if (claim.locator.includes("name=twitter:"))
+    return 40;
+  if (claim.source === "html-meta")
+    return 50;
+  if (claim.source === "html-title" || claim.source === "html-language")
+    return 60;
+  return 90;
+}
+function select(claims) {
+  const ranks = new Map;
+  for (const claim of claims)
+    ranks.set(claim.field, Math.min(ranks.get(claim.field) ?? 1000, rank(claim)));
+  const chosen = new Set;
+  return claims.map((claim) => {
+    const multiple = ["authors", "tags", "alternate"].includes(claim.field);
+    const selected = rank(claim) < 1000 && rank(claim) === ranks.get(claim.field) && (multiple || !chosen.has(claim.field));
+    if (selected)
+      chosen.add(claim.field);
+    return { ...claim, selected, rule: `metadata-precedence-v1:${claim.rule}` };
+  });
+}
+function parseArticleMetadata(input, redact = cleanText) {
+  if (!record(input) || input.schemaVersion !== 1 || input.extractorVersion !== "wordcell-metadata-v1" || !Array.isArray(input.claims) || input.claims.length > metadataLimits.claims || !Array.isArray(input.warnings))
+    throw new Error("Unsupported or malformed article metadata envelope");
+  let bytes = 0;
+  const text = (value2, limit = metadataLimits.value) => {
+    if (typeof value2 !== "string" || value2.length > limit)
+      throw new Error("Invalid article metadata text");
+    const result = cleanText(redact(value2));
+    bytes += Buffer.byteLength(result);
+    if (bytes > metadataLimits.totalBytes)
+      throw new Error("Article metadata exceeds byte limit");
+    return result;
+  };
+  const value = (v) => Array.isArray(v) ? v.length <= 32 ? v.map((part) => text(part)) : (() => {
+    throw new Error("Article metadata list exceeds limit");
+  })() : text(v);
+  const claims = input.claims.map((raw) => {
+    if (!record(raw) || !sources.has(raw.source) || typeof raw.selected !== "boolean")
+      throw new Error("Invalid article metadata claim");
+    const field = text(raw.field, 128);
+    if (!/^[a-z][a-z0-9:_-]{0,127}$/.test(field) || credentialName.test(field))
+      throw new Error("Invalid article metadata field");
+    let observed = value(raw.observed), normalized = value(raw.value);
+    if (urlFields.has(field)) {
+      const urls = (input2) => {
+        const normalize = (part) => {
+          const parsed = publicUrl(part);
+          if (parsed === null)
+            throw new Error("Invalid article metadata URL");
+          return parsed;
+        };
+        return typeof input2 === "string" ? normalize(input2) : input2.map(normalize);
+      };
+      observed = urls(observed);
+      normalized = urls(normalized);
+    }
+    const temporal = raw.datePrecision === undefined ? {} : dateFields.has(field) && typeof observed === "string" ? dateValue(observed) : (() => {
+      throw new Error("Invalid article metadata date");
+    })();
+    if (raw.datePrecision !== undefined && (raw.datePrecision !== temporal.datePrecision || raw.timezone !== temporal.timezone))
+      throw new Error("Invalid article metadata date precision");
+    return { field, observed, value: normalized, source: raw.source, locator: text(raw.locator, 512), rule: text(raw.rule, 256), selected: raw.selected, ...temporal };
+  });
+  if (input.warnings.length > warningKinds.size || input.warnings.some((warning) => !warningKinds.has(warning)))
+    throw new Error("Invalid article metadata warnings");
+  return { schemaVersion: 1, extractorVersion: "wordcell-metadata-v1", claims, warnings: [...input.warnings] };
+}
+var fields = {
+  "og:title": "title",
+  "twitter:title": "title",
+  title: "title",
+  citation_title: "title",
+  "dc.title": "title",
+  description: "description",
+  "og:description": "description",
+  "twitter:description": "description",
+  "dc.description": "description",
+  author: "authors",
+  "article:author": "authors",
+  citation_author: "authors",
+  "dc.creator": "authors",
+  "article:published_time": "published",
+  datepublished: "published",
+  citation_publication_date: "published",
+  "dc.date": "published",
+  "article:modified_time": "modified",
+  datemodified: "modified",
+  "last-modified": "modified",
+  "og:url": "canonical",
+  "twitter:url": "canonical",
+  "og:image": "image",
+  "og:image:url": "image",
+  "twitter:image": "image",
+  "twitter:image:src": "image",
+  "og:site_name": "site",
+  publisher: "publisher",
+  "dc.publisher": "publisher",
+  citation_journal_title: "publisher",
+  "og:locale": "language",
+  language: "language",
+  "dc.language": "language",
+  "og:type": "type",
+  "twitter:card": "card",
+  "article:tag": "tags",
+  keywords: "tags",
+  news_keywords: "tags",
+  citation_keywords: "tags",
+  citation_doi: "doi",
+  "dc.identifier": "identifier",
+  citation_pdf_url: "alternate"
+};
+async function extractArticleMetadata(html, base, fallback = {}) {
+  const claims = [];
+  const warnings = new Set;
+  let totalBytes = 0, title = "", script = "", scriptIndex = 0, activeScript = false, jsonBytes = 0;
+  const add = (field, raw, source, locator, decode = false, evidenceRule) => {
+    if (claims.length >= metadataLimits.claims) {
+      warnings.add("claim-limit");
+      return;
+    }
+    let values = Array.isArray(raw) ? raw : [raw];
+    if (values.length > 32) {
+      warnings.add("value-limit");
+      values = values.slice(0, 32);
+    }
+    const strings = [];
+    for (const value2 of values) {
+      if (typeof value2 !== "string")
+        continue;
+      if (value2.length > metadataLimits.value) {
+        warnings.add("value-limit");
+        continue;
+      }
+      const decoded = decode ? decodeHTML(value2) : value2;
+      const cleaned = cleanText(urlFields.has(field) ? publicUrl(decoded, base) ?? "" : decoded);
+      if (cleaned)
+        strings.push(cleaned);
+    }
+    if (!strings.length)
+      return;
+    const observed = Array.isArray(raw) ? strings : strings[0];
+    let value = observed;
+    if (urlFields.has(field)) {
+      const urls = strings.map((part) => publicUrl(part, base)).filter((part) => part !== null);
+      if (!urls.length)
+        return;
+      value = Array.isArray(raw) ? urls : urls[0];
+    }
+    const temporal = dateFields.has(field) && typeof observed === "string" ? dateValue(observed) : {};
+    const claim = { field, observed, value, source, locator, rule: `trim-whitespace-url-query-redaction${evidenceRule === undefined ? "" : `:${evidenceRule}`}`, selected: false, ...temporal };
+    const bytes = Buffer.byteLength(JSON.stringify(claim));
+    if (totalBytes + bytes > metadataLimits.totalBytes / 2) {
+      warnings.add("claim-limit");
+      return;
+    }
+    totalBytes += bytes;
+    claims.push(claim);
+  };
+  const parseLd = (raw, index) => {
+    if (!raw.trim())
+      return;
+    if (Buffer.byteLength(raw) > metadataLimits.jsonBytes || (jsonBytes += Buffer.byteLength(raw)) > metadataLimits.jsonBytes * 4) {
+      warnings.add("json-limit");
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      warnings.add("json-invalid");
+      return;
+    }
+    let nodes = 0;
+    const stack = [{ value: parsed, depth: 0 }];
+    while (stack.length) {
+      const node = stack.pop();
+      if (++nodes > metadataLimits.jsonNodes || node.depth > metadataLimits.jsonDepth) {
+        warnings.add("json-limit");
+        return;
+      }
+      const children = Array.isArray(node.value) ? node.value : record(node.value) ? Object.values(node.value) : [];
+      if (children.length + nodes + stack.length > metadataLimits.jsonNodes) {
+        warnings.add("json-limit");
+        return;
+      }
+      for (const child of children)
+        stack.push({ value: child, depth: node.depth + 1 });
+    }
+    const items = Array.isArray(parsed) ? parsed.map((value, i) => ({ value, path: `$[${i}]` })) : [{ value: parsed, path: "$" }];
+    for (let cursor = 0;cursor < items.length && cursor < metadataLimits.jsonNodes; cursor++) {
+      const item = items[cursor];
+      if (!record(item.value))
+        continue;
+      const object = item.value;
+      if (Array.isArray(object["@graph"]))
+        items.push(...object["@graph"].map((value, i) => ({ value, path: `${item.path}.@graph[${i}]` })));
+      const types = Array.isArray(object["@type"]) ? object["@type"] : [object["@type"]];
+      const entityTypes = types.flatMap((type) => {
+        const match = typeof type === "string" ? /^(?:(?:https?:\/\/)?schema\.org\/)?(Article|NewsArticle|BlogPosting|ScholarlyArticle|TechArticle|Report|WebPage|VideoObject|AudioObject|PodcastEpisode)$/.exec(type) : null;
+        return match?.[1] === undefined ? [] : [match[1]];
+      });
+      const entityType = entityTypes.find((type) => type !== "WebPage") ?? entityTypes[0];
+      if (entityType === undefined)
+        continue;
+      const names = (v) => Array.isArray(v) ? v.slice(0, 32).map((entry) => record(entry) ? entry.name : entry) : record(v) ? v.name : v;
+      const props = { headline: "title", name: "title", description: "description", author: "authors", creator: "authors", datePublished: "published", dateModified: "modified", inLanguage: "language", publisher: "publisher", keywords: "tags", image: "image", thumbnailUrl: "image", url: "canonical", mainEntityOfPage: "canonical", duration: "duration", episodeNumber: "episode", identifier: "identifier" };
+      for (const [key, field] of Object.entries(props)) {
+        let value = object[key];
+        if (value === undefined)
+          continue;
+        if (["author", "creator", "publisher"].includes(key))
+          value = names(value);
+        if (key === "image")
+          value = Array.isArray(value) ? value.map((v) => record(v) ? v.url ?? v.contentUrl : v) : record(value) ? value.url ?? value.contentUrl : value;
+        if (key === "mainEntityOfPage" && record(value))
+          value = value["@id"] ?? value.url;
+        if (key === "episodeNumber" && typeof value === "number" && Number.isFinite(value))
+          value = String(value);
+        add(field, value, "json-ld", `script[${index}]${item.path}.${key}`, false, `jsonld-type=${entityType}`);
+      }
+    }
+  };
+  let input = html;
+  if (Buffer.byteLength(input) > metadataLimits.htmlBytes) {
+    input = Buffer.from(input).subarray(0, metadataLimits.htmlBytes).toString("utf8");
+    warnings.add("input-limit");
+  }
+  await new HTMLRewriter().on("html", { element(element) {
+    add("language", element.getAttribute("lang"), "html-language", "html@lang", true);
+  } }).on("title", { text(chunk) {
+    if (title.length <= metadataLimits.value)
+      title += chunk.text;
+  } }).on("meta", { element(element) {
+    const attribute = element.getAttribute("property") ? "property" : "name";
+    const key = decodeHTML(element.getAttribute(attribute) ?? "").toLowerCase();
+    if (!/^[a-z][a-z0-9:._-]{0,100}$/.test(key) || credentialName.test(key))
+      return;
+    const field = Object.hasOwn(fields, key) ? fields[key] : `meta:${key.replaceAll(".", "_")}`;
+    add(field, element.getAttribute("content"), "html-meta", `meta[${attribute}=${key}]@content`, true);
+  } }).on("link", { element(element) {
+    const rel = (element.getAttribute("rel") ?? "").toLowerCase().split(/\s+/);
+    const field = rel.includes("canonical") ? "canonical" : rel.includes("alternate") ? "alternate" : null;
+    if (field)
+      add(field, element.getAttribute("href"), "html-link", `link[rel=${field}]@href`, true);
+  } }).on("script", { element(element) {
+    activeScript = (element.getAttribute("type") ?? "").toLowerCase().trim() === "application/ld+json";
+    script = "";
+    if (activeScript) {
+      const index = scriptIndex++;
+      if (index >= 64) {
+        activeScript = false;
+        warnings.add("json-limit");
+        return;
+      }
+      element.onEndTag(() => {
+        parseLd(script, index);
+        activeScript = false;
+      });
+    }
+  }, text(chunk) {
+    if (activeScript && script.length <= metadataLimits.jsonBytes)
+      script += chunk.text;
+  } }).transform(new Response(input)).text();
+  if (activeScript)
+    warnings.add("json-invalid");
+  add("title", title, "html-title", "title", true);
+  for (const [key, field] of Object.entries({ title: "title", author: "authors", published: "published", description: "description" }))
+    add(field, fallback[key], "extractor", `defuddle.${key}`);
+  return parseArticleMetadata({ schemaVersion: 1, extractorVersion: "wordcell-metadata-v1", claims: select(claims), warnings: [...warnings] });
+}
+
+export { parseArticleMetadata, extractArticleMetadata };
diff --git a/dist/index-hacpnaew.js b/dist/index-fd8j527z.js
similarity index 99%
rename from dist/index-hacpnaew.js
rename to dist/index-fd8j527z.js
index 15235826..2c7886f7 100644
--- a/dist/index-hacpnaew.js
+++ b/dist/index-fd8j527z.js
@@ -1,7 +1,7 @@
 // @bun
 import {
   sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   assertSafeNetworkUrl,
   decodeBytes,
diff --git a/dist/index-mxxxytys.js b/dist/index-g63d3937.js
similarity index 99%
rename from dist/index-mxxxytys.js
rename to dist/index-g63d3937.js
index 90c5d0de..cbc11cec 100644
--- a/dist/index-mxxxytys.js
+++ b/dist/index-g63d3937.js
@@ -1,4 +1,7 @@
 // @bun
+import {
+  parseArticleMetadata
+} from "./index-e2wstc7t.js";
 import {
   sanitizeTerminalText
 } from "./index-1xxnjn0d.js";
@@ -1070,6 +1073,7 @@ function normalizeManifest(input, hasSourceHtml, document) {
   return {
     schemaVersion: CAPTURE_MANIFEST_SCHEMA_VERSION,
     document,
+    ...input.metadata === undefined ? {} : { metadata: parseArticleMetadata(input.metadata, redactSensitiveText) },
     sourceUrl: sanitizeArtifactUrl(input.sourceUrl),
     canonicalUrl: sanitizeArtifactUrl(input.canonicalUrl),
     capturedAt: new Date(capturedAtTime).toISOString(),
diff --git a/dist/index-k86wepd8.js b/dist/index-h2w7syy2.js
similarity index 99%
rename from dist/index-k86wepd8.js
rename to dist/index-h2w7syy2.js
index a206889f..1c7709e0 100644
--- a/dist/index-k86wepd8.js
+++ b/dist/index-h2w7syy2.js
@@ -6,7 +6,10 @@ import {
   resolveRemote,
   rewriteContentWithStatus,
   scanImageSources
-} from "./index-cd75vky9.js";
+} from "./index-jbtyp6q5.js";
+import {
+  parseArticleMetadata
+} from "./index-e2wstc7t.js";
 import {
   FetchFailure,
   safeFetch
@@ -812,6 +815,7 @@ async function extractPage(acquisition, scope, timeoutMs = 30000) {
         article = {
           content: retainDefuddleMedia(restoredContent, response, acquisition.finalUrl),
           title: boundedMetadata(response.title, articleMetadataLimits.title) ?? boundedMetadata(acquisition.browserTitle, articleMetadataLimits.title),
+          ...response.metadata === undefined ? {} : { metadata: parseArticleMetadata(response.metadata) },
           author: boundedMetadata(response.author, articleMetadataLimits.author),
           published: boundedMetadata(response.published, articleMetadataLimits.published),
           description
diff --git a/dist/index-cd75vky9.js b/dist/index-jbtyp6q5.js
similarity index 100%
rename from dist/index-cd75vky9.js
rename to dist/index-jbtyp6q5.js
diff --git a/dist/index-6c8xhred.js b/dist/index-k9yzc4vn.js
similarity index 100%
rename from dist/index-6c8xhred.js
rename to dist/index-k9yzc4vn.js
diff --git a/dist/index-m9p2a4mj.js b/dist/index-my50xsa3.js
similarity index 83%
rename from dist/index-m9p2a4mj.js
rename to dist/index-my50xsa3.js
index a0e74b5d..b40caee5 100644
--- a/dist/index-m9p2a4mj.js
+++ b/dist/index-my50xsa3.js
@@ -2,7 +2,7 @@
 import {
   countWords,
   sniffImage
-} from "./index-k86wepd8.js";
+} from "./index-h2w7syy2.js";
 import {
   renderFailure,
   sentence,
@@ -10,11 +10,11 @@ import {
   stderrStyle,
   terminalOutput,
   yamlString
-} from "./index-cd75vky9.js";
+} from "./index-jbtyp6q5.js";
 import {
   redactSensitiveText,
   sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   safeFetch
 } from "./index-e5fbsywq.js";
@@ -26,6 +26,16 @@ import {
   sanitizeTerminalText
 } from "./index-1xxnjn0d.js";
 
+// src/pdf/errors.ts
+class PdfCaptureError extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "PdfCaptureError";
+  }
+}
+
 // src/pdf/args.ts
 var pdfUsage = `wordcell pdf \u2014 save a local or public remote PDF as an auditable Markdown bundle
 
@@ -521,7 +531,7 @@ function layoutBlocks(pages) {
   const repeatedMargins = repeatedMarginLines(pages, linesByPage);
   const output = [];
   for (const page of pages) {
-    const lines = (linesByPage.get(page.page) ?? []).filter((line) => !repeatedMargins.has(normalizedMarginText(line.text)));
+    const lines = (linesByPage.get(page.page) ?? []).filter((line) => !(line.top <= page.height * 0.06 || line.top + line.height >= page.height * 0.94) || !repeatedMargins.has(normalizedMarginText(line.text)));
     const steps = lines.slice(1).map((line, index) => Math.max(0, line.top - (lines[index]?.top ?? line.top)));
     const normalStep = median(steps.filter((step) => step > 0), Math.max(1, bodySize * 1.4));
     const events = [
@@ -548,7 +558,7 @@ function layoutBlocks(pages) {
       const { line, index } = event;
       const previous = lines[index - 1];
       const gapBefore = previous === undefined ? Number.POSITIVE_INFINITY : line.top - previous.top;
-      const fontHeading = line.fontSize > bodySize * 1.08;
+      const fontHeading = line.fontSize > bodySize * 1.08 && !/[=\u222B\u2211\u221A\u2070\u00B9\u00B2\u00B3\u2074\u2075\u2076\u2077\u2078\u2079]/u.test(line.text);
       const boldHeading = line.boldRatio >= 0.78 && line.text.length <= 180 && gapBefore >= normalStep * 1.45;
       if (line.text.length <= 240 && (fontHeading || boldHeading)) {
         flushParagraph();
@@ -572,7 +582,7 @@ function layoutBlocks(pages) {
     }
     flushParagraph();
   }
-  return output.filter((block) => block.kind === "image" || block.text.trim() !== "");
+  return output.filter((block) => block.kind === "image" || block.kind === "table" || block.text.trim() !== "");
 }
 function parsePdfImageInterpretations(value) {
   if (!Array.isArray(value))
@@ -673,6 +683,160 @@ function parsePdfImageInterpretations(value) {
   }
   return output;
 }
+function analyzePdfLayout(pages) {
+  const issues = [];
+  const blocks = [];
+  const marginLines = new Map(pages.filter((page) => page.text.length <= 4000).map((page) => [page.page, pageLines(page)]));
+  const margins = repeatedMarginLines(pages, marginLines);
+  for (const originalInput of pages) {
+    const original = { ...originalInput, text: originalInput.text.filter((fragment) => !(fragment.top <= originalInput.height * 0.06 || fragment.top + fragment.height >= originalInput.height * 0.94) || !margins.has(normalizedMarginText(fragment.text))) };
+    const warn = (code) => {
+      if (!issues.some((issue) => issue.page === original.page && issue.code === code))
+        issues.push({ page: original.page, code });
+    };
+    if (original.text.length > 4000) {
+      warn("reading-order-uncertain");
+      blocks.push(...layoutBlocks([original]));
+      continue;
+    }
+    if (original.text.some((fragment) => /[\u222B\u2211\u221A]/u.test(fragment.text)))
+      warn("math-structure-uncertain");
+    const text = [...original.text].sort((a, b) => a.top - b.top || a.left - b.left);
+    const consumed = new Set;
+    const replacements = new Map;
+    const superscripts = { "0": "\u2070", "1": "\xB9", "2": "\xB2", "3": "\xB3", "4": "\u2074", "5": "\u2075", "6": "\u2076", "7": "\u2077", "8": "\u2078", "9": "\u2079", "+": "\u207A", "-": "\u207B", "=": "\u207C", "(": "\u207D", ")": "\u207E", n: "\u207F", i: "\u2071" };
+    for (const small of text) {
+      const bases = text.filter((base2) => base2 !== small && base2.fontSize >= small.fontSize * 1.3 && small.top < base2.top && small.top + small.height > base2.top - base2.height * 0.25 && Math.abs(small.left - (base2.left + base2.width)) < base2.fontSize * 0.6);
+      if (bases.length === 0)
+        continue;
+      const base = bases[0];
+      const glyphs = [...small.text.trim()];
+      if (bases.length === 1 && glyphs.length > 0 && glyphs.length <= 8 && glyphs.every((glyph) => superscripts[glyph] !== undefined) && !replacements.has(base)) {
+        replacements.set(base, { ...base, text: base.text + glyphs.map((glyph) => superscripts[glyph]).join(""), width: small.left + small.width - base.left });
+        consumed.add(small);
+      } else
+        warn("math-structure-uncertain");
+    }
+    const fragments = text.filter((fragment) => !consumed.has(fragment)).map((fragment) => replacements.get(fragment) ?? fragment);
+    const page = { ...original, text: fragments };
+    const rows = [];
+    for (const fragment of fragments) {
+      const row = rows.at(-1);
+      if (row === undefined || Math.abs(fragment.top - row[0].top) > Math.max(2, fragment.height * 0.2))
+        rows.push([fragment]);
+      else
+        row.push(fragment);
+    }
+    const cellRows = rows.map((row) => {
+      const groups = [];
+      for (const fragment of [...row].sort((a, b) => a.left - b.left)) {
+        const prior = groups.at(-1), last = prior?.at(-1);
+        if (last === undefined || fragment.left - (last.left + last.width) > Math.max(12, fragment.fontSize * 1.5))
+          groups.push([fragment]);
+        else
+          prior.push(fragment);
+      }
+      return groups;
+    });
+    const tables = [];
+    for (let index = 0;index < cellRows.length; index++) {
+      const first = cellRows[index];
+      if (first.length < 2 || first.length > 12)
+        continue;
+      const group = [first];
+      let next = index + 1;
+      for (;next < cellRows.length; next++) {
+        const candidate = cellRows[next];
+        if (candidate.length !== first.length || candidate.some((cell, column) => Math.abs(cell[0].left - first[column][0].left) > 4))
+          break;
+        if (candidate[0][0].top - group.at(-1)[0][0].top > Math.max(40, candidate[0][0].height * 3))
+          break;
+        group.push(candidate);
+      }
+      const cells = group.map((row) => row.map((cell) => joinFragments(cell)));
+      const header = first.every((cell) => cell.every((fragment) => fragment.bold));
+      const numeric = cells.slice(1).some((row) => row.slice(1).some((cell) => /^[-+\d$\u20AC\u00A3]/u.test(cell.trim())));
+      const compact = cells.every((row) => row.every((cell) => cell.length <= 100));
+      if (group.length >= 3 && compact && header && numeric) {
+        const members = group.flat(2);
+        tables.push({ top: Math.min(...members.map((fragment) => fragment.top)), bottom: Math.max(...members.map((fragment) => fragment.top + fragment.height)), block: { kind: "table", page: page.page, rows: cells }, fragments: members });
+        index = next - 1;
+      } else if (group.length >= 3 && first.length >= 3)
+        warn("table-structure-uncertain");
+    }
+    const tableFragments = new Set(tables.flatMap((table) => table.fragments));
+    const remaining = fragments.filter((fragment) => !tableFragments.has(fragment));
+    const emitBand = (band, images) => {
+      if (band.length === 0 && images.length === 0)
+        return;
+      const candidates = new Set;
+      for (const row of cellRows) {
+        for (let i = 1;i < row.length; i++) {
+          const left = row[i - 1].at(-1), right = row[i][0];
+          const gap = right.left - (left.left + left.width);
+          if (gap >= Math.max(page.width * 0.025, left.fontSize * 1.5))
+            candidates.add(Math.round((left.left + left.width + right.left) / 2));
+        }
+      }
+      const valid = [...candidates].filter((gutter) => {
+        const left = band.filter((fragment) => fragment.left + fragment.width <= gutter);
+        const right = band.filter((fragment) => fragment.left >= gutter);
+        if (left.length + right.length !== band.length || left.length < 3 || right.length < 3)
+          return false;
+        if (left.filter((fragment) => fragment.width > page.width * 0.18).length < 2 || right.filter((fragment) => fragment.width > page.width * 0.18).length < 2)
+          return false;
+        const overlap = Math.min(Math.max(...left.map((fragment) => fragment.top)), Math.max(...right.map((fragment) => fragment.top))) - Math.max(Math.min(...left.map((fragment) => fragment.top)), Math.min(...right.map((fragment) => fragment.top)));
+        return overlap > Math.max(...band.map((fragment) => fragment.height)) * 1.5;
+      });
+      if (valid.length > 0) {
+        const gutter = valid[Math.floor(valid.length / 2)];
+        if (images.some((image) => image.left < gutter && image.left + image.width > gutter)) {
+          warn("reading-order-uncertain");
+          blocks.push(...layoutBlocks([{ ...page, text: band, images }]));
+          return;
+        }
+        for (const left of [true, false])
+          blocks.push(...layoutBlocks([{ ...page, text: band.filter((fragment) => left ? fragment.left + fragment.width <= gutter : fragment.left >= gutter), images: images.filter((image) => left ? image.left + image.width <= gutter : image.left >= gutter) }]));
+      } else {
+        if (band.length >= 6 && cellRows.filter((row) => row.length >= 2 && row.some((cell) => band.includes(cell[0]))).length >= 3)
+          warn("reading-order-uncertain");
+        blocks.push(...layoutBlocks([{ ...page, text: band, images }]));
+      }
+    };
+    const bodyFont = weightedBodyFontSize(pageLines(page));
+    const gutterVotes = new Map;
+    for (const row of cellRows)
+      for (let i = 1;i < row.length; i++) {
+        const left = row[i - 1].at(-1), right = row[i][0];
+        if (right.left - (left.left + left.width) < Math.max(12, left.fontSize * 1.5))
+          continue;
+        const gutter = Math.round((left.left + left.width + right.left) / 20) * 10;
+        gutterVotes.set(gutter, (gutterVotes.get(gutter) ?? 0) + 1);
+      }
+    const repeatedGutters = [...gutterVotes].filter(([, votes]) => votes >= 3).map(([gutter]) => gutter);
+    const spans = remaining.filter((fragment) => fragment.width > page.width * 0.65 || fragment.fontSize > bodyFont * 1.08 && repeatedGutters.some((gutter) => fragment.left < gutter && fragment.left + fragment.width > gutter));
+    const boundaries = [...tables.map((table) => ({ top: table.top, bottom: table.bottom, table, span: null })), ...spans.map((span) => ({ top: span.top, bottom: span.top + span.height, table: null, span }))].sort((a, b) => a.top - b.top);
+    const emitted = new Set, emittedImages = new Set;
+    for (const boundary of boundaries) {
+      const band = remaining.filter((fragment) => !emitted.has(fragment) && fragment !== boundary.span && fragment.top < boundary.top);
+      const images = page.images.filter((image) => !emittedImages.has(image) && image.top < boundary.top);
+      emitBand(band, images);
+      for (const fragment of band)
+        emitted.add(fragment);
+      for (const image of images)
+        emittedImages.add(image);
+      if (boundary.table !== null)
+        blocks.push(boundary.table.block);
+      if (boundary.span !== null) {
+        const span = boundary.span;
+        blocks.push(span.fontSize > bodyFont * 1.08 ? { kind: "heading", page: page.page, level: 2, text: span.text } : { kind: "paragraph", page: page.page, text: span.text });
+        emitted.add(span);
+      }
+    }
+    emitBand(remaining.filter((fragment) => !emitted.has(fragment)), page.images.filter((image) => !emittedImages.has(image)));
+  }
+  return { blocks, issues };
+}
 
 // src/pdf/tools.ts
 import { spawn } from "child_process";
@@ -696,7 +860,7 @@ async function readBoundedStream(stream, maxBytes) {
     else
       throw new Error("PDF tool returned an unsupported output chunk");
     if (!bytes.append(chunk))
-      throw new Error(`PDF tool output exceeded ${maxBytes} bytes`);
+      throw new PdfCaptureError("limit-exceeded", `PDF tool output exceeded ${maxBytes} bytes`);
   }
   return new TextDecoder().decode(bytes.toUint8Array());
 }
@@ -704,7 +868,9 @@ var runPdfToolCommand = async (specification) => {
   const executable = specification.command[0];
   if (executable === undefined)
     throw new Error("PDF tool command is empty");
-  const useProcessGroup = process.platform !== "win32";
+  if (specification.processGroup !== undefined && !["new", "inherit"].includes(specification.processGroup))
+    throw new PdfCaptureError("invalid-input", "Invalid PDF process group policy");
+  const useProcessGroup = process.platform !== "win32" && specification.processGroup !== "inherit";
   const child = spawn(executable, specification.command.slice(1), {
     cwd: specification.cwd,
     detached: useProcessGroup,
@@ -718,7 +884,7 @@ var runPdfToolCommand = async (specification) => {
     windowsHide: true
   });
   const exited = new Promise((resolveExit, rejectExit) => {
-    child.once("error", rejectExit);
+    child.once("error", (error) => rejectExit(error.code === "ENOENT" ? new PdfCaptureError("tool-unavailable", "PDF tool executable is unavailable", { cause: error }) : error));
     child.once("close", (code) => resolveExit(code ?? 1));
   });
   const signalProcessTree = (signal) => {
@@ -742,7 +908,7 @@ var runPdfToolCommand = async (specification) => {
     forceKillTimer = setTimeout(() => signalProcessTree("SIGKILL"), 1000);
   };
   const timer = setTimeout(() => {
-    requestStop(new Error(`PDF tool timed out after ${specification.timeoutMs}ms`));
+    requestStop(new PdfCaptureError("timeout", `PDF tool timed out after ${specification.timeoutMs}ms`));
   }, specification.timeoutMs);
   try {
     const [stdout, stderr, exitCode] = await Promise.all([
@@ -791,10 +957,10 @@ function resolvePdfTools(dependencies = {}) {
   const pdftohtml = dependencies.tools?.pdftohtml ?? discoverExecutable("pdftohtml", dependencies);
   const tesseract = dependencies.tools?.tesseract === undefined ? discoverExecutable("tesseract", dependencies) : dependencies.tools.tesseract;
   if (pdfinfo === null) {
-    throw new Error("pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
   }
   if (pdftohtml === null) {
-    throw new Error("pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
   }
   return { pdfinfo, pdftohtml, tesseract };
 }
@@ -828,7 +994,7 @@ var pdfCaptureDefaults = {
 function positiveBound(value, fallback, maximum, label) {
   const selected = value ?? fallback;
   if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
-    throw new Error(`${label} must be an integer from 1 through ${maximum}`);
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
   }
   return selected;
 }
@@ -841,10 +1007,10 @@ function prepareWorkspace(path) {
   if (existsSync2(absolute)) {
     const stats = lstatSync(absolute);
     if (!stats.isDirectory() || stats.isSymbolicLink()) {
-      throw new Error("PDF inspection workspace must be a real directory");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be a real directory");
     }
     if (readdirSync(absolute).length !== 0) {
-      throw new Error("PDF inspection workspace must be empty");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be empty");
     }
   } else {
     mkdirSync(absolute, { recursive: false, mode: 448 });
@@ -857,17 +1023,17 @@ function sourceIdentity(path, maxPdfBytes) {
   const canonical = realpathSync(resolve(path));
   const stats = statSync(canonical);
   if (!stats.isFile())
-    throw new Error("PDF input must be a regular file");
+    throw new PdfCaptureError("invalid-input", "PDF input must be a regular file");
   if (stats.size < 5)
-    throw new Error("PDF input is too small to contain a PDF header");
+    throw new PdfCaptureError("invalid-input", "PDF input is too small to contain a PDF header");
   if (stats.size > maxPdfBytes)
-    throw new Error(`PDF input exceeds the ${maxPdfBytes}-byte limit`);
+    throw new PdfCaptureError("limit-exceeded", `PDF input exceeds the ${maxPdfBytes}-byte limit`);
   const descriptor = openSync(canonical, "r");
   try {
     const signature = Buffer.alloc(5);
     const count = readSync(descriptor, signature, 0, signature.length, 0);
     if (count !== signature.length || signature.toString("ascii") !== "%PDF-") {
-      throw new Error("PDF input does not have a valid PDF signature");
+      throw new PdfCaptureError("invalid-input", "PDF input does not have a valid PDF signature");
     }
   } finally {
     closeSync(descriptor);
@@ -923,18 +1089,18 @@ function safeGeneratedImage(image, workspace, index, limits) {
 function generatedTreeSize(workspace, maximumFiles, maximumBytes) {
   const entries = readdirSync(workspace, { withFileTypes: true });
   if (entries.length > maximumFiles) {
-    throw new Error(`PDF extraction created more than ${maximumFiles} files`);
+    throw new PdfCaptureError("limit-exceeded", `PDF extraction created more than ${maximumFiles} files`);
   }
   let totalBytes = 0;
   for (const entry of entries) {
     const path = join2(workspace, entry.name);
     const stats = lstatSync(path);
     if (!entry.isFile() || stats.isSymbolicLink()) {
-      throw new Error("PDF extraction created an unexpected non-file output");
+      throw new PdfCaptureError("extraction-failed", "PDF extraction created an unexpected non-file output");
     }
     totalBytes += stats.size;
     if (totalBytes > maximumBytes) {
-      throw new Error(`PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
+      throw new PdfCaptureError("limit-exceeded", `PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
     }
   }
 }
@@ -957,7 +1123,8 @@ async function inspectPdf(options, dependencies = {}) {
     cwd: workspaceDirectory
   });
   if (info.exitCode !== 0) {
-    throw new Error("pdfinfo could not inspect the input PDF");
+    const encrypted = info.stderr.split(/\r?\n/u).some((line) => line.trim() === "Command Line Error: Incorrect password");
+    throw new PdfCaptureError(encrypted ? "encrypted" : "extraction-failed", "pdfinfo could not inspect the input PDF");
   }
   const metadata = parsePdfInfo(info.stdout);
   const processedPageLimit = Math.min(metadata.pageCount, maxPages);
@@ -982,12 +1149,12 @@ async function inspectPdf(options, dependencies = {}) {
     cwd: workspaceDirectory
   });
   if (extracted.exitCode !== 0) {
-    throw new Error("pdftohtml could not extract the input PDF");
+    throw new PdfCaptureError("extraction-failed", "pdftohtml could not extract the input PDF");
   }
   generatedTreeSize(workspaceDirectory, 10002, Math.min(Number.MAX_SAFE_INTEGER, 8 * 1024 ** 3 + pdfCaptureDefaults.maxLayoutBytes));
   const layoutStats = statSync(layoutPath);
   if (!layoutStats.isFile() || layoutStats.size > pdfCaptureDefaults.maxLayoutBytes) {
-    throw new Error(`Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
+    throw new PdfCaptureError("limit-exceeded", `Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
   }
   const parsed = parsePopplerXml(readFileSync(layoutPath, "utf8"), {
     maxPages: processedPageLimit,
@@ -1214,8 +1381,14 @@ function persistPdfCapture(input) {
       copyFileSync(image.sourcePath, destination);
       chmodSync2(destination, 420);
     }
-    writeFileSync(join3(stagingDirectory, `${slug}.md`), `${redactSensitiveText(input.markdown).trimEnd()}
-`, { encoding: "utf8", flag: "wx", mode: 420 });
+    const markdownBytes = `${redactSensitiveText(input.markdown).trimEnd()}
+`;
+    const markdownDescriptor = { path: `${slug}.md`, bytes: Buffer.byteLength(markdownBytes), sha256: createHash2("sha256").update(markdownBytes).digest("hex") };
+    if (input.manifest.markdown !== undefined && (input.manifest.markdown.path !== markdownDescriptor.path || input.manifest.markdown.bytes !== markdownDescriptor.bytes || input.manifest.markdown.sha256 !== markdownDescriptor.sha256)) {
+      throw new Error("PDF Markdown does not match its manifest provenance");
+    }
+    const manifest = { ...input.manifest, markdown: markdownDescriptor };
+    writeFileSync(join3(stagingDirectory, `${slug}.md`), markdownBytes, { encoding: "utf8", flag: "wx", mode: 420 });
     if (input.manifest.annotations === null) {
       if (input.annotationsJson !== undefined) {
         throw new Error("PDF annotations were supplied without manifest provenance");
@@ -1239,7 +1412,7 @@ function persistPdfCapture(input) {
       }
       writeFileSync(join3(stagingDirectory, PDF_CAPTURE_ANNOTATIONS_FILENAME), annotationsJson, { encoding: "utf8", flag: "wx", mode: 420 });
     }
-    writeFileSync(join3(stagingDirectory, PDF_CAPTURE_MANIFEST_FILENAME), `${JSON.stringify(input.manifest, null, 2)}
+    writeFileSync(join3(stagingDirectory, PDF_CAPTURE_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}
 `, { encoding: "utf8", flag: "wx", mode: 420 });
     assertStagingTreeSafe(stagingDirectory);
     if (existsSync3(targetDirectory) !== (expectedIdentity !== null)) {
@@ -1297,7 +1470,7 @@ function pdfMarkdownFilename(slug) {
 
 // src/pdf/markdown.ts
 function escapeInline(value) {
-  return sanitizeTerminalText(value).replace(/\\/gu, "\\\\").replace(/([`*_[\]{}<>#])/gu, "\\$1").replace(/\s+/gu, " ").trim();
+  return sanitizeTerminalText(value).replace(/\\/gu, "\\\\").replace(/([`*_[\]{}<>#|])/gu, "\\$1").replace(/\s+/gu, " ").trim();
 }
 function metadataLine(metadata) {
   if (metadata === null)
@@ -1347,6 +1520,13 @@ function markdownContent(blocks, images) {
       lines.push(imageMarkdown(resolved), "");
       continue;
     }
+    if (block.kind === "table") {
+      textBlockCount += 1;
+      const rows = block.rows.map((row) => `| ${row.map((cell) => escapeInline(cell)).join(" | ")} |`);
+      if (rows.length > 0)
+        lines.push(rows[0], `| ${block.rows[0].map(() => "---").join(" | ")} |`, ...rows.slice(1), "");
+      continue;
+    }
     if (block.kind === "heading") {
       headingCount += 1;
       lines.push(`${"#".repeat(Math.max(2, Math.min(6, block.level)))} ${escapeInline(block.text)}`, "");
@@ -1662,13 +1842,16 @@ async function runPdfCapture(options, dependencies = {}) {
       });
     }
     const platforms = embeddedPlatforms(resolvedImages);
+    const layout = analyzePdfLayout(inspection.pages);
+    for (const issue of layout.issues)
+      warnings.push(`Page ${issue.page}: ${issue.code}; consult the retained source PDF.`);
     const status = warnings.length > 0 || unclassifiedImages > 0 || ocrWarningCount > 0 ? "partial" : "complete";
     const filenameTitle = inspection.originalFilename.replace(/\.pdf$/iu, "").trim();
     const requestedSlug = options.slug ?? inspection.metadata.title ?? filenameTitle;
     const slug = slugify(sanitizeTerminalText(requestedSlug));
     if (slug === "")
       throw new Error("could not derive a safe PDF capture slug; pass an explicit slug");
-    const blocks = layoutBlocks(inspection.pages);
+    const blocks = layout.blocks;
     const byId = new Map(resolvedImages.map((image) => [image.image.id, image]));
     const capturedAt = (dependencies.now ?? (() => new Date))().toISOString();
     const built = buildPdfMarkdown({
@@ -1701,6 +1884,8 @@ async function runPdfCapture(options, dependencies = {}) {
     const manifest = {
       schemaVersion: PDF_CAPTURE_MANIFEST_SCHEMA_VERSION,
       kind: "pdf",
+      quality: { schemaVersion: 1, issues: layout.issues },
+      markdown: { path: pdfMarkdownFilename(slug), bytes: Buffer.byteLength(built.markdown), sha256: createHash3("sha256").update(built.markdown).digest("hex") },
       capturedAt,
       status,
       source: {
@@ -1785,13 +1970,13 @@ function parseRemoteUrl(input) {
   try {
     url = new URL(input);
   } catch {
-    throw new Error("PDF URL is invalid");
+    throw new PdfCaptureError("invalid-input", "PDF URL is invalid");
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("PDF URL must use HTTP or HTTPS");
+    throw new PdfCaptureError("invalid-input", "PDF URL must use HTTP or HTTPS");
   }
   if (url.username !== "" || url.password !== "") {
-    throw new Error("PDF URL must not contain embedded credentials");
+    throw new PdfCaptureError("invalid-input", "PDF URL must not contain embedded credentials");
   }
   return url;
 }
@@ -1808,7 +1993,7 @@ function remoteFilename(url) {
 }
 function assertPdfSignature(bytes) {
   if (bytes.byteLength < 5 || new TextDecoder().decode(bytes.subarray(0, 5)) !== "%PDF-") {
-    throw new Error("remote PDF input does not have a valid PDF signature");
+    throw new PdfCaptureError("invalid-input", "remote PDF input does not have a valid PDF signature");
   }
 }
 async function preparePdfSource(input, options = {}, dependencies = {}) {
@@ -1961,7 +2146,7 @@ async function main(rawArguments = process.argv.slice(2), environment = process.
   } catch (error) {
     const message = safe(error instanceof Error ? error.message : String(error));
     if (arguments_.json)
-      output.stdout(terminalSafeJson({ ok: false, error: message }));
+      output.stdout(terminalSafeJson({ ok: false, error: message, code: error instanceof PdfCaptureError ? error.code : "unknown" }));
     else
       output.stderr(renderFailure(message, "wordcell doctor", stderrStyle(environment, output)));
     return 1;
@@ -1972,4 +2157,4 @@ async function main(rawArguments = process.argv.slice(2), environment = process.
 if (false)
   ;
 
-export { pdfUsage, parsePdfArguments, decodePopplerText, parsePopplerXml, parsePdfInfo, layoutBlocks, parsePdfImageInterpretations, runPdfToolCommand, resolvePdfTools, pdfCaptureDefaults, inspectPdf, PDF_CAPTURE_MANIFEST_SCHEMA_VERSION, PDF_CAPTURE_MANIFEST_FILENAME, PDF_CAPTURE_SOURCE_FILENAME, PDF_CAPTURE_ANNOTATIONS_FILENAME, pdfImageAssetPath, persistPdfCapture, pdfMarkdownFilename, buildPdfMarkdown, parseTesseractTsv, ocrPdfImage, runPdfCapture, pdfCaptureSummary, main };
+export { PdfCaptureError, pdfUsage, parsePdfArguments, decodePopplerText, parsePopplerXml, parsePdfInfo, layoutBlocks, parsePdfImageInterpretations, runPdfToolCommand, resolvePdfTools, pdfCaptureDefaults, inspectPdf, PDF_CAPTURE_MANIFEST_SCHEMA_VERSION, PDF_CAPTURE_MANIFEST_FILENAME, PDF_CAPTURE_SOURCE_FILENAME, PDF_CAPTURE_ANNOTATIONS_FILENAME, pdfImageAssetPath, persistPdfCapture, pdfMarkdownFilename, buildPdfMarkdown, parseTesseractTsv, ocrPdfImage, runPdfCapture, pdfCaptureSummary, main };
diff --git a/dist/index-ncwzmsge.js b/dist/index-nwdzhj1h.js
similarity index 99%
rename from dist/index-ncwzmsge.js
rename to dist/index-nwdzhj1h.js
index 9996c145..a55cb69e 100644
--- a/dist/index-ncwzmsge.js
+++ b/dist/index-nwdzhj1h.js
@@ -2,7 +2,7 @@
 import {
   classifyPlatformUrl,
   symbol
-} from "./index-cd75vky9.js";
+} from "./index-jbtyp6q5.js";
 import {
   filterCookieProviderResult,
   readCookieFile,
@@ -10,7 +10,7 @@ import {
 } from "./index-2gv8y733.js";
 import {
   sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
 import {
   startNetworkProxy
 } from "./index-w2zc0vwa.js";
diff --git a/dist/index-nd8v7r0z.js b/dist/index-sp43012q.js
similarity index 99%
rename from dist/index-nd8v7r0z.js
rename to dist/index-sp43012q.js
index 1331aefe..42cb37d2 100644
--- a/dist/index-nd8v7r0z.js
+++ b/dist/index-sp43012q.js
@@ -1,7 +1,7 @@
 // @bun
 import {
   isolatedAgentBrowserEnvironment
-} from "./index-ncwzmsge.js";
+} from "./index-nwdzhj1h.js";
 import {
   BoundedByteBuffer
 } from "./index-gh719d91.js";
diff --git a/dist/index-npg9z1a4.js b/dist/index-xn5q4kne.js
similarity index 99%
rename from dist/index-npg9z1a4.js
rename to dist/index-xn5q4kne.js
index eaed8ba6..af2e63a9 100644
--- a/dist/index-npg9z1a4.js
+++ b/dist/index-xn5q4kne.js
@@ -2,7 +2,10 @@
 import {
   CAPTURE_MANIFEST_FILENAME,
   CAPTURE_SOURCE_EVIDENCE_PATH
-} from "./index-mxxxytys.js";
+} from "./index-g63d3937.js";
+import {
+  parseArticleMetadata
+} from "./index-e2wstc7t.js";
 
 // src/clip/bundle-reader.ts
 import { createHash } from "crypto";
@@ -384,6 +387,7 @@ async function readCaptureBundle(path, options = {}) {
     }
     await assertBundleRoot(root);
     return Object.freeze({
+      ...manifest.metadata === undefined ? {} : { metadata: parseArticleMetadata(manifest.metadata) },
       root: root.path,
       schemaVersion,
       sourceUrl: manifest.sourceUrl,
diff --git a/dist/pdf.js b/dist/pdf.js
index a8428920..8a20b337 100644
--- a/dist/pdf.js
+++ b/dist/pdf.js
@@ -4,6 +4,7 @@ import {
   PDF_CAPTURE_MANIFEST_FILENAME,
   PDF_CAPTURE_MANIFEST_SCHEMA_VERSION,
   PDF_CAPTURE_SOURCE_FILENAME,
+  PdfCaptureError,
   buildPdfMarkdown,
   decodePopplerText,
   inspectPdf,
@@ -24,15 +25,442 @@ import {
   resolvePdfTools,
   runPdfCapture,
   runPdfToolCommand
-} from "./index-m9p2a4mj.js";
-import"./index-k86wepd8.js";
-import"./index-cd75vky9.js";
-import"./index-mxxxytys.js";
+} from "./index-my50xsa3.js";
+import"./index-h2w7syy2.js";
+import"./index-jbtyp6q5.js";
+import"./index-g63d3937.js";
+import"./index-e2wstc7t.js";
 import"./index-e5fbsywq.js";
 import"./index-gh719d91.js";
 import"./index-1xxnjn0d.js";
 import"./index-z1w83f81.js";
 
+// src/pdf/bundle-reader.ts
+import { createHash } from "crypto";
+import { constants as fsConstants } from "fs";
+import { lstat, open, opendir, realpath } from "fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "path";
+function boundedInteger(value, fallback, maximum, label) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
+  }
+  return selected;
+}
+function confinedRelativePath(value, label) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 4096 || value.includes("\x00")) {
+    throw new PdfCaptureError("integrity", `${label} must be a bounded non-empty path`);
+  }
+  if (isAbsolute(value) || value.includes("\\"))
+    throw new PdfCaptureError("integrity", `${label} must be a relative POSIX path`);
+  const segments = value.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new PdfCaptureError("integrity", `${label} contains an unsafe segment`);
+  }
+  return value;
+}
+
+class MissingCaptureAssetError extends PdfCaptureError {
+  constructor(message) {
+    super("integrity", message);
+  }
+}
+function isMissingPathError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function assertAssetVerificationDeadline(deadline) {
+  if (deadline !== undefined && performance.now() >= deadline) {
+    throw new PdfCaptureError("timeout", "capture asset verification exceeded its time budget");
+  }
+}
+function confined(root, relativePath, label) {
+  const path = resolve(root.path, relativePath);
+  const lexical = relative(root.path, path);
+  if (lexical === "" || lexical === ".." || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+    throw new PdfCaptureError("integrity", `${label} escapes the capture bundle`);
+  }
+  return path;
+}
+async function safeDirectory(pathInput) {
+  if (pathInput.trim() === "")
+    throw new PdfCaptureError("integrity", "capture bundle path is required");
+  const path = resolve(pathInput);
+  const canonical = await realpath(path);
+  if (canonical !== path)
+    throw new PdfCaptureError("integrity", "capture bundle path must be canonical and cannot traverse a symbolic link");
+  const stats = await lstat(path, { bigint: true });
+  if (!stats.isDirectory() || stats.isSymbolicLink())
+    throw new PdfCaptureError("integrity", "capture bundle path must be a real directory");
+  if (dirname(path) === path)
+    throw new PdfCaptureError("integrity", "refusing a filesystem root as a capture bundle");
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isDirectory() || opened.dev !== stats.dev || opened.ino !== stats.ino) {
+      throw new PdfCaptureError("integrity", "capture bundle root changed while it was opened");
+    }
+    return { path, handle, device: opened.dev, inode: opened.ino };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+async function assertBundleRoot(root, deadline) {
+  assertAssetVerificationDeadline(deadline);
+  const [opened, named, canonical] = await Promise.all([
+    root.handle.stat({ bigint: true }),
+    lstat(root.path, { bigint: true }),
+    realpath(root.path)
+  ]);
+  assertAssetVerificationDeadline(deadline);
+  if (canonical !== root.path || !opened.isDirectory() || !named.isDirectory() || named.isSymbolicLink() || opened.dev !== root.device || opened.ino !== root.inode || named.dev !== root.device || named.ino !== root.inode)
+    throw new PdfCaptureError("integrity", "capture bundle root changed during inspection");
+}
+async function assertAncestorChain(root, relativePath, label, deadline) {
+  await assertBundleRoot(root, deadline);
+  const segments = confinedRelativePath(relativePath, label).split("/");
+  let current = root.path;
+  for (const segment of segments.slice(0, -1)) {
+    current = resolve(current, segment);
+    assertAssetVerificationDeadline(deadline);
+    const metadata = await lstat(current, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a linked or non-directory ancestor`);
+    }
+    const canonical = await realpath(current);
+    assertAssetVerificationDeadline(deadline);
+    if (canonical !== current) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+    }
+  }
+  await assertBundleRoot(root, deadline);
+}
+async function withRegularFile(root, relativePath, maximumBytes, label, read, deadline, missingError) {
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  let before;
+  try {
+    before = await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (missingError !== undefined && isMissingPathError(error))
+      throw missingError;
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
+    throw new PdfCaptureError("integrity", `${label} must be a regular single-link file`);
+  }
+  if (before.size > BigInt(maximumBytes))
+    throw new PdfCaptureError("integrity", `${label} exceeds ${maximumBytes} bytes`);
+  const canonical = await realpath(path);
+  assertAssetVerificationDeadline(deadline);
+  if (canonical !== path)
+    throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    assertAssetVerificationDeadline(deadline);
+    const opened = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size)
+      throw new PdfCaptureError("integrity", `${label} changed while it was opened`);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const result = await read(handle, Number(opened.size));
+    assertAssetVerificationDeadline(deadline);
+    const after = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    const named = await lstat(path, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const finalCanonical = await realpath(path);
+    assertAssetVerificationDeadline(deadline);
+    if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.nlink !== 1n || named.dev !== before.dev || named.ino !== before.ino || named.size !== before.size || named.mtimeNs !== before.mtimeNs || named.nlink !== 1n || named.isSymbolicLink() || finalCanonical !== path)
+      throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+    return result;
+  } finally {
+    await handle.close();
+    assertAssetVerificationDeadline(deadline);
+  }
+}
+async function readRegularFile(root, relativePath, maximumBytes, label, deadline) {
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    const bytes = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+      if (result.bytesRead === 0)
+        throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      offset += result.bytesRead;
+    }
+    return bytes;
+  }, deadline);
+}
+async function hashRegularFile(root, relativePath, maximumBytes, deadline, label) {
+  assertAssetVerificationDeadline(deadline);
+  await assertBundleRoot(root, deadline);
+  assertAssetVerificationDeadline(deadline);
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  try {
+    await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (isMissingPathError(error)) {
+      await assertBundleRoot(root, deadline);
+      throw new MissingCaptureAssetError(`capture asset ${relativePath} is missing`);
+    }
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    assertAssetVerificationDeadline(deadline);
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(Math.min(1 * 1024 * 1024, Math.max(1, size)));
+    let offset = 0;
+    while (offset < size) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(chunk, 0, Math.min(chunk.byteLength, size - offset), offset);
+      assertAssetVerificationDeadline(deadline);
+      if (result.bytesRead === 0)
+        throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      hash.update(chunk.subarray(0, result.bytesRead));
+      offset += result.bytesRead;
+    }
+    assertAssetVerificationDeadline(deadline);
+    return { bytes: size, sha256: hash.digest("hex") };
+  }, deadline, new MissingCaptureAssetError(`capture asset ${relativePath} is missing`));
+}
+function digest(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function invalid(message) {
+  throw new PdfCaptureError("invalid-input", message);
+}
+function object(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    invalid("PDF bundle requires an object");
+  return value;
+}
+function integer(value, maximum, minimum = 0) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+    invalid("PDF bundle has an invalid count or page reference");
+  return value;
+}
+function descriptor(value) {
+  const entry = object(value);
+  if (typeof entry.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(entry.sha256))
+    invalid("PDF bundle has an invalid digest");
+  return { path: confinedRelativePath(entry.path, "PDF artifact"), bytes: integer(entry.bytes, 8 * 1024 ** 3), sha256: entry.sha256 };
+}
+function decode(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return invalid("PDF bundle text is not UTF-8");
+  }
+}
+function parse(bytes) {
+  try {
+    return JSON.parse(decode(bytes));
+  } catch (error) {
+    if (error instanceof PdfCaptureError)
+      throw error;
+    return invalid("PDF bundle JSON is invalid");
+  }
+}
+async function inspectPdfCaptureBundle(path, options = {}) {
+  const maxDocument = boundedInteger(options.maxDocumentBytes, 64 * 1024 ** 2, 256 * 1024 ** 2, "maxDocumentBytes");
+  const maxSource = boundedInteger(options.maxSourceBytes, 512 * 1024 ** 2, 8 * 1024 ** 3, "maxSourceBytes");
+  const maxAsset = boundedInteger(options.maxAssetBytes, 100 * 1024 ** 2, 8 * 1024 ** 3, "maxAssetBytes");
+  const maxTotal = boundedInteger(options.maxTotalAssetBytes, 500 * 1024 ** 2, 8 * 1024 ** 3, "maxTotalAssetBytes");
+  const maxAssets = boundedInteger(options.maxVerifiedAssets, 1000, 1e4, "maxVerifiedAssets");
+  const deadline = performance.now() + boundedInteger(options.maxVerificationMs, 30000, 300000, "maxVerificationMs");
+  const root = await safeDirectory(path);
+  try {
+    const manifest = object(parse(await readRegularFile(root, "capture.json", 4 * 1024 ** 2, "PDF manifest", deadline)));
+    if (manifest.schemaVersion !== 1)
+      throw new PdfCaptureError("unsupported-schema", "Unsupported PDF manifest schema");
+    if (manifest.kind !== "pdf" || manifest.status !== "complete" && manifest.status !== "partial")
+      invalid("Invalid PDF manifest kind or status");
+    const document = object(manifest.document);
+    const pageCount = integer(document.pageCount, 1e5, 1);
+    const processedPages = integer(document.processedPages, pageCount, 1);
+    if (processedPages < pageCount && manifest.status !== "partial")
+      invalid("Truncated PDF cannot claim complete");
+    if (manifest.quality !== undefined) {
+      const quality = object(manifest.quality);
+      if (quality.schemaVersion !== 1)
+        throw new PdfCaptureError("unsupported-schema", "Unsupported PDF quality schema");
+      if (!Array.isArray(quality.issues) || quality.issues.length > 1e5)
+        invalid("Invalid PDF quality issues");
+      for (const raw of quality.issues) {
+        const issue = object(raw);
+        if (!["reading-order-uncertain", "table-structure-uncertain", "math-structure-uncertain", "ocr-needed"].includes(String(issue.code)))
+          invalid("Unknown PDF quality issue");
+        integer(issue.page, processedPages, 1);
+      }
+      if (quality.issues.length > 0 && manifest.status !== "partial")
+        invalid("Uncertain PDF cannot claim complete");
+    }
+    const sourceDescriptor = descriptor(manifest.source);
+    if (sourceDescriptor.path !== "source.pdf" || object(manifest.source).mimeType !== "application/pdf")
+      invalid("Invalid retained PDF source");
+    const check = async (expected, maximum) => {
+      if (expected.bytes > maximum)
+        throw new PdfCaptureError("limit-exceeded", "PDF artifact exceeds verification byte limit");
+      const actual = await hashRegularFile(root, expected.path, maximum, deadline, "PDF artifact");
+      return { ...actual, path: expected.path, integrity: actual.bytes === expected.bytes && actual.sha256 === expected.sha256 ? "verified" : "mismatch" };
+    };
+    const source = await check(sourceDescriptor, maxSource);
+    let expectedMarkdown = null;
+    let markdownPath;
+    if (manifest.markdown !== undefined) {
+      expectedMarkdown = descriptor(manifest.markdown);
+      markdownPath = expectedMarkdown.path;
+      if (markdownPath.includes("/") || !markdownPath.endsWith(".md"))
+        invalid("Invalid PDF Markdown path");
+    } else {
+      const directory = await opendir(root.path);
+      const candidates = [];
+      let entries = 0;
+      try {
+        for await (const entry of directory) {
+          assertAssetVerificationDeadline(deadline);
+          if (++entries > 1000)
+            throw new PdfCaptureError("limit-exceeded", "Legacy PDF directory exceeds entry limit");
+          if (entry.name.endsWith(".md"))
+            candidates.push(entry.name);
+        }
+      } finally {
+        try {
+          await directory.close();
+        } catch {}
+      }
+      if (candidates.length !== 1)
+        invalid("Legacy PDF bundle must contain exactly one Markdown document");
+      markdownPath = candidates[0];
+    }
+    const markdownBytes = await readRegularFile(root, markdownPath, maxDocument, "PDF Markdown", deadline);
+    const markdownText = decode(markdownBytes);
+    const markdownDigest = digest(markdownBytes);
+    const markdown = {
+      path: markdownPath,
+      bytes: markdownBytes.length,
+      sha256: markdownDigest,
+      markdown: markdownText,
+      integrity: expectedMarkdown === null ? "unavailable" : expectedMarkdown.bytes === markdownBytes.length && expectedMarkdown.sha256 === markdownDigest ? "verified" : "mismatch"
+    };
+    const assetReferences = new Map;
+    let currentPage = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->|!\[[^\]\n]*\]\((assets\/[^)\r\n]+)\)/gu)) {
+      if (match[1] !== undefined)
+        currentPage = integer(Number(match[1]), processedPages, 1);
+      else if (match[2] !== undefined) {
+        const pages = assetReferences.get(match[2]) ?? new Set;
+        pages.add(currentPage);
+        assetReferences.set(match[2], pages);
+      }
+    }
+    const anchors = new Set;
+    let anchorCount = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->/gu)) {
+      if (++anchorCount > 1e5)
+        invalid("Too many PDF page anchors");
+      anchors.add(integer(Number(match[1]), processedPages, 1));
+    }
+    if (!Array.isArray(manifest.images) || manifest.images.length > maxAssets)
+      invalid("Invalid PDF image count");
+    const imageIds = new Map;
+    const assetsByPath = new Map;
+    const declaredPages = new Map;
+    let totalBytes = 0;
+    for (const raw of manifest.images) {
+      const image = object(raw);
+      if (typeof image.id !== "string" || !/^[a-z0-9][a-z0-9._:-]{0,255}$/u.test(image.id) || imageIds.has(image.id))
+        invalid("Invalid or duplicate PDF image ID");
+      const page = integer(image.page, processedPages, 1);
+      if (!anchors.has(page))
+        invalid("PDF image has no corresponding Markdown page anchor");
+      const asset = descriptor(image.asset);
+      if (!/^assets\/[^/]+$/u.test(asset.path))
+        invalid("PDF image must be a direct assets child");
+      if (!assetReferences.get(asset.path)?.has(page))
+        invalid("PDF image has no corresponding Markdown asset reference");
+      imageIds.set(image.id, asset.sha256);
+      const pages = declaredPages.get(asset.path) ?? new Set;
+      pages.add(page);
+      declaredPages.set(asset.path, pages);
+      const existing = assetsByPath.get(asset.path);
+      if (existing !== undefined) {
+        if (existing.bytes !== asset.bytes || existing.sha256 !== asset.sha256)
+          invalid("Conflicting PDF asset descriptors");
+      } else {
+        totalBytes += asset.bytes;
+        if (totalBytes > maxTotal)
+          throw new PdfCaptureError("limit-exceeded", "PDF assets exceed total byte limit");
+        const checked = await check(asset, Math.min(maxAsset, maxTotal - (totalBytes - asset.bytes)));
+        totalBytes += checked.bytes - asset.bytes;
+        assetsByPath.set(asset.path, checked);
+      }
+    }
+    for (const [path2, pages] of assetReferences) {
+      if (!assetsByPath.has(path2))
+        invalid("Markdown references an undeclared PDF asset");
+      if ([...pages].some((page) => !declaredPages.get(path2)?.has(page)))
+        invalid("Markdown asset page disagrees with PDF manifest");
+    }
+    const extraction = object(manifest.extraction);
+    if (integer(extraction.imageCount, maxAssets) !== imageIds.size)
+      invalid("PDF image count disagrees with manifest");
+    let annotations = null;
+    if (manifest.annotations !== null) {
+      const annotationDescriptor = descriptor(manifest.annotations);
+      if (annotationDescriptor.path !== "annotations.json")
+        invalid("Invalid PDF annotations path");
+      const annotationBytes = await readRegularFile(root, "annotations.json", 16 * 1024 ** 2, "PDF annotations", deadline);
+      const annotationHash = digest(annotationBytes);
+      annotations = { path: annotationDescriptor.path, bytes: annotationBytes.length, sha256: annotationHash, integrity: annotationDescriptor.bytes === annotationBytes.length && annotationDescriptor.sha256 === annotationHash ? "verified" : "mismatch" };
+      let retained;
+      try {
+        retained = parsePdfImageInterpretations(parse(annotationBytes));
+      } catch (error) {
+        if (error instanceof PdfCaptureError)
+          throw error;
+        throw new PdfCaptureError("invalid-input", "Invalid PDF image annotations", { cause: error });
+      }
+      if (retained.length !== integer(object(manifest.annotations).count, 1e4))
+        invalid("PDF annotation count disagrees with manifest");
+      for (const annotation of retained) {
+        if (imageIds.get(annotation.id) !== annotation.sha256)
+          invalid("PDF annotation references an unknown image or digest");
+      }
+    }
+    await assertBundleRoot(root, deadline);
+    return { root: root.path, schemaVersion: 1, status: manifest.status, pageCount, processedPages, markdown, source, assets: [...assetsByPath.values()], annotations };
+  } finally {
+    await root.handle.close();
+  }
+}
+async function verifyPdfCaptureBundle(path, options = {}) {
+  const inspection = await inspectPdfCaptureBundle(path, options);
+  const issues = [];
+  const add = (file, kind) => {
+    if (file.integrity !== "verified")
+      issues.push({ kind, path: file.path, integrity: file.integrity });
+  };
+  add(inspection.markdown, "document-integrity");
+  add(inspection.source, "source-integrity");
+  for (const asset of inspection.assets)
+    add(asset, "asset-integrity");
+  if (inspection.annotations !== null)
+    add(inspection.annotations, "annotation-integrity");
+  return { ok: issues.length === 0, inspection, issues };
+}
+
 // src/pdf.ts
 var PDF_CAPTURE_MANIFEST_FILENAME2 = PDF_CAPTURE_MANIFEST_FILENAME;
 var PDF_CAPTURE_MANIFEST_SCHEMA_VERSION2 = PDF_CAPTURE_MANIFEST_SCHEMA_VERSION;
@@ -58,7 +486,11 @@ var resolvePdfTools2 = resolvePdfTools;
 var runPdfCapture2 = runPdfCapture;
 var runPdfCommand = main;
 var runPdfToolCommand2 = runPdfToolCommand;
+var inspectPdfCaptureBundle2 = (...arguments_) => inspectPdfCaptureBundle(...arguments_);
+var verifyPdfCaptureBundle2 = (...arguments_) => verifyPdfCaptureBundle(...arguments_);
+var PdfCaptureError2 = PdfCaptureError;
 export {
+  verifyPdfCaptureBundle2 as verifyPdfCaptureBundle,
   runPdfToolCommand2 as runPdfToolCommand,
   runPdfCommand,
   runPdfCapture2 as runPdfCapture,
@@ -76,9 +508,11 @@ export {
   parsePdfArguments2 as parsePdfArguments,
   ocrPdfImage2 as ocrPdfImage,
   layoutBlocks2 as layoutBlocks,
+  inspectPdfCaptureBundle2 as inspectPdfCaptureBundle,
   inspectPdf2 as inspectPdf,
   decodePopplerText2 as decodePopplerText,
   buildPdfMarkdown2 as buildPdfMarkdown,
+  PdfCaptureError2 as PdfCaptureError,
   PDF_CAPTURE_SOURCE_FILENAME2 as PDF_CAPTURE_SOURCE_FILENAME,
   PDF_CAPTURE_MANIFEST_SCHEMA_VERSION2 as PDF_CAPTURE_MANIFEST_SCHEMA_VERSION,
   PDF_CAPTURE_MANIFEST_FILENAME2 as PDF_CAPTURE_MANIFEST_FILENAME,
diff --git a/dist/support-hd4754m4.js b/dist/support-s059eytv.js
similarity index 90%
rename from dist/support-hd4754m4.js
rename to dist/support-s059eytv.js
index ec166e51..861fb99b 100644
--- a/dist/support-hd4754m4.js
+++ b/dist/support-s059eytv.js
@@ -2,24 +2,25 @@
 import {
   parseArguments as parseArguments2,
   parseUrlMetadataArguments
-} from "./index-878bh2f1.js";
-import"./index-5h5awwh4.js";
+} from "./index-30v9w4cy.js";
+import"./index-b40e2dkx.js";
 import {
   parsePdfArguments
-} from "./index-m9p2a4mj.js";
+} from "./index-my50xsa3.js";
 import"./index-3hts6yy9.js";
-import"./index-j4zgmzjr.js";
-import"./index-npg9z1a4.js";
-import"./index-h9vyd03z.js";
-import"./index-hacpnaew.js";
-import"./index-k86wepd8.js";
-import"./index-nd8v7r0z.js";
+import"./index-8djdwjjd.js";
+import"./index-xn5q4kne.js";
+import"./index-58azscg5.js";
+import"./index-fd8j527z.js";
+import"./index-h2w7syy2.js";
+import"./index-sp43012q.js";
 import"./index-hnvx7m1j.js";
 import"./index-t4hjm1kk.js";
-import"./index-ncwzmsge.js";
-import"./index-cd75vky9.js";
+import"./index-nwdzhj1h.js";
+import"./index-jbtyp6q5.js";
 import"./index-2gv8y733.js";
-import"./index-mxxxytys.js";
+import"./index-g63d3937.js";
+import"./index-e2wstc7t.js";
 import"./index-w2zc0vwa.js";
 import"./index-e5fbsywq.js";
 import"./index-gh719d91.js";
diff --git a/dist/url-intelligence.js b/dist/url-intelligence.js
index 546090e0..cc33313c 100644
--- a/dist/url-intelligence.js
+++ b/dist/url-intelligence.js
@@ -10,7 +10,7 @@ import {
   readUrlMetadataDocument,
   renderUrlMetadataDocument,
   writeUrlMetadataDocument
-} from "./index-5h5awwh4.js";
+} from "./index-b40e2dkx.js";
 import {
   ARCHIVE_TODAY_HOSTS,
   ArchiveTodayFailure,
@@ -23,8 +23,9 @@ import {
   parseMetadataSearchResponse,
   rankMetadataSearchResults,
   selectNewestArchiveTodayMemento
-} from "./index-hacpnaew.js";
-import"./index-mxxxytys.js";
+} from "./index-fd8j527z.js";
+import"./index-g63d3937.js";
+import"./index-e2wstc7t.js";
 import"./index-e5fbsywq.js";
 import"./index-gh719d91.js";
 import"./index-1xxnjn0d.js";
diff --git a/docs/capture.md b/docs/capture.md
index 2e7d71bf..bc1afe62 100644
--- a/docs/capture.md
+++ b/docs/capture.md
@@ -235,3 +235,22 @@ This operation discloses each eligible source URL as an exact search query to th
 Only a result with the same conservative URL identity can supply the selected title or description. A timestamped Archive.today result must embed that same source identity before it can be recorded. Provider failures, partial engine coverage, throttling, and absence remain explicit in the sidecar. A zero-result record is `not-found` only after complete attempted coverage; any failed engine or archive lookup keeps the top-level result `partial`.
 
 The command skips compatible sidecars by default. Use `--refresh` to query them again, `--no-archive` to omit Archive.today discovery, or `--delay-ms` to change the default one-second interval between outbound requests. It reads Markdown and sidecars through validated no-follow descriptors, carries the source Markdown and article-directory identities through provider work, and revalidates them under an inode-bound kernel advisory lock immediately before atomic installation. A live writer's lock cannot be stolen. The kernel releases a crashed writer's lock, and the next run safely reuses its verified lock file while UUID-scoped temporary names prevent an orphan from blocking progress. Malformed, linked, mismatched, replaced, or concurrently changed sources, locks, and sidecars fail closed.
+
+## Observed article metadata
+
+New captures include an optional `metadata` envelope in `capture.json`. Schema 1
+keeps each observed value, its normalized value, source and locator, the selection
+rule, and whether that claim was selected. Conflicting claims remain available.
+The parser reads HTML title, language, standard meta and link tags, and bounded
+JSON-LD from the captured document. It does not fetch remote JSON-LD contexts.
+
+Specific article metadata takes precedence over generic webpage metadata.
+Multiple authors and alternate links can remain selected. A date without an
+explicit timezone stays local; a calendar date is not converted into an instant.
+Metadata URLs omit query strings, fragments and credentials. They are descriptive
+evidence and must not replace the original acquisition URL. Parser limits and
+malformed JSON-LD appear in the envelope's warnings. Older bundles can omit the
+envelope.
+
+`@hraness/wordcell/capture` exports `extractArticleMetadata` and
+`parseArticleMetadata`; the bundle reader returns this evidence when present.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 9c157b5b..d4925a03 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -13,13 +13,13 @@ Install [Bun 1.3.14 or newer](https://bun.sh/docs/installation) and Git first,
 then install the pinned release archive:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 wordcell --help
 ```
 
 If your shell cannot find `wordcell`, add your package manager's global
 executable directory to `PATH` and reopen the terminal. The npm mirror
-`npm install --global --ignore-scripts @hraness/wordcell@0.26.3` carries the
+`npm install --global --ignore-scripts @hraness/wordcell@0.27.0` carries the
 same bytes.
 
 ## Search an existing Markdown or Obsidian vault
diff --git a/docs/pdf.md b/docs/pdf.md
index 7b3ae29b..22718504 100644
--- a/docs/pdf.md
+++ b/docs/pdf.md
@@ -110,3 +110,33 @@ Reaching any boundary is recorded and makes the result `partial`.
 5. Inspect low-confidence OCR against its source image.
 6. Keep later summaries and interpretations in maintained notes linked to the
    capture.
+
+## Layout quality and verification
+
+Separated columns are read in sequence before lines are merged. Compact aligned
+tables with an explicit header and numeric cells become Markdown tables. Basic
+raised digits remain superscripts. Complex formulas, ambiguous tables and
+uncertain layout produce page-specific quality issues and a partial capture;
+the original PDF remains the reference. Repeated headers are removed only near
+page margins. These rules do not promise complete layout reconstruction.
+
+New bundles bind the Markdown bytes as well as the original PDF and images.
+Use the public SDK to inspect or verify an existing bundle:
+
+```ts
+import { verifyPdfCaptureBundle } from "@hraness/wordcell/pdf";
+const result = await verifyPdfCaptureBundle("/absolute/path/to/saved-document");
+if (!result.ok) throw new Error("PDF bundle verification failed");
+```
+
+`inspectPdfCaptureBundle` returns the saved text and integrity results.
+`verifyPdfCaptureBundle` checks bounded, confined files and page/asset references.
+Legacy bundles without a Markdown digest report unavailable integrity rather
+than verified content. `PdfCaptureError.code` provides stable failure categories;
+unknown failures remain unknown, and password errors require a recognized tool
+diagnostic.
+
+A host with its own process supervisor can inject `runTool` and call
+`runPdfToolCommand({ ...command, processGroup: "inherit" })`. That host owns
+termination and descendant cleanup for the surrounding group. Standalone
+commands keep the default separate process group.
diff --git a/docs/reference.md b/docs/reference.md
index c694fa8c..aa58d96d 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -11,7 +11,7 @@
 Copy this prompt into Codex, Claude Code, or another coding agent:
 
 ```text
-Install the `wordcell` Agent Skill from `hraness/wordcell#v0.26.3` with the standard skills
+Install the `wordcell` Agent Skill from `hraness/wordcell#v0.27.0` with the standard skills
 CLI. Use the skill's runtime instructions to install the exact
 versioned GitHub release archive only when the command is missing. Verify it
 with `wordcell doctor` and `wordcell --help`, but do not initialize or modify a vault until
@@ -21,8 +21,8 @@ I ask.
 Install the single public skill with either runner:
 
 ```sh
-npx skills add hraness/wordcell#v0.26.3
-bunx skills add hraness/wordcell#v0.26.3
+npx skills add hraness/wordcell#v0.27.0
+bunx skills add hraness/wordcell#v0.27.0
 ```
 
 Both commands discover the same `wordcell` skill and install it into the selected
@@ -39,7 +39,7 @@ installed skill is byte-identical to the repository source.
 Install the two global commands with Bun:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 wordcell --help
 wordcell-evaluation-builder --help
 ```
@@ -47,7 +47,7 @@ wordcell-evaluation-builder --help
 The same GitHub archive can be installed with npm:
 
 ```sh
-npm install --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+npm install --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 wordcell --help
 ```
 
@@ -60,7 +60,7 @@ reviewed and enabled; run `wordcell doctor` to inspect the resulting capabilitie
 For programmatic use, add the versioned GitHub archive to a Bun project:
 
 ```sh
-bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz
+bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 ```
 
 The resulting dependency should remain exact:
@@ -68,7 +68,7 @@ The resulting dependency should remain exact:
 ```json
 {
   "dependencies": {
-    "@hraness/wordcell": "https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz"
+    "@hraness/wordcell": "https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz"
   }
 }
 ```
@@ -730,9 +730,9 @@ companion skill for a distinct recurring ritual. The package smoke test keeps
 future tagged packages byte-identical to that source tree.
 
 ```sh
-npx skills add hraness/wordcell#v0.26.3
+npx skills add hraness/wordcell#v0.27.0
 # or
-bunx skills add hraness/wordcell#v0.26.3
+bunx skills add hraness/wordcell#v0.27.0
 ```
 
 The skill invokes the installed `wordcell` command without depending on a repository
diff --git a/package.json b/package.json
index e35a5f62..15d181e5 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.26.3",
+  "version": "0.27.0",
   "description": "Wordcell keeps decisions, plans, and sources as Markdown beside your code, so coding agents can find them from the file they are about to change.",
   "license": "MIT",
   "type": "module",
@@ -484,7 +484,10 @@
     "src/cli-update.ts",
     "src/cli-release.ts",
     "src/evaluation-builder-bin.ts",
-    "src/evaluation-builder-cli-args.ts"
+    "src/evaluation-builder-cli-args.ts",
+    "src/clip/metadata.ts",
+    "src/pdf/bundle-reader.ts",
+    "src/pdf/errors.ts"
   ],
   "scripts": {
     "kb:refresh": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.24.1/hraness-wordcell-0.24.1.tgz wordcell refresh --root kb",
@@ -511,16 +514,17 @@
     "check:worker": "tsc -p worker/tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@hraness/cli-update": "https://github.com/hraness/cli-update/releases/download/v0.1.0/hraness-cli-update-0.1.0.tgz",
     "@hraness/oh": "https://github.com/hraness/oh/releases/download/v0.12.0/hraness-oh-0.12.0.tgz",
+    "@hraness/support-foundation": "git+https://github.com/hraness/support-foundation.git#b32c1c81bb2444f50509ed54388758ecfab1f1c0",
     "@steipete/sweet-cookie": "0.4.3",
     "@tobilu/qmd": "https://github.com/hraness/qmd/releases/download/v2.8.3-hraness.1/hraness-qmd-2.8.3-hraness.1.tgz",
     "agent-browser": "0.32.3",
     "defuddle": "0.19.1",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3",
     "effect": "3.22.1",
-    "@hraness/support-foundation": "git+https://github.com/hraness/support-foundation.git#b32c1c81bb2444f50509ed54388758ecfab1f1c0",
-    "@hraness/cli-update": "https://github.com/hraness/cli-update/releases/download/v0.1.0/hraness-cli-update-0.1.0.tgz"
+    "entities": "7.0.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@hraness/build-governance": "github:hraness/build-governance#v0.1.0",
diff --git a/portfolio-inventory.json b/portfolio-inventory.json
index b3815b7c..b84b7a6b 100644
--- a/portfolio-inventory.json
+++ b/portfolio-inventory.json
@@ -8,7 +8,7 @@
       "name": "@hraness/wordcell",
       "path": ".",
       "visibility": "public",
-      "version": "0.26.3"
+      "version": "0.27.0"
     }
   ],
   "dependencies": [
diff --git a/scripts/kb-skill-contract.test.ts b/scripts/kb-skill-contract.test.ts
index 6881fb32..81650954 100644
--- a/scripts/kb-skill-contract.test.ts
+++ b/scripts/kb-skill-contract.test.ts
@@ -194,7 +194,7 @@ test("the shipped skill resources preserve routing and companion contracts", asy
     "references/url-platforms.md",
     "templates/companion-skill.template.md",
   ]);
-  expect(manifest.version).toBe("0.26.3");
+  expect(manifest.version).toBe("0.27.0");
   const scripts = manifest.scripts as Record<string, string>;
   expect(scripts["kb:search"]).not.toContain("--rerank");
   expect(scripts["kb:search:clef"]).toContain("--rerank clef");
diff --git a/scripts/kb-skill-contract.ts b/scripts/kb-skill-contract.ts
index 455ee702..dbf04c2b 100644
--- a/scripts/kb-skill-contract.ts
+++ b/scripts/kb-skill-contract.ts
@@ -418,8 +418,8 @@ export function validateKbSkillContractResources(
       errors.push(`SKILL.md must link ${link}`);
     }
   }
-  if (!resources.skill.includes("bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.26.3/hraness-wordcell-0.26.3.tgz")) {
-    errors.push("SKILL.md must retain the immutable 0.26.3 GitHub runtime pin");
+  if (!resources.skill.includes("bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz")) {
+    errors.push("SKILL.md must retain the immutable 0.27.0 GitHub runtime pin");
   }
   for (const [name, contents, headings] of [
     ["customize.md", resources.customize, CUSTOMIZE_HEADINGS],
diff --git a/scripts/npm-release-workflow.test.ts b/scripts/npm-release-workflow.test.ts
index f3c60645..d60d5480 100644
--- a/scripts/npm-release-workflow.test.ts
+++ b/scripts/npm-release-workflow.test.ts
@@ -382,7 +382,7 @@ describe("npm release workflows", () => {
       readonly version?: unknown;
     };
     expect(manifest).toEqual(expect.objectContaining({
-      version: "0.26.3",
+      version: "0.27.0",
       description: expect.any(String),
       keywords: [
         "knowledge-base",
diff --git a/scripts/package-artifact.ts b/scripts/package-artifact.ts
index 8871d67f..c3a8f918 100644
--- a/scripts/package-artifact.ts
+++ b/scripts/package-artifact.ts
@@ -4,18 +4,18 @@ import { gunzipSync } from "node:zlib";
 
 const blockSize = 512;
 const packagePrefix = "package/";
-const maximumTarBytes = 6_950_000;
+const maximumTarBytes = 7_050_000;
 const ustarSignature = Buffer.from([0x75, 0x73, 0x74, 0x61, 0x72, 0x00, 0x30, 0x30]);
 
-// The Clef provider migration ships src/rerank-clef.ts and dist/rerank-clef.js:
-// measured npm package 6,385,735 unpacked bytes (1,439,073 compressed, 302 files).
-// Preserve the compressed/file bounds and the existing 450 KB tar overhead cap.
-export const maximumUnpackedBytes = 6_500_000;
+// Metadata/PDF SDK0.27.0 ships three public transitive source modules:
+// measured npm package6,492,562 unpacked bytes (1,463,933 compressed,306 files).
+// Reviewed modest headroom preserves the450KB tar overhead cap.
+export const maximumUnpackedBytes = 6_600_000;
 
 const packageBudget = Object.freeze({
   entryCount: { min: 190, max: 420 },
-  fileCount: { min: 190, max: 306 },
-  packedBytes: { min: 950_000, max: 1_450_000 },
+  fileCount: { min: 190, max: 310 },
+  packedBytes: { min: 950_000, max: 1_500_000 },
   unpackedBytes: { min: 4_500_000, max: maximumUnpackedBytes },
 });
 
diff --git a/scripts/package-smoke.ts b/scripts/package-smoke.ts
index 72f76f42..a4555905 100644
--- a/scripts/package-smoke.ts
+++ b/scripts/package-smoke.ts
@@ -12,7 +12,7 @@ import { requiresOhAdoptionPreparerExport } from "./npm-package-identity.js";
 
 const packageName = "@hraness/wordcell";
 const maximumPackageFiles = 306;
-const maximumPackedBytes = 1_450_000;
+const maximumPackedBytes = 1_500_000;
 const importSpecifiers = [
   "@hraness/wordcell",
   "@hraness/wordcell/agent-context",
@@ -77,6 +77,8 @@ const baselineRequiredNamedExports = {
   "@hraness/wordcell/graph-authority": ["openGraphAuthority", "queryGraph", "rebuildGraph", "verifyGraph"],
   "@hraness/wordcell/graph-percolation": ["percolateWithGraph"],
   "@hraness/wordcell/clip/bundle-reader": ["readCaptureBundle", "verifyCaptureBundle"],
+  "@hraness/wordcell/capture": ["extractArticleMetadata", "parseArticleMetadata"],
+  "@hraness/wordcell/pdf": ["inspectPdfCaptureBundle", "verifyPdfCaptureBundle", "PdfCaptureError"],
   "@hraness/wordcell/clip/jobs": ["createCaptureJob", "openCaptureJobStore", "updateCaptureJob"],
   "@hraness/wordcell/clip/refresh": ["diffCaptureBundle"],
   "@hraness/wordcell/portfolio": ["openKnowledgePortfolio", "parsePortfolioRegistry", "parseQualifiedDocumentUri"],
diff --git a/site/app/docs/docs.generated.ts b/site/app/docs/docs.generated.ts
index 340deb79..c2f7ca30 100644
--- a/site/app/docs/docs.generated.ts
+++ b/site/app/docs/docs.generated.ts
@@ -5,8 +5,8 @@ export const docHtml: Readonly<Record<string, string>> = {
   "agent-handoffs": "<h1 id=\"connect-wordcell-to-your-coding-agent\">Connect Wordcell to your coding agent</h1>\n<p><code>wordcell mcp</code> serves one Markdown vault to a coding agent over the Model\nContext Protocol (MCP). The agent starts the server itself, then searches,\nreads, and follows links between your notes, and it can write notes unless you\nstart the server with <code>--read-only</code>. This guide registers the server with\nClaude Code, Codex, and Cursor, checks that the agent can start it, and lists\nthe errors you are most likely to see.</p>\n<p>Checked on October 4, 2026: Claude Code 2.1.287 and Codex CLI 0.160.0\nregistered Wordcell 0.26.3 with the commands below, in a test project with\nempty configuration directories. The command output on this page comes from\nthose runs and from calling the server's tools directly, without an agent.</p>\n<h2 id=\"before-you-start\">Before you start</h2>\n<ol>\n<li>Install Wordcell 0.23.0 or newer, the first release with <code>wordcell mcp</code>.\n<a href=\"/docs/getting-started#install-the-cli\">Get started</a> has the install command.</li>\n<li>Find the absolute path of your vault, such as a <code>kb/</code> folder in your\nrepository or an existing notes folder.</li>\n<li>Search the vault from a terminal for a phrase you know is in one note:</li>\n</ol>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;a phrase from your notes&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/kb <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p>If the result names the note you expected, the vault and the installation\nwork, and any later problem is in the agent's configuration. Exact search\nreads the Markdown directly and needs no index or model.</p>\n<p>Every client runs the same server command. Choose its arguments first:</p>\n<ul>\n<li><code>--root /absolute/path/to/kb</code> names the vault and is required.</li>\n<li><code>--repo /absolute/path/to/repository</code> adds the <code>context</code> tool, which returns\nthe notes and <code>AGENTS.md</code> files that apply to a path in that repository.</li>\n<li><code>--read-only</code> leaves out the three tools that write notes.</li>\n</ul>\n<p>Use absolute paths. A client can start the server from a different working\ndirectory than your terminal's, and a relative path resolves from there.</p>\n<h2 id=\"claude-code\">Claude Code</h2>\n<p>Add the server with <code>claude mcp add</code>. Everything after <code>--</code> is the server\ncommand:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">claude</span> mcp add <span class=\"syntax-token syntax-token--flag\">--transport</span> stdio <span class=\"syntax-token syntax-token--flag\">--scope</span> project wordcell <span class=\"syntax-token syntax-token--flag\">--</span> wordcell mcp <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/kb\n</code></pre></div></figure>\n<p><code>--scope</code> decides where Claude Code saves the server, as its\n<a href=\"https://code.claude.com/docs/en/mcp\">MCP guide</a> describes:</p>\n<table>\n<thead>\n<tr><th>Scope</th><th>Saved in</th><th>Available to</th></tr>\n</thead>\n<tbody>\n<tr><td><code>local</code>, the default</td><td><code>~/.claude.json</code>, under this project</td><td>You, in this project</td></tr>\n<tr><td><code>project</code></td><td><code>.mcp.json</code> at the project root</td><td>Everyone who uses the repository, after each person approves it</td></tr>\n<tr><td><code>user</code></td><td><code>~/.claude.json</code></td><td>You, in every project</td></tr>\n</tbody>\n</table>\n<p><code>claude mcp list</code> starts each configured server to check it. A server that\nstarted prints <code>✔ Connected</code>:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">$ claude mcp list\nChecking MCP server health…\n\nwordcell: wordcell mcp --root /tmp/wordcell-demo/kb --repo /tmp/wordcell-demo - ✔ Connected\n</code></pre>\n<p>A server saved with <code>--scope project</code> waits until you start <code>claude</code> in that\nproject and approve it. Until then the list shows:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">wordcell: wordcell mcp --root /tmp/wordcell-demo/kb - ⏸ Pending approval (run `claude` to approve)\n</code></pre>\n<p>An absolute vault path in <code>.mcp.json</code> works only on your machine. When the\nvault is a <code>kb/</code> folder in the repository, a shared <code>.mcp.json</code> can name it\nthrough the <code>CLAUDE_PROJECT_DIR</code> variable that Claude Code sets for the\nserver. Keep the <code>:-.</code> default, which Claude Code requires for this variable\nin <code>.mcp.json</code>:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcpServers</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">type</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">stdio</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">command</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">args</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcp</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">--root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">${CLAUDE_PROJECT_DIR:-.}/kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>With the server approved, <code>claude mcp list</code> showed this entry connected in the\nsame test.</p>\n<h2 id=\"codex\">Codex</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">codex</span> mcp add wordcell <span class=\"syntax-token syntax-token--flag\">--</span> wordcell mcp <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/kb\n</code></pre></div></figure>\n<p>The command adds this table to <code>~/.codex/config.toml</code>. The\n<a href=\"https://developers.openai.com/codex/mcp\">Codex MCP guide</a> says the Codex CLI,\nthe IDE extension, and the ChatGPT desktop app share that file. You can also\nwrite the table yourself, there or in <code>.codex/config.toml</code> inside a trusted\nproject:</p>\n<pre><code class=\"syntax-code language-toml\" data-language=\"toml\"><span class=\"syntax-token syntax-token--operator\">[</span><span class=\"syntax-token syntax-token--property\">mcp_servers</span><span class=\"syntax-token syntax-token--operator\">.</span><span class=\"syntax-token syntax-token--property\">wordcell</span><span class=\"syntax-token syntax-token--operator\">]</span>\n<span class=\"syntax-token syntax-token--property\">command</span> <span class=\"syntax-token syntax-token--operator\">=</span> <span class=\"syntax-token syntax-token--string\">&quot;wordcell&quot;</span>\n<span class=\"syntax-token syntax-token--property\">args</span> <span class=\"syntax-token syntax-token--operator\">=</span> <span class=\"syntax-token syntax-token--operator\">[</span><span class=\"syntax-token syntax-token--string\">&quot;mcp&quot;</span><span class=\"syntax-token syntax-token--operator\">,</span> <span class=\"syntax-token syntax-token--string\">&quot;--root&quot;</span><span class=\"syntax-token syntax-token--operator\">,</span> <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/kb&quot;</span><span class=\"syntax-token syntax-token--operator\">]</span>\n</code></pre>\n<p><code>codex mcp list</code> shows the configuration without starting the server:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">$ codex mcp list\nName      Command   Args                                                        Env  Cwd  Status   Auth\nwordcell  wordcell  mcp --root /tmp/wordcell-demo/kb --repo /tmp/wordcell-demo  -    -    enabled  Unsupported\n</code></pre>\n<p><code>enabled</code> means the entry is switched on, not that the server works: a vault\npath that does not exist also shows <code>enabled</code>. Start <code>codex</code> and run <code>/mcp</code> to\nsee the servers that started. By default Codex waits 10 seconds for a server\nto start and 60 seconds for a tool call; <code>startup_timeout_sec</code> and\n<code>tool_timeout_sec</code> in the same table change those limits.</p>\n<h2 id=\"cursor\">Cursor</h2>\n<p>Cursor reads MCP servers from <code>.cursor/mcp.json</code> in a project, or from\n<code>~/.cursor/mcp.json</code> for every project, as its\n<a href=\"https://cursor.com/docs/context/mcp\">MCP guide</a> describes:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcpServers</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">type</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">stdio</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">command</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">args</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcp</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">--root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">/absolute/path/to/kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>When the vault is a <code>kb/</code> folder in the project, the project file can use\nCursor's <code>${workspaceFolder}</code> variable instead of a fixed path:\n<code>&quot;args&quot;: [&quot;mcp&quot;, &quot;--root&quot;, &quot;${workspaceFolder}/kb&quot;]</code>. Turn servers on or off\nfrom Customize in the sidebar. Server errors appear in the Output panel under\nMCP Logs, and Cursor asks before it runs an MCP tool unless your run mode\nallows it.</p>\n<p>These steps come from Cursor's documentation, read on October 4, 2026. They\nwere not run in Cursor for this guide.</p>\n<h2 id=\"claude-desktop\">Claude Desktop</h2>\n<p>From the Claude menu, open Settings, then Developer, then Edit Config, and add\nthe server to <code>claude_desktop_config.json</code>. The file is in\n<code>~/Library/Application Support/Claude/</code> on macOS and <code>%APPDATA%\\Claude\\</code> on\nWindows. Quit and restart Claude Desktop after you save it.</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcpServers</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">command</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">wordcell</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">args</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mcp</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">--root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">/absolute/path/to/kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>On macOS, the server's standard error goes to\n<code>~/Library/Logs/Claude/mcp-server-wordcell.log</code>. These steps follow the\n<a href=\"https://modelcontextprotocol.io/docs/develop/connect-local-servers\">local server guide</a>,\nread on October 4, 2026, and were not run for this guide.</p>\n<h2 id=\"other-mcp-clients\">Other MCP clients</h2>\n<p>A client that starts local stdio servers can run Wordcell with the command\n<code>wordcell</code> and the arguments <code>mcp --root /absolute/path/to/kb</code>. The server\nwrites only protocol messages to standard output and its errors to standard\nerror. The <a href=\"/docs/reference#local-mcp-server\">local MCP server reference</a> lists\nthe protocol versions it accepts.</p>\n<h2 id=\"check-that-the-agent-reads-your-notes\">Check that the agent reads your notes</h2>\n<p>Ask the agent to call Wordcell's <code>search</code> tool with the phrase you searched in\nthe terminal, in exact mode:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">query</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">a phrase from your notes</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mode</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">exact</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">limit</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">3</span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>The result should name the same note as the terminal search. Then ask for\n<code>get_note</code> with that note's ID, its vault path without <code>.md</code>, and compare the\nbody with the file. Called directly in the test project, <code>search</code> for\n<code>parser retries</code> returned <code>notes/parser-contract</code> at line 11, and <code>context</code> for\n<code>src/parser.ts</code> returned the same note, which declares that file in its\n<code>repository_scopes</code>.</p>\n<p>Start with exact mode. The default mode, <code>hybrid</code>, adds local semantic search,\nand the first hybrid search on a machine downloads an embedding model. In one\nrun on October 4, 2026, that download was 334 MB and the first call took 26.5\nseconds. When semantic search is unavailable, the result is marked partial and\n<code>diagnostics.lanes</code> gives the reason.</p>\n<p>The tools the agent sees depend on the server arguments:</p>\n<table>\n<thead>\n<tr><th>Server arguments</th><th>Tools</th></tr>\n</thead>\n<tbody>\n<tr><td><code>--root</code></td><td><code>search</code>, <code>list_notes</code>, <code>get_note</code>, <code>backlinks</code>, <code>links</code>, <code>create_note</code>, <code>update_note_body</code>, <code>add_relation</code></td></tr>\n<tr><td><code>--root</code> and <code>--repo</code></td><td>The same tools and <code>context</code></td></tr>\n<tr><td><code>--root</code>, <code>--repo</code>, and <code>--read-only</code></td><td><code>search</code>, <code>context</code>, <code>list_notes</code>, <code>get_note</code>, <code>backlinks</code>, <code>links</code></td></tr>\n</tbody>\n</table>\n<h2 id=\"keep-results-within-the-agents-limits\">Keep results within the agent's limits</h2>\n<p>Wordcell caps each tool result at 64 KiB of JSON and sends the same JSON again\nas text. When the cap applies, it leaves out the items that do not fit and\nsets <code>truncated: true</code> and an <code>omitted</code> count. On a test vault of 400 notes:</p>\n<table>\n<thead>\n<tr><th>Call</th><th>JSON returned as text</th></tr>\n</thead>\n<tbody>\n<tr><td><code>search</code>, exact, default 10 results</td><td>13.2 KiB</td></tr>\n<tr><td><code>search</code>, exact, <code>limit: 3</code></td><td>4.3 KiB</td></tr>\n<tr><td><code>search</code>, exact, <code>limit: 100</code></td><td>62.9 KiB, with 49 results returned and 51 omitted</td></tr>\n<tr><td><code>list_notes</code>, <code>limit: 1000</code></td><td>63.7 KiB, with 142 of 400 notes returned</td></tr>\n</tbody>\n</table>\n<p>Claude Code warns when an MCP tool result passes 10,000 tokens and limits\nresults to 25,000 tokens by default. Set <code>MAX_MCP_OUTPUT_TOKENS</code> before you\nstart <code>claude</code> to raise the limit; a result over the limit is saved to a file\nthat Claude reads when it needs to, according to its\n<a href=\"https://code.claude.com/docs/en/mcp#mcp-output-limits-and-warnings\">output limits</a>.\nClaude Code also saves any text result longer than 50,000 characters to a\nfile, whatever <code>MAX_MCP_OUTPUT_TOKENS</code> says, so the two largest results in the\ntable reach Claude as a file path.\nCodex takes a per-tool <code>output_token_limit</code> in a table such as\n<code>[mcp_servers.wordcell.tools.search]</code> in <code>config.toml</code>, as its\n<a href=\"https://developers.openai.com/codex/mcp\">MCP guide</a> describes. Token counts\ndepend on each model's tokenizer and were not measured here, so keep <code>limit</code>\nat 10 or lower and open notes one at a time with <code>get_note</code>.</p>\n<h2 id=\"troubleshoot-the-connection\">Troubleshoot the connection</h2>\n<table>\n<thead>\n<tr><th>Symptom</th><th>What to check or change</th></tr>\n</thead>\n<tbody>\n<tr><td><code>claude mcp list</code> shows <code>Failed to connect</code> with <code>ENOENT: Executable not found in $PATH: &quot;wordcell&quot;</code></td><td>The client cannot find <code>wordcell</code> on its <code>PATH</code>, which can be shorter than your terminal's. Use the absolute path that <code>which wordcell</code> prints as the command, then restart the client.</td></tr>\n<tr><td><code>claude mcp list</code> shows <code>Failed to connect</code> with <code>CONNECTION_CLOSED: Connection closed</code></td><td>The server started and exited. Run the same command in a terminal to see why. A vault path that does not exist prints <code>✗ ENOENT: no such file or directory</code> and <code>→ wordcell mcp --help</code>, then exits with status 2. With an absolute <code>wordcell</code> path, Bun must also be on the client's <code>PATH</code>, because <code>wordcell</code> runs on Bun.</td></tr>\n<tr><td><code>claude mcp list</code> shows <code>⏸ Pending approval (run `claude` to approve)</code></td><td>A server from <code>.mcp.json</code> waits for approval. Start <code>claude</code> in the project and accept it.</td></tr>\n<tr><td>Codex lists the server, but its tools never appear</td><td><code>codex mcp list</code> does not start servers. Run the server command in a terminal, fix the path or <code>PATH</code>, and check <code>/mcp</code> again.</td></tr>\n<tr><td>Search returns a partial result</td><td>Read <code>diagnostics.lanes</code>, then search again with <code>mode: &quot;exact&quot;</code>, which reads the current Markdown without the semantic index. Read <a href=\"/docs/reference#review-lifecycle-scripts-before-enabling-optional-adapters\">optional adapters</a> before you set up semantic search.</td></tr>\n<tr><td>A result has <code>truncated: true</code></td><td>Lower <code>limit</code> on <code>search</code> or <code>list_notes</code>, or <code>limit</code> and <code>depth</code> on <code>backlinks</code> and <code>links</code>. Read the <code>omitted</code> count, then open notes one at a time with <code>get_note</code>.</td></tr>\n<tr><td><code>get_note</code> reports <code>truncated: true</code></td><td>The read stopped at 64 KiB. Open the Markdown file itself, and do not send the shortened body to <code>update_note_body</code>, which replaces the whole body.</td></tr>\n<tr><td><code>context</code> or the write tools are missing</td><td><code>context</code> needs <code>--repo</code>, and <code>--read-only</code> removes the write tools. Change the server arguments and restart the connection.</td></tr>\n</tbody>\n</table>\n<h2 id=\"remove-the-server\">Remove the server</h2>\n<ul>\n<li>Claude Code: <code>claude mcp remove wordcell -s local</code>, with the scope you used.</li>\n<li>Codex: <code>codex mcp remove wordcell</code>.</li>\n<li>Cursor and Claude Desktop: delete the <code>wordcell</code> entry from the file you\nedited.</li>\n</ul>\n<p>Next, <a href=\"/docs/agent-workflow\">use Wordcell with a coding agent</a> to keep decisions\nand plans beside the code, or\n<a href=\"/docs/obsidian\">search an existing Obsidian vault</a> from the agent without\nchanging it.</p>\n",
   "obsidian": "<h1 id=\"use-wordcell-with-an-existing-obsidian-vault\">Use Wordcell with an existing Obsidian vault</h1>\n<p>Point Wordcell at the folder Obsidian already uses as a vault. Wordcell reads\nthe Markdown files where they are: it needs no <code>index.md</code>, no import, and no\nchange to your notes, and it does not read the <code>.obsidian/</code> settings folder.\nYour coding agent can then search the vault, follow its wikilinks, and read\nnotes, with the write tools turned off if you prefer.</p>\n<p>The behavior on this page was checked on October 4, 2026 with Wordcell 0.26.3\non a test vault that has an <code>.obsidian/</code> folder and one note for each link\nform in the table below. The vault was a Git repository, and <code>git status</code>\nshowed no changes after any command on this page, including the MCP tool\ncalls.</p>\n<h2 id=\"search-the-vault\">Search the vault</h2>\n<p>Wordcell 0.22.0 and newer search a folder without initializing it. Run an\nexact search with the vault's absolute path:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;retry budget&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/vault <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p><a href=\"/docs/getting-started#search-an-existing-markdown-or-obsidian-vault\">Search an existing Markdown or Obsidian vault</a>\nlists the files a search skips and what to try when nothing matches. Exact\nsearch finds text in callouts, inline <code>#tags</code>, and frontmatter, and it matches\na note's <code>aliases</code> as well as its title. Wordcell reads only <code>.md</code> files, so\ncanvases and attachments are not searched.</p>\n<h2 id=\"what-wordcell-reads-from-obsidian-notes\">What Wordcell reads from Obsidian notes</h2>\n<table>\n<thead>\n<tr><th>Obsidian syntax</th><th>Example</th><th>What Wordcell does</th></tr>\n</thead>\n<tbody>\n<tr><td>Wikilink to a note</td><td><code>[[Parser rewrite]]</code></td><td>Resolves the link and counts it as a backlink.</td></tr>\n<tr><td>Display text</td><td><code>[[Parser rewrite|the rewrite]]</code></td><td>Resolves the link.</td></tr>\n<tr><td>Folder path</td><td><code>[[Projects/Parser rewrite]]</code></td><td>Resolves the link.</td></tr>\n<tr><td>Heading or block link</td><td><code>[[Parser rewrite#Retry budget]]</code>, <code>[[Parser rewrite#^retry-budget]]</code></td><td>Resolves the link to the note. It does not check that the heading or block exists.</td></tr>\n<tr><td>Embedded note or section</td><td><code>![[Parser rewrite]]</code>, <code>![[Parser rewrite#Retry budget]]</code></td><td>Resolves the link and counts it as a backlink.</td></tr>\n<tr><td>Two notes with the same name</td><td><code>[[Standup]]</code></td><td>Reports an ambiguous link and names both paths. Link with the folder path instead.</td></tr>\n<tr><td>Different letter case</td><td><code>[[parser rewrite]]</code></td><td>Reports a broken link. Match the case of the file name.</td></tr>\n<tr><td>Alias as the link target</td><td><code>[[Parser v2]]</code></td><td>Reports a broken link and lists an unlinked mention of the note that has the alias.</td></tr>\n<tr><td>Markdown link to a note</td><td><code>[the rewrite](../Projects/Parser%20rewrite.md)</code></td><td>Ignores it: the link is neither counted nor reported.</td></tr>\n<tr><td>Embedded or linked attachment</td><td><code>![[Diagram.png]]</code>, <code>![[Diagram.png|300]]</code>, <code>![[Spec.pdf#page=2]]</code>, <code>[[Spec.pdf]]</code></td><td>Finds the file by name anywhere in the vault. A missing file is an error.</td></tr>\n<tr><td>Frontmatter properties</td><td><code>status: active</code></td><td>Filters with <code>wordcell list --where status=active</code>.</td></tr>\n<tr><td>Frontmatter tags</td><td><code>tags: [project, standup/weekly]</code></td><td>Filters with <code>wordcell list --tag project</code>. A nested tag matches only in full: <code>--tag standup/weekly</code> finds it and <code>--tag standup</code> does not.</td></tr>\n<tr><td>Inline tags</td><td><code>#decision</code>, <code>#standup/notes</code></td><td>Searches them as text. <code>--tag</code> does not see them.</td></tr>\n<tr><td>Callouts</td><td><code>&gt; [!warning] Rollback plan</code></td><td>Searches the callout's text.</td></tr>\n<tr><td>Settings folder</td><td><code>.obsidian/app.json</code></td><td>Does not read it.</td></tr>\n</tbody>\n</table>\n<p>When you pick a note through one of its aliases, Obsidian writes the link as\n<code>[[Parser rewrite|Parser v2]]</code>, as its\n<a href=\"https://obsidian.md/help/aliases\">aliases guide</a> describes, and Wordcell\nresolves that form. Only a link that names the alias alone breaks. Wordcell's\nlink graph reads wikilinks and typed relations, so a vault that links notes\nwith Markdown links has no backlinks in Wordcell. In Obsidian's own search,\n<code>tag:inbox</code> also matches nested tags such as <code>#inbox/to-read</code>\n(<a href=\"https://obsidian.md/help/tags\">tags guide</a>); Wordcell's <code>--tag</code> matches the\nfull tag and reads only the <code>tags</code> property.</p>\n<h2 id=\"check-links-and-attachments\">Check links and attachments</h2>\n<p><code>wordcell check</code> reports broken and ambiguous wikilinks and missing\nattachments, and it changes no files. It runs on a vault without an\n<code>index.md</code>:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> check <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/vault\n</code></pre></div></figure>\n<p>On the test vault it reported these errors:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">error: Links/alias-as-target.md:5: broken wikilink [[Parser v2]]\nerror: Links/ambiguous-name.md:5: ambiguous wikilink [[Standup]] (Archive/Standup, Meetings/2026/Standup)\nerror: Links/different-case.md:5: broken wikilink [[parser rewrite]]\nerror: Links/missing-note.md:5: broken wikilink [[Tokenizer benchmark]]\nerror: Areas/Inbox.md:3: missing attachment Missing diagram.png: Obsidian attachment basename was not found in the vault.\n</code></pre>\n<p>The command exits with status 3 when it finds an error. It also lists notes\nthat nothing links to and titles or aliases mentioned without a link. Those\nare advisories: a vault with advisories and no errors exits with status 0.</p>\n<p>Obsidian's own help vault is a larger test. On a local copy of the\n<a href=\"https://github.com/obsidianmd/obsidian-help\">obsidian-help</a> repository at its\nSeptember 29, 2026 commit, Wordcell read the 176 notes in the English folder,\nresolved 959 links, and reported 68 broken and five ambiguous ones. Of the 68, 46\nnamed an existing note with different letter case. It found 251 of the 253\nattachments the notes reference.</p>\n<h2 id=\"serve-the-vault-to-your-agent-without-changes\">Serve the vault to your agent without changes</h2>\n<p>Start the server with <code>--read-only</code>, so the agent can search and read but not\nwrite. For Claude Code:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">claude</span> mcp add <span class=\"syntax-token syntax-token--flag\">--transport</span> stdio wordcell <span class=\"syntax-token syntax-token--flag\">--</span> wordcell mcp <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/vault <span class=\"syntax-token syntax-token--flag\">--read-only</span>\n</code></pre></div></figure>\n<p><a href=\"/docs/agent-handoffs\">Connect Wordcell to your coding agent</a> has the same step\nfor Codex, Cursor, and Claude Desktop, and the checks to run after it. With\n<code>--read-only</code>, the server offers <code>search</code>, <code>list_notes</code>, <code>get_note</code>,\n<code>backlinks</code>, and <code>links</code>, and a call to <code>create_note</code> fails with\n<code>Unknown tool: create_note</code>.</p>\n<p>Note IDs are vault paths without <code>.md</code>, spaces included, such as\n<code>Projects/Parser rewrite</code>. <code>get_note</code> returns the note's frontmatter as JSON,\nincluding <code>aliases</code>, <code>tags</code>, and your other properties, and <code>backlinks</code>\nreturns the notes that link to it.</p>\n<p>Ask for <code>mode: &quot;exact&quot;</code> until you decide to use semantic search. The default\nmode, <code>hybrid</code>, downloads an embedding model on first use. In this check,\nWordcell kept that model and its search index under <code>~/.cache</code>, outside the\nvault.</p>\n<h2 id=\"let-the-agent-write-notes\">Let the agent write notes</h2>\n<p>Without <code>--read-only</code>, the agent can create notes, replace a note body at the\nrevision it read, and add typed relations. A new note is an ordinary Markdown\nfile with YAML frontmatter, and Obsidian\n<a href=\"https://obsidian.md/help/data-storage\">picks up changes made by other programs</a>,\nso it appears in the vault like any other note. <code>create_note</code> does not create\nfolders. <code>update_note_body</code> keeps the note's frontmatter and fails if the note\nchanged after the agent read it. Commit the vault before you turn on the write\ntools, so <code>git diff</code> shows each change the agent makes.</p>\n",
   "migration-from-supermemory": "<h1 id=\"migrate-from-supermemory\">Migrate from Supermemory</h1>\n<p>This guide moves the documents and memory entries you saved in Supermemory into\na Wordcell vault: Markdown notes in a Git repository that your coding agent\nreads and writes through <code>wordcell mcp</code>. You export your data with the\nSupermemory API, import it with <code>wordcell import supermemory</code>, check the\nresult, and connect your agent. Every external page linked here was checked on\nSeptember 26, 2026.</p>\n<p><code>wordcell import supermemory</code> and <code>wordcell mcp</code> need Wordcell 0.23.0 or\nlater. Install it as <a href=\"/docs/getting-started#install-the-cli\">Get started</a> shows;\nthe <a href=\"/docs/reference#installation-reference\">installation reference</a> lists the\nrequirements.</p>\n<h2 id=\"who-should-switch-and-who-should-stay\">Who should switch and who should stay</h2>\n<p>Switch when your agents keep memory about your own work and you want that\nmemory in files. The\n<a href=\"https://supermemory.ai/docs/integrations/claude-code\">Supermemory plugin for Claude Code</a>\nsaves conversations and tool use to your Supermemory account, and\n<a href=\"https://supermemory.ai/docs/smfs/overview\">SMFS</a> mounts a container as a\ndirectory whose writes push to Supermemory. A vault keeps the same kind of\nmemory as Markdown files that you and your agent read, edit, diff, and review\nin Git, with no account or API key.</p>\n<p>Stay with Supermemory when you build a product that stores memory for many\nusers and you need what the hosted service runs for you:\n<a href=\"https://supermemory.ai/docs/concepts/container-tags\">container tags</a> that\nisolate each user’s memories, API keys limited to chosen tags,\n<a href=\"https://supermemory.ai/docs/overview/analytics\">analytics endpoints</a>,\n<a href=\"https://supermemory.ai/docs/connectors/overview\">connectors</a> that sync on\ntheir own, automatic extraction of facts and\n<a href=\"https://supermemory.ai/docs/concepts/user-profiles\">user profiles</a>, and SOC 2\nType II compliance with a HIPAA business associate agreement on some plans\n(<a href=\"https://supermemory.ai/docs/overview/security\">security</a>). Wordcell has none\nof these.</p>\n<p><a href=\"https://supermemory.ai/docs/self-hosting/overview\">Supermemory local</a> runs the\nsame engine on your own machine, so keeping data off a hosted service is not by\nitself a reason to switch. Switch when you want the Markdown files themselves\nto be the memory.</p>\n<h2 id=\"map-supermemory-concepts-to-wordcell\">Map Supermemory concepts to Wordcell</h2>\n<table>\n<thead>\n<tr><th>Supermemory</th><th>Wordcell</th><th>Notes</th></tr>\n</thead>\n<tbody>\n<tr><td><a href=\"https://supermemory.ai/docs/concepts/container-tags\">Container tag</a></td><td>A vault per project or person, or the imported <code>container_tag</code> and <code>container_tags</code> fields</td><td>Only imported documents keep their tags: <code>container_tag</code> holds the first tag, and <code>container_tags</code> lists every tag when a document has several. To find every document with a tag, run <code>wordcell list --where container_tag=&lt;tag&gt;</code>, then again with <code>--where container_tags=&lt;tag&gt;</code>. Memory entries keep no tag, so when the separation matters, import each tag into its own vault or under its own <code>--prefix</code>.</td></tr>\n<tr><td>Document</td><td>A note under <code>articles/</code> or <code>notes/imported/</code></td><td>See <a href=\"/docs/reference#where-notes-go\">Where notes go</a>.</td></tr>\n<tr><td>Memory entry and its versions</td><td>One note per version under <code>notes/imported/memories/</code></td><td>Each version has a <code>supersedes</code> relation to the one before it.</td></tr>\n<tr><td>Updates, Extends, and Derives relations (<a href=\"https://supermemory.ai/docs/concepts/graph-memory\">graph memory</a>)</td><td>Relations you add with <code>wordcell relation add</code></td><td>Supermemory infers these links, so the importer does not convert them.</td></tr>\n<tr><td><a href=\"https://supermemory.ai/docs/concepts/user-profiles\">User profile</a></td><td>A <code>type: profile</code> note that your agent maintains</td><td>See <a href=\"#connect-your-agent\">Connect your agent</a>.</td></tr>\n<tr><td>Automatic extraction</td><td>Notes that you or your agent write</td><td><code>wordcell percolate</code> suggests connections for you to review. Nothing writes a note on its own.</td></tr>\n<tr><td><a href=\"https://supermemory.ai/docs/api-reference/content-management/forget-a-memory\">Forgetting</a> and <code>forgetAfter</code></td><td>Delete the note (Git keeps its history) or mark it superseded</td><td>The importer skips forgotten entries and records <code>forget_after</code>, but no note expires.</td></tr>\n<tr><td><a href=\"https://supermemory.ai/docs/connectors/overview\">Connectors</a></td><td>Exports that you save into the vault</td><td>Each source needs its own export. See <a href=\"#replace-connectors\">Replace connectors</a>.</td></tr>\n<tr><td><a href=\"https://supermemory.ai/docs/supermemory-mcp/mcp\">Hosted MCP server</a></td><td><code>wordcell mcp</code></td><td><code>search_memory</code> becomes <code>search</code>; <code>get_document</code> and <code>get_profile</code> become <code>get_note</code>; <code>add_memory</code> becomes <code>create_note</code> or <code>update_note_body</code>; <code>list_documents</code> and <code>list_memories</code> become <code>list_notes</code>. <code>list_spaces</code> and <code>who_am_i</code> have no equivalent.</td></tr>\n<tr><td><a href=\"https://supermemory.ai/docs/smfs/overview\">SMFS</a></td><td>The vault directory</td><td><a href=\"/docs/sync\">Sync it with Git</a> between machines.</td></tr>\n<tr><td>REST API and SDKs</td><td>The <code>wordcell</code> CLI and TypeScript SDK</td><td>See the <a href=\"/docs/reference\">reference</a>.</td></tr>\n</tbody>\n</table>\n<h2 id=\"export-your-data\">Export your data</h2>\n<p>You need a Supermemory API key in <code>SUPERMEMORY_API_KEY</code>, and either curl and\njq or Python 3. Work in a directory outside the vault, so that the export files\nare never committed.</p>\n<p>Documents come from\n<a href=\"https://supermemory.ai/docs/api-reference/documents/list-documents\">list documents</a>\n(<code>POST /v3/documents/list</code>). Memory entries, with their earlier versions, come\nfrom\n<a href=\"https://supermemory.ai/docs/api-reference/content-management/list-memory-entries-with-history\">list memory entries</a>\n(<code>POST /v4/memories/list</code>), which lists entries by container tag. The scripts\nbelow request one tag at a time. They find tags in the <code>containerTags</code> field of\nyour documents, which the list documents reference marks as deprecated, so a\nresponse may leave it out. Pass every container tag you used as an argument.\nThe scripts print the tags they export, and they stop with an error when they\nfind none.</p>\n<p>Save this script as <code>export-supermemory.sh</code>:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--comment\">#!/bin/sh</span>\n<span class=\"syntax-token syntax-token--comment\"># Save Supermemory documents and memory entries as JSON pages in the</span>\n<span class=\"syntax-token syntax-token--comment\"># current directory. Extra arguments are container tags to export</span>\n<span class=\"syntax-token syntax-token--comment\"># in addition to the tags found on your documents.</span>\n<span class=\"syntax-token syntax-token--command\">set</span> <span class=\"syntax-token syntax-token--flag\">-eu</span>\n<span class=\"syntax-token syntax-token--variable\">base=https://api.supermemory.ai</span>\n\n<span class=\"syntax-token syntax-token--command\">post</span><span class=\"syntax-token syntax-token--operator\">(</span><span class=\"syntax-token syntax-token--operator\">)</span> {\n  <span class=\"syntax-token syntax-token--command\">curl</span> <span class=\"syntax-token syntax-token--flag\">-fsS</span> <span class=\"syntax-token syntax-token--string\">&quot;$base$1&quot;</span> \\\n    <span class=\"syntax-token syntax-token--flag\">-H</span> <span class=\"syntax-token syntax-token--string\">&quot;Authorization: Bearer $SUPERMEMORY_API_KEY&quot;</span> \\\n    <span class=\"syntax-token syntax-token--flag\">-H</span> <span class=\"syntax-token syntax-token--string\">&quot;Content-Type: application/json&quot;</span> \\\n    <span class=\"syntax-token syntax-token--flag\">-d</span> <span class=\"syntax-token syntax-token--string\">&quot;$2&quot;</span> <span class=\"syntax-token syntax-token--flag\">-o</span> <span class=\"syntax-token syntax-token--string\">&quot;$3&quot;</span>\n<span class=\"syntax-token syntax-token--command\">}</span>\n\n<span class=\"syntax-token syntax-token--command\">last_page</span><span class=\"syntax-token syntax-token--operator\">(</span><span class=\"syntax-token syntax-token--operator\">)</span> {\n  <span class=\"syntax-token syntax-token--command\">jq</span> <span class=\"syntax-token syntax-token--string\">&#39;.pagination.totalPages // 0&#39;</span> <span class=\"syntax-token syntax-token--string\">&quot;$1&quot;</span>\n<span class=\"syntax-token syntax-token--command\">}</span>\n\n<span class=\"syntax-token syntax-token--variable\">page=1</span>\n<span class=\"syntax-token syntax-token--keyword\">while</span> <span class=\"syntax-token syntax-token--command\">:</span><span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">do</span>\n  <span class=\"syntax-token syntax-token--variable\">file=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span>printf <span class=\"syntax-token syntax-token--string\">&#39;documents-%03d.json&#39;</span> <span class=\"syntax-token syntax-token--string\">&quot;$page&quot;</span><span class=\"syntax-token syntax-token--operator\">)</span>\n  <span class=\"syntax-token syntax-token--command\">post</span> /v3/documents/list <span class=\"syntax-token syntax-token--string\">&quot;{\\&quot;includeContent\\&quot;: true, \\&quot;limit\\&quot;: 100, \\&quot;page\\&quot;: $page, \\&quot;sort\\&quot;: \\&quot;createdAt\\&quot;, \\&quot;order\\&quot;: \\&quot;asc\\&quot;}&quot;</span> <span class=\"syntax-token syntax-token--string\">&quot;$file&quot;</span>\n  <span class=\"syntax-token syntax-token--command\">[</span> <span class=\"syntax-token syntax-token--string\">&quot;$page&quot;</span> <span class=\"syntax-token syntax-token--flag\">-ge</span> <span class=\"syntax-token syntax-token--string\">&quot;$(last_page &quot;</span><span class=\"syntax-token syntax-token--variable\">$file</span><span class=\"syntax-token syntax-token--string\">&quot;)&quot;</span> ] <span class=\"syntax-token syntax-token--operator\">&amp;&amp;</span> <span class=\"syntax-token syntax-token--command\">break</span>\n  <span class=\"syntax-token syntax-token--variable\">page=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span><span class=\"syntax-token syntax-token--operator\">(</span>page + 1<span class=\"syntax-token syntax-token--operator\">)</span><span class=\"syntax-token syntax-token--operator\">)</span>\n<span class=\"syntax-token syntax-token--keyword\">done</span>\n\n<span class=\"syntax-token syntax-token--command\">{</span>\n  <span class=\"syntax-token syntax-token--command\">jq</span> <span class=\"syntax-token syntax-token--flag\">-rn</span> <span class=\"syntax-token syntax-token--string\">&#39;[inputs.memories[].containerTags[]?] | unique[]&#39;</span> documents-*.json\n  <span class=\"syntax-token syntax-token--command\">printf</span> <span class=\"syntax-token syntax-token--string\">&#39;%s\\n&#39;</span> <span class=\"syntax-token syntax-token--string\">&quot;$@&quot;</span>\n<span class=\"syntax-token syntax-token--command\">}</span> <span class=\"syntax-token syntax-token--operator\">|</span> <span class=\"syntax-token syntax-token--command\">sort</span> <span class=\"syntax-token syntax-token--flag\">-u</span> <span class=\"syntax-token syntax-token--operator\">|</span> <span class=\"syntax-token syntax-token--command\">sed</span> <span class=\"syntax-token syntax-token--string\">&#39;/^$/d&#39;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span> container-tags.txt\n\n<span class=\"syntax-token syntax-token--keyword\">if</span> <span class=\"syntax-token syntax-token--command\">[</span> ! <span class=\"syntax-token syntax-token--flag\">-s</span> container-tags.txt ]<span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">then</span>\n  <span class=\"syntax-token syntax-token--command\">echo</span> <span class=\"syntax-token syntax-token--string\">&quot;export-supermemory: no container tags found; pass your tags as arguments&quot;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span><span class=\"syntax-token syntax-token--operator\">&amp;</span>2\n  <span class=\"syntax-token syntax-token--command\">exit</span> 1\n<span class=\"syntax-token syntax-token--keyword\">fi</span>\n<span class=\"syntax-token syntax-token--command\">echo</span> <span class=\"syntax-token syntax-token--string\">&quot;export-supermemory: exporting memory entries for these container tags:&quot;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span><span class=\"syntax-token syntax-token--operator\">&amp;</span>2\n<span class=\"syntax-token syntax-token--command\">cat</span> container-tags.txt <span class=\"syntax-token syntax-token--operator\">&gt;</span><span class=\"syntax-token syntax-token--operator\">&amp;</span>2\n\n<span class=\"syntax-token syntax-token--variable\">n=0</span>\n<span class=\"syntax-token syntax-token--keyword\">while</span> <span class=\"syntax-token syntax-token--command\">read</span> <span class=\"syntax-token syntax-token--flag\">-r</span> tag<span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">do</span>\n  <span class=\"syntax-token syntax-token--variable\">n=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span><span class=\"syntax-token syntax-token--operator\">(</span>n + 1<span class=\"syntax-token syntax-token--operator\">)</span><span class=\"syntax-token syntax-token--operator\">)</span>\n  <span class=\"syntax-token syntax-token--variable\">page=1</span>\n  <span class=\"syntax-token syntax-token--keyword\">while</span> <span class=\"syntax-token syntax-token--command\">:</span><span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">do</span>\n    <span class=\"syntax-token syntax-token--variable\">file=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span>printf <span class=\"syntax-token syntax-token--string\">&#39;memories-%03d-%03d.json&#39;</span> <span class=\"syntax-token syntax-token--string\">&quot;$n&quot;</span> <span class=\"syntax-token syntax-token--string\">&quot;$page&quot;</span><span class=\"syntax-token syntax-token--operator\">)</span>\n    <span class=\"syntax-token syntax-token--variable\">body=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span>jq <span class=\"syntax-token syntax-token--flag\">-cn</span> <span class=\"syntax-token syntax-token--flag\">--arg</span> tag <span class=\"syntax-token syntax-token--string\">&quot;$tag&quot;</span> <span class=\"syntax-token syntax-token--flag\">--argjson</span> page <span class=\"syntax-token syntax-token--string\">&quot;$page&quot;</span> \\\n      <span class=\"syntax-token syntax-token--string\">&#39;{containerTags: [$tag], limit: 100, page: $page, sort: &quot;createdAt&quot;, order: &quot;asc&quot;}&#39;</span><span class=\"syntax-token syntax-token--operator\">)</span>\n    <span class=\"syntax-token syntax-token--command\">post</span> /v4/memories/list <span class=\"syntax-token syntax-token--string\">&quot;$body&quot;</span> <span class=\"syntax-token syntax-token--string\">&quot;$file&quot;</span>\n    <span class=\"syntax-token syntax-token--command\">[</span> <span class=\"syntax-token syntax-token--string\">&quot;$page&quot;</span> <span class=\"syntax-token syntax-token--flag\">-ge</span> <span class=\"syntax-token syntax-token--string\">&quot;$(last_page &quot;</span><span class=\"syntax-token syntax-token--variable\">$file</span><span class=\"syntax-token syntax-token--string\">&quot;)&quot;</span> ] <span class=\"syntax-token syntax-token--operator\">&amp;&amp;</span> <span class=\"syntax-token syntax-token--command\">break</span>\n    <span class=\"syntax-token syntax-token--variable\">page=</span><span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span><span class=\"syntax-token syntax-token--operator\">(</span>page + 1<span class=\"syntax-token syntax-token--operator\">)</span><span class=\"syntax-token syntax-token--operator\">)</span>\n  <span class=\"syntax-token syntax-token--keyword\">done</span>\n<span class=\"syntax-token syntax-token--keyword\">done</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span> container-tags.txt\n</code></pre></div></figure>\n<p>Run it with your container tags as arguments:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">sh</span> export-supermemory.sh <span class=\"syntax-token syntax-token--operator\">&lt;</span>tag<span class=\"syntax-token syntax-token--operator\">&gt;</span>...\n</code></pre></div></figure>\n<p>Compare the tags it prints with the tags your application sends, or with the\nspaces that the <code>list_spaces</code> tool of the\n<a href=\"https://supermemory.ai/docs/supermemory-mcp/mcp\">hosted MCP server</a> shows. Run\nit again with any tag it missed.</p>\n<p>The script writes one file per page: <code>documents-001.json</code> and onward, then\n<code>memories-001-001.json</code> and onward for each tag in <code>container-tags.txt</code>. It\nrequests 100 items per page in ascending creation order, so the pages stay\nstable while it runs, and it stops after the last page that\n<code>pagination.totalPages</code> reports. It stops at the first failed request and\nprints the HTTP status.</p>\n<p><code>&quot;includeContent&quot;: true</code> adds each document’s full text, which the API\nreference notes can make responses much larger. Without it, each note holds\nonly the document’s summary.</p>\n<p>The API reference marks the <code>containerTags</code> array as required, while the\n<a href=\"https://supermemory.ai/docs/concepts/container-tags\">container tags page</a> says\nthe <code>/v4</code> API accepts only <code>containerTag</code>. If <code>/v4/memories/list</code> returns status\n400, replace <code>containerTags: [$tag]</code> with <code>containerTag: $tag</code> in the script\nand run it again.</p>\n<p>With Python 3 in place of curl and jq, save this script as\n<code>export_supermemory.py</code>. It saves every page in one file,\n<code>supermemory-export.json</code>, and takes the same tag arguments:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">&quot;&quot;&quot;Save every Supermemory document and memory entry to supermemory-export.json.\n\nExtra arguments are container tags to export in addition to the tags\nfound on your documents.\n&quot;&quot;&quot;\nimport json\nimport os\nimport sys\nimport urllib.request\n\nBASE = &quot;https://api.supermemory.ai&quot;\nKEY = os.environ[&quot;SUPERMEMORY_API_KEY&quot;]\n\n\ndef post(path, body):\n    request = urllib.request.Request(\n        BASE + path,\n        data=json.dumps(body).encode(),\n        headers={\n            &quot;Authorization&quot;: f&quot;Bearer {KEY}&quot;,\n            &quot;Content-Type&quot;: &quot;application/json&quot;,\n            &quot;User-Agent&quot;: &quot;supermemory-export&quot;,\n        },\n    )\n    with urllib.request.urlopen(request) as response:\n        return json.load(response)\n\n\ndef pages(path, body):\n    page = 1\n    while True:\n        query = {**body, &quot;limit&quot;: 100, &quot;page&quot;: page, &quot;sort&quot;: &quot;createdAt&quot;, &quot;order&quot;: &quot;asc&quot;}\n        result = post(path, query)\n        yield result\n        if page &gt;= ((result.get(&quot;pagination&quot;) or {}).get(&quot;totalPages&quot;) or 0):\n            return\n        page += 1\n\n\nexport = list(pages(&quot;/v3/documents/list&quot;, {&quot;includeContent&quot;: True}))\nfound = {tag for p in export for d in p[&quot;memories&quot;] for tag in d.get(&quot;containerTags&quot;) or []}\ntags = sorted(found | set(sys.argv[1:]))\nif not tags:\n    sys.exit(&quot;export_supermemory: no container tags found; pass your tags as arguments&quot;)\nprint(&quot;Exporting memory entries for these container tags:&quot;, *tags, sep=&quot;\\n&quot;, file=sys.stderr)\nfor tag in tags:\n    export.extend(pages(&quot;/v4/memories/list&quot;, {&quot;containerTags&quot;: [tag]}))\n\nwith open(&quot;supermemory-export.json&quot;, &quot;w&quot;, encoding=&quot;utf-8&quot;) as out:\n    json.dump(export, out)\nprint(f&quot;Saved {len(export)} pages to supermemory-export.json&quot;)\n</code></pre>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">python3</span> export_supermemory.py <span class=\"syntax-token syntax-token--operator\">&lt;</span>tag<span class=\"syntax-token syntax-token--operator\">&gt;</span>...\n</code></pre></div></figure>\n<h2 id=\"import-into-a-vault\">Import into a vault</h2>\n<ol>\n<li>Create a vault if you do not have one: <code>wordcell init kb</code>.</li>\n<li>Preview the import:\n<code>wordcell import supermemory documents-*.json memories-*.json --root kb --dry-run</code>.\nWith the Python script, name <code>supermemory-export.json</code> in place of the two\npatterns.</li>\n<li>Read the summary. It counts what the import would create, update, skip,\nreport as a conflict, or reject. Each <code>diagnostic</code> line names a value the\nimporter dropped or a relation it left out.</li>\n<li>Import: run the same command without <code>--dry-run</code>.</li>\n<li>Rebuild the catalog: <code>wordcell refresh --root kb</code>.</li>\n<li>Check the vault: <code>wordcell check --root kb</code>.</li>\n</ol>\n<p>For example, a dry run over pages built from the importer’s\n<a href=\"https://github.com/hraness/wordcell/tree/main/src/fixtures/supermemory\">test fixtures</a>\nprinted:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">Dry run of 11 items from 7 files: created 10, updated 0, skipped 1, conflicts 0, rejected 0. Nothing was written.\nWould add 2 supersedes relations.\ndiagnostic: memoryRelations are the service&#39;s inferred links and were not imported\ndiagnostic: notes/imported/nested-metadata: metadata.author is a nested value; dropped\ndiagnostic: notes/imported/nested-metadata: metadata key &quot;bad key&quot; is not a safe key; dropped\ndiagnostic: notes/imported/nested-metadata: metadata.labels is a nested value; dropped\ndiagnostic: notes/imported/zr8tqw3nhc6ypd1fgk5lmv: status is &quot;queued&quot;; the imported text may be incomplete\ndiagnostic: notes/imported/memories/prefers-dark-mode-in-every-editor-and-terminal: metadata.context is a nested value; dropped\ndiagnostic: notes/imported/memories/works-from-berlin-utc-1-in-winter: parent memory mem_timezone_v1 was not imported; supersedes relation omitted\n</code></pre>\n<p>The skipped item was a forgotten memory entry. Apart from the <code>supersedes</code>\nrelations between memory versions, imported notes have no contextual links to\neach other, so <code>wordcell check</code> lists most of them as contextual orphans. That\nlist is advisory and does not fail the check.</p>\n<p>You can export and import again at any time. The importer updates notes you\nhave not edited, skips unchanged ones, and leaves a note you edited after the\nlast import unchanged, with a line such as\n<code>conflict: &lt;note&gt; from &lt;file&gt;#&lt;pointer&gt; (&lt;id&gt;): the note was edited after the last import</code>.\nConflicts do not change the exit status. <a href=\"/docs/reference#import-again\">Import again</a>\ndescribes each outcome, and <a href=\"/docs/reference#frontmatter\">Frontmatter</a> lists the\nfields each note records.</p>\n<h2 id=\"verify-the-result\">Verify the result</h2>\n<p>List the imported notes:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> list <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--where</span> <span class=\"syntax-token syntax-token--variable\">imported_from=supermemory</span>\n</code></pre></div></figure>\n<p>Search for a phrase you remember saving:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;dark mode&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p>Follow a memory entry’s earlier versions:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> relation list notes/imported/memories/<span class=\"syntax-token syntax-token--operator\">&lt;</span>slug<span class=\"syntax-token syntax-token--operator\">&gt;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<p>Commit the result. Skip <code>git init</code> when the vault is inside a project\nrepository.</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">cd</span> kb\n<span class=\"syntax-token syntax-token--command\">git</span> init <span class=\"syntax-token syntax-token--flag\">-b</span> main\n<span class=\"syntax-token syntax-token--command\">git</span> add <span class=\"syntax-token syntax-token--flag\">-A</span>\n<span class=\"syntax-token syntax-token--command\">git</span> commit <span class=\"syntax-token syntax-token--flag\">-m</span> <span class=\"syntax-token syntax-token--string\">&quot;Import Supermemory export&quot;</span>\n</code></pre></div></figure>\n<p>To keep the vault current on several machines, see\n<a href=\"/docs/sync\">Sync a vault with Git</a>.</p>\n<h2 id=\"connect-your-agent\">Connect your agent</h2>\n<p><code>wordcell mcp</code> serves the vault to a local Model Context Protocol client over\nstandard input and output. It runs on your machine and needs no account. With\nClaude Code, run this in your project:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">claude</span> mcp add <span class=\"syntax-token syntax-token--flag\">--transport</span> stdio <span class=\"syntax-token syntax-token--flag\">--scope</span> project wordcell <span class=\"syntax-token syntax-token--flag\">--</span> wordcell mcp <span class=\"syntax-token syntax-token--flag\">--root</span> /absolute/path/to/kb\n</code></pre></div></figure>\n<p><a href=\"/docs/reference#connect-a-client\">Connect a client</a> has the settings for Claude\nDesktop, Cursor, and Codex, and <a href=\"/docs/reference#tools\">Tools</a> lists what each\ntool accepts. Add <code>--read-only</code> to remove the three write tools.</p>\n<p>Supermemory builds a profile of each user on its own. In a vault, keep one\nmaintained note in its place: <code>notes/profile.md</code> with <code>type: profile</code> and two\nsections, “Stable” for lasting facts and “Recent” for current work. Ask your\nagent to read it at the start of each session with <code>get_note</code> and to revise it\nwith <code>update_note_body</code>, which takes the revision that <code>get_note</code> returned. The\nWordcell skill describes this convention in\n<a href=\"https://github.com/hraness/wordcell/blob/main/skills/wordcell/references/session-memory.md#keep-a-profile-note\">Keep a profile note</a>.</p>\n<h2 id=\"replace-connectors\">Replace connectors</h2>\n<p>Supermemory <a href=\"https://supermemory.ai/docs/connectors/overview\">connectors</a> pull\ncontent from sources such as Google Drive, Gmail, Notion, OneDrive, GitHub, and\nwebsites, and keep it current with webhooks and scheduled syncs. Wordcell has no\nconnectors. Save what you want your agent to know as Markdown files in the\nvault, check it, and commit. Wordcell reads Markdown files without frontmatter\nas notes, and <a href=\"/docs/sync\">Sync a vault with Git</a> commits and pushes on a\nschedule.</p>\n<h3 id=\"google-drive-onedrive-or-dropbox\">Google Drive, OneDrive, or Dropbox</h3>\n<p>In Google Docs, choose File, then Download, then Markdown (.md) to save one\ndocument as a Markdown file\n(<a href=\"https://support.google.com/docs/answer/12014036\">Google Docs Help</a>). Copy\nMarkdown files out of a synced OneDrive or Dropbox folder. Move the files into a\nfolder in the vault and check it:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">mkdir</span> <span class=\"syntax-token syntax-token--flag\">-p</span> kb/notes/drive\n<span class=\"syntax-token syntax-token--command\">mv</span> ~/Downloads/meeting-notes.md kb/notes/drive/\n<span class=\"syntax-token syntax-token--command\">wordcell</span> refresh <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n<span class=\"syntax-token syntax-token--command\">wordcell</span> check <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<p>Convert a PDF into the vault with\n<code>wordcell pdf &lt;file&gt; --output kb/articles</code>\n(<a href=\"/docs/pdf\">Capture PDF documents</a>).</p>\n<h3 id=\"gmail\">Gmail</h3>\n<p>Google Takeout downloads your mail from Gmail\n(<a href=\"https://support.google.com/accounts/answer/3024190\">How to download your Google data</a>),\nbut Wordcell has no mail importer. Save the messages worth keeping as notes\ninstead: ask your agent to write a note from a message with the <code>create_note</code>\ntool, or pipe the text into <code>wordcell note create</code> with <code>--body-file -</code>. On\nmacOS, pipe the text you copied:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">mkdir</span> <span class=\"syntax-token syntax-token--flag\">-p</span> kb/notes/mail\n<span class=\"syntax-token syntax-token--command\">pbpaste</span> <span class=\"syntax-token syntax-token--operator\">|</span> <span class=\"syntax-token syntax-token--command\">wordcell</span> note create notes/mail/launch-date <span class=\"syntax-token syntax-token--flag\">--title</span> <span class=\"syntax-token syntax-token--string\">&quot;Launch date&quot;</span> <span class=\"syntax-token syntax-token--flag\">--body-file</span> <span class=\"syntax-token syntax-token--flag\">-</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<p>The folder must exist before <code>note create</code> writes into it.</p>\n<h3 id=\"github\">GitHub</h3>\n<p>Keep the vault in the repository, as <code>kb/</code> beside the code, and your notes\ntravel with every clone (<a href=\"/docs/sync#choose-where-the-vault-lives\">Choose where the vault lives</a>).\n<code>wordcell context</code> then lists the guides and notes that apply to a path:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> context src/index.ts <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--repo</span> .\n</code></pre></div></figure>\n<p>To keep an issue from another repository, save its text as a note with the\n<a href=\"https://cli.github.com/manual/gh_issue_view\">GitHub CLI</a>:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">mkdir</span> <span class=\"syntax-token syntax-token--flag\">-p</span> kb/notes/github\n<span class=\"syntax-token syntax-token--command\">gh</span> issue view 42 <span class=\"syntax-token syntax-token--flag\">--repo</span> owner/repo <span class=\"syntax-token syntax-token--flag\">--json</span> body <span class=\"syntax-token syntax-token--flag\">--jq</span> .body <span class=\"syntax-token syntax-token--operator\">|</span>\n  <span class=\"syntax-token syntax-token--command\">wordcell</span> note create notes/github/owner-repo-42 <span class=\"syntax-token syntax-token--flag\">--title</span> <span class=\"syntax-token syntax-token--string\">&quot;owner/repo#42&quot;</span> <span class=\"syntax-token syntax-token--flag\">--body-file</span> <span class=\"syntax-token syntax-token--flag\">-</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<h3 id=\"web-pages\">Web pages</h3>\n<p>Supermemory’s <a href=\"https://supermemory.ai/docs/connectors/web-crawler\">web crawler</a>\ncrawls a site and recrawls it on a schedule. <code>wordcell clip</code> captures one page\nas a Markdown bundle under <code>articles/</code>, and Git records each change. Save this\nscript as <code>~/bin/clip-pages.sh</code>. It captures each page in a list again and\nprints what changed since the last commit:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--comment\">#!/bin/sh</span>\n<span class=\"syntax-token syntax-token--comment\"># Capture each page in a list again and show what changed since the</span>\n<span class=\"syntax-token syntax-token--comment\"># last commit. Each line of the list is a slug, a space, and a URL.</span>\n<span class=\"syntax-token syntax-token--variable\">vault=</span><span class=\"syntax-token syntax-token--string\">&quot;${1:?usage: clip-pages.sh &lt;vault directory&gt; &lt;page list&gt;}&quot;</span>\n<span class=\"syntax-token syntax-token--variable\">list=</span><span class=\"syntax-token syntax-token--string\">&quot;${2:?usage: clip-pages.sh &lt;vault directory&gt; &lt;page list&gt;}&quot;</span>\n<span class=\"syntax-token syntax-token--variable\">PATH=</span><span class=\"syntax-token syntax-token--string\">&quot;$HOME/.bun/bin:$PATH&quot;</span>\n<span class=\"syntax-token syntax-token--variable\">status=0</span>\n\n<span class=\"syntax-token syntax-token--keyword\">while</span> <span class=\"syntax-token syntax-token--command\">read</span> <span class=\"syntax-token syntax-token--flag\">-r</span> slug url<span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">do</span>\n  <span class=\"syntax-token syntax-token--command\">[</span> <span class=\"syntax-token syntax-token--flag\">-n</span> <span class=\"syntax-token syntax-token--string\">&quot;$url&quot;</span> ] <span class=\"syntax-token syntax-token--operator\">||</span> <span class=\"syntax-token syntax-token--command\">continue</span>\n  <span class=\"syntax-token syntax-token--keyword\">if</span> <span class=\"syntax-token syntax-token--command\">wordcell</span> clip <span class=\"syntax-token syntax-token--string\">&quot;$url&quot;</span> <span class=\"syntax-token syntax-token--string\">&quot;$slug&quot;</span> <span class=\"syntax-token syntax-token--flag\">--output</span> <span class=\"syntax-token syntax-token--string\">&quot;$vault/articles&quot;</span> <span class=\"syntax-token syntax-token--flag\">--force</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span>/dev/null<span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">then</span>\n    <span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff <span class=\"syntax-token syntax-token--string\">&quot;$vault/articles/$slug&quot;</span> <span class=\"syntax-token syntax-token--flag\">--repo</span> <span class=\"syntax-token syntax-token--string\">&quot;$vault&quot;</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span>/dev/null\n  <span class=\"syntax-token syntax-token--keyword\">else</span>\n    <span class=\"syntax-token syntax-token--command\">echo</span> <span class=\"syntax-token syntax-token--string\">&quot;clip-pages: could not capture $url&quot;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span><span class=\"syntax-token syntax-token--operator\">&amp;</span>2\n    <span class=\"syntax-token syntax-token--variable\">status=1</span>\n  <span class=\"syntax-token syntax-token--keyword\">fi</span>\n<span class=\"syntax-token syntax-token--keyword\">done</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span><span class=\"syntax-token syntax-token--string\">&quot;$list&quot;</span>\n\n<span class=\"syntax-token syntax-token--command\">wordcell</span> refresh <span class=\"syntax-token syntax-token--flag\">--root</span> <span class=\"syntax-token syntax-token--string\">&quot;$vault&quot;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span>/dev/null <span class=\"syntax-token syntax-token--operator\">||</span> <span class=\"syntax-token syntax-token--variable\">status=1</span>\n<span class=\"syntax-token syntax-token--command\">exit</span> <span class=\"syntax-token syntax-token--string\">&quot;$status&quot;</span>\n</code></pre></div></figure>\n<p>List the pages in <code>~/kb-pages.txt</code>:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">example-domain https://example.com/\n</code></pre>\n<p>Then run it once a day before the sync script. With cron, add this line\n(<code>crontab -e</code>):</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">0 6 * * * /bin/sh &quot;$HOME/bin/clip-pages.sh&quot; &quot;$HOME/kb&quot; &quot;$HOME/kb-pages.txt&quot; &gt;&gt;&quot;$HOME/clip-pages.log&quot; 2&gt;&amp;1\n</code></pre>\n<p>The script expects the vault to be its own repository, as in\n<a href=\"/docs/sync\">Sync a vault with Git</a>. Cron starts jobs with a short <code>PATH</code>, so the\nscript adds <code>~/.bun/bin</code>. If <code>command -v wordcell</code> or <code>command -v bun</code> prints\nanother directory, add that one too. <code>--force</code> replaces the whole bundle, so\nedits inside a clipped file are lost on the next run. Write your own notes\nabout a page in a separate note that links to it. Wordcell captures only the\npages you list and does not follow links. <a href=\"/docs/capture\">Capture web content</a>\nand <code>wordcell clip --help</code> cover the slug argument, <code>--force</code>, signed-in pages,\nand other options.</p>\n<h3 id=\"notion\">Notion</h3>\n<p>Notion exports a page, and optionally its subpages, as a zip file of Markdown\nand CSV files\n(<a href=\"https://www.notion.com/help/export-your-content\">Export your content</a>).\nUnzip it into the vault:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">mkdir</span> <span class=\"syntax-token syntax-token--flag\">-p</span> kb/notes/notion\n<span class=\"syntax-token syntax-token--command\">unzip</span> ~/Downloads/notion-export.zip <span class=\"syntax-token syntax-token--flag\">-d</span> kb/notes/notion\n<span class=\"syntax-token syntax-token--command\">wordcell</span> refresh <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n<span class=\"syntax-token syntax-token--command\">wordcell</span> check <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<p>Search finds the pages right away. Wordcell ignores the CSV files, and\n<code>wordcell check</code> may list the pages as orphans, which is advice, not an error.</p>\n<h2 id=\"what-does-not-transfer\">What does not transfer</h2>\n<p>The hosted features named in\n<a href=\"#who-should-switch-and-who-should-stay\">Who should switch and who should stay</a>\nhave no Wordcell equivalent. Neither do these:</p>\n<ul>\n<li>The relations Supermemory infers between memories, such as Derives, and its\ntime-based forgetting\n(<a href=\"https://supermemory.ai/docs/concepts/graph-memory\">graph memory</a>).</li>\n<li>Spaces, widgets, and OAuth sign-in in the hosted MCP server\n(<a href=\"https://supermemory.ai/docs/supermemory-mcp/mcp\">Supermemory MCP</a>).</li>\n</ul>\n",
-  "capture": "<h1 id=\"capture-web-content\">Capture web content</h1>\n<p><code>wordcell clip</code> saves public and signed-in web content as an auditable Markdown bundle. It combines bounded structured adapters, HTTP extraction, browser rendering, a read-only Archive.today fallback, localized assets, and explicit completeness metadata.</p>\n<h2 id=\"check-local-capabilities\">Check local capabilities</h2>\n<p>Run the diagnostics before using local search, browser state, PDF ingestion, or video capture:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> doctor\n<span class=\"syntax-token syntax-token--command\">wordcell</span> adapters\n</code></pre></div></figure>\n<p><code>wordcell doctor --json</code> reports the installed runtime, QMD and static semantic-search\nprerequisites, extraction dependencies, browser support, profile display names,\nyt-dlp, ffmpeg, Poppler (<code>pdfinfo</code> and <code>pdftohtml</code>), and Tesseract. The semantic\nreport distinguishes model-free keyword readiness from SQLite and sqlite-vec\nvector prerequisites; it does not inspect or download the embedding model. The\nPoppler pair is required by <code>wordcell pdf</code>; Tesseract adds local OCR for scans and\nscreenshots.\n<code>wordcell adapters --json</code> returns the current platform capability matrix.</p>\n<h2 id=\"capture-or-inspect-a-page\">Capture or inspect a page</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article\n<span class=\"syntax-token syntax-token--command\">wordcell</span> inspect https://example.com/article\n<span class=\"syntax-token syntax-token--command\">wordcell</span> inspect https://example.com/article <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The default route tries stable public structured data when available, bounded HTTP extraction, and a rendered browser when the platform or result requires one. If those routes produce no usable representation, Wordcell may make one read-only lookup for the exact URL through Archive.today's fixed <code>archive.ph/newest/</code> route. An authentication, paywall, CAPTCHA, access-control, or rate-limit response disables that fallback instead of using an archive to bypass the current source's controls. Wordcell never submits the URL for archiving, retries through aliases, or lets archived HTML displace a complete or partial Hacker News or Bluesky structured capture. It validates the source through the public-network boundary before disclosure, shares one deadline across validation and provider requests, and binds every snapshot and redirect to the exact source. An archived result is rescored and always reported as <code>partial</code>; it keeps the original canonical URL and records the timestamped snapshot as its acquisition URL. Inspection returns the selected Markdown and capture report without writing artifacts.</p>\n<p>By default, a capture writes <code>kb/articles/&lt;slug&gt;/</code>:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">&lt;slug&gt;/\n  &lt;slug&gt;.md\n  capture.json\n  url-metadata.json # after an optional metadata backfill\n  assets/\n  evidence/       # only when requested\n</code></pre>\n<p>The Markdown records source and capture metadata. <code>capture.json</code> records the acquisition attempts, selected extractor, scope, status, item counts, warnings, asset hashes, and requested artifact outcomes. The optional <code>url-metadata.json</code> is a separate tool-owned enrichment record. It does not rewrite acquisition provenance in <code>capture.json</code>. Writes stage beside the target and install with an atomic rename. <code>--force</code> replaces only a compatible clip-owned bundle and restores the previous bundle if installation fails.</p>\n<p>Set <code>KB_CLIP_OUTPUT</code> to change the default output root, or pass <code>--output &lt;directory&gt;</code> for one command. Set <code>KB_CLIP_USER_AGENT</code> or pass <code>--user-agent &lt;value&gt;</code> to override the default request user agent.</p>\n<h2 id=\"inspect-and-verify-a-saved-bundle\">Inspect and verify a saved bundle</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example <span class=\"syntax-token syntax-token--flag\">--verify-assets</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture verify kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture verify kb/articles/example <span class=\"syntax-token syntax-token--flag\">--verify-assets</span> <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p><code>show</code> reads the document, compares its v4 byte count and digest when present, and prints its Markdown as untrusted data. <code>verify</code> reports integrity without printing the document in its text output. Add <code>--verify-assets</code> to either command to read and hash every listed asset. A mismatch or an unavailable authoritative document digest returns exit status 3.</p>\n<p>The JSON forms preserve the same disclosure boundary: <code>show --json</code> includes the stored Markdown as explicitly untrusted inspection data, while <code>verify --json</code> returns only integrity metadata and issues. Verification JSON omits both the Markdown and retained source HTML so an integrity check does not accidentally disclose captured content.</p>\n<p>Schema v4 records <code>document.path</code>, <code>document.bytes</code>, and <code>document.sha256</code> in <code>capture.json</code>. The lowercase SHA-256 digest covers the exact credential-redacted, newline-terminated Markdown bytes that Wordcell writes. It does not cover <code>capture.json</code>, source HTML, or assets. Each asset has a separate byte count and SHA-256 digest. Schema versions one through three report document integrity as <code>unavailable</code> because they do not contain the v4 document record; <code>verify</code> does not present that state as success.</p>\n<p>When asset verification is requested, a listed asset that is absent is an integrity mismatch rather than an operational reader crash. It produces an <code>asset-integrity</code> issue and exit status 3, like a digest or byte-count mismatch. Structural alias, link, confinement, and resource-budget failures remain operational errors because the reader cannot safely characterize the requested bytes.</p>\n<p>Bundle inspection keeps the canonical root open, rejects linked or aliased path ancestors and linked leaves, and rechecks root, ancestor, and file identities around every read. Asset verification is also bounded by file count, per-file bytes, aggregate bytes, and elapsed time. The SDK defaults are 1,000 files, 100 MB per file, 500 MB total, and 30 seconds; callers may raise them only to the capture contract's hard ceilings. These checks protect against hostile stored bundle structure and ordinary concurrent replacement. A malicious process with the same filesystem authority that can swap and restore path components during a system call is outside the pure-JavaScript reader's boundary; do not inspect bundles in a directory concurrently writable by an untrusted local process.</p>\n<p>Source HTML remains opt-in when you read a bundle:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example <span class=\"syntax-token syntax-token--flag\">--include-source-html</span>\n</code></pre></div></figure>\n<p>This flag has an effect only when the capture used <code>--evidence source</code> or <code>--evidence all</code>. Wordcell removes active subtrees and form state, redacts credential-shaped values, and stores the result as inert HTML. Treat the retained text as hostile data, not instructions. It can still contain private content or text intended to influence an agent.</p>\n<h2 id=\"use-git-for-capture-history\">Use Git for capture history</h2>\n<p>Commit retained capture bundles to Git, then compare the current Markdown document with an earlier revision:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff /path/to/repository/kb/articles/example <span class=\"syntax-token syntax-token--flag\">--repo</span> /path/to/repository <span class=\"syntax-token syntax-token--flag\">--ref</span> main\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff kb/articles/example <span class=\"syntax-token syntax-token--flag\">--repo</span> . <span class=\"syntax-token syntax-token--flag\">--ref</span> main <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The bundle must be inside the selected repository. The default reference is <code>HEAD</code>; <code>--ref</code> accepts a bounded branch, tag, or commit name, not a revision expression such as <code>HEAD~1</code>. Wordcell validates the work tree and ref separately, so a bad repository or ref is not mislabeled as a missing file. The command reports <code>changed</code>, <code>unchanged</code>, or <code>missing-at-ref</code> for the exact Markdown path and emits a bounded Git diff when it changed. It rereads and matches the capture digest after diff generation, rejecting a concurrent change instead of pairing one digest with another snapshot's diff. It does not compare the manifest, source HTML, or assets. Run <code>wordcell capture verify</code> separately when integrity matters. Git is the capture version history; Wordcell does not maintain a second content-history database.</p>\n<h2 id=\"track-capture-jobs-programmatically\">Track capture jobs programmatically</h2>\n<p>Use the optional <code>@hraness/wordcell/clip/jobs</code> ledger when a service needs durable capture progress:</p>\n<pre><code class=\"syntax-code language-typescript\" data-language=\"typescript\"><span class=\"sh__line\"><span class=\"sh__token--keyword\">import</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">completeCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">createCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">openCaptureJobStore</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">updateCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">from</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">@hraness/wordcell/clip/jobs</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">const</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">openCaptureJobStore</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">/absolute/path/to/capture-jobs</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">let</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">createCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">target</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">https://example.com/article</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">updateCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">id</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">expectedRevision</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">revision</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">phase</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">acquiring</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">completeCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">id</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">expectedRevision</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">revision</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">status</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">complete</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>Create the dedicated canonical mode-0700 store directory before opening it, and pass the returned store to every operation. The opener rejects filesystem aliases, links, and group/world access. Each job is one private, bounded UUID JSON record. Creation starts revision 1 in <code>running</code> and <code>queued</code>; updates require the expected revision, append attempts and warnings, and move phases forward. Completion records a capture status. It can also record <code>bundle: { path, sha256 }</code>; use <code>capture.json</code>'s v4 <code>document.sha256</code> as <code>sha256</code> because the ledger does not calculate a separate bundle digest. <code>failCaptureJob</code> records an operational error separately from capture status. <code>readCaptureJob</code> and <code>listCaptureJobs</code> inspect retained records. A terminal <code>completed</code> or <code>failed</code> record cannot transition again, and a process crash leaves the last <code>running</code> record visible.</p>\n<p>The ledger redacts credential-shaped values and strips terminal controls from targets, attempts, warnings, bundle paths, and errors. A store-local, heartbeat-backed filesystem lease serializes cooperating processes across revision validation, atomic whole-record replacement, record verification, and directory synchronization; exactly one same-revision transition can succeed. There is no shared append log. Records remain until the caller applies an explicit external retention policy. The module provides no delete or automatic pruning API, and it does not replace Git as capture history. The lease is a same-host coordination mechanism, not a distributed lock for multi-host network filesystems, and a malicious same-user writer with direct store access remains outside its guarantee.</p>\n<h2 id=\"select-acquisition-and-scope\">Select acquisition and scope</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--mode</span> http\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/application <span class=\"syntax-token syntax-token--flag\">--mode</span> browser\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/post <span class=\"syntax-token syntax-token--flag\">--scope</span> page\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/post <span class=\"syntax-token syntax-token--flag\">--scope</span> thread\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/discussion <span class=\"syntax-token syntax-token--flag\">--scope</span> comments\n</code></pre></div></figure>\n<p><code>auto</code> is the normal acquisition mode. <code>http</code> disables browser fallback but retains the final read-only archive lookup. <code>browser</code> requires rendered state and does not query Archive.today. Saved HTML can be imported without browser automation:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--html</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_SAVED_HTML&quot;</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--html</span> <span class=\"syntax-token syntax-token--flag\">-</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span> page.html\n</code></pre></div></figure>\n<p>Default resource bounds are 30 seconds per request, process, or extraction operation; 500 scoped items; depth 16; 25 MB of HTML; 100 MB per asset; and 500 MB across assets. Browser observation also has fixed DOM and scroll ceilings. Reaching a bound is recorded and can downgrade a result to <code>partial</code>.</p>\n<h2 id=\"capture-images-media-and-evidence\">Capture images, media, and evidence</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--media</span> none\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--media</span> images\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/video <span class=\"syntax-token syntax-token--flag\">--media</span> all\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> source\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> screenshot\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> all\n</code></pre></div></figure>\n<p>Image downloads are signature-checked, content-addressed, byte-bounded, and\nrewritten to relative bundle paths. Failed images remain inert links. Video\nposters and thumbnails exposed by the page are localized without downloading\nthe full video.</p>\n<p>For YouTube, the normal capture route uses yt-dlp to retain the title,\ndescription, duration, channel, thumbnail, and one exact-language transcript\nwhen those fields are available. Full audio/video download remains opt-in:\n<code>--media all</code> invokes yt-dlp for accessible media, and ffmpeg may be required\nfor merging or remuxing.</p>\n<p>Source evidence is sanitized into inert HTML with credential-shaped values redacted and a deny-all content security policy. Screenshots are viewport-only pixels and are not structurally sanitized. They may contain private content or notifications, so review them before retaining or sharing a bundle.</p>\n<h2 id=\"capture-a-signed-in-page\">Capture a signed-in page</h2>\n<p>If the page is already open, read the current tab without navigating it:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip current <span class=\"syntax-token syntax-token--flag\">--browser-live</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip current <span class=\"syntax-token syntax-token--flag\">--cdp</span> 9222\n</code></pre></div></figure>\n<p>For <code>--browser-live</code>, first enable Chrome's local debugging connection at <code>chrome://inspect/#remote-debugging</code> (Chrome 144+). If Chrome was launched with an explicit loopback debugging port, pass that numeric port to <code>--cdp</code> instead.</p>\n<p>To open a URL with existing browser state, select a profile name or path. Path-backed profiles run from a temporary copy, so the source profile is unchanged:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--browser-profile</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_CAPTURE_PROFILE&quot;</span>\n</code></pre></div></figure>\n<p>Cookie-backed HTTP capture is useful when the page does not require local storage, IndexedDB, or other browser-only state:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--cookie-source</span> chrome <span class=\"syntax-token syntax-token--flag\">--cookie-profile</span> <span class=\"syntax-token syntax-token--string\">&quot;Default&quot;</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--cookies-file</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_COOKIES_FILE&quot;</span>\n</code></pre></div></figure>\n<p>Choose at most one browser session and one cookie input. A browser session may use a separate cookie input for later asset or media downloads because attached browser state is not exported.</p>\n<p>On a Mac, reading Chrome, Arc, Brave, Chromium, or Edge cookies asks the keychain for that browser's &quot;Safe Storage&quot; key. The dialog names <code>security</code>, the macOS tool Wordcell uses to read it, so Wordcell prints a note first that says why. Enter your Mac password if asked, then choose Always Allow so macOS doesn't ask again. Wordcell never stores the key. If you deny the request, Wordcell says so and suggests <code>--cookies-file</code>. Safari cookies need Full Disk Access for your terminal app, because macOS doesn't ask for it. Turn it on in System Settings › Privacy &amp; Security › Full Disk Access.</p>\n<p>Current-tab capture issues no navigation, click, form, typing, upload, or submit command. URL-based browser capture may navigate and scroll within fixed work limits, taking bounded observations as content is rendered. Both routes are ingestion-only: they do not post, like, follow, send, delete, or submit.</p>\n<h2 id=\"interpret-status-and-counts\">Interpret status and counts</h2>\n<p>Capture status is one of:</p>\n<ul>\n<li><code>complete</code>: the selected bounded representation was acquired without a known missing boundary.</li>\n<li><code>partial</code>: useful content was retained, but a count, cursor, configured bound, hidden branch, or generic rendered representation prevents a completeness claim.</li>\n<li><code>auth-required</code>: the selected routes reached an authentication gate.</li>\n<li><code>blocked</code>: the source returned a block or verification shell.</li>\n<li><code>unsupported</code>: no route produced a usable representation.</li>\n</ul>\n<p>For page scope, counts cover primary entries. For thread and comment scopes, counts cover replies or comments and exclude roots, quotes, ancestors, and pagination markers. Generic rendered conversations often report <code>capturedItems: 0</code> because visible prose does not prove a trustworthy per-item tree.</p>\n<p>A <code>complete</code> or <code>partial</code> capture exits with status 0. Authentication, blocked, and unsupported outcomes use status 3. Argument errors use status 2, environment diagnostic failures use status 4, and operational errors use status 1. Automation should inspect the structured status and warnings rather than relying only on the process exit code.</p>\n<h2 id=\"platform-routes\">Platform routes</h2>\n<ul>\n<li>Hacker News uses the official Firebase item API for bounded recursive discussions.</li>\n<li>Bluesky uses public AT Protocol resolution and thread APIs.</li>\n<li>Reddit first tries its unofficial public listing JSON and falls back when that surface is denied or changes.</li>\n<li>X uses article extraction plus rendered capture; unloaded or virtualized replies remain partial.</li>\n<li>Substack uses article extraction and a signed-in browser for subscriber text when selected.</li>\n<li>GitHub issues, pull requests, and discussions use the Defuddle GitHub extractor, with a signed-in browser fallback for private repositories.</li>\n<li>Discourse topics use the Defuddle Discourse extractor and rendered fallback.</li>\n<li>YouTube adds bounded yt-dlp video context—title, description, duration,\nchannel, thumbnail, and an available exact-language transcript—to HTTP or\nrendered page capture. Full audio/video remains opt-in with <code>--media all</code>.</li>\n<li>Instagram, Facebook, LinkedIn, TikTok, Threads, WhatsApp Web, and arbitrary\napplications use rendered or saved-HTML capture. They do not gain a\ntrustworthy item tree without a dedicated adapter.</li>\n</ul>\n<p>Platform markup and endpoints change. Run <code>wordcell adapters</code> for the installed version's current claims.</p>\n<h2 id=\"backfill-saved-url-metadata\">Backfill saved URL metadata</h2>\n<p>The URL metadata command enriches every external URL record under <code>articles/</code>, including legacy web clips and remote PDF sources. It skips local-only PDFs. It writes one sibling <code>url-metadata.json</code> without changing the source Markdown or synthesizing an old capture manifest.</p>\n<p>Build the isolated Rust helper, then run the resumable backfill:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> url-metadata tool build\n<span class=\"syntax-token syntax-token--command\">wordcell</span> url-metadata backfill <span class=\"syntax-token syntax-token--flag\">--root</span> .\n</code></pre></div></figure>\n<p>The helper pins <a href=\"https://github.com/MikeLuu99/searxng-rust\"><code>MikeLuu99/searxng-rust</code></a> at revision <code>f40a00ea67a857ee996e1caba1ebab3ee7a14a47</code>. Its crate is named <code>metadata-search-engine-rs</code>; it queries DuckDuckGo, Brave, Startpage, and Yahoo and combines their results. Wordcell resolves those four fixed hosts through its public-network boundary, passes only the validated addresses to the helper, disables redirects, and queries the engines serially. Wordcell validates DuckDuckGo HTML itself and limits its decoded body to 2 MiB. A challenge page or unrecognized response marks that engine as failed; only recognized result entries or an explicit no-results message count as a valid response. Empty responses from the other engines remain unverified and mark those engines as failed. A bounded global allocator caps Rust-owned response buffers and parsed data at 128 MiB. Linux also applies a 256 MiB process data ceiling. macOS rejects a lowered <code>RLIMIT_DATA</code>, so it retains the allocator ceiling plus the parent's subprocess deadline and output bounds. Wordcell passes requests over stdin to a private subprocess with ambient proxy and credential variables removed, bounds the subprocess deadline and output, parses the closed response itself, and does not use the upstream URL normalizer for saved identity.</p>\n<p>This operation discloses each eligible source URL as an exact search query to those search engines. Archive discovery also discloses it to Archive.today. Before either request, Wordcell resolves the source host through its public-network boundary and rejects credential-bearing URLs, private targets, and credential-shaped query parameters. Safe identity parameters such as Hacker News <code>item?id=</code> and YouTube <code>watch?v=</code> remain part of the exact query.</p>\n<p>Only a result with the same conservative URL identity can supply the selected title or description. A timestamped Archive.today result must embed that same source identity before it can be recorded. Provider failures, partial engine coverage, throttling, and absence remain explicit in the sidecar. A zero-result record is <code>not-found</code> only after complete attempted coverage; any failed engine or archive lookup keeps the top-level result <code>partial</code>.</p>\n<p>The command skips compatible sidecars by default. Use <code>--refresh</code> to query them again, <code>--no-archive</code> to omit Archive.today discovery, or <code>--delay-ms</code> to change the default one-second interval between outbound requests. It reads Markdown and sidecars through validated no-follow descriptors, carries the source Markdown and article-directory identities through provider work, and revalidates them under an inode-bound kernel advisory lock immediately before atomic installation. A live writer's lock cannot be stolen. The kernel releases a crashed writer's lock, and the next run safely reuses its verified lock file while UUID-scoped temporary names prevent an orphan from blocking progress. Malformed, linked, mismatched, replaced, or concurrently changed sources, locks, and sidecars fail closed.</p>\n",
-  "pdf": "<h1 id=\"capture-pdf-documents\">Capture PDF documents</h1>\n<p><code>wordcell pdf</code> converts a local PDF or a public HTTP(S) PDF into an auditable Markdown\nbundle. Remote downloads use the same DNS-pinned, private-network-denying\nacquisition boundary as web capture, and sensitive URL parameters are removed\nbefore provenance is persisted. It preserves\nthe original bytes, reconstructs native document structure, extracts embedded\nimages, and uses local OCR for text that exists only inside scans or\nscreenshots.</p>\n<h2 id=\"capture-a-pdf\">Capture a PDF</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> doctor\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;https://example.com/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--slug</span> stable-slug <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n</code></pre></div></figure>\n<p>The output mirrors a web capture without pretending the local file is a URL:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">articles/&lt;slug&gt;/\n  &lt;slug&gt;.md\n  capture.json\n  source.pdf\n  annotations.json  # present after a reviewed annotation pass\n  assets/\n</code></pre>\n<p><code>source.pdf</code> is byte-identical to the input. <code>capture.json</code> records the\noriginal filename, SHA-256, bytes, page count, bounded PDF metadata, processed\npage count, tool versions, text blocks, inferred headings, image geometry, OCR\nmethod and confidence, embedded platforms, and warnings. It never records the\ninput's original absolute path.</p>\n<p>When <code>--annotations</code> is used, the bundle also retains the normalized annotation\narray as <code>annotations.json</code>. Its path, count, byte count, and SHA-256 in\n<code>capture.json</code> bind the reviewed interpretation to the saved evidence and make\nthe second pass reproducible.</p>\n<p>Pass <code>--force</code> only to replace a compatible PDF bundle previously created at\nthe same slug. Installation stages beside the target and commits with an\natomic rename.</p>\n<h2 id=\"text-headings-and-page-order\">Text, headings, and page order</h2>\n<p>Poppler supplies native text, font, emphasis, link, geometry, and page data.\nThe converter infers a body style from the document and promotes only\nwell-supported heading candidates. Uncertain structure remains a paragraph\ninstead of becoming a confident but invented hierarchy.</p>\n<p>Every emitted page is marked in the Markdown, and the manifest records\nprocessed-page and block counts. Repeated page headers and footers can be\nomitted from the readable Markdown while remaining accounted for by the source\nPDF. Font and spacing can identify a likely heading without proving its\nsemantic depth, so review peer-versus-child levels against the source.</p>\n<h2 id=\"images-and-ocr\">Images and OCR</h2>\n<p>Every extracted image becomes a content-addressed local asset and remains\nembedded in the Markdown. A text-bearing image also receives a Markdown\ntranscription. A mixed screenshot keeps both\nrepresentations so a message, chart, photograph, code sample, or UI state is\nnot discarded merely because OCR found words.</p>\n<p>Tesseract is the local OCR fallback. Its output is bounded and records method,\nword count, and confidence. Missing OCR or an unclassified image makes the\ncapture <code>partial</code> but never removes the image. Screenshot-heavy captures\nshould be visually reviewed; recognizable Slack or other conversation images\ncan preserve visible platform, author, channel, timestamp, and reply metadata\nwithout inventing fields the image does not show.</p>\n<p>For a reviewed second pass, copy each image's <code>id</code> and <code>asset.sha256</code> from the\nfirst <code>capture.json</code> into an annotation array. A text or mixed annotation\naccepts <code>markdown</code>, optional <code>method</code> (<code>agent</code> or <code>manual</code>), and optional\n<code>metadata</code> fields for <code>platform</code>, <code>contentType</code>, <code>channel</code>, <code>author</code>,\n<code>timestamp</code>, and <code>participants</code>. A visual annotation accepts an optional\n<code>alt</code>. Re-run against the same bundle with:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--output</span> articles \\\n  <span class=\"syntax-token syntax-token--flag\">--annotations</span> /tmp/pdf-image-annotations.json \\\n  <span class=\"syntax-token syntax-token--flag\">--force</span>\n</code></pre></div></figure>\n<p>IDs and hashes bind the interpretation to the exact extracted image; stale or\nmisaddressed annotations are rejected. Annotation <code>markdown</code> contains only the\ntranscription; the renderer supplies the image embed, metadata line, and\n“Text visible in…” heading. The normalized input is copied into the installed\nbundle, so the path passed to <code>--annotations</code> does not need to remain available.</p>\n<h2 id=\"local-tools\">Local tools</h2>\n<p>PDF ingestion uses the open-source Poppler command-line tools <code>pdfinfo</code> and\n<code>pdftohtml</code>. Tesseract enables image text extraction. <code>wordcell doctor</code> reports\nwhether each route is available.</p>\n<p>Tool processes run with fixed argument shapes, bounded output, wall-time\nlimits, page and image caps, per-asset limits, and an aggregate asset budget.\nReaching any boundary is recorded and makes the result <code>partial</code>.</p>\n<h2 id=\"review\">Review</h2>\n<ol>\n<li>Compare source and processed page counts.</li>\n<li>Sample native-text, screenshot, scanned, and visual-only pages.</li>\n<li>Confirm heading levels match the source.</li>\n<li>Confirm every asset is referenced by the Markdown or manifest.</li>\n<li>Inspect low-confidence OCR against its source image.</li>\n<li>Keep later summaries and interpretations in maintained notes linked to the\ncapture.</li>\n</ol>\n",
+  "capture": "<h1 id=\"capture-web-content\">Capture web content</h1>\n<p><code>wordcell clip</code> saves public and signed-in web content as an auditable Markdown bundle. It combines bounded structured adapters, HTTP extraction, browser rendering, a read-only Archive.today fallback, localized assets, and explicit completeness metadata.</p>\n<h2 id=\"check-local-capabilities\">Check local capabilities</h2>\n<p>Run the diagnostics before using local search, browser state, PDF ingestion, or video capture:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> doctor\n<span class=\"syntax-token syntax-token--command\">wordcell</span> adapters\n</code></pre></div></figure>\n<p><code>wordcell doctor --json</code> reports the installed runtime, QMD and static semantic-search\nprerequisites, extraction dependencies, browser support, profile display names,\nyt-dlp, ffmpeg, Poppler (<code>pdfinfo</code> and <code>pdftohtml</code>), and Tesseract. The semantic\nreport distinguishes model-free keyword readiness from SQLite and sqlite-vec\nvector prerequisites; it does not inspect or download the embedding model. The\nPoppler pair is required by <code>wordcell pdf</code>; Tesseract adds local OCR for scans and\nscreenshots.\n<code>wordcell adapters --json</code> returns the current platform capability matrix.</p>\n<h2 id=\"capture-or-inspect-a-page\">Capture or inspect a page</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article\n<span class=\"syntax-token syntax-token--command\">wordcell</span> inspect https://example.com/article\n<span class=\"syntax-token syntax-token--command\">wordcell</span> inspect https://example.com/article <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The default route tries stable public structured data when available, bounded HTTP extraction, and a rendered browser when the platform or result requires one. If those routes produce no usable representation, Wordcell may make one read-only lookup for the exact URL through Archive.today's fixed <code>archive.ph/newest/</code> route. An authentication, paywall, CAPTCHA, access-control, or rate-limit response disables that fallback instead of using an archive to bypass the current source's controls. Wordcell never submits the URL for archiving, retries through aliases, or lets archived HTML displace a complete or partial Hacker News or Bluesky structured capture. It validates the source through the public-network boundary before disclosure, shares one deadline across validation and provider requests, and binds every snapshot and redirect to the exact source. An archived result is rescored and always reported as <code>partial</code>; it keeps the original canonical URL and records the timestamped snapshot as its acquisition URL. Inspection returns the selected Markdown and capture report without writing artifacts.</p>\n<p>By default, a capture writes <code>kb/articles/&lt;slug&gt;/</code>:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">&lt;slug&gt;/\n  &lt;slug&gt;.md\n  capture.json\n  url-metadata.json # after an optional metadata backfill\n  assets/\n  evidence/       # only when requested\n</code></pre>\n<p>The Markdown records source and capture metadata. <code>capture.json</code> records the acquisition attempts, selected extractor, scope, status, item counts, warnings, asset hashes, and requested artifact outcomes. The optional <code>url-metadata.json</code> is a separate tool-owned enrichment record. It does not rewrite acquisition provenance in <code>capture.json</code>. Writes stage beside the target and install with an atomic rename. <code>--force</code> replaces only a compatible clip-owned bundle and restores the previous bundle if installation fails.</p>\n<p>Set <code>KB_CLIP_OUTPUT</code> to change the default output root, or pass <code>--output &lt;directory&gt;</code> for one command. Set <code>KB_CLIP_USER_AGENT</code> or pass <code>--user-agent &lt;value&gt;</code> to override the default request user agent.</p>\n<h2 id=\"inspect-and-verify-a-saved-bundle\">Inspect and verify a saved bundle</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example <span class=\"syntax-token syntax-token--flag\">--verify-assets</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture verify kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture verify kb/articles/example <span class=\"syntax-token syntax-token--flag\">--verify-assets</span> <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p><code>show</code> reads the document, compares its v4 byte count and digest when present, and prints its Markdown as untrusted data. <code>verify</code> reports integrity without printing the document in its text output. Add <code>--verify-assets</code> to either command to read and hash every listed asset. A mismatch or an unavailable authoritative document digest returns exit status 3.</p>\n<p>The JSON forms preserve the same disclosure boundary: <code>show --json</code> includes the stored Markdown as explicitly untrusted inspection data, while <code>verify --json</code> returns only integrity metadata and issues. Verification JSON omits both the Markdown and retained source HTML so an integrity check does not accidentally disclose captured content.</p>\n<p>Schema v4 records <code>document.path</code>, <code>document.bytes</code>, and <code>document.sha256</code> in <code>capture.json</code>. The lowercase SHA-256 digest covers the exact credential-redacted, newline-terminated Markdown bytes that Wordcell writes. It does not cover <code>capture.json</code>, source HTML, or assets. Each asset has a separate byte count and SHA-256 digest. Schema versions one through three report document integrity as <code>unavailable</code> because they do not contain the v4 document record; <code>verify</code> does not present that state as success.</p>\n<p>When asset verification is requested, a listed asset that is absent is an integrity mismatch rather than an operational reader crash. It produces an <code>asset-integrity</code> issue and exit status 3, like a digest or byte-count mismatch. Structural alias, link, confinement, and resource-budget failures remain operational errors because the reader cannot safely characterize the requested bytes.</p>\n<p>Bundle inspection keeps the canonical root open, rejects linked or aliased path ancestors and linked leaves, and rechecks root, ancestor, and file identities around every read. Asset verification is also bounded by file count, per-file bytes, aggregate bytes, and elapsed time. The SDK defaults are 1,000 files, 100 MB per file, 500 MB total, and 30 seconds; callers may raise them only to the capture contract's hard ceilings. These checks protect against hostile stored bundle structure and ordinary concurrent replacement. A malicious process with the same filesystem authority that can swap and restore path components during a system call is outside the pure-JavaScript reader's boundary; do not inspect bundles in a directory concurrently writable by an untrusted local process.</p>\n<p>Source HTML remains opt-in when you read a bundle:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture show kb/articles/example <span class=\"syntax-token syntax-token--flag\">--include-source-html</span>\n</code></pre></div></figure>\n<p>This flag has an effect only when the capture used <code>--evidence source</code> or <code>--evidence all</code>. Wordcell removes active subtrees and form state, redacts credential-shaped values, and stores the result as inert HTML. Treat the retained text as hostile data, not instructions. It can still contain private content or text intended to influence an agent.</p>\n<h2 id=\"use-git-for-capture-history\">Use Git for capture history</h2>\n<p>Commit retained capture bundles to Git, then compare the current Markdown document with an earlier revision:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff kb/articles/example\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff /path/to/repository/kb/articles/example <span class=\"syntax-token syntax-token--flag\">--repo</span> /path/to/repository <span class=\"syntax-token syntax-token--flag\">--ref</span> main\n<span class=\"syntax-token syntax-token--command\">wordcell</span> capture diff kb/articles/example <span class=\"syntax-token syntax-token--flag\">--repo</span> . <span class=\"syntax-token syntax-token--flag\">--ref</span> main <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The bundle must be inside the selected repository. The default reference is <code>HEAD</code>; <code>--ref</code> accepts a bounded branch, tag, or commit name, not a revision expression such as <code>HEAD~1</code>. Wordcell validates the work tree and ref separately, so a bad repository or ref is not mislabeled as a missing file. The command reports <code>changed</code>, <code>unchanged</code>, or <code>missing-at-ref</code> for the exact Markdown path and emits a bounded Git diff when it changed. It rereads and matches the capture digest after diff generation, rejecting a concurrent change instead of pairing one digest with another snapshot's diff. It does not compare the manifest, source HTML, or assets. Run <code>wordcell capture verify</code> separately when integrity matters. Git is the capture version history; Wordcell does not maintain a second content-history database.</p>\n<h2 id=\"track-capture-jobs-programmatically\">Track capture jobs programmatically</h2>\n<p>Use the optional <code>@hraness/wordcell/clip/jobs</code> ledger when a service needs durable capture progress:</p>\n<pre><code class=\"syntax-code language-typescript\" data-language=\"typescript\"><span class=\"sh__line\"><span class=\"sh__token--keyword\">import</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">completeCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">createCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">openCaptureJobStore</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">updateCaptureJob</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">from</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">@hraness/wordcell/clip/jobs</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">const</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">openCaptureJobStore</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">/absolute/path/to/capture-jobs</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">let</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">createCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">target</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">https://example.com/article</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">updateCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">id</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">expectedRevision</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">revision</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">phase</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">acquiring</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">completeCaptureJob</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">store</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">id</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">expectedRevision</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">job</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">revision</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">status</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">complete</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>Create the dedicated canonical mode-0700 store directory before opening it, and pass the returned store to every operation. The opener rejects filesystem aliases, links, and group/world access. Each job is one private, bounded UUID JSON record. Creation starts revision 1 in <code>running</code> and <code>queued</code>; updates require the expected revision, append attempts and warnings, and move phases forward. Completion records a capture status. It can also record <code>bundle: { path, sha256 }</code>; use <code>capture.json</code>'s v4 <code>document.sha256</code> as <code>sha256</code> because the ledger does not calculate a separate bundle digest. <code>failCaptureJob</code> records an operational error separately from capture status. <code>readCaptureJob</code> and <code>listCaptureJobs</code> inspect retained records. A terminal <code>completed</code> or <code>failed</code> record cannot transition again, and a process crash leaves the last <code>running</code> record visible.</p>\n<p>The ledger redacts credential-shaped values and strips terminal controls from targets, attempts, warnings, bundle paths, and errors. A store-local, heartbeat-backed filesystem lease serializes cooperating processes across revision validation, atomic whole-record replacement, record verification, and directory synchronization; exactly one same-revision transition can succeed. There is no shared append log. Records remain until the caller applies an explicit external retention policy. The module provides no delete or automatic pruning API, and it does not replace Git as capture history. The lease is a same-host coordination mechanism, not a distributed lock for multi-host network filesystems, and a malicious same-user writer with direct store access remains outside its guarantee.</p>\n<h2 id=\"select-acquisition-and-scope\">Select acquisition and scope</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--mode</span> http\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/application <span class=\"syntax-token syntax-token--flag\">--mode</span> browser\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/post <span class=\"syntax-token syntax-token--flag\">--scope</span> page\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/post <span class=\"syntax-token syntax-token--flag\">--scope</span> thread\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/discussion <span class=\"syntax-token syntax-token--flag\">--scope</span> comments\n</code></pre></div></figure>\n<p><code>auto</code> is the normal acquisition mode. <code>http</code> disables browser fallback but retains the final read-only archive lookup. <code>browser</code> requires rendered state and does not query Archive.today. Saved HTML can be imported without browser automation:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--html</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_SAVED_HTML&quot;</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--html</span> <span class=\"syntax-token syntax-token--flag\">-</span> <span class=\"syntax-token syntax-token--operator\">&lt;</span> page.html\n</code></pre></div></figure>\n<p>Default resource bounds are 30 seconds per request, process, or extraction operation; 500 scoped items; depth 16; 25 MB of HTML; 100 MB per asset; and 500 MB across assets. Browser observation also has fixed DOM and scroll ceilings. Reaching a bound is recorded and can downgrade a result to <code>partial</code>.</p>\n<h2 id=\"capture-images-media-and-evidence\">Capture images, media, and evidence</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--media</span> none\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--media</span> images\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/video <span class=\"syntax-token syntax-token--flag\">--media</span> all\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> source\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> screenshot\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/article <span class=\"syntax-token syntax-token--flag\">--evidence</span> all\n</code></pre></div></figure>\n<p>Image downloads are signature-checked, content-addressed, byte-bounded, and\nrewritten to relative bundle paths. Failed images remain inert links. Video\nposters and thumbnails exposed by the page are localized without downloading\nthe full video.</p>\n<p>For YouTube, the normal capture route uses yt-dlp to retain the title,\ndescription, duration, channel, thumbnail, and one exact-language transcript\nwhen those fields are available. Full audio/video download remains opt-in:\n<code>--media all</code> invokes yt-dlp for accessible media, and ffmpeg may be required\nfor merging or remuxing.</p>\n<p>Source evidence is sanitized into inert HTML with credential-shaped values redacted and a deny-all content security policy. Screenshots are viewport-only pixels and are not structurally sanitized. They may contain private content or notifications, so review them before retaining or sharing a bundle.</p>\n<h2 id=\"capture-a-signed-in-page\">Capture a signed-in page</h2>\n<p>If the page is already open, read the current tab without navigating it:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip current <span class=\"syntax-token syntax-token--flag\">--browser-live</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip current <span class=\"syntax-token syntax-token--flag\">--cdp</span> 9222\n</code></pre></div></figure>\n<p>For <code>--browser-live</code>, first enable Chrome's local debugging connection at <code>chrome://inspect/#remote-debugging</code> (Chrome 144+). If Chrome was launched with an explicit loopback debugging port, pass that numeric port to <code>--cdp</code> instead.</p>\n<p>To open a URL with existing browser state, select a profile name or path. Path-backed profiles run from a temporary copy, so the source profile is unchanged:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--browser-profile</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_CAPTURE_PROFILE&quot;</span>\n</code></pre></div></figure>\n<p>Cookie-backed HTTP capture is useful when the page does not require local storage, IndexedDB, or other browser-only state:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--cookie-source</span> chrome <span class=\"syntax-token syntax-token--flag\">--cookie-profile</span> <span class=\"syntax-token syntax-token--string\">&quot;Default&quot;</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> clip https://example.com/member/article <span class=\"syntax-token syntax-token--flag\">--cookies-file</span> <span class=\"syntax-token syntax-token--string\">&quot;$KB_COOKIES_FILE&quot;</span>\n</code></pre></div></figure>\n<p>Choose at most one browser session and one cookie input. A browser session may use a separate cookie input for later asset or media downloads because attached browser state is not exported.</p>\n<p>On a Mac, reading Chrome, Arc, Brave, Chromium, or Edge cookies asks the keychain for that browser's &quot;Safe Storage&quot; key. The dialog names <code>security</code>, the macOS tool Wordcell uses to read it, so Wordcell prints a note first that says why. Enter your Mac password if asked, then choose Always Allow so macOS doesn't ask again. Wordcell never stores the key. If you deny the request, Wordcell says so and suggests <code>--cookies-file</code>. Safari cookies need Full Disk Access for your terminal app, because macOS doesn't ask for it. Turn it on in System Settings › Privacy &amp; Security › Full Disk Access.</p>\n<p>Current-tab capture issues no navigation, click, form, typing, upload, or submit command. URL-based browser capture may navigate and scroll within fixed work limits, taking bounded observations as content is rendered. Both routes are ingestion-only: they do not post, like, follow, send, delete, or submit.</p>\n<h2 id=\"interpret-status-and-counts\">Interpret status and counts</h2>\n<p>Capture status is one of:</p>\n<ul>\n<li><code>complete</code>: the selected bounded representation was acquired without a known missing boundary.</li>\n<li><code>partial</code>: useful content was retained, but a count, cursor, configured bound, hidden branch, or generic rendered representation prevents a completeness claim.</li>\n<li><code>auth-required</code>: the selected routes reached an authentication gate.</li>\n<li><code>blocked</code>: the source returned a block or verification shell.</li>\n<li><code>unsupported</code>: no route produced a usable representation.</li>\n</ul>\n<p>For page scope, counts cover primary entries. For thread and comment scopes, counts cover replies or comments and exclude roots, quotes, ancestors, and pagination markers. Generic rendered conversations often report <code>capturedItems: 0</code> because visible prose does not prove a trustworthy per-item tree.</p>\n<p>A <code>complete</code> or <code>partial</code> capture exits with status 0. Authentication, blocked, and unsupported outcomes use status 3. Argument errors use status 2, environment diagnostic failures use status 4, and operational errors use status 1. Automation should inspect the structured status and warnings rather than relying only on the process exit code.</p>\n<h2 id=\"platform-routes\">Platform routes</h2>\n<ul>\n<li>Hacker News uses the official Firebase item API for bounded recursive discussions.</li>\n<li>Bluesky uses public AT Protocol resolution and thread APIs.</li>\n<li>Reddit first tries its unofficial public listing JSON and falls back when that surface is denied or changes.</li>\n<li>X uses article extraction plus rendered capture; unloaded or virtualized replies remain partial.</li>\n<li>Substack uses article extraction and a signed-in browser for subscriber text when selected.</li>\n<li>GitHub issues, pull requests, and discussions use the Defuddle GitHub extractor, with a signed-in browser fallback for private repositories.</li>\n<li>Discourse topics use the Defuddle Discourse extractor and rendered fallback.</li>\n<li>YouTube adds bounded yt-dlp video context—title, description, duration,\nchannel, thumbnail, and an available exact-language transcript—to HTTP or\nrendered page capture. Full audio/video remains opt-in with <code>--media all</code>.</li>\n<li>Instagram, Facebook, LinkedIn, TikTok, Threads, WhatsApp Web, and arbitrary\napplications use rendered or saved-HTML capture. They do not gain a\ntrustworthy item tree without a dedicated adapter.</li>\n</ul>\n<p>Platform markup and endpoints change. Run <code>wordcell adapters</code> for the installed version's current claims.</p>\n<h2 id=\"backfill-saved-url-metadata\">Backfill saved URL metadata</h2>\n<p>The URL metadata command enriches every external URL record under <code>articles/</code>, including legacy web clips and remote PDF sources. It skips local-only PDFs. It writes one sibling <code>url-metadata.json</code> without changing the source Markdown or synthesizing an old capture manifest.</p>\n<p>Build the isolated Rust helper, then run the resumable backfill:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> url-metadata tool build\n<span class=\"syntax-token syntax-token--command\">wordcell</span> url-metadata backfill <span class=\"syntax-token syntax-token--flag\">--root</span> .\n</code></pre></div></figure>\n<p>The helper pins <a href=\"https://github.com/MikeLuu99/searxng-rust\"><code>MikeLuu99/searxng-rust</code></a> at revision <code>f40a00ea67a857ee996e1caba1ebab3ee7a14a47</code>. Its crate is named <code>metadata-search-engine-rs</code>; it queries DuckDuckGo, Brave, Startpage, and Yahoo and combines their results. Wordcell resolves those four fixed hosts through its public-network boundary, passes only the validated addresses to the helper, disables redirects, and queries the engines serially. Wordcell validates DuckDuckGo HTML itself and limits its decoded body to 2 MiB. A challenge page or unrecognized response marks that engine as failed; only recognized result entries or an explicit no-results message count as a valid response. Empty responses from the other engines remain unverified and mark those engines as failed. A bounded global allocator caps Rust-owned response buffers and parsed data at 128 MiB. Linux also applies a 256 MiB process data ceiling. macOS rejects a lowered <code>RLIMIT_DATA</code>, so it retains the allocator ceiling plus the parent's subprocess deadline and output bounds. Wordcell passes requests over stdin to a private subprocess with ambient proxy and credential variables removed, bounds the subprocess deadline and output, parses the closed response itself, and does not use the upstream URL normalizer for saved identity.</p>\n<p>This operation discloses each eligible source URL as an exact search query to those search engines. Archive discovery also discloses it to Archive.today. Before either request, Wordcell resolves the source host through its public-network boundary and rejects credential-bearing URLs, private targets, and credential-shaped query parameters. Safe identity parameters such as Hacker News <code>item?id=</code> and YouTube <code>watch?v=</code> remain part of the exact query.</p>\n<p>Only a result with the same conservative URL identity can supply the selected title or description. A timestamped Archive.today result must embed that same source identity before it can be recorded. Provider failures, partial engine coverage, throttling, and absence remain explicit in the sidecar. A zero-result record is <code>not-found</code> only after complete attempted coverage; any failed engine or archive lookup keeps the top-level result <code>partial</code>.</p>\n<p>The command skips compatible sidecars by default. Use <code>--refresh</code> to query them again, <code>--no-archive</code> to omit Archive.today discovery, or <code>--delay-ms</code> to change the default one-second interval between outbound requests. It reads Markdown and sidecars through validated no-follow descriptors, carries the source Markdown and article-directory identities through provider work, and revalidates them under an inode-bound kernel advisory lock immediately before atomic installation. A live writer's lock cannot be stolen. The kernel releases a crashed writer's lock, and the next run safely reuses its verified lock file while UUID-scoped temporary names prevent an orphan from blocking progress. Malformed, linked, mismatched, replaced, or concurrently changed sources, locks, and sidecars fail closed.</p>\n<h2 id=\"observed-article-metadata\">Observed article metadata</h2>\n<p>New captures include an optional <code>metadata</code> envelope in <code>capture.json</code>. Schema 1\nkeeps each observed value, its normalized value, source and locator, the selection\nrule, and whether that claim was selected. Conflicting claims remain available.\nThe parser reads HTML title, language, standard meta and link tags, and bounded\nJSON-LD from the captured document. It does not fetch remote JSON-LD contexts.</p>\n<p>Specific article metadata takes precedence over generic webpage metadata.\nMultiple authors and alternate links can remain selected. A date without an\nexplicit timezone stays local; a calendar date is not converted into an instant.\nMetadata URLs omit query strings, fragments and credentials. They are descriptive\nevidence and must not replace the original acquisition URL. Parser limits and\nmalformed JSON-LD appear in the envelope's warnings. Older bundles can omit the\nenvelope.</p>\n<p><code>@hraness/wordcell/capture</code> exports <code>extractArticleMetadata</code> and\n<code>parseArticleMetadata</code>; the bundle reader returns this evidence when present.</p>\n",
+  "pdf": "<h1 id=\"capture-pdf-documents\">Capture PDF documents</h1>\n<p><code>wordcell pdf</code> converts a local PDF or a public HTTP(S) PDF into an auditable Markdown\nbundle. Remote downloads use the same DNS-pinned, private-network-denying\nacquisition boundary as web capture, and sensitive URL parameters are removed\nbefore provenance is persisted. It preserves\nthe original bytes, reconstructs native document structure, extracts embedded\nimages, and uses local OCR for text that exists only inside scans or\nscreenshots.</p>\n<h2 id=\"capture-a-pdf\">Capture a PDF</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> doctor\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;https://example.com/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n<span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> <span class=\"syntax-token syntax-token--flag\">--slug</span> stable-slug <span class=\"syntax-token syntax-token--flag\">--output</span> articles\n</code></pre></div></figure>\n<p>The output mirrors a web capture without pretending the local file is a URL:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">articles/&lt;slug&gt;/\n  &lt;slug&gt;.md\n  capture.json\n  source.pdf\n  annotations.json  # present after a reviewed annotation pass\n  assets/\n</code></pre>\n<p><code>source.pdf</code> is byte-identical to the input. <code>capture.json</code> records the\noriginal filename, SHA-256, bytes, page count, bounded PDF metadata, processed\npage count, tool versions, text blocks, inferred headings, image geometry, OCR\nmethod and confidence, embedded platforms, and warnings. It never records the\ninput's original absolute path.</p>\n<p>When <code>--annotations</code> is used, the bundle also retains the normalized annotation\narray as <code>annotations.json</code>. Its path, count, byte count, and SHA-256 in\n<code>capture.json</code> bind the reviewed interpretation to the saved evidence and make\nthe second pass reproducible.</p>\n<p>Pass <code>--force</code> only to replace a compatible PDF bundle previously created at\nthe same slug. Installation stages beside the target and commits with an\natomic rename.</p>\n<h2 id=\"text-headings-and-page-order\">Text, headings, and page order</h2>\n<p>Poppler supplies native text, font, emphasis, link, geometry, and page data.\nThe converter infers a body style from the document and promotes only\nwell-supported heading candidates. Uncertain structure remains a paragraph\ninstead of becoming a confident but invented hierarchy.</p>\n<p>Every emitted page is marked in the Markdown, and the manifest records\nprocessed-page and block counts. Repeated page headers and footers can be\nomitted from the readable Markdown while remaining accounted for by the source\nPDF. Font and spacing can identify a likely heading without proving its\nsemantic depth, so review peer-versus-child levels against the source.</p>\n<h2 id=\"images-and-ocr\">Images and OCR</h2>\n<p>Every extracted image becomes a content-addressed local asset and remains\nembedded in the Markdown. A text-bearing image also receives a Markdown\ntranscription. A mixed screenshot keeps both\nrepresentations so a message, chart, photograph, code sample, or UI state is\nnot discarded merely because OCR found words.</p>\n<p>Tesseract is the local OCR fallback. Its output is bounded and records method,\nword count, and confidence. Missing OCR or an unclassified image makes the\ncapture <code>partial</code> but never removes the image. Screenshot-heavy captures\nshould be visually reviewed; recognizable Slack or other conversation images\ncan preserve visible platform, author, channel, timestamp, and reply metadata\nwithout inventing fields the image does not show.</p>\n<p>For a reviewed second pass, copy each image's <code>id</code> and <code>asset.sha256</code> from the\nfirst <code>capture.json</code> into an annotation array. A text or mixed annotation\naccepts <code>markdown</code>, optional <code>method</code> (<code>agent</code> or <code>manual</code>), and optional\n<code>metadata</code> fields for <code>platform</code>, <code>contentType</code>, <code>channel</code>, <code>author</code>,\n<code>timestamp</code>, and <code>participants</code>. A visual annotation accepts an optional\n<code>alt</code>. Re-run against the same bundle with:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> pdf <span class=\"syntax-token syntax-token--string\">&quot;/absolute/path/to/document.pdf&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--output</span> articles \\\n  <span class=\"syntax-token syntax-token--flag\">--annotations</span> /tmp/pdf-image-annotations.json \\\n  <span class=\"syntax-token syntax-token--flag\">--force</span>\n</code></pre></div></figure>\n<p>IDs and hashes bind the interpretation to the exact extracted image; stale or\nmisaddressed annotations are rejected. Annotation <code>markdown</code> contains only the\ntranscription; the renderer supplies the image embed, metadata line, and\n“Text visible in…” heading. The normalized input is copied into the installed\nbundle, so the path passed to <code>--annotations</code> does not need to remain available.</p>\n<h2 id=\"local-tools\">Local tools</h2>\n<p>PDF ingestion uses the open-source Poppler command-line tools <code>pdfinfo</code> and\n<code>pdftohtml</code>. Tesseract enables image text extraction. <code>wordcell doctor</code> reports\nwhether each route is available.</p>\n<p>Tool processes run with fixed argument shapes, bounded output, wall-time\nlimits, page and image caps, per-asset limits, and an aggregate asset budget.\nReaching any boundary is recorded and makes the result <code>partial</code>.</p>\n<h2 id=\"review\">Review</h2>\n<ol>\n<li>Compare source and processed page counts.</li>\n<li>Sample native-text, screenshot, scanned, and visual-only pages.</li>\n<li>Confirm heading levels match the source.</li>\n<li>Confirm every asset is referenced by the Markdown or manifest.</li>\n<li>Inspect low-confidence OCR against its source image.</li>\n<li>Keep later summaries and interpretations in maintained notes linked to the\ncapture.</li>\n</ol>\n<h2 id=\"layout-quality-and-verification\">Layout quality and verification</h2>\n<p>Separated columns are read in sequence before lines are merged. Compact aligned\ntables with an explicit header and numeric cells become Markdown tables. Basic\nraised digits remain superscripts. Complex formulas, ambiguous tables and\nuncertain layout produce page-specific quality issues and a partial capture;\nthe original PDF remains the reference. Repeated headers are removed only near\npage margins. These rules do not promise complete layout reconstruction.</p>\n<p>New bundles bind the Markdown bytes as well as the original PDF and images.\nUse the public SDK to inspect or verify an existing bundle:</p>\n<pre><code class=\"syntax-code language-typescript\" data-language=\"typescript\"><span class=\"sh__line\"><span class=\"sh__token--keyword\">import</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">verifyPdfCaptureBundle</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">from</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">@hraness/wordcell/pdf</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">const</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">result</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">verifyPdfCaptureBundle</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">/absolute/path/to/saved-document</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">if</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--sign\">!</span><span class=\"sh__token--identifier\">result</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">ok</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">throw</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">new</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">Error</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">PDF bundle verification failed</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p><code>inspectPdfCaptureBundle</code> returns the saved text and integrity results.\n<code>verifyPdfCaptureBundle</code> checks bounded, confined files and page/asset references.\nLegacy bundles without a Markdown digest report unavailable integrity rather\nthan verified content. <code>PdfCaptureError.code</code> provides stable failure categories;\nunknown failures remain unknown, and password errors require a recognized tool\ndiagnostic.</p>\n<p>A host with its own process supervisor can inject <code>runTool</code> and call\n<code>runPdfToolCommand({ ...command, processGroup: &quot;inherit&quot; })</code>. That host owns\ntermination and descendant cleanup for the surrounding group. Standalone\ncommands keep the default separate process group.</p>\n",
   "publish": "<h1 id=\"publish-a-static-site\">Publish a static site</h1>\n<p><code>wordcell publish</code> turns selected Markdown notes into a static website with\nsearch, backlinks, and a graph. Build it locally, inspect the result, then copy\nthe files to your preferred host. Publishing does not upload your vault or\nrequire an account, database, model, or API key.</p>\n<p>The HTML pages work without JavaScript. Serve the directory over HTTP to use\nthe bundled browser-local search and graph; opening HTML files directly is\nsuitable for reading pages, but browser restrictions can block the reader.</p>\n<h2 id=\"preview-and-publish-a-slice\">Preview and publish a slice</h2>\n<p>Choose notes by exact path, directory, glob, metadata, or a graph neighborhood.\nThis example combines a directory tree with one note from elsewhere in the\nvault, then removes drafts:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site \\\n  <span class=\"syntax-token syntax-token--flag\">--include-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;guides/**/*.md&#39;</span> <span class=\"syntax-token syntax-token--flag\">--include</span> notes/getting-started \\\n  <span class=\"syntax-token syntax-token--flag\">--exclude</span> drafts <span class=\"syntax-token syntax-token--flag\">--dry-run</span> <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The dry run builds the same artifact in memory and leaves the output directory\nuntouched. Its JSON report includes counts, a source digest, and up to 20\nselected note ids. The digest covers selected Markdown; it does not cover\nattachment bytes. Review those ids, counts, and referenced assets before writing. Repeat the same\nselectors without <code>--dry-run</code> to build the site:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site \\\n  <span class=\"syntax-token syntax-token--flag\">--include-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;guides/**/*.md&#39;</span> <span class=\"syntax-token syntax-token--flag\">--include</span> notes/getting-started \\\n  <span class=\"syntax-token syntax-token--flag\">--exclude</span> drafts\n<span class=\"syntax-token syntax-token--command\">wordcell</span> serve <span class=\"syntax-token syntax-token--flag\">--root</span> site <span class=\"syntax-token syntax-token--flag\">--port</span> 8080\n</code></pre></div></figure>\n<p>Open <code>http://127.0.0.1:8080</code> to inspect the pages. Nothing is publicly hosted\nuntil you upload the generated directory. When rebuilding an existing site,\nadd <code>--force</code> to replace that output directory. Keep it separate from your\nsource vault: neither directory may contain the other. An empty selection\nreturns a zero-count dry-run report, but writing it fails so a mistyped selector\ncannot replace an existing site. Wordcell writes the complete replacement\ninto a sibling staging directory first. A write failure leaves the previous\nsite in place. Promotion moves the previous site to a temporary backup, then\nmoves the staged site into place. These are two renames, so a running server can\nbriefly see no output directory. If promotion fails, Wordcell restores the\nbackup; if restoration also fails, the error names the retained backup path.\nThe backup is removed only after successful promotion.</p>\n<p>For agent workflows, <code>--json</code> returns the report without note bodies, HTML,\nsearch postings, or file contents. <code>--list-limit 0</code> returns counts and the source\ndigest only; a value from zero through 1,000 changes the maximum listed ids.\nThe ids also have a combined 16 KiB byte budget, and <code>selection.truncated</code>\nreports when the list is incomplete. The bound changes only the report, never\nwhich notes publish. Read the generated <code>catalog.json</code> when you need the full\npublished list. An SDK caller can reuse a scanned vault with <code>projectVault</code>.</p>\n<h2 id=\"choose-what-publishes\">Choose what publishes</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site/docs <span class=\"syntax-token syntax-token--flag\">--include</span> docs\n<span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site/public <span class=\"syntax-token syntax-token--flag\">--tag</span> public <span class=\"syntax-token syntax-token--flag\">--exclude</span> drafts\n<span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site/guides \\\n  <span class=\"syntax-token syntax-token--flag\">--include-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;guides/**/*.md&#39;</span> <span class=\"syntax-token syntax-token--flag\">--exclude-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;**/draft-*&#39;</span>\n<span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site/topic \\\n  <span class=\"syntax-token syntax-token--flag\">--from</span> notes/topic-seed <span class=\"syntax-token syntax-token--flag\">--depth</span> 2 <span class=\"syntax-token syntax-token--flag\">--direction</span> both\n<span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site/concepts <span class=\"syntax-token syntax-token--flag\">--where</span> <span class=\"syntax-token syntax-token--variable\">type=concept</span> <span class=\"syntax-token syntax-token--flag\">--has</span> relations\n</code></pre></div></figure>\n<ul>\n<li><code>--include &lt;path&gt;</code> selects a note id, <code>.md</code> path, or directory prefix. Repeat\nit to combine notes from anywhere in the vault.</li>\n<li><code>--include-glob &lt;pattern&gt;</code> matches note ids or <code>.md</code> paths, case sensitively.\n<code>*</code> matches within one path segment, <code>?</code> matches one character, and a whole\n<code>**</code> segment matches zero or more directories. Quote patterns so your shell\ndoes not expand them. Bracket classes and brace expansion are unsupported.\nGlob matching has a shared work budget; if a large or complex selection\nexceeds it, use fewer patterns or exact path prefixes.</li>\n<li><code>--where &lt;path=value&gt;</code>, <code>--has &lt;path&gt;</code>, <code>--tag &lt;tag&gt;</code>, and <code>--scope &lt;repository-path&gt;</code> form one metadata query. All filters in that query must\nmatch, as with <code>wordcell list</code>.</li>\n<li><code>--from &lt;note&gt;</code> selects a link-and-relation neighborhood with <code>--depth</code>\n(1–10) and <code>--direction in|out|both</code>. Neighborhoods are bounded at 1,000 notes\nand 10,000 connections; exceeding either bound fails instead of silently\npublishing an incomplete neighborhood. Narrow the depth or use paths/globs.</li>\n<li>Include paths, include globs, the metadata query, and the graph neighborhood\nform a union. For example, <code>--include docs --tag public</code> selects every note\nunder <code>docs</code> plus every public-tagged note elsewhere.</li>\n<li><code>--exclude &lt;path&gt;</code> and <code>--exclude-glob &lt;pattern&gt;</code> remove notes after that\nunion. <code>publish: false</code> frontmatter always removes a note, even when another\nselector matches it. With no positive selector, all remaining notes publish.</li>\n</ul>\n<p>Review selected prose and attachments before hosting. Selection controls which\nnotes enter the site; it does not redact text inside them. A selected note can\nstill mention a private name, contain sensitive metadata in its search fields,\nor reference an attachment you intended to keep private. Exclusion selectors\napply to notes, not attachment files. Only validated local attachments directly\nreferenced by selected notes are copied.</p>\n<p>Links and typed relationships to excluded notes are omitted from structured\nnavigation. An authored link label can remain in the selected note's rendered\nprose. Public manifests record selector counts without storing raw include,\nexclude, filter, or seed values.</p>\n<h2 id=\"set-the-site-identity\">Set the site identity</h2>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site <span class=\"syntax-token syntax-token--flag\">--title</span> <span class=\"syntax-token syntax-token--string\">&quot;Team Handbook&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--description</span> <span class=\"syntax-token syntax-token--string\">&quot;Public engineering notes&quot;</span> <span class=\"syntax-token syntax-token--flag\">--base-path</span> /handbook/ \\\n  <span class=\"syntax-token syntax-token--flag\">--base-url</span> https://docs.example.com\n</code></pre></div></figure>\n<p><code>--base-path</code> sets the URL prefix (default <code>/</code>). <code>--base-url</code> adds a\n<code>sitemap.xml</code>; omit it when the site has no canonical origin. <code>--noindex</code>\nemits a robots disallow and a noindex marker on every page. These are indexing\nrequests, not access controls. <code>--deterministic</code> omits the generation timestamp\nso identical inputs and options produce byte-identical artifacts.</p>\n<h2 id=\"the-emitted-artifact\">The emitted artifact</h2>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">site/\n  index.html              # front door: the vault index note, or a catalog page\n  index.json              # the index note payload, when one published\n  manifest.json           # hraness.wordcell.site.v1 manifest\n  catalog.json            # every note: slug, title, type, tags\n  graph.json              # selection-scoped link and relation edges\n  graph/index.html        # interactive map of the published graph\n  n/&lt;slug&gt;/index.html     # prerendered note pages with backlink panels\n  n/&lt;slug&gt;.json           # hydrated note payloads for richer readers\n  index/docs.json         # document table with normalized eager fields\n  index/terms.json        # sorted term dictionary for prefix lookup\n  index/c/&lt;hh&gt;.json       # content postings shards, only for large selections\n  assets/&lt;hash&gt;.&lt;ext&gt;     # referenced attachments, content-addressed\n  reader/reader.js|.css   # the bundled reader: search overlay and graph map\n  reader/theme.js         # synchronous appearance bootstrap (see below)\n  404.html, robots.txt, sitemap.xml\n</code></pre>\n<h2 id=\"reading-the-site\">Reading the site</h2>\n<p>Every page ships the same chrome: a header with the site title, a <code>Graph</code> link,\nand a <code>Search</code> button; a sidebar tree of the published notes; and a footer.\nThe tree is derived from slug paths. Directories sort before notes at each\nlevel, groups open along the path to the current page, and oversized branches\nfold into bounded <code>+N more</code> links back to the catalog. Everything is\nprerendered HTML: navigation works with JavaScript disabled.</p>\n<p>Note pages add breadcrumbs above the article and an <em>On this page</em> table of\ncontents beside it, generated from the same heading anchors the Markdown\nrenderer emits. The backlink, relation, and referenced-by panels still sit in\nthe article aside.</p>\n<p>The graph page maps <code>graph.json</code> onto a canvas: nodes sized by degree, links\nas solid edges and typed relations as dashed ones. Drag to pan, scroll or\npinch to zoom, hover a node to light its neighborhood, and click a node to\nopen the note. <code>graph/#n=&lt;slug&gt;</code> deep-links to a focused node. The layout is a\nseeded deterministic force layout, so every visitor sees the same map. Sites\nover the contract's node limit publish the same page with the static note\nindex instead of the live canvas, and the prerendered index below the map\nkeeps the page useful without JavaScript at any size.</p>\n<h3 id=\"footnotes\">Footnotes</h3>\n<p>Use <code>[^label]</code> in prose and a top-level <code>[^label]: Source or explanation</code>\ndefinition to publish a numbered footnote. Each citation links to its footnote;\neach footnote links back to every place that cites it. These links work without\nJavaScript. Definitions can contain ordinary links and inline formatting.\nIndent continuation lines by four spaces or one tab. Nested footnote references\ninside definitions remain literal, and supported explicit links take precedence over\nfootnote syntax in their labels.</p>\n<pre><code class=\"syntax-code language-markdown\" data-language=\"markdown\">The measured result is consistent with the earlier study.[^study]\n\n[^study]: [Read the study](https://example.com/study).\n</code></pre>\n<p>Labels allow Unicode letters, marks, and numbers plus <code>._:-</code>; they are\ncase-sensitive and normalized to Unicode NFC. Keep labels within\n128 UTF-8 bytes and definitions within 32 lines and 8,192 UTF-8 bytes. A page\nsupports 256 definitions and 2,048 linked citations. Missing, duplicated,\ninvalid, and over-limit references remain visibly unresolved; their authored\ndefinitions remain visible. Footnote syntax in code or comments stays inert.</p>\n<h3 id=\"appearance\">Appearance</h3>\n<p>The reader supports the shared Hraness palette contract: the <code>wordcell</code>\nneutral palette plus Catppuccin, Gruvbox, Rosé Pine, and Tokyo Night, each\nin light and dark. A small classic script, <code>reader/theme.js</code>, loads\nsynchronously in every page head, ahead of the stylesheet, and applies\nthe stored preference to <code>data-palette</code> and <code>data-theme</code> on the document\nelement before first paint, so a saved palette never flashes the default.\nThe preference lives under <code>hraness-design-palette-v1</code> in the origin's\nlocal storage, the same key design-kit applications use, so a reader\nhosted beside one honors the visitor's existing choice; <code>system</code> mode\nfollows the operating system and <code>storage</code> events synchronize other tabs.\nThe deferred reader adds a single appearance menu as the rightmost header\naction — radio groups for mode and palette — and the graph map repaints\non every applied change. Without JavaScript, or with no stored preference,\npages fall back to the neutral palette under <code>prefers-color-scheme</code>.</p>\n<p>Every JSON file carries an explicit format identifier and parses under a\nbounded <code>unknown</code>-value contract; parsers reject unexpected keys, oversize\nfields, and wrong formats. <code>manifest.json</code> records the generator identity and\nversion, selector counts, the source digest, artifact paths, search\nmode, counts, and any truncated aspects. In <code>--deterministic</code> mode the manifest\ncarries no timestamp and the whole directory is reproducible.</p>\n<h3 id=\"browser-local-search\">Browser-local search</h3>\n<p>The document table eagerly stores normalized title, alias, path, tag, and\nmetadata fields so in-page matching reproduces the exact lane's substring\nsemantics. Note content is indexed inline while the selection fits the\ncontract's aggregate budget; larger selections store sharded postings that the\nreader fetches lazily by FNV-1a term hash. <code>--no-index-content</code> disables content\nindexing entirely, leaving field-only search. Query, prefix-expansion, result,\nand hydration bounds are fixed by the contract so a hostile or oversized\nartifact cannot exhaust the browser.</p>\n<p>The overlay opens from the <code>Search</code> button or the <code>/</code> key. Alongside free\ntext, field filters narrow the candidate set:</p>\n<ul>\n<li><code>tag:&lt;tag&gt;</code> requires every listed tag.</li>\n<li><code>type:&lt;type&gt;</code> matches the catalog <code>type</code> value; notes without one count as\n<code>note</code>.</li>\n<li><code>path:&lt;prefix&gt;</code> limits results to notes whose slug, id, or vault path sits\nunder the prefix on a segment boundary (<code>path:docs</code> matches <code>docs/alpha</code>,\nnever <code>docs2/x</code>).</li>\n</ul>\n<p>Filters combine with free text. <code>tag:public path:docs migration</code> searches\n&quot;migration&quot; inside public notes under <code>docs/</code> — and a filter-only query lists\neverything that matches. Unknown or malformed <code>name:</code> tokens stay in the\nfree-text query. Matched terms render with <code>&lt;mark&gt;</code> highlighting built from\nDOM text nodes, never injected HTML.</p>\n<p>Search excerpts show readable article text and link labels. Resolved footnote\nmarkers and Markdown formatting are omitted; code, escaped text, and unresolved\nreferences remain literal. The full Markdown is interpreted before excerpts are\nclipped, so a definition later in the note still resolves its citation. Snippets\nkeep complete Unicode characters within their byte limit.</p>\n<p>For custom readers, <code>docs.json</code> stores the eager preview in <code>p</code> and the inline\nsearch basis in <code>x</code>. Hydrated note <code>text</code> holds bounded readable content,\nnormalized to NFC and lowercase for snippet matching. Use the document table\nand content postings for ranking; hydration supplies display text. Existing\npublished artifacts keep their original excerpts until republished.</p>\n<h3 id=\"safety\">Safety</h3>\n<p>Raw HTML never passes through the renderer: every text span and attribute is\nentity-escaped, only the controlled Markdown grammar emits markup, and external\nURLs are restricted to <code>http</code>, <code>https</code>, and <code>mailto</code>. Pages ship a strict\n<code>default-src 'self'</code> Content-Security-Policy, so no remote image, script, or\nframe can load. The output directory and vault must be separate: neither may contain the\nother, including through symlinked parent directories. The output directory\nitself cannot be a symlink, and every written path is confined to <code>--out</code>.\nGenerated JSON must pass the reader contracts before any output is replaced.\nEvery generated filename component must fit 255 UTF-8 bytes, and a generated\nfile cannot also serve as a directory. A conflicting or oversized filename\nproduces a rename instruction before an existing site is touched.\nAn oversized title or too many aliases or tags produces a named validation\nerror; shorten that field or narrow the selection and publish again.</p>\n<h2 id=\"host-the-result\">Host the result</h2>\n<p>The site is static files. Sync the output directory to any object store or\nstatic host — no adapter is required or bundled:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">aws</span> s3 sync site/ s3://bucket/handbook/ <span class=\"syntax-token syntax-token--flag\">--delete</span>\n<span class=\"syntax-token syntax-token--command\">rclone</span> sync site/ remote:handbook\n</code></pre></div></figure>\n<p>Serve under a subpath by passing <code>--base-path</code> at publish time. For a local\npreview, <code>wordcell serve</code> binds a static file server to the output directory:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> serve <span class=\"syntax-token syntax-token--flag\">--root</span> site <span class=\"syntax-token syntax-token--flag\">--port</span> 8080\n</code></pre></div></figure>\n<p>The server defaults to the loopback interface (<code>--host</code> overrides), maps\ndirectories to <code>index.html</code>, returns the published <code>404.html</code> for missing\npaths, confines requests and symlinks to the root, and answers <code>GET</code> and\n<code>HEAD</code> only. Production hosting stays with the object store or CDN. Any other static file\nserver works for previews too:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">python3</span> <span class=\"syntax-token syntax-token--flag\">-m</span> http.server <span class=\"syntax-token syntax-token--flag\">--directory</span> site 8080\n</code></pre></div></figure>\n<h2 id=\"host-on-wordcellio\">Host on wordcell.io</h2>\n<p><code>wordcell.io</code> also publishes a vault for you: the API runs the same projection\nserver-side and serves the emitted artifact at <code>https://wordcell.io/p/&lt;key8&gt;/&lt;slug&gt;/</code>.\nThis path exists for agents and machines that cannot hold files or deploy a\nstatic host; the CLI remains the primary publication path, and the artifact\ncontract is identical either way.</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">curl</span> <span class=\"syntax-token syntax-token--flag\">-s</span> <span class=\"syntax-token syntax-token--flag\">-X</span> POST https://wordcell.io/api/v1/tokens <span class=\"syntax-token syntax-token--flag\">-d</span> <span class=\"syntax-token syntax-token--string\">&#39;{&quot;label&quot;:&quot;my agent&quot;}&#39;</span>\n<span class=\"syntax-token syntax-token--comment\"># → { &quot;ok&quot;: true, &quot;token&quot;: &quot;wc_pub_…&quot;, &quot;key8&quot;: &quot;…&quot;, &quot;urlBase&quot;: &quot;…/p/&lt;key8&gt;/&quot; }</span>\n\n<span class=\"syntax-token syntax-token--command\">curl</span> <span class=\"syntax-token syntax-token--flag\">-s</span> <span class=\"syntax-token syntax-token--flag\">-X</span> PUT https://wordcell.io/api/v1/sites/handbook \\\n  <span class=\"syntax-token syntax-token--flag\">-H</span> <span class=\"syntax-token syntax-token--string\">&quot;Authorization: Bearer wc_pub_…&quot;</span> <span class=\"syntax-token syntax-token--flag\">-H</span> <span class=\"syntax-token syntax-token--string\">&quot;content-type: application/json&quot;</span> <span class=\"syntax-token syntax-token--flag\">-d</span> <span class=\"syntax-token syntax-token--string\">&#39;{</span>\n    <span class=\"syntax-token syntax-token--string\">&quot;operation&quot;</span>: {\n      <span class=\"syntax-token syntax-token--string\">&quot;contract&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;hraness.wordcell.hosted-operation.v1&quot;</span>,\n      <span class=\"syntax-token syntax-token--string\">&quot;id&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;32d708ac-782d-4ca0-8c34-3e89ad0ed02a&quot;</span>,\n      <span class=\"syntax-token syntax-token--string\">&quot;expectedRevision&quot;</span>: 0\n    <span class=\"syntax-token syntax-token--command\">},</span>\n    <span class=\"syntax-token syntax-token--string\">&quot;title&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;Team Handbook&quot;</span>,\n    <span class=\"syntax-token syntax-token--string\">&quot;files&quot;</span>: {\n      <span class=\"syntax-token syntax-token--string\">&quot;index.md&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;# Handbook\\n\\nStart with [[onboarding]].\\n&quot;</span>,\n      <span class=\"syntax-token syntax-token--string\">&quot;onboarding.md&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;# Onboarding\\n\\nWelcome.\\n&quot;</span>,\n      <span class=\"syntax-token syntax-token--string\">&quot;assets/logo.png&quot;</span>: {<span class=\"syntax-token syntax-token--string\">&quot;upload&quot;</span>: <span class=\"syntax-token syntax-token--string\">&quot;&lt;id from POST /api/v1/uploads&gt;&quot;</span>}\n    <span class=\"syntax-token syntax-token--command\">}</span>\n  <span class=\"syntax-token syntax-token--command\">}</span><span class=\"syntax-token syntax-token--string\">&#39;</span>\n<span class=\"syntax-token syntax-token--comment\"># → { &quot;ok&quot;: true, &quot;site&quot;: { &quot;url&quot;: &quot;https://wordcell.io/p/&lt;key8&gt;/handbook/&quot;, … } }</span>\n</code></pre></div></figure>\n<ul>\n<li><strong>Tokens are capability tokens.</strong> <code>POST /api/v1/tokens</code> is self-serve and\nfree, bounded per client address. The server stores only the token's SHA-256\ndigest; the digest's first 8 hex chars form the site namespace, so a token\ncan only create or replace its own sites. There is no account and no device\nflow at this stage.</li>\n<li><strong>Files</strong> map vault-relative paths to a UTF-8 string, <code>{&quot;base64&quot;: &quot;…&quot;}</code>, or\n<code>{&quot;upload&quot;: &quot;&lt;id&gt;&quot;}</code>. Uploads come from <code>POST /api/v1/uploads</code>, which mints a\nshort-lived, write-once presigned PUT (≤32 MiB); uploads expire after a day.\nInline bytes are capped at 4 MiB per request, 256 files per request.</li>\n<li><strong>Options</strong> (<code>title</code>, <code>description</code>, <code>index</code>, <code>noindex</code>, <code>indexContent</code>,\n<code>selection</code>) mirror the CLI flags; <code>selection</code> accepts the same\nincludes/excludes/globs/tags/repositoryScopes/filters/from shape. <code>index</code>\nselects the vault's index note path when it is not <code>index.md</code>.</li>\n<li><strong>Conditional writes and recovery.</strong> Read the current revision with <code>GET</code>\nbefore a write. PUT and DELETE require a unique operation ID and the revision\nthey expect to replace. Exact retries return the original receipt. Resolve\nuncertain outcomes with <code>GET ?operation=&lt;id&gt;</code>. One conditional site-head\nwrite changes the record and public visibility after all artifact bytes are\ndurable. DELETE retains a tombstone and receipts; shared artifact bytes stay\nstored. See the <a href=\"/docs/hosted-publication\">hosted operation contract</a> for request\nshapes, conflict handling, and recovery. Public reads can remain cached for\nup to 60 seconds.</li>\n<li><strong>Bounds.</strong> Hosted publication accepts ≤256 files per request, applies the\ncontract's per-note and per-asset byte caps, and rejects projected output\nover 3,500 files or 256 MiB. Tokens get 60 publishes per day and 50 distinct\nreserved slugs, including deletions and interrupted operations; addresses get 8 token mints and\n120 publishes per day.\nPublic reads carry no quota beyond ordinary CDN caching.</li>\n<li><strong>Data.</strong> The request vault is materialized to a temporary directory for the\nprojection and deleted when the request ends; only the emitted artifact\npersists. Quota counters expire within two days; token digests, site records,\nnamespace reservations, operation receipts, and tombstones persist. Published sites are\npublic by contract — never publish private content.</li>\n<li><strong>Search indexing.</strong> Hosted sites can be indexed by search engines by\ndefault. To opt out, send <code>&quot;noindex&quot;: true</code>: every page then carries a\n<code>noindex</code> robots tag. Crawlers read <code>robots.txt</code> only at the root of\nwordcell.io, so the site's own <code>robots.txt</code> has no effect there. Each HTML\npage is served with a canonical <code>Link</code> header that names its wordcell.io\nURL. Either way, the site stays public to anyone with the link.</li>\n</ul>\n<p><code>GET /api/v1/openapi.json</code> returns the OpenAPI 3.1 description;\n<code>GET /api/v1/health</code> reports service and storage health. MCP clients can use\nthe streamable-HTTP endpoint <code>POST /api/v1/mcp</code> instead of REST: it exposes\n<code>create_token</code>, <code>get_site</code>, <code>publish_site</code>, <code>list_sites</code>, and <code>delete_site</code> tools that\ndispatch to the identical route logic — send the <code>wc_pub_</code> Bearer token as on\nREST, and <code>create_token</code> stays unauthenticated so an MCP-only client can\nonboard itself. The storage layer is\na private Cloudflare R2 bucket behind the <code>wordcell-sites</code> worker — object\nreads and writes are HMAC-signed, and the public <code>/p/</code> path resolves the site\nhead to immutable artifact bytes with directory-index and <code>404.html</code>\nsemantics identical to <code>wordcell serve</code>.</p>\n<p>Hosted directory pages use a trailing slash so their relative navigation and\nreader assets stay inside the edition. A slashless request redirects only\nafter the Worker finds that directory's index; files and missing paths do not\nacquire a slash. The site proxy preserves <code>/p/</code> paths and keeps other site\npages on their usual slashless URLs.</p>\n<p>When introducing this routing policy, deploy the site first and verify that a\nhosted directory URL returns its published HTML and keeps its slash, then deploy\nthe Worker redirect. The Vercel configuration has a separate trailing-slash\nrewrite before the slashless rule; both must forward the original path form.\nVerify root and nested published pages on the preview deployment before merging.\nThe local Next server does not exercise Vercel's external rewrites. Reversing\nthat order creates a redirect loop with the older site. Roll back the Worker\nbefore restoring the older site policy. Existing stored artifacts need no rewrite.</p>\n<h2 id=\"programmatic-use\">Programmatic use</h2>\n<p><code>publishVault</code> drives the filesystem pipeline; <code>projectVault</code> projects an\nalready-scanned snapshot through an injectable <code>PublishIo</code> seam, so tests and\nalternative hosts can resolve and read assets without disk access:</p>\n<pre><code class=\"syntax-code language-typescript\" data-language=\"typescript\"><span class=\"sh__line\"><span class=\"sh__token--keyword\">import</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">publishVault</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">from</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">@hraness/wordcell/publish</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"></span>\n<span class=\"sh__line\"><span class=\"sh__token--keyword\">const</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">preview</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">await</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">publishVault</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">root</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">out</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">site</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">selection</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">includeGlobs</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">guides/**/*.md</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">includes</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">notes/getting-started</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">dryRun</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">true</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--identifier\">listLimit</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">10</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--identifier\">console</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">log</span><span class=\"sh__token--sign\">(</span><span class=\"sh__token--identifier\">preview</span><span class=\"sh__token--sign\">.</span><span class=\"sh__token--property\">report</span><span class=\"sh__token--sign\">)</span><span class=\"sh__token--sign\">;</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--comment\">// counts, selected ids, and digest; no note bodies</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--comment\"></span></span></code></pre>\n<p><code>parseSiteManifestV1</code> and <code>WORDCELL_SITE_LIMITS_V1</code> are available from\n<code>@hraness/wordcell/publish-model</code>. The constants fix every artifact bound: note,\nasset, term, shard, preview, inline-text, payload-text, and hydration caps.</p>\n",
   "portfolio": "<h1 id=\"search-several-vaults-together\">Search several vaults together</h1>\n<p>Portfolio federation searches and audits selected Markdown vaults without combining their files or indexes. A strict registry gives each vault a stable logical identity and maps that identity to a checkout under one workspace. Each vault keeps its own Markdown, local graph, optional QMD index, and Git history.</p>\n<p>The registry discovers vaults. An explicit selection determines which vaults a command or SDK session may open.</p>\n<h2 id=\"define-a-v1-registry\">Define a v1 registry</h2>\n<p>A v1 registry is a JSON file with the contract <code>hraness.kb-portfolio/v1</code> and <code>schemaVersion</code> <code>1</code>:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">contract</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hraness.kb-portfolio/v1</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">schemaVersion</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">vaults</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">owner</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">example</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">repository</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">example/product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">checkout</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">history-vault</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">role</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">repository</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">visibility</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">organization</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">defaultRef</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">main</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">parserVersion</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">owner</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hraness</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">legacy-notes</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">repository</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hraness/legacy-notes</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">checkout</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">legacy-notes</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">role</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">archive</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">visibility</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">private</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">parserVersion</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">owner</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">personal</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">tiff</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">repository</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">personal/tiff</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">checkout</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">tiff</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">root</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">kb</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">role</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">portfolio</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">visibility</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">personal</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">parserVersion</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">]</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">authorityGroups</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">members</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">        </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">example/product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">        </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hraness/legacy-notes</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--sign\">]</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">state</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">unresolved</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">protected</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--keyword\">true</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">reason</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">An owner must choose the maintained authority.</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>The vault key is the explicit <code>owner/id</code> pair. It remains <code>example/product-history</code> even when the local checkout is named <code>history-vault</code>. Do not derive a vault key from <code>checkout</code>, <code>root</code>, or a Git remote.</p>\n<p>The other fields have separate purposes:</p>\n<ul>\n<li><code>repository</code> is the logical repository identity.</li>\n<li><code>checkout</code> is a relative path under the <code>--workspace</code> directory.</li>\n<li><code>root</code> is a relative path under the checkout. Use <code>.</code> when the repository root is the vault root.</li>\n<li><code>role</code> is <code>portfolio</code>, <code>repository</code>, <code>archive</code>, <code>template</code>, or <code>sample</code>. It changes audit severity for missing stable IDs. It does not grant access.</li>\n<li><code>visibility</code> is <code>public</code>, <code>organization</code>, <code>private</code>, or <code>personal</code>. It controls the CLI's <code>--shared</code> selection. It is not a filesystem permission.</li>\n<li><code>parserVersion</code> is exactly <code>1</code> in this contract.</li>\n</ul>\n<p>The parser rejects unknown properties and unsafe paths. A registry is limited to 1 MiB, 128 vaults, and 64 authority groups. One operation may select at most 32 vaults. <code>--shared</code> and <code>--all</code> reject a registry-derived selection above that bound; they never truncate it silently.</p>\n<h2 id=\"select-vaults-explicitly\">Select vaults explicitly</h2>\n<p>The SDK requires a nonempty <code>authorizedVaults</code> list. The CLI offers three selection forms:</p>\n<ul>\n<li>Repeated <code>--vault owner/id</code> selects the named vaults.</li>\n<li><code>--shared</code> selects entries whose visibility is <code>public</code> or <code>organization</code>.</li>\n<li><code>--all</code> selects every registry entry and is available only for audit.</li>\n</ul>\n<p>Use <code>--vault</code> for <code>private</code> and <code>personal</code> entries. Use <code>--all</code> only when the process is permitted to read every configured vault.</p>\n<p>After selection, the portfolio core resolves, opens, scans, and reports only selected vaults. Results do not expose names, counts, paths, or failures from unselected vaults. The CLI must still read and validate the registry to compute <code>--shared</code> or <code>--all</code>, so access to registry metadata is a separate prerequisite. It passes that exact immutable registry snapshot into the operation; authorization and checkout resolution cannot observe two different registry versions.</p>\n<p>Visibility is a registry classification. Operating-system permissions and workspace confinement remain the access boundary. A registry entry cannot give the process access to a checkout it cannot already read.</p>\n<h2 id=\"search-selected-vaults\">Search selected vaults</h2>\n<p>Search the shared vaults under one workspace:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;durable agent memory&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--shared</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--mode</span> hybrid \\\n  <span class=\"syntax-token syntax-token--flag\">--limit</span> 10\n</code></pre></div></figure>\n<p>Select private or personal vaults by exact key:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;release rationale&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--vault</span> example/product-history \\\n  <span class=\"syntax-token syntax-token--flag\">--vault</span> hraness/legacy-notes \\\n  <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p>The supported modes are <code>hybrid</code>, <code>exact</code>, <code>keyword</code>, and <code>semantic</code>. Add <code>--json</code> to inspect per-vault diagnostics and local retrieval evidence.</p>\n<p>A query that is a canonical qualified URI routes directly to its named selected vault and uses exact retrieval:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;kb://example/product-history/018f4b20-7c95-7af2-a11f-89011baf1137&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--vault</span> example/product-history\n</code></pre></div></figure>\n<p>If that vault or document is outside the selection, the search does not reveal whether it exists elsewhere.</p>\n<h3 id=\"failure-policy\">Failure policy</h3>\n<p>Portfolio search uses the <code>partial</code> failure policy by default. A selected vault that cannot resolve, open, or complete its search produces a selected-vault diagnostic. Results from available selected vaults remain usable, and the result has <code>partial: true</code>.</p>\n<p>Add <code>--require-all</code> when every selected vault must resolve, open, and execute its search:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;release rationale&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--shared</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--require-all</span>\n</code></pre></div></figure>\n<p><code>--require-all</code> does not turn an optional QMD or Git provenance degradation into a fatal error. Inspect <code>partial</code> and the lane diagnostics when completeness matters.</p>\n<h3 id=\"deterministic-federation-order\">Deterministic federation order</h3>\n<p>Each vault performs its own exact or QMD-backed retrieval. The federation layer keeps QMD scores inside that vault's evidence because scores from separate QMD databases are not comparable.</p>\n<p>The global merge uses this order:</p>\n<ol>\n<li>Exact identity matches precede other matches.</li>\n<li>A reciprocal score derived from the result's local rank orders the remaining candidates.</li>\n<li>The stable vault key breaks a tie.</li>\n<li>The qualified identity or current path breaks the final tie.</li>\n</ol>\n<p>The returned portfolio <code>score</code> describes this reciprocal local-rank merge. It is not a probability or a QMD similarity score. Raw local evidence remains available under the hit's <code>local</code> and <code>evidence</code> fields.</p>\n<p>Graph traversal remains vault-local. Portfolio search does not infer a cross-vault neighborhood or use graph context as a relevance boost.</p>\n<h2 id=\"give-notes-stable-identities\">Give notes stable identities</h2>\n<p>Use <code>document_id</code> for an identity that survives a path change:</p>\n<pre><code class=\"syntax-code language-markdown\" data-language=\"markdown\">---\ndocument_id: 018f4b20-7c95-7af2-a11f-89011baf1137\ntype: concept\ntitle: Durable agent memory\n---\n\n<span class=\"syntax-token syntax-token--marker\">#</span> <span class=\"syntax-token syntax-token--heading\">Durable agent memory</span>\n</code></pre>\n<p><code>document_id</code> is a lowercase ASCII ID of at most 128 bytes. It may contain letters, digits, dots, underscores, and hyphens. Ordinary notes created through <code>wordcell note create</code> or <code>createNote</code> receive a UUID v4 when the caller does not provide an ID.</p>\n<p>An idempotent create preserves an existing valid ID. It leaves a legacy note without an ID unchanged, and it rejects an explicit ID that conflicts with the existing note. Add IDs to legacy notes through a reviewed Markdown edit rather than treating an idempotent create as a migration.</p>\n<p>A stable portfolio URI combines the logical vault identity and the authored document ID:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">kb://owner/vault/document_id\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">kb://example/product-history/018f4b20-7c95-7af2-a11f-89011baf1137\n</code></pre>\n<p>The URI is byte-canonical. Uppercase aliases, percent-encoded components, path traversal, and extra path segments are rejected. A <code>document_id</code> must be unique within its vault. The same ID in two different vaults produces two different qualified URIs.</p>\n<p>Notes without a valid <code>document_id</code> remain searchable through a tagged <code>legacy-path</code> identity. A legacy path is not reported as stable and cannot be used for a qualified read.</p>\n<h2 id=\"author-cross-vault-relations\">Author cross-vault relations</h2>\n<p>A typed relation may target a canonical qualified URI:</p>\n<pre><code class=\"syntax-code language-yaml\" data-language=\"yaml\"><span class=\"syntax-token syntax-token--property\">relations</span><span class=\"syntax-token syntax-token--operator\">:</span>\n  <span class=\"syntax-token syntax-token--property\">supports</span><span class=\"syntax-token syntax-token--operator\">:</span>\n    <span class=\"syntax-token syntax-token--operator\">-</span> kb://example/product-history/018f4b20-7c95-7af2-a11f-89011baf1137\n</code></pre>\n<p>The source note still owns the assertion. The local graph records it as an external authored relation instead of resolving it to a local note ID.</p>\n<p>Portfolio audit verifies the target against valid stable IDs in the explicitly selected, successfully audited vaults. It reports <code>external-relation-unavailable</code> when the target is not available in that selection. This diagnostic does not claim that the target is absent from an unselected vault.</p>\n<p>Cross-vault relations do not create inferred backlinks, reciprocal assertions, or cross-vault graph traversal. Author each assertion in Markdown where its source belongs.</p>\n<h2 id=\"audit-a-portfolio\">Audit a portfolio</h2>\n<p>Run a report-only audit across the shared selection:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio audit \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--shared</span>\n</code></pre></div></figure>\n<p>Audit exact vaults when the review includes private material:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio audit \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--vault</span> example/product-history \\\n  <span class=\"syntax-token syntax-token--flag\">--vault</span> hraness/legacy-notes \\\n  <span class=\"syntax-token syntax-token--flag\">--strict</span>\n</code></pre></div></figure>\n<p>The default command exits successfully after producing the report, even when the report contains issues. <code>--strict</code> exits with status <code>3</code> when the report contains at least one error or is truncated. Warnings and advisories do not trigger that exit status. Use <code>--json</code> for the complete bounded report; its <code>ok</code> field is also false for an error or truncation.</p>\n<p>Audit checks include:</p>\n<ul>\n<li>missing, invalid, and duplicate <code>document_id</code> values;</li>\n<li>unavailable cross-vault relation targets within the selected audit scope;</li>\n<li>broken or ambiguous links and malformed or unresolved local relations;</li>\n<li>local attachment failures;</li>\n<li>stale managed catalogs and unavailable Git provenance;</li>\n<li>invalid, unavailable, or overlapping selected roots;</li>\n<li>exact duplicate content across selected notes; and</li>\n<li>unresolved authority groups whose complete membership is selected.</li>\n</ul>\n<p>Missing IDs are warnings in <code>portfolio</code> and <code>repository</code> vaults. They are advisories in <code>archive</code>, <code>template</code>, and <code>sample</code> vaults. Invalid or duplicate IDs are errors. Exact duplicate content is a warning when an active vault is involved and an advisory otherwise.</p>\n<p>An audit is <code>partial</code> when a selected vault is unavailable or the report is truncated. Ordinary findings do not by themselves make the report partial. The default issue limit is 500, and the maximum is 5,000. Severity counts include every discovered issue even when only a bounded severity-preserving sample is materialized. <code>--strict</code> fails closed when any error is counted or when the report is truncated.</p>\n<p>Audit is read-only. It does not assign IDs, repair links, update a catalog, deduplicate notes, move files, or choose an authority.</p>\n<h2 id=\"record-authority-decisions\">Record authority decisions</h2>\n<p>An authority group records a reviewed decision state among registry members. Use <code>state: &quot;unresolved&quot;</code> while an owner must still choose. An unresolved group cannot declare <code>canonical</code>.</p>\n<p>After review, change the state and name one member:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">members</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">example/product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hraness/legacy-notes</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">]</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">state</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">resolved</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">canonical</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">example/product-history</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">reason</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">The maintained repository owns current product history.</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p><code>protected: true</code> marks a group whose duplicate material must remain visible during review. It does not suppress duplicate findings, grant access, or change search rank.</p>\n<p>Use this migration sequence:</p>\n<ol>\n<li>Register each real vault with its current stable logical <code>owner/id</code> identity.</li>\n<li>Mark unresolved authority groups before moving or deleting content.</li>\n<li>Run a selected audit and review root, identity, relation, and duplicate findings.</li>\n<li>Add <code>document_id</code> to maintained legacy notes through reviewed Markdown edits. Preserve an ID when a note moves.</li>\n<li>Replace cross-vault path assumptions with reviewed <code>kb://</code> relation targets.</li>\n<li>Resolve an authority group only after its owner selects a canonical member and records the reason.</li>\n<li>Enable <code>--strict</code> in automation after expected errors have been resolved.</li>\n</ol>\n<p>Keep protected duplicate sources until their owner approves a consolidation. The registry and audit surface an authority conflict; they do not settle it.</p>\n<h2 id=\"keep-search-rules-opt-in\">Keep search rules opt-in</h2>\n<p>Search rules are a strict configuration with <code>schemaVersion: 1</code>, named leading aliases, and priority rules. Configure them through <code>OpenKnowledgeBaseOptions.searchRules</code>, or through <code>OpenKnowledgePortfolioOptions.knowledgeBase.searchRules</code> for each local vault session. The CLI reads the same bounded JSON contract from <code>--rules &lt;file&gt;</code>.</p>\n<p>For example, a consumer-owned <code>search-rules.json</code> can define one constrained alias and one opt-in maintained-note tier:</p>\n<pre><code class=\"syntax-code language-json\" data-language=\"json\"><span class=\"sh__line\"><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">schemaVersion</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">aliases</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">active-plans</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">mode</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">hybrid</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">filters</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">        </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">          </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">kind</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">one-of</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">          </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">path</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">status</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">          </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">values</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">proposed</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">accepted</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">in-progress</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">        </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">}</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">priorityRules</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--sign\">[</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">{</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">id</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">maintained-notes</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">tier</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">1</span><span class=\"sh__token--sign\">,</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">      </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">pathPrefix</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">notes/</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">]</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">}</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>The full alias fields are <code>query</code>, <code>mode</code>, <code>filters</code>, <code>tags</code>, and <code>repositoryScopes</code>. A priority rule needs a canonical <code>id</code>, a tier from 1 through 32, and at least one of <code>pathPrefix</code>, <code>tagsAll</code>, <code>repositoryScope</code>, <code>metadata</code>, or <code>vaultId</code>. Unknown fields and malformed predicates are rejected.</p>\n<p>A leading alias expands only when it is the first query token, such as <code>@active context</code>. Alias filters, tags, and repository scopes add constraints. Caller-provided constraints are preserved.</p>\n<p>Priority rules may match <code>pathPrefix</code>, <code>tagsAll</code>, <code>repositoryScope</code>, <code>metadata</code>, or <code>vaultId</code>. Conditions on one rule are combined with AND. Smaller positive <code>tier</code> values are preferred. Exact identity matches remain ahead of every tier, and ties retain the original relevance order.</p>\n<p>Priority ordering applies only when a search request sets:</p>\n<pre><code class=\"syntax-code language-typescript\" data-language=\"typescript\"><span class=\"sh__line\"><span class=\"sh__token--identifier\">ordering</span><span class=\"sh__token--sign\">:</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">priority-then-relevance</span><span class=\"sh__token--string\">&quot;</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>The default is <code>ordering: &quot;relevance&quot;</code>, which leaves configured priority rules inactive. A single-vault <code>KnowledgeBaseSearchResult</code> includes a trace when at least one selected hit matches a priority rule, whether or not that match changes the final ordering. Search rules do not create authority, permissions, graph edges, or Markdown edits.</p>\n<p>On the CLI, <code>--rules</code> enables leading aliases. Add <code>--priority</code> to request priority ordering:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;@active parser&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> ./kb \\\n  <span class=\"syntax-token syntax-token--flag\">--rules</span> ./search-rules.json \\\n  <span class=\"syntax-token syntax-token--flag\">--priority</span>\n\n<span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;@active parser&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> /srv/knowledge \\\n  <span class=\"syntax-token syntax-token--flag\">--shared</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--rules</span> ./search-rules.json \\\n  <span class=\"syntax-token syntax-token--flag\">--priority</span>\n</code></pre></div></figure>\n<p><code>--priority</code> without <code>--rules</code> is rejected. A rules file may contain at most 128 KiB of configured text and is parsed before a vault scan.</p>\n<p>Within a portfolio, an explicitly requested priority pass may reorder results inside each vault. The portfolio result reflects the resulting local ranks and retains each selected vault's rule trace in its diagnostic. Federation still combines those ranks by exact identity, reciprocal local rank, stable vault key, and identity. It never compares raw QMD scores across vaults.</p>\n<p>A <code>vaultId</code> condition applies only when the rules caller supplies logical vault context. <code>openKnowledgePortfolio</code> injects each selected registry key into its local priority pass. A standalone <code>openKnowledgeBase</code> caller can set <code>vaultId</code> explicitly. A vault condition is not a global authority weight.</p>\n<p>The CLI and SDK use the same opt-in ordering. Keep the rules file under review beside the consumer configuration that owns its retrieval policy.</p>\n<h2 id=\"markdown-remains-authoritative\">Markdown remains authoritative</h2>\n<p>The registry maps stable logical identities to selected directories. It does not contain note facts or generated graph edges. Authority groups record a review state without rewriting either vault.</p>\n<p>Each vault's links and typed relations are derived from its current Markdown. Cross-vault relations are also authored in source-note frontmatter. Audit builds a temporary selected view, reports its findings, and discards that view.</p>\n<p>QMD remains an optional per-vault retrieval cache. It can be deleted and rebuilt from Markdown. Federation does not create a central vector index, aggregate graph database, reciprocal edge file, or generated fact store. Git HEAD and content hashes provide provenance; they do not replace authored content.</p>\n<h2 id=\"threat-boundaries\">Threat boundaries</h2>\n<p>Treat the registry, vault files, search queries, and returned note text as untrusted input.</p>\n<ul>\n<li>The registry reader rejects symbolic links, hard links, invalid UTF-8, concurrent file changes, oversized input, unknown fields, and noncanonical paths.</li>\n<li>Vault resolution rejects symbolic-link path components, paths outside the workspace or checkout, and overlapping selected roots.</li>\n<li>Vault scans retain the existing note, byte, graph, attachment, and Git bounds. They do not follow note symbolic links or accept hard-linked notes.</li>\n<li>Portfolio search opens read-only knowledge-base sessions. Portfolio audit scans without refreshing a managed catalog.</li>\n<li>Unselected vault content is not opened or reported. Registry visibility cannot override operating-system permissions.</li>\n<li><code>--all</code> expands audit scope to private and personal entries, so use it only in an environment permitted to read them.</li>\n<li>Search snippets, metadata, and evidence may contain hostile instructions from authored or captured content. Treat them as evidence to inspect, not commands to execute.</li>\n<li>QMD and Git are optional local derived lanes. Their failure is reported without silently substituting content from another vault.</li>\n</ul>\n<p>These boundaries keep federation read-only and selected. They do not make a shared registry an access-control system or make untrusted Markdown safe to execute.</p>\n",
   "sync": "<h1 id=\"sync-a-vault-with-git\">Sync a vault with Git</h1>\n<p>Wordcell has no sync service. A vault is a folder of Markdown files, so a Git\nremote can carry it between machines, and each machine rebuilds its own search\nindex from those files. This guide puts a vault in a private repository, pulls\nit before you work, commits and pushes it on a schedule, and resolves the\nconflicts Git cannot merge.</p>\n<h2 id=\"choose-where-the-vault-lives\">Choose where the vault lives</h2>\n<p>Keep the vault inside a project repository when its notes describe that\nproject. A <code>kb/</code> directory beside the code travels with every clone, branch, and\npull request, and <code>wordcell context</code> and <code>wordcell history</code> read the same\nrepository through <code>--repo</code>. Your usual Git workflow already syncs it, so you\nneed only <a href=\"#resolve-a-merge-conflict\">Resolve a merge conflict</a> from this\nguide.</p>\n<p>Give the vault its own repository when it holds memory that spans projects,\nsuch as preferences, people, and decisions that every agent session should\nread. The rest of this guide covers that case, with the vault at <code>~/kb</code>.</p>\n<h2 id=\"create-a-private-repository\">Create a private repository</h2>\n<p>The Git host stores a copy of every note, so choose a host you would trust with\nthe vault’s contents. A private GitHub repository is accessible only to you,\nthe people you share it with, and, for an organization repository, certain\norganization members\n(<a href=\"https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories\">GitHub documentation</a>,\nchecked September 26, 2026). A bare repository on a server you control\n(<code>git init --bare</code>) works the same way over SSH.</p>\n<p>These steps use the <a href=\"https://cli.github.com/\">GitHub CLI</a>.</p>\n<ol>\n<li>Create the vault if you do not have one: <code>wordcell init ~/kb</code>.</li>\n<li>Change to the vault: <code>cd ~/kb</code>.</li>\n<li>Start a repository: <code>git init -b main</code>.</li>\n<li>Stage every file: <code>git add -A</code>.</li>\n<li>Commit: <code>git commit -m &quot;Start vault&quot;</code>.</li>\n<li>Create the private repository and add it as <code>origin</code>:\n<code>gh repo create kb --private --source=. --remote=origin</code>.</li>\n<li>Push and set the upstream branch: <code>git push -u origin main</code>.</li>\n</ol>\n<p>With another host, create an empty private repository in its interface, then\nrun <code>git remote add origin &lt;repository URL&gt;</code> in place of step 6.</p>\n<h2 id=\"pull-before-you-work\">Pull before you work</h2>\n<p>On each other machine, clone the repository once:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">git</span> clone <span class=\"syntax-token syntax-token--operator\">&lt;</span>repository URL<span class=\"syntax-token syntax-token--operator\">&gt;</span> ~/kb\n</code></pre></div></figure>\n<p>Pull at the start of each session so that you and your agents read the latest\nnotes:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">git</span> <span class=\"syntax-token syntax-token--flag\">-C</span> ~/kb pull <span class=\"syntax-token syntax-token--flag\">--no-rebase</span>\n</code></pre></div></figure>\n<p>Git carries only the files. Exact search, links, and <code>wordcell check</code> read the\nMarkdown directly, so they are current after a pull. Keyword, semantic, and\nhybrid search read the optional local QMD index, which stays on each machine.\nWhere you use those modes, run <code>wordcell index --root ~/kb</code> after a pull to\nupdate the index incrementally. <code>wordcell graph rebuild</code> writes\n<code>.wordcell/oh.sqlite</code>, which Git ignores, so rebuild it on each machine that\nuses it.</p>\n<p>A running <a href=\"/docs/reference#local-mcp-server\"><code>wordcell mcp</code></a> server reads edits\nfrom an editor or Git on its next call, so you do not need to restart it after\na pull.</p>\n<h2 id=\"commit-and-push-on-a-schedule\">Commit and push on a schedule</h2>\n<p>Save this script as <code>~/bin/sync-vault.sh</code>. It commits every change in the vault,\nmerges the remote branch, and pushes. When the merge conflicts, it restores the\nstate from before the pull, keeps your local commit, and exits 1. A scheduled\nrun never leaves conflict markers in your notes.</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--comment\">#!/bin/sh</span>\n<span class=\"syntax-token syntax-token--comment\"># Commit local changes, merge the remote branch, and push.</span>\n<span class=\"syntax-token syntax-token--comment\"># On a merge conflict, restore the pre-merge state and exit 1.</span>\n<span class=\"syntax-token syntax-token--command\">set</span> <span class=\"syntax-token syntax-token--flag\">-eu</span>\n<span class=\"syntax-token syntax-token--variable\">vault=</span><span class=\"syntax-token syntax-token--string\">&quot;${1:?usage: sync-vault.sh &lt;vault directory&gt;}&quot;</span>\n<span class=\"syntax-token syntax-token--command\">cd</span> <span class=\"syntax-token syntax-token--string\">&quot;$vault&quot;</span>\n\n<span class=\"syntax-token syntax-token--command\">git</span> add <span class=\"syntax-token syntax-token--flag\">-A</span>\n<span class=\"syntax-token syntax-token--keyword\">if</span> <span class=\"syntax-token syntax-token--command\">!</span> git diff <span class=\"syntax-token syntax-token--flag\">--cached</span> <span class=\"syntax-token syntax-token--flag\">--quiet</span><span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">then</span>\n  <span class=\"syntax-token syntax-token--command\">git</span> commit <span class=\"syntax-token syntax-token--flag\">--quiet</span> <span class=\"syntax-token syntax-token--flag\">-m</span> <span class=\"syntax-token syntax-token--string\">&quot;Sync vault from $(hostname)&quot;</span>\n<span class=\"syntax-token syntax-token--keyword\">fi</span>\n\n<span class=\"syntax-token syntax-token--keyword\">if</span> <span class=\"syntax-token syntax-token--command\">!</span> git pull <span class=\"syntax-token syntax-token--flag\">--quiet</span> <span class=\"syntax-token syntax-token--flag\">--no-rebase</span> <span class=\"syntax-token syntax-token--flag\">--no-edit</span><span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">then</span>\n  <span class=\"syntax-token syntax-token--keyword\">if</span> <span class=\"syntax-token syntax-token--command\">git</span> rev-parse <span class=\"syntax-token syntax-token--flag\">-q</span> <span class=\"syntax-token syntax-token--flag\">--verify</span> MERGE_HEAD <span class=\"syntax-token syntax-token--operator\">&gt;</span>/dev/null<span class=\"syntax-token syntax-token--operator\">;</span> <span class=\"syntax-token syntax-token--keyword\">then</span>\n    <span class=\"syntax-token syntax-token--command\">git</span> merge <span class=\"syntax-token syntax-token--flag\">--abort</span>\n    <span class=\"syntax-token syntax-token--command\">echo</span> <span class=\"syntax-token syntax-token--string\">&quot;sync-vault: merge conflict in $vault; resolve it by hand&quot;</span> <span class=\"syntax-token syntax-token--operator\">&gt;</span><span class=\"syntax-token syntax-token--operator\">&amp;</span>2\n  <span class=\"syntax-token syntax-token--keyword\">fi</span>\n  <span class=\"syntax-token syntax-token--command\">exit</span> 1\n<span class=\"syntax-token syntax-token--keyword\">fi</span>\n\n<span class=\"syntax-token syntax-token--command\">git</span> push <span class=\"syntax-token syntax-token--flag\">--quiet</span>\n</code></pre></div></figure>\n<p><code>git add -A</code> stages every file under the vault. Keep files you do not want on\nthe remote outside the vault, or list them in a <code>.gitignore</code> file. The script\nmerges instead of rebasing, so <code>git merge --abort</code> returns the vault to the\nexact state it had before the pull, and the next run tries again.</p>\n<p>The job runs without a terminal, so Git must reach the remote without asking\nfor a password or passphrase. For a GitHub remote over HTTPS,\n<code>gh auth setup-git</code> configures the GitHub CLI as Git’s credential helper. Run\nthe script once by hand to confirm that it exits 0:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">sh</span> ~/bin/sync-vault.sh ~/kb\n</code></pre></div></figure>\n<h3 id=\"schedule-it-with-cron\">Schedule it with cron</h3>\n<p>Run <code>crontab -e</code> and add this line to sync every 30 minutes:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">*/30 * * * * /bin/sh &quot;$HOME/bin/sync-vault.sh&quot; &quot;$HOME/kb&quot; &gt;&gt;&quot;$HOME/sync-vault.log&quot; 2&gt;&amp;1\n</code></pre>\n<h3 id=\"schedule-it-with-launchd-on-macos\">Schedule it with launchd on macOS</h3>\n<p>Save this agent as <code>~/Library/LaunchAgents/com.example.wordcell-sync.plist</code>.\nReplace <code>/Users/you</code> with your home directory, because each path must be\nabsolute.</p>\n<pre><code class=\"syntax-code language-html\" data-language=\"html\"><span class=\"sh__line\"><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--sign\">?</span><span class=\"sh__token--identifier\">xml</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">version</span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">1.0</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">encoding</span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">UTF-8</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">?</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--sign\">!</span><span class=\"sh__token--class\">DOCTYPE</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--identifier\">plist</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--class\">PUBLIC</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">-//Apple//DTD PLIST 1.0//EN</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">http://www.apple.com/DTDs/PropertyList-1.0.dtd</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">plist</span><span class=\"sh__token--space\"> </span><span class=\"sh__token--property\">version</span><span class=\"sh__token--sign\">=</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--string\">1.0</span><span class=\"sh__token--string\">&quot;</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\"></span></span>\n<span class=\"sh__line\"><span class=\"sh__token--jsxliterals\"></span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">dict</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\"></span></span>\n<span class=\"sh__line\"><span class=\"sh__token--jsxliterals\"></span><span class=\"sh__token--jsxliterals\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">Label</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">com.example.wordcell-sync</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">ProgramArguments</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">array</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\"></span></span>\n<span class=\"sh__line\"><span class=\"sh__token--jsxliterals\"></span><span class=\"sh__token--jsxliterals\">    </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">/bin/sh</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">/Users/you/bin/sync-vault.sh</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">    </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">/Users/you/kb</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">array</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">StartInterval</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">integer</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">1800</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">integer</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">StandardOutPath</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">/Users/you/Library/Logs/wordcell-sync.log</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">StandardErrorPath</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">key</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--space\">  </span><span class=\"sh__token--sign\">&lt;</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span><span class=\"sh__token--jsxliterals\">/Users/you/Library/Logs/wordcell-sync.log</span><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">string</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">dict</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"><span class=\"sh__token--sign\">&lt;/</span><span class=\"sh__token--entity\">plist</span><span class=\"sh__token--sign\">&gt;</span></span>\n<span class=\"sh__line\"></span></code></pre>\n<p>Load it:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">launchctl</span> bootstrap gui/<span class=\"syntax-token syntax-token--variable\">$</span><span class=\"syntax-token syntax-token--operator\">(</span>id <span class=\"syntax-token syntax-token--flag\">-u</span><span class=\"syntax-token syntax-token--operator\">)</span> ~/Library/LaunchAgents/com.example.wordcell-sync.plist\n</code></pre></div></figure>\n<p>To stop it, run the same command with <code>bootout</code> in place of <code>bootstrap</code>.\nlaunchd skips an interval that falls while the Mac is asleep and runs the job\nat the next one.</p>\n<h2 id=\"resolve-a-merge-conflict\">Resolve a merge conflict</h2>\n<p>Git merges changes to separate parts of a file and stops when both sides\nchanged the same or neighboring lines\n(<a href=\"https://git-scm.com/docs/git-merge#_how_conflicts_are_presented\">git-merge documentation</a>,\nchecked September 26, 2026). Edits to different notes never conflict. Three\nconflicts are common in a vault:</p>\n<ul>\n<li>Two machines changed the same or neighboring lines of one note.</li>\n<li>Two machines created a note with the same ID.</li>\n<li>Two machines added notes and ran <code>wordcell refresh</code>, so both rewrote the\nmanaged catalog in <code>index.md</code>.</li>\n</ul>\n<p>When the log shows <code>sync-vault: merge conflict</code>, resolve it by hand:</p>\n<ol>\n<li>Change to the vault: <code>cd ~/kb</code>.</li>\n<li>Merge the remote branch: <code>git pull --no-rebase</code>.</li>\n<li>List the conflicted files: <code>git status --short</code>. Each one starts with <code>UU</code>,\nor with <code>AA</code> when both machines created it. <code>UD</code> or <code>DU</code> means one machine\ndeleted a note that the other edited. Step 8 keeps the edited note unless\nyou remove it first with <code>git rm</code>.</li>\n<li>Edit each conflicted note to keep the text you want, and delete the\n<code>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code>, <code>=======</code>, and <code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</code> lines.</li>\n<li>If <code>index.md</code> conflicts, take the remote side: <code>git checkout --theirs index.md</code>.\nThe next step regenerates its catalog from the notes.</li>\n<li>Rebuild the catalog: <code>wordcell refresh --root .</code>.</li>\n<li>Check the vault: <code>wordcell check --root .</code>. Fix anything it reports.</li>\n<li>Stage the result: <code>git add -A</code>.</li>\n<li>Commit the merge: <code>git commit --no-edit</code>.</li>\n<li>Push: <code>sh ~/bin/sync-vault.sh ~/kb</code>.</li>\n</ol>\n<p>To give up on a merge and return to your local commit, run <code>git merge --abort</code>.</p>\n<p>If you import from Supermemory, run\n<a href=\"/docs/reference#import-again\"><code>wordcell import supermemory</code></a> on one machine and\nlet its notes sync like any other file. A later import on any machine reports a\nnote that was edited after the last import as a <code>conflict</code> and leaves it\nunchanged.</p>\n<h2 id=\"search-several-vaults-instead-of-syncing-them\">Search several vaults instead of syncing them</h2>\n<p>When each project keeps its own <code>kb/</code>, you do not need to combine them to search\nacross them. List the vaults in a portfolio registry and search the ones you\nselect:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> portfolio search <span class=\"syntax-token syntax-token--string\">&quot;retry policy&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--registry</span> ./kb-portfolio.json \\\n  <span class=\"syntax-token syntax-token--flag\">--workspace</span> ~/src \\\n  <span class=\"syntax-token syntax-token--flag\">--shared</span>\n</code></pre></div></figure>\n<p>Portfolio search reads the checkouts under the workspace as they are on disk,\nso pull each repository first. <code>--shared</code> selects vaults whose registry\nvisibility is <code>public</code> or <code>organization</code>. Select a private vault with\n<code>--vault owner/id</code>. See <a href=\"/docs/portfolio#define-a-v1-registry\">Define a v1 registry</a>\nand <a href=\"/docs/portfolio#search-selected-vaults\">Search selected vaults</a>.</p>\n",
diff --git a/site/app/readme.generated.ts b/site/app/readme.generated.ts
index 3b3f6a28..81bc35c3 100644
--- a/site/app/readme.generated.ts
+++ b/site/app/readme.generated.ts
@@ -1,5 +1,5 @@
 // Generated from ../README.md by scripts/sync-readme.ts. Do not edit.
-export const readmeVersion = "0.26.3";
+export const readmeVersion = "0.27.0";
 export const readmeTitle = "Wordcell";
 export const readmeLead = "Wordcell is a Markdown knowledge base and local MCP memory server for coding agents such as Claude Code, Codex, and Cursor. It keeps decisions, plans, and sources as Markdown files beside your code, and agents find them by exact words, by meaning with an optional local model, or from the file they are about to change.";
 export const readmeHtml = "<h1 id=\"wordcell\">Wordcell</h1>\n<blockquote>\n<p>🧠 Wordcell hands the next agent session what this one learned. Decisions,\nplans, and sources live as Markdown files beside your code. Tie a note to the\npaths it explains, and an agent about to change that code gets the note\nfirst. Search matches exact words or meaning, with an optional local model,\nand every index rebuilds from files you can read in any editor.</p>\n<p>Ask your agent to set it up: https://wordcell.io</p>\n</blockquote>\n<p><a href=\"https://github.com/hraness/wordcell/tree/main/skills/wordcell\">Install the Agent Skill</a></p>\n<p>Wordcell is a Markdown knowledge base and local MCP memory server for coding\nagents such as Claude Code, Codex, and Cursor. It keeps decisions, plans, and\nsources as Markdown files beside your code, and agents find them by exact\nwords, by meaning with an optional local model, or from the file they are\nabout to change.</p>\n<p>A new coding-agent session needs the reasons behind the code it is changing.\nWordcell keeps the decision, its supporting sources, and the plan that puts it\ninto practice in a connected set of Markdown files. Tie a note to a repository\npath, and the next agent can recover that context before it edits the file.\nWhen an assumption changes, update the decision and keep its earlier reasoning\nin Git.</p>\n<p>Captured sources preserve what you read, maintained notes explain what you\ncurrently understand, and plans record the work and its results. Named\nrelationships such as <code>evidenced-by</code> and <code>supersedes</code> make those connections\navailable to the embedded Oh graph engine, whose results point back to the\nsupporting files. Optional local semantic search helps when the words in a\nquestion differ from the note; Git history connects the explanation to its\ncommits and accompanying code changes.</p>\n<p>Use the CLI, local MCP server, or TypeScript SDK from your existing agent and\neditor. The public Agent Skill teaches agents to recover context, maintain\nplans, and leave reusable decisions for later sessions. Exact search, backlinks,\nand Git history need no account or model. Every index rebuilds from files you\ncan read in Obsidian or any text editor. Wordcell is free and open source.</p>\n<p>Web capture, optional hosted reranking, and your agent's provider reach other\nservices; <a href=\"#privacy-and-boundaries\">Privacy and boundaries</a> says what each one\nsends.</p>\n<p><a href=\"https://wordcell.io/docs\">Documentation</a> · <a href=\"https://wordcell.io/docs/comparisons\">Comparisons</a> · <a href=\"https://wordcell.io/docs/evidence\">Measured evidence</a> · <a href=\"https://github.com/hraness/wordcell/blob/main/CHANGELOG.md\">Changelog</a></p>\n<h2 id=\"why-wordcell\">Why Wordcell</h2>\n<ul>\n<li><strong>Keep what you learn in files you own.</strong> Write decisions, sources, and plans\nin Markdown. Obsidian, Git, and Wordcell read the same record, and every\nindex rebuilds from the files.</li>\n<li><strong>Find it by words or by meaning.</strong> Exact search needs no model or account.\nOptional local semantic search joins each match to current metadata, links,\nand history instead of returning isolated text.</li>\n<li><strong>Author the connections.</strong> Wikilinks and typed relationships turn notes into\na graph you can query. Backlinks and graph queries use only what you wrote,\nand <code>wordcell percolate</code> suggests missing links for you to review without\nwriting them into your notes.</li>\n<li><strong>Give coding agents the reasons behind the code.</strong> Tie notes to repository\npaths, list the commits behind a note, and let the next session start from\nthe notes for the file it is changing. Only context you save becomes part of\nthe record.</li>\n</ul>\n<p>Plain Markdown may be enough for a small set of notes. QMD is a good fit for\nlocal document retrieval and also supplies Wordcell's optional semantic search.\nWordcell adds a connected workflow for repository context, authored relationships,\nGit evidence, and selective publishing. <a href=\"https://wordcell.io/docs/comparisons\">Compare the tradeoffs</a>.</p>\n<p>Wordcell keeps the record in Markdown files you own, rebuilds every index from those files, and lets the next session start from the notes for the file it is changing: the design every Hraness project shares. <a href=\"https://hraness.com/writing/the-thread-through-hraness\">The thread through hraness</a> follows that design across the projects, and the <a href=\"https://algal.computer/docs/vision/\">ALGAL vision</a> states the bet behind it.</p>\n<h2 id=\"install\">Install</h2>\n<p><a href=\"https://bun.sh/docs/installation\">Bun 1.3.14 or newer</a> and Git are required.\nThe CLI and TypeScript SDK run with Bun. Install the versioned GitHub archive:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">bun</span> add <span class=\"syntax-token syntax-token--flag\">--global</span> <span class=\"syntax-token syntax-token--flag\">--ignore-scripts</span> https://github.com/hraness/wordcell/releases/download/v0.26.0/hraness-wordcell-0.26.0.tgz\n<span class=\"syntax-token syntax-token--command\">wordcell</span> <span class=\"syntax-token syntax-token--flag\">--help</span>\n</code></pre></div></figure>\n<p>Prefer npm? The same release is <a href=\"https://www.npmjs.com/package/@hraness/wordcell\">mirrored there</a>:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">npm</span> install <span class=\"syntax-token syntax-token--flag\">--global</span> <span class=\"syntax-token syntax-token--flag\">--ignore-scripts</span> @hraness/wordcell@0.26.0\n<span class=\"syntax-token syntax-token--command\">wordcell</span> <span class=\"syntax-token syntax-token--flag\">--help</span>\n</code></pre></div></figure>\n<p>Keep Bun in <code>PATH</code> for either installation. If your shell cannot find <code>wordcell</code>,\nadd your package manager's global executable directory to <code>PATH</code> and reopen the\nterminal. Optional semantic search, browser capture, and PDF tools have\n<a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#review-lifecycle-scripts-before-enabling-optional-adapters\">additional prerequisites</a>.</p>\n<p>Global Bun and npm installations on macOS and Linux check for updates daily\nbefore a command starts. Updates require the GitHub CLI (<code>gh</code>) to verify the\nrelease and preserve <code>--ignore-scripts</code>. An active command, MCP server, or\npreview server prevents replacement until it exits. Both installed commands\nshare the same settings:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> update status\n<span class=\"syntax-token syntax-token--command\">wordcell</span> update check\n<span class=\"syntax-token syntax-token--command\">wordcell</span> update\n<span class=\"syntax-token syntax-token--command\">wordcell</span> update disable\n<span class=\"syntax-token syntax-token--command\">wordcell</span> update enable\n</code></pre></div></figure>\n<p>Use <code>HRANESS_NO_UPDATE=1 wordcell …</code> for an invocation without automatic update\nrequests, including offline work. Help, version output, and SDK imports never\ncheck for updates. Source, project, copied, and Windows installations use manual\nupgrades. Exact Bun registry versions stay pinned until <code>update enable</code>; npm\ndoes not reliably retain the original global version constraint, so use\n<code>update disable</code> when you need a fixed global version. A versioned GitHub archive\ntracks verified releases by default. See the <a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#cli-updates\">update reference</a>.</p>\n<h2 id=\"keep-one-decision-available-to-the-next-session\">Keep one decision available to the next session</h2>\n<p>Run this from a directory where you want a new <code>kb/</code> folder. It creates one\nMarkdown note and finds it without a search model or hosted search service:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> init kb\n<span class=\"syntax-token syntax-token--command\">wordcell</span> note create notes/parser-contract \\\n  <span class=\"syntax-token syntax-token--flag\">--title</span> <span class=\"syntax-token syntax-token--string\">&quot;Parser contract&quot;</span> <span class=\"syntax-token syntax-token--flag\">--type</span> concept <span class=\"syntax-token syntax-token--flag\">--tag</span> architecture \\\n  <span class=\"syntax-token syntax-token--flag\">--body</span> <span class=\"syntax-token syntax-token--string\">&quot;Parser retries stop after three attempts.&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n<span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;parser retries&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p>The result includes <code>notes/parser-contract</code> and the saved retry constraint.\nOpen <code>kb/notes/parser-contract.md</code> to see the ordinary Markdown file. Wordcell\nadds a stable <code>document_id</code> in its frontmatter; you can edit the prose normally.</p>\n<p>Already have Markdown or an Obsidian vault? In <strong>v0.22.0 or newer</strong>, search\nthe existing folder without initialization or an <code>index.md</code> file:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> search <span class=\"syntax-token syntax-token--string\">&quot;a phrase from your notes&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> /path/to/your/vault <span class=\"syntax-token syntax-token--flag\">--mode</span> exact\n</code></pre></div></figure>\n<p>Replace the path and phrase with your own. You don't need to initialize,\nconvert, or move the existing files to search them.</p>\n<h3 id=\"use-with-a-coding-agent\">Use with a coding agent</h3>\n<p>After trying the CLI, install the public Agent Skill into a compatible agent,\nsuch as Claude Code, Codex, Cursor, or GitHub Copilot:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">bunx</span> skills add hraness/wordcell#v0.26.0 <span class=\"syntax-token syntax-token--flag\">--skill</span> wordcell\n</code></pre></div></figure>\n<p>Then ask:</p>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">Use Wordcell to search for &quot;parser retries&quot; in ./kb using exact mode.\nRead the matching note and explain the saved constraint.\n</code></pre>\n<p>The skill installs instructions, not a service. Installation does not create a\nvault, modify your notes, or grant an agent permission to access other accounts.\nThe agent still follows its own provider and data-handling settings.\n<a href=\"https://github.com/hraness/wordcell/blob/main/skills/wordcell/SKILL.md\">Inspect the skill</a>.</p>\n<h2 id=\"recover-the-stopped-session\">Recover the stopped session</h2>\n<p>Link a plan to the decision you saved:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> note create plans/parser-v2 \\\n  <span class=\"syntax-token syntax-token--flag\">--title</span> <span class=\"syntax-token syntax-token--string\">&quot;Parser v2&quot;</span> <span class=\"syntax-token syntax-token--flag\">--type</span> plan \\\n  <span class=\"syntax-token syntax-token--flag\">--body</span> <span class=\"syntax-token syntax-token--string\">&quot;The plan implements [[notes/parser-contract|the parser contract]].&quot;</span> \\\n  <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n<span class=\"syntax-token syntax-token--command\">wordcell</span> backlinks notes/parser-contract <span class=\"syntax-token syntax-token--flag\">--root</span> kb\n</code></pre></div></figure>\n<p>The backlink result includes <code>plans/parser-v2</code>, so a later session can find the\nwork that depends on the constraint.</p>\n<p>For code-path lookup, add this field inside the existing frontmatter of\n<code>kb/notes/parser-contract.md</code>:</p>\n<pre><code class=\"syntax-code language-yaml\" data-language=\"yaml\"><span class=\"syntax-token syntax-token--property\">repository_scopes</span><span class=\"syntax-token syntax-token--operator\">:</span>\n  <span class=\"syntax-token syntax-token--operator\">-</span> packages/parser\n</code></pre>\n<p>From your repository root, use an actual path under that scope and inspect the\nreturned notes and inherited <code>AGENTS.md</code> guides:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> context packages/parser/src/index.ts <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--repo</span> .\n</code></pre></div></figure>\n<p>Commit the vault with your repository to preserve its history, then use\n<code>wordcell history notes/parser-contract --root kb --repo .</code> to inspect the\ncommits behind the note. History is optional and requires recorded Git commits.</p>\n<p>These views recover saved decisions, related work, rules, and provenance.\nThey do not reconstruct private chat or prove that the note is still correct.\nOpen the returned Markdown and guides before acting on them.</p>\n<h2 id=\"rerank-a-search-window\">Rerank a search window</h2>\n<p>Cloudflare Clef support is in the current source tree. The versioned release\nlisted above does not include it. From a source checkout, run:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">bun</span> ./src/cli.ts search <span class=\"syntax-token syntax-token--string\">&quot;why releases use immutable archives&quot;</span> <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--mode</span> exact \\\n  <span class=\"syntax-token syntax-token--flag\">--rerank</span> clef <span class=\"syntax-token syntax-token--flag\">--rerank-limit</span> 25 <span class=\"syntax-token syntax-token--flag\">--limit</span> 5 <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>This optional hosted reranker uses Cloudflare Clef (<code>clef</code> by default, or\n<code>--rerank-model clef-flash</code>). It sends the query and candidate note identifiers,\ntitles, paths, and snippets to Cloudflare, needs <code>CLOUDFLARE_ACCOUNT_ID</code> and\n<code>CLOUDFLARE_API_TOKEN</code>, and incurs provider charges. Enable it only for vaults you\napprove for external processing; credentials alone never enable it. Exact\nidentities remain first; a provider failure retains the baseline order with a diagnostic. See the\n<a href=\"https://github.com/hraness/wordcell/blob/main/docs/reranking.md\">setup, SDK examples, measured results, and limits</a>.</p>\n<h2 id=\"what-you-can-do\">What you can do</h2>\n<table>\n<thead>\n<tr><th>Task</th><th>Command</th><th>Evidence and effects</th></tr>\n</thead>\n<tbody>\n<tr><td>Find a saved decision</td><td><code>wordcell search &quot;parser retries&quot; --root kb --mode exact</code></td><td>Reads current Markdown; no model or hosted search request.</td></tr>\n<tr><td>Recover context for code</td><td><code>wordcell context packages/parser/src/index.ts --root kb --repo .</code></td><td>Returns scoped notes, plans, and inherited <code>AGENTS.md</code> rules.</td></tr>\n<tr><td>Inspect explicit connections</td><td><code>wordcell backlinks notes/parser-contract --root kb</code></td><td>Returns notes that link to the decision.</td></tr>\n<tr><td>Search by meaning</td><td><code>wordcell search &quot;retry policy&quot; --root kb --mode hybrid</code></td><td>Adds optional local QMD keyword and vector retrieval; model setup is required.</td></tr>\n<tr><td>Query with graph proofs</td><td><code>wordcell graph query --program scope-route --scope packages/parser --root kb</code></td><td>Returns bounded results tied to the source revision. Queries do not write a cache.</td></tr>\n<tr><td>Capture a source</td><td><code>wordcell clip https://example.com/article --output kb/articles</code></td><td>Reads the selected URL and writes a Markdown bundle with a capture receipt.</td></tr>\n<tr><td>Capture a PDF</td><td><code>wordcell pdf /absolute/path/to/document.pdf --output kb/articles</code></td><td>Preserves the original PDF and extracted evidence; Poppler is required.</td></tr>\n<tr><td>Check the vault</td><td><code>wordcell check --root kb</code></td><td>Reports structural and attachment problems without editing files.</td></tr>\n<tr><td>Publish selected notes</td><td><code>wordcell publish --root kb --out site/ --include notes/parser-contract --dry-run --json</code></td><td>Previews a static site selection locally; remove <code>--dry-run</code> to build it.</td></tr>\n<tr><td>Preview a site</td><td><code>wordcell serve --root site --port 8080</code></td><td>Serves a published site on a loopback static file server with the emitted <code>404.html</code> fallback.</td></tr>\n<tr><td>Connect an MCP client</td><td><code>wordcell mcp --root kb</code></td><td>Serves this vault to a local MCP client over standard input and output; <code>--read-only</code> removes the write tools.</td></tr>\n<tr><td>Import from Supermemory</td><td><code>wordcell import supermemory documents.json --root kb</code></td><td>Turns saved Supermemory API responses into Markdown notes and reports local edits as conflicts on later imports.</td></tr>\n</tbody>\n</table>\n<p>Use <code>--json</code> for structured output and <code>wordcell --help</code> for the complete command\nsurface. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#command-surface\">Full command reference</a>.</p>\n<h2 id=\"publish-a-selected-part-of-your-vault\">Publish a selected part of your vault</h2>\n<p>Preview the decision and plan from the example before writing an output folder:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site \\\n  <span class=\"syntax-token syntax-token--flag\">--include</span> notes/parser-contract <span class=\"syntax-token syntax-token--flag\">--include</span> plans/parser-v2 <span class=\"syntax-token syntax-token--flag\">--dry-run</span> <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>Review the selection, then build and preview it:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site \\\n  <span class=\"syntax-token syntax-token--flag\">--include</span> notes/parser-contract <span class=\"syntax-token syntax-token--flag\">--include</span> plans/parser-v2\n<span class=\"syntax-token syntax-token--command\">wordcell</span> serve <span class=\"syntax-token syntax-token--flag\">--root</span> site <span class=\"syntax-token syntax-token--flag\">--port</span> 8080\n</code></pre></div></figure>\n<p>Open <code>http://127.0.0.1:8080</code>. You get readable pages, linked notes, and search\nthat runs in the browser. Upload the <code>site/</code> folder to your chosen static host\nwhen you want to share it; <code>publish</code> itself never uploads anything.</p>\n<p>For a repeatable slice, use path patterns or combine folders, tags, metadata,\ncode scopes, and linked neighborhoods:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> publish <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--out</span> site-notes \\\n  <span class=\"syntax-token syntax-token--flag\">--include-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;notes/**/*.md&#39;</span> <span class=\"syntax-token syntax-token--flag\">--exclude-glob</span> <span class=\"syntax-token syntax-token--string\">&#39;**/draft-*&#39;</span> <span class=\"syntax-token syntax-token--flag\">--dry-run</span> <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>Preview reports show up to 20 selected IDs by default, with a total count and\nselection digest. They keep note bodies out of the agent's context. Use\n<code>--list-limit</code> to adjust that preview without changing what gets published. <code>publish: false</code> excludes a note, but selected\nprose and attachments still need review before sharing: selection is not secret\nredaction. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/publish.md\">Selection recipes and hosting guide</a>.</p>\n<h2 id=\"use-a-vault-as-agent-memory\">Use a vault as agent memory</h2>\n<p><code>wordcell mcp --root kb</code> serves a vault to a local MCP client, such as Claude\nCode, Claude Desktop, Cursor, or Codex, over standard input and output. The\nclient can search, list, and read notes, follow links, create notes, update a\nnote body at a known revision, and add typed relations. <code>--read-only</code> removes\nthe write tools. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-handoffs.md\">Connect Wordcell to your coding agent</a>\nshows the setup for each host.</p>\n<p>With the Agent Skill, ask your agent to save the session. It writes a dated\nsession note, links it to the notes it changed, and keeps a profile note for\nyou or your project. Wordcell extracts no facts and writes no note on its own.\n<a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-memory.md#session-memory-and-profiles\">Session memory and profiles</a>.</p>\n<p>To move from Supermemory, <code>wordcell import supermemory</code> turns saved Supermemory\nAPI responses into Markdown notes. The <a href=\"https://github.com/hraness/wordcell/blob/main/docs/migration-from-supermemory.md\">migration guide</a>\ncovers export, import, and what does not transfer, and the\n<a href=\"https://wordcell.io/compare/supermemory\">Supermemory comparison</a> lists when to\nchoose Supermemory instead. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/sync.md\">Sync with Git</a>\nkeeps one vault current on several machines.</p>\n<h2 id=\"evidence-and-comparisons\">Evidence and comparisons</h2>\n<p>In the September 19, 2026 SciFact study of scientific abstracts, hosted Jev\nreranking placed a relevant result first for <strong>161 of 300 queries</strong>, versus\n<strong>101</strong> with Wordcell exact search alone. These historical measurements do not\nevaluate Cloudflare Clef or Clef Flash. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/reranking.md#evidence-and-limits\">Results and method</a>.</p>\n<p><a href=\"https://wordcell.io/docs/comparisons\">The comparison guide</a>\ncovers Markdown alone, QMD, Basic Memory, Obsidian, static publishing tools,\nSupermemory, Mem0, and Zep using their own documentation. Choose the smallest\nworkflow that meets your needs.</p>\n<p>The <a href=\"https://wordcell.io/benchmarks\">benchmarks page</a> shows the SciFact results\nand the published results of Oh, the embedded memory framework, each with its\nsource data and method. On all 500 LongMemEval-S\nquestions, Oh semantic retrieval scored 88.87% and BM25 86.13% with the same\nreader and budget; on the measure Oh named before the run, its interval does\nnot rule out a tie. Oh's scores measure its own memory-retrieval path, not a\nWordcell vault.</p>\n<h2 id=\"how-the-files-fit-together\">How the files fit together</h2>\n<pre><code class=\"syntax-code language-text\" data-language=\"text\">repository/\n├── AGENTS.md                # rules that govern edits\n├── packages/parser/\n│   └── AGENTS.md            # rules scoped to this code\n└── kb/\n    ├── index.md             # authored or managed front door\n    ├── articles/            # captured sources and assets\n    ├── notes/               # maintained explanations\n    └── plans/               # decisions and outcomes\n</code></pre>\n<p>Markdown, YAML frontmatter, explicit wikilinks, and Git hold the record. Open\nthe same files in Obsidian, a text editor, or ordinary file-search tools.\nApplication code does not need to import Wordcell or its vault.</p>\n<p>Wordcell is the Markdown knowledge base. <a href=\"https://oh.computer\">Oh</a> is the\nembedded memory framework that backs its named graph queries and source proofs.\nMarkdown and Git remain authoritative. Query the graph immediately without an\nOh account, service, or persisted database:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">wordcell</span> graph query <span class=\"syntax-token syntax-token--flag\">--program</span> backlinks <span class=\"syntax-token syntax-token--flag\">--note</span> notes/parser-contract <span class=\"syntax-token syntax-token--flag\">--root</span> kb <span class=\"syntax-token syntax-token--flag\">--json</span>\n</code></pre></div></figure>\n<p>The result traces each returned link to its source note and revision. Only an explicit\n<code>wordcell graph rebuild --root kb</code> writes <code>.wordcell/oh.sqlite</code>, the file stays\nignored and rebuildable, and nothing flows from the projection back into notes.\nBacklinks and typed relationships come from authored links. Percolation\nsuggests connections for review and does not add inferred edges to notes.</p>\n<p>Wordcell search combines its own exact matching with optional QMD local search\nand optional hosted Cloudflare Clef reranking. Oh also offers memory retrieval for applications;\nits conversation-memory benchmark scores measure that separate path. They do not\nestablish Wordcell's retrieval or answer quality. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md#how-wordcell-and-oh-fit-together\">How the integration works</a>.</p>\n<p>Graph proofs explain a supported derivation from a specific source revision.\nThey do not prove that a note is true or that a missing relationship cannot\nexist. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md\">Graph queries and proof limits</a>.</p>\n<h2 id=\"build-with-the-typescript-sdk\">Build with the TypeScript SDK</h2>\n<p>Add the same immutable release to a Bun project:</p>\n<figure class=\"hraness-marketing-proof-frame xtylnni xs5hli xrtw95r x19vpta5 xesnm00 x10im51j xvueqy4 x7giv3 x17p5ghk x18z9243 x16x8cr2 xv2i73l x1w0e1mo xtthz4l x72sy0d xug5yj x18sabzy x1cfjbvc x1jleocg x1a4igh8 x1pjjote xsdpl10 x1e53mt7 x1sz4vi2 xgkqhyc x4aylkk x1eubfot x1itpb23 x9yvj25 x18o3ruo xhobzj1 x1y4qj14 x2c5uud x103pssi x1ug5rqp x182nak8 x1pjo12s x12koezg xzln6ae x1u7o2vf x1tzqu68 x1fdtg7e xcrev8p xtnh2io xwaqzdf\" data-chrome=\"terminal\" data-hraness-marketing=\"proof-frame\"><div aria-hidden=\"true\" class=\"hraness-marketing-proof-frame__chrome x78zum5 x6s0dn4 x8233eu xrqs5gp x1drtmal xhobzj1 xs301gt xwaqzdf xothggy x1j9yjdw xs87ocq xp1qmoa\"><span class=\"hraness-marketing-proof-frame__lights x3nfvp2 x73f2yu\"><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span><span class=\"hraness-marketing-proof-frame__light x19a4nw2 x10oi0ya x1e6avla xw7x07y x18o3ruo x1y4qj14 x103pssi x182nak8 x12koezg x1u7o2vf x1fdtg7e\"></span></span></div><div class=\"hraness-marketing-proof-frame__content xesnm00 xysyzu8\"><pre tabindex=\"0\"><code class=\"syntax-code language-shell\" data-language=\"shell\"><span class=\"syntax-token syntax-token--command\">bun</span> add <span class=\"syntax-token syntax-token--flag\">--exact</span> <span class=\"syntax-token syntax-token--flag\">--ignore-scripts</span> https://github.com/hraness/wordcell/releases/download/v0.26.0/hraness-wordcell-0.26.0.tgz\n</code></pre></div></figure>\n<p>The SDK provides read-only vault sessions, metadata queries, search, graph\nproofs, Git context, and composable workflows. A session owns one snapshot;\nreopen it after Markdown changes. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#graph-reference\">SDK and workflow examples</a>\nshow the public imports and lifecycle.</p>\n<h2 id=\"privacy-and-boundaries\">Privacy and boundaries</h2>\n<ul>\n<li>Structural queries and exact search read local files. Optional semantic\nsearch downloads its model on first use and runs locally. Optional Cloudflare\nClef reranking sends the query and candidate context to Cloudflare;\nit is off by default.</li>\n<li>URL capture contacts the requested source. Signed-in capture uses only\nexplicitly selected browser state. Review the <a href=\"https://github.com/hraness/wordcell/blob/main/SECURITY.md\">security policy</a>\nbefore using it with private sources.</li>\n<li>An agent that reads the vault follows its own provider and data-handling\nsettings. Keep private records out of public repositories and outputs.</li>\n<li>Git history is opt-in. Saved notes preserve recorded context; Wordcell does\nnot reconstruct unsaved conversations or silently record every agent action.</li>\n</ul>\n<h2 id=\"documentation\">Documentation</h2>\n<p>Start with the task you want to complete. Browse all guides on the\n<a href=\"https://wordcell.io/docs\">documentation index</a>.</p>\n<table>\n<thead>\n<tr><th>Read next</th><th>Purpose</th></tr>\n</thead>\n<tbody>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/getting-started.md\">Get started</a></td><td>Learn the full loop on a first vault: save, find, connect, and publish one note.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-workflow.md\">Agent workflow</a></td><td>Set up, query, maintain, and revise repository memory.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/getting-started.md#search-an-existing-markdown-or-obsidian-vault\">Search an existing Obsidian or Markdown vault</a></td><td>Find a saved note without initialization or a model download.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/obsidian.md\">Use an existing Obsidian vault</a></td><td>See which Obsidian links, tags, and attachments Wordcell reads, and serve the vault to an agent read-only.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-handoffs.md\">Connect a coding agent over MCP</a></td><td>Configure Claude Code, Codex, Cursor, or Claude Desktop, then verify a note read.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-handoffs.md#troubleshoot-the-connection\">Troubleshoot MCP</a></td><td>Diagnose executable paths, partial search results, missing tools, and oversized responses.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md\">Installation and command reference</a></td><td>Exact interfaces, SDK imports, optional adapters, and troubleshooting prerequisites.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/capture.md\">Web capture</a> and <a href=\"https://github.com/hraness/wordcell/blob/main/docs/pdf.md\">PDF capture</a></td><td>Save sources with provenance, assets, and explicit completeness limits.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/publish.md\">Publish selected notes</a></td><td>Preview a slice, build a static site, and choose how to host it.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md\">Graph guide</a></td><td>Named queries, proofs, revisions, resource limits, and cache recovery.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/portfolio.md\">Search several vaults together</a></td><td>Search only selected, authorized vaults.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/sync.md\">Sync with Git</a></td><td>Keep one vault current on several machines with a private repository.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/migration-from-supermemory.md\">Migrate from Supermemory</a></td><td>Export documents and memory entries, import them as notes, and replace connectors.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/design.md\">Design</a> and <a href=\"https://github.com/hraness/wordcell/blob/main/docs/agent-memory.md\">memory rationale</a></td><td>File contracts, design choices, and evaluation context.</td></tr>\n<tr><td><a href=\"https://github.com/hraness/wordcell/blob/main/docs/publishing.md#verify-a-published-release\">Release verification</a></td><td>Verify archive identity, signatures, and provenance.</td></tr>\n</tbody>\n</table>\n<h3 id=\"installation-reference\">Installation reference</h3>\n<p><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#installation-reference\">Alternative installs and optional capabilities</a>.</p>\n<h3 id=\"the-kb-vault-format\">The kb vault format</h3>\n<p>Existing <code>kb/</code>, <code>index.md</code>, <code>kb://</code> identifiers, and Markdown formats remain\ncompatible. <a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#the-kb-vault-format\">Vault format reference</a>.</p>\n<h3 id=\"command-surface\">Command surface</h3>\n<p><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#command-surface\">Complete CLI reference</a>.</p>\n<h3 id=\"capture-reference\">Capture reference</h3>\n<p><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#capture-reference\">Capture commands and dependencies</a>.</p>\n<h3 id=\"graph-reference\">Graph reference</h3>\n<p><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#graph-reference\">Graph and SDK interfaces</a>.</p>\n<h3 id=\"agent-skills\">Agent skills</h3>\n<p><a href=\"https://github.com/hraness/wordcell/blob/main/docs/reference.md#agent-skills\">Installation and runtime contract</a>.\nThe same skill is included at <code>node_modules/@hraness/wordcell/skills/wordcell/</code>.</p>\n<h2 id=\"release-notes\">Release notes</h2>\n<p>Version 0.22 adds selective static publishing and local preview. Choose notes,\nfolders, path patterns, metadata, or linked neighborhoods, then inspect a\nbounded selection report before building. Existing vaults need no migration.\nThe deprecated <code>kb</code> command was removed in 0.21.0; use <code>wordcell</code>.\n<a href=\"https://github.com/hraness/wordcell/blob/main/CHANGELOG.md\">All release notes and upgrade instructions</a>.</p>\n<h2 id=\"contributing\">Contributing</h2>\n<p>Run <code>bun run check</code> for source, architecture, package installation, types, and\nnative-helper validation. The site has its own <code>bun run check</code> under <code>site/</code>.\nSee <a href=\"https://github.com/hraness/wordcell/blob/main/CONTRIBUTING.md\">Contributing</a>, <a href=\"https://github.com/hraness/wordcell/blob/main/SECURITY.md\">Security</a>, and the <a href=\"https://github.com/hraness/wordcell/blob/main/LICENSE\">MIT License</a>.</p>\n<p><a href=\"https://github.com/hraness/wordcell/releases\">Install Wordcell from GitHub Releases</a> ·\n<a href=\"https://github.com/hraness/wordcell\">Wordcell source on GitHub</a> ·\n<a href=\"https://wordcell.io\">Wordcell overview</a></p>\n<h2 id=\"optional-development-support\">Optional development support</h2>\n<p><code>wordcell support</code> shows optional development support for Wordcell. Features stay\nfree and no account is required. Accounts presents current terms; the person\nconfirms any payment in their browser. Wordcell has no product newsletter and\ndoes not look up an email address for support.</p>\n<p>After useful standalone work, agents can receive a discovery record on stderr.\nRead <code>wordcell support protocol --json</code> for the shared closeout procedure.\nHelp, diagnostics, evaluation, SDK calls and nested commands stay quiet.\n<code>HRANESS_SUPPORT=off</code> or <code>HRANESS_SUPPORT_AUDIENCE=off</code> suppresses incidental\ninvitations. Explicit human terminal rendering requires\n<code>HRANESS_SUPPORT_AUDIENCE=human</code>; the default audience is an agent, including in\na pseudo-terminal.</p>\n<p><code>wordcell support dismiss</code> disables invitations across participating tools on\nthis machine. <code>snooze</code> pauses them for thirty days, <code>enable</code> restores them, and\n<code>status --json</code> shows their separate local preferences. These commands do not\nchange a vault, sign up or pay. Acknowledged invitations share a seven-day\ncooldown; discovery itself does not consume it.</p>\n";
diff --git a/skills/wordcell/SKILL.md b/skills/wordcell/SKILL.md
index a9691834..0ef98a6b 100644
--- a/skills/wordcell/SKILL.md
+++ b/skills/wordcell/SKILL.md
@@ -58,7 +58,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.26.3/hraness-wordcell-0.26.3.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz
 }
 wordcell --help
 ```
diff --git a/src/capture.ts b/src/capture.ts
index 34184ae4..8d89b5ad 100644
--- a/src/capture.ts
+++ b/src/capture.ts
@@ -66,3 +66,8 @@ export type {
   MediaMode,
   ParseArgumentsResult,
 };
+
+import { extractArticleMetadata as extractArticleMetadataImplementation, parseArticleMetadata as parseArticleMetadataImplementation } from "./clip/metadata.js";
+export const extractArticleMetadata: typeof extractArticleMetadataImplementation = (...arguments_) => extractArticleMetadataImplementation(...arguments_);
+export const parseArticleMetadata: typeof parseArticleMetadataImplementation = (...arguments_) => parseArticleMetadataImplementation(...arguments_);
+export type { ArticleMetadata, ArticleMetadataClaim, MetadataSource, MetadataValue } from "./clip/metadata.js";
diff --git a/src/clip/bundle-reader.ts b/src/clip/bundle-reader.ts
index d39d3ada..a0f99129 100644
--- a/src/clip/bundle-reader.ts
+++ b/src/clip/bundle-reader.ts
@@ -1,3 +1,4 @@
+import { parseArticleMetadata, type ArticleMetadata } from "./metadata.js";
 import { createHash } from "node:crypto";
 import { constants as fsConstants, type BigIntStats } from "node:fs";
 import { lstat, open, opendir, realpath, type FileHandle } from "node:fs/promises";
@@ -27,6 +28,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
 export type CaptureBundleIntegrity = "mismatch" | "unavailable" | "verified";
 
 export type CaptureBundleInspection = {
+  readonly metadata?: ArticleMetadata;
   readonly root: string;
   readonly schemaVersion: 1 | 2 | 3 | 4;
   readonly sourceUrl: string;
@@ -556,6 +558,7 @@ export async function readCaptureBundle(
 
     await assertBundleRoot(root);
     return Object.freeze({
+      ...(manifest.metadata === undefined ? {} : { metadata: parseArticleMetadata(manifest.metadata) }),
       root: root.path,
       schemaVersion,
       sourceUrl: manifest.sourceUrl,
diff --git a/src/clip/capture.ts b/src/clip/capture.ts
index e618330e..0814949a 100644
--- a/src/clip/capture.ts
+++ b/src/clip/capture.ts
@@ -965,6 +965,7 @@ export async function runCapture(
       const finalWarnings = finalizedWarnings(combinedWarnings, redactedMarkdown.count);
       const includeSource = options.evidence === "source" || options.evidence === "all";
       const manifestInput: CaptureManifestInput = {
+        ...(article.metadata === undefined ? {} : { metadata: article.metadata }),
         sourceUrl,
         canonicalUrl: best.canonicalUrl.href,
         capturedAt,
diff --git a/src/clip/defuddle-worker.ts b/src/clip/defuddle-worker.ts
index 38a64d7e..7a9849ba 100644
--- a/src/clip/defuddle-worker.ts
+++ b/src/clip/defuddle-worker.ts
@@ -1,3 +1,4 @@
+import { extractArticleMetadata } from "./metadata.js";
 import { Defuddle } from "defuddle/node";
 import { embeddedArticleHtml } from "./embedded-article.js";
 
@@ -125,7 +126,7 @@ workerGlobal.onmessage = async (event: MessageEvent<unknown>): Promise<void> =>
       removeImages: false,
     });
     const enriched = typeof value === "object" && value !== null && !Array.isArray(value)
-      ? { ...value, captureVideoPosters: videoPosters }
+      ? { ...value, captureVideoPosters: videoPosters, metadata: await extractArticleMetadata(request.html, request.url, value) }
       : value;
     workerGlobal.postMessage({ ok: true, value: enriched });
   } catch {
diff --git a/src/clip/extract.ts b/src/clip/extract.ts
index 19166ca1..3f91ba5e 100644
--- a/src/clip/extract.ts
+++ b/src/clip/extract.ts
@@ -1,3 +1,4 @@
+import { parseArticleMetadata } from "./metadata.js";
 import type { CaptureScope } from "./args.js";
 import type { AcquiredPage } from "./acquire.js";
 import {
@@ -719,6 +720,7 @@ export async function extractPage(
           content: retainDefuddleMedia(restoredContent, response, acquisition.finalUrl),
           title: boundedMetadata(response.title, articleMetadataLimits.title)
             ?? boundedMetadata(acquisition.browserTitle, articleMetadataLimits.title),
+          ...(response.metadata === undefined ? {} : { metadata: parseArticleMetadata(response.metadata) }),
           author: boundedMetadata(response.author, articleMetadataLimits.author),
           published: boundedMetadata(response.published, articleMetadataLimits.published),
           description,
diff --git a/src/clip/lib.ts b/src/clip/lib.ts
index 72d6da84..349f8d6c 100644
--- a/src/clip/lib.ts
+++ b/src/clip/lib.ts
@@ -1,7 +1,9 @@
+import { parseArticleMetadata, type ArticleMetadata } from "./metadata.js";
 import { sanitizeTerminalText } from "./terminal.js";
 
 /** Defuddle fields consumed after narrowing its JSON output. */
 export type Article = {
+  metadata?: ArticleMetadata;
   content: string;
   title: string | null;
   author: string | null;
@@ -46,6 +48,7 @@ export function parseArticle(parsed: unknown): Article | null {
   if (content === null) return null;
   return {
     content,
+    ...(parsed.metadata === undefined ? {} : { metadata: parseArticleMetadata(parsed.metadata) }),
     title: nonEmptyString(parsed.title, articleMetadataLimits.title),
     author: nonEmptyString(parsed.author, articleMetadataLimits.author),
     published: nonEmptyString(parsed.published, articleMetadataLimits.published),
diff --git a/src/clip/metadata-search.test.ts b/src/clip/metadata-search.test.ts
index adee0513..cd722ee6 100644
--- a/src/clip/metadata-search.test.ts
+++ b/src/clip/metadata-search.test.ts
@@ -322,7 +322,7 @@ process.stdout.write`,
       const provider = createRustMetadataSearchProvider({ binaryPath: fixture.path, resolveNetworkTarget: async () => shuffled });
       expect((await provider({ query: "large DNS", timeoutMs: 10_000 })).status).toBe("success");
     }), { numRuns: 8 });
-  });
+  }, 30_000);
 
   test("rejects unsafe DNS answers beyond the candidate limit before spawning", async () => {
     const fixture = executable(SUCCESS_SCRIPT);
diff --git a/src/clip/metadata.test.ts b/src/clip/metadata.test.ts
new file mode 100644
index 00000000..e093fc24
--- /dev/null
+++ b/src/clip/metadata.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import { extractArticleMetadata, parseArticleMetadata, metadataLimits } from "./metadata.js";
+
+describe("observed article metadata", () => {
+  test("retains conflicts, authors and evidence with deterministic choice", async () => {
+    const metadata = await extractArticleMetadata(`<html lang="en"><head><title>HTML &amp; title</title>
+      <link rel="canonical" href="/article?token=private#secret"><link rel="alternate" href="/fr">
+      <meta property="og:title" content="OG title"><meta name="twitter:title" content="Twitter title">
+      <meta name="author" content="Élodie &amp; Jo"><meta name="description" content="Description &eacute;">
+      <meta name="keywords" content="science, history"><meta name="citation_doi" content="10.1000/example">
+      <script type="application/ld+json">{"@context":"https://unreachable.invalid/schema","@type":"Article","headline":"LD title","author":[{"name":"Ada"},{"name":"Bo"}],"datePublished":"2026-10-16T12:30:00+08:00","publisher":{"name":"Press"}}</script></head></html>`, "https://example.test/post");
+    const selected = metadata.claims.filter((claim) => claim.selected);
+    expect(selected.find((claim) => claim.field === "title")?.value).toBe("LD title");
+    expect(metadata.claims.filter((claim) => claim.field === "title")).toHaveLength(4);
+    expect(selected.find((claim) => claim.field === "authors")?.value).toEqual(["Ada", "Bo"]);
+    expect(selected.find((claim) => claim.field === "published")).toMatchObject({ value: "2026-10-16T04:30:00.000Z", timezone: "explicit", datePrecision: "datetime", source: "json-ld" });
+    expect(selected.find((claim) => claim.field === "description")?.value).toBe("Description é");
+    expect(selected.find((claim) => claim.field === "canonical")?.value).toBe("https://example.test/article");
+    expect(metadata.claims.every((claim) => claim.locator && claim.rule)).toBe(true);
+  });
+  test("retains timezone uncertainty and never invents publication time", async () => {
+    for (const [date, precision, timezone] of [["2026-10-16", "date", "not-applicable"], ["2026-10-16T12:30:00", "datetime", "unknown"], ["2026-02-31", "invalid", "unknown"]]) {
+      const metadata = await extractArticleMetadata(`<meta property="article:published_time" content="${date}">`, "https://example.test/");
+      expect(metadata.claims[0]).toMatchObject({ value: date, datePrecision: precision, timezone, selected: precision !== "invalid" });
+    }
+    expect((await extractArticleMetadata("<title>No date</title>", "https://example.test/")).claims.some((claim) => claim.field === "published")).toBe(false);
+  });
+  test("bounded JSON-LD ignores remote contexts, hostile depth and malformed scripts", async () => {
+    const deep = '{"x":'.repeat(20) + '0' + '}'.repeat(20);
+    const metadata = await extractArticleMetadata(`<script type="application/ld+json">${deep}</script><script type="application/ld+json">no json</script><meta name="csrf-token" content="secret"><meta property="og:image" content="https://user:pass@example.test/image?X-Amz-Signature=secret">`, "https://example.test/");
+    expect(metadata.warnings).toContain("json-limit"); expect(metadata.warnings).toContain("json-invalid");
+    expect(JSON.stringify(metadata)).not.toContain("secret"); expect(JSON.stringify(metadata)).not.toContain("pass@");
+    expect(metadata.claims).toHaveLength(1);
+  });
+  test("enforces claim/value limits and rejects unknown envelopes", async () => {
+    const metadata = await extractArticleMetadata('<meta name="description" content="x">'.repeat(metadataLimits.claims + 20), "https://example.test/");
+    expect(metadata.claims.length).toBeLessThanOrEqual(metadataLimits.claims); expect(metadata.warnings).toContain("claim-limit");
+    expect(() => parseArticleMetadata({ ...metadata, schemaVersion: 2 })).toThrow();
+    expect(() => parseArticleMetadata({ ...metadata, claims: [{ ...metadata.claims[0], value: "x".repeat(9000) }] })).toThrow();
+    expect(() => parseArticleMetadata({ ...metadata, claims: [{ ...metadata.claims[0], selected: "yes" }] })).toThrow();
+  });
+});
+
+
+test("unknown meta keys do not inherit object prototype fields", async () => {
+  const metadata = await extractArticleMetadata('<meta name="constructor" content="A builder"><title>Still captured</title>', "https://example.test/");
+  expect(metadata.claims.find(claim => claim.field === "meta:constructor")?.value).toBe("A builder");
+  expect(metadata.claims.find(claim => claim.field === "title")?.value).toBe("Still captured");
+});
+test("an unterminated JSON-LD script is explicitly incomplete", async () => {
+  const metadata = await extractArticleMetadata('<title>Useful title</title><script type="application/ld+json">{"@type":"Article","headline":"Unclosed"}', "https://example.test/");
+  expect(metadata.warnings).toContain("json-invalid");
+  expect(metadata.claims.some(claim => claim.source === "json-ld")).toBe(false);
+});
+test("stored URL evidence rejects relative signed locators and non-HTTP schemes", async () => {
+  const metadata = await extractArticleMetadata('<meta property="og:image" content="/image?token=private#secret">', "https://example.test/");
+  for (const field of ["observed", "value"]) for (const unsafe of ["/image?token=private", "javascript:alert(1)", "data:text/plain,secret"]) {
+    expect(() => parseArticleMetadata({ ...metadata, claims: metadata.claims.map(claim => ({ ...claim, [field]: unsafe })) })).toThrow("metadata URL");
+  }
+  expect(JSON.stringify(metadata)).not.toContain("private"); expect(JSON.stringify(metadata)).not.toContain("secret");
+  expect(metadata.claims[0]?.value).toBe("https://example.test/image");
+});
+
+
+test("specific article JSON-LD outranks generic WebPage independent of graph order", async () => {
+  for (const type of ["Article", "NewsArticle", "BlogPosting", "https://schema.org/ScholarlyArticle"]) for (const reverse of [false, true]) {
+    const nodes = [{ "@type": "WebPage", name: "Generic page", description: "Page details" }, { "@type": type, headline: "Actual article", description: "Article details" }];
+    if (reverse) nodes.reverse();
+    const metadata = await extractArticleMetadata(`<script type="application/ld+json">${JSON.stringify({ "@graph": nodes })}</script>`, "https://example.test/");
+    expect(metadata.claims.find(claim => claim.field === "title" && claim.selected)?.value).toBe("Actual article");
+    expect(metadata.claims.find(claim => claim.field === "description" && claim.selected)?.value).toBe("Article details");
+    expect(metadata.claims.find(claim => claim.observed === "Generic page")?.rule).toContain("jsonld-type=WebPage");
+    expect(metadata.claims.filter(claim => claim.field === "title")).toHaveLength(2);
+  }
+});
diff --git a/src/clip/metadata.ts b/src/clip/metadata.ts
new file mode 100644
index 00000000..87072fd9
--- /dev/null
+++ b/src/clip/metadata.ts
@@ -0,0 +1,232 @@
+import { decodeHTML } from "entities";
+
+export const metadataLimits = { htmlBytes: 8 * 1024 * 1024, claims: 256, value: 8192, totalBytes: 256 * 1024, jsonBytes: 128 * 1024, jsonNodes: 2048, jsonDepth: 12 } as const;
+export type MetadataSource = "html-title" | "html-meta" | "html-link" | "html-language" | "json-ld" | "extractor";
+export type MetadataValue = string | readonly string[];
+export type ArticleMetadataClaim = {
+  readonly field: string;
+  readonly observed: MetadataValue;
+  readonly value: MetadataValue;
+  readonly source: MetadataSource;
+  readonly locator: string;
+  readonly rule: string;
+  readonly selected: boolean;
+  readonly datePrecision?: "date" | "datetime" | "invalid";
+  readonly timezone?: "explicit" | "unknown" | "not-applicable";
+};
+export type ArticleMetadata = {
+  readonly schemaVersion: 1;
+  readonly extractorVersion: "wordcell-metadata-v1";
+  readonly claims: readonly ArticleMetadataClaim[];
+  readonly warnings: readonly ("input-limit" | "claim-limit" | "value-limit" | "json-limit" | "json-invalid")[];
+};
+const record = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const sources = new Set<MetadataSource>(["html-title", "html-meta", "html-link", "html-language", "json-ld", "extractor"]);
+const warningKinds = new Set(["input-limit", "claim-limit", "value-limit", "json-limit", "json-invalid"]);
+const credentialName = /(?:csrf|xsrf|token|nonce|password|secret|session|authorization|api[-_]?key|signature)/i;
+const urlFields = new Set(["canonical", "alternate", "image", "url"]);
+const dateFields = new Set(["published", "modified"]);
+
+/** Metadata is descriptive evidence, never an authenticated resource locator. */
+function publicUrl(value: string, base?: string): string | null {
+  try {
+    const url = new URL(value, base);
+    if (!/^https?:$/.test(url.protocol)) return null;
+    url.username = ""; url.password = ""; url.search = ""; url.hash = "";
+    return url.href;
+  } catch { return null; }
+}
+function cleanText(value: string): string {
+  return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "")
+    .replace(/https?:\/\/[^\s<>"']+/giu, (url) => publicUrl(url) ?? "[invalid URL]")
+    .replace(/\s+/gu, " ").trim();
+}
+function dateValue(value: string): Pick<ArticleMetadataClaim, "value" | "datePrecision" | "timezone"> {
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+  const zoned = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
+  const local = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/.test(value);
+  const parsed = Date.parse(dateOnly ? value + "T00:00:00Z" : local ? value + "Z" : value);
+  const validDay = Number.isFinite(parsed) && new Date(Date.UTC(Number(value.slice(0, 4)), Number(value.slice(5, 7)) - 1, Number(value.slice(8, 10)))).toISOString().slice(0, 10) === value.slice(0, 10);
+  if ((!dateOnly && !zoned && !local) || !validDay) return { value, datePrecision: "invalid", timezone: "unknown" };
+  if (dateOnly) return { value, datePrecision: "date", timezone: "not-applicable" };
+  return { value: zoned ? new Date(parsed).toISOString() : value, datePrecision: "datetime", timezone: zoned ? "explicit" : "unknown" };
+}
+function rank(claim: ArticleMetadataClaim): number {
+  if (claim.datePrecision === "invalid") return 1000;
+  if (claim.source === "json-ld") return claim.rule.includes("jsonld-type=WebPage") ? 15 : 10;
+  if (claim.source === "html-link") return 5;
+  if (claim.locator.includes("property=article:")) return 20;
+  if (claim.locator.includes("property=og:")) return 30;
+  if (claim.locator.includes("name=twitter:")) return 40;
+  if (claim.source === "html-meta") return 50;
+  if (claim.source === "html-title" || claim.source === "html-language") return 60;
+  return 90;
+}
+function select(claims: readonly ArticleMetadataClaim[]): ArticleMetadataClaim[] {
+  const ranks = new Map<string, number>();
+  for (const claim of claims) ranks.set(claim.field, Math.min(ranks.get(claim.field) ?? 1000, rank(claim)));
+  const chosen = new Set<string>();
+  return claims.map((claim) => {
+    const multiple = ["authors", "tags", "alternate"].includes(claim.field);
+    const selected = rank(claim) < 1000 && rank(claim) === ranks.get(claim.field) && (multiple || !chosen.has(claim.field));
+    if (selected) chosen.add(claim.field);
+    return { ...claim, selected, rule: `metadata-precedence-v1:${claim.rule}` };
+  });
+}
+
+/** Validate an optional additive envelope from a worker or a stored bundle. */
+export function parseArticleMetadata(input: unknown, redact: (text: string) => string = cleanText): ArticleMetadata {
+  if (!record(input) || input.schemaVersion !== 1 || input.extractorVersion !== "wordcell-metadata-v1" || !Array.isArray(input.claims) || input.claims.length > metadataLimits.claims || !Array.isArray(input.warnings)) throw new Error("Unsupported or malformed article metadata envelope");
+  let bytes = 0;
+  const text = (value: unknown, limit: number = metadataLimits.value): string => {
+    if (typeof value !== "string" || value.length > limit) throw new Error("Invalid article metadata text");
+    const result = cleanText(redact(value));
+    bytes += Buffer.byteLength(result);
+    if (bytes > metadataLimits.totalBytes) throw new Error("Article metadata exceeds byte limit");
+    return result;
+  };
+  const value = (v: unknown): MetadataValue => Array.isArray(v)
+    ? v.length <= 32 ? v.map((part) => text(part)) : (() => { throw new Error("Article metadata list exceeds limit"); })()
+    : text(v);
+  const claims = input.claims.map((raw): ArticleMetadataClaim => {
+    if (!record(raw) || !sources.has(raw.source as MetadataSource) || typeof raw.selected !== "boolean") throw new Error("Invalid article metadata claim");
+    const field = text(raw.field, 128);
+    if (!/^[a-z][a-z0-9:_-]{0,127}$/.test(field) || credentialName.test(field)) throw new Error("Invalid article metadata field");
+    let observed = value(raw.observed), normalized = value(raw.value);
+    if (urlFields.has(field)) {
+      const urls = (input: MetadataValue): MetadataValue => {
+        const normalize = (part: string): string => {
+          const parsed = publicUrl(part);
+          if (parsed === null) throw new Error("Invalid article metadata URL");
+          return parsed;
+        };
+        return typeof input === "string" ? normalize(input) : input.map(normalize);
+      };
+      observed = urls(observed); normalized = urls(normalized);
+    }
+    const temporal = raw.datePrecision === undefined ? {} : dateFields.has(field) && typeof observed === "string"
+      ? dateValue(observed) : (() => { throw new Error("Invalid article metadata date"); })();
+    if (raw.datePrecision !== undefined && (raw.datePrecision !== (temporal as ArticleMetadataClaim).datePrecision || raw.timezone !== (temporal as ArticleMetadataClaim).timezone)) throw new Error("Invalid article metadata date precision");
+    return { field, observed, value: normalized, source: raw.source as MetadataSource, locator: text(raw.locator, 512), rule: text(raw.rule, 256), selected: raw.selected, ...temporal };
+  });
+  if (input.warnings.length > warningKinds.size || input.warnings.some((warning) => !warningKinds.has(warning))) throw new Error("Invalid article metadata warnings");
+  return { schemaVersion: 1, extractorVersion: "wordcell-metadata-v1", claims, warnings: [...input.warnings] as ArticleMetadata["warnings"] };
+}
+
+const fields: Readonly<Record<string, string>> = {
+  "og:title": "title", "twitter:title": "title", title: "title", "citation_title": "title", "dc.title": "title",
+  description: "description", "og:description": "description", "twitter:description": "description", "dc.description": "description",
+  author: "authors", "article:author": "authors", "citation_author": "authors", "dc.creator": "authors",
+  "article:published_time": "published", "datepublished": "published", "citation_publication_date": "published", "dc.date": "published",
+  "article:modified_time": "modified", "datemodified": "modified", "last-modified": "modified",
+  "og:url": "canonical", "twitter:url": "canonical", "og:image": "image", "og:image:url": "image", "twitter:image": "image", "twitter:image:src": "image",
+  "og:site_name": "site", publisher: "publisher", "dc.publisher": "publisher", "citation_journal_title": "publisher",
+  "og:locale": "language", language: "language", "dc.language": "language", "og:type": "type", "twitter:card": "card",
+  "article:tag": "tags", keywords: "tags", "news_keywords": "tags", "citation_keywords": "tags",
+  "citation_doi": "doi", "dc.identifier": "identifier", "citation_pdf_url": "alternate",
+};
+
+/** Parse inert HTML locally. JSON-LD contexts are evidence strings and are never resolved. */
+export async function extractArticleMetadata(html: string, base: string, fallback: { readonly title?: unknown; readonly author?: unknown; readonly published?: unknown; readonly description?: unknown } = {}): Promise<ArticleMetadata> {
+  const claims: ArticleMetadataClaim[] = [];
+  const warnings = new Set<ArticleMetadata["warnings"][number]>();
+  let totalBytes = 0, title = "", script = "", scriptIndex = 0, activeScript = false, jsonBytes = 0;
+  const add = (field: string, raw: unknown, source: MetadataSource, locator: string, decode = false, evidenceRule?: string): void => {
+    if (claims.length >= metadataLimits.claims) { warnings.add("claim-limit"); return; }
+    let values = Array.isArray(raw) ? raw : [raw];
+    if (values.length > 32) { warnings.add("value-limit"); values = values.slice(0, 32); }
+    const strings: string[] = [];
+    for (const value of values) {
+      if (typeof value !== "string") continue;
+      if (value.length > metadataLimits.value) { warnings.add("value-limit"); continue; }
+      const decoded = decode ? decodeHTML(value) : value;
+      const cleaned = cleanText(urlFields.has(field) ? publicUrl(decoded, base) ?? "" : decoded);
+      if (cleaned) strings.push(cleaned);
+    }
+    if (!strings.length) return;
+    const observed: MetadataValue = Array.isArray(raw) ? strings : strings[0]!;
+    let value: MetadataValue = observed;
+    if (urlFields.has(field)) {
+      const urls = strings.map((part) => publicUrl(part, base)).filter((part): part is string => part !== null);
+      if (!urls.length) return;
+      value = Array.isArray(raw) ? urls : urls[0]!;
+    }
+    const temporal = dateFields.has(field) && typeof observed === "string" ? dateValue(observed) : {};
+    const claim: ArticleMetadataClaim = { field, observed, value, source, locator, rule: `trim-whitespace-url-query-redaction${evidenceRule === undefined ? "" : `:${evidenceRule}`}`, selected: false, ...temporal };
+    const bytes = Buffer.byteLength(JSON.stringify(claim));
+    if (totalBytes + bytes > metadataLimits.totalBytes / 2) { warnings.add("claim-limit"); return; }
+    totalBytes += bytes; claims.push(claim);
+  };
+  const parseLd = (raw: string, index: number): void => {
+    if (!raw.trim()) return;
+    if (Buffer.byteLength(raw) > metadataLimits.jsonBytes || (jsonBytes += Buffer.byteLength(raw)) > metadataLimits.jsonBytes * 4) { warnings.add("json-limit"); return; }
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch { warnings.add("json-invalid"); return; }
+    let nodes = 0;
+    // A full bounded walk rejects deep or wide hostile payloads before extracting facts.
+    const stack: { value: unknown; depth: number }[] = [{ value: parsed, depth: 0 }];
+    while (stack.length) {
+      const node = stack.pop()!;
+      if (++nodes > metadataLimits.jsonNodes || node.depth > metadataLimits.jsonDepth) { warnings.add("json-limit"); return; }
+      const children = Array.isArray(node.value) ? node.value : record(node.value) ? Object.values(node.value) : [];
+      if (children.length + nodes + stack.length > metadataLimits.jsonNodes) { warnings.add("json-limit"); return; }
+      for (const child of children) stack.push({ value: child, depth: node.depth + 1 });
+    }
+    const items: { value: unknown; path: string }[] = Array.isArray(parsed) ? parsed.map((value, i) => ({ value, path: `$[${i}]` })) : [{ value: parsed, path: "$" }];
+    for (let cursor = 0; cursor < items.length && cursor < metadataLimits.jsonNodes; cursor++) {
+      const item = items[cursor]!;
+      if (!record(item.value)) continue;
+      const object = item.value;
+      if (Array.isArray(object["@graph"])) items.push(...object["@graph"].map((value, i) => ({ value, path: `${item.path}.@graph[${i}]` })));
+      const types = Array.isArray(object["@type"]) ? object["@type"] : [object["@type"]];
+      const entityTypes = types.flatMap((type) => {
+        const match = typeof type === "string" ? /^(?:(?:https?:\/\/)?schema\.org\/)?(Article|NewsArticle|BlogPosting|ScholarlyArticle|TechArticle|Report|WebPage|VideoObject|AudioObject|PodcastEpisode)$/.exec(type) : null;
+        return match?.[1] === undefined ? [] : [match[1]];
+      });
+      const entityType = entityTypes.find(type => type !== "WebPage") ?? entityTypes[0];
+      if (entityType === undefined) continue;
+      const names = (v: unknown): unknown => Array.isArray(v) ? v.slice(0, 32).map((entry) => record(entry) ? entry.name : entry) : record(v) ? v.name : v;
+      const props: Readonly<Record<string, string>> = { headline: "title", name: "title", description: "description", author: "authors", creator: "authors", datePublished: "published", dateModified: "modified", inLanguage: "language", publisher: "publisher", keywords: "tags", image: "image", thumbnailUrl: "image", url: "canonical", mainEntityOfPage: "canonical", duration: "duration", episodeNumber: "episode", identifier: "identifier" };
+      for (const [key, field] of Object.entries(props)) {
+        let value = object[key];
+        if (value === undefined) continue;
+        if (["author", "creator", "publisher"].includes(key)) value = names(value);
+        if (key === "image") value = Array.isArray(value) ? value.map((v) => record(v) ? v.url ?? v.contentUrl : v) : record(value) ? value.url ?? value.contentUrl : value;
+        if (key === "mainEntityOfPage" && record(value)) value = value["@id"] ?? value.url;
+        if (key === "episodeNumber" && typeof value === "number" && Number.isFinite(value)) value = String(value);
+        add(field, value, "json-ld", `script[${index}]${item.path}.${key}`, false, `jsonld-type=${entityType}`);
+      }
+    }
+  };
+  let input = html;
+  if (Buffer.byteLength(input) > metadataLimits.htmlBytes) { input = Buffer.from(input).subarray(0, metadataLimits.htmlBytes).toString("utf8"); warnings.add("input-limit"); }
+  await new HTMLRewriter()
+    .on("html", { element(element) { add("language", element.getAttribute("lang"), "html-language", "html@lang", true); } })
+    .on("title", { text(chunk) { if (title.length <= metadataLimits.value) title += chunk.text; } })
+    .on("meta", { element(element) {
+      const attribute = element.getAttribute("property") ? "property" : "name";
+      const key = decodeHTML(element.getAttribute(attribute) ?? "").toLowerCase();
+      if (!/^[a-z][a-z0-9:._-]{0,100}$/.test(key) || credentialName.test(key)) return;
+      const field = Object.hasOwn(fields, key) ? fields[key]! : `meta:${key.replaceAll(".", "_")}`;
+      add(field, element.getAttribute("content"), "html-meta", `meta[${attribute}=${key}]@content`, true);
+    } })
+    .on("link", { element(element) {
+      const rel = (element.getAttribute("rel") ?? "").toLowerCase().split(/\s+/);
+      const field = rel.includes("canonical") ? "canonical" : rel.includes("alternate") ? "alternate" : null;
+      if (field) add(field, element.getAttribute("href"), "html-link", `link[rel=${field}]@href`, true);
+    } })
+    .on("script", { element(element) {
+      activeScript = (element.getAttribute("type") ?? "").toLowerCase().trim() === "application/ld+json";
+      script = "";
+      if (activeScript) {
+        const index = scriptIndex++;
+        if (index >= 64) { activeScript = false; warnings.add("json-limit"); return; }
+        element.onEndTag(() => { parseLd(script, index); activeScript = false; });
+      }
+    }, text(chunk) { if (activeScript && script.length <= metadataLimits.jsonBytes) script += chunk.text; } })
+    .transform(new Response(input)).text();
+  if (activeScript) warnings.add("json-invalid");
+  add("title", title, "html-title", "title", true);
+  for (const [key, field] of Object.entries({ title: "title", author: "authors", published: "published", description: "description" })) add(field, fallback[key as keyof typeof fallback], "extractor", `defuddle.${key}`);
+  return parseArticleMetadata({ schemaVersion: 1, extractorVersion: "wordcell-metadata-v1", claims: select(claims), warnings: [...warnings] });
+}
diff --git a/src/clip/persist.ts b/src/clip/persist.ts
index d7503270..eef6ba23 100644
--- a/src/clip/persist.ts
+++ b/src/clip/persist.ts
@@ -1,3 +1,4 @@
+import { parseArticleMetadata, type ArticleMetadata } from "./metadata.js";
 import {
   chmodSync,
   existsSync,
@@ -48,6 +49,7 @@ export type VideoContextManifestMetadata = {
 };
 
 export type CaptureManifestInput = {
+  readonly metadata?: ArticleMetadata;
   readonly sourceUrl: string;
   readonly canonicalUrl: string;
   readonly capturedAt: string;
@@ -1248,6 +1250,7 @@ function normalizeManifest(
   return {
     schemaVersion: CAPTURE_MANIFEST_SCHEMA_VERSION,
     document,
+    ...(input.metadata === undefined ? {} : { metadata: parseArticleMetadata(input.metadata, redactSensitiveText) }),
     sourceUrl: sanitizeArtifactUrl(input.sourceUrl),
     canonicalUrl: sanitizeArtifactUrl(input.canonicalUrl),
     capturedAt: new Date(capturedAtTime).toISOString(),
diff --git a/src/pdf.ts b/src/pdf.ts
index ef0c92c9..09267197 100644
--- a/src/pdf.ts
+++ b/src/pdf.ts
@@ -90,3 +90,13 @@ export type {
   PdfToolPaths,
   PdfToolRunner,
 } from "./pdf/model.js";
+
+import { inspectPdfCaptureBundle as inspectPdfCaptureBundleImplementation, verifyPdfCaptureBundle as verifyPdfCaptureBundleImplementation } from "./pdf/bundle-reader.js";
+import { PdfCaptureError as PdfCaptureErrorImplementation } from "./pdf/errors.js";
+export const inspectPdfCaptureBundle: typeof inspectPdfCaptureBundleImplementation = (...arguments_) => inspectPdfCaptureBundleImplementation(...arguments_);
+export const verifyPdfCaptureBundle: typeof verifyPdfCaptureBundleImplementation = (...arguments_) => verifyPdfCaptureBundleImplementation(...arguments_);
+export const PdfCaptureError = PdfCaptureErrorImplementation;
+export type PdfCaptureError = InstanceType<typeof PdfCaptureErrorImplementation>;
+export type { PdfCaptureErrorCode } from "./pdf/errors.js";
+export type { PdfBundleInspection, PdfBundleVerification, ReadPdfCaptureBundleOptions, PdfBundleIntegrity } from "./pdf/bundle-reader.js";
+export type { PdfQualityIssue } from "./pdf/model.js";
diff --git a/src/pdf/bundle-reader.test.ts b/src/pdf/bundle-reader.test.ts
new file mode 100644
index 00000000..74be01b8
--- /dev/null
+++ b/src/pdf/bundle-reader.test.ts
@@ -0,0 +1,87 @@
+import { afterEach, expect, test } from "bun:test";
+import fc from "fast-check";
+import { createHash } from "node:crypto";
+import { mkdtempSync, realpathSync, writeFileSync, mkdirSync, rmSync, symlinkSync, linkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { inspectPdfCaptureBundle, verifyPdfCaptureBundle } from "./bundle-reader.js";
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+const hash = (value: string): string => createHash("sha256").update(value).digest("hex");
+function fixture() {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "pdf-bundle-test-"))); roots.push(root);
+  const source = "%PDF-1.4\n%%EOF\n", markdown = "# Sample\n\n<!-- pdf-page: 1 -->\n\n![pixel](assets/image.png)\n", image = "fixture";
+  mkdirSync(join(root, "assets"));
+  writeFileSync(join(root, "source.pdf"), source); writeFileSync(join(root, "note.md"), markdown); writeFileSync(join(root, "assets/image.png"), image);
+  const descriptor = (path: string, text: string) => ({ path, bytes: Buffer.byteLength(text), sha256: hash(text) });
+  const manifest = { schemaVersion: 1, kind: "pdf", status: "complete", document: { pageCount: 1, processedPages: 1 }, source: { ...descriptor("source.pdf", source), mimeType: "application/pdf" }, markdown: descriptor("note.md", markdown), images: [{ id: "image-1", page: 1, asset: descriptor("assets/image.png", image) }], annotations: null, extraction: { imageCount: 1 } };
+  const save = (value: unknown = manifest) => writeFileSync(join(root, "capture.json"), JSON.stringify(value)); save();
+  return { root, manifest, save };
+}
+test("verifies source, Markdown, image digests and page references", async () => {
+  const { root } = fixture(); const result = await verifyPdfCaptureBundle(root);
+  expect(result.ok).toBe(true); expect(result.inspection.assets).toHaveLength(1);
+});
+test("legacy Markdown is readable but explicitly unverified", async () => {
+  const { root, manifest, save } = fixture(); const { markdown: _, ...legacy } = manifest; save(legacy);
+  const result = await verifyPdfCaptureBundle(root); expect(result.ok).toBe(false); expect(result.inspection.markdown.integrity).toBe("unavailable");
+});
+test("tampering never verifies", async () => {
+  const { root } = fixture(); writeFileSync(join(root, "source.pdf"), "%PDF-tampered"); writeFileSync(join(root, "assets/image.png"), "damage");
+  const result = await verifyPdfCaptureBundle(root); expect(result.ok).toBe(false); expect(result.issues.map(issue => issue.kind)).toEqual(["source-integrity", "asset-integrity"]);
+});
+test("rejects unsupported schemas and false complete quality", async () => {
+  const { root, manifest, save } = fixture(); save({ ...manifest, schemaVersion: 2 }); await expect(inspectPdfCaptureBundle(root)).rejects.toMatchObject({ code: "unsupported-schema" });
+  save({ ...manifest, quality: { schemaVersion: 1, issues: [{ page: 1, code: "reading-order-uncertain" }] } }); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("cannot claim complete");
+});
+test("rejects linked files, linked parents, aliases and multiple hard links", async () => {
+  const { root } = fixture(); rmSync(join(root, "assets/image.png")); symlinkSync(join(root, "source.pdf"), join(root, "assets/image.png")); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("single-link");
+  rmSync(join(root, "assets/image.png")); linkSync(join(root, "source.pdf"), join(root, "assets/image.png")); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("single-link");
+  rmSync(join(root, "assets"), { recursive: true }); symlinkSync(root, join(root, "assets")); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("ancestor");
+  const alias = join(root, "alias"); symlinkSync(root, alias); await expect(inspectPdfCaptureBundle(alias)).rejects.toThrow("canonical");
+});
+test("rejects invalid UTF-8, image page references and asset quotas", async () => {
+  const { root, manifest, save } = fixture();
+  await expect(inspectPdfCaptureBundle(root, { maxTotalAssetBytes: 2 })).rejects.toMatchObject({ code: "limit-exceeded" });
+  manifest.images[0]!.page = 2; save(); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("page reference");
+  manifest.images[0]!.page = 1; save(); writeFileSync(join(root, "note.md"), Buffer.from([0xff])); await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("UTF-8");
+});
+test("rejects mismatched annotation references", async () => {
+  const { root, manifest, save } = fixture(); const bytes = JSON.stringify([{ id: "other", sha256: "a".repeat(64), kind: "visual" }]);
+  writeFileSync(join(root, "annotations.json"), bytes);
+  save({ ...manifest, annotations: { path: "annotations.json", bytes: Buffer.byteLength(bytes), sha256: hash(bytes), count: 1 } });
+  await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("unknown image");
+});
+test("arbitrary traversal paths are rejected", async () => {
+  const { root, manifest, save } = fixture();
+  await fc.assert(fc.asyncProperty(fc.stringMatching(/^[a-z]{1,20}$/), async value => {
+    save({ ...manifest, markdown: { ...manifest.markdown, path: `../${value}.md` } });
+    await expect(inspectPdfCaptureBundle(root)).rejects.toThrow("unsafe segment");
+  }), { numRuns: 50 });
+});
+test("undeclared Markdown assets cannot pass verification", async () => {
+  const {root, manifest, save}=fixture();
+  const markdown="<!-- pdf-page: 1 -->\n![one](assets/image.png) ![missing](assets/absent.png)\n";
+  writeFileSync(join(root,"note.md"),markdown);manifest.markdown={path:"note.md",bytes:Buffer.byteLength(markdown),sha256:hash(markdown)};save();
+  await expect(verifyPdfCaptureBundle(root)).rejects.toThrow("undeclared PDF asset");
+});
+test("cumulative asset budget accounts actual bytes when declared sizes are understated", async () => {
+  const {root,manifest,save}=fixture();
+  const markdown="<!-- pdf-page: 1 -->\n![one](assets/image.png) ![two](assets/second.png)\n";
+  writeFileSync(join(root,"note.md"),markdown);writeFileSync(join(root,"assets/second.png"),"fixture");
+  manifest.markdown={path:"note.md",bytes:Buffer.byteLength(markdown),sha256:hash(markdown)};
+  manifest.images[0]!.asset.bytes=1;manifest.images.push({id:"image-2",page:1,asset:{path:"assets/second.png",bytes:1,sha256:hash("fixture")}});manifest.extraction.imageCount=2;save();
+  await expect(inspectPdfCaptureBundle(root,{maxTotalAssetBytes:10})).rejects.toThrow("exceeds");
+  const result=await verifyPdfCaptureBundle(root,{maxTotalAssetBytes:14});expect(result.ok).toBe(false);expect(result.inspection.assets).toHaveLength(2);
+});
+test("invalid annotation shapes have a typed invalid-input failure",async()=>{
+ const {root,manifest,save}=fixture();const bytes=JSON.stringify([{kind:"unknown"}]);writeFileSync(join(root,"annotations.json"),bytes);
+ save({...manifest,annotations:{path:"annotations.json",bytes:Buffer.byteLength(bytes),sha256:hash(bytes),count:1}});
+ await expect(inspectPdfCaptureBundle(root)).rejects.toMatchObject({code:"invalid-input"});
+});
+test("Markdown cannot silently associate a retained image with an undeclared page",async()=>{
+ const {root,manifest,save}=fixture();const markdown="<!-- pdf-page: 1 -->\n![one](assets/image.png)\n<!-- pdf-page: 2 -->\n![two](assets/image.png)\n";
+ writeFileSync(join(root,"note.md"),markdown);manifest.document={pageCount:2,processedPages:2};manifest.markdown={path:"note.md",bytes:Buffer.byteLength(markdown),sha256:hash(markdown)};save();
+ await expect(verifyPdfCaptureBundle(root)).rejects.toThrow("page disagrees");
+ manifest.images.push({...manifest.images[0]!,id:"image-2",page:2});manifest.extraction.imageCount=2;save();expect((await verifyPdfCaptureBundle(root)).ok).toBe(true);
+});
diff --git a/src/pdf/bundle-reader.ts b/src/pdf/bundle-reader.ts
new file mode 100644
index 00000000..b8a37fea
--- /dev/null
+++ b/src/pdf/bundle-reader.ts
@@ -0,0 +1,457 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants, type BigIntStats } from "node:fs";
+import { lstat, open, opendir, realpath, type FileHandle } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { PdfCaptureError } from "./errors.js";
+import { parsePdfImageInterpretations } from "./layout.js";
+
+// The same no-follow/inode fencing used by the article reader, specialized for PDF.
+function boundedInteger(value: number | undefined, fallback: number, maximum: number, label: string): number {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
+  }
+  return selected;
+}
+
+function confinedRelativePath(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 4_096 || value.includes("\0")) {
+    throw new PdfCaptureError("integrity", `${label} must be a bounded non-empty path`);
+  }
+  if (isAbsolute(value) || value.includes("\\")) throw new PdfCaptureError("integrity", `${label} must be a relative POSIX path`);
+  const segments = value.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new PdfCaptureError("integrity", `${label} contains an unsafe segment`);
+  }
+  return value;
+}
+
+type SafeBundleRoot = {
+  readonly path: string;
+  readonly handle: FileHandle;
+  readonly device: bigint;
+  readonly inode: bigint;
+};
+
+class MissingCaptureAssetError extends PdfCaptureError {
+  constructor(message: string) { super("integrity", message); }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function assertAssetVerificationDeadline(deadline: number | undefined): void {
+  if (deadline !== undefined && performance.now() >= deadline) {
+    throw new PdfCaptureError("timeout", "capture asset verification exceeded its time budget");
+  }
+}
+
+function confined(root: SafeBundleRoot, relativePath: string, label: string): string {
+  const path = resolve(root.path, relativePath);
+  const lexical = relative(root.path, path);
+  if (lexical === "" || lexical === ".." || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+    throw new PdfCaptureError("integrity", `${label} escapes the capture bundle`);
+  }
+  return path;
+}
+
+async function safeDirectory(pathInput: string): Promise<SafeBundleRoot> {
+  if (pathInput.trim() === "") throw new PdfCaptureError("integrity", "capture bundle path is required");
+  const path = resolve(pathInput);
+  const canonical = await realpath(path);
+  if (canonical !== path) throw new PdfCaptureError("integrity", "capture bundle path must be canonical and cannot traverse a symbolic link");
+  const stats = await lstat(path, { bigint: true });
+  if (!stats.isDirectory() || stats.isSymbolicLink()) throw new PdfCaptureError("integrity", "capture bundle path must be a real directory");
+  if (dirname(path) === path) throw new PdfCaptureError("integrity", "refusing a filesystem root as a capture bundle");
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isDirectory() || opened.dev !== stats.dev || opened.ino !== stats.ino) {
+      throw new PdfCaptureError("integrity", "capture bundle root changed while it was opened");
+    }
+    return { path, handle, device: opened.dev, inode: opened.ino };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+
+async function assertBundleRoot(root: SafeBundleRoot, deadline?: number): Promise<void> {
+  assertAssetVerificationDeadline(deadline);
+  const [opened, named, canonical] = await Promise.all([
+    root.handle.stat({ bigint: true }),
+    lstat(root.path, { bigint: true }),
+    realpath(root.path),
+  ]);
+  assertAssetVerificationDeadline(deadline);
+  if (
+    canonical !== root.path
+    || !opened.isDirectory()
+    || !named.isDirectory()
+    || named.isSymbolicLink()
+    || opened.dev !== root.device
+    || opened.ino !== root.inode
+    || named.dev !== root.device
+    || named.ino !== root.inode
+  ) throw new PdfCaptureError("integrity", "capture bundle root changed during inspection");
+}
+
+async function assertAncestorChain(
+  root: SafeBundleRoot,
+  relativePath: string,
+  label: string,
+  deadline?: number,
+): Promise<void> {
+  await assertBundleRoot(root, deadline);
+  const segments = confinedRelativePath(relativePath, label).split("/");
+  let current = root.path;
+  for (const segment of segments.slice(0, -1)) {
+    current = resolve(current, segment);
+    assertAssetVerificationDeadline(deadline);
+    const metadata = await lstat(current, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a linked or non-directory ancestor`);
+    }
+    const canonical = await realpath(current);
+    assertAssetVerificationDeadline(deadline);
+    if (canonical !== current) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+    }
+  }
+  await assertBundleRoot(root, deadline);
+}
+
+async function withRegularFile<T>(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  label: string,
+  read: (handle: FileHandle, size: number) => Promise<T>,
+  deadline?: number,
+  missingError?: Error,
+): Promise<T> {
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  let before: BigIntStats;
+  try {
+    before = await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (missingError !== undefined && isMissingPathError(error)) throw missingError;
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
+    throw new PdfCaptureError("integrity", `${label} must be a regular single-link file`);
+  }
+  if (before.size > BigInt(maximumBytes)) throw new PdfCaptureError("integrity", `${label} exceeds ${maximumBytes} bytes`);
+  const canonical = await realpath(path);
+  assertAssetVerificationDeadline(deadline);
+  if (canonical !== path) throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    assertAssetVerificationDeadline(deadline);
+    const opened = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (
+      !opened.isFile()
+      || opened.nlink !== 1n
+      || opened.dev !== before.dev
+      || opened.ino !== before.ino
+      || opened.size !== before.size
+    ) throw new PdfCaptureError("integrity", `${label} changed while it was opened`);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const result = await read(handle, Number(opened.size));
+    assertAssetVerificationDeadline(deadline);
+    const after = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    const named = await lstat(path, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const finalCanonical = await realpath(path);
+    assertAssetVerificationDeadline(deadline);
+    if (
+      after.dev !== before.dev
+      || after.ino !== before.ino
+      || after.size !== before.size
+      || after.mtimeNs !== before.mtimeNs
+      || after.nlink !== 1n
+      || named.dev !== before.dev
+      || named.ino !== before.ino
+      || named.size !== before.size
+      || named.mtimeNs !== before.mtimeNs
+      || named.nlink !== 1n
+      || named.isSymbolicLink()
+      || finalCanonical !== path
+    ) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+    return result;
+  } finally {
+    await handle.close();
+    assertAssetVerificationDeadline(deadline);
+  }
+}
+
+async function readRegularFile(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  label: string,
+  deadline?: number,
+): Promise<Buffer> {
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    const bytes = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+      if (result.bytesRead === 0) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      offset += result.bytesRead;
+    }
+    return bytes;
+  }, deadline);
+}
+
+async function hashRegularFile(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  deadline: number,
+  label: string,
+): Promise<{ readonly bytes: number; readonly sha256: string }> {
+  assertAssetVerificationDeadline(deadline);
+  await assertBundleRoot(root, deadline);
+  assertAssetVerificationDeadline(deadline);
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  try {
+    await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (isMissingPathError(error)) {
+      await assertBundleRoot(root, deadline);
+      throw new MissingCaptureAssetError(`capture asset ${relativePath} is missing`);
+    }
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    assertAssetVerificationDeadline(deadline);
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(Math.min(1 * 1_024 * 1_024, Math.max(1, size)));
+    let offset = 0;
+    while (offset < size) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(chunk, 0, Math.min(chunk.byteLength, size - offset), offset);
+      assertAssetVerificationDeadline(deadline);
+      if (result.bytesRead === 0) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      hash.update(chunk.subarray(0, result.bytesRead));
+      offset += result.bytesRead;
+    }
+    assertAssetVerificationDeadline(deadline);
+    return { bytes: size, sha256: hash.digest("hex") };
+  }, deadline, new MissingCaptureAssetError(`capture asset ${relativePath} is missing`));
+}
+
+function digest(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+
+type RecordValue = Readonly<Record<string, unknown>>;
+type Descriptor = { readonly path: string; readonly bytes: number; readonly sha256: string };
+export type PdfBundleIntegrity = "verified" | "mismatch" | "unavailable";
+export type PdfBundleFile = Descriptor & { readonly integrity: PdfBundleIntegrity };
+export type PdfBundleInspection = {
+  readonly root: string;
+  readonly schemaVersion: 1;
+  readonly status: "complete" | "partial";
+  readonly pageCount: number;
+  readonly processedPages: number;
+  readonly markdown: PdfBundleFile & { readonly markdown: string };
+  readonly source: PdfBundleFile;
+  readonly assets: readonly PdfBundleFile[];
+  readonly annotations: PdfBundleFile | null;
+};
+export type ReadPdfCaptureBundleOptions = {
+  readonly maxDocumentBytes?: number;
+  readonly maxSourceBytes?: number;
+  readonly maxAssetBytes?: number;
+  readonly maxTotalAssetBytes?: number;
+  readonly maxVerifiedAssets?: number;
+  readonly maxVerificationMs?: number;
+};
+export type PdfBundleVerification = {
+  readonly ok: boolean;
+  readonly inspection: PdfBundleInspection;
+  readonly issues: readonly { readonly kind: "document-integrity" | "source-integrity" | "asset-integrity" | "annotation-integrity"; readonly path: string; readonly integrity: PdfBundleIntegrity }[];
+};
+function invalid(message: string): never { throw new PdfCaptureError("invalid-input", message); }
+function object(value: unknown): RecordValue {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalid("PDF bundle requires an object");
+  return value as RecordValue;
+}
+function integer(value: unknown, maximum: number, minimum = 0): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) invalid("PDF bundle has an invalid count or page reference");
+  return value;
+}
+function descriptor(value: unknown): Descriptor {
+  const entry = object(value);
+  if (typeof entry.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(entry.sha256)) invalid("PDF bundle has an invalid digest");
+  return { path: confinedRelativePath(entry.path, "PDF artifact"), bytes: integer(entry.bytes, 8 * 1024 ** 3), sha256: entry.sha256 };
+}
+function decode(bytes: Buffer): string {
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+  catch { return invalid("PDF bundle text is not UTF-8"); }
+}
+function parse(bytes: Buffer): unknown {
+  try { return JSON.parse(decode(bytes)) as unknown; }
+  catch (error) { if (error instanceof PdfCaptureError) throw error; return invalid("PDF bundle JSON is invalid"); }
+}
+
+/** Inspect retained source and assets without following aliases or trusting manifest paths. */
+export async function inspectPdfCaptureBundle(path: string, options: ReadPdfCaptureBundleOptions = {}): Promise<PdfBundleInspection> {
+  const maxDocument = boundedInteger(options.maxDocumentBytes, 64 * 1024 ** 2, 256 * 1024 ** 2, "maxDocumentBytes");
+  const maxSource = boundedInteger(options.maxSourceBytes, 512 * 1024 ** 2, 8 * 1024 ** 3, "maxSourceBytes");
+  const maxAsset = boundedInteger(options.maxAssetBytes, 100 * 1024 ** 2, 8 * 1024 ** 3, "maxAssetBytes");
+  const maxTotal = boundedInteger(options.maxTotalAssetBytes, 500 * 1024 ** 2, 8 * 1024 ** 3, "maxTotalAssetBytes");
+  const maxAssets = boundedInteger(options.maxVerifiedAssets, 1000, 10_000, "maxVerifiedAssets");
+  const deadline = performance.now() + boundedInteger(options.maxVerificationMs, 30_000, 300_000, "maxVerificationMs");
+  const root = await safeDirectory(path);
+  try {
+    const manifest = object(parse(await readRegularFile(root, "capture.json", 4 * 1024 ** 2, "PDF manifest", deadline)));
+    if (manifest.schemaVersion !== 1) throw new PdfCaptureError("unsupported-schema", "Unsupported PDF manifest schema");
+    if (manifest.kind !== "pdf" || (manifest.status !== "complete" && manifest.status !== "partial")) invalid("Invalid PDF manifest kind or status");
+    const document = object(manifest.document);
+    const pageCount = integer(document.pageCount, 100_000, 1);
+    const processedPages = integer(document.processedPages, pageCount, 1);
+    if (processedPages < pageCount && manifest.status !== "partial") invalid("Truncated PDF cannot claim complete");
+    if (manifest.quality !== undefined) {
+      const quality = object(manifest.quality);
+      if (quality.schemaVersion !== 1) throw new PdfCaptureError("unsupported-schema", "Unsupported PDF quality schema");
+      if (!Array.isArray(quality.issues) || quality.issues.length > 100_000) invalid("Invalid PDF quality issues");
+      for (const raw of quality.issues as unknown[]) {
+        const issue = object(raw);
+        if (!["reading-order-uncertain", "table-structure-uncertain", "math-structure-uncertain", "ocr-needed"].includes(String(issue.code))) invalid("Unknown PDF quality issue");
+        integer(issue.page, processedPages, 1);
+      }
+      if (quality.issues.length > 0 && manifest.status !== "partial") invalid("Uncertain PDF cannot claim complete");
+    }
+    const sourceDescriptor = descriptor(manifest.source);
+    if (sourceDescriptor.path !== "source.pdf" || object(manifest.source).mimeType !== "application/pdf") invalid("Invalid retained PDF source");
+    const check = async (expected: Descriptor, maximum: number): Promise<PdfBundleFile> => {
+      if (expected.bytes > maximum) throw new PdfCaptureError("limit-exceeded", "PDF artifact exceeds verification byte limit");
+      const actual = await hashRegularFile(root, expected.path, maximum, deadline, "PDF artifact");
+      return { ...actual, path: expected.path, integrity: actual.bytes === expected.bytes && actual.sha256 === expected.sha256 ? "verified" : "mismatch" };
+    };
+    const source = await check(sourceDescriptor, maxSource);
+    let expectedMarkdown: Descriptor | null = null;
+    let markdownPath: string;
+    if (manifest.markdown !== undefined) {
+      expectedMarkdown = descriptor(manifest.markdown);
+      markdownPath = expectedMarkdown.path;
+      if (markdownPath.includes("/") || !markdownPath.endsWith(".md")) invalid("Invalid PDF Markdown path");
+    } else {
+      // Legacy bundles retain their readable Markdown, but its digest is not attested.
+      const directory = await opendir(root.path);
+      const candidates: string[] = [];
+      let entries = 0;
+      try {
+        for await (const entry of directory) {
+          assertAssetVerificationDeadline(deadline);
+          if (++entries > 1000) throw new PdfCaptureError("limit-exceeded", "Legacy PDF directory exceeds entry limit");
+          if (entry.name.endsWith(".md")) candidates.push(entry.name);
+        }
+      } finally { try { await directory.close(); } catch { /* Iteration closes the directory. */ } }
+      if (candidates.length !== 1) invalid("Legacy PDF bundle must contain exactly one Markdown document");
+      markdownPath = candidates[0]!;
+    }
+    const markdownBytes = await readRegularFile(root, markdownPath, maxDocument, "PDF Markdown", deadline);
+    const markdownText = decode(markdownBytes);
+    const markdownDigest = digest(markdownBytes);
+    const markdown: PdfBundleInspection["markdown"] = {
+      path: markdownPath, bytes: markdownBytes.length, sha256: markdownDigest, markdown: markdownText,
+      integrity: expectedMarkdown === null ? "unavailable" : expectedMarkdown.bytes === markdownBytes.length && expectedMarkdown.sha256 === markdownDigest ? "verified" : "mismatch",
+    };
+    const assetReferences = new Map<string, Set<number>>();
+    let currentPage = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->|!\[[^\]\n]*\]\((assets\/[^)\r\n]+)\)/gu)) {
+      if (match[1] !== undefined) currentPage = integer(Number(match[1]), processedPages, 1);
+      else if (match[2] !== undefined) {
+        const pages = assetReferences.get(match[2]) ?? new Set<number>(); pages.add(currentPage); assetReferences.set(match[2], pages);
+      }
+    }
+    const anchors = new Set<number>();
+    let anchorCount = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->/gu)) {
+      if (++anchorCount > 100_000) invalid("Too many PDF page anchors");
+      anchors.add(integer(Number(match[1]), processedPages, 1));
+    }
+    if (!Array.isArray(manifest.images) || manifest.images.length > maxAssets) invalid("Invalid PDF image count");
+    const imageIds = new Map<string, string>();
+    const assetsByPath = new Map<string, PdfBundleFile>();
+    const declaredPages = new Map<string, Set<number>>();
+    let totalBytes = 0;
+    for (const raw of manifest.images as unknown[]) {
+      const image = object(raw);
+      if (typeof image.id !== "string" || !/^[a-z0-9][a-z0-9._:-]{0,255}$/u.test(image.id) || imageIds.has(image.id)) invalid("Invalid or duplicate PDF image ID");
+      const page = integer(image.page, processedPages, 1);
+      if (!anchors.has(page)) invalid("PDF image has no corresponding Markdown page anchor");
+      const asset = descriptor(image.asset);
+      if (!/^assets\/[^/]+$/u.test(asset.path)) invalid("PDF image must be a direct assets child");
+      if (!assetReferences.get(asset.path)?.has(page)) invalid("PDF image has no corresponding Markdown asset reference");
+      imageIds.set(image.id, asset.sha256);
+      const pages = declaredPages.get(asset.path) ?? new Set<number>();
+      pages.add(page); declaredPages.set(asset.path, pages);
+      const existing = assetsByPath.get(asset.path);
+      if (existing !== undefined) {
+        if (existing.bytes !== asset.bytes || existing.sha256 !== asset.sha256) invalid("Conflicting PDF asset descriptors");
+      } else {
+        totalBytes += asset.bytes;
+        if (totalBytes > maxTotal) throw new PdfCaptureError("limit-exceeded", "PDF assets exceed total byte limit");
+        const checked = await check(asset, Math.min(maxAsset, maxTotal - (totalBytes - asset.bytes)));
+        totalBytes += checked.bytes - asset.bytes;
+        assetsByPath.set(asset.path, checked);
+      }
+    }
+    for (const [path, pages] of assetReferences) {
+      if (!assetsByPath.has(path)) invalid("Markdown references an undeclared PDF asset");
+      if ([...pages].some(page => !declaredPages.get(path)?.has(page))) invalid("Markdown asset page disagrees with PDF manifest");
+    }
+    const extraction = object(manifest.extraction);
+    if (integer(extraction.imageCount, maxAssets) !== imageIds.size) invalid("PDF image count disagrees with manifest");
+    let annotations: PdfBundleFile | null = null;
+    if (manifest.annotations !== null) {
+      const annotationDescriptor = descriptor(manifest.annotations);
+      if (annotationDescriptor.path !== "annotations.json") invalid("Invalid PDF annotations path");
+      const annotationBytes = await readRegularFile(root, "annotations.json", 16 * 1024 ** 2, "PDF annotations", deadline);
+      const annotationHash = digest(annotationBytes);
+      annotations = { path: annotationDescriptor.path, bytes: annotationBytes.length, sha256: annotationHash, integrity: annotationDescriptor.bytes === annotationBytes.length && annotationDescriptor.sha256 === annotationHash ? "verified" : "mismatch" };
+      let retained: ReturnType<typeof parsePdfImageInterpretations>;
+      try { retained = parsePdfImageInterpretations(parse(annotationBytes)); }
+      catch (error) { if (error instanceof PdfCaptureError) throw error; throw new PdfCaptureError("invalid-input", "Invalid PDF image annotations", { cause: error }); }
+      if (retained.length !== integer(object(manifest.annotations).count, 10_000)) invalid("PDF annotation count disagrees with manifest");
+      for (const annotation of retained) {
+        if (imageIds.get(annotation.id) !== annotation.sha256) invalid("PDF annotation references an unknown image or digest");
+      }
+    }
+    await assertBundleRoot(root, deadline);
+    return { root: root.path, schemaVersion: 1, status: manifest.status, pageCount, processedPages, markdown, source, assets: [...assetsByPath.values()], annotations };
+  } finally { await root.handle.close(); }
+}
+
+/** Missing legacy Markdown provenance is explicit and never counted as verified. */
+export async function verifyPdfCaptureBundle(path: string, options: ReadPdfCaptureBundleOptions = {}): Promise<PdfBundleVerification> {
+  const inspection = await inspectPdfCaptureBundle(path, options);
+  const issues: Array<PdfBundleVerification["issues"][number]> = [];
+  const add = (file: PdfBundleFile, kind: PdfBundleVerification["issues"][number]["kind"]): void => {
+    if (file.integrity !== "verified") issues.push({ kind, path: file.path, integrity: file.integrity });
+  };
+  add(inspection.markdown, "document-integrity"); add(inspection.source, "source-integrity");
+  for (const asset of inspection.assets) add(asset, "asset-integrity");
+  if (inspection.annotations !== null) add(inspection.annotations, "annotation-integrity");
+  return { ok: issues.length === 0, inspection, issues };
+}
diff --git a/src/pdf/capture.test.ts b/src/pdf/capture.test.ts
index eea248c0..228f2abe 100644
--- a/src/pdf/capture.test.ts
+++ b/src/pdf/capture.test.ts
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import {
   mkdtempSync,
   readFileSync,
+  realpathSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
@@ -10,6 +11,7 @@ import { basename, dirname, join } from "node:path";
 
 import { afterEach, describe, expect, test } from "bun:test";
 
+import { verifyPdfCaptureBundle } from "./bundle-reader.js";
 import { runPdfCapture } from "./capture.js";
 import type {
   PdfCaptureDependencies,
@@ -54,6 +56,7 @@ function fakeDependencies(
   options: {
     readonly failOnTesseract?: boolean;
     readonly imageCount?: number;
+    readonly uncertainMath?: boolean;
   } = {},
 ): PdfCaptureDependencies {
   return {
@@ -92,7 +95,7 @@ function fakeDependencies(
 <fontspec id="0" size="24" family="Helvetica" color="#000000"/>
 <fontspec id="1" size="12" family="Helvetica" color="#000000"/>
 <text top="70" left="60" width="500" height="30" font="0"><b>Fixture PDF</b></text>
-<text top="130" left="60" width="500" height="16" font="1">A useful paragraph.</text>
+<text top="130" left="60" width="500" height="16" font="1">${options.uncertainMath ? "∫ f(x)" : "A useful paragraph."}</text>
 ${images.join("\n")}
 </page>
 </pdf2xml>`);
@@ -228,3 +231,15 @@ describe("PDF capture", () => {
     expect(outcome.warnings.join(" ")).toContain("configured asset byte limit was reached");
   });
 });
+
+
+test("capture returns the exact persisted Markdown digest and partial quality", async () => {
+  const fixture = sourceFixture();
+  const outcome = await runPdfCapture({ inputPath: fixture.sourcePath, outputBase: fixture.outputBase }, fakeDependencies({ uncertainMath: true }));
+  expect(outcome.status).toBe("partial");
+  expect(outcome.manifest.quality?.issues).toEqual([{ page: 1, code: "math-structure-uncertain" }]);
+  const bytes = readFileSync(outcome.markdownPath);
+  expect(outcome.manifest.markdown?.sha256).toBe(createHash("sha256").update(bytes).digest("hex"));
+  expect(outcome.manifest.markdown?.bytes).toBe(bytes.length);
+  expect((await verifyPdfCaptureBundle(realpathSync(outcome.outputDirectory))).ok).toBe(true);
+});
diff --git a/src/pdf/capture.ts b/src/pdf/capture.ts
index 0f73fd5b..991524da 100644
--- a/src/pdf/capture.ts
+++ b/src/pdf/capture.ts
@@ -8,7 +8,7 @@ import { slugify } from "../clip/lib.js";
 import { sanitizeTerminalText } from "../clip/terminal.js";
 import { inspectPdf } from "./extract.js";
 import {
-  layoutBlocks,
+  analyzePdfLayout,
   parsePdfImageInterpretations,
 } from "./layout.js";
 import {
@@ -183,6 +183,8 @@ export async function runPdfCapture(
       });
     }
     const platforms = embeddedPlatforms(resolvedImages);
+    const layout = analyzePdfLayout(inspection.pages);
+    for (const issue of layout.issues) warnings.push(`Page ${issue.page}: ${issue.code}; consult the retained source PDF.`);
     const status = warnings.length > 0 || unclassifiedImages > 0 || ocrWarningCount > 0
       ? "partial"
       : "complete";
@@ -190,7 +192,7 @@ export async function runPdfCapture(
     const requestedSlug = options.slug ?? inspection.metadata.title ?? filenameTitle;
     const slug = slugify(sanitizeTerminalText(requestedSlug));
     if (slug === "") throw new Error("could not derive a safe PDF capture slug; pass an explicit slug");
-    const blocks = layoutBlocks(inspection.pages);
+    const blocks = layout.blocks;
     const byId = new Map(resolvedImages.map((image) => [image.image.id, image]));
     const capturedAt = (dependencies.now ?? (() => new Date()))().toISOString();
     const built = buildPdfMarkdown({
@@ -233,6 +235,8 @@ export async function runPdfCapture(
     const manifest: PdfCaptureManifest = {
       schemaVersion: PDF_CAPTURE_MANIFEST_SCHEMA_VERSION,
       kind: "pdf",
+      quality: { schemaVersion: 1, issues: layout.issues },
+      markdown: { path: pdfMarkdownFilename(slug), bytes: Buffer.byteLength(built.markdown), sha256: createHash("sha256").update(built.markdown).digest("hex") },
       capturedAt,
       status,
       source: {
diff --git a/src/pdf/cli.ts b/src/pdf/cli.ts
index b38150c7..5173fca6 100644
--- a/src/pdf/cli.ts
+++ b/src/pdf/cli.ts
@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { lstatSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -149,7 +150,7 @@ export async function main(
     return 0;
   } catch (error) {
     const message = safe(error instanceof Error ? error.message : String(error));
-    if (arguments_.json) output.stdout(terminalSafeJson({ ok: false, error: message }));
+    if (arguments_.json) output.stdout(terminalSafeJson({ ok: false, error: message, code: error instanceof PdfCaptureError ? error.code : "unknown" }));
     else output.stderr(renderFailure(message, "wordcell doctor", stderrStyle(environment, output)));
     return 1;
   } finally {
diff --git a/src/pdf/errors.test.ts b/src/pdf/errors.test.ts
new file mode 100644
index 00000000..8ee358ae
--- /dev/null
+++ b/src/pdf/errors.test.ts
@@ -0,0 +1,27 @@
+import { expect, test } from "bun:test";
+import { runPdfToolCommand } from "./tools.js";
+import { PdfCaptureError } from "./errors.js";
+
+test("tool timeout and output overflow preserve typed codes", async () => {
+  await expect(runPdfToolCommand({ command: [process.execPath, "-e", "setTimeout(()=>{},10000)"], timeoutMs: 20, maxOutputBytes: 1024 })).rejects.toMatchObject({ code: "timeout" });
+  await expect(runPdfToolCommand({ command: [process.execPath, "-e", "process.stdout.write('a'.repeat(8192))"], timeoutMs: 5000, maxOutputBytes: 8 })).rejects.toMatchObject({ code: "limit-exceeded" });
+});
+test("missing executable is observed as tool-unavailable", async () => {
+  await expect(runPdfToolCommand({ command: ["/nonexistent/wordcell-test"], timeoutMs: 1000, maxOutputBytes: 1024 })).rejects.toMatchObject({ code: "tool-unavailable" });
+});
+test("typed error retains cause without classifying unknown prose", () => {
+  const cause = new Error("arbitrary private failure"); const error = new PdfCaptureError("unknown", "PDF operation failed", { cause });
+  expect(error.cause).toBe(cause); expect(error.code).toBe("unknown");
+});
+
+test("external supervision keeps PDF tools in the owned parent group", async () => {
+  if (process.platform === "win32") return;
+  const { execFileSync } = await import("node:child_process");
+  const parentGroup = Number(execFileSync("/bin/ps", ["-o", "pgid=", "-p", String(process.pid)], { encoding: "utf8" }).trim());
+  const code = "const {execFileSync}=require('node:child_process');process.stdout.write(JSON.stringify({pid:process.pid,group:Number(execFileSync('/bin/ps',['-o','pgid=','-p',String(process.pid)],{encoding:'utf8'}).trim())}))";
+  const command = [process.execPath, "-e", code];
+  const standalone = JSON.parse((await runPdfToolCommand({ command, timeoutMs: 5000, maxOutputBytes: 1024 })).stdout);
+  expect(standalone.group).toBe(standalone.pid);
+  const supervised = JSON.parse((await runPdfToolCommand({ command, processGroup: "inherit", timeoutMs: 5000, maxOutputBytes: 1024 })).stdout);
+  expect(supervised.group).toBe(parentGroup);
+});
diff --git a/src/pdf/errors.ts b/src/pdf/errors.ts
new file mode 100644
index 00000000..30d76d09
--- /dev/null
+++ b/src/pdf/errors.ts
@@ -0,0 +1,11 @@
+export type PdfCaptureErrorCode = "invalid-input" | "encrypted" | "limit-exceeded" | "tool-unavailable" | "extraction-failed" | "timeout" | "cancelled" | "integrity" | "unsupported-schema" | "unknown";
+
+/** Codes describe observed failures; unknown errors are never classified from their prose. */
+export class PdfCaptureError extends Error {
+  readonly code: PdfCaptureErrorCode;
+  constructor(code: PdfCaptureErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.code = code;
+    this.name = "PdfCaptureError";
+  }
+}
diff --git a/src/pdf/extract.ts b/src/pdf/extract.ts
index 2a34a6c9..262dae54 100644
--- a/src/pdf/extract.ts
+++ b/src/pdf/extract.ts
@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { createHash } from "node:crypto";
 import {
   chmodSync,
@@ -43,7 +44,7 @@ export const pdfCaptureDefaults = {
 function positiveBound(value: number | undefined, fallback: number, maximum: number, label: string): number {
   const selected = value ?? fallback;
   if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
-    throw new Error(`${label} must be an integer from 1 through ${maximum}`);
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
   }
   return selected;
 }
@@ -61,10 +62,10 @@ function prepareWorkspace(path: string): string {
   if (existsSync(absolute)) {
     const stats = lstatSync(absolute);
     if (!stats.isDirectory() || stats.isSymbolicLink()) {
-      throw new Error("PDF inspection workspace must be a real directory");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be a real directory");
     }
     if (readdirSync(absolute).length !== 0) {
-      throw new Error("PDF inspection workspace must be empty");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be empty");
     }
   } else {
     mkdirSync(absolute, { recursive: false, mode: 0o700 });
@@ -81,15 +82,15 @@ function sourceIdentity(path: string, maxPdfBytes: number): {
   const originalFilename = basename(path);
   const canonical = realpathSync(resolve(path));
   const stats = statSync(canonical);
-  if (!stats.isFile()) throw new Error("PDF input must be a regular file");
-  if (stats.size < 5) throw new Error("PDF input is too small to contain a PDF header");
-  if (stats.size > maxPdfBytes) throw new Error(`PDF input exceeds the ${maxPdfBytes}-byte limit`);
+  if (!stats.isFile()) throw new PdfCaptureError("invalid-input", "PDF input must be a regular file");
+  if (stats.size < 5) throw new PdfCaptureError("invalid-input", "PDF input is too small to contain a PDF header");
+  if (stats.size > maxPdfBytes) throw new PdfCaptureError("limit-exceeded", `PDF input exceeds the ${maxPdfBytes}-byte limit`);
   const descriptor = openSync(canonical, "r");
   try {
     const signature = Buffer.alloc(5);
     const count = readSync(descriptor, signature, 0, signature.length, 0);
     if (count !== signature.length || signature.toString("ascii") !== "%PDF-") {
-      throw new Error("PDF input does not have a valid PDF signature");
+      throw new PdfCaptureError("invalid-input", "PDF input does not have a valid PDF signature");
     }
   } finally {
     closeSync(descriptor);
@@ -155,18 +156,18 @@ function safeGeneratedImage(
 function generatedTreeSize(workspace: string, maximumFiles: number, maximumBytes: number): void {
   const entries = readdirSync(workspace, { withFileTypes: true });
   if (entries.length > maximumFiles) {
-    throw new Error(`PDF extraction created more than ${maximumFiles} files`);
+    throw new PdfCaptureError("limit-exceeded", `PDF extraction created more than ${maximumFiles} files`);
   }
   let totalBytes = 0;
   for (const entry of entries) {
     const path = join(workspace, entry.name);
     const stats = lstatSync(path);
     if (!entry.isFile() || stats.isSymbolicLink()) {
-      throw new Error("PDF extraction created an unexpected non-file output");
+      throw new PdfCaptureError("extraction-failed", "PDF extraction created an unexpected non-file output");
     }
     totalBytes += stats.size;
     if (totalBytes > maximumBytes) {
-      throw new Error(`PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
+      throw new PdfCaptureError("limit-exceeded", `PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
     }
   }
 }
@@ -208,7 +209,9 @@ export async function inspectPdf(
     cwd: workspaceDirectory,
   });
   if (info.exitCode !== 0) {
-    throw new Error("pdfinfo could not inspect the input PDF");
+    // Poppler runs in the C locale; only its exact password diagnostic establishes encryption.
+    const encrypted = info.stderr.split(/\r?\n/u).some(line => line.trim() === "Command Line Error: Incorrect password");
+    throw new PdfCaptureError(encrypted ? "encrypted" : "extraction-failed", "pdfinfo could not inspect the input PDF");
   }
   const metadata = parsePdfInfo(info.stdout);
   const processedPageLimit = Math.min(metadata.pageCount, maxPages);
@@ -233,7 +236,7 @@ export async function inspectPdf(
     cwd: workspaceDirectory,
   });
   if (extracted.exitCode !== 0) {
-    throw new Error("pdftohtml could not extract the input PDF");
+    throw new PdfCaptureError("extraction-failed", "pdftohtml could not extract the input PDF");
   }
   generatedTreeSize(
     workspaceDirectory,
@@ -245,7 +248,7 @@ export async function inspectPdf(
   );
   const layoutStats = statSync(layoutPath);
   if (!layoutStats.isFile() || layoutStats.size > pdfCaptureDefaults.maxLayoutBytes) {
-    throw new Error(`Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
+    throw new PdfCaptureError("limit-exceeded", `Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
   }
   const parsed = parsePopplerXml(readFileSync(layoutPath, "utf8"), {
     maxPages: processedPageLimit,
diff --git a/src/pdf/layout-analysis.test.ts b/src/pdf/layout-analysis.test.ts
new file mode 100644
index 00000000..f8263bc7
--- /dev/null
+++ b/src/pdf/layout-analysis.test.ts
@@ -0,0 +1,40 @@
+import { expect, test } from "bun:test";
+import fc from "fast-check";
+import { analyzePdfLayout } from "./layout.js";
+import type { PdfPageLayout, PdfTextFragment } from "./model.js";
+import { buildPdfMarkdown } from "./markdown.js";
+function fragment(text: string, left: number, top: number, width = 210, extra: Partial<PdfTextFragment> = {}): PdfTextFragment {
+  return { text, left, top, width, height: 14, fontSize: 12, fontId: "1", bold: false, italic: false, ...extra };
+}
+const page = (text: readonly PdfTextFragment[]): PdfPageLayout => ({ page: 1, width: 600, height: 800, text, images: [] });
+const content = (result: ReturnType<typeof analyzePdfLayout>): string => result.blocks.map(block => block.kind === "image" ? "image" : block.kind === "table" ? block.rows.flat().join(" ") : block.text).join(" ");
+test("orders columns before merging baselines and preserves a spanning heading", () => {
+  const text = [fragment("Heading", 30, 30, 300, { fontSize: 24 }), ...[0, 1, 2, 3].flatMap(i => [fragment(`left${i}`, 30, 100 + i * 20), fragment(`right${i}`, 330, 100 + i * 20)])];
+  const result = analyzePdfLayout([page(text)]);
+  expect(content(result)).toBe("Heading left0 left1 left2 left3 right0 right1 right2 right3"); expect(result.issues).toEqual([]); expect(result.blocks[0]!.kind).toBe("heading");
+});
+test("aligned compact numeric table with explicit header becomes escaped Markdown", () => {
+  const text = [fragment("Name\\|type", 30, 80, 60, { bold: true }), fragment("Count", 250, 80, 40, { bold: true }), ...[0, 1, 2].flatMap(i => [fragment(`item${i}`, 30, 100 + i * 20, 50), fragment(String(i), 250, 100 + i * 20, 30)])];
+  const result = analyzePdfLayout([page(text)]); expect(result.blocks[0]!.kind).toBe("table"); expect(result.issues).toEqual([]);
+  const built = buildPdfMarkdown({ slug: "table", originalFilename: "table.pdf", sourceSha256: "a".repeat(64), capturedDate: "2026-10-16", status: "complete", metadata: { title: null, author: null, subject: null, keywords: null, creator: null, producer: null, createdAt: null, modifiedAt: null, pageCount: 1, encrypted: false }, blocks: result.blocks, images: new Map(), embeddedPlatforms: [] });
+  expect(built.markdown).toContain("| Name\\\\\\|type | Count |"); expect(built.markdown).toContain("| --- | --- |");
+});
+test("adjacent raised digits remain attached while unsupported math is partial", () => {
+  const result = analyzePdfLayout([page([fragment("x", 30, 100, 10), fragment("2", 40, 95, 6, { fontSize: 8, height: 9 })])]); expect(content(result)).toBe("x²");
+  const uncertain = analyzePdfLayout([page([fragment("∫ f(x)", 30, 100)])]); expect(uncertain.issues).toEqual([{ page: 1, code: "math-structure-uncertain" }]);
+});
+test("ambiguous multi-cell geometry is reported instead of asserting a table", () => {
+  const result = analyzePdfLayout([page([0, 1, 2].flatMap(i => [fragment(`a${i}`, 30, 100 + i * 20, 30), fragment(`b${i}`, 200, 100 + i * 20, 30), fragment(`c${i}`, 400, 100 + i * 20, 30)]))]);
+  expect(result.issues.some(issue => issue.code === "table-structure-uncertain")).toBe(true);
+});
+test("column output is invariant to fragment input permutation and translation", () => {
+  fc.assert(fc.property(fc.integer({ min: 3, max: 20 }), fc.integer({ min: 0, max: 20 }), (count, shift) => {
+    const text = Array.from({ length: count }, (_, i) => [fragment(`L${i}`, 30 + shift, 100 + i * 20), fragment(`R${i}`, 330 + shift, 100 + i * 20)]).flat();
+    expect(content(analyzePdfLayout([page(text)]))).toBe(content(analyzePdfLayout([page([...text].reverse())])));
+    const output = content(analyzePdfLayout([page(text)])); for (let i = 0; i < count; i++) { expect(output.split(`L${i}`).length).toBeGreaterThan(1); expect(output.split(`R${i}`).length).toBeGreaterThan(1); }
+  }), { numRuns: 50 });
+});
+test("removing repeated margins preserves identical body text",()=>{
+ const pages=[1,2,3].map(number=>({...page([fragment("Methods",30,20),fragment("Methods",30,200)]),page:number}));
+ const result=analyzePdfLayout(pages);expect(content(result)).toBe("Methods Methods Methods");
+});
diff --git a/src/pdf/layout.ts b/src/pdf/layout.ts
index ea7d89ac..3ddf6d70 100644
--- a/src/pdf/layout.ts
+++ b/src/pdf/layout.ts
@@ -36,6 +36,7 @@ export type ParsedPopplerXml = {
 };
 
 export type PdfLayoutBlock =
+  | { readonly kind: "table"; readonly page: number; readonly rows: readonly (readonly string[])[] }
   | {
       readonly kind: "heading";
       readonly page: number;
@@ -456,7 +457,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
 
   for (const page of pages) {
     const lines = (linesByPage.get(page.page) ?? []).filter(
-      (line) => !repeatedMargins.has(normalizedMarginText(line.text)),
+      (line) => !(line.top <= page.height * 0.06 || line.top + line.height >= page.height * 0.94) || !repeatedMargins.has(normalizedMarginText(line.text)),
     );
     const steps = lines.slice(1).map((line, index) =>
       Math.max(0, line.top - (lines[index]?.top ?? line.top)));
@@ -491,7 +492,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
       const { line, index } = event;
       const previous = lines[index - 1];
       const gapBefore = previous === undefined ? Number.POSITIVE_INFINITY : line.top - previous.top;
-      const fontHeading = line.fontSize > bodySize * 1.08;
+      const fontHeading = line.fontSize > bodySize * 1.08 && !/[=∫∑√⁰¹²³⁴⁵⁶⁷⁸⁹]/u.test(line.text);
       const boldHeading = line.boldRatio >= 0.78
         && line.text.length <= 180
         && gapBefore >= normalStep * 1.45;
@@ -516,7 +517,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
     }
     flushParagraph();
   }
-  return output.filter((block) => block.kind === "image" || block.text.trim() !== "");
+  return output.filter((block) => block.kind === "image" || block.kind === "table" || block.text.trim() !== "");
 }
 
 export function parsePdfImageInterpretations(value: unknown): readonly PdfImageInterpretation[] {
@@ -616,3 +617,135 @@ export function parsePdfImageInterpretations(value: unknown): readonly PdfImageI
   }
   return output;
 }
+
+/** Geometry evidence is deliberately conservative: uncertain structure remains visible in quality. */
+export function analyzePdfLayout(pages: readonly PdfPageLayout[]): { readonly blocks: readonly PdfLayoutBlock[]; readonly issues: readonly import("./model.js").PdfQualityIssue[] } {
+  const issues: import("./model.js").PdfQualityIssue[] = [];
+  const blocks: PdfLayoutBlock[] = [];
+  const marginLines = new Map(pages.filter(page => page.text.length <= 4000).map(page => [page.page, pageLines(page)]));
+  const margins = repeatedMarginLines(pages, marginLines);
+  for (const originalInput of pages) {
+    const original = { ...originalInput, text: originalInput.text.filter(fragment => !(fragment.top <= originalInput.height * 0.06 || fragment.top + fragment.height >= originalInput.height * 0.94) || !margins.has(normalizedMarginText(fragment.text))) };
+    const warn = (code: import("./model.js").PdfQualityIssue["code"]): void => {
+      if (!issues.some(issue => issue.page === original.page && issue.code === code)) issues.push({ page: original.page, code });
+    };
+    // Bound quadratic geometry analysis independently of the parser's byte limit.
+    if (original.text.length > 4000) {
+      warn("reading-order-uncertain"); blocks.push(...layoutBlocks([original])); continue;
+    }
+    if (original.text.some(fragment => /[∫∑√]/u.test(fragment.text))) warn("math-structure-uncertain");
+    const text = [...original.text].sort((a, b) => a.top - b.top || a.left - b.left);
+    const consumed = new Set<PdfTextFragment>();
+    const replacements = new Map<PdfTextFragment, PdfTextFragment>();
+    const superscripts: Record<string, string> = { "0": "⁰", "1": "¹", "2": "²", "3": "³", "4": "⁴", "5": "⁵", "6": "⁶", "7": "⁷", "8": "⁸", "9": "⁹", "+": "⁺", "-": "⁻", "=": "⁼", "(": "⁽", ")": "⁾", "n": "ⁿ", "i": "ⁱ" };
+    for (const small of text) {
+      const bases = text.filter(base => base !== small && base.fontSize >= small.fontSize * 1.3
+        && small.top < base.top && small.top + small.height > base.top - base.height * 0.25
+        && Math.abs(small.left - (base.left + base.width)) < base.fontSize * 0.6);
+      if (bases.length === 0) continue;
+      const base = bases[0]!;
+      const glyphs = [...small.text.trim()];
+      if (bases.length === 1 && glyphs.length > 0 && glyphs.length <= 8 && glyphs.every(glyph => superscripts[glyph] !== undefined) && !replacements.has(base)) {
+        replacements.set(base, { ...base, text: base.text + glyphs.map(glyph => superscripts[glyph]).join(""), width: small.left + small.width - base.left });
+        consumed.add(small);
+      } else warn("math-structure-uncertain");
+    }
+    const fragments = text.filter(fragment => !consumed.has(fragment)).map(fragment => replacements.get(fragment) ?? fragment);
+    const page: PdfPageLayout = { ...original, text: fragments };
+    const rows: PdfTextFragment[][] = [];
+    for (const fragment of fragments) {
+      const row = rows.at(-1);
+      if (row === undefined || Math.abs(fragment.top - row[0]!.top) > Math.max(2, fragment.height * 0.2)) rows.push([fragment]);
+      else row.push(fragment);
+    }
+    const cellRows = rows.map(row => {
+      const groups: PdfTextFragment[][] = [];
+      for (const fragment of [...row].sort((a, b) => a.left - b.left)) {
+        const prior = groups.at(-1), last = prior?.at(-1);
+        if (last === undefined || fragment.left - (last.left + last.width) > Math.max(12, fragment.fontSize * 1.5)) groups.push([fragment]);
+        else prior!.push(fragment);
+      }
+      return groups;
+    });
+    const tables: Array<{ top: number; bottom: number; block: PdfLayoutBlock; fragments: PdfTextFragment[] }> = [];
+    for (let index = 0; index < cellRows.length; index++) {
+      const first = cellRows[index]!;
+      if (first.length < 2 || first.length > 12) continue;
+      const group = [first];
+      let next = index + 1;
+      for (; next < cellRows.length; next++) {
+        const candidate = cellRows[next]!;
+        if (candidate.length !== first.length || candidate.some((cell, column) => Math.abs(cell[0]!.left - first[column]![0]!.left) > 4)) break;
+        if (candidate[0]![0]!.top - group.at(-1)![0]![0]!.top > Math.max(40, candidate[0]![0]!.height * 3)) break;
+        group.push(candidate);
+      }
+      const cells = group.map(row => row.map(cell => joinFragments(cell)));
+      const header = first.every(cell => cell.every(fragment => fragment.bold));
+      const numeric = cells.slice(1).some(row => row.slice(1).some(cell => /^[-+\d$€£]/u.test(cell.trim())));
+      const compact = cells.every(row => row.every(cell => cell.length <= 100));
+      if (group.length >= 3 && compact && header && numeric) {
+        const members = group.flat(2);
+        tables.push({ top: Math.min(...members.map(fragment => fragment.top)), bottom: Math.max(...members.map(fragment => fragment.top + fragment.height)), block: { kind: "table", page: page.page, rows: cells }, fragments: members });
+        index = next - 1;
+      } else if (group.length >= 3 && first.length >= 3) warn("table-structure-uncertain");
+    }
+    const tableFragments = new Set(tables.flatMap(table => table.fragments));
+    const remaining = fragments.filter(fragment => !tableFragments.has(fragment));
+    const emitBand = (band: readonly PdfTextFragment[], images: readonly PdfImageCandidate[]): void => {
+      if (band.length === 0 && images.length === 0) return;
+      // Repeated gutters are detected before line grouping can join adjacent columns.
+      const candidates = new Set<number>();
+      for (const row of cellRows) {
+        for (let i = 1; i < row.length; i++) {
+          const left = row[i - 1]!.at(-1)!, right = row[i]![0]!;
+          const gap = right.left - (left.left + left.width);
+          if (gap >= Math.max(page.width * 0.025, left.fontSize * 1.5)) candidates.add(Math.round((left.left + left.width + right.left) / 2));
+        }
+      }
+      const valid = [...candidates].filter(gutter => {
+        const left = band.filter(fragment => fragment.left + fragment.width <= gutter);
+        const right = band.filter(fragment => fragment.left >= gutter);
+        if (left.length + right.length !== band.length || left.length < 3 || right.length < 3) return false;
+        if (left.filter(fragment => fragment.width > page.width * 0.18).length < 2 || right.filter(fragment => fragment.width > page.width * 0.18).length < 2) return false;
+        const overlap = Math.min(Math.max(...left.map(fragment => fragment.top)), Math.max(...right.map(fragment => fragment.top))) - Math.max(Math.min(...left.map(fragment => fragment.top)), Math.min(...right.map(fragment => fragment.top)));
+        return overlap > Math.max(...band.map(fragment => fragment.height)) * 1.5;
+      });
+      if (valid.length > 0) {
+        const gutter = valid[Math.floor(valid.length / 2)]!;
+        if (images.some(image => image.left < gutter && image.left + image.width > gutter)) {
+          warn("reading-order-uncertain"); blocks.push(...layoutBlocks([{ ...page, text: band, images }])); return;
+        }
+        for (const left of [true, false]) blocks.push(...layoutBlocks([{ ...page, text: band.filter(fragment => left ? fragment.left + fragment.width <= gutter : fragment.left >= gutter), images: images.filter(image => left ? image.left + image.width <= gutter : image.left >= gutter) }]));
+      } else {
+        if (band.length >= 6 && cellRows.filter(row => row.length >= 2 && row.some(cell => band.includes(cell[0]!))).length >= 3) warn("reading-order-uncertain");
+        blocks.push(...layoutBlocks([{ ...page, text: band, images }]));
+      }
+    };
+    // Spanning headings split vertical regions; tables retain their exact place.
+    const bodyFont = weightedBodyFontSize(pageLines(page));
+    const gutterVotes = new Map<number, number>();
+    for (const row of cellRows) for (let i = 1; i < row.length; i++) {
+      const left = row[i - 1]!.at(-1)!, right = row[i]![0]!;
+      if (right.left - (left.left + left.width) < Math.max(12, left.fontSize * 1.5)) continue;
+      const gutter = Math.round((left.left + left.width + right.left) / 20) * 10;
+      gutterVotes.set(gutter, (gutterVotes.get(gutter) ?? 0) + 1);
+    }
+    const repeatedGutters = [...gutterVotes].filter(([, votes]) => votes >= 3).map(([gutter]) => gutter);
+    const spans = remaining.filter(fragment => fragment.width > page.width * 0.65 || (fragment.fontSize > bodyFont * 1.08 && repeatedGutters.some(gutter => fragment.left < gutter && fragment.left + fragment.width > gutter)));
+    const boundaries = [...tables.map(table => ({ top: table.top, bottom: table.bottom, table, span: null as PdfTextFragment | null })), ...spans.map(span => ({ top: span.top, bottom: span.top + span.height, table: null, span }))].sort((a, b) => a.top - b.top);
+    const emitted = new Set<PdfTextFragment>(), emittedImages = new Set<PdfImageCandidate>();
+    for (const boundary of boundaries) {
+      const band = remaining.filter(fragment => !emitted.has(fragment) && fragment !== boundary.span && fragment.top < boundary.top);
+      const images = page.images.filter(image => !emittedImages.has(image) && image.top < boundary.top);
+      emitBand(band, images); for (const fragment of band) emitted.add(fragment); for (const image of images) emittedImages.add(image);
+      if (boundary.table !== null) blocks.push(boundary.table.block);
+      if (boundary.span !== null) {
+        const span = boundary.span;
+        blocks.push(span.fontSize > bodyFont * 1.08 ? { kind: "heading", page: page.page, level: 2, text: span.text } : { kind: "paragraph", page: page.page, text: span.text });
+        emitted.add(span);
+      }
+    }
+    emitBand(remaining.filter(fragment => !emitted.has(fragment)), page.images.filter(image => !emittedImages.has(image)));
+  }
+  return { blocks, issues };
+}
diff --git a/src/pdf/markdown.ts b/src/pdf/markdown.ts
index 751df07b..61664aa3 100644
--- a/src/pdf/markdown.ts
+++ b/src/pdf/markdown.ts
@@ -24,7 +24,7 @@ export type ResolvedPdfImage = {
 function escapeInline(value: string): string {
   return sanitizeTerminalText(value)
     .replace(/\\/gu, "\\\\")
-    .replace(/([`*_[\]{}<>#])/gu, "\\$1")
+    .replace(/([`*_[\]{}<>#|])/gu, "\\$1")
     .replace(/\s+/gu, " ")
     .trim();
 }
@@ -81,6 +81,12 @@ function markdownContent(
       lines.push(imageMarkdown(resolved), "");
       continue;
     }
+    if (block.kind === "table") {
+      textBlockCount += 1;
+      const rows = block.rows.map(row => `| ${row.map(cell => escapeInline(cell)).join(" | ")} |`);
+      if (rows.length > 0) lines.push(rows[0]!, `| ${block.rows[0]!.map(() => "---").join(" | ")} |`, ...rows.slice(1), "");
+      continue;
+    }
     if (block.kind === "heading") {
       headingCount += 1;
       lines.push(`${"#".repeat(Math.max(2, Math.min(6, block.level)))} ${escapeInline(block.text)}`, "");
diff --git a/src/pdf/model.ts b/src/pdf/model.ts
index 380520be..be51df94 100644
--- a/src/pdf/model.ts
+++ b/src/pdf/model.ts
@@ -126,7 +126,14 @@ export type PdfManifestImage = PdfBounds & {
   readonly metadata: PdfImageSemanticMetadata | null;
 };
 
+export type PdfQualityIssue = {
+  readonly code: "reading-order-uncertain" | "table-structure-uncertain" | "math-structure-uncertain" | "ocr-needed";
+  readonly page: number;
+};
+
 export type PdfCaptureManifest = {
+  readonly markdown?: { readonly path: string; readonly bytes: number; readonly sha256: string };
+  readonly quality?: { readonly schemaVersion: 1; readonly issues: readonly PdfQualityIssue[] };
   readonly schemaVersion: typeof PDF_CAPTURE_MANIFEST_SCHEMA_VERSION;
   readonly kind: "pdf";
   readonly capturedAt: string;
@@ -204,6 +211,8 @@ export type PdfCaptureOutcome = {
 };
 
 export type PdfToolCommand = {
+  /** An external supervisor may own the inherited group and its final cleanup. */
+  readonly processGroup?: "new" | "inherit";
   readonly command: readonly string[];
   readonly timeoutMs: number;
   readonly maxOutputBytes: number;
diff --git a/src/pdf/persist.ts b/src/pdf/persist.ts
index c40839e8..4b3b1058 100644
--- a/src/pdf/persist.ts
+++ b/src/pdf/persist.ts
@@ -212,9 +212,15 @@ export function persistPdfCapture(input: PersistPdfCaptureInput): string {
       chmodSync(destination, 0o644);
     }
 
+    const markdownBytes = `${redactSensitiveText(input.markdown).trimEnd()}\n`;
+    const markdownDescriptor = { path: `${slug}.md`, bytes: Buffer.byteLength(markdownBytes), sha256: createHash("sha256").update(markdownBytes).digest("hex") };
+    if (input.manifest.markdown !== undefined && (input.manifest.markdown.path !== markdownDescriptor.path || input.manifest.markdown.bytes !== markdownDescriptor.bytes || input.manifest.markdown.sha256 !== markdownDescriptor.sha256)) {
+      throw new Error("PDF Markdown does not match its manifest provenance");
+    }
+    const manifest = { ...input.manifest, markdown: markdownDescriptor };
     writeFileSync(
       join(stagingDirectory, `${slug}.md`),
-      `${redactSensitiveText(input.markdown).trimEnd()}\n`,
+      markdownBytes,
       { encoding: "utf8", flag: "wx", mode: 0o644 },
     );
     if (input.manifest.annotations === null) {
@@ -253,7 +259,7 @@ export function persistPdfCapture(input: PersistPdfCaptureInput): string {
     }
     writeFileSync(
       join(stagingDirectory, PDF_CAPTURE_MANIFEST_FILENAME),
-      `${JSON.stringify(input.manifest, null, 2)}\n`,
+      `${JSON.stringify(manifest, null, 2)}\n`,
       { encoding: "utf8", flag: "wx", mode: 0o644 },
     );
     assertStagingTreeSafe(stagingDirectory);
diff --git a/src/pdf/source.ts b/src/pdf/source.ts
index 496537ab..51644ec0 100644
--- a/src/pdf/source.ts
+++ b/src/pdf/source.ts
@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import {
   chmodSync,
   mkdtempSync,
@@ -37,13 +38,13 @@ function parseRemoteUrl(input: string): URL | null {
   try {
     url = new URL(input);
   } catch {
-    throw new Error("PDF URL is invalid");
+    throw new PdfCaptureError("invalid-input", "PDF URL is invalid");
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("PDF URL must use HTTP or HTTPS");
+    throw new PdfCaptureError("invalid-input", "PDF URL must use HTTP or HTTPS");
   }
   if (url.username !== "" || url.password !== "") {
-    throw new Error("PDF URL must not contain embedded credentials");
+    throw new PdfCaptureError("invalid-input", "PDF URL must not contain embedded credentials");
   }
   return url;
 }
@@ -69,7 +70,7 @@ function assertPdfSignature(bytes: Uint8Array): void {
     bytes.byteLength < 5
     || new TextDecoder().decode(bytes.subarray(0, 5)) !== "%PDF-"
   ) {
-    throw new Error("remote PDF input does not have a valid PDF signature");
+    throw new PdfCaptureError("invalid-input", "remote PDF input does not have a valid PDF signature");
   }
 }
 
diff --git a/src/pdf/tools.ts b/src/pdf/tools.ts
index 9af1f7c6..6f4901ad 100644
--- a/src/pdf/tools.ts
+++ b/src/pdf/tools.ts
@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
@@ -26,7 +27,7 @@ async function readBoundedStream(stream: NodeJS.ReadableStream, maxBytes: number
     if (typeof value === "string") chunk = new TextEncoder().encode(value);
     else if (value instanceof Uint8Array) chunk = value;
     else throw new Error("PDF tool returned an unsupported output chunk");
-    if (!bytes.append(chunk)) throw new Error(`PDF tool output exceeded ${maxBytes} bytes`);
+    if (!bytes.append(chunk)) throw new PdfCaptureError("limit-exceeded", `PDF tool output exceeded ${maxBytes} bytes`);
   }
   return new TextDecoder().decode(bytes.toUint8Array());
 }
@@ -37,7 +38,8 @@ export const runPdfToolCommand: PdfToolRunner = async (
 ): Promise<PdfToolCommandResult> => {
   const executable = specification.command[0];
   if (executable === undefined) throw new Error("PDF tool command is empty");
-  const useProcessGroup = process.platform !== "win32";
+  if (specification.processGroup !== undefined && !["new", "inherit"].includes(specification.processGroup)) throw new PdfCaptureError("invalid-input", "Invalid PDF process group policy");
+  const useProcessGroup = process.platform !== "win32" && specification.processGroup !== "inherit";
   const child = spawn(executable, specification.command.slice(1), {
     cwd: specification.cwd,
     detached: useProcessGroup,
@@ -51,7 +53,7 @@ export const runPdfToolCommand: PdfToolRunner = async (
     windowsHide: true,
   });
   const exited = new Promise<number>((resolveExit, rejectExit) => {
-    child.once("error", rejectExit);
+    child.once("error", (error: NodeJS.ErrnoException) => rejectExit(error.code === "ENOENT" ? new PdfCaptureError("tool-unavailable", "PDF tool executable is unavailable", { cause: error }) : error));
     child.once("close", (code) => resolveExit(code ?? 1));
   });
   const signalProcessTree = (signal: NodeJS.Signals): void => {
@@ -79,7 +81,7 @@ export const runPdfToolCommand: PdfToolRunner = async (
     forceKillTimer = setTimeout(() => signalProcessTree("SIGKILL"), 1_000);
   };
   const timer = setTimeout(() => {
-    requestStop(new Error(`PDF tool timed out after ${specification.timeoutMs}ms`));
+    requestStop(new PdfCaptureError("timeout", `PDF tool timed out after ${specification.timeoutMs}ms`));
   }, specification.timeoutMs);
 
   try {
@@ -137,10 +139,10 @@ export function resolvePdfTools(dependencies: PdfCaptureDependencies = {}): PdfT
     ? discoverExecutable("tesseract", dependencies)
     : dependencies.tools.tesseract;
   if (pdfinfo === null) {
-    throw new Error("pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
   }
   if (pdftohtml === null) {
-    throw new Error("pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
   }
   return { pdfinfo, pdftohtml, tesseract };
 }