@hraness/wordcell 0.21.0 → 0.21.1

package/README.md

@@ -1,7 +1,7 @@
 <!-- hraness:wordcell-landing:start -->
 # Wordcell
 
-[![skills.sh](https://skills.sh/b/hraness/wordcell)](https://skills.sh/hraness/wordcell)
+[![Agent Skill](https://raw.githubusercontent.com/hraness/wordcell/main/assets/agent-skill.svg)](https://github.com/hraness/wordcell/tree/main/skills/wordcell)
 
 A knowledge base for coding agents, built from Markdown, backlinks, semantic
 search, and Git context.
@@ -9,15 +9,50 @@ It turns sources, plans, and decisions into inspectable context that agents can
 recover across sessions without coupling application code to the knowledge
 system.
 
+[Documentation](https://wordcell.io/docs) · [npm package](https://www.npmjs.com/package/@hraness/wordcell) · [Graph guide](https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md) · [Changelog](https://github.com/hraness/wordcell/blob/main/CHANGELOG.md)
+
 ## Install
 
-Bun 1.3.14 or newer is required.
+[Bun 1.3.14 or newer](https://bun.sh/docs/installation) and Git are required.
+The CLI and TypeScript SDK run with Bun. Choose one installation source:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.0/hraness-wordcell-0.21.0.tgz
+# Canonical, versioned GitHub archive
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.1/hraness-wordcell-0.21.1.tgz
 wordcell --help
 ```
 
+The same release is mirrored to [npm](https://www.npmjs.com/package/@hraness/wordcell):
+
+```sh
+npm install --global --ignore-scripts @hraness/wordcell@0.21.1
+wordcell --help
+```
+
+Bun must remain in `PATH` when npm installs the commands. Exact search and
+Markdown graph commands need no account, service, or embedding model. Optional
+semantic search, browser capture, and PDF tools have [additional prerequisites](https://github.com/hraness/wordcell/blob/main/docs/reference.md#review-lifecycle-scripts-before-enabling-optional-adapters).
+
+### Use with a coding agent
+
+Install the single public Agent Skill into your choice of compatible agent,
+including Claude Code, Codex, Cursor, or GitHub Copilot:
+
+```sh
+bunx skills add hraness/wordcell#v0.21.1 --skill wordcell
+```
+
+Then ask:
+
+```text
+Use Wordcell to find the notes and plans about packages/parser in ./kb.
+Open the sources behind the result and explain the recorded decision.
+```
+
+The skill installs instructions, not a running service. It uses an existing
+`wordcell` command and prepares the pinned runtime only when needed. Installing
+it does not create a vault or modify your notes. [Read the skill](https://github.com/hraness/wordcell/blob/main/skills/wordcell/SKILL.md).
+
 ## Keep one decision available to the next session
 
 Suppose a parser must stop retrying after three attempts. Record that constraint
@@ -78,686 +113,124 @@ neither the vault nor a hosted knowledge service.
 
 <!-- hraness:wordcell-landing:end -->
 
-## Links
+## What you can do
 
-[Install Wordcell from GitHub Releases](https://github.com/hraness/wordcell/releases) ·
-[Wordcell source on GitHub](https://github.com/hraness/wordcell) ·
-[Wordcell overview](https://wordcell.io)
-
-## A knowledge base for your coding agents
-
-> Give coding agents durable, searchable memory beside the repository with plain Markdown, Git history, and replaceable local search.
-
-Coding agents lose useful context when a session ends. The next agent can search the code again, but it cannot recover a source that was never saved, a decision that stayed in chat, or the relationship between two notes that nobody recorded. Repeating that work costs time and produces inconsistent answers.
-
-Search alone cannot preserve agent memory. The system also needs a write path into inspectable files under version control: evidence can be captured, current understanding can be revised, plans can accumulate outcomes, and mandatory edit rules can move onto the instruction path. Search indexes, graph views, and embeddings used for meaning-based similarity should remain derived and replaceable.
-
-[hraness/wordcell](<https://wordcell.io>) implements that split as repository-adjacent Markdown and Git. Exact lookup, metadata filters, local search, explicit links, and Git provenance help an agent find and inspect the files without making application code depend on the knowledge system.
+| Task | Command | Evidence and effects |
+| --- | --- | --- |
+| Find a saved decision | `wordcell search "parser retries" --root kb --mode exact` | Reads current Markdown; no model or network request. |
+| Recover context for code | `wordcell context packages/parser/src/index.ts --root kb --repo .` | Returns scoped notes, plans, and inherited `AGENTS.md` rules. |
+| Inspect explicit connections | `wordcell backlinks notes/parser-contract --root kb` | Returns notes that link to the decision. |
+| Search by meaning | `wordcell search "retry policy" --root kb --mode hybrid` | Adds optional local QMD keyword and vector retrieval; model setup is required. |
+| Query with graph proofs | `wordcell graph query --program scope-route --scope packages/parser --root kb` | Returns bounded results tied to the source revision. Queries do not write a cache. |
+| Capture a source | `wordcell clip https://example.com/article --output kb/articles` | Reads the selected URL and writes a Markdown bundle with a capture receipt. |
+| Capture a PDF | `wordcell pdf /absolute/path/to/document.pdf --output kb/articles` | Preserves the original PDF and extracted evidence; Poppler is required. |
+| Check the vault | `wordcell check --root kb` | Reports structural and attachment problems without editing files. |
 
-### The pattern converged across agent tools
+Use `--json` for structured output and `wordcell --help` for the complete command
+surface. [Full command reference](https://github.com/hraness/wordcell/blob/main/docs/reference.md#command-surface).
 
-[Devin's 2024 release history](<https://docs.devin.ai/release-notes/2024>) records Knowledge that could be recalled across future sessions and Repo Knowledge produced by scanning repositories. Its [2025 release history](<https://docs.devin.ai/release-notes/2025>) records DeepWiki in April, codebase intelligence inside Devin in May, and a DeepWiki Model Context Protocol server later that month.
-
-In April 2026, Andrej Karpathy published an [LLM Wiki proposal](<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>) with immutable raw sources, an agent-maintained interlinked Markdown wiki, and an instruction schema. Its operations are ingest, query, and lint, with QMD as an optional search layer when a simple index stops being enough. These systems converged on durable agent-readable knowledge. The sequence does not establish direct lineage between them or hraness/wordcell.
-
-### Separate rules from explanations
-
-A repository needs two kinds of memory. Rules that must govern an edit belong in a scoped `AGENTS.md` file on the path to the code. Rationale, history, examples, evidence, plans, and neighboring decisions belong in a knowledge base that an agent pulls only when the task needs them. This keeps mandatory instructions short without throwing away the context behind them.
-
-A root guide carries repository-wide policy, and nested guides add constraints owned by a package or product. A nearby knowledge note can explain why a parser rejects a tempting shortcut, preserve the source behind the decision, and link the plan that introduced it. If the note and the applicable guide disagree, the guide controls the edit and the note needs repair.
-
-The result has two concrete parts: scoped instruction files govern edits, while an ordinary Markdown vault stores supporting context. Application code imports neither the vault nor its search indexes:
-
-**Repository rules beside durable knowledge**
+## How the files fit together
 
 ```text
 repository/
-├── AGENTS.md                         # inherited root rules
+├── AGENTS.md                # rules that govern edits
 ├── packages/parser/
-│   ├── AGENTS.md                     # scoped rules and checks
-│   └── src/
+│   └── AGENTS.md            # rules scoped to this code
 └── kb/
-    ├── articles/<slug>/              # captured evidence and assets
-    ├── notes/                         # maintained explanations
-    ├── plans/                         # decisions and outcomes
-    └── index.md                       # short authored front door
-```
-
-### Keep the implementation small and the files authoritative
-
-hraness/wordcell packages the pattern as a small file contract. A useful vault can begin with Markdown, Git, `index.md`, and standard file search. Source capture, metadata queries, repository-path context, QMD, typed relationships, graph traversal, and TypeScript sessions are layers to add when the simpler setup stops answering the repository's questions. Application code need not import Wordcell, and no hosted service or graph database owns its records.
-
-Captured sources preserve evidence, notes hold current explanations, and plans retain decisions and outcomes. YAML frontmatter adds queryable metadata without requiring one domain schema for every vault. A code-related record may declare a few exact repository-relative `repository_scopes` so an agent can recover it from the path it is about. The declaration stays in the record instead of a central project database, which lets parallel agents update unrelated memory without sharing a generated file.
-
-The Markdown files are authoritative. The catalog, QMD database, backlink view, path-context view, graph traversal, and bounded Git index are derived and replaceable. A vault can keep a managed catalog or an authored front door and render the complete inventory on demand. Deleting one of those views removes a way to retrieve knowledge, not the knowledge itself.
-
-### Route current memory from the code path
-
-A broad semantic search over years of completed plans can rank a detailed historical record above the short explanation that owns the code today. `wordcell context packages/parser/src/index.ts --root kb --repo .` starts from a stronger signal: the path being changed. It returns the inherited guides that govern the edit, curated scope hubs, and bounded records whose declared scope is that path or one of its ancestors.
-
-The records stay grouped by role. Maintained notes, proposed through blocked plans, dated market research, and generated reports form current memory. Completed, superseded, and cancelled plans remain available in a separate historical group. Every result states the declaration that matched and whether the target currently exists. A plan can therefore describe a future path, while a retired path remains honest historical evidence instead of being silently rewritten after a rename.
-
-**Path context, exact scope filtering, and Git memory**
-
-```shell
-wordcell context packages/parser/src/index.ts --root kb --repo .
-wordcell list --root kb --scope packages/parser --where type=plan --json
-wordcell history search packages/parser/src/index.ts --root kb --repo . --json
-```
-
-### Preserve evidence and plans as working records
-
-Durable reasoning needs inspectable evidence. `wordcell clip` can read a public URL,
-saved HTML, rendered page, a page already open in an authenticated browser, or
-an existing exact Archive.today snapshot after the direct routes fail. Archive
-fallback is read-only and always partial. The
-[capture documentation](docs/capture.md) defines the supported routes. A capture
-writes readable Markdown beside localized assets and `capture.json`, whose
-manifest records where the material came from, how it was extracted, what was
-saved, and any warnings. “Complete” describes the selected page surface, not
-every hidden branch or future version of the site.
-
-**Capture a web source or local PDF**
-
-```shell
-wordcell clip "https://example.com/article" --output articles
-wordcell pdf "/absolute/path/to/document.pdf" --output articles
-```
-
-The resulting bundle is evidence, not final interpretation. A maintained note can cite several captures, record disagreement, and change when later evidence warrants it. The sources stay available for audit. This prevents an agent from silently replacing what a page said with what it now believes the page meant.
-
-The `wordcell` Agent Skill routes vault planning requests to a focused durable-plan workflow. It creates a normal Markdown file under `kb/plans/` with an outcome, status, area, repository scopes, assumptions, dependencies, decisions, and verification method. The file grows during execution as agents record deviations, review findings, and reproducible evidence. Closeout adds a compact result and durable-memory disposition: each reusable conclusion links to the maintained note, guide, code contract, or runbook that now owns it, or says that no promotion was needed. Completed plans remain in Git as the history of the work. When a finding becomes a rule whose omission would make a future edit wrong, move that rule into the applicable `AGENTS.md` and retain the plan as its rationale.
-
-### Search and connect with bounded signals
-
-An identifier, title, alias, path, tag, or quoted phrase should not depend on an embedding. Exact mode reads the live Markdown. The default hybrid mode combines those results with keyword and vector result orders from [QMD, a local search engine for Markdown](<https://github.com/tobi/qmd>), while keeping exact identity matches first. Graph context and Git provenance remain separate evidence, so neither silently changes the primary text rank.
-
-**Path context, exact and hybrid search, and direct history**
-
-```shell
-wordcell context packages/parser/src/index.ts --root kb --repo .
-wordcell search "parser-v2" --root kb --mode exact
-wordcell search "why does the parser reject this input?" --root kb \
-  --tag architecture --where status=active --json
-wordcell history "notes/parser-design" --root kb --repo . --json
-```
-
-`--mode keyword` uses QMD's local full-text index without loading an embedding model. Hybrid and semantic modes use a pinned local embedding model. Wordcell reconciles every QMD hit with current Markdown before returning it, and applies metadata and tag filters to those live notes. Search modes remain explicit through `--mode exact`, `--mode keyword`, `--mode semantic`, and `--mode hybrid`.
-
-Retrieval is bounded. The high-level `wordcell search` and `KnowledgeBaseSession.search` surfaces return at most 100 primary results and request at most 500 candidates from each QMD retrieval lane. Selective filters can discard stale or ineligible rows from that window. When those discards prevent Wordcell from filling the requested eligible result set, Wordcell marks the QMD lane degraded and the overall result partial instead of presenting the bounded approximation as complete. Scores are local ranking signals, not probabilities, and cannot be compared across modes.
-
-Each note owns its outbound typed relationships in frontmatter. Wordcell derives backlinks, inverse edges, and bounded traversal at read time, so parallel agents do not contend on one generated fact file. `wordcell percolate <note>` reports recurring concepts and missing-link candidates with inspectable support but writes nothing. An agent reads the cited notes before creating a reusable concept or relationship. Semantic similarity never creates an edge automatically.
-
-Percolation Result V2 presents a missing relationship as an unordered pair of
-notes with a required predicate. It does not choose the source, direction, or a
-`related-to` fallback. Recommended authored predicates include `synthesizes`,
-`evidenced-by`, `informed-by`, `supersedes`, and `contradicts`; they are an
-advisory vocabulary, so a vault can use another canonical predicate when its
-prose and evidence define the claim. Wordcell never infers reciprocal, inverse,
-transitive, or similarity-derived relationships.
-
-Git provenance is opt-in. A search without `--history` performs no Git indexing. `--history` requests best-effort provenance, while `--require-history` rejects unavailable history or incomplete provenance for the selected notes. If one commit exceeds the 2,000-path detail limit, Wordcell retains its identity and vault-local note associations, marks its co-change detail incomplete, and continues through later commits. Best-effort search reports that requested lane as partial.
-
-Local attachment checks cover Markdown and Obsidian references to images, PDFs, and editable tldraw sources. They reject missing or escaping files while leaving external URLs alone. A source-inbox view separately lists recent captures that have no inbound disposition from maintained knowledge. It is an advisory, not an automatic backlink requirement: a saved source may intentionally remain a leaf.
-
-### Measure retrieval on a frozen corpus
-
-The August 2, 2026 pilot froze one repository snapshot and 18 questions whose graded relevance judgments were written before the rankings were inspected. The evaluator scanned 156 Markdown records and projected 155 searchable notes into QMD after excluding the authored vault index and agent guides. Nine questions formed the development set, and nine were held out for the test. The test covered exact identity, conceptual recall, active plans, current decisions, code-path context, source evidence, historical rationale, stale-versus-current conflicts, and one no-answer case.
-
-At a cutoff of 10 results, exact search recorded `Recall@10` of 0.833333, `MRR@10` of 0.892857, and `nDCG@10` of 0.790377. Hybrid search recorded 0.833333, 0.937500, and 0.833884, respectively. Recall measures how much of the judged relevant set appeared; mean reciprocal rank rewards an earlier first relevant result; normalized discounted cumulative gain also accounts for graded relevance and position.
-
-Eight test questions had an answer. A 10,000-resample paired bootstrap, which repeatedly samples those same questions to estimate the stability of the difference, measured hybrid minus exact. The `Recall@10` difference was 0 with a 95% confidence interval of \[0, 0\]; the `MRR@10` difference was +0.044643 with \[0, 0.133929\]; and the `nDCG@10` difference was +0.043508 with \[-0.012752, 0.111832\]. Both retrievers returned a result for the one no-answer question instead of abstaining, so their no-answer accuracy was 0.
-
-The same mixed-cache, single-run test recorded p95 latencies of 44.345 milliseconds for exact, 62.834 for hybrid, 821.370 for keyword, and 41,000.524 for semantic retrieval. The semantic figure includes the first in-process model load. The run used [QMD 2.5.3 at Hraness compatibility commit aa993dc](<https://github.com/hraness/qmd/commit/aa993dceb3ef8cfb71d470554ca437570f5a2b3c>) and a locally verified EmbeddingGemma 300M Q8 model on Bun 1.3.14 and Node 24.3.0 under arm64 Darwin 25.5.0, with an Apple M4 Max, 16 logical CPUs, and 128 GiB of memory. Each p95 summarizes only nine queries with mixed cold and warm state, so these are local diagnostics, not speed claims. The corpus is too small to establish that hybrid is generally superior to exact search or to compare Wordcell with industry retrieval systems.
-
-Search finds candidates. Similarity does not establish that a passage is current, correct, or supported by its sources. The Markdown, cited captures, explicit relationships, and requested Git history supply the material a reader must inspect.
-
-### Customize through an approved proposal
-
-The Agent Skill routes setup and evolution requests before it prepares a
-runtime. It inspects the proposed location without mutation, interviews the
-user about the memory questions the Wordcell should answer, and presents exact read
-and write targets. Only the approved targets may be scaffolded. A changed path,
-repository, account, integration, or companion skill requires renewed
-approval.
-
-The standard router may be enough. A recurring ritual can instead receive a
-companion skill with explicit inputs, authority, durable outputs, idempotence,
-failure behavior, and verification. These skills are inert instructions. They
-do not create a plugin runtime, execute vault metadata, inherit ambient account
-access, or couple application code to the Wordcell. An exact repeat is a no-op;
-divergence, path escape, symbolic links, partial writes, and unapproved
-external surfaces stop the workflow.
-
-The repository's fake-capability suite exercises those transitions. It is a
-tested contract example, not proof that every agent or host integration
-complies.
-
-This workflow builds on Frank Chen's public notes about [designing a personal
-knowledge base with an
-agent](https://gist.github.com/fxchen/773397095d7a6bffda621e4237da0da9)
-and [extending it with
-skills](https://gist.github.com/fxchen/09cb410b22c9c5256d80243ee925b57e).
-
-Wordcell ships no `kb_role` metadata, lifecycle resolver or API, lifecycle CLI,
-compatibility diagnostic, or metadata migration. A frozen Phase 0 value gate
-must show that those surfaces improve deterministic agent decisions before they
-are introduced. Current and historical plan routing remains derived from
-existing type, path, and status conventions.
-
-### Adopt the smallest useful split
-
-Start with a short inherited `AGENTS.md` path for rules whose omission would make an edit wrong. A small knowledge base may need only Markdown, Git, an index page, and ordinary file search. Add source capture when evidence keeps disappearing. Add repository scopes when agents need to recover current memory from code paths. Add metadata or hybrid search when file search stops answering the repository's questions. Add links and graph views only when the relationships themselves help people make decisions.
-
-Treat the knowledge base as repository-adjacent durable memory. Authored Markdown and Git are the record; catalogs, indexes, embeddings, and graph views are replaceable ways to find and inspect it. Checks can validate structure, captures can preserve a selected surface, and similarity can suggest candidates. None of those mechanisms proves that a source is trustworthy or an explanation is still true. People and agents must revise the knowledge as the repository changes.
-
-## Installation reference
-
-[Bun](https://bun.sh/docs/installation) is the required runtime. GitHub Releases are the canonical distribution, and each release publishes the same archive to npm as `@hraness/wordcell`. The examples target the prepared `0.21.0` release and become available when its GitHub release is published. Existing `@hraness/kb` installs remain available during that transition. For signed artifact verification, see [the release procedure](docs/publishing.md#verify-a-published-release).
-
-### Tell your coding agent to install it
-
-Copy this prompt into Codex, Claude Code, or another coding agent:
-
-```text
-Install the `wordcell` Agent Skill from `hraness/wordcell#v0.21.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
-I ask.
-```
-
-Install the single public skill with either runner:
-
-```sh
-npx skills add hraness/wordcell#v0.21.0
-bunx skills add hraness/wordcell#v0.21.0
-```
-
-Both commands discover the same `wordcell` skill and install it into the selected
-agent runner. Skill installation is inert: it does not initialize a vault,
-refresh a catalog, or edit Markdown. When invoked, the skill uses an existing
-`wordcell` command or, when the command is missing, checks for Bun and installs the
-CLI from the immutable GitHub release archive.
-
-The public skills CLI reads `skills/wordcell/` from the repository. The immutable
-`0.21.0` packed release includes the same tree under
-`node_modules/@hraness/wordcell/skills/wordcell/`, and the package check verifies that the
-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.21.0/hraness-wordcell-0.21.0.tgz
-wordcell --help
-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.21.0/hraness-wordcell-0.21.0.tgz
-wordcell --help
+    ├── index.md             # authored or managed front door
+    ├── articles/            # captured sources and assets
+    ├── notes/               # maintained explanations
+    └── plans/               # decisions and outcomes
 ```
 
-Both commands are Bun executables. Bun `1.3.14` or newer must remain in `PATH`
-even when npm performs the global installation. The conservative npm command
-above disables dependency lifecycle scripts. Optional native search and
-rendered-browser setup remain unavailable until the relevant scripts are
-reviewed and enabled; run `wordcell doctor` to inspect the resulting capabilities.
+Markdown, YAML frontmatter, explicit wikilinks, and Git hold the record. Open
+the same files in Obsidian, a text editor, or ordinary file-search tools.
+Application code does not need to import Wordcell or its vault.
 
-For programmatic use, add the versioned GitHub archive to a Bun project:
+QMD supplies optional local search. Oh supplies a disposable graph projection;
+only an explicit `wordcell graph rebuild --root kb` writes `.wordcell/oh.sqlite`.
+Backlinks and typed relationships come from authored links. Percolation
+suggests connections for review and does not add inferred edges to notes.
 
-```sh
-bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.0/hraness-wordcell-0.21.0.tgz
-```
+Graph proofs explain a supported derivation from a specific source revision.
+They do not prove that a note is true or that a missing relationship cannot
+exist. [Graph queries and proof limits](https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md).
 
-The resulting dependency should remain exact:
+## Build with the TypeScript SDK
 
-```json
-{
-  "dependencies": {
-    "@hraness/wordcell": "https://github.com/hraness/wordcell/releases/download/v0.21.0/hraness-wordcell-0.21.0.tgz"
-  }
-}
-```
-
-Version 0.21.0 retains two public GitHub dependencies: `@hraness/oh` at
-immutable release archive `v0.4.3` for graph projection and closure verification and `@tobilu/qmd` at commit
-`aa993dceb3ef8cfb71d470554ca437570f5a2b3c` for store-local model behavior.
-Installation also needs Git and public GitHub access while it resolves those
-dependencies. Browser-cookie capture uses the exact upstream registry release
-`@steipete/sweet-cookie` `0.4.3`, which includes the host-scope, isolation, and
-explicit Chromium Keychain fixes previously carried by the Hraness fork.
-
-### Review lifecycle scripts before enabling optional adapters
-
-[Bun blocks dependency lifecycle scripts](https://bun.sh/docs/pm/lifecycle)
-unless the consumer trusts them. Run
-`bun pm untrusted` in the consuming project and inspect the exact resolved
-versions and scripts before allowing any of them. Do not use `bun pm trust
---all` for this package's dependency graph.
-
-The pinned QMD Git dependency has a `prepare` script that installs development
-hooks only when its own `.git` directory exists; the packaged runtime does not
-need that script. Optional rendered capture uses `agent-browser`, whose
-postinstall downloads a platform-specific executable. QMD's native semantic
-and language-parser paths can report lifecycle scripts for `node-llama-cpp`,
-`tree-sitter-go`, `tree-sitter-javascript`, `tree-sitter-python`, and
-`tree-sitter-rust`. Trust only the packages required by the capability you have
-chosen, then reinstall and run `wordcell doctor` to verify that capability. npm runs
-dependency lifecycle scripts by default, so inspect the same packages before
-omitting `--ignore-scripts` from an npm installation.
-
-Wordcell can read explicitly selected signed-in browser state and perform
-bounded capture and network operations. Read the [security
-policy](SECURITY.md) before using authenticated capture.
-
-Contributors can install from a checkout instead:
+Add the same immutable release to a Bun project:
 
 ```sh
-git clone https://github.com/hraness/wordcell.git
-cd wordcell
-bun install --frozen-lockfile
-bun link
-wordcell --help
+bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.1/hraness-wordcell-0.21.1.tgz
 ```
 
-HTTP and Archive.today capture work with the installed JavaScript dependencies. Rendered capture additionally needs a local Chromium-compatible browser. [yt-dlp](https://github.com/yt-dlp/yt-dlp) adds YouTube metadata, thumbnails, and transcripts; full audio or video localization is opt-in and some formats also need [FFmpeg](https://ffmpeg.org). PDF ingestion uses the open-source Poppler tools `pdfinfo` and `pdftohtml`; [Tesseract](https://github.com/tesseract-ocr/tesseract) adds local OCR for scans and screenshots. URL metadata backfill requires Rust on macOS or Linux to build the immutable, fixed-network, memory-confined `metadata-search-engine-rs` helper included in the installed package. Run `wordcell url-metadata tool build` once, then use `wordcell url-metadata backfill` from any working directory.
-
-Structural commands and exact search read the current Markdown directly and
-need no service, model, or graph database. Wordcell pins
-[QMD](https://github.com/tobi/qmd) 2.5.3 for local keyword and vector search.
-`--mode keyword` uses its full-text index without an embedding model. Hybrid
-and semantic search use a revision-pinned compact local EmbeddingGemma model;
-the first index or vector query downloads about 300 MB. On macOS with Bun,
-install extension-capable Homebrew SQLite with `brew install sqlite` before
-using vector retrieval.
-
-`wordcell doctor` statically checks the pinned QMD, SQLite, sqlite-vec,
-node-llama-cpp, and matching native packages without importing native code or
-downloading the model. Exact and keyword search remain model-free. Wordcell also
-refuses an older adjacent `.snapshot` directory that lacks its ownership
-marker; inspect and remove only the explicitly named disposable directory,
-then retry so Wordcell never guesses that unrelated files are cache data.
-
-## The kb vault format
-
-Wordcell is the product; `kb` is the vault format. The conventional vault
-directory is `kb/`, managed regions use the `<!-- kb:catalog:start -->` and
-`<!-- kb:context … -->` markers, the front-door frontmatter key is
-`kb_catalog`, portfolio identities use `kb://<owner>/<vault>/<document_id>`
-URIs, and the shell conventions in the skill and docs are `KB_ROOT` and
-`KB_REPO`. These names identify files that many repositories already commit,
-so they did not change with the product name. Every `wordcell` command reads
-and writes the same vaults that `kb` did.
-
-## Start a vault
+The SDK provides read-only vault sessions, metadata queries, search, graph
+proofs, Git context, and composable workflows. A session owns one snapshot;
+reopen it after Markdown changes. [SDK and workflow examples](https://github.com/hraness/wordcell/blob/main/docs/reference.md#graph-reference)
+show the public imports and lifecycle.
 
-```sh
-wordcell init my-kb
-cd my-kb
-wordcell clip https://example.com/article --output articles
-wordcell refresh --root .
-wordcell check --root .
-```
-
-`wordcell init` creates an `index.md` front door plus `articles/`, `notes/`,
-`plans/`, `riffs/`, and optional repository-context `scopes/` boundaries. The
-generated Markdown remains ordinary Markdown: open it in Obsidian, edit it in a
-text editor, search it with standard tools, and version it with Git.
-
-When a vault lives at `kb/` inside a repository, inspect the instructions and
-mapped context for a repository path from the repository root:
-
-```sh
-wordcell agents identity packages/parser --json
-wordcell context packages/parser/src/index.ts --root kb --repo .
-wordcell agents check --root kb --repo .
-```
+## Privacy and boundaries
 
-`wordcell agents identity` derives a canonical mapping without writing files.
-`wordcell context` lists inherited `AGENTS.md` files from the repository root toward
-the target, verified context hubs from the nearest scope back toward the root,
-and bounded repository-scoped memory. Maintained knowledge, active plans,
-dated research, reports, and terminal plans stay in separate groups. Every
-record states the exact authored scope that matched and whether it exists.
-Open only the useful summaries, then use `wordcell links`, `wordcell backlinks`, `wordcell list`,
-or `wordcell search` to expand the question deliberately.
+- Structural queries and exact search read local files. Optional semantic
+  search downloads its model on first use and runs locally.
+- URL capture contacts the requested source. Signed-in capture uses only
+  explicitly selected browser state. Review the [security policy](https://github.com/hraness/wordcell/blob/main/SECURITY.md)
+  before using it with private sources.
+- An agent that reads the vault follows its own provider and data-handling
+  settings. Keep private records out of public repositories and outputs.
+- Git history is opt-in. Saved notes preserve recorded context; Wordcell does
+  not reconstruct unsaved conversations or silently record every agent action.
 
-## Command surface
+## Documentation
 
-| Command | Purpose |
+| Read next | Purpose |
 | --- | --- |
-| `wordcell init [directory]` | Create a new vault without merging into or overwriting an existing path; the default directory is `kb`. |
-| `wordcell clip <url\|current>` | Capture a source and write an article bundle. `current` reads an attached active tab without navigating it; `wordcell capture <url>` is the explicit URL form. |
-| `wordcell capture show\|verify\|diff <bundle>` | Inspect a stored capture as hostile content, verify its recorded document and optional asset hashes, or compare its exact Markdown bytes with a bounded Git ref. |
-| `wordcell inspect <url>` | Run acquisition and extraction without writing a bundle. |
-| `wordcell pdf <file-or-url> [--slug <slug>]` | Convert a local or public remote PDF into Markdown while retaining the original bytes, extracted images, OCR-derived text, URL provenance, and page provenance. |
-| `wordcell refresh --root <directory>` | Rebuild a managed catalog atomically and report graph findings. An authored-catalog vault remains unchanged. |
-| `wordcell check --root <directory>` | Verify catalog policy, graph integrity, and confined local image, PDF, and tldraw attachments without changing files. `--no-catalog` gates an edit lane without requiring the shared catalog refresh. |
-| `wordcell catalog --root <directory>` | Render an exhaustive disposable catalog without modifying an authored or managed front door. |
-| `wordcell graph query --program <name> --root <directory>` | Query a bounded, proof-bearing Oh projection; see [the graph guide](docs/graph-authority.md). |
-| `wordcell graph rebuild\|verify --root <directory>` | Rebuild or verify the disposable local graph cache without editing Markdown. |
-| `wordcell graph --root <directory>` | Print the resolved contextual and typed graph, broken or ambiguous targets, orphans, and advisory mention candidates. |
-| `wordcell backlinks <note> --root <directory>` | Show incoming contextual links and typed relationships for a note resolved by path, title, or alias. |
-| `wordcell links <note> --root <directory>` | Traverse incoming, outgoing, or bidirectional contextual links and typed relationships with explicit depth and node limits. |
-| `wordcell note create <id> --title <title> --root <directory>` | Atomically create one confined Markdown note; use `--type concept` for a reusable concept. |
-| `wordcell relation add\|remove <source> <predicate> <target>` | Idempotently edit one source note's typed outbound relationship using an exact local note ID or canonical stable `kb://` URI. |
-| `wordcell relation list <note> --root <directory>` | List a note's authored outbound and derived inbound typed relationships. |
-| `wordcell percolate [note] --root <directory>` | Report evidence-backed recurring-concept and missing-relationship candidates without writing notes. |
-| `wordcell list --root <directory>` | Filter typed nested frontmatter, tags, and repeated exact `--scope` declarations; sort by metadata, title, path, or graph counts. `wordcell notes` is an alias. |
-| `wordcell index --root <directory>` | Build or incrementally refresh the optional local QMD embedding index. |
-| `wordcell search <query> --root <directory>` | Combine live exact matches with local QMD keyword and vector retrieval. Use `--mode exact\|keyword\|semantic\|hybrid`, metadata, tags, exact `--scope` filters, or bounded graph context. `--rules <file>` enables reviewed aliases; add `--priority` for explicit rule-based ordering. Omitted history performs no Git work; `--history` requests best-effort provenance and `--require-history` rejects unavailable or incomplete selected-note provenance. |
-| `wordcell portfolio search <query> --registry <file> --workspace <directory>` | Search only explicitly authorized vaults. Use `--shared` for public and organization entries or repeat `--vault owner/id` for a deliberate selection. The same `--rules <file>` and opt-in `--priority` apply within each selected vault before deterministic federation. |
-| `wordcell portfolio audit --registry <file> --workspace <directory>` | Audit selected vault identities, authority groups, graph references, attachments, exact duplicate content, catalogs, and Git availability without repairing or electing an authority. |
-| `wordcell history <note> --root <vault> --repo <repository>` | Return bounded direct provenance for one resolved note, including explicit oversized-commit limitations. |
-| `wordcell history search <query-or-path> --root <vault> --repo <repository>` | Search bounded commit subjects, note paths, and co-change paths without authoring links or repository scopes. |
-| `wordcell context <repository-path> --root <vault> --repo <repository>` | List inherited guides root to nearest, reciprocal hubs nearest to root, and grouped repository-scoped current and historical memory. Use `--kind auto\|file\|directory` to control path interpretation. |
-| `wordcell inbox --root <vault>` | List recent captures without a maintained-note disposition. This is advisory and never creates links or fails merely because a source is a leaf. |
-| `wordcell evaluate <manifest.json> --root <vault> --repo <repository>` | Verify an exact frozen Git/vault snapshot and run built-in exact, QMD, metadata, graph, path-context, and Git retrievers with raw evidence, latency, resource counters, metrics, and paired intervals. |
-| `wordcell-evaluation-builder --anchor-seal\|--build --config <file> --artifact-root <directory>` | Anchor or build a frozen evaluation corpus through the installed package boundary. |
-| `wordcell url-metadata tool build\|check` | Build or validate the pinned Rust metadata-search helper through the installed package boundary. |
-| `wordcell url-metadata backfill --root <vault>` | Add resumable `url-metadata.json` sidecars for saved external URLs through the pinned metadata search helper and optional read-only Archive.today discovery. |
-| `wordcell agents identity <repository-scope>` | Derive the normalized scope, canonical hub ID and path, owning guide path, and exact reciprocal marker without writing files. |
-| `wordcell agents check --root <vault> --repo <repository>` | Validate context identities, exact scopes, reciprocal markers, real guide paths, collisions, confinement, and guide shape. Unmapped guides remain valid. |
-| `wordcell agents audit --root <vault> --repo <repository>` | Run the same correctness gate, then report deterministic per-guide, section, inherited-chain, long-bullet, and exact-duplicate advisories. |
-| `wordcell doctor` | Report capture capabilities and statically inspect local QMD, SQLite, sqlite-vec, node-llama-cpp, and native search prerequisites without loading a model. |
-| `wordcell adapters` | Print the installed platform capability matrix. |
-
-Vault commands default to the current directory and `index.md`; use `--root` and `--index` to select alternatives. Commands that report structured data accept `--json`. Run `wordcell --help` for the complete top-level surface and `wordcell clip --help` for capture, authentication, evidence, and resource-bound options.
-
-## Capture reference
-
-Use the current browser tab without navigating it:
+| [Agent workflow](https://github.com/hraness/wordcell/blob/main/docs/agent-workflow.md) | Set up, query, maintain, and revise repository memory. |
+| [Installation and command reference](https://github.com/hraness/wordcell/blob/main/docs/reference.md) | Exact interfaces, SDK imports, optional adapters, and troubleshooting prerequisites. |
+| [Web capture](https://github.com/hraness/wordcell/blob/main/docs/capture.md) and [PDF capture](https://github.com/hraness/wordcell/blob/main/docs/pdf.md) | Save sources with provenance, assets, and explicit completeness limits. |
+| [Graph guide](https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md) | Named queries, proofs, revisions, resource limits, and cache recovery. |
+| [Portfolio federation](https://github.com/hraness/wordcell/blob/main/docs/portfolio.md) | Search only selected, authorized vaults. |
+| [Design](https://github.com/hraness/wordcell/blob/main/docs/design.md) and [memory rationale](https://github.com/hraness/wordcell/blob/main/docs/agent-memory.md) | File contracts, design choices, and evaluation context. |
+| [Release verification](https://github.com/hraness/wordcell/blob/main/docs/publishing.md#verify-a-published-release) | Verify archive identity, signatures, and provenance. |
 
-```sh
-wordcell clip current --browser-live --output articles
-wordcell clip current --cdp 9222 --output articles
-```
-
-For `--browser-live`, first enable Chrome's local debugging connection at `chrome://inspect/#remote-debugging` (Chrome 144+). If Chrome was launched with an explicit loopback debugging port, pass that numeric port to `--cdp` instead.
-
-To open a URL with state from a path-backed Chromium profile, pass its path. The capture runs against a temporary copy, leaving the source profile unchanged. A named profile selects reusable agent-browser-managed state instead:
-
-```sh
-wordcell clip https://example.com/private --browser-profile <path> --output articles
-```
+### Installation reference
 
-Each web capture writes readable Markdown, `capture.json`, localized assets, and optional evidence under `articles/<slug>/`. Unless media is disabled, YouTube captures add the title, description, duration, channel, thumbnail, and a locally extracted transcript when available; other video surfaces retain a poster or thumbnail instead of downloading the video by default. See [Capture web content](docs/capture.md) for scopes, saved files, browser modes, media, evidence, completeness states, and limits.
+[Alternative installs and optional capabilities](https://github.com/hraness/wordcell/blob/main/docs/reference.md#installation-reference).
 
-Schema v4 manifests bind the exact saved Markdown path, byte count, and SHA-256
-digest. `wordcell capture verify articles/<slug>` checks that digest without executing
-the content. Add `--verify-assets` to check recorded assets. Source HTML remains
-omitted unless `wordcell capture show` receives `--include-source-html`.
+### The kb vault format
 
-PDF capture uses the same bundle boundary:
-
-```sh
-wordcell pdf "/absolute/path/to/document.pdf" --output articles
-wordcell pdf "https://example.com/document.pdf" --output articles
-```
+Existing `kb/`, `index.md`, `kb://` identifiers, and Markdown formats remain
+compatible. [Vault format reference](https://github.com/hraness/wordcell/blob/main/docs/reference.md#the-kb-vault-format).
 
-The bundle includes byte-identical `source.pdf`, readable Markdown, `capture.json`, and content-addressed extracted images. A reviewed second pass also retains its hash-bound `annotations.json`. See [Capture PDF documents](docs/pdf.md) for heading inference, OCR, screenshot metadata, completeness, and review.
+### Command surface
 
-## Graph reference
+[Complete CLI reference](https://github.com/hraness/wordcell/blob/main/docs/reference.md#command-surface).
 
-Vault-root wikilinks such as
-`[[notes/context-engineering|context engineering]]` and source-owned typed
-frontmatter relationships are the graph's authored facts:
+### Capture reference
 
-```yaml
-type: concept
-document_id: durable-agent-memory
-relations:
-  supports:
-    - notes/durable-agent-memory
-```
+[Capture commands and dependencies](https://github.com/hraness/wordcell/blob/main/docs/reference.md#capture-reference).
 
-Predicates use lower-kebab-case. Local targets use exact vault-root IDs without
-`.md`; cross-vault targets use canonical stable `kb://` URIs. `wordcell graph`, `wordcell backlinks`, `wordcell relation list`, and `wordcell links` derive
-inverse edges and bounded paths without injecting reciprocal or inferred facts into notes.
-`wordcell percolate` proposes reusable concepts and missing connections with explicit
-support; an agent reviews the cited prose before authoring anything. In its V2
-result, a missing relationship is an unordered endpoint pair with a required
-predicate, never an executable directed assertion or an automatic
-`related-to`. Common reviewed claims use `synthesizes`, `evidenced-by`,
-`informed-by`, `supersedes`, or `contradicts`; other canonical custom predicates
-remain valid when their meaning is supported.
-
-Within a portfolio, a note can target a stable cross-vault identity such as
-`kb://hraness/sleepyland/sound-wellness-expansion`. The target vault must be
-explicitly selected for `wordcell portfolio audit` to resolve it. Missing or invalid
-`document_id` values remain legacy path identities and never gain a stable URI
-by inference.
-
-These focused views are rebuilt from current Markdown. Wordcell never commits a graph
-database, generated fact file, or engine entity ID. Parallel agents therefore
-keep editing separate notes. Each lane can run `wordcell check --no-catalog`, and the
-integrator runs one final `wordcell refresh` for the only shared generated region in
-`index.md`. Use `wordcell graph --json` for a whole-vault structural question; when a
-question recurs, prefer adding a focused command with a bounded output contract
-over introducing a parallel query store.
-
-Frontmatter retains nested objects, arrays, finite numbers with safe integer precision, booleans, strings, and nulls. `wordcell list --where type=plan --tag ingestion --sort metadata.updated --order desc` answers exact questions from that authored data. Unquoted `true`, `false`, `null`, and numeric filter values are typed; keep the quotes inside the argument to match a string with the same spelling, for example `wordcell list --where 'external_id="9007199254740993"'`. Hybrid search fuses exact and QMD result orders, then joins each match back to live metadata. Graph neighbors and Git provenance are returned as separate evidence. Similarity never becomes a link automatically.
-
-Repository context preserves a stricter authority boundary. `AGENTS.md` remains
-the always-loaded, normative home for ownership, required commands,
-prohibitions, and edit gates. An optional `type: agent-context` note under
-`scopes/` holds rationale, history, examples, evidence, and links for one exact
-repository-relative directory. Its reciprocal
-`<!-- kb:context scopes/<id> -->` marker appears before the guide headings.
-A hub cannot override its guide or become the only home of a load-bearing
-editing rule. Moving the scoped directory changes its identity.
-
-Scope hubs are ordinary Markdown in the graph and optional QMD index;
-`AGENTS.md` files remain excluded. This workflow reads repository and vault
-files at development time. Applications do not need to import Wordcell or couple
-their runtime to the vault.
-
-The package exports its full programmatic surface from `@hraness/wordcell`. Open one
-read-only vault session through `@hraness/wordcell/sdk` to share a live Markdown scan
-across exact search, metadata queries, reads, navigation, hybrid search, and Git
-provenance. Compose finite parallel retrieval graphs with
-`@hraness/wordcell/workflow`. `@hraness/wordcell/workflows` includes editable
-`decision-context`, `explain-change`, and `plan-radar` compositions. Focused
-lower-level entry points include
-`@hraness/wordcell/search`, `@hraness/wordcell/git`,
-`@hraness/wordcell/agent-context`,
-`@hraness/wordcell/agent-guide-audit`, `@hraness/wordcell/attachments`,
-`@hraness/wordcell/authoring`, `@hraness/wordcell/evaluation`,
-`@hraness/wordcell/evaluation-kb`, and `@hraness/wordcell/evaluation-builder`. The builder
-entry point owns frozen-corpus authoring, evidence compilation, implementation
-commitments, seal validation, and the bounded v2 evaluation mechanics. A
-consumer keeps its corpus, build configuration, repository-specific retriever
-descriptors, and promotion expectations in its own repository. The installed
-`wordcell-evaluation-builder` binary exposes the same build lifecycle without a
-source checkout.
-Other focused entries include
-`@hraness/wordcell/graph-authority`, `@hraness/wordcell/graph-percolation`, `@hraness/wordcell/graph`, `@hraness/wordcell/navigation`, `@hraness/wordcell/percolate`,
-`@hraness/wordcell/portfolio`, `@hraness/wordcell/query`, `@hraness/wordcell/repository-memory`,
-`@hraness/wordcell/search-rules`, `@hraness/wordcell/untrusted-content`,
-`@hraness/wordcell/source-inbox`, and `@hraness/wordcell/semantic`; web-capture orchestration and
-diagnostics from
-`@hraness/wordcell/capture`; metadata search, Archive.today discovery, sidecar parsing,
-and backfill composition from `@hraness/wordcell/url-intelligence`; PDF ingestion from `@hraness/wordcell/pdf`; and reusable
-disposable-profile helpers from `@hraness/wordcell/browser-profiles`. Embedders that
-need the CLI's lower-level ingestion machinery can use the explicit
-capture-primitive subpaths listed in `package.json`, including
-`@hraness/wordcell/clip/acquire`, `@hraness/wordcell/clip/args`, the DNS-pinned request and
-connection-pool boundary at `@hraness/wordcell/clip/network`, and the browser proxy at
-`@hraness/wordcell/clip/network-proxy`. Stored-bundle inspection, capture refresh
-diffs, and the explicit local job ledger are available from
-`@hraness/wordcell/clip/bundle-reader`, `@hraness/wordcell/clip/refresh`, and
-`@hraness/wordcell/clip/jobs`.
-
-## Agent skills
-
-The repository ships one reusable `wordcell` Agent Skill under `skills/wordcell/`. Its
-intent router loads focused references only when a task needs them: querying
-repository context and agent memory, capturing URLs or PDFs, writing durable
-plans, promoting concepts and typed relationships, refreshing and checking a
-vault, or designing a setup through an interview and approved proposal. An
-approved setup may scaffold a bounded companion skill for a distinct recurring
-ritual. The package smoke test keeps future tagged packages byte-identical to
-that source tree.
+### Graph reference
 
-```sh
-npx skills add hraness/wordcell#v0.21.0
-# or
-bunx skills add hraness/wordcell#v0.21.0
-```
+[Graph and SDK interfaces](https://github.com/hraness/wordcell/blob/main/docs/reference.md#graph-reference).
 
-The skill invokes the installed `wordcell` command without depending on a repository
-checkout. It routes setup and evolution before runtime preparation. For
-execution workflows, runtime setup installs the pinned CLI only when the
-command is missing, and it never initializes or mutates a vault as an
-installation side effect. The repository's phase-orchestration skill remains
-available to local repository agents but is marked internal, so public skill
-discovery omits it.
+### Agent skills
 
-See [Design](docs/design.md), [Portfolio federation](docs/portfolio.md), [Agent workflow](docs/agent-workflow.md), [PDF capture](docs/pdf.md), and [Contributing](CONTRIBUTING.md) for the durable contracts and development gate. hraness/wordcell is available under the [MIT License](LICENSE).
+[Installation and runtime contract](https://github.com/hraness/wordcell/blob/main/docs/reference.md#agent-skills).
+The same skill is included at `node_modules/@hraness/wordcell/skills/wordcell/`.
 
 ## Release notes
 
-### Upgrade to v0.21.0
-
-Version 0.21.0 adds a rebuildable Oh graph, named positive-rule queries with
-source proofs, read-only cache verification, and opt-in percolation proofs.
-See [the graph guide](docs/graph-authority.md) for commands, resource limits,
-revision identity, and cache recovery. Existing graph reports, percolation V2,
-search ranking, vault formats and `kb://` identifiers stay compatible.
-
-The deprecated `kb` command alias is removed as announced in 0.20.0. Update
-scripts to invoke `wordcell`; existing pinned 0.20.x installations retain the
-alias. No Markdown or document-ID migration is required.
+Version 0.21 adds Oh graph queries and proofs. The deprecated `kb` command was
+removed at this boundary; use `wordcell`. Existing vaults need no migration.
+[All release notes and upgrade instructions](https://github.com/hraness/wordcell/blob/main/CHANGELOG.md).
 
-### Upgrade to v0.20.0
+## Contributing
 
-Version 0.20.0 renames the product from KB to Wordcell. The package is
-`@hraness/wordcell`, the commands are `wordcell` and
-`wordcell-evaluation-builder`, the Agent Skill is `wordcell`, and the homepage
-moved from hraness.com to [wordcell.io](https://wordcell.io). The `kb` command
-stays as a deprecated alias that prints one notice; it is removed in 0.21.0.
-The vault format keeps its `kb` names, so existing vaults need no migration.
-The package is published as ordinary software with no npm content-policy
-declaration, and each tag Release now publishes the same archive bytes to npm
-automatically through OIDC trusted publishing. Versions through 0.19.6 remain
-available under `@hraness/kb`.
+Run `bun run check` for source, architecture, package installation, types, and
+native-helper validation. The site has its own `bun run check` under `site/`.
+See [Contributing](https://github.com/hraness/wordcell/blob/main/CONTRIBUTING.md), [Security](https://github.com/hraness/wordcell/blob/main/SECURITY.md), and the [MIT License](https://github.com/hraness/wordcell/blob/main/LICENSE).
 
-### Upgrade to v0.19.6
-
-Version 0.19.6 adopts the upstream Sweet Cookie 0.4.3 registry package in place
-of the Hraness 0.4.4 fork. Upstream includes the cookie-scope, isolation, and
-explicit Chromium Keychain fixes. Capture retains host-only and Domain cookie
-scope, rejects partitioned or container state it cannot replay, and keeps
-explicit browser selection bound to its profile. The local cookie guards and
-synthetic provider regressions remain in place.
-
-### Upgrade to v0.19.5
-
-This candidate corrects draft asset URL admission before the first canonical
-GitHub package release. GitHub may expose a temporary same-repository URL until
-the draft is published; published assets still require their exact versioned
-URLs and verified bytes. The failed `v0.19.4` draft is retained as release
-evidence and is not an installable release.
-
-GitHub Releases become the canonical installation source. Each release binds its packed archive to the reviewed source and signed GitHub build identity. npm remains an optional mirror and older installations keep working. The SDK and CLI interfaces do not change.
-
-### Upgrade to v0.19.3
-
-Version 0.19.3 gives workflow execution and single-note publication complete
-Effect owners behind their existing Promise APIs. Native callbacks and writes
-remain owned until they settle. In particular, a failed directory sync now
-joins its admitted sibling before recovery releases the note lock. Workflow
-ordering, concurrency bounds, exact public errors, revision checks and
-no-clobber recovery remain compatible. Effect 3.22.1 is an exact runtime
-dependency; consumers do not need to create an Effect runtime or change calls.
-
-### Upgrade to v0.19.2
-
-Version 0.19.2 recognizes npm 11.19's `signedAccessSignatureUrl` attestation
-wrapper field only when it is the currently evidenced empty string. Exact-key,
-signature, package, workflow, source, and provenance verification remain
-mandatory. Package runtime behavior is unchanged.
-
-### Upgrade to v0.19.1
-
-Version 0.19.1 updates the pinned Hraness Sweet Cookie fork to v0.4.4. Cookie
-ingestion now rejects records marked `partitionKeyOpaque: true` even when
-`partitionKey` is missing or null. If every selected inline cookie has
-unsupported isolation provenance, Sweet Cookie returns no cookies instead of
-falling back to browser stores. Explicit `partitionKeyOpaque: false` remains
-replayable, while malformed marker values fail closed.
-
-### Upgrade to v0.19.0
-
-Version 0.19.0 adds interview-first setup and evolution guidance, a bounded
-filesystem-only companion-skill scaffold contract, and Percolation Result V2.
-V2 requires an explicit predicate and leaves relationship ownership and
-direction to review. The release does not add lifecycle metadata, a resolver,
-a lifecycle CLI, inferred edges, or automatic account and network actions.
-
-### Upgrade to v0.18.1
-
-Version 0.18.1 restructures the public README and hosted projection around one
-durable note, the exact recovery workflow, inspectable retrieval signals, and
-explicit authority boundaries. Runtime APIs and package behavior are
-unchanged.
-
-### Upgrade to v0.18.0
-
-Version 0.18.0 adds a review-only adoption seam for exact dependency closures
-from an Oh working authority. Trusted host code creates a
-`createOhAdoptionPreparerV1` facade with the expected binding and head,
-destination, rights clearance, review route, and conflict policy. The narrow
-`prepare` call accepts only a capsule plus transformation and redaction
-disclosures, returns deeply immutable deterministic Markdown and manifest
-bytes with status `prepared`, and has no vault, Git, Oh-store, or promotion
-capability. Wordcell pins `@hraness/oh` v0.2.0 and delegates closure integrity to its
-official store verifier.
-
-### Upgrade to v0.17.3
-
-Version 0.17.3 restructures the README around an inspectable first task,
-explicit operating boundaries, and a shorter path from installation to useful
-output. Runtime APIs and package behavior are unchanged.
-
-### Upgrade to v0.17.2
-
-Version 0.17.2 improves package discovery through focused npm keywords, a more
-specific README opening, and direct links between npm, GitHub, and the project
-overview. Runtime APIs and package behavior are unchanged.
-
-### Upgrade to v0.17.1
-
-Version 0.17.1 adds the public `@hraness/kb` npm installation path without
-changing the runtime API introduced in 0.17.0. Bun `1.3.14` or newer is now an
-explicit package requirement. Consumers should review the package's declared
-dual-use capture boundary and the lifecycle scripts used by optional browser
-and native search adapters before enabling those scripts.
-
-### Upgrade to v0.17.0
-
-Version 0.17 adds selected portfolio federation, stable note identities,
-qualified external relations, search rules, capture inspection, and untrusted
-context packing. Consumers with typed fixtures or custom capture writers should
-make these migrations before upgrading:
-
-- Capture writers now emit manifest schema v4 and must provide the stored
-  document `path`, exact UTF-8 `bytes`, and lowercase SHA-256 digest. The reader
-  can inspect schema v1-v3, but verification reports their document integrity as
-  unavailable instead of success.
-- `DecisionContextOutput.search` has been removed. Consume the bounded untrusted
-  `context` projection and its `truncated` flag instead of transporting the raw
-  search result into an agent prompt.
-- `VaultAnalysis` fixtures must include `externalAuthoredRelations`, even when
-  the value is an empty array. This keeps qualified authored edges distinct
-  from locally resolved graph edges.
-- `createNote` and `wordcell note create` now assign `document_id` to new ordinary
-  notes. Preserve that ID across renames and update snapshots that intentionally
-  assert the generated frontmatter.
-
-Existing Markdown is not rewritten automatically. Add IDs to maintained legacy
-notes only through reviewed edits, and keep every QMD, graph, portfolio, and
-audit projection disposable.
+[Install Wordcell from GitHub Releases](https://github.com/hraness/wordcell/releases) ·
+[Wordcell source on GitHub](https://github.com/hraness/wordcell) ·
+[Wordcell overview](https://wordcell.io)

package/assets/agent-skill.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="124" height="20" role="img" aria-label="Agent Skill: install"><title>Agent Skill: install</title><rect width="124" height="20" rx="3" fill="#334155"/><path d="M74 0h47a3 3 0 0 1 3 3v14a3 3 0 0 1-3 3H74z" fill="#2563eb"/><g fill="#fff" text-anchor="middle" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11"><text x="37" y="14">Agent Skill</text><text x="99" y="14">install</text></g></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
   "license": "MIT",
   "type": "module",
@@ -79,7 +79,11 @@
     "backlinks",
     "knowledge-graph",
     "semantic-search",
-    "local-first"
+    "local-first",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "typescript-sdk"
   ],
   "exports": {
     ".": {
@@ -396,7 +400,8 @@
     "src/oh/programs.ts",
     "src/oh/schema.ts",
     "src/oh/snapshot.ts",
-    "src/oh/validation.ts"
+    "src/oh/validation.ts",
+    "assets/agent-skill.svg"
   ],
   "scripts": {
     "kb:refresh": "bunx --bun github:hraness/kb#v0.15.1 refresh --root kb",

package/skills/wordcell/SKILL.md

@@ -55,7 +55,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.21.0/hraness-wordcell-0.21.0.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.1/hraness-wordcell-0.21.1.tgz
 }
 wordcell --help
 ```