@hraness/kb 0.17.1

package/package.json

@@ -0,0 +1,409 @@
+{
+  "name": "@hraness/kb",
+  "version": "0.17.1",
+  "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
+  "license": "MIT",
+  "contentPolicy": {
+    "class": "dual-use"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./src/agent-context.ts",
+    "./src/agent-guide-audit.ts",
+    "./src/attachments.ts",
+    "./src/authoring.ts",
+    "./src/benchmark.ts",
+    "./src/capture.ts",
+    "./src/cli.ts",
+    "./src/clip/acquire.ts",
+    "./src/clip/args.ts",
+    "./src/clip/bounded-byte-buffer.ts",
+    "./src/clip/browser-profiles.ts",
+    "./src/clip/bundle-reader.ts",
+    "./src/clip/cli.ts",
+    "./src/clip/cookies.ts",
+    "./src/clip/defuddle-worker.ts",
+    "./src/clip/doctor.ts",
+    "./src/clip/jobs.ts",
+    "./src/clip/network-proxy.ts",
+    "./src/clip/network.ts",
+    "./src/clip/persist.ts",
+    "./src/clip/refresh.ts",
+    "./src/clip/terminal.ts",
+    "./src/evaluation-builder.ts",
+    "./src/evaluation-kb.ts",
+    "./src/evaluation.ts",
+    "./src/git.ts",
+    "./src/graph.ts",
+    "./src/index.ts",
+    "./src/navigation.ts",
+    "./src/pdf.ts",
+    "./src/percolate.ts",
+    "./src/portfolio.ts",
+    "./src/portfolio-audit.ts",
+    "./src/portfolio-identity.ts",
+    "./src/portfolio-registry.ts",
+    "./src/query.ts",
+    "./src/repository-memory.ts",
+    "./src/sdk.ts",
+    "./src/search.ts",
+    "./src/search-rules.ts",
+    "./src/semantic.ts",
+    "./src/source-inbox.ts",
+    "./src/untrusted-content.ts",
+    "./src/url-intelligence.ts",
+    "./src/workflow.ts",
+    "./src/workflows/decision-context.ts",
+    "./src/workflows/explain-change.ts",
+    "./src/workflows/index.ts",
+    "./src/workflows/plan-radar.ts"
+  ],
+  "packageManager": "bun@1.3.14",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hraness/kb.git"
+  },
+  "homepage": "https://hraness.com/kb",
+  "bugs": {
+    "url": "https://github.com/hraness/kb/issues"
+  },
+  "keywords": [
+    "knowledge-base",
+    "markdown",
+    "obsidian",
+    "web-clipper",
+    "backlinks",
+    "knowledge-graph",
+    "semantic-search",
+    "agent-memory",
+    "agents-md",
+    "context-engineering",
+    "local-first"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./agent-context": {
+      "types": "./src/agent-context.ts",
+      "import": "./dist/agent-context.js"
+    },
+    "./agent-guide-audit": {
+      "types": "./src/agent-guide-audit.ts",
+      "import": "./dist/agent-guide-audit.js"
+    },
+    "./attachments": {
+      "types": "./src/attachments.ts",
+      "import": "./dist/attachments.js"
+    },
+    "./authoring": {
+      "types": "./src/authoring.ts",
+      "import": "./dist/authoring.js"
+    },
+    "./benchmark": {
+      "types": "./src/benchmark.ts",
+      "import": "./dist/benchmark.js"
+    },
+    "./browser-profiles": {
+      "types": "./src/clip/browser-profiles.ts",
+      "import": "./dist/clip/browser-profiles.js"
+    },
+    "./capture": {
+      "types": "./src/capture.ts",
+      "import": "./dist/capture.js"
+    },
+    "./cli": {
+      "types": "./src/cli.ts",
+      "import": "./dist/cli.js"
+    },
+    "./clip/acquire": {
+      "types": "./src/clip/acquire.ts",
+      "import": "./dist/clip/acquire.js"
+    },
+    "./clip/args": {
+      "types": "./src/clip/args.ts",
+      "import": "./dist/clip/args.js"
+    },
+    "./clip/bounded-byte-buffer": {
+      "types": "./src/clip/bounded-byte-buffer.ts",
+      "import": "./dist/clip/bounded-byte-buffer.js"
+    },
+    "./clip/bundle-reader": {
+      "types": "./src/clip/bundle-reader.ts",
+      "import": "./dist/clip/bundle-reader.js"
+    },
+    "./clip/cli": {
+      "types": "./src/clip/cli.ts",
+      "import": "./dist/clip/cli.js"
+    },
+    "./clip/cookies": {
+      "types": "./src/clip/cookies.ts",
+      "import": "./dist/clip/cookies.js"
+    },
+    "./clip/doctor": {
+      "types": "./src/clip/doctor.ts",
+      "import": "./dist/clip/doctor.js"
+    },
+    "./clip/jobs": {
+      "types": "./src/clip/jobs.ts",
+      "import": "./dist/clip/jobs.js"
+    },
+    "./clip/network": {
+      "types": "./src/clip/network.ts",
+      "import": "./dist/clip/network.js"
+    },
+    "./clip/network-proxy": {
+      "types": "./src/clip/network-proxy.ts",
+      "import": "./dist/clip/network-proxy.js"
+    },
+    "./clip/persist": {
+      "types": "./src/clip/persist.ts",
+      "import": "./dist/clip/persist.js"
+    },
+    "./clip/refresh": {
+      "types": "./src/clip/refresh.ts",
+      "import": "./dist/clip/refresh.js"
+    },
+    "./clip/terminal": {
+      "types": "./src/clip/terminal.ts",
+      "import": "./dist/clip/terminal.js"
+    },
+    "./evaluation": {
+      "types": "./src/evaluation.ts",
+      "import": "./dist/evaluation.js"
+    },
+    "./evaluation-builder": {
+      "types": "./src/evaluation-builder.ts",
+      "import": "./dist/evaluation-builder.js"
+    },
+    "./evaluation-kb": {
+      "types": "./src/evaluation-kb.ts",
+      "import": "./dist/evaluation-kb.js"
+    },
+    "./git": {
+      "types": "./src/git.ts",
+      "import": "./dist/git.js"
+    },
+    "./graph": {
+      "types": "./src/graph.ts",
+      "import": "./dist/graph.js"
+    },
+    "./navigation": {
+      "types": "./src/navigation.ts",
+      "import": "./dist/navigation.js"
+    },
+    "./pdf": {
+      "types": "./src/pdf.ts",
+      "import": "./dist/pdf.js"
+    },
+    "./percolate": {
+      "types": "./src/percolate.ts",
+      "import": "./dist/percolate.js"
+    },
+    "./portfolio": {
+      "types": "./src/portfolio.ts",
+      "import": "./dist/portfolio.js"
+    },
+    "./query": {
+      "types": "./src/query.ts",
+      "import": "./dist/query.js"
+    },
+    "./repository-memory": {
+      "types": "./src/repository-memory.ts",
+      "import": "./dist/repository-memory.js"
+    },
+    "./sdk": {
+      "types": "./src/sdk.ts",
+      "import": "./dist/sdk.js"
+    },
+    "./search": {
+      "types": "./src/search.ts",
+      "import": "./dist/search.js"
+    },
+    "./search-rules": {
+      "types": "./src/search-rules.ts",
+      "import": "./dist/search-rules.js"
+    },
+    "./semantic": {
+      "types": "./src/semantic.ts",
+      "import": "./dist/semantic.js"
+    },
+    "./source-inbox": {
+      "types": "./src/source-inbox.ts",
+      "import": "./dist/source-inbox.js"
+    },
+    "./untrusted-content": {
+      "types": "./src/untrusted-content.ts",
+      "import": "./dist/untrusted-content.js"
+    },
+    "./url-intelligence": {
+      "types": "./src/url-intelligence.ts",
+      "import": "./dist/url-intelligence.js"
+    },
+    "./workflow": {
+      "types": "./src/workflow.ts",
+      "import": "./dist/workflow.js"
+    },
+    "./workflows": {
+      "types": "./src/workflows/index.ts",
+      "import": "./dist/workflows/index.js"
+    },
+    "./workflows/decision-context": {
+      "types": "./src/workflows/decision-context.ts",
+      "import": "./dist/workflows/decision-context.js"
+    },
+    "./workflows/explain-change": {
+      "types": "./src/workflows/explain-change.ts",
+      "import": "./dist/workflows/explain-change.js"
+    },
+    "./workflows/plan-radar": {
+      "types": "./src/workflows/plan-radar.ts",
+      "import": "./dist/workflows/plan-radar.js"
+    }
+  },
+  "bin": {
+    "kb": "./dist/cli.js",
+    "kb-evaluation-builder": "./dist/evaluation-builder.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "dist",
+    "src/agent-context.ts",
+    "src/agent-guide-audit.ts",
+    "src/authoring.ts",
+    "src/attachments.ts",
+    "src/benchmark.ts",
+    "src/capture.ts",
+    "src/url-intelligence.ts",
+    "src/cli.ts",
+    "src/clip/acquire.ts",
+    "src/clip/archive-today.ts",
+    "src/clip/args.ts",
+    "src/clip/assets.ts",
+    "src/clip/bounded-byte-buffer.ts",
+    "src/clip/browser-profiles.ts",
+    "src/clip/bundle-reader.ts",
+    "src/clip/capture.ts",
+    "src/clip/cli.ts",
+    "src/clip/cookies.ts",
+    "src/clip/doctor.ts",
+    "src/clip/jobs.ts",
+    "src/clip/extract.ts",
+    "src/clip/lib.ts",
+    "src/clip/media.ts",
+    "src/clip/network-proxy.ts",
+    "src/clip/network.ts",
+    "src/clip/package-root.ts",
+    "src/clip/persist.ts",
+    "src/clip/refresh.ts",
+    "src/clip/platforms.ts",
+    "src/clip/structured.ts",
+    "src/clip/terminal.ts",
+    "src/clip/metadata-search.ts",
+    "src/clip/url-intelligence.ts",
+    "src/clip/url-metadata.ts",
+    "src/clip/url-metadata-backfill.ts",
+    "src/clip/url-metadata-cli.ts",
+    "src/clip/metadata-search-tool/Cargo.toml",
+    "src/clip/metadata-search-tool/Cargo.lock",
+    "src/clip/metadata-search-tool/runner.ts",
+    "src/clip/metadata-search-tool/src/main.rs",
+    "src/git.ts",
+    "src/evaluation-analysis-v2.ts",
+    "src/evaluation-builder.ts",
+    "src/evaluation-corpus-authoring.ts",
+    "src/evaluation-evidence.ts",
+    "src/evaluation-execution-v2.ts",
+    "src/evaluation-implementation.ts",
+    "src/evaluation-kb-closure.ts",
+    "src/evaluation-kb-runner-v2.ts",
+    "src/evaluation-kb-v2.ts",
+    "src/evaluation-redaction.ts",
+    "src/evaluation-kb.ts",
+    "src/evaluation-measurement-v2.ts",
+    "src/evaluation-packing-v2.ts",
+    "src/evaluation-v2.ts",
+    "src/evaluation.ts",
+    "src/graph.ts",
+    "src/index.ts",
+    "src/init.ts",
+    "src/navigation.ts",
+    "src/note-lock.ts",
+    "src/percolate.ts",
+    "src/portfolio.ts",
+    "src/portfolio-audit.ts",
+    "src/portfolio-identity.ts",
+    "src/portfolio-registry.ts",
+    "src/pdf.ts",
+    "src/pdf/args.ts",
+    "src/pdf/capture.ts",
+    "src/pdf/cli.ts",
+    "src/pdf/extract.ts",
+    "src/pdf/layout.ts",
+    "src/pdf/markdown.ts",
+    "src/pdf/model.ts",
+    "src/pdf/ocr.ts",
+    "src/pdf/persist.ts",
+    "src/pdf/source.ts",
+    "src/pdf/tools.ts",
+    "src/query.ts",
+    "src/repository-memory.ts",
+    "src/search.ts",
+    "src/search-rules.ts",
+    "src/semantic-runtime.ts",
+    "src/semantic.ts",
+    "src/sdk.ts",
+    "src/source-inbox.ts",
+    "src/untrusted-content.ts",
+    "src/vault.ts",
+    "src/workflow.ts",
+    "src/workflows/decision-context.ts",
+    "src/workflows/explain-change.ts",
+    "src/workflows/index.ts",
+    "src/workflows/plan-radar.ts",
+    "skills/kb",
+    "README.md",
+    "DISCLOSURE",
+    "LICENSE"
+  ],
+  "scripts": {
+    "kb:refresh": "bunx --bun github:hraness/kb#v0.15.1 refresh --root kb",
+    "kb:check:lane": "bunx --bun github:hraness/kb#v0.15.1 check --root kb --no-catalog",
+    "kb:check": "bunx --bun github:hraness/kb#v0.15.1 check --root kb && bunx --bun github:hraness/kb#v0.15.1 agents check --root kb --repo .",
+    "kb:catalog": "bunx --bun github:hraness/kb#v0.15.1 catalog --root kb",
+    "build": "bun -e 'await (await import(\"node:fs/promises\")).rm(\"./dist\", { recursive: true, force: true })' && bun build ./src/index.ts ./src/agent-context.ts ./src/agent-guide-audit.ts ./src/attachments.ts ./src/authoring.ts ./src/benchmark.ts ./src/clip/browser-profiles.ts ./src/capture.ts ./src/cli.ts ./src/clip/acquire.ts ./src/clip/args.ts ./src/clip/bounded-byte-buffer.ts ./src/clip/bundle-reader.ts ./src/clip/cli.ts ./src/clip/cookies.ts ./src/clip/doctor.ts ./src/clip/jobs.ts ./src/clip/network.ts ./src/clip/network-proxy.ts ./src/clip/persist.ts ./src/clip/refresh.ts ./src/clip/terminal.ts ./src/evaluation.ts ./src/evaluation-builder.ts ./src/evaluation-kb.ts ./src/git.ts ./src/graph.ts ./src/navigation.ts ./src/pdf.ts ./src/percolate.ts ./src/portfolio.ts ./src/query.ts ./src/repository-memory.ts ./src/sdk.ts ./src/search.ts ./src/search-rules.ts ./src/semantic.ts ./src/source-inbox.ts ./src/untrusted-content.ts ./src/url-intelligence.ts ./src/workflow.ts ./src/workflows/index.ts ./src/workflows/decision-context.ts ./src/workflows/explain-change.ts ./src/workflows/plan-radar.ts ./src/clip/defuddle-worker.ts --outdir ./dist --root ./src --target bun --format esm --splitting --packages external",
+    "check:workflows": "bun ./scripts/check-workflow-yaml.ts",
+    "check:installed-command-docs": "bun ./scripts/check-installed-command-docs.ts",
+    "check:portfolio-inventory": "bun ./scripts/check-portfolio-inventory.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src ./scripts",
+    "url-metadata:backfill": "bun ./dist/cli.js url-metadata backfill",
+    "url-metadata:tool:build": "bun ./dist/cli.js url-metadata tool build",
+    "url-metadata:tool:check": "bun ./dist/cli.js url-metadata tool check",
+    "test:package": "bun run ./scripts/package-smoke.ts",
+    "check": "bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
+    "prepack": "bun run check"
+  },
+  "dependencies": {
+    "@steipete/sweet-cookie": "github:hraness/sweet-cookie#v0.4.2",
+    "@tobilu/qmd": "git+https://github.com/hraness/qmd.git#aa993dceb3ef8cfb71d470554ca437570f5a2b3c",
+    "agent-browser": "0.32.3",
+    "defuddle": "0.19.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "fast-check": "^4.8.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/skills/kb/AGENTS.md

@@ -0,0 +1,19 @@
+# Contents
+
+- `SKILL.md` – public entrypoint, runtime contract, and intent router for all hraness/kb agent workflows.
+- `references/query.md` – scoped retrieval through exact metadata, hybrid search, graph structure, and Git provenance.
+- `references/save-url.md`, `url-authentication.md`, and `url-platforms.md` – auditable web capture, signed-in source handling, and platform-specific completeness boundaries.
+- `references/save-pdf.md` and `pdf-review.md` – PDF ingestion, OCR, image evidence, and mixed-media review.
+- `references/plan.md` and `plan-structure.md` – durable plan authoring and its adaptable Markdown contract.
+- `references/percolate.md` and `refresh.md` – evidence-backed graph edits, catalog maintenance, and vault validation.
+- `agents/openai.yaml` – user-facing skill metadata and invocation prompt.
+
+# Guidelines
+
+- Keep `kb` as the only public skill entrypoint. Preserve substantial workflows as focused references and keep the router compact enough to load by default.
+- Keep discovery language grounded in real user requests for knowledge bases, coding-agent memory, Markdown or Obsidian vaults, source capture, repository context, plans, and knowledge graphs. Exclude generic research, PDF reading, and planning outside hraness/kb.
+- Invoke the installed `kb` CLI without depending on a source checkout. Check for an existing command first, require Bun when installation is needed, and pin installation to the current immutable repository tag.
+- Never initialize or mutate a vault as part of skill or CLI installation.
+- Keep Markdown authoritative. Preserve incomplete source boundaries, read cited evidence before graph edits, and never generate reciprocal, inferred, transitive, or similarity-derived relationships.
+- In parallel managed-catalog work, defer refresh to the integrating agent and use the catalog-skipping check in each edit lane. Authored-catalog refreshes leave the front door unchanged.
+- Update `agents/openai.yaml`, README installation text, package inventory checks, and the pinned CLI tag together when the skill identity or package release changes.

package/skills/kb/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: kb
+description: >-
+  Operate a hraness/kb local-first Markdown knowledge base for coding-agent
+  memory. Use when a user asks to search or query a KB or Obsidian vault; load
+  repository context, plans, decisions, concepts, backlinks, semantic search,
+  or Git provenance; save, clip, scrape, or archive a URL, article, social
+  thread, signed-in browser page, or PDF as auditable Markdown; create or
+  update a durable plan in the vault; or refresh, check, percolate, and
+  maintain its knowledge graph. Do not use for generic web research, generic
+  PDF reading, or ordinary planning that will not use a hraness/kb vault.
+---
+
+# Work with KB
+
+Use hraness/kb to preserve and retrieve inspectable agent memory in Markdown
+and Git. Select the smallest workflow that matches the request, then load only
+its references.
+
+## Prepare the runtime
+
+Use an existing `kb` command when one is available. Do not reinstall or upgrade
+it merely because this skill loaded.
+
+If `kb` is missing, check for Bun. Bun is the required runtime. When Bun is
+also missing, install it with the official instructions at
+<https://bun.sh/docs/installation> under the environment's normal approval
+rules, then repeat command discovery. Install KB only while `kb` remains
+missing:
+
+```sh
+command -v kb >/dev/null 2>&1 || {
+  command -v bun >/dev/null 2>&1 || exit 1
+  bun add --global @hraness/kb@0.17.1
+}
+kb --help
+```
+
+The exact npm version is the immutable release owned by this skill. Do not
+replace it with `latest`, a branch, or an unpinned package source. Both installed
+commands require Bun `1.3.14` or newer in `PATH`. Run `kb doctor` when the
+chosen workflow may need browser capture, media tools, PDF extraction, OCR, or
+local semantic search.
+
+Installation ends after command verification. Never run `kb init`, create a
+vault, refresh a catalog, or edit Markdown as an installation side effect.
+Initialize or mutate a vault only when the user's request requires that change.
+
+## Route the request
+
+| User intent | Read |
+| --- | --- |
+| Find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
+| Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
+| Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |
+| Review recurring ideas, promote concepts, or add and verify typed relationships | [Percolate concepts and relationships](references/percolate.md) |
+| Refresh or validate the catalog, graph, attachments, repository scopes, context mappings, or overall vault health | [Refresh and check the knowledge base](references/refresh.md) |
+
+Read more than one primary reference only when the request spans those
+workflows. For example, saving a source and linking it from a maintained note
+uses the capture workflow followed by the relevant percolation and refresh
+steps.
+
+## Preserve the KB contract
+
+- Resolve `KB_ROOT` to the existing vault directory that contains its managed
+  or authored `index.md`. Read the applicable repository and vault
+  `AGENTS.md` files before writing. Do not assume the session started in the
+  vault.
+- Treat authored Markdown and Git as the record. Catalogs, backlinks, graph
+  reports, search indexes, embeddings, and percolation candidates are derived
+  views.
+- Open cited notes and source records before turning search results, tags,
+  mentions, or similarity into a conclusion. Author only relationships that
+  the source note's prose and evidence support.
+- Keep source capture separate from synthesis. Preserve access, pagination,
+  extraction, OCR, and configured-limit failures instead of upgrading partial
+  evidence to complete.
+- Follow the selected reference's final checks. In a managed-catalog vault,
+  parallel edit lanes use `kb check --root "$KB_ROOT" --no-catalog`; the
+  integrating agent performs one refresh and normal check.

package/skills/kb/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "KB"
+  short_description: "Query, capture, plan, and maintain Markdown memory"
+  default_prompt: "Use $kb to work with this hraness/kb knowledge base and load only the workflow references needed for the request."

package/skills/kb/references/pdf-review.md

@@ -0,0 +1,51 @@
+# Review PDF image-derived text
+
+Read this guide when a PDF contains screenshots, scans, or mixed text and
+visual media.
+
+## Keep the source inspectable
+
+- Retain every extracted image in `assets/`.
+- Embed primarily visual images.
+- Keep a source-image link beside OCR-derived or manually corrected text.
+- Preserve page number, image index, bounding box, extraction method, and
+  confidence in `capture.json`.
+- Never replace a mixed image with text alone. Screenshots can contain a
+  message, chart, photograph, code sample, or UI state at the same time.
+- The renderer embeds the source image and adds its metadata and “Text visible
+  in…” heading. Annotation `markdown` should contain only the transcription.
+
+## Structure conversations
+
+When the surface is recognizable, use available metadata rather than flattening
+the screenshot into one paragraph:
+
+```markdown
+> bg @ Oct 15, 2024 at 4:26 PM
+> Substrate did look very well designed and ambitious from the outside...
+```
+
+Use the platform's visible display name. Include channel, thread, or reply
+context only when the screenshot shows it. Split a multi-message screenshot
+into distinct message blocks, including each visible message author and
+timestamp in that message's Markdown header. Annotation metadata describes
+shared or whole-image context: use its scalar `author` or `timestamp` only when
+one value accurately characterizes the image, and use `participants` for
+multiple visible authors. The generated image embed is the shared source-image
+reference.
+
+Do not invent missing authors, dates, channels, or thread relationships. Mark
+uncertain OCR as `[unclear]`; do not silently turn a plausible guess into source
+text.
+
+## Distinguish image roles
+
+- `text`: a scan or crop is adequately represented by its prose, code, table,
+  or labels, although the source asset is still retained.
+- `visual`: the image remains meaningful without recognized text.
+- `mixed`: both recognized text and non-text visual or spatial context matter.
+  Use this for most message and application screenshots because avatars,
+  grouping, thread layout, reactions, and UI state can remain evidentiary.
+
+When classification is uncertain, choose `mixed`, keep the image visible, and
+preserve the OCR warning.