commit 0964819cdc3140465c8b5a5c724fdff104c42bb0
Author: NotExpectedYet <onlie@notexpectedyet.com>
Date:   Sat Sep 26 05:35:29 2026 +0100

    init

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f7dabe1
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..92ecb1d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,372 @@
+# dsh-recall
+
+Local-embedding code recall for **DeepSeek Harness**. One tool, `recall`, that
+answers "where is this handled?" with ranked **excerpts** — file path, line range,
+and a bounded slice of the code — instead of you reading whole files into the
+conversation.
+
+## Why this exists
+
+A long agent session does not get expensive because the model reasons. It gets
+expensive because **every step re-sends the accumulated transcript**, and in a
+coding session most of that transcript is file contents the agent has already
+read.
+
+Measured on one real DSH install over 32 days, from the `dsh-cost-meter` ledger:
+
+| | |
+|---|---|
+| total spend | **$160.27** (32 days — $5.01/day, ~$150/month) |
+| model calls | 39,804 |
+| prompt cache hit rate | **99.18%** — caching was already saturated |
+| cost from **re-reading cached context** | **65.1%** |
+| cost from new input | 16.9% |
+| cost from output (60% of it reasoning) | 18.0% |
+| **share of context that is message history** | **96.0%** (system 0.8%, tools 3.2%) |
+| average context re-read **per call** | **332,000 tokens** |
+
+That reframes the problem. Caching had nothing left to give, and trimming the
+system prompt or tool definitions would have chased 4% of the context. The money
+was in **how much history each step carried**. A tool that adds a 40-line excerpt
+instead of a 900-line file does not just save those tokens once — it saves them
+on *every subsequent step of the session*, because the context it never added is
+never re-sent.
+
+## What it does, measured
+
+Run against `ha-runtime` (684 indexable files) with the default 8-result limit:
+
+```
+query     : how does the occupancy state machine decide a room is occupied
+returned  : 13,075 chars   ~3,269 tokens
+source    : 78,669 chars  ~19,667 tokens  across the 4 files the results came from
+ratio     : 6.0x smaller
+```
+
+All eight results landed inside `src/controllers/room/occupancy/state_machine/`
+— the correct module — best cosine similarity **0.61**. Scoring a warm index takes
+about a millisecond; the only per-query network cost is one embedding call.
+
+## Install
+
+```sh
+dsh plugin --profile web add /path/to/dsh-recall
+```
+
+Then point it at your embedding endpoint. Anything Ollama-compatible works, and
+the endpoint must be stated because `127.0.0.1:11434` is a convention rather than
+a fact:
+
+```yaml
+# your profile's cordis.patch.yml
+- id: dsh-recall
+  name: dsh-recall
+  config:
+    embeddingApiBase: http://10.50.1.2:11434
+```
+
+Or edit every setting from the UI. The plugin ships **two halves**, and the settings
+page draws a card only when it has both:
+
+- the **host half** (`index.js`) serves a `dsh-recall` settings namespace;
+- the **browser half** (`client/client.js`) claims that same namespace with a
+  collapsible card under **Settings → Plugins → Plugin configuration**.
+
+A served namespace with no card renders nothing at all, and a card whose namespace
+is not served is never dispatched — so both are required. A restart is needed for a
+newly installed browser half to appear, because client bundle bytes are snapshotted
+when the profile activates.
+
+Every value is also checkable from the tool, without touching a file:
+
+```
+recall  action=configure  config={"embeddingApiBase":"http://10.50.1.2:11434"}
+```
+
+The API key is declared `role('secret')` on the host, so it is stripped from every
+settings response — the card can show that a key is set without ever receiving it,
+and leaving it blank on save means "unchanged" rather than "clear".
+
+Pull the model once:
+
+```sh
+ollama pull unclemusclez/jina-embeddings-v2-base-code
+```
+
+## The tool
+
+`recall` — three actions plus configuration.
+
+| action | what it does |
+|---|---|
+| `search` *(default)* | answers `query`, warming a bounded slice of the index first |
+| `index` | builds or refreshes the whole index; **background job by default** |
+| `status` | index and endpoint state, touching nothing |
+| `configure` | writes settings through the settings namespace |
+
+Parameters: `query`, `action`, `limit`, `path` (restrict to a subdirectory),
+`run_in_background`.
+
+### What it shows you
+
+Two surfaces, both reading a host projection rather than polling:
+
+- a **chip in the session header** — `Recall 3 · 40× · 457 KB kept out`. No price
+  on it, deliberately: at the measured rate a whole conversation's avoided
+  context is a fraction of a penny, and a chip advertising that reads as the tool
+  being useless rather than as the arithmetic being honest. The tooltip carries
+  the full comparison.
+- a **right-sidebar Recall tab** — the same figures with room for what they are
+  not: *"An estimate, and an upper bound: it assumes a whole file would have been
+  read each time. Token counts are bytes ÷ 4."*
+
+Both render nothing when there is nothing to say — a conversation that never used
+recall costs no layout at all, which matters for the header corner because the
+framework lays it out only while its occupant renders something.
+
+The data path is `presentationMeta` → the `tool/result` event's `meta` → a
+projection unit (`recallUsage`) with a wire view the browser reads through
+`useProjection`. No new event type, no side channel, and nothing leaves the
+machine.
+
+The tool description steers the model on when *not* to use it: prefer `grep` when
+you already know the symbol, `read` when you need the whole file, and do not
+follow up with a `read` of a range you were just handed.
+
+## Focus: letting a conversation see less
+
+A workspace-wide index has to rank across everything, and in a codebase built
+from many near-identical modules that is where embedding similarity fails. On the
+repository this was written against there are **18 controllers** — same idioms,
+same naming, same shape — across 228k lines, and a query about one returns
+plausible fragments of all of them.
+
+Narrowing the index to one of them removes the confusability rather than ranking
+through it:
+
+| | |
+|---|---|
+| median controller scope | **114 chunks, 2.4% of the workspace** |
+| candidate pool | 4,738 → 114 chunks, a **41.6× smaller haystack** |
+| cold start (projected from measured throughput) | **3.1 min → 5s** |
+
+Set it per call, or configure a default:
+
+```
+recall  action=index  focus=src/controllers/room/occupancy
+```
+
+```yaml
+focus: src/controllers/room/occupancy   # or leave empty to resolve by marker
+focusMarkers: [CONTROLLER.md]           # files that make a directory its own scope
+```
+
+Resolution is most-explicit-first: an explicit `focus`, then the nearest
+enclosing directory carrying a marker file, then the workspace. The last fallback
+is the pre-focus behaviour, so adopting this cannot regress a deployment that
+never configures it. **`recall status` lists every scope it can find**, so
+choosing one is a matter of reading the list.
+
+Two things worth knowing, both measured:
+
+- **Scoping hides shared code.** 41.6% of that workspace — 1,972 chunks of shared
+  types, services and infrastructure — sits outside every controller. A weak
+  result inside a scope says so and tells you to retry without it, because a
+  scope is a window, not a relevance filter.
+- **Choosing a scope is explicit, never inferred.** A session sitting at the
+  repository root is not thereby *about* any one controller, and silently
+  confining it to whichever scope sorted first would hide code it needs. So
+  `status` lists them and a caller names one.
+
+## Two opt-in local-model steps
+
+Both are **off by default**, and both are built so that any failure is a
+fallback rather than an error:
+
+| setting | what it does | default |
+|---|---|---|
+| `expansionEnabled` | asks the local model for alternative phrasings, ranks each, and fuses the orders | `false` |
+| `rerankEnabled` | has the local model score the top candidates against the query | `false` |
+
+They are off because **their benefit has not been measured against a real
+model**, and a feature that spends latency on an unquantified gain is not a
+default worth having. Turn them on and run `scripts/baseline.mjs` if you want to
+find out.
+
+### Why the failures matter more than the features
+
+Both run on the critical path of a search, against a model on another box that
+can be slow, wedged, or absent. That is not hypothetical here — the endpoint
+this was developed against spent the whole project in exactly that state. So the
+contracts are narrow:
+
+- **expansion always returns the original query**, first, whatever happens. The
+  worst case is a search with no expansion, never a failed search.
+- **re-ranking returns `undefined` for "no opinion"**, which is deliberately not
+  the same as zero. Replacing a good embedding score with a zero because the
+  model timed out would turn a working search into an empty one.
+- both use their **own deadline** inside the caller's signal, so a slow local
+  model gives up and lets the search continue: cancelling mean stop, being slow
+  does not.
+- a non-finite timeout is **clamped, not propagated** — `AbortSignal.timeout(NaN)`
+  throws, and the catch below it would report that as "the model had nothing to
+  say". A misconfiguration must not wear the disguise of a slow model.
+
+Tested, including the wedged case: a socket that opens and never answers must
+give up on its own deadline rather than pass the wait on.
+
+## Measuring it
+
+`scripts/baseline.mjs` is the before/after instrument, and it reads two stores
+because they answer different questions:
+
+```sh
+node scripts/baseline.mjs          # human report
+node scripts/baseline.mjs --json   # machine readable
+```
+
+- the **cost ledger** knows requests, cache-read tokens, and therefore what each
+  request carried;
+- the **session projection cache** knows the surface each session reached, and
+  whether it used recall at all.
+
+```
+BASELINE
+  sessions                      109
+  requests                      39,706
+  avg context/request (pooled)  339,182    every request counts once
+  avg context/request (typical) 155,175    every session counts once
+  cost                          $160.11
+```
+
+**Both averages are reported on purpose.** They differ by a factor of two here,
+because the largest sessions dominate the pooled figure — quoting only one would
+mislead in whichever direction it happened to favour. Which to use depends on
+the question: pooled is what maps to money, typical is what a new conversation
+should expect.
+
+Sessions that used recall form the "after" group; everything else is the
+baseline. While no session has used it, the report says so rather than printing
+a comparison of nothing against nothing.
+
+## How it works
+
+**Chunking is structure-aware.** Splitting on a fixed line count produces units
+that begin mid-function; their embedding sits between two topics and matches
+neither. Chunks are cut at column-0 declarations instead, neighbouring small
+declarations are merged, and a chunk that absorbs several of them is labelled with
+all of their names — because for a small file that label is the module's only
+description in the index. Minified and generated files are detected and skipped
+rather than indexed as noise.
+
+**Ranking is hybrid, fused by rank.** Pure vector search is weak on code: an
+embedding of `getUserById` sits near every other lookup in the repo. Lexical
+scoring is weak in the opposite direction. The two are combined by reciprocal
+rank fusion rather than by adding normalised scores — min-max normalising a
+cluster of unrelated similarities stretches noise into a confident-looking
+ranking, and rank fusion cannot make that mistake.
+
+**The index is incremental and lives outside your repository.** Files are keyed by
+content hash; only changed files are re-embedded. The SQLite index sits in
+`$DSH_HOME/dsh-recall/workspaces/<key>/` — never in the repo, because for a
+300k-line project it is tens of megabytes. Vectors are stored unit-length, so
+scoring is a dot product.
+
+**Cold start is bounded, and honest.** A search reads and hashes everything
+(fast), then embeds only what fits its time budget, and reports exactly what is
+still pending. `apply` never blocks on embedding a repository. In the measurement
+above, the first search spent its 90s budget on 309 of 684 files (2,257 chunks);
+a full `index` finished the remainder in about 75s more.
+
+**Changing the model or the vector width discards the index** rather than silently
+mixing two incompatible vector spaces into one ranking.
+
+## Honest limitations
+
+- **The 6.0x figure is a comparison, not a guarantee.** It measures what the tool
+  returned against the whole files those results came from. An unusually careful
+  agent might have read only one of those files, so treat it as an upper bound on
+  the saving rather than a promise.
+- **Token figures are `characters / 4`.** An approximation, not a measurement.
+- **Excerpts are capped at 40 lines by default**, so most results in the
+  measurement above were truncated. The excerpt identifies the location; a
+  *targeted* follow-up `read` of that range is still sometimes the right move. The
+  saving is in not reading the other 90% of each file.
+- **A locally built index costs minutes of CPU** on a large repository. It costs
+  no API money, and only once.
+- **Retrieval quality is the model's quality.** A different embedding model will
+  rank differently. `scripts/smoke.mjs` is the check that the top hit is actually
+  correct.
+- **A file edited since it was embedded is flagged `[stale]`**, not silently
+  trusted.
+
+## Operational notes
+
+- The **only outbound request** this plugin makes is to the embedding endpoint you
+  configure. No source code goes anywhere else, and there is no telemetry.
+- The endpoint receives your source code. Point it at infrastructure you trust —
+  that is the whole reason it is explicit configuration rather than a default.
+- The workspace walk **never follows a symlink**, so a link out of the repository
+  cannot cause the machine to be indexed.
+- The index is a cache. Deleting `$DSH_HOME/dsh-recall/` costs one re-embed and
+  nothing else.
+
+### Give the endpoint room
+
+A cold index is a sustained CPU load — hundreds of batched requests. The defaults
+(`embeddingBatchSize: 16`, `embeddingConcurrency: 2`) are deliberately
+conservative, and they were chosen the hard way.
+
+**What happened during development.** An index run at concurrency 4 against a
+small Ollama host that was *also* holding a generation model resident
+(`expires_at` set to the year 2319 — pinned forever) left the host unable to load
+the embedding model. It did not error: it accepted connections and never
+answered. `ollama ps` afterwards showed only the pinned model. That needs a
+restart of the Ollama service on that host; nothing this plugin can do reaches it.
+
+Three things now guard against it:
+
+- **Lower concurrency and batch size by default.** If you raise them, raise them
+  on hardware you know.
+- **`embeddingKeepAlive`** (default `5m`) keeps the embedding model resident for
+  the length of a run instead of letting it be evicted and reloaded between
+  requests.
+- **A short timeout, and a probe.** A wedged endpoint does not refuse a
+  connection, so a long timeout turns a broken backend into a tool call that
+  appears to hang. `recall status` issues a single no-retry probe with a 10-second
+  ceiling and reports whether the endpoint **answered** — which is a different
+  claim from "is configured", and the one worth having.
+
+If `status` reports `endpoint did NOT answer`, check `ollama ps` on that host
+before assuming the plugin is at fault.
+
+## Development
+
+```sh
+npm test              # 91 tests, no network required
+node scripts/smoke.mjs [workspace] [query]     # live retrieval check
+node scripts/measure.mjs [workspace] [query] [budgetMs]
+```
+
+The `lib/` tests run anywhere. `test/config.test.js` and `test/plugin.test.js`
+import `index.js`, which imports `@deepseek-ai/dsh-tools` and
+`@deepseek-ai/schemastery` — resolvable once the plugin is installed into a
+profile (or via a local `node_modules` link to the profile's copies, which the
+`.gitignore` excludes).
+
+`test/plugin.test.js` validates every tool result against **the tool's own
+declared output schema**, which is `additionalProperties: false`. That is not
+pedantry: the host enforces the schema before the model sees a result, so an
+internal field leaking into the returned object is a failed call. It caught
+exactly that during development.
+
+`test/config.test.js` covers the load-time contract. Cordis rejects a `Config`
+before `apply` ever runs, so a broken schema cannot be reported from inside the
+plugin — the profile simply refuses to boot. Every other test in the suite calls
+`apply` directly and would not notice.
+
+`test/client.test.js` runs the browser half in Node by stubbing `window` and
+`require('react')`. That is worth more than it sounds: the two failure modes most
+likely to reach you silently are structural — a root element that is not an `<li>`,
+and a card that does not start collapsed — and both are invisible until someone
+opens Settings. It also pins that an untouched API key is never written or unset.
diff --git a/client/client.js b/client/client.js
new file mode 100644
index 0000000..37c9fee
--- /dev/null
+++ b/client/client.js
@@ -0,0 +1,644 @@
+/**
+ * dsh-recall — browser half: the card in Settings → Plugins → Plugin configuration.
+ *
+ * The Host half registers a `dsh-recall` settings namespace. This file registers
+ * a card under that exact namespace key. Both are required: the tab pairs the
+ * namespaces the Host serves with the cards the browser claims, so a served
+ * namespace with no card draws nothing at all, and a card whose namespace is not
+ * served is never dispatched.
+ *
+ * The chrome follows the framework's `PluginCard`: the root is an `<li>` (the tab
+ * renders every card into a `<ul>`), the header is its own `<button>` that
+ * discloses the controls in place, the card starts collapsed, it marks itself
+ * when it holds unsaved edits, and it collapses again after a successful save.
+ * None of that is imported — `PluginCard` lives in that package's client bundle
+ * and the client purity gate forbids cross-plugin value imports — so the
+ * behaviour is reproduced here rather than borrowed.
+ *
+ * Hand-written plain JavaScript inside the module-loader wrapper, with no build
+ * step and no bundler. The only import is `react`, which is in the platform seed
+ * table. Styling is inline for the same reason: there is no stylesheet this file
+ * may reach.
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-recall',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+
+    const react = require('react')
+
+    const NS = 'dsh-recall'
+    const h = react.createElement
+
+    const TITLE = 'Recall'
+    const DESCRIPTION = 'Local embedding endpoint, what gets indexed, and how many tokens a result may cost.'
+
+    /**
+     * The settings this card edits, grouped for scanning.
+     *
+     * This list mirrors the Host schema in index.js. It is duplicated rather
+     * than fetched because the card renders its own controls — there is no
+     * generic schema-to-form renderer in the framework — and a field the Host
+     * does not know is rejected there anyway, so drift shows up as a clear error
+     * rather than as silent data loss.
+     */
+    const FIELDS = [
+      {
+        key: 'embeddingApiBase',
+        group: 'Endpoint',
+        label: 'Embedding endpoint',
+        hint: 'e.g. http://127.0.0.1:11434 for Ollama. Must be reachable from the machine running the harness.',
+      },
+      {
+        key: 'embeddingModel',
+        group: 'Endpoint',
+        label: 'Embedding model',
+        hint: 'The model id as the endpoint knows it. Changing this discards the existing index.',
+      },
+      {
+        key: 'embeddingDimensions',
+        group: 'Endpoint',
+        label: 'Embedding dimensions',
+        kind: 'number',
+        hint: 'Must match what the model returns. Changing this discards the existing index.',
+      },
+      {
+        key: 'embeddingApiKey',
+        group: 'Endpoint',
+        label: 'Embedding API key',
+        kind: 'secret',
+        hint: 'Stored as a secret and never returned to this page. Leave blank to keep the current value; use Reset to clear it.',
+      },
+      {
+        key: 'embeddingKeepAlive',
+        group: 'Endpoint',
+        label: 'Keep-alive',
+        hint: 'Ollama keep_alive, e.g. 5m. Keeps the model resident for the length of an index run.',
+      },
+      {
+        key: 'embeddingTimeoutMs',
+        group: 'Endpoint',
+        label: 'Request timeout (ms)',
+        kind: 'number',
+        hint: 'Short on purpose. A wedged endpoint accepts the connection and never answers, so a long timeout looks like a hang.',
+      },
+      {
+        key: 'embeddingBatchSize',
+        group: 'Endpoint',
+        label: 'Inputs per request',
+        kind: 'number',
+      },
+      {
+        key: 'embeddingConcurrency',
+        group: 'Endpoint',
+        label: 'Requests in flight',
+        kind: 'number',
+        hint: 'Keep this low on a small host. A cold index is a sustained CPU load, and too much of it can leave the endpoint unable to load the model.',
+      },
+
+      {
+        key: 'extensions',
+        group: 'What gets indexed',
+        label: 'Extensions',
+        kind: 'list',
+        hint: 'Comma separated. Empty uses the built-in code set (no prose or markup).',
+      },
+      {
+        key: 'exclude',
+        group: 'What gets indexed',
+        label: 'Extra exclude patterns',
+        kind: 'list',
+        hint: 'Comma separated globs, e.g. src/generated/. Added to the built-in directory list rather than replacing it.',
+      },
+      {
+        key: 'maxFileBytes',
+        group: 'What gets indexed',
+        label: 'Skip files larger than (bytes)',
+        kind: 'number',
+        hint: 'Generated and minified files are usually large; they are skipped rather than indexed as noise.',
+      },
+      {
+        key: 'maxFiles',
+        group: 'What gets indexed',
+        label: 'Most files to consider',
+        kind: 'number',
+      },
+
+      { key: 'chunkLines', group: 'Chunking', label: 'Target lines per chunk', kind: 'number' },
+      { key: 'maxChunkLines', group: 'Chunking', label: 'Hard cap before splitting', kind: 'number' },
+      {
+        key: 'overlapLines',
+        group: 'Chunking',
+        label: 'Lines shared when splitting',
+        kind: 'number',
+        hint: 'Must be smaller than the hard cap, or a split never advances.',
+      },
+
+      {
+        key: 'excerptLines',
+        group: 'Results',
+        label: 'Lines per excerpt',
+        kind: 'number',
+        hint: 'A chunk is a bounded semantic unit, so this defaults to the chunk cap and results come back whole. Truncating below it is how a search turns into a follow-up read that costs more than it saved.',
+      },
+      {
+        key: 'totalExcerptLines',
+        group: 'Results',
+        label: 'Total lines across one result set',
+        kind: 'number',
+        hint: 'Shared budget, allocated by rank, so the best answer gets the room and the response stays bounded.',
+      },
+      { key: 'defaultLimit', group: 'Results', label: 'Excerpts returned', kind: 'number' },
+      { key: 'maxLimit', group: 'Results', label: 'Most a caller may ask for', kind: 'number' },
+      {
+        key: 'perFileLimit',
+        group: 'Results',
+        label: 'Most chunks from one file',
+        kind: 'number',
+        hint: 'Stops one large file filling the whole result set.',
+      },
+      {
+        key: 'minSimilarity',
+        group: 'Results',
+        label: 'Weak-match threshold',
+        kind: 'number',
+        hint: 'A cosine similarity between 0 and 1. Below this best score, results are reported as a weak match and the model is told to prefer grep.',
+      },
+
+      {
+        key: 'syncBudgetMs',
+        group: 'Index',
+        label: 'Index warm-up budget per search (ms)',
+        kind: 'number',
+        hint: 'How long one search may spend embedding changed files before reporting the rest as pending.',
+      },
+      {
+        key: 'stateDir',
+        group: 'Index',
+        label: 'Index directory',
+        hint: 'Empty uses $DSH_HOME/dsh-recall/workspaces/<workspace>.',
+      },
+    ]
+
+    /** Fields the Host redacts, so the page never holds their real value. */
+    const SECRET_KEYS = new Set(FIELDS.filter((field) => field.kind === 'secret').map((field) => field.key))
+
+    const BORDER = '1px solid var(--dsh-border, #3a3a3a)'
+
+    const S = {
+      // The tab renders into a <ul>, so the root must be an <li> or the list
+      // styling never reaches it.
+      card: { listStyle: 'none', border: BORDER, borderRadius: '8px', margin: '8px 0', overflow: 'hidden' },
+      cardOpen: { background: 'var(--dsh-surface, rgba(255,255,255,0.02))' },
+      header: {
+        display: 'flex',
+        alignItems: 'center',
+        gap: '12px',
+        width: '100%',
+        padding: '12px 16px',
+        border: 'none',
+        background: 'transparent',
+        color: 'inherit',
+        textAlign: 'left',
+        cursor: 'pointer',
+        font: 'inherit',
+      },
+      headText: { display: 'flex', flexDirection: 'column', gap: '2px', flex: '1 1 auto', minWidth: 0 },
+      name: { fontSize: '14px', fontWeight: 600 },
+      description: { fontSize: '11px', opacity: 0.65, lineHeight: 1.45 },
+      pending: {
+        flex: '0 0 auto',
+        fontSize: '10px',
+        textTransform: 'uppercase',
+        letterSpacing: '0.04em',
+        padding: '2px 6px',
+        borderRadius: '4px',
+        border: BORDER,
+        opacity: 0.8,
+      },
+      chevron: { flex: '0 0 auto', fontSize: '10px', opacity: 0.7, transition: 'transform 120ms ease' },
+      chevronOpen: { transform: 'rotate(180deg)' },
+      body: { padding: '0 16px 16px 16px' },
+      readOnly: { fontSize: '11px', opacity: 0.75, marginTop: 0, marginBottom: '12px' },
+      group: {
+        fontSize: '10px',
+        textTransform: 'uppercase',
+        letterSpacing: '0.06em',
+        opacity: 0.55,
+        marginTop: '18px',
+        marginBottom: '2px',
+        paddingBottom: '4px',
+        borderBottom: BORDER,
+      },
+      hint: { fontSize: '11px', opacity: 0.65, marginTop: '2px', lineHeight: 1.45 },
+      row: { marginTop: '12px' },
+      label: { display: 'block', fontSize: '12px', fontWeight: 500, marginBottom: '4px' },
+      input: {
+        width: '100%',
+        boxSizing: 'border-box',
+        padding: '6px 8px',
+        fontSize: '12px',
+        borderRadius: '6px',
+        border: BORDER,
+        background: 'transparent',
+        color: 'inherit',
+      },
+      actions: { display: 'flex', gap: '8px', alignItems: 'center', marginTop: '16px', flexWrap: 'wrap' },
+      button: {
+        padding: '6px 12px',
+        fontSize: '12px',
+        borderRadius: '6px',
+        border: BORDER,
+        background: 'transparent',
+        color: 'inherit',
+        cursor: 'pointer',
+      },
+      primary: { fontWeight: 600 },
+      note: { fontSize: '11px', opacity: 0.75, marginLeft: 'auto' },
+      footer: { fontSize: '11px', opacity: 0.6, marginTop: '16px', lineHeight: 1.5 },
+    }
+
+    /** The editable string form of one field's value. */
+    function toText(field, value) {
+      if (field.kind === 'list') return Array.isArray(value) ? value.join(', ') : ''
+      if (value === undefined || value === null) return ''
+      return String(value)
+    }
+
+    /** The value to write for one field, from its string form. */
+    function fromText(field, text) {
+      const trimmed = typeof text === 'string' ? text.trim() : ''
+      if (field.kind === 'number') return Number(trimmed)
+      if (field.kind === 'list') {
+        return trimmed === ''
+          ? []
+          : trimmed
+              .split(/[,\n]/)
+              .map((part) => part.trim())
+              .filter((part) => part !== '')
+      }
+      return text
+    }
+
+    /** Build a draft of every field from a resolved section. */
+    function toDraft(value) {
+      const draft = {}
+      for (const field of FIELDS) draft[field.key] = toText(field, value?.[field.key])
+      return draft
+    }
+
+    function Field(props) {
+      const { field, value, overridden, disabled, onChange } = props
+      const common = {
+        style: S.input,
+        value,
+        disabled,
+        'aria-label': field.label,
+        onChange: (event) => onChange(event.target.value),
+      }
+      return h(
+        'div',
+        { style: S.row },
+        h(
+          'label',
+          { style: S.label },
+          field.label,
+          overridden ? h('span', { style: { opacity: 0.6, fontWeight: 400 } }, ' · overridden') : null,
+        ),
+        h('input', {
+          ...common,
+          type: field.kind === 'secret' ? 'password' : 'text',
+          ...(field.kind === 'secret' ? { placeholder: '(unchanged)' } : {}),
+        }),
+        field.hint === undefined ? null : h('div', { style: S.hint }, field.hint),
+      )
+    }
+
+    function Card(props) {
+      const scope = props.scope
+      const [snapshot, setSnapshot] = react.useState(() => scope.getSnapshot())
+      const [draft, setDraft] = react.useState(null)
+      const [busy, setBusy] = react.useState(false)
+      const [note, setNote] = react.useState('')
+      // Collapsed on mount, like every other card in the tab.
+      const [open, setOpen] = react.useState(false)
+
+      react.useEffect(() => scope.subscribe(() => setSnapshot(scope.getSnapshot())), [scope])
+
+      const status = snapshot.status
+      const value = snapshot.value
+      const baseline = react.useMemo(() => toDraft(value), [value])
+      const current = draft ?? baseline
+      const user = snapshot.user
+
+      if (status === 'unavailable') {
+        // A deployment without the Host half, or a remote browser: show no trace.
+        return null
+      }
+
+      const dirtyKeys = FIELDS.filter((field) => current[field.key] !== baseline[field.key]).map((field) => field.key)
+      const overriddenKeys = user !== null && typeof user === 'object' ? Object.keys(user) : []
+      const writable = snapshot.writable === true
+
+      const save = async () => {
+        setBusy(true)
+        setNote('')
+        try {
+          for (const field of FIELDS) {
+            const next = current[field.key]
+            if (next === baseline[field.key]) continue
+            const trimmed = String(next).trim()
+            // A redacted secret always reads as blank. Blank therefore means
+            // "leave it alone", not "clear it" — otherwise opening this card and
+            // pressing Save would silently delete the key.
+            if (SECRET_KEYS.has(field.key) && trimmed === '') continue
+            // Clearing any other field is an unset, not a write of "", so the
+            // value re-inherits the composition layer instead of becoming empty.
+            if (trimmed === '') await scope.unset(field.key)
+            else await scope.set(field.key, fromText(field, next))
+          }
+          setDraft(null)
+          setNote('Saved.')
+          // A landed save folds the card back up. A failed or blocked one stays
+          // open with the drafts, which is the whole point of staging them.
+          setOpen(false)
+        } catch (error) {
+          setNote(`Save failed: ${error?.message ?? error}`)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const reset = async () => {
+        setBusy(true)
+        setNote('')
+        try {
+          for (const key of overriddenKeys) await scope.unset(key)
+          setDraft(null)
+          setNote('Reset to the deployment defaults.')
+        } catch (error) {
+          setNote(`Reset failed: ${error?.message ?? error}`)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const rows = []
+      let group
+      for (const field of FIELDS) {
+        if (field.group !== group) {
+          group = field.group
+          rows.push(h('div', { key: `group-${group}`, style: S.group }, group))
+        }
+        rows.push(
+          h(Field, {
+            key: field.key,
+            field,
+            value: current[field.key],
+            overridden: overriddenKeys.includes(field.key),
+            disabled: busy || !writable,
+            onChange: (next) => setDraft({ ...current, [field.key]: next }),
+          }),
+        )
+      }
+
+      return h(
+        'li',
+        { style: open ? { ...S.card, ...S.cardOpen } : S.card },
+        h(
+          'button',
+          {
+            type: 'button',
+            style: S.header,
+            'aria-expanded': open,
+            'aria-label': `${open ? 'Collapse' : 'Expand'}: ${TITLE}`,
+            onClick: () => setOpen(!open),
+          },
+          h(
+            'span',
+            { style: S.headText },
+            h('span', { style: S.name }, TITLE),
+            h('span', { style: S.description }, DESCRIPTION),
+          ),
+          // Marked on the header, so unsaved edits are visible while collapsed.
+          dirtyKeys.length > 0 ? h('span', { style: S.pending }, 'unsaved') : null,
+          h('span', { style: open ? { ...S.chevron, ...S.chevronOpen } : S.chevron }, '▾'),
+        ),
+        open
+          ? h(
+              'div',
+              { style: S.body },
+              writable ? null : h('p', { style: S.readOnly, role: 'status' }, 'This namespace is read-only here.'),
+              ...rows,
+              h(
+                'div',
+                { style: S.actions },
+                h(
+                  'button',
+                  { type: 'button', style: { ...S.button, ...S.primary }, disabled: busy || dirtyKeys.length === 0, onClick: save },
+                  dirtyKeys.length === 0 ? 'Save' : `Save ${dirtyKeys.length} change${dirtyKeys.length === 1 ? '' : 's'}`,
+                ),
+                h(
+                  'button',
+                  { type: 'button', style: S.button, disabled: busy || overriddenKeys.length === 0, onClick: reset },
+                  `Reset ${overriddenKeys.length} override${overriddenKeys.length === 1 ? '' : 's'}`,
+                ),
+                note === '' ? null : h('span', { style: S.note }, note),
+              ),
+              h(
+                'p',
+                { style: S.footer },
+                'Values are checked when saved, not when next used. The endpoint is not contacted here — run ' +
+                  'recall with action "status" to probe it.',
+              ),
+            )
+          : null,
+      )
+    }
+
+    /**
+     * Register the card, but only once a settings transport exists.
+     *
+     * `ctx.inject(['settingsScope'], …)` rather than a top-level `inject`,
+     * because a required dependency that is unsatisfied means this plugin never
+     * applies at all — the card would vanish along with everything else instead
+     * of simply not appearing.
+     */
+    /** The projection key the host half registers. */
+    const USAGE_KEY = 'recallUsage'
+
+    /** Byte counts a person reads at a glance. */
+    function humanBytes(bytes) {
+      if (!Number.isFinite(bytes) || bytes <= 0) return '0'
+      if (bytes < 1024) return bytes + ' B'
+      if (bytes < 1024 * 1024) return Math.round(bytes / 1024) + ' KB'
+      return (bytes / (1024 * 1024)).toFixed(1) + ' MB'
+    }
+
+    /**
+     * Read the usage projection, whatever the slot can offer.
+     *
+     * Called unconditionally and before any early return, because it is a hook:
+     * a conditional call would break the moment the chip had nothing to show,
+     * which is its normal state in a conversation that has not used the tool.
+     */
+    function useUsage(props) {
+      if (typeof props.useProjection !== 'function') return undefined
+      return props.useProjection(USAGE_KEY)
+    }
+
+    /**
+     * The one-line summary: what it kept out, not what it cost.
+     *
+     * The dollar figure is deliberately absent here. At the measured cache-read
+     * rate a whole conversation's avoided context is worth a fraction of a
+     * penny, and a chip advertising that would be read as the tool being
+     * useless rather than as the arithmetic being honest. The detail lives in
+     * the tab and in the tooltip.
+     */
+    function chipText(usage) {
+      const parts = ['Recall ' + usage.searches]
+      if (usage.compression > 1) parts.push(usage.compression + '\u00d7')
+      if (usage.avoidedBytes > 0) parts.push(humanBytes(usage.avoidedBytes) + ' kept out')
+      return parts.join(' \u00b7 ')
+    }
+
+    /** Everything a hover can hold, including what is not worth a chip. */
+    function chipDetail(usage) {
+      const lines = [
+        usage.searches + ' search' + (usage.searches === 1 ? '' : 'es') + (usage.indexes ? ', ' + usage.indexes + ' index' : ''),
+        usage.excerpts + ' excerpt' + (usage.excerpts === 1 ? '' : 's') + ' from ' + usage.files + ' file' + (usage.files === 1 ? '' : 's'),
+        humanBytes(usage.returnedBytes) + ' returned where ' + humanBytes(usage.sourceBytes) + ' would have been read',
+      ]
+      if (usage.rereadTokens > 0) {
+        lines.push(
+          'about ' + usage.rereadTokens.toLocaleString() + ' tokens re-read since, if those files had been read in full',
+        )
+      }
+      lines.push('estimate: reading every file the excerpts came from, not a measurement of what you would have done')
+      return lines.join('\n')
+    }
+
+    function RecallChip(props) {
+      const usage = useUsage(props)
+      // The corner is laid out only while its occupant renders something, so a
+      // conversation that never called the tool costs no layout at all.
+      if (usage === undefined || !usage.searches) return null
+      return h(
+        'span',
+        {
+          title: chipDetail(usage),
+          'aria-label': chipText(usage) + ' \u2014 recall usage for this conversation',
+          style: {
+            fontSize: '11px',
+            opacity: 0.75,
+            whiteSpace: 'nowrap',
+            padding: '2px 8px',
+            borderRadius: '999px',
+            border: '1px solid var(--dsh-border, #3a3a3a)',
+          },
+        },
+        chipText(usage),
+      )
+    }
+
+    function RecallTabTitle() {
+      return h('span', { style: { fontSize: '12px' } }, 'Recall')
+    }
+
+    /** One labelled figure in the panel. */
+    function Figure(props) {
+      const { label, value, note } = props
+      return h(
+        'div',
+        { style: { marginBottom: '10px' } },
+        h('div', { style: { fontSize: '11px', opacity: 0.6 } }, label),
+        h('div', { style: { fontSize: '15px', fontWeight: 600 } }, value),
+        note === undefined ? null : h('div', { style: { fontSize: '11px', opacity: 0.6, lineHeight: 1.4 } }, note),
+      )
+    }
+
+    function RecallPanel(props) {
+      const usage = useUsage(props)
+      if (usage === undefined) {
+        // A host without the projection, or a session that predates it. Say so
+        // rather than showing zeroes, which would read as "this did nothing".
+        return h('div', { style: { padding: '16px', fontSize: '12px', opacity: 0.7 } }, 'Recall usage is not available for this conversation.')
+      }
+      if (!usage.searches && !usage.indexes) {
+        return h(
+          'div',
+          { style: { padding: '16px', fontSize: '12px', opacity: 0.7, lineHeight: 1.5 } },
+          'This conversation has not used recall yet. It returns ranked excerpts instead of whole files, so context it keeps out is never re-sent on a later step.',
+        )
+      }
+
+      const head = usage.compression > 1 ? usage.compression + '\u00d7' : '\u2014'
+      return h(
+        'div',
+        { style: { padding: '16px', fontSize: '12px' } },
+        h(Figure, {
+          label: 'Kept out of this conversation',
+          value: humanBytes(usage.avoidedBytes),
+          note: humanBytes(usage.returnedBytes) + ' returned, where reading those files would have been ' + humanBytes(usage.sourceBytes),
+        }),
+        h(Figure, {
+          label: 'Smaller than reading the files',
+          value: head,
+          note: 'The excerpt is a slice; the comparison is against the whole of each file it came from.',
+        }),
+        h(Figure, {
+          label: 'Re-read since',
+          value: usage.rereadTokens > 0 ? '~' + usage.rereadTokens.toLocaleString() + ' tokens' : 'not yet',
+          note: 'Context a conversation carries is re-sent on every later step. Avoided context is avoided every time.',
+        }),
+        h(Figure, {
+          label: 'Searches',
+          value: String(usage.searches) + (usage.indexes ? ' + ' + usage.indexes + ' indexed' : ''),
+          note: usage.excerpts + ' excerpts from ' + usage.files + ' files' + (usage.weak ? '; ' + usage.weak + ' too weak to use' : ''),
+        }),
+        h(
+          'p',
+          { style: { fontSize: '11px', opacity: 0.6, lineHeight: 1.5, marginTop: '4px' } },
+          'An estimate, and an upper bound: it assumes a whole file would have been read each time. Token counts are bytes \u00f7 4.',
+        ),
+      )
+    }
+
+    function apply(ctx) {
+      // The chip and the panel are session-scoped, so the framework hands them
+      // `useProjection` as a standard prop — the same wire view the host
+      // projection registers. Both render nothing when there is nothing to say.
+      ctx.slots.inject('conversation.session.header.corner', () =>
+        ctx.slots.register({ name: 'conversation.session.header.corner' }, (props) => h(RecallChip, props)),
+      )
+      ctx.slots.inject('sidebar.right.pane.tab', () =>
+        ctx.slots.register({ name: 'sidebar.right.pane.tab', key: NS }, (props) => h(RecallPanel, props)),
+      )
+      ctx.slots.inject('sidebar.right.pane.tab.title', () =>
+        ctx.slots.register({ name: 'sidebar.right.pane.tab.title', key: NS }, () => h(RecallTabTitle)),
+      )
+
+      ctx.inject(['settingsScope'], (scoped) => {
+        const binder = scoped.settingsScope
+        if (binder === undefined) return
+        const scope = binder.bind({ namespace: NS })
+        scoped.slots.inject('settings.plugin.item', () =>
+          scoped.slots.register(
+            {
+              name: 'settings.plugin.item',
+              key: NS,
+              inject: () => ({ scope }),
+            },
+            (props) => h(Card, props),
+          ),
+        )
+      })
+    }
+
+    module.exports = { name: NS, inject: ['slots'], apply }
+    return module.exports
+  },
+})
diff --git a/cordis.patch.yml b/cordis.patch.yml
new file mode 100644
index 0000000..57d91d3
--- /dev/null
+++ b/cordis.patch.yml
@@ -0,0 +1,21 @@
+# The layer this bundle contributes to a dsh profile that lists it.
+#
+# One row: the dsh-recall host plugin, which registers exactly one tool
+# (`recall`) on `ctx.tools` and one settings namespace on `ctx.settings`.
+#
+# There is deliberately NO `config:` block. Every value the plugin needs is
+# either discovered at runtime (the workspace, from the calling session) or
+# carried by a schema default that is honest for any machine. The embedding
+# endpoint is the one field a real deployment usually has to state, because the
+# Ollama default of 127.0.0.1 is a convention rather than a fact — so it belongs
+# in the profile's own patch layer, where the machine's address is known, and
+# not baked into a layer that other machines also apply:
+#
+#   - id: dsh-recall
+#     name: dsh-recall
+#     config:
+#       embeddingApiBase: http://10.50.1.2:11434
+
+- insert:
+    - id: dsh-recall
+      name: dsh-recall
diff --git a/index.js b/index.js
new file mode 100644
index 0000000..db749a7
--- /dev/null
+++ b/index.js
@@ -0,0 +1,1279 @@
+/**
+ * dsh-recall — local-embedding code recall for DeepSeek Harness.
+ *
+ * One tool (`recall`) over a per-workspace vector index built by a local
+ * embedding model, plus a settings namespace so the endpoint is editable at
+ * runtime.
+ *
+ * **The economics this exists for.** In a long agent session the dominant cost
+ * is not the model's reasoning; it is re-reading the accumulated transcript on
+ * every step. Measured on this harness over 32 days, 65% of spend was re-reading
+ * cached context and 96% of that context was message history — mostly file
+ * contents the agent had already read. A tool that answers "where is this
+ * handled" with a ranked 40-line excerpt instead of four whole files keeps that
+ * history small, and the saving compounds on every subsequent step because the
+ * context it did not add is never re-sent again.
+ *
+ * **Why the index is warmed lazily rather than at load.** `apply` must not block
+ * on embedding a repository; a plugin that took minutes to activate would make
+ * every profile start slow, including the ones that never call the tool. Instead
+ * a search does a *bounded* sync — read and hash everything, embed only what
+ * fits in a time budget — and reports honestly what is still pending. A full
+ * warm-up is available as an explicit background action.
+ *
+ * **Why there is a settings namespace and no baked endpoint.** The Ollama
+ * default of `127.0.0.1:11434` is a convention, not a fact — this deployment
+ * runs Ollama on another host. Baking one machine's address into a bundle layer
+ * that other machines apply is exactly the mistake the composition docs warn
+ * about, so the endpoint is a schema default the profile can override.
+ */
+
+import { readFile, stat } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { basename, join, resolve } from 'node:path'
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+// A real dependency rather than a duck-typed `{ parse }`: the projection service
+// calls these schemas, and `dsh-session-projection` declares zod itself, so it is
+// present wherever projections are.
+import { z } from 'zod'
+import Schema from '@deepseek-ai/schemastery'
+
+import { chunkFile, embedText } from './lib/chunk.js'
+import { EmbeddingError, createEmbedder } from './lib/embed.js'
+import { DEFAULT_FOCUS_MARKERS, discoverScopes, focusKey, resolveFocus } from './lib/focus.js'
+import { indexFile, resolveDshHome, workspaceStateDir } from './lib/paths.js'
+import { fuseRankings, rankOrder, selectFrom } from './lib/rank.js'
+import { RecallIndex } from './lib/store.js'
+import { createExpander } from './lib/expand.js'
+import { createReranker } from './lib/rerank.js'
+import { deriveUsage, emptyUsage, foldUsage, usageSummary } from './lib/usage.js'
+import { DEFAULT_EXTENSIONS, DEFAULT_SKIP_DIRS, listCodeFiles } from './lib/walk.js'
+
+/** Settings namespace. Must match /^[a-z][a-z0-9-]*$/. */
+const SETTINGS_NAMESPACE = 'dsh-recall'
+
+/** Every configuration field this plugin exposes. */
+export const SETTING_KEYS = [
+  'embeddingApiBase',
+  'embeddingModel',
+  'embeddingDimensions',
+  'embeddingApiKey',
+  'embeddingBatchSize',
+  'embeddingConcurrency',
+  'embeddingTimeoutMs',
+  'embeddingKeepAlive',
+  'extensions',
+  'exclude',
+  'maxFiles',
+  'maxFileBytes',
+  'chunkLines',
+  'maxChunkLines',
+  'overlapLines',
+  'defaultLimit',
+  'maxLimit',
+  'perFileLimit',
+  'excerptLines',
+  'totalExcerptLines',
+  'minSimilarity',
+  'syncBudgetMs',
+  'stateDir',
+  'focus',
+  'focusMarkers',
+  'expansionEnabled',
+  'expansionModel',
+  'expansionCount',
+  'expansionTimeoutMs',
+  'rerankEnabled',
+  'rerankModel',
+  'rerankCandidates',
+  'rerankTimeoutMs',
+]
+
+export const Config = Schema.object({
+  /** Embedding endpoint, without a trailing slash. */
+  embeddingApiBase: Schema.string().default('http://127.0.0.1:11434'),
+  /** Model id as the endpoint knows it. */
+  embeddingModel: Schema.string().default('unclemusclez/jina-embeddings-v2-base-code:latest'),
+  /** Vector width. Must match the model; a mismatch is refused, not truncated. */
+  embeddingDimensions: Schema.number().default(768),
+  /** Bearer token for a gateway that wants one. */
+  // `role('secret')` keeps this out of every settings response: the wire
+  // surfaces strip schema-declared secret positions, so a card can report that a
+  // key is set without ever receiving it.
+  embeddingApiKey: Schema.string().default('').role('secret'),
+  /** Inputs per request on the batch endpoint. */
+  embeddingBatchSize: Schema.number().default(16),
+  /** Requests in flight. */
+  embeddingConcurrency: Schema.number().default(2),
+  /**
+   * Per-request timeout.
+   *
+   * Deliberately short. A local endpoint that has wedged does not refuse the
+   * connection — it accepts it and never answers, so a long timeout turns a
+   * broken backend into a tool call that appears to hang. Thirty seconds is far
+   * more than a batch of a few thousand characters needs on any CPU, and it
+   * fails in bounded time instead of leaving the caller guessing.
+   */
+  embeddingTimeoutMs: Schema.number().default(30_000),
+  /** Ollama `keep_alive`. Keeps the model resident across an index run. */
+  embeddingKeepAlive: Schema.string().default('5m'),
+  /** Extensions to index. Empty means the built-in code set. */
+  extensions: Schema.array(String).default([]),
+  /** Extra glob patterns to skip, on top of the built-in directory list. */
+  exclude: Schema.array(String).default([]),
+  /** Most files a workspace walk will consider. */
+  maxFiles: Schema.number().default(20_000),
+  /** Files larger than this are skipped as generated. */
+  maxFileBytes: Schema.number().default(1_048_576),
+  /** Target lines per chunk. */
+  chunkLines: Schema.number().default(48),
+  /** Hard cap before a chunk is split. */
+  maxChunkLines: Schema.number().default(80),
+  /** Lines shared between the halves of a split chunk. */
+  overlapLines: Schema.number().default(8),
+  /** Results returned when the caller does not say. */
+  defaultLimit: Schema.number().default(8),
+  /** Ceiling on the caller's `limit`. */
+  maxLimit: Schema.number().default(25),
+  /** Most chunks one file may contribute to one result set. */
+  perFileLimit: Schema.number().default(2),
+  /**
+   * Lines shown per excerpt.
+   *
+   * Defaults to the chunk cap, so a chunk — already a bounded semantic unit —
+   * is returned whole. Cutting one in half is how a search turns into a
+   * follow-up read that costs more than the lines it saved.
+   */
+  excerptLines: Schema.number().default(80),
+  /** Total lines across one result set, allocated by rank. */
+  totalExcerptLines: Schema.number().default(400),
+  /** Below this best-similarity, the result set is reported as weak. */
+  minSimilarity: Schema.number().default(0.2),
+  /** Embedding time one `search` call may spend warming the index. */
+  syncBudgetMs: Schema.number().default(20_000),
+  /** Index directory. Empty means `$DSH_HOME/dsh-recall/workspaces/<key>`. */
+  stateDir: Schema.string().default(''),
+  /**
+   * Narrows the index and every search to one directory.
+   *
+   * Empty resolves by marker: the nearest ancestor of the session's directory
+   * carrying a `focusMarkers` file becomes the scope, and the workspace root is
+   * the fallback — which is the behaviour that existed before focus did, so
+   * adopting this cannot regress a deployment that never configures it.
+   */
+  focus: Schema.string().default(''),
+  /** Filenames that mark a directory as its own scope. Empty means the built-ins. */
+  focusMarkers: Schema.array(String).default([]),
+  /**
+   * Ask the local model for alternative phrasings and fuse the rankings.
+   *
+   * Off by default. It costs one local generation plus an embedding per variant,
+   * and its benefit has not been measured against a real model — a default that
+   * spends latency on an unquantified gain is not a default worth having.
+   */
+  expansionEnabled: Schema.boolean().default(false),
+  /** Model that writes the phrasings. Empty uses `embeddingModel`'s endpoint, not its model. */
+  expansionModel: Schema.string().default(''),
+  /** Most variants to ask for. */
+  expansionCount: Schema.number().default(4),
+  /** Budget for the whole expansion, in ms. Expiry just means search without it. */
+  expansionTimeoutMs: Schema.number().default(8_000),
+  /**
+   * Have the local model score the top candidates against the query.
+   *
+   * Off by default for the same reason, and more so: it is one more model call
+   * on the critical path of every search.
+   */
+  rerankEnabled: Schema.boolean().default(false),
+  /** Model that scores candidates. */
+  rerankModel: Schema.string().default(''),
+  /** Candidates scored per search. The reranker caps this at 12. */
+  rerankCandidates: Schema.number().default(8),
+  /** Budget for the scoring call, in ms. */
+  rerankTimeoutMs: Schema.number().default(15_000),
+})
+
+/** Resolve the harness home, preferring the harness's own resolver. */
+function dshHomeOf(ctx) {
+  try {
+    const homePath = ctx.get('dshHomePath')
+    if (typeof homePath === 'function') {
+      const resolved = homePath()
+      if (typeof resolved === 'string' && resolved !== '') return resolved
+    }
+  } catch {
+    // Declared optional; absent outside dsh-app-boot, which is expected.
+  }
+  return resolveDshHome()
+}
+
+/**
+ * Constraints the settings schema cannot express.
+ *
+ * Run by the settings provider when a value is WRITTEN, not when it is next
+ * used. That distinction is the point: a bad endpoint or an impossible limit
+ * should fail in front of the person who typed it, rather than surfacing later
+ * as a failed search with no obvious cause.
+ *
+ * @param {Record<string, any>} value a schema-valid settings section
+ * @throws {Error} when the section cannot be acted on
+ */
+export function validateSettings(value) {
+  const base = String(value.embeddingApiBase ?? '').trim()
+  let url
+  try {
+    url = new URL(base)
+  } catch {
+    throw new Error(`embeddingApiBase is not a URL: ${JSON.stringify(base)}`)
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`embeddingApiBase must be http or https, not ${url.protocol}`)
+  }
+  if (!(Number(value.embeddingDimensions) > 0)) {
+    throw new Error('embeddingDimensions must be a positive number')
+  }
+  for (const key of [
+    'embeddingBatchSize',
+    'embeddingConcurrency',
+    'embeddingTimeoutMs',
+    'maxLimit',
+    'defaultLimit',
+    'perFileLimit',
+    'excerptLines',
+    'totalExcerptLines',
+    'chunkLines',
+    'maxChunkLines',
+    'maxFiles',
+    'maxFileBytes',
+    'expansionCount',
+    'expansionTimeoutMs',
+    'rerankCandidates',
+    'rerankTimeoutMs',
+  ]) {
+    if (!(Number(value[key]) >= 1)) throw new Error(`${key} must be at least 1`)
+  }
+  if (Number(value.syncBudgetMs) < 0) throw new Error('syncBudgetMs cannot be negative')
+  if (Number(value.overlapLines) < 0) throw new Error('overlapLines cannot be negative')
+  if (Number(value.maxChunkLines) < Number(value.chunkLines)) {
+    throw new Error('maxChunkLines cannot be below chunkLines')
+  }
+  if (Number(value.overlapLines) >= Number(value.maxChunkLines)) {
+    throw new Error('overlapLines must be smaller than maxChunkLines, or a split never advances')
+  }
+  if (Number(value.defaultLimit) > Number(value.maxLimit)) {
+    throw new Error(`defaultLimit (${value.defaultLimit}) cannot exceed maxLimit (${value.maxLimit})`)
+  }
+  if (Number(value.minSimilarity) < 0 || Number(value.minSimilarity) > 1) {
+    throw new Error('minSimilarity is a cosine similarity and must be between 0 and 1')
+  }
+}
+
+/** SHA-256 of file content, used as the change key. */
+function hashOf(content) {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+/**
+ * Serialise work per key.
+ *
+ * Two tool calls can arrive while the first is still warming the index, and two
+ * concurrent syncs of the same workspace would interleave writes to one SQLite
+ * handle. Chaining on a per-workspace promise makes the second wait rather than
+ * race, which is what lets `search` stay marked concurrency-safe.
+ */
+function createLock() {
+  const chains = new Map()
+  return async function withLock(key, work) {
+    const previous = chains.get(key) ?? Promise.resolve()
+    let release
+    const gate = new Promise((resolveGate) => {
+      release = resolveGate
+    })
+    chains.set(
+      key,
+      previous.then(() => gate),
+    )
+    await previous
+    try {
+      return await work()
+    } finally {
+      release()
+      if (chains.get(key) === gate) chains.delete(key)
+    }
+  }
+}
+
+/**
+ * Schema of the persisted fold.
+ *
+ * The projection stores state as plain JSON and validates it with `.parse()`
+ * before seeding a fold from a checkpoint, so this must accept exactly what
+ * `emptyUsage()` produces and what `foldUsage` returns.
+ */
+const usageStateSchema = z.object({
+  version: z.number(),
+  searches: z.number(),
+  indexes: z.number(),
+  failed: z.number(),
+  excerpts: z.number(),
+  returnedBytes: z.number(),
+  sourceBytes: z.number(),
+  files: z.number(),
+  weak: z.number(),
+  rereadBytes: z.number(),
+  lastFocus: z.string(),
+})
+
+/** Schema of the wire view — what the browser receives. */
+const usageViewSchema = z.object({
+  searches: z.number(),
+  indexes: z.number(),
+  failed: z.number(),
+  excerpts: z.number(),
+  files: z.number(),
+  weak: z.number(),
+  returnedBytes: z.number(),
+  sourceBytes: z.number(),
+  avoidedBytes: z.number(),
+  avoidedTokens: z.number(),
+  compression: z.number(),
+  rereadTokens: z.number(),
+  avoidedUsd: z.number(),
+  lastFocus: z.string(),
+})
+
+/**
+ * Per-conversation recall usage, folded from the tool metadata in the log.
+ *
+ * A projection rather than a client-side fold over conversation nodes: nodes
+ * carry only the loaded window, so a chip built on them would undercount the
+ * moment a session outgrew what the browser had scrolled through. This folds
+ * the whole log and is replayed from it.
+ */
+const USAGE_KEY = 'recallUsage'
+
+/** Views are compared by reference, so one state must yield one view object. */
+const usageViews = new WeakMap()
+
+function usageViewFor(state) {
+  let view = usageViews.get(state)
+  if (view === undefined) {
+    view = usageSummary(state)
+    usageViews.set(state, view)
+  }
+  return view
+}
+
+export const usageProjection = {
+  key: USAGE_KEY,
+  stateSchema: usageStateSchema,
+  init: () => emptyUsage(),
+  apply: (state, event) => foldUsage(state, event),
+  stateVersion: 1,
+  wire: { viewSchema: usageViewSchema, view: usageViewFor },
+}
+
+export const name = 'dsh-recall'
+export const inject = ['tools']
+
+/**
+ * Register the tool and the settings namespace.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, any>} config validated composition config
+ */
+export function apply(ctx, config) {
+  const logger = ctx.logger('dsh-recall')
+  const dshHome = dshHomeOf(ctx)
+  const withLock = createLock()
+
+  // Discovered scopes per workspace, cached for a short window. Discovery is a
+  // directory walk on the hot path of every tool call, and re-walking a large
+  // repository to learn something that changes only when a marker file is added
+  // is work with no benefit.
+  const SCOPE_CACHE_MS = 30_000
+  const scopeCache = new Map()
+
+  // Open indexes are filesystem handles, so they are an effect: Cordis closes
+  // them on unload and on a config change, and a reload never leaks a handle.
+  const openIndexes = new Map()
+  ctx.effect(() => () => {
+    for (const index of openIndexes.values()) index.close()
+    openIndexes.clear()
+  })
+
+  // The authoritative settings source. Starts as the composition config and is
+  // replaced by the settings scope's thunk once a provider attaches.
+  let readSettings = () => config
+  let writeSettings
+
+  // Per-conversation usage, folded from the tool metadata the log already
+  // carries. Optional: a profile without projections still gets the tool, it
+  // just does not get a surface that reports what it saved.
+  ctx.inject(['sessionProjections'], (projectionCtx) => {
+    try {
+      projectionCtx.sessionProjections.register(usageProjection)
+    } catch (error) {
+      logger.warn('dsh-recall: usage projection unavailable: %s', error?.message ?? error)
+    }
+  })
+
+  ctx.inject(['settings'], (settingsCtx) => {
+    try {
+      settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+        setSource: (current) => {
+          readSettings = current
+        },
+        // Settings changes take effect on the next call: the embedder is built
+        // per call, and `recheck` re-validates the stored embedding identity
+        // against the new snapshot, so there are no registration-level facts to
+        // re-judge here.
+        onChange: () => {},
+        // Constraints the schema cannot express, refused at WRITE time rather
+        // than discovered on the next search.
+        validate: validateSettings,
+      })
+      writeSettings = (patch) => settingsCtx.settings.update(SETTINGS_NAMESPACE, patch)
+    } catch (error) {
+      logger.warn('dsh-recall: settings namespace unavailable: %s', error?.message ?? error)
+    }
+  })
+
+  /** The embedder for a settings snapshot. */
+  const embedderFor = (settings) =>
+    createEmbedder({
+      apiBase: String(settings.embeddingApiBase),
+      model: String(settings.embeddingModel),
+      dimensions: Number(settings.embeddingDimensions),
+      apiKey: String(settings.embeddingApiKey ?? ''),
+      batchSize: Number(settings.embeddingBatchSize),
+      concurrency: Number(settings.embeddingConcurrency),
+      timeoutMs: Number(settings.embeddingTimeoutMs),
+      keepAlive: String(settings.embeddingKeepAlive ?? ''),
+    })
+
+  /**
+   * A one-shot embedder for probing the endpoint.
+   *
+   * No retries and a short timeout, because a probe exists to answer a question
+   * quickly: `status` should report a wedged backend, not wait for one. Three
+   * retries against a socket that accepts and never replies would take longer
+   * than the tool call that provoked it.
+   */
+  const proberFor = (settings) =>
+    createEmbedder({
+      apiBase: String(settings.embeddingApiBase),
+      model: String(settings.embeddingModel),
+      dimensions: Number(settings.embeddingDimensions),
+      apiKey: String(settings.embeddingApiKey ?? ''),
+      batchSize: 1,
+      concurrency: 1,
+      timeoutMs: Math.min(Number(settings.embeddingTimeoutMs), 10_000),
+      maxAttempts: 1,
+      keepAlive: String(settings.embeddingKeepAlive ?? ''),
+    })
+
+  /**
+   * The index fields the tool's output schema declares.
+   *
+   * Built by picking rather than by spreading the sync result, because that
+   * result also carries internal fields (`stale`, `chunksWritten`) which are not
+   * part of the model-facing contract — and the schema is
+   * `additionalProperties: false`, so spreading one in is a validation failure
+   * rather than a harmless extra.
+   */
+  function indexView(current, extra = {}) {
+    const out = { ...current }
+    const fields = [
+      'files',
+      'chunks',
+      'pending',
+      'scanned',
+      'embedded',
+      'removed',
+      'oversized',
+      'unreadable',
+      'truncated',
+    ]
+    for (const key of fields) if (extra[key] !== undefined) out[key] = extra[key]
+    return out
+  }
+
+  /**
+   * Discovered scopes for a workspace, cached briefly.
+   *
+   * Discovery is a directory walk, not a file read, so it is cheap — but it runs
+   * on every tool call and a large repository has a lot of directories. A short
+   * cache keeps the cost off the hot path while still noticing a marker file
+   * added a moment ago.
+   *
+   * @param {string} workspace absolute workspace root
+   * @param {readonly string[]} markers marker filenames
+   */
+  async function scopesFor(workspace, markers) {
+    const key = `${workspace}\u0000${markers.join(',')}`
+    const hit = scopeCache.get(key)
+    if (hit !== undefined && Date.now() - hit.at < SCOPE_CACHE_MS) return hit.scopes
+    let scopes = []
+    try {
+      scopes = await discoverScopes({ workspace, markers })
+    } catch {
+      // A workspace that cannot be walked simply has no discoverable scopes;
+      // resolution still falls back to markers and then the workspace.
+      scopes = []
+    }
+    cacheScopes(key, scopes)
+    return scopes
+  }
+
+  /** Replace the scope cache, dropping entries for workspaces that are gone. */
+  function cacheScopes(key, scopes) {
+    scopeCache.set(key, { at: Date.now(), scopes })
+    if (scopeCache.size > 32) {
+      for (const [existing, entry] of scopeCache) {
+        if (Date.now() - entry.at > SCOPE_CACHE_MS * 4) scopeCache.delete(existing)
+      }
+    }
+  }
+
+  /**
+   * Open (or reuse) the index for one workspace and focus.
+   *
+   * @param {Record<string, any>} settings resolved settings
+   * @param {string} cwd workspace root
+   * @param {string} focus focus key, `.` for the whole workspace
+   */
+  function indexFor(settings, cwd, focus = '.') {
+    const absolute = (path) => join(resolve(path), focus === '.' ? 'index.sqlite' : join('focus', focus, 'index.sqlite'))
+    const file =
+      typeof settings.stateDir === 'string' && settings.stateDir.trim() !== ''
+        ? absolute(settings.stateDir.trim())
+        : indexFile(dshHome, cwd, focus)
+    let index = openIndexes.get(file)
+    if (index === undefined) {
+      index = new RecallIndex(file)
+      openIndexes.set(file, index)
+    }
+    const identity = {
+      model: String(settings.embeddingModel),
+      dimensions: String(settings.embeddingDimensions),
+      apiBase: String(settings.embeddingApiBase),
+    }
+    // `open` is idempotent for an already-open handle; the identity check is the
+    // part that must run every time, because the settings can change under it.
+    const outcome = index.db === undefined ? index.open(identity) : index.recheck(identity)
+    return { index, file, discarded: outcome.discarded }
+  }
+
+  /**
+   * Bring one workspace's index up to date.
+   *
+   * Phase one reads and hashes every candidate — fast, bounded by disk. Phase
+   * two embeds what changed, and is the only part given a deadline. Splitting
+   * them is what makes the reported state honest: after phase one the plugin
+   * knows exactly what is stale, so a partial index is described rather than
+   * guessed at.
+   */
+  async function syncWorkspace(input) {
+    const { root, prefix = '', index, settings, budgetMs, signal, onProgress } = input
+    const walk = await listCodeFiles(root, {
+      ...(settings.extensions?.length ? { extensions: settings.extensions } : {}),
+      skipDirs: DEFAULT_SKIP_DIRS,
+      exclude: settings.exclude ?? [],
+      maxFiles: Number(settings.maxFiles),
+      signal,
+    })
+    // `listCodeFiles` reports paths relative to the walk root, which under a
+    // focus is the focus directory. They are rewritten to be relative to the
+    // WORKSPACE, because that is the path the model will hand to `read` — a
+    // focus-relative result would silently read the wrong file.
+    if (prefix !== '') {
+      for (const file of walk.files) file.path = `${prefix}/${file.path}`
+    }
+
+    const known = index.fileHashes()
+    const present = new Set(walk.files.map((file) => file.path))
+    const removed = index.prune([...known.keys()].filter((path) => !present.has(path)))
+
+    const maxBytes = Number(settings.maxFileBytes)
+    const pending = []
+    let oversized = 0
+    let unreadable = 0
+
+    for (const file of walk.files) {
+      if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+      let content
+      try {
+        const info = await stat(file.absolute)
+        if (info.size > maxBytes) {
+          oversized += 1
+          continue
+        }
+        content = await readFile(file.absolute, 'utf8')
+      } catch {
+        unreadable += 1
+        continue
+      }
+      const hash = hashOf(content)
+      if (known.get(file.path) === hash) continue
+      pending.push({ ...file, content, hash, bytes: Buffer.byteLength(content) })
+    }
+
+    // Anything still holding an old hash is stale until it is re-embedded.
+    const stale = new Set(pending.map((file) => file.path))
+    const deadline = Date.now() + budgetMs
+    let embedded = 0
+    let chunksWritten = 0
+
+    for (const file of pending) {
+      if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+      // Always embed at least one file, or a zero budget would make the feature
+      // indistinguishable from a broken index.
+      if (embedded > 0 && Date.now() >= deadline) break
+      const { chunks } = chunkFile({
+        path: file.path,
+        content: file.content,
+        chunkLines: Number(settings.chunkLines),
+        maxChunkLines: Number(settings.maxChunkLines),
+        overlapLines: Number(settings.overlapLines),
+      })
+      if (chunks.length === 0) {
+        // An empty or generated file still gets a row, so it is not re-read and
+        // re-chunked on every subsequent search.
+        index.replaceFile(file.path, file.hash, file.bytes, [])
+        embedded += 1
+        stale.delete(file.path)
+        onProgress?.(embedded, pending.length)
+        continue
+      }
+      const vectors = await input.embedder.embed(
+        chunks.map((chunk) => embedText(file.path, chunk)),
+        signal,
+      )
+      index.replaceFile(
+        file.path,
+        file.hash,
+        file.bytes,
+        chunks.map((chunk, at) => ({ ...chunk, vec: vectors[at] })),
+      )
+      chunksWritten += chunks.length
+      embedded += 1
+      stale.delete(file.path)
+      onProgress?.(embedded, pending.length)
+    }
+
+    const stats = index.stats()
+    return {
+      ...stats,
+      scanned: walk.files.length,
+      truncated: walk.truncated,
+      removed,
+      embedded,
+      chunksWritten,
+      pending: pending.length - embedded,
+      stale: [...stale],
+      oversized,
+      unreadable,
+    }
+  }
+
+  const TOOL_OUTPUT = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      action: { type: 'string', required: true },
+      ok: { type: 'boolean', required: true },
+      query: { type: 'string' },
+      workspace: { type: 'string' },
+      focus: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          source: { type: 'string', required: true },
+          marker: { type: 'string' },
+          problem: { type: 'string' },
+        },
+      },
+      results: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string', required: true },
+            startLine: { type: 'integer', required: true },
+            endLine: { type: 'integer', required: true },
+            symbol: { type: 'string' },
+            similarity: { type: 'number', required: true },
+            excerpt: { type: 'string', required: true },
+            truncated: { type: 'boolean', required: true },
+            stale: { type: 'boolean', required: true },
+          },
+        },
+      },
+      index: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          files: { type: 'integer' },
+          chunks: { type: 'integer' },
+          pending: { type: 'integer' },
+          scanned: { type: 'integer' },
+          embedded: { type: 'integer' },
+          removed: { type: 'integer' },
+          oversized: { type: 'integer' },
+          unreadable: { type: 'integer' },
+          truncated: { type: 'boolean' },
+          database: { type: 'string' },
+          stateDir: { type: 'string' },
+        },
+      },
+      best: { type: 'number' },
+      endpoint: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          url: { type: 'string', required: true },
+          model: { type: 'string', required: true },
+          errorCode: { type: 'string' },
+          message: { type: 'string' },
+        },
+      },
+      weak: { type: 'boolean' },
+      /**
+       * What this call returned, against what reading those files would have
+       * cost. `sourceBytes` is an upper bound and is labelled as one wherever
+       * it is shown — a careful reader might have opened one file, not four.
+       */
+      measure: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          excerpts: { type: 'integer', required: true },
+          returnedBytes: { type: 'integer', required: true },
+          sourceBytes: { type: 'integer', required: true },
+          files: { type: 'integer', required: true },
+        },
+      },
+      jobId: { type: 'string' },
+      /** Every scope discovered in this workspace, so a caller can pick one. */
+      scopes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string', required: true },
+            marker: { type: 'string', required: true },
+          },
+        },
+      },
+      note: { type: 'string' },
+      errorCode: { type: 'string' },
+      remedy: { type: 'string' },
+    },
+  }
+
+  /** Render one search result set for the model. */
+  function renderResults(value) {
+    if (value.jobId !== undefined) {
+      return [
+        {
+          type: 'text',
+          text:
+            `Indexing ${value.workspace} as background job ${value.jobId}. You will be notified when it settles; ` +
+            `collect it with job_output for "${value.jobId}" (add wait: true if you are blocked on it). ` +
+            'Searches work meanwhile against whatever is already indexed.',
+        },
+      ]
+    }
+    if (value.ok !== true) {
+      const parts = [value.note ?? `recall ${value.action} failed.`]
+      if (value.remedy !== undefined) parts.push(`Next: ${value.remedy}`)
+      return [{ type: 'text', text: parts.join('\n\n') }]
+    }
+    if (value.action === 'configure') {
+      return [{ type: 'text', text: value.note ?? 'Configuration updated.' }]
+    }
+    if (value.action !== 'search') {
+      const { files = 0, chunks = 0, pending = 0, scanned = 0, embedded = 0 } = value.index ?? {}
+      return [
+        {
+          type: 'text',
+          text:
+            `Index for ${value.workspace}: ${files} files, ${chunks} chunks. ` +
+            `Scanned ${scanned}, embedded ${embedded} this call, ${pending} still pending.`,
+        },
+      ]
+    }
+
+    const results = value.results ?? []
+    if (results.length === 0) {
+      const suffix = (value.index?.pending ?? 0) > 0 ? ` ${value.index.pending} file(s) are still unindexed.` : ''
+      return [
+        {
+          type: 'text',
+          text:
+            `No match for ${JSON.stringify(value.query)}.${suffix} ` +
+            'If you know the exact identifier, grep is the better tool for this query.',
+        },
+      ]
+    }
+
+    const scope = value.focus?.path !== undefined && value.focus.path !== '.' ? ` in ${value.focus.path}` : ''
+    const header =
+      `${results.length} excerpt(s) for ${JSON.stringify(value.query)}${scope} — ` +
+      `from ${value.index?.chunks ?? 0} indexed chunks` +
+      ((value.index?.pending ?? 0) > 0 ? `, ${value.index.pending} file(s) still unindexed` : '')
+    const body = results.map((result, at) => {
+      const symbol = result.symbol === undefined ? '' : ` (${result.symbol})`
+      const stale = result.stale ? ' [stale — file changed since indexing]' : ''
+      const cut = result.truncated ? '\n… excerpt truncated; read the file for the rest' : ''
+      return (
+        `--- ${at + 1}. ${result.path}:${result.startLine}-${result.endLine}${symbol} ` +
+        `similarity ${result.similarity}${stale}\n${result.excerpt}${cut}`
+      )
+    })
+    // A scope is a window, not a filter on relevance. When it holds nothing
+    // strong, the most likely reason is that the answer is shared code the scope
+    // excludes — 41.6% of the workspace this was measured on — so say that
+    // rather than leaving the caller to conclude the code does not exist.
+    const outside =
+      value.focus?.path !== undefined && value.focus.path !== '.'
+        ? ` Only ${value.focus.path} is indexed here; shared code outside it is not. Retry without focus to search the whole workspace.`
+        : ''
+    const advice = value.weak
+      ? `\n\nNo strong match. Prefer grep for a known identifier, or rephrase with the name of the thing.${outside}`
+      : ''
+    return [{ type: 'text', text: `${header}\n\n${body.join('\n\n')}${advice}` }]
+  }
+
+  ctx.tools.register(
+    defineTool({
+      name: 'recall',
+      description:
+        'Search this workspace semantically with a local embedding model and return ranked code excerpts ' +
+        'with file paths and line ranges — without reading whole files into the conversation. Use it when ' +
+        'you do not know the exact identifier: "where is X handled", "which module does Y", "how does Z ' +
+        'recover from failure". Prefer grep when you already know the exact symbol, and read when you need ' +
+        'the whole file. Because excerpts are returned inline, do not follow up with a read of the same ' +
+        'range. Actions: "search" (default) answers a query and warms a bounded slice of the index; ' +
+        '"index" builds or refreshes the whole index, as a background job by default; "status" reports the ' +
+        'index and endpoint state. The index is incremental and lives outside your repository.',
+      parameters: {
+        query: {
+          type: 'string',
+          description: 'What to look for, in words. A description of behaviour works as well as a name.',
+        },
+        action: {
+          type: 'string',
+          enum: ['search', 'index', 'status', 'configure'],
+          description: 'What to do. Defaults to "search".',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Most excerpts to return. Defaults to the configured limit (8).',
+        },
+        path: {
+          type: 'string',
+          description:
+            'Restrict the search to files under this workspace-relative directory, for example "src/services".',
+        },
+        focus: {
+          type: 'string',
+          description:
+            'Scope this whole call — index and search — to one workspace-relative directory, for example ' +
+            '"src/controllers/room/occupancy". Use it when the session is working on one module: the index ' +
+            'then holds only that module, so its near-identical neighbours cannot outrank it and the first ' +
+            'search does not wait on the rest of the repository. Empty uses the configured focus, then the ' +
+            'nearest enclosing directory that carries a CONTROLLER.md, DEBUG_UI.md or AGENTS.md.',
+        },
+        run_in_background: {
+          type: 'boolean',
+          description:
+            'For action "index" only: return a job id instead of the result. Defaults to true, because a ' +
+            'cold index of a large repository takes minutes.',
+        },
+        config: {
+          type: 'json',
+          description:
+            'Settings patch for action "configure", using this plugin\'s own camelCase field names, for ' +
+            'example {"embeddingApiBase":"http://10.50.1.2:11434"}.',
+        },
+      },
+      output: {
+        schema: TOOL_OUTPUT,
+        render: (_args, value) => renderResults(value),
+        // The harness persists this verbatim as the `meta` of the `tool/result`
+        // event, which is what puts per-call usage in the session log — and
+        // therefore in reach of a projection the browser can read. Pure, and it
+        // carries totals rather than content: it is appended on every call and
+        // replayed on every projection rebuild.
+        presentationMeta: (args, value) => deriveUsage(args, value),
+      },
+      isConcurrencySafe: (args) => (args.action ?? 'search') !== 'index',
+      async execute(args, exec) {
+        const settings = readSettings() ?? config
+        const cwd = exec.agent?.session.header.cwd ?? process.cwd()
+        const action = args.action ?? 'search'
+        const workspace = basename(cwd) || cwd
+        const embedder = embedderFor(settings)
+
+        // Resolve the scope before anything else, because it decides which index
+        // is opened. A caller's `focus` outranks the configured one, so a session
+        // can name a controller without changing the deployment's default.
+        const markers = settings.focusMarkers?.length ? settings.focusMarkers : DEFAULT_FOCUS_MARKERS
+        const scopes = await scopesFor(cwd, markers)
+        const focus = resolveFocus({
+          workspace: cwd,
+          cwd,
+          explicit: args.focus ?? settings.focus ?? '',
+          markers,
+          scopes,
+        })
+        const focusPath = focusKey(cwd, focus.root)
+
+        let opened
+        try {
+          opened = indexFor(settings, cwd, focusPath)
+        } catch (error) {
+          return {
+            action,
+            ok: false,
+            workspace,
+            errorCode: 'INDEX_UNAVAILABLE',
+            note: `Could not open the index: ${error?.message ?? error}`,
+            remedy: `Check that ${dshHome} is writable.`,
+          }
+        }
+        const { index, file, discarded } = opened
+        const stateDir = workspaceStateDir(dshHome, cwd)
+        const focusView = {
+          path: focusPath,
+          source: focus.source,
+          ...(focus.marker === undefined ? {} : { marker: focus.marker }),
+          ...(focus.problem === undefined ? {} : { problem: focus.problem }),
+        }
+        const base = { action, workspace, focus: focusView, index: { database: file, stateDir } }
+
+        if (action === 'status') {
+          const stats = index.stats()
+
+          // Probe the endpoint rather than merely naming it. A wedged backend
+          // accepts the connection and never answers, so "configured" and
+          // "working" are different claims and status should make the second
+          // one. One attempt, short timeout — a probe that waits is not a probe.
+          let endpoint
+          try {
+            await proberFor(settings).embedOne('dsh-recall endpoint probe', exec.signal)
+            endpoint = {
+              ok: true,
+              url: String(settings.embeddingApiBase),
+              model: String(settings.embeddingModel),
+            }
+          } catch (error) {
+            endpoint = {
+              ok: false,
+              url: String(settings.embeddingApiBase),
+              model: String(settings.embeddingModel),
+              errorCode: error instanceof EmbeddingError ? error.code : 'PROBE_FAILED',
+              message: error?.message ?? String(error),
+            }
+          }
+
+          return {
+            ...base,
+            ok: true,
+            index: indexView(base.index, stats),
+            endpoint,
+            scopes: scopes.map((entry) => ({ path: entry.path, marker: entry.marker })),
+            note:
+              `Index ${file} holds ${stats.files} files and ${stats.chunks} chunks, scoped to ` +
+              `${focusPath === '.' ? 'the whole workspace' : focusPath} (${focus.source}` +
+              `${focus.marker === undefined ? '' : `: ${focus.marker}`}). ` +
+              (focus.problem === undefined ? '' : `Requested focus was ignored — ${focus.problem}. `) +
+              // A workspace with discoverable scopes can be scoped by naming one,
+              // so listing them is the difference between a feature that exists
+              // and one a caller can actually use.
+              (scopes.length === 0
+                ? 'No focusable scopes were found; pass focus to scope a call explicitly. '
+                : `Available scopes: ${scopes
+                    .slice(0, 12)
+                    .map((entry) => entry.path)
+                    .join(', ')}${scopes.length > 12 ? ` (+${scopes.length - 12} more)` : ''}. `) +
+              `Embeddings come from "${settings.embeddingModel}" (${settings.embeddingDimensions} dims) at ` +
+              `${settings.embeddingApiBase} — ` +
+              (endpoint.ok === true
+                ? 'endpoint answered.'
+                : `endpoint did NOT answer (${endpoint.errorCode}). Run \`ollama ps\` on that host; a ` +
+                  'model can be evicted, and an endpoint holding another model resident forever can ' +
+                  'leave no room to load this one.') +
+              (discarded === undefined ? '' : ` The index was rebuilt because ${discarded}.`),
+          }
+        }
+
+        if (action === 'configure') {
+          const patch = args.config
+          if (patch === undefined || patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+            return {
+              ...base,
+              ok: false,
+              errorCode: 'BAD_PATCH',
+              note: 'The `config` parameter must be an object.',
+            }
+          }
+          const unknown = Object.keys(patch).filter((key) => !SETTING_KEYS.includes(key))
+          if (unknown.length > 0) {
+            return {
+              ...base,
+              ok: false,
+              errorCode: 'UNKNOWN_SETTING',
+              note: `Unknown setting(s): ${unknown.join(', ')}.`,
+              remedy: `Known settings: ${SETTING_KEYS.join(', ')}.`,
+            }
+          }
+          if (writeSettings === undefined) {
+            return {
+              ...base,
+              ok: false,
+              errorCode: 'NO_SETTINGS_PROVIDER',
+              note: 'No settings provider is mounted, so configuration cannot be persisted at runtime.',
+              remedy: `Set these values in the dsh-recall row of your cordis layer instead: ${JSON.stringify(patch)}`,
+            }
+          }
+          await writeSettings(patch)
+          return { ...base, ok: true, note: `Updated ${Object.keys(patch).join(', ')}.` }
+        }
+
+        // Full warm-up. Deliberately a background job by default: on a large
+        // repository this is minutes of work, and blocking a turn on it is the
+        // behaviour that makes a useful tool feel broken.
+        if (action === 'index') {
+          const jobs = ctx.get('jobs')
+          const wantsBackground = args.run_in_background ?? true
+          const runIndex = (signal) =>
+            withLock(file, () =>
+              syncWorkspace({
+                root: focus.root,
+                prefix: focusPath === '.' ? '' : focusPath,
+                index,
+                embedder,
+                settings,
+                budgetMs: Number.POSITIVE_INFINITY,
+                signal,
+              }),
+            )
+
+          if (wantsBackground && jobs !== undefined) {
+            const jobId = jobs.start({
+              kind: 'recall-index',
+              label: `recall index ${workspace}`,
+              ...(exec.agent === undefined ? {} : { owner: exec.agent }),
+              run: () => {
+                const controller = new AbortController()
+                const done = (async () => {
+                  const result = await runIndex(controller.signal)
+                  return {
+                    status: 'completed',
+                    detail: `${result.files} files, ${result.chunks} chunks`,
+                    output:
+                      `Indexed ${result.embedded} file(s) into ${result.chunks} chunks (${result.files} files ` +
+                      `total, ${result.removed} removed). Database: ${file}`,
+                  }
+                })()
+                return { cancel: () => controller.abort(), done }
+              },
+            })
+            return { ...base, ok: true, jobId }
+          }
+
+          const result = await runIndex(exec.signal)
+          return { ...base, ok: true, index: indexView(base.index, result) }
+        }
+
+        // search
+        const query = typeof args.query === 'string' ? args.query.trim() : ''
+        if (query === '') {
+          return {
+            ...base,
+            ok: false,
+            errorCode: 'NO_QUERY',
+            note: 'A search needs a query.',
+            remedy: 'Call recall with a `query` describing what you are looking for.',
+          }
+        }
+
+        const limit = Math.max(
+          1,
+          Math.min(Number(args.limit ?? settings.defaultLimit), Number(settings.maxLimit)),
+        )
+
+        try {
+          const sync = await withLock(file, () =>
+            syncWorkspace({
+              root: focus.root,
+              prefix: focusPath === '.' ? '' : focusPath,
+              index,
+              embedder,
+              settings,
+              budgetMs: Math.max(0, Number(settings.syncBudgetMs)),
+              signal: exec.signal,
+            }),
+          )
+          const matrix = index.matrix()
+          if (matrix.rows.length === 0) {
+            return {
+              ...base,
+              ok: true,
+              query,
+              results: [],
+              weak: true,
+              index: indexView(base.index, sync),
+              note:
+                'Nothing is indexed yet, so there is nothing to search. ' +
+                (sync.pending > 0
+                  ? `${sync.pending} file(s) were found but the per-call embedding budget was reached.`
+                  : 'No indexable code was found in this workspace.'),
+              ...(sync.pending > 0
+                ? {
+                    remedy:
+                      'Run recall with action "index" to build the whole index in the background.',
+                  }
+                : {}),
+            }
+          }
+
+          // Query expansion: rank every phrasing and fuse the orders. The
+          // expander never throws — on a slow or absent local model it returns
+          // the original query alone, and this path is unchanged.
+          const expansionModel = String(settings.expansionModel ?? '').trim()
+          const queries = settings.expansionEnabled === true
+            ? await createExpander({
+                apiBase: String(settings.embeddingApiBase),
+                model: expansionModel === '' ? String(settings.embeddingModel) : expansionModel,
+                timeoutMs: Number(settings.expansionTimeoutMs),
+                count: Number(settings.expansionCount),
+              }).expand(query, exec.signal)
+            : [query]
+
+          const orders = []
+          let similarity
+          let vectorBest = 0
+          for (const variant of queries) {
+            const vector = await embedder.embedOne(variant, exec.signal)
+            const ranked = rankOrder({ matrix, queryVector: vector, query: variant })
+            orders.push(ranked.order)
+            // The first variant is the caller's own query, so its similarities
+            // are the honest ones to report against each result.
+            if (similarity === undefined) {
+              similarity = ranked.similarity
+              vectorBest = ranked.vectorBest
+            }
+          }
+
+          let results = selectFrom(fuseRankings(orders), {
+            matrix,
+            similarity,
+            limit,
+            perFile: Number(settings.perFileLimit),
+            excerptLines: Number(settings.excerptLines),
+            totalLines: Number(settings.totalExcerptLines),
+          })
+
+          // Local re-ranking: one call scores the head of the list. `undefined`
+          // means the model had no opinion, which is not the same as "all
+          // irrelevant" — the fused order stands unchanged.
+          const rerankModel = String(settings.rerankModel ?? '').trim()
+          const rerankCount = Math.min(results.length, Number(settings.rerankCandidates), 12)
+          if (settings.rerankEnabled === true && rerankCount > 1) {
+            const head = results.slice(0, rerankCount)
+            const localScores = await createReranker({
+              apiBase: String(settings.embeddingApiBase),
+              model: rerankModel === '' ? String(settings.embeddingModel) : rerankModel,
+              timeoutMs: Number(settings.rerankTimeoutMs),
+            }).score(query, head.map((result) => result.excerpt), exec.signal)
+            if (localScores !== undefined && localScores.length === head.length) {
+              const blended = head
+                .map((result, at) => ({ result, score: 0.4 * result.similarity + 0.6 * localScores[at] }))
+                .sort((left, right) => right.score - left.score)
+                .map((entry) => entry.result)
+              results = [...blended, ...results.slice(rerankCount)]
+            }
+          }
+
+          if (typeof args.path === 'string' && args.path.trim() !== '') {
+            const prefix = args.path.trim().replace(/^\.\//, '').replace(/\/+$/, '')
+            results = results.filter(
+              (result) => result.path === prefix || result.path.startsWith(`${prefix}/`),
+            )
+          }
+
+          const stale = new Set(sync.stale ?? [])
+          const best = results.length === 0 ? 0 : Math.max(...results.map((result) => result.similarity))
+
+          // The alternative to these excerpts: the whole of each file they came
+          // from. Sizes come from the index, which recorded them at embed time,
+          // so this costs nothing here — and it is an upper bound, because a
+          // careful reader might have opened one of the four rather than all.
+          const sourcePaths = [...new Set(results.map((result) => result.path))]
+          const sourceSizes = index.bytesFor(sourcePaths)
+          const sourceBytes = [...sourceSizes.values()].reduce((sum, size) => sum + size, 0)
+          const returnedBytes = results.reduce(
+            (sum, result) => sum + Buffer.byteLength(result.excerpt, 'utf8'),
+            0,
+          )
+          const measure = {
+            excerpts: results.length,
+            returnedBytes,
+            sourceBytes,
+            files: sourceSizes.size,
+          }
+
+          return {
+            ...base,
+            ok: true,
+            query,
+            // Built field by field rather than spread: the ranker also returns
+            // a fused RRF `score`, which is an internal ordering artefact and not
+            // part of the declared result shape.
+            results: results.map((result) => ({
+              path: result.path,
+              startLine: result.startLine,
+              endLine: result.endLine,
+              ...(result.symbol === undefined ? {} : { symbol: result.symbol }),
+              similarity: result.similarity,
+              excerpt: result.excerpt,
+              truncated: result.truncated,
+              stale: stale.has(result.path),
+            })),
+            index: indexView(base.index, sync),
+            best,
+            weak: results.length === 0 || best < Number(settings.minSimilarity),
+            measure,
+          }
+        } catch (error) {
+          const code = error instanceof EmbeddingError ? error.code : 'RECALL_FAILED'
+          const remedy =
+            code === 'UNREACHABLE' || error?.cause?.code === 'ECONNREFUSED'
+              ? `Is the embedding endpoint at ${settings.embeddingApiBase} running and reachable? Set ` +
+                '`embeddingApiBase` through the plugin settings if it moved.'
+              : code === 'DIMENSION_MISMATCH'
+                ? `Set \`embeddingDimensions\` to match "${settings.embeddingModel}".`
+                : undefined
+          logger.warn('recall search failed: %s', error?.message ?? error)
+          return {
+            ...base,
+            ok: false,
+            query,
+            errorCode: code,
+            note: error?.message ?? String(error),
+            ...(remedy === undefined ? {} : { remedy }),
+          }
+        }
+      },
+    }),
+  )
+}
diff --git a/lib/chunk.js b/lib/chunk.js
new file mode 100644
index 0000000..49bda42
--- /dev/null
+++ b/lib/chunk.js
@@ -0,0 +1,273 @@
+/**
+ * Splitting source into retrievable units.
+ *
+ * This is where retrieval quality is decided, and the rule that matters is that
+ * **a chunk must be a thing a person would name**. Splitting on a fixed line
+ * count produces units that begin mid-function and end mid-conditional; their
+ * embedding sits between two topics and matches neither, so the search returns
+ * plausible-looking noise. Splitting at declarations produces units whose
+ * embedding is about one subject, which is the entire premise of the retrieval.
+ *
+ * The anchor set is deliberately shallow — column-0 declarations only. A real
+ * parser would place boundaries better, but it would also mean shipping a
+ * tree-sitter grammar per language and keeping ten of them current, for a gain
+ * that only shows up on languages with heavy nesting. Since a chunk is a
+ * *search result* and not an edit target, a boundary that is roughly right costs
+ * a few wasted lines and nothing else.
+ *
+ * Fixed-width windows remain as the fallback, because a file whose structure the
+ * anchor set cannot see — a minified bundle, a template, an unusual dialect —
+ * must still be searchable rather than silently absent from the index.
+ */
+
+/** Lines a chunk aims for when merging neighbouring declarations. */
+export const DEFAULT_CHUNK_LINES = 48
+
+/** Lines a chunk may never exceed; longer ones are split with overlap. */
+export const DEFAULT_MAX_CHUNK_LINES = 80
+
+/** Lines shared between the halves of a split chunk, so a boundary is never lost. */
+export const DEFAULT_OVERLAP_LINES = 8
+
+/** Chunks taken from one file, so one pathological file cannot dominate the index. */
+export const DEFAULT_MAX_CHUNKS_PER_FILE = 250
+
+/** Files whose mean line length exceeds this are treated as generated/minified. */
+const MINIFIED_MEAN_LINE = 400
+
+/** Anchor patterns by language family, applied to the raw line. */
+const FAMILIES = {
+  javascript: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var|interface|type|enum|namespace|declare)\b/,
+  python: /^(?:async\s+)?(?:def|class)\s+[A-Za-z_]/,
+  go: /^(?:func|type|var|const)\b/,
+  rust: /^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern\s+)?(?:fn|struct|enum|impl|trait|mod|const|static|type)\b/,
+  jvm: /^(?:@\w+|public|private|protected|static|final|abstract|sealed|open|class|interface|enum|record|object|fun|val|var|def)\b/,
+  dotnet: /^(?:\[[^\]]*\]|public|private|protected|internal|static|final|abstract|sealed|partial|class|interface|enum|record|struct|namespace)\b/,
+  c: /^(?:class|struct|enum|union|namespace|template|typedef|using|extern)\b|^[A-Za-z_][\w \t*&:<>]*\s+[A-Za-z_]\w*\s*\([^;]*\)\s*(?:const\s*)?$/,
+  ruby: /^(?:def|class|module)\s/,
+  php: /^(?:public|private|protected|static|final|abstract|function|class|interface|trait|namespace)\b/,
+  shell: /^(?:function\s+[A-Za-z_]|[A-Za-z_]\w*\s*\(\)\s*\{)/,
+  sql: /^(?:CREATE|ALTER|DROP|WITH)\b/i,
+  markup: /^<(?:template|script|style|svelte:)/,
+}
+
+/** Extension to family. Anything unlisted falls back to the window splitter. */
+const EXTENSION_FAMILY = {
+  ts: 'javascript', tsx: 'javascript', mts: 'javascript', cts: 'javascript',
+  js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript',
+  py: 'python', rb: 'ruby', go: 'go', rs: 'rust',
+  java: 'jvm', kt: 'jvm', kts: 'jvm', scala: 'jvm', swift: 'jvm',
+  c: 'c', h: 'c', cc: 'c', cpp: 'c', cxx: 'c', hpp: 'c', hh: 'c',
+  cs: 'dotnet',
+  php: 'php', pl: 'ruby', lua: 'ruby',
+  sh: 'shell', bash: 'shell', zsh: 'shell',
+  sql: 'sql', graphql: 'sql', proto: 'c',
+  vue: 'markup', svelte: 'markup',
+}
+
+/** Name of the declaration on an anchor line, when one can be read off it. */
+const SYMBOL_PATTERNS = [
+  /\b(?:function|class|interface|type|enum|namespace|def|func|fn|struct|trait|impl|mod|const|let|var|record|object|fun|val|module|macro_rules!)\s+([A-Za-z_$][\w$]*)/,
+  /\b([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?:const\s*)?(?:\{|:)?\s*$/,
+]
+
+/** The language family for a path, or `undefined` when it has none. */
+export function languageOf(path) {
+  const name = path.slice(path.lastIndexOf('/') + 1).toLowerCase()
+  const dot = name.lastIndexOf('.')
+  if (dot <= 0) return undefined
+  return EXTENSION_FAMILY[name.slice(dot + 1)]
+}
+
+/** The declaration regex for a family, or `undefined`. */
+export function declarationPattern(family) {
+  return family === undefined ? undefined : FAMILIES[family]
+}
+
+/** The name declared on a line, when one reads off it. */
+export function symbolOf(line) {
+  for (const pattern of SYMBOL_PATTERNS) {
+    const match = pattern.exec(line)
+    if (match !== null) return match[1]
+  }
+  return undefined
+}
+
+/** Declaration names for a freshly built segment. */
+function symbolList(symbol) {
+  return symbol === undefined ? [] : [symbol]
+}
+
+/**
+ * The label for a chunk that may have absorbed several declarations.
+ *
+ * A small file merges into a single chunk, and that chunk's label is then the
+ * file's only description in the index — so dropping every name but the first
+ * would describe a whole module as whatever its first declaration happened to
+ * be. The list is capped because beyond a handful of names the label stops
+ * being a description and starts being noise that dilutes the embedding.
+ */
+export function symbolLabel(symbols) {
+  const unique = [...new Set(symbols)]
+  if (unique.length === 0) return undefined
+  if (unique.length <= 4) return unique.join(', ')
+  return `${unique.slice(0, 4).join(', ')} +${unique.length - 4}`
+}
+
+/**
+ * Whether a file looks machine-generated.
+ *
+ * A minified bundle is one enormous line; embedding windows taken from it
+ * produces chunks of arbitrary identifiers that match every query weakly and
+ * none strongly. The mean line length separates the two cheaply and without
+ * reading the whole file.
+ */
+export function isLikelyMinified(content) {
+  const lines = content.split('\n')
+  if (lines.length === 0) return true
+  // Only consider files large enough for the statistic to mean anything.
+  if (lines.length < 4) {
+    return content.length > 20_000
+  }
+  const total = content.length
+  return total / lines.length > MINIFIED_MEAN_LINE
+}
+
+/** Trim trailing blank lines from a segment, leaving at least one line. */
+function trimEnd(lines, start, end) {
+  let last = end
+  while (last > start && lines[last].trim() === '') last -= 1
+  return last
+}
+
+/** Split one oversized segment into overlapping windows. */
+function splitLong(lines, start, end, maxLines, overlap) {
+  const out = []
+  const step = Math.max(1, maxLines - overlap)
+  for (let at = start; at <= end; at += step) {
+    const stop = Math.min(end, at + maxLines - 1)
+    out.push({ startLine: at, endLine: stop, symbol: undefined })
+    if (stop === end) break
+  }
+  return out
+}
+
+/**
+ * Split a file into chunks.
+ *
+ * @param {object} input
+ * @param {string} input.path workspace-relative path, used only for language detection
+ * @param {string} input.content file text
+ * @param {number} [input.chunkLines] target chunk size
+ * @param {number} [input.maxChunkLines] hard cap before splitting
+ * @param {number} [input.overlapLines] lines shared when splitting
+ * @param {number} [input.maxChunks] cap on chunks returned for one file
+ * @returns {{chunks: {startLine: number, endLine: number, symbol?: string, text: string}[], skipped?: string}}
+ */
+export function chunkFile(input) {
+  const {
+    path,
+    content,
+    chunkLines = DEFAULT_CHUNK_LINES,
+    maxChunkLines = DEFAULT_MAX_CHUNK_LINES,
+    overlapLines = DEFAULT_OVERLAP_LINES,
+    maxChunks = DEFAULT_MAX_CHUNKS_PER_FILE,
+  } = input
+
+  if (isLikelyMinified(content)) return { chunks: [], skipped: 'generated-or-minified' }
+  if (content.trim() === '') return { chunks: [], skipped: 'empty' }
+
+  const lines = content.split('\n')
+  const family = languageOf(path)
+  const pattern = declarationPattern(family)
+
+  /** Anchors: line indices that begin a declaration. */
+  const anchors = []
+  if (pattern !== undefined) {
+    for (let at = 0; at < lines.length; at += 1) {
+      const line = lines[at]
+      if (line === '' || /^\s/.test(line)) continue
+      if (pattern.test(line)) anchors.push(at)
+    }
+  }
+
+  /** Segments: [anchor, next anchor) with trailing blanks trimmed. */
+  const segments = []
+  // One anchor is still structure: a module holding a single top-level function
+  // should carry that function's name rather than lose it to the fallback.
+  if (anchors.length >= 1) {
+    if (anchors[0] > 0) anchors.unshift(0)
+    for (let at = 0; at < anchors.length; at += 1) {
+      const start = anchors[at]
+      const rawEnd = at + 1 < anchors.length ? anchors[at + 1] - 1 : lines.length - 1
+      const end = trimEnd(lines, start, rawEnd)
+      if (end < start) continue
+      segments.push({ startLine: start, endLine: end, symbols: symbolList(symbolOf(lines[start])) })
+    }
+  } else {
+    // No usable structure: one segment, and the splitter below does the work.
+    segments.push({ startLine: 0, endLine: trimEnd(lines, 0, lines.length - 1), symbols: [] })
+  }
+
+  /**
+   * Merge neighbours that fit together.
+   *
+   * A file of one-line getters would otherwise produce one chunk per getter,
+   * each too small to carry meaning. Merging accumulates every declaration name
+   * it swallowed, because a chunk tagged only with its first name would be
+   * embedded under a label describing a fraction of its contents.
+   */
+  const merged = []
+  let current
+  for (const segment of segments) {
+    if (current !== undefined) {
+      const combined = segment.endLine - current.startLine + 1
+      if (combined <= chunkLines) {
+        current.endLine = segment.endLine
+        current.symbols.push(...segment.symbols)
+        continue
+      }
+    }
+    current = { startLine: segment.startLine, endLine: segment.endLine, symbols: [...segment.symbols] }
+    merged.push(current)
+  }
+
+  const out = []
+  for (const segment of merged) {
+    const label = symbolLabel(segment.symbols)
+    const length = segment.endLine - segment.startLine + 1
+    if (length <= maxChunkLines) {
+      out.push({ startLine: segment.startLine, endLine: segment.endLine, symbol: label })
+      continue
+    }
+    for (const piece of splitLong(lines, segment.startLine, segment.endLine, maxChunkLines, overlapLines)) {
+      out.push({ ...piece, symbol: piece.startLine === segment.startLine ? label : undefined })
+    }
+  }
+
+  const capped = out.length > maxChunks
+  const kept = capped ? out.slice(0, maxChunks) : out
+  return {
+    chunks: kept.map((chunk) => ({
+      // 1-based, so a result can be handed straight to `read` as offset/limit.
+      startLine: chunk.startLine + 1,
+      endLine: chunk.endLine + 1,
+      ...(chunk.symbol === undefined ? {} : { symbol: chunk.symbol }),
+      text: lines.slice(chunk.startLine, chunk.endLine + 1).join('\n'),
+    })),
+    ...(capped ? { skipped: 'chunk-cap-reached' } : {}),
+  }
+}
+
+/**
+ * The exact string that gets embedded for a chunk.
+ *
+ * The path is included on purpose. A developer asking "where is auth handled"
+ * means something closer to "under a path called auth" than to any particular
+ * line of code, and the path is the only signal in the chunk that carries that.
+ * The symbol follows for the same reason: it is what the question would name.
+ */
+export function embedText(path, chunk) {
+  const header = chunk.symbol === undefined ? path : `${path} :: ${chunk.symbol}`
+  return `${header}\n${chunk.text}`
+}
diff --git a/lib/embed.js b/lib/embed.js
new file mode 100644
index 0000000..e970a17
--- /dev/null
+++ b/lib/embed.js
@@ -0,0 +1,268 @@
+/**
+ * The embedding client.
+ *
+ * Speaks the Ollama HTTP API, which also covers any OpenAI-compatible gateway
+ * that implements `/api/embed`, and is deliberately the *only* outbound call
+ * this plugin makes. There is no vendor SDK and no configuration surface that
+ * could redirect code anywhere except the endpoint the operator named.
+ *
+ * Two properties the rest of the plugin depends on:
+ *
+ * **Every vector is unit length.** Cosine similarity is then a plain dot
+ * product, which is what makes ranking over tens of thousands of chunks a few
+ * milliseconds of arithmetic rather than a normalisation pass per comparison.
+ *
+ * **A dimension mismatch is fatal and loud.** A vector of the wrong width
+ * cannot be compared with the others, and silently storing one would corrupt
+ * the index in a way that looks like bad ranking rather than a broken config —
+ * the hardest possible failure to diagnose from the outside.
+ */
+
+/** Failure carrying a stable code, so the tool can explain rather than dump a stack. */
+export class EmbeddingError extends Error {
+  /**
+   * @param {string} message human-readable cause
+   * @param {string} code stable identifier
+   */
+  constructor(message, code) {
+    super(message)
+    this.name = 'EmbeddingError'
+    this.code = code
+  }
+}
+
+/** Characters sent per chunk. Comfortably inside an 8k-token code model's window. */
+const MAX_INPUT_CHARS = 24_000
+
+/** Attempts per request, including the first. */
+const MAX_ATTEMPTS = 3
+
+/** Base backoff between attempts. */
+const RETRY_BASE_MS = 250
+
+/** Truncate one input to the character budget. */
+export function clampInput(text) {
+  return text.length <= MAX_INPUT_CHARS ? text : text.slice(0, MAX_INPUT_CHARS)
+}
+
+/** Scale a vector to unit length. A zero vector is returned unchanged. */
+export function normalize(vector) {
+  let sum = 0
+  for (let at = 0; at < vector.length; at += 1) sum += vector[at] * vector[at]
+  if (sum === 0) return vector
+  const scale = 1 / Math.sqrt(sum)
+  for (let at = 0; at < vector.length; at += 1) vector[at] *= scale
+  return vector
+}
+
+/** Dot product, which is cosine similarity for unit vectors. */
+export function dot(left, right) {
+  let sum = 0
+  const length = Math.min(left.length, right.length)
+  for (let at = 0; at < length; at += 1) sum += left[at] * right[at]
+  return sum
+}
+
+/** Sleep that rejects promptly when the caller's signal fires. */
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal.reason ?? new Error('aborted'))
+    }
+    if (signal?.aborted) onAbort()
+    else signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Build an embedder bound to one endpoint.
+ *
+ * @param {object} options
+ * @param {string} options.apiBase base URL, without a trailing slash
+ * @param {string} options.model model id as the endpoint knows it
+ * @param {number} options.dimensions expected vector width
+ * @param {string} [options.apiKey] bearer token, when the endpoint wants one
+ * @param {number} [options.batchSize] inputs per request on the batch endpoint
+ * @param {number} [options.concurrency] requests in flight
+ * @param {number} [options.timeoutMs] per-request timeout
+ * @param {typeof fetch} [options.fetchImpl] injection point for tests
+ */
+export function createEmbedder(options) {
+  const {
+    apiBase,
+    model,
+    dimensions,
+    apiKey = '',
+    batchSize = 16,
+    concurrency = 2,
+    timeoutMs = 30_000,
+    maxAttempts = MAX_ATTEMPTS,
+    keepAlive = '',
+    fetchImpl = fetch,
+  } = options
+
+  const base = apiBase.replace(/\/+$/, '')
+  const headers = { 'content-type': 'application/json' }
+  if (apiKey !== '') headers.authorization = `Bearer ${apiKey}`
+
+  /**
+   * Add Ollama's `keep_alive` to a request body, when one is configured.
+   *
+   * Two reasons. An index run issues hundreds of requests, and without a
+   * keep-alive the model can be evicted between them and reloaded from disk
+   * repeatedly. And on a host already holding another model resident, a load
+   * that has to wait for memory is exactly the situation where a bounded,
+   * explicit residency beats Ollama's own default.
+   */
+  const withKeepAlive = (body) => (keepAlive === '' ? body : { ...body, keep_alive: keepAlive })
+
+  // Discovered on first use: the batch endpoint is preferred, but an older
+  // Ollama build answers it with a 404 and then every request pays that
+  // discovery again. Remembering the answer keeps the fallback cheap.
+  let batchEndpointWorks = true
+
+  /** One HTTP request, with retries on transport faults and 5xx. */
+  async function request(path, body, signal) {
+    let lastError
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+      const timeout = AbortSignal.timeout(timeoutMs)
+      const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout])
+      try {
+        const response = await fetchImpl(`${base}${path}`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: combined,
+        })
+        if (response.status === 404 || response.status === 405) {
+          const error = new EmbeddingError(`${path} is not available on ${base}`, 'ENDPOINT_UNSUPPORTED')
+          error.status = response.status
+          throw error
+        }
+        if (!response.ok) {
+          const text = await response.text().catch(() => '')
+          const error = new EmbeddingError(
+            `${path} responded ${response.status}${text === '' ? '' : `: ${text.slice(0, 300)}`}`,
+            'HTTP_ERROR',
+          )
+          error.status = response.status
+          throw error
+        }
+        return await response.json()
+      } catch (error) {
+        // A 4xx that is not a retryable status is a configuration fault, not a
+        // transient one, and retrying it just delays the explanation.
+        if (error instanceof EmbeddingError && error.status !== undefined && error.status < 500) throw error
+        if (signal?.aborted) throw signal.reason ?? error
+        lastError = error
+        if (attempt + 1 < MAX_ATTEMPTS) await delay(RETRY_BASE_MS * 2 ** attempt, signal)
+      }
+    }
+    throw new EmbeddingError(
+      `could not reach ${base}: ${lastError?.message ?? lastError}`,
+      'UNREACHABLE',
+    )
+  }
+
+  /** Check a returned vector's width against the configured one. */
+  function check(vector, index) {
+    if (!Array.isArray(vector)) {
+      throw new EmbeddingError(`response item ${index} was not an array`, 'BAD_RESPONSE')
+    }
+    if (dimensions > 0 && vector.length !== dimensions) {
+      throw new EmbeddingError(
+        `model "${model}" returned ${vector.length}-dimensional vectors but ${dimensions} are configured`,
+        'DIMENSION_MISMATCH',
+      )
+    }
+    return normalize(Float32Array.from(vector))
+  }
+
+  /** Embed one batch through whichever endpoint answers. */
+  async function embedBatch(texts, signal) {
+    const inputs = texts.map(clampInput)
+    if (inputs.length === 0) return []
+    if (batchEndpointWorks) {
+      try {
+        const payload = await request('/api/embed', withKeepAlive({ model, input: inputs }), signal)
+        if (!Array.isArray(payload?.embeddings) || payload.embeddings.length !== inputs.length) {
+          throw new EmbeddingError(
+            `/api/embed returned ${payload?.embeddings?.length ?? 0} vectors for ${inputs.length} inputs`,
+            'BAD_RESPONSE',
+          )
+        }
+        return payload.embeddings.map((vector, index) => check(vector, index))
+      } catch (error) {
+        // Only a missing endpoint falls back. A dimension mismatch or a bad
+        // response is a real fault and must not be papered over by a second
+        // endpoint that would fail the same way more slowly.
+        if (!(error instanceof EmbeddingError) || error.code !== 'ENDPOINT_UNSUPPORTED') throw error
+        batchEndpointWorks = false
+      }
+    }
+    const out = []
+    for (const input of inputs) {
+      const payload = await request('/api/embeddings', withKeepAlive({ model, prompt: input }), signal)
+      out.push(check(payload?.embedding, out.length))
+    }
+    return out
+  }
+
+  return {
+    model,
+    dimensions,
+    base,
+    /** Whether the batch endpoint has been ruled out. */
+    get batchEnabled() {
+      return batchEndpointWorks
+    },
+    /**
+     * Embed many texts, preserving order.
+     *
+     * @param {string[]} texts inputs
+     * @param {AbortSignal} [signal] caller cancellation
+     * @param {(done: number, total: number) => void} [onProgress]
+     * @returns {Promise<Float32Array[]>} unit vectors in input order
+     */
+    async embed(texts, signal, onProgress) {
+      const out = new Array(texts.length)
+      const size = Math.max(1, Math.min(batchSize, texts.length))
+      const batches = []
+      for (let at = 0; at < texts.length; at += size) {
+        batches.push({ start: at, items: texts.slice(at, at + size) })
+      }
+      let done = 0
+      let cursor = 0
+      const workers = new Array(Math.max(1, Math.min(concurrency, batches.length))).fill(0).map(async () => {
+        while (cursor < batches.length) {
+          if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+          const batch = batches[cursor]
+          cursor += 1
+          const vectors = await embedBatch(batch.items, signal)
+          for (let at = 0; at < vectors.length; at += 1) out[batch.start + at] = vectors[at]
+          done += vectors.length
+          onProgress?.(done, texts.length)
+        }
+      })
+      await Promise.all(workers)
+      return out
+    },
+    /**
+     * Embed one query string.
+     *
+     * @param {string} text query
+     * @param {AbortSignal} [signal] caller cancellation
+     * @returns {Promise<Float32Array>} unit vector
+     */
+    async embedOne(text, signal) {
+      const [vector] = await embedBatch([text], signal)
+      return vector
+    },
+  }
+}
diff --git a/lib/expand.js b/lib/expand.js
new file mode 100644
index 0000000..fcff96f
--- /dev/null
+++ b/lib/expand.js
@@ -0,0 +1,171 @@
+/**
+ * Query expansion, on the local model.
+ *
+ * A developer's first query is often a description rather than a name — "how
+ * does a room decide it is occupied" — and that phrasing shares few tokens with
+ * the code that answers it. Asking a small local model for a handful of
+ * alternative phrasings, embedding each, and fusing the rankings costs one local
+ * generation and a few local embeddings, and is free in money.
+ *
+ * ## Every failure is a fallback, never an error
+ *
+ * This runs on the critical path of a search, against a model on somebody else's
+ * box. It can be slow, wedged, or absent. None of those may fail the search, so
+ * the contract is narrow: **the returned list always contains the original
+ * query**, and anything that goes wrong simply returns it alone. The caller can
+ * treat expansion as a bonus that is either there or not.
+ *
+ * The internal timeout is deliberately separate from the caller's signal: the
+ * caller cancelling means stop everything, while the model being slow just means
+ * search with what we have.
+ */
+
+/** Attempts per request. Expansion is a bonus; one more try is enough. */
+const MAX_ATTEMPTS = 2
+
+/** Characters of query allowed through. Longer is a paste, not a question. */
+const MAX_QUERY_CHARS = 500
+
+/** A variant this long is a paragraph, not a search phrase. */
+const MAX_VARIANT_CHARS = 200
+
+/** Variants shorter than this match everything and rank nothing. */
+const MIN_VARIANT_CHARS = 3
+
+/**
+ * Openers that mark a line as the model talking rather than a phrasing.
+ *
+ * A small model asked for a list sometimes answers with a sentence about the
+ * request — "I cannot help with that." A line like that is not a weak variant,
+ * it is not a variant at all: embedding it would search the codebase for the
+ * model's apology and rank whatever matched.
+ *
+ * `i\b` and the refusal check below are the load-bearing ones. A question-shaped
+ * variant ("how does a room decide it is occupied") is entirely legitimate, so
+ * the test is first-person and refusal vocabulary, not sentence punctuation.
+ */
+const COMMENTARY = /^(?:i\b|i'm\b|i am\b|sorry\b|unfortunately\b|note\b|explanation\b|here\b|sure\b|of course\b|certainly\b|these\b|those\b|the following\b|as an?\b|phrasings?\b|query\b)/i
+
+/** Refusal vocabulary, wherever it sits in the line. */
+const REFUSAL = /\b(?:cannot help|can't help|don't have|do not have|not able to|unable to|no way to)\b/i
+
+const PROMPT = `You turn a developer's search query into alternative phrasings that would match source code.
+
+Rules:
+- One phrasing per line. No numbering, no bullets, no commentary, no blank lines.
+- Use the vocabulary the code itself would use: identifiers, domain nouns, verb phrases.
+- Vary the angle: a likely function name, a likely filename fragment, a description of the behaviour.
+- Do not repeat the original query.
+
+Query: {{QUERY}}
+
+Phrasings:`
+
+/**
+ * Reduce one model line to a usable phrase, or nothing.
+ *
+ * Models are reliably inclined to number a list, wrap it in quotes, or add a
+ * closing remark. None of that is worth an error path, so it is all stripped.
+ */
+export function cleanVariant(line) {
+  let text = String(line ?? '')
+    .replace(/^\s*(?:[-*•]|\d+[.)])\s*/, '')
+    .trim()
+  // A trailing aside ("this should find the handler") is common; drop it.
+  text = text.split(/\s+[—–-]{1,2}\s+/)[0].trim()
+  if (text.length >= 2 && ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
+    text = text.slice(1, -1).trim()
+  }
+  if (text.length < MIN_VARIANT_CHARS || text.length > MAX_VARIANT_CHARS) return undefined
+  if (COMMENTARY.test(text) || REFUSAL.test(text)) return undefined
+  return text
+}
+
+/**
+ * Parse a model response into alternative queries, best effort.
+ *
+ * @param {string} body raw model output
+ * @param {string} query the original, excluded from the results
+ * @param {number} count most variants to keep
+ * @returns {string[]} deduplicated variants, in the order the model gave them
+ */
+export function parseVariants(body, query, count) {
+  const seen = new Set([String(query).trim().toLowerCase()])
+  const out = []
+  for (const line of String(body ?? '').split('\n')) {
+    if (out.length >= count) break
+    const variant = cleanVariant(line)
+    if (variant === undefined) continue
+    const key = variant.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(variant)
+  }
+  return out
+}
+
+/**
+ * Build an expander bound to one local model.
+ *
+ * @param {object} options
+ * @param {string} options.apiBase endpoint, no trailing slash
+ * @param {string} options.model model id
+ * @param {number} [options.timeoutMs] budget for the whole expansion
+ * @param {number} [options.count] most variants to ask for
+ * @param {typeof fetch} [options.fetchImpl] injection point for tests
+ */
+export function createExpander(options) {
+  const { apiBase, model, timeoutMs = 8_000, count = 4, fetchImpl = fetch } = options
+  const base = String(apiBase).replace(/\/+$/, '')
+
+  /** One request, bounded by its own deadline. */
+  async function request(query, budget, signal) {
+    // A non-finite budget would make AbortSignal.timeout throw, and the caller's
+    // catch would turn that into a silent fallback — a misconfiguration wearing
+    // the disguise of a slow model. Clamp instead.
+    const deadline = AbortSignal.timeout(Number.isFinite(budget) && budget > 0 ? budget : 8_000)
+    const combined = signal === undefined ? deadline : AbortSignal.any([signal, deadline])
+    const response = await fetchImpl(`${base}/api/generate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model,
+        prompt: PROMPT.replace('{{QUERY}}', query),
+        stream: false,
+        // A handful of short lines; a model allowed to ramble will.
+        options: { num_predict: 120, temperature: 0.4 },
+      }),
+      signal: combined,
+    })
+    if (!response.ok) throw new Error(`${base} responded ${response.status}`)
+    const payload = await response.json()
+    return typeof payload?.response === 'string' ? payload.response : ''
+  }
+
+  return {
+    model,
+    /**
+     * Alternative phrasings for a query.
+     *
+     * @param {string} query the original
+     * @param {AbortSignal} [signal] caller cancellation
+     * @returns {Promise<string[]>} the original first, then whatever else worked
+     */
+    async expand(query, signal) {
+      const original = String(query ?? '').trim()
+      if (original === '' || original.length > MAX_QUERY_CHARS) return [original]
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+        if (signal?.aborted) return [original]
+        try {
+          const body = await request(original, timeoutMs, signal)
+          return [original, ...parseVariants(body, original, count)]
+        } catch {
+          // Slow, wedged, or unreachable all mean the same thing here: search
+          // with the query we were given rather than failing the call.
+          if (signal?.aborted) return [original]
+        }
+      }
+      return [original]
+    },
+  }
+}
diff --git a/lib/focus.js b/lib/focus.js
new file mode 100644
index 0000000..77c97c0
--- /dev/null
+++ b/lib/focus.js
@@ -0,0 +1,215 @@
+/**
+ * Focus resolution: which slice of the workspace an agent is confined to.
+ *
+ * ## Why this exists
+ *
+ * A workspace-wide index has to rank across every part of a repository, and in
+ * a codebase built from many near-identical modules that is exactly where
+ * embedding similarity fails. In the repository this was written against there
+ * are eighteen controllers — each a state machine with the same idioms, the same
+ * naming and the same shape — spread across 228k lines. A query about one of
+ * them returns plausible fragments of all eighteen.
+ *
+ * Narrowing the index to the one being worked on removes the confusability
+ * rather than trying to rank through it, and it does three things at once:
+ *
+ * 1. **precision** — there are no near-duplicates to outrank the right answer;
+ * 2. **cold start** — ten files embed in seconds where six hundred took minutes;
+ * 3. **context** — code the agent never sees is code that is never re-sent on
+ *    every later step, which is where the money actually is.
+ *
+ * ## Resolution order
+ *
+ * Most explicit wins, and the last fallback is the workspace root — which is the
+ * behaviour that existed before focus did, so adopting this cannot regress a
+ * deployment that never configures it.
+ *
+ * The marker step is the interesting one: a folder that contains its own
+ * instructions *is* a scope. A controller directory holding a `CONTROLLER.md`
+ * becomes the world the agent sees, and the document that describes the module
+ * also defines its boundary. Nothing needed to be invented for that — the
+ * convention already means "this folder is self-describing".
+ */
+
+import { existsSync, statSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/**
+ * Files whose presence marks a directory as a scope root.
+ *
+ * Ordered by how specific they are: a `CONTROLLER.md` is a stronger claim about
+ * a directory than the `AGENTS.md` that sits at every repository root.
+ */
+export const DEFAULT_FOCUS_MARKERS = Object.freeze(['CONTROLLER.md', 'DEBUG_UI.md', 'AGENTS.md'])
+
+/** True when `path` is `root` itself or sits underneath it. */
+export function isInside(root, path) {
+  const prefix = root.endsWith(sep) ? root : root + sep
+  return path === root || path.startsWith(prefix)
+}
+
+/** True when `path` exists and is a directory. */
+function statIsDirectory(path) {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Every ancestor of `from` up to and including `stop`, nearest first. */
+export function ancestorsTo(from, stop) {
+  const out = []
+  let current = resolve(from)
+  const limit = resolve(stop)
+  for (;;) {
+    out.push(current)
+    if (current === limit) break
+    const parent = dirname(current)
+    // A path that is not under `stop`, or a filesystem root, ends the walk
+    // rather than looping.
+    if (parent === current || !isInside(limit, parent)) break
+    current = parent
+  }
+  return out
+}
+
+/**
+ * Resolve the focus directory for one session.
+ *
+ * @param {object} input
+ * @param {string} input.workspace absolute workspace root
+ * @param {string} [input.cwd] directory the session is working from
+ * @param {string} [input.explicit] a configured or caller-supplied focus
+ * @param {(path: string) => boolean} [input.isDirectory] injection point for tests
+ * @param {readonly string[]} [input.markers] scope-marker filenames
+ * @param {(path: string) => boolean} [input.exists] injection point for tests
+ * @param {{path: string, marker: string}[]} [input.scopes] scopes found by {@link discoverScopes}
+ * @returns {{root: string, source: 'explicit'|'scope'|'marker'|'workspace', marker?: string, problem?: string}}
+ */
+export function resolveFocus(input) {
+  const {
+    workspace,
+    cwd = workspace,
+    explicit = '',
+    markers = DEFAULT_FOCUS_MARKERS,
+    scopes = [],
+    exists = existsSync,
+    isDirectory = statIsDirectory,
+  } = input
+
+  // 1. An explicit focus wins, but a bad one is reported rather than silently
+  //    ignored: a typo that quietly fell back to the whole workspace would look
+  //    like the feature doing nothing.
+  const requested = String(explicit ?? '').trim()
+  if (requested !== '') {
+    const absolute = isAbsolute(requested) ? resolve(requested) : resolve(workspace, requested)
+    if (!isInside(workspace, absolute)) {
+      return {
+        root: resolve(workspace),
+        source: 'workspace',
+        problem: `focus "${requested}" is outside the workspace`,
+      }
+    }
+    if (!isDirectory(absolute)) {
+      return {
+        root: resolve(workspace),
+        source: 'workspace',
+        problem: `focus "${requested}" is not a directory`,
+      }
+    }
+    return { root: absolute, source: 'explicit' }
+  }
+
+  // 2. Nothing here adopts a discovered scope automatically, and that is
+  //    deliberate. A session sitting at the repository root is not thereby
+  //    *about* any one controller, and silently confining it to whichever scope
+  //    sorted first would hide code the session legitimately needs. Discovery
+  //    exists so a caller can be shown the scopes and name one; choosing is an
+  //    explicit act, which is what `focus` is for.
+
+  // 3. The nearest ancestor carrying a marker file. `cwd` is normally the
+  //    workspace root, at which point the root's own AGENTS.md matches and the
+  //    result is the workspace — the same answer the old code gave.
+  const start = isInside(workspace, resolve(cwd)) ? resolve(cwd) : resolve(workspace)
+  for (const directory of ancestorsTo(start, workspace)) {
+    for (const marker of markers) {
+      if (marker !== '' && exists(join(directory, marker))) {
+        return { root: directory, source: 'marker', marker }
+      }
+    }
+  }
+
+  // 4. The workspace.
+  return { root: resolve(workspace), source: 'workspace' }
+}
+
+/** A stable key for one focus directory, for index filenames. */
+export function focusKey(workspace, root) {
+  const rel = relative(resolve(workspace), resolve(root)).split(sep).join('/')
+  return rel === '' ? '.' : rel
+}
+
+/**
+ * Directories skipped while looking for scopes.
+ *
+ * A marker inside a dependency or a build directory describes somebody else's
+ * project, so discovering it would offer the user a scope they do not own.
+ */
+const DISCOVERY_SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', 'coverage', 'target',
+  '.next', '.nuxt', '.venv', 'venv', '__pycache__', 'vendor', '.cache',
+])
+
+/**
+ * Find every directory that declares itself a scope.
+ *
+ * This exists because walking up from the working directory cannot find a
+ * marker in a subdirectory, and in the repository this was written for that is
+ * the whole point: the session sits at the workspace root while the eighteen
+ * controllers each carry their own instructions further down. Inheritance and
+ * discovery are different questions — "what contains me?" versus "what is
+ * available?" — and a scope needs both.
+ *
+ * Results are workspace-relative and sorted, so a list shown to a user or a
+ * model is stable between calls.
+ *
+ * @param {object} input
+ * @param {string} input.workspace absolute workspace root
+ * @param {readonly string[]} [input.markers] marker filenames
+ * @param {number} [input.maxDepth] deepest directory level to scan
+ * @returns {Promise<{path: string, marker: string}[]>} discovered scopes
+ */
+export async function discoverScopes(input) {
+  const { workspace, markers = DEFAULT_FOCUS_MARKERS, maxDepth = 8 } = input
+  const root = resolve(workspace)
+  const found = []
+
+  const walk = async (directory, depth) => {
+    if (depth > maxDepth) return
+    let entries
+    try {
+      entries = await readdir(directory, { withFileTypes: true })
+    } catch {
+      return
+    }
+    const names = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name))
+    for (const marker of markers) {
+      if (names.has(marker)) {
+        const rel = relative(root, directory).split(sep).join('/')
+        found.push({ path: rel === '' ? '.' : rel, marker })
+        break
+      }
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.isSymbolicLink()) continue
+      if (DISCOVERY_SKIP_DIRS.has(entry.name)) continue
+      await walk(join(directory, entry.name), depth + 1)
+    }
+  }
+
+  await walk(root, 0)
+  found.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+  return found
+}
diff --git a/lib/paths.js b/lib/paths.js
new file mode 100644
index 0000000..a0f151d
--- /dev/null
+++ b/lib/paths.js
@@ -0,0 +1,72 @@
+/**
+ * Where this plugin keeps things on disk.
+ *
+ * Everything lives under `$DSH_HOME`, never inside the workspace. That is the
+ * whole point of the plugin's economics: the index holds a vector per code
+ * chunk, which for a 300k-line repository is tens of megabytes — several times
+ * the size of the source it describes. A multi-megabyte binary file appearing
+ * in a repository the user might commit, or that a `git status` might surface
+ * mid-task, is a worse outcome than the tokens it saves.
+ *
+ * The index is also disposable by construction. It is keyed by content hash, so
+ * deleting it costs one re-embed and nothing else — which is what makes it safe
+ * to treat as a cache rather than a document.
+ */
+
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+
+/** Plugin name. Also the `$DSH_HOME/<name>` directory. */
+export const PLUGIN_NAME = 'dsh-recall'
+
+/** The dsh home directory: `$DSH_HOME`, else `~/.dsh`. */
+export function resolveDshHome(env = process.env) {
+  const configured = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
+  return configured === '' ? join(homedir(), '.dsh') : resolve(configured)
+}
+
+/**
+ * A stable, filesystem-safe key for one workspace.
+ *
+ * The basename is for a human reading the directory listing; the hash is what
+ * actually identifies it, so two checkouts both named `app` cannot collide and
+ * one checkout moved between parents does not silently inherit the other's
+ * index.
+ */
+export function workspaceKey(cwd) {
+  const absolute = resolve(cwd)
+  const name =
+    basename(absolute)
+      .replace(/[^A-Za-z0-9._-]+/g, '-')
+      .replace(/^[-.]+|-+$/g, '') || 'workspace'
+  const hash = createHash('sha256').update(absolute).digest('hex').slice(0, 8)
+  return `${name}-${hash}`
+}
+
+/** Root of this plugin's own data, independent of any workspace. */
+export function pluginDataDir(dshHome) {
+  return join(dshHome, PLUGIN_NAME)
+}
+
+/** Per-workspace state directory. */
+export function workspaceStateDir(dshHome, cwd) {
+  return join(pluginDataDir(dshHome), 'workspaces', workspaceKey(cwd))
+}
+
+/** The SQLite index for one workspace. */
+/**
+ * The SQLite index for one workspace, optionally narrowed to one focus.
+ *
+ * The workspace-wide index deliberately keeps its original path. Focus is
+ * additive: a deployment that never sets one must find the index it already
+ * built, not silently re-embed the repository into a new file.
+ *
+ * @param {string} dshHome harness home
+ * @param {string} cwd workspace root
+ * @param {string} [focus] focus key, `.` for the workspace itself
+ */
+export function indexFile(dshHome, cwd, focus = '.') {
+  const base = workspaceStateDir(dshHome, cwd)
+  return focus === '.' ? join(base, 'index.sqlite') : join(base, 'focus', focus, 'index.sqlite')
+}
diff --git a/lib/rank.js b/lib/rank.js
new file mode 100644
index 0000000..36346aa
--- /dev/null
+++ b/lib/rank.js
@@ -0,0 +1,337 @@
+/**
+ * Ranking retrieved chunks.
+ *
+ * **Pure vector search is not good enough for code, and this is the whole reason
+ * the module exists.** An embedding of `getUserById` sits close to every other
+ * lookup function in the repository, so a query naming it returns ten plausible
+ * lookups and buries the actual definition. A keyword match has the opposite
+ * failure: it finds the definition instantly and misses the query that describes
+ * behaviour without naming it.
+ *
+ * The two are combined by **reciprocal rank fusion** rather than by adding
+ * normalised scores. Cosine similarity and a term-frequency score live on
+ * different scales, and the usual fix — min-max normalising each into [0,1] —
+ * is actively harmful here: when every candidate is unrelated, the similarities
+ * are tightly clustered, and stretching that cluster across the full range turns
+ * noise into a confident-looking ranking. Rank fusion is scale-free, so it
+ * cannot make that mistake, and a chunk found by only one of the two methods
+ * still surfaces.
+ */
+
+/** RRF damping. 60 is the value from the original TREC work; larger flattens. */
+const RRF_K = 60
+
+/** Terms shorter than this carry no signal in code and match everywhere. */
+const MIN_TERM_LENGTH = 2
+
+/** Words that appear in almost every source file and therefore rank nothing. */
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'then',
+  'const', 'let', 'var', 'function', 'return', 'import', 'export', 'class',
+  'def', 'self', 'new', 'use', 'are', 'was', 'were', 'not', 'but', 'you', 'how',
+  'does', 'what', 'where', 'which', 'who', 'why', 'can', 'should', 'would',
+])
+
+/** Lowercased haystacks, keyed by the matrix object they describe. */
+const haystacks = new WeakMap()
+
+/**
+ * Split an identifier into its words.
+ *
+ * `getUserById` must match the query terms `get`, `user`, `by` and `id`, because
+ * a caller writing a search phrase naturally writes them separately. Without
+ * this, the single most useful lexical signal in a codebase — a name spelled in
+ * camelCase — is invisible.
+ *
+ * @param {string} identifier
+ * @returns {string[]} lowercased words
+ */
+export function splitIdentifier(identifier) {
+  return identifier
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .filter((word) => word !== '')
+}
+
+/**
+ * The search terms of a query.
+ *
+ * Both the raw tokens and the sub-words of each identifier are kept, so a query
+ * of `getUserById` matches a chunk that spells it `get_user_by_id` as well as
+ * one that spells it identically.
+ *
+ * @param {string} query
+ * @returns {string[]} de-duplicated terms, longest first
+ */
+export function queryTerms(query) {
+  const found = new Set()
+  for (const raw of String(query).split(/[^A-Za-z0-9_$]+/)) {
+    if (raw === '') continue
+    const lower = raw.toLowerCase()
+    if (lower.length >= MIN_TERM_LENGTH && !STOPWORDS.has(lower)) found.add(lower)
+    if (raw.length >= MIN_TERM_LENGTH) {
+      for (const word of splitIdentifier(raw)) {
+        const part = word.toLowerCase()
+        if (part.length >= MIN_TERM_LENGTH && !STOPWORDS.has(part)) found.add(part)
+      }
+    }
+  }
+  return [...found].sort((left, right) => right.length - left.length)
+}
+
+/** The lowercased text a chunk is matched against, built once per matrix. */
+function haystackFor(matrix, row) {
+  let list = haystacks.get(matrix)
+  if (list === undefined) {
+    list = new Array(matrix.rows.length)
+    haystacks.set(matrix, list)
+  }
+  if (list[row.id] === undefined) {
+    const symbol = row.symbol === undefined ? '' : ` ${row.symbol}`
+    list[row.id] = `${row.path}${symbol} ${row.text}`.toLowerCase()
+  }
+  return list[row.id]
+}
+
+/**
+ * Score every chunk against the query terms.
+ *
+ * Matches in the path or the symbol are weighted above matches in the body,
+ * because a question about behaviour usually names the thing, and the name is
+ * what the path and symbol carry.
+ *
+ * @param {object} matrix
+ * @param {string[]} terms
+ * @returns {{lexical: Float64Array, matched: Uint8Array}} raw scores and a hit flag
+ */
+export function lexicalScores(matrix, terms) {
+  const count = matrix.rows.length
+  const lexical = new Float64Array(count)
+  const matched = new Uint8Array(count)
+  if (terms.length === 0) return { lexical, matched }
+
+  // Document frequency per term, for the inverse-document-frequency weight.
+  const frequency = new Map()
+  for (const term of terms) {
+    let seen = 0
+    for (let at = 0; at < count; at += 1) {
+      if (haystackFor(matrix, matrix.rows[at]).includes(term)) seen += 1
+    }
+    frequency.set(term, seen)
+  }
+
+  for (let at = 0; at < count; at += 1) {
+    const row = matrix.rows[at]
+    const hay = haystackFor(matrix, row)
+    const header = `${row.path} ${row.symbol ?? ''}`.toLowerCase()
+    let score = 0
+    for (const term of terms) {
+      const df = frequency.get(term) ?? 0
+      if (df === 0) continue
+      // Standard IDF, damped so a term present in every file still contributes.
+      const idf = Math.log(1 + count / (1 + df))
+      let occurrences = 0
+      let from = hay.indexOf(term)
+      while (from !== -1) {
+        occurrences += 1
+        from = hay.indexOf(term, from + term.length)
+      }
+      if (occurrences === 0) continue
+      const weight = header.includes(term) ? 3 : 1
+      score += idf * (1 + Math.log(occurrences)) * weight
+    }
+    if (score > 0) {
+      lexical[at] = score
+      matched[at] = 1
+    }
+  }
+  return { lexical, matched }
+}
+
+/** Indices ordered by score, descending, ties broken by index for determinism. */
+function orderBy(score) {
+  const indices = Array.from({ length: score.length }, (_, at) => at)
+  indices.sort((left, right) => score[right] - score[left] || left - right)
+  return indices
+}
+
+/**
+ * The excerpt a result shows.
+ *
+ * Head-truncated rather than tail-truncated: a function's signature, its
+ * parameters and its first statements are what identify it, while the tail of a
+ * long function is usually a closing brace and a return.
+ *
+ * @param {string} text chunk text
+ * @param {number} maxLines cap
+ * @returns {{excerpt: string, truncated: boolean}}
+ */
+export function excerptOf(text, maxLines) {
+  const lines = text.split('\n')
+  if (lines.length <= maxLines) return { excerpt: text, truncated: false }
+  return { excerpt: lines.slice(0, maxLines).join('\n'), truncated: true }
+}
+
+/**
+ * The fused order of every chunk for one query, before selection.
+ *
+ * Split out from ranking so several queries can be ranked against the same rows
+ * and merged: query expansion produces a handful of phrasings, each gets an
+ * order, and the orders are fused. Selecting results is a separate step because
+ * it is the only part that cares about limits and budgets.
+ *
+ * @param {object} input
+ * @param {object} input.matrix vector matrix and rows
+ * @param {Float32Array} input.queryVector unit query vector
+ * @param {string} input.query raw query text
+ * @param {number} [input.vectorWeight] fusion weight for the vector ranking
+ * @param {number} [input.lexicalWeight] fusion weight for the keyword ranking
+ * @returns {{order: number[], similarity: Float64Array, vectorBest: number, lexicalBest: number}}
+ */
+export function rankOrder(input) {
+  const { matrix, queryVector, query, vectorWeight = 0.7, lexicalWeight = 0.3 } = input
+  const count = matrix.rows.length
+  if (count === 0) {
+    return { order: [], similarity: new Float64Array(0), vectorBest: 0, lexicalBest: 0 }
+  }
+
+  const dimensions = matrix.dimensions
+  const similarity = new Float64Array(count)
+  for (let at = 0; at < count; at += 1) {
+    let sum = 0
+    const offset = at * dimensions
+    for (let dim = 0; dim < dimensions; dim += 1) sum += matrix.vectors[offset + dim] * queryVector[dim]
+    similarity[at] = sum
+  }
+
+  const terms = queryTerms(query)
+  const { lexical } = lexicalScores(matrix, terms)
+
+  const vectorOrder = orderBy(similarity)
+  const lexicalOrder = orderBy(lexical)
+  const vectorRank = new Int32Array(count).fill(count)
+  const lexicalRank = new Int32Array(count).fill(count)
+  for (let rank = 0; rank < count; rank += 1) vectorRank[vectorOrder[rank]] = rank
+  for (let rank = 0; rank < count; rank += 1) lexicalRank[lexicalOrder[rank]] = rank
+
+  const fused = new Float64Array(count)
+  for (let at = 0; at < count; at += 1) {
+    fused[at] = vectorWeight / (RRF_K + vectorRank[at]) + lexicalWeight / (RRF_K + lexicalRank[at])
+  }
+
+  return {
+    order: orderBy(fused),
+    similarity,
+    vectorBest: Number(similarity[vectorOrder[0]]?.toFixed(4) ?? 0),
+    lexicalBest: Number(lexical[lexicalOrder[0]]?.toFixed(4) ?? 0),
+  }
+}
+
+/**
+ * Merge several rankings of the same rows into one order, by rank.
+ *
+ * Used for query expansion: each alternative phrasing ranks every chunk, and a
+ * chunk that several phrasings agree on should outrank one that a single
+ * phrasing happened to like. Rank fusion again rather than adding scores,
+ * because the rankings come from different query vectors and their similarities
+ * are not on a comparable scale.
+ *
+ * A chunk missing from a ranking is simply absent from that ranking's
+ * contribution rather than penalised, so a phrasing that finds nothing does not
+ * drag anything down.
+ *
+ * @param {readonly (readonly number[])[]} rankings row indices, each in rank order
+ * @returns {number[]} row indices, best first
+ */
+export function fuseRankings(rankings) {
+  const present = rankings.filter((ranking) => Array.isArray(ranking) && ranking.length > 0)
+  if (present.length === 0) return []
+  if (present.length === 1) return [...present[0]]
+
+  const scores = new Map()
+  for (const ranking of present) {
+    for (let rank = 0; rank < ranking.length; rank += 1) {
+      const row = ranking[rank]
+      scores.set(row, (scores.get(row) ?? 0) + 1 / (RRF_K + rank))
+    }
+  }
+  // Ties break by row index, so the same input always gives the same output.
+  return [...scores.keys()].sort((left, right) => scores.get(right) - scores.get(left) || left - right)
+}
+
+/**
+ * Turn a fused order into the results a caller sees.
+ *
+ * @param {number[]} order row indices, best first
+ * @param {object} input
+ * @param {object} input.matrix
+ * @param {Float64Array} input.similarity per-row similarity, for reporting
+ * @param {number} [input.limit]
+ * @param {number} [input.perFile]
+ * @param {number} [input.excerptLines]
+ * @param {number} [input.totalLines]
+ * @returns {object[]} results
+ */
+export function selectFrom(order, input) {
+  const { matrix, similarity, limit = 8, perFile = 2, excerptLines = 80, totalLines = 400 } = input
+  const perFileUsed = new Map()
+  const results = []
+  // A shared line budget across the whole result set. The per-excerpt cap alone
+  // does not bound the response — `limit` does — and a chunk is already a
+  // semantic unit, so cutting one in half is how a search turns into a
+  // follow-up read that costs more than the lines it saved. Allocation is by
+  // rank, so the best answer gets the room.
+  let remaining = totalLines
+  for (const at of order) {
+    if (results.length >= limit) break
+    // Always return at least one result, however small the budget.
+    if (remaining <= 0 && results.length > 0) break
+    const row = matrix.rows[at]
+    if (row === undefined) continue
+    const used = perFileUsed.get(row.path) ?? 0
+    if (used >= perFile) continue
+    perFileUsed.set(row.path, used + 1)
+    const allowance = Math.max(1, Math.min(excerptLines, remaining))
+    const { excerpt, truncated } = excerptOf(row.text, allowance)
+    remaining -= excerpt.split('\n').length
+    results.push({
+      path: row.path,
+      startLine: row.startLine,
+      endLine: row.endLine,
+      ...(row.symbol === undefined ? {} : { symbol: row.symbol }),
+      similarity: Number(similarity[at].toFixed(4)),
+      excerpt,
+      truncated,
+    })
+  }
+  return results
+}
+
+/**
+ * Rank chunks for a query.
+ *
+ * @param {object} input
+ * @param {object} input.matrix vector matrix and rows
+ * @param {Float32Array} input.queryVector unit query vector
+ * @param {string} input.query raw query text
+ * @param {number} [input.limit] results to return
+ * @param {number} [input.perFile] most chunks one file may contribute
+ * @param {number} [input.excerptLines] lines per excerpt
+ * @param {number} [input.totalLines] total line budget
+ * @param {number} [input.vectorWeight] fusion weight for the vector ranking
+ * @param {number} [input.lexicalWeight] fusion weight for the keyword ranking
+ * @returns {{results: object[], vectorBest: number, lexicalBest: number}}
+ */
+export function rankChunks(input) {
+  const ranked = rankOrder(input)
+  const results = selectFrom(ranked.order, {
+    matrix: input.matrix,
+    similarity: ranked.similarity,
+    limit: input.limit,
+    perFile: input.perFile,
+    excerptLines: input.excerptLines,
+    totalLines: input.totalLines,
+  })
+  return { results, vectorBest: ranked.vectorBest, lexicalBest: ranked.lexicalBest }
+}
diff --git a/lib/rerank.js b/lib/rerank.js
new file mode 100644
index 0000000..b3501d3
--- /dev/null
+++ b/lib/rerank.js
@@ -0,0 +1,124 @@
+/**
+ * Re-ranking candidates on the local model.
+ *
+ * Cosine similarity ranks a chunk against a query in isolation. A small model
+ * reading the query *and* the candidate together does better — it can see that a
+ * chunk is about the right topic but the wrong side of it, which is exactly the
+ * mistake embeddings make.
+ *
+ * ## `undefined` is not zero
+ *
+ * The re-ranker answers with a score per candidate, or with **`undefined`** when
+ * it has no opinion — slow, wedged, unparseable, or scoring a different number
+ * of candidates than it was given. The caller must treat those differently:
+ * replacing a good embedding score with a zero because the model timed out would
+ * turn a working search into an empty one. No opinion means keep the ranking you
+ * had.
+ *
+ * This is why the module returns a bare array rather than an object with a
+ * status: there are exactly two outcomes, and one of them is "carry on".
+ */
+
+/** Attempts. Re-ranking is an improvement, not a requirement. */
+const MAX_ATTEMPTS = 2
+
+/** Characters sent per candidate. The head of a chunk identifies it. */
+const MAX_CANDIDATE_CHARS = 700
+
+/** Candidates scored in one call. Longer prompts get slower and vaguer. */
+const MAX_CANDIDATES = 12
+
+const PROMPT = `You score how well each code excerpt answers a developer's search query.
+
+Give each excerpt a whole number from 0 to 10:
+- 10: this is the code the query is asking about.
+- 5: same area, but not what was asked.
+- 0: unrelated.
+
+Answer with JSON only, no prose: {"scores": [n, n, ...]} with exactly one score per excerpt, in order.
+
+Query: {{QUERY}}
+
+{{CANDIDATES}}`
+
+/** Pull the first JSON array of numbers out of a model response. */
+export function parseScores(body) {
+  const text = String(body ?? '')
+  // Prefer the documented shape, then fall back to any bare array: models drift
+  // between the two and both are unambiguous.
+  const wrapped = /\{[^{}]*"scores"\s*:\s*\[([^\]]*)\]/i.exec(text)
+  const bare = wrapped === null ? /\[([^\]]*)\]/.exec(text) : null
+  const inner = wrapped?.[1] ?? bare?.[1]
+  if (inner === undefined) return undefined
+  const numbers = inner
+    .split(',')
+    .map((part) => Number.parseFloat(part.trim()))
+    .filter((value) => Number.isFinite(value))
+  return numbers.length === 0 ? undefined : numbers
+}
+
+/**
+ * Build a re-ranker bound to one local model.
+ *
+ * @param {object} options
+ * @param {string} options.apiBase endpoint, no trailing slash
+ * @param {string} options.model model id
+ * @param {number} [options.timeoutMs] budget for the whole call
+ * @param {typeof fetch} [options.fetchImpl] injection point for tests
+ */
+export function createReranker(options) {
+  const { apiBase, model, timeoutMs = 15_000, fetchImpl = fetch } = options
+  const base = String(apiBase).replace(/\/+$/, '')
+
+  return {
+    model,
+    /**
+     * Score candidates against a query.
+     *
+     * @param {string} query the search query
+     * @param {readonly string[]} candidates excerpt texts, in rank order
+     * @param {AbortSignal} [signal] caller cancellation
+     * @returns {Promise<number[] | undefined>} one score in 0..1 per candidate, in
+     *   order, or `undefined` when the model offered no usable opinion
+     */
+    async score(query, candidates, signal) {
+      const texts = candidates.slice(0, MAX_CANDIDATES)
+      if (texts.length === 0 || String(query ?? '').trim() === '') return undefined
+      const rendered = texts
+        .map((text, at) => `Excerpt ${at + 1}:\n${String(text).slice(0, MAX_CANDIDATE_CHARS)}`)
+        .join('\n\n')
+      const prompt = PROMPT.replace('{{QUERY}}', String(query).trim()).replace('{{CANDIDATES}}', rendered)
+
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+        if (signal?.aborted) return undefined
+        try {
+          // See the expander: a non-finite timeout must not become a silent
+          // "no opinion" that looks exactly like a slow model.
+          const deadline = AbortSignal.timeout(Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 15_000)
+          const combined = signal === undefined ? deadline : AbortSignal.any([signal, deadline])
+          const response = await fetchImpl(`${base}/api/generate`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+              model,
+              prompt,
+              stream: false,
+              options: { num_predict: 80, temperature: 0 },
+            }),
+            signal: combined,
+          })
+          if (!response.ok) throw new Error(`${base} responded ${response.status}`)
+          const payload = await response.json()
+          const scores = parseScores(payload?.response)
+          // A count mismatch is not a partial answer — it is a model that lost
+          // track of the list, and applying it would score the wrong candidates.
+          if (scores === undefined || scores.length !== texts.length) throw new Error('unusable score count')
+          return scores.map((value) => Math.max(0, Math.min(10, value)) / 10)
+        } catch {
+          if (signal?.aborted) return undefined
+        }
+      }
+      return undefined
+    },
+  }
+}
diff --git a/lib/store.js b/lib/store.js
new file mode 100644
index 0000000..fc6f28c
--- /dev/null
+++ b/lib/store.js
@@ -0,0 +1,285 @@
+/**
+ * The SQLite index.
+ *
+ * `node:sqlite` rather than a dependency: the plugin ships with no build step
+ * and no install-time code, so every package it imports is one the user has to
+ * trust and keep current. Node has carried a synchronous SQLite binding since
+ * 22.5, and a synchronous API is genuinely the right shape here — the work is
+ * local, short, and on the critical path of a tool call, so an async wrapper
+ * would only add interleaving to reason about.
+ *
+ * **Why vectors are stored and not merely ranked at write time.** A search must
+ * be able to answer a query it has never seen, so the index has to keep the
+ * vectors themselves. They are written as unit-length `Float32Array` blobs, so
+ * scoring is a dot product and nothing else.
+ *
+ * **Why the model and width are recorded.** Vectors from two different models,
+ * or two widths of the same model, are not comparable, and mixing them produces
+ * plausible-looking but meaningless ranking. A change to either is detected on
+ * open and the index is discarded rather than silently degraded.
+ */
+
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+/** Schema version. A bump discards existing indexes. */
+const SCHEMA_VERSION = '1'
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS files (
+  path       TEXT PRIMARY KEY,
+  hash       TEXT NOT NULL,
+  bytes      INTEGER NOT NULL,
+  chunks     INTEGER NOT NULL,
+  indexed_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS chunks (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  path       TEXT NOT NULL,
+  start_line INTEGER NOT NULL,
+  end_line   INTEGER NOT NULL,
+  symbol     TEXT,
+  text       TEXT NOT NULL,
+  dim        INTEGER NOT NULL,
+  vec        BLOB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS chunks_path_idx ON chunks(path);
+`
+
+/** One indexed chunk, metadata only. */
+/** @typedef {{id: number, path: string, startLine: number, endLine: number, symbol?: string, text: string}} ChunkRow */
+
+export class RecallIndex {
+  /** @param {string} file absolute path to the index database */
+  constructor(file) {
+    this.file = file
+    /** @type {DatabaseSync | undefined} */
+    this.db = undefined
+    /** Cached scoring matrix, dropped on every write. */
+    this.cached = undefined
+  }
+
+  /**
+   * Open the database, creating it when absent.
+   *
+   * @param {{model: string, dimensions: number, apiBase: string}} identity
+   *   the embedding identity this index is only valid under
+   * @returns {{discarded?: string}} what was thrown away, when the identity moved
+   */
+  open(identity) {
+    mkdirSync(dirname(this.file), { recursive: true })
+    this.db = new DatabaseSync(this.file)
+    // WAL keeps a search from blocking a concurrent sync; the index is a cache
+    // and losing the tail of a write on power loss is acceptable.
+    this.db.exec('PRAGMA journal_mode = WAL')
+    this.db.exec('PRAGMA synchronous = NORMAL')
+    this.db.exec(SCHEMA)
+    return this.recheck(identity)
+  }
+
+  /**
+   * Re-validate the stored embedding identity against a live settings snapshot.
+   *
+   * Called on every tool call, not just on open, because the settings namespace
+   * is editable at runtime: pointing the plugin at a different model must
+   * invalidate the existing vectors rather than silently mix two incompatible
+   * spaces into one ranking.
+   *
+   * @param {{model: string, dimensions: number, apiBase: string}} identity
+   * @returns {{discarded?: string}} what was thrown away, when the identity moved
+   */
+  recheck(identity) {
+    const previous = {
+      version: this.#meta('schema_version'),
+      model: this.#meta('model'),
+      dimensions: this.#meta('dimensions'),
+    }
+
+    let discarded
+    if (previous.version !== undefined && previous.version !== SCHEMA_VERSION) {
+      discarded = `schema version changed from ${previous.version} to ${SCHEMA_VERSION}`
+    } else if (previous.model !== undefined && previous.model !== identity.model) {
+      discarded = `embedding model changed from "${previous.model}" to "${identity.model}"`
+    } else if (previous.dimensions !== undefined && previous.dimensions !== String(identity.dimensions)) {
+      discarded = `embedding width changed from ${previous.dimensions} to ${identity.dimensions}`
+    }
+
+    if (discarded !== undefined) this.#wipe()
+
+    this.#setMeta('schema_version', SCHEMA_VERSION)
+    this.#setMeta('model', identity.model)
+    this.#setMeta('dimensions', String(identity.dimensions))
+    this.#setMeta('api_base', identity.apiBase)
+    return discarded === undefined ? {} : { discarded }
+  }
+
+  /** Close the database, if open. Safe to call twice. */
+  close() {
+    try {
+      this.db?.close()
+    } catch {
+      // Already closed, or the handle was lost with the process. Nothing to do.
+    }
+    this.db = undefined
+    this.cached = undefined
+  }
+
+  /** Drop every row and reset the identity. */
+  #wipe() {
+    this.db.exec('DELETE FROM chunks; DELETE FROM files; DELETE FROM meta;')
+    this.cached = undefined
+  }
+
+  /** One meta value, or `undefined`. */
+  #meta(key) {
+    const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key)
+    return row === undefined ? undefined : row.value
+  }
+
+  /** Write one meta value. */
+  #setMeta(key, value) {
+    this.db
+      .prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+      .run(key, value)
+  }
+
+  /** `path -> content hash` for every indexed file. */
+  fileHashes() {
+    const out = new Map()
+    for (const row of this.db.prepare('SELECT path, hash FROM files').all()) out.set(row.path, row.hash)
+    return out
+  }
+
+  /**
+   * Byte size of each named file, for the files that are indexed.
+   *
+   * This is what makes an honest "returned less than it would have read" figure
+   * possible: the index already recorded every file's size when it embedded it,
+   * so the alternative to an excerpt can be stated without reading a single
+   * source file at query time.
+   *
+   * @param {readonly string[]} paths workspace-relative paths
+   * @returns {Map<string, number>} only the paths that are indexed
+   */
+  bytesFor(paths) {
+    const out = new Map()
+    if (paths.length === 0) return out
+    const statement = this.db.prepare('SELECT bytes FROM files WHERE path = ?')
+    for (const path of paths) {
+      const row = statement.get(path)
+      if (row !== undefined) out.set(path, row.bytes)
+    }
+    return out
+  }
+
+  /** Counts for the status surface. */
+  stats() {
+    const files = this.db.prepare('SELECT COUNT(*) AS n FROM files').get()?.n ?? 0
+    const chunks = this.db.prepare('SELECT COUNT(*) AS n FROM chunks').get()?.n ?? 0
+    const bytes = this.db.prepare('SELECT COALESCE(SUM(bytes), 0) AS n FROM files').get()?.n ?? 0
+    return { files, chunks, bytes }
+  }
+
+  /**
+   * Replace one file's chunks atomically.
+   *
+   * @param {string} path workspace-relative path
+   * @param {string} hash content hash
+   * @param {number} bytes file size
+   * @param {{startLine: number, endLine: number, symbol?: string, text: string, vec: Float32Array}[]} chunks
+   */
+  replaceFile(path, hash, bytes, chunks) {
+    this.db.exec('BEGIN IMMEDIATE')
+    try {
+      this.db.prepare('DELETE FROM chunks WHERE path = ?').run(path)
+      const insert = this.db.prepare(
+        'INSERT INTO chunks (path, start_line, end_line, symbol, text, dim, vec) VALUES (?, ?, ?, ?, ?, ?, ?)',
+      )
+      for (const chunk of chunks) {
+        insert.run(
+          path,
+          chunk.startLine,
+          chunk.endLine,
+          chunk.symbol ?? null,
+          chunk.text,
+          chunk.vec.length,
+          new Uint8Array(chunk.vec.buffer, chunk.vec.byteOffset, chunk.vec.byteLength),
+        )
+      }
+      this.db
+        .prepare(
+          `INSERT INTO files (path, hash, bytes, chunks, indexed_at) VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(path) DO UPDATE SET
+             hash = excluded.hash, bytes = excluded.bytes,
+             chunks = excluded.chunks, indexed_at = excluded.indexed_at`,
+        )
+        .run(path, hash, bytes, chunks.length, Date.now())
+      this.db.exec('COMMIT')
+    } catch (error) {
+      this.db.exec('ROLLBACK')
+      throw error
+    }
+    this.cached = undefined
+  }
+
+  /** Forget files that no longer exist on disk. Returns how many were dropped. */
+  prune(toRemove) {
+    if (toRemove.length === 0) return 0
+    this.db.exec('BEGIN IMMEDIATE')
+    try {
+      const dropChunks = this.db.prepare('DELETE FROM chunks WHERE path = ?')
+      const dropFile = this.db.prepare('DELETE FROM files WHERE path = ?')
+      for (const path of toRemove) {
+        dropChunks.run(path)
+        dropFile.run(path)
+      }
+      this.db.exec('COMMIT')
+    } catch (error) {
+      this.db.exec('ROLLBACK')
+      throw error
+    }
+    this.cached = undefined
+    return toRemove.length
+  }
+
+  /**
+   * Load every chunk for scoring.
+   *
+   * One contiguous `Float32Array` and a parallel row list, built once and reused
+   * until the next write. At 300k lines of source this is a few tens of
+   * megabytes — the alternative, a blob read per query, would pay SQLite's row
+   * overhead on every search for no benefit, since a search visits every row
+   * anyway.
+   *
+   * @returns {{vectors: Float32Array, rows: ChunkRow[], dimensions: number}}
+   */
+  matrix() {
+    if (this.cached !== undefined) return this.cached
+    const raw = this.db
+      .prepare('SELECT id, path, start_line, end_line, symbol, text, dim, vec FROM chunks ORDER BY id')
+      .all()
+    const dimensions = raw.length === 0 ? 0 : raw[0].dim
+    const vectors = new Float32Array(raw.length * dimensions)
+    const rows = new Array(raw.length)
+    for (let at = 0; at < raw.length; at += 1) {
+      const row = raw[at]
+      const view = new Float32Array(row.vec.buffer, row.vec.byteOffset, row.vec.byteLength / 4)
+      vectors.set(view, at * dimensions)
+      rows[at] = {
+        id: row.id,
+        path: row.path,
+        startLine: row.start_line,
+        endLine: row.end_line,
+        ...(row.symbol === null ? {} : { symbol: row.symbol }),
+        text: row.text,
+      }
+    }
+    this.cached = { vectors, rows, dimensions }
+    return this.cached
+  }
+}
diff --git a/lib/usage.js b/lib/usage.js
new file mode 100644
index 0000000..6208e28
--- /dev/null
+++ b/lib/usage.js
@@ -0,0 +1,160 @@
+/**
+ * What one conversation got, and what to do with it.
+ *
+ * Two jobs, both pure:
+ *
+ * 1. **Derive** the small record a tool call leaves in the session log. The
+ *    harness persists `output.presentationMeta` verbatim as the `meta` of the
+ *    `tool/result` event, so this is the one place a result can state facts
+ *    about itself without inventing an event type or a side channel.
+ * 2. **Fold** those records into a running total per conversation. The fold is
+ *    the projection unit's transition function, which the framework requires to
+ *    be pure and to return the *same reference* for events it does not care
+ *    about — an unchanged reference costs nothing downstream, while a fresh
+ *    object on every tool call would republish on every step.
+ *
+ * ## Why `sourceBytes` rather than a headline saving
+ *
+ * The honest comparison is between what the caller received and what reading
+ * those same files would have cost. The index already recorded every file's
+ * size when it embedded it, so the second figure costs nothing at query time.
+ *
+ * It is still an **upper bound**, and the numbers are labelled that way
+ * everywhere they surface: a careful agent might have read one of those four
+ * files rather than all four. A figure that flatters the tool is worse than no
+ * figure, because it stops being believed the first time somebody checks.
+ */
+
+/** State for a conversation that has never called the tool. */
+export function emptyUsage() {
+  return {
+    version: 1,
+    searches: 0,
+    indexes: 0,
+    failed: 0,
+    excerpts: 0,
+    returnedBytes: 0,
+    sourceBytes: 0,
+    files: 0,
+    weak: 0,
+    // Bytes of avoided context multiplied by the steps that have re-read them.
+    // Accumulated here rather than derived, because deriving it needs a step
+    // count this state does not own — and the fold sees every step anyway.
+    rereadBytes: 0,
+    lastFocus: '',
+  }
+}
+
+/** The context a conversation is carrying that it would not have, in bytes. */
+function avoidedBytesOf(state) {
+  return Math.max(0, state.sourceBytes - state.returnedBytes)
+}
+
+/**
+ * The record one call writes into the session log.
+ *
+ * Deliberately tiny: it is appended for every recall call and replayed on every
+ * projection rebuild, so it carries totals and never content.
+ *
+ * @param {{action?: string, query?: string}} args the validated call arguments
+ * @param {Record<string, any>} value the canonical result
+ * @returns {{recall: Record<string, any>}} the persisted metadata
+ */
+export function deriveUsage(args, value) {
+  const action = value?.action ?? args?.action ?? 'search'
+  const record = { action }
+  if (value?.ok === false) record.failed = 1
+  if (typeof value?.focus?.path === 'string') record.focus = value.focus.path
+  if (value?.weak === true) record.weak = 1
+
+  if (action === 'search' && Array.isArray(value?.results)) {
+    record.excerpts = value.results.length
+    record.returnedBytes = value.results.reduce(
+      (sum, result) => sum + Buffer.byteLength(String(result?.excerpt ?? ''), 'utf8'),
+      0,
+    )
+  }
+  if (action === 'index' && typeof value?.index?.embedded === 'number') {
+    record.embedded = value.index.embedded
+  }
+  if (typeof value?.measure?.sourceBytes === 'number') {
+    record.sourceBytes = value.measure.sourceBytes
+    record.files = value.measure.files
+  }
+  return { recall: record }
+}
+
+/**
+ * Fold one session event into the running total.
+ *
+ * @param {ReturnType<typeof emptyUsage>} state state covering all prior events
+ * @param {{type?: string, meta?: any}} event the next committed session event
+ * @returns the next state, or **the same reference** when not this unit's event
+ */
+export function foldUsage(state, event) {
+  // Every step re-reads whatever the conversation is already carrying, so each
+  // step adds the avoided-so-far to the compounding total. This is what makes
+  // the figure exact rather than an estimate the caller has to supply.
+  if (event?.type === 'step/start') {
+    const carried = avoidedBytesOf(state)
+    if (carried === 0) return state
+    return { ...state, rereadBytes: state.rereadBytes + carried }
+  }
+
+  const record = event?.type === 'tool/result' ? event.meta?.recall : undefined
+  if (record === undefined || record === null || typeof record !== 'object') return state
+
+  const next = {
+    ...state,
+    searches: state.searches + (record.action === 'search' ? 1 : 0),
+    indexes: state.indexes + (record.action === 'index' ? 1 : 0),
+    failed: state.failed + (record.failed === 1 ? 1 : 0),
+    excerpts: state.excerpts + (record.excerpts ?? 0),
+    returnedBytes: state.returnedBytes + (record.returnedBytes ?? 0),
+    sourceBytes: state.sourceBytes + (record.sourceBytes ?? 0),
+    files: state.files + (record.files ?? 0),
+    weak: state.weak + (record.weak === 1 ? 1 : 0),
+    lastFocus: typeof record.focus === 'string' ? record.focus : state.lastFocus,
+  }
+  return next
+}
+
+/**
+ * The derived figures a surface shows, computed from state.
+ *
+ * Kept out of the state itself so the persisted fold stays a plain running
+ * total: anything derivable is derived on read, which is what lets the formula
+ * change without invalidating every checkpoint in the cache.
+ *
+ * @param {ReturnType<typeof emptyUsage>} state folded totals
+ * @param {{cacheReadPricePerMillion?: number}} [assumptions]
+ * @returns {Record<string, number|string|boolean>}
+ */
+export function usageSummary(state, assumptions = {}) {
+  const { cacheReadPricePerMillion = 0.007 } = assumptions
+  // What a read would have cost, less what the excerpt did cost.
+  const avoidedBytes = avoidedBytesOf(state)
+  // bytes/4 is an approximation of tokens; labelled as one wherever it is shown.
+  const avoidedTokens = Math.round(avoidedBytes / 4)
+  const compression = state.sourceBytes > 0 ? state.sourceBytes / Math.max(1, state.returnedBytes) : 0
+  // The compounding figure: context kept out, re-read once per step since.
+  const rereadTokens = Math.round((state.rereadBytes ?? 0) / 4)
+  const avoidedUsd = ((avoidedTokens + rereadTokens) / 1_000_000) * cacheReadPricePerMillion
+
+  return {
+    searches: state.searches,
+    indexes: state.indexes,
+    failed: state.failed,
+    excerpts: state.excerpts,
+    files: state.files,
+    weak: state.weak,
+    returnedBytes: state.returnedBytes,
+    sourceBytes: state.sourceBytes,
+    avoidedBytes,
+    avoidedTokens,
+    compression: Number(compression.toFixed(2)),
+    rereadTokens,
+    avoidedUsd: Number(avoidedUsd.toFixed(4)),
+    lastFocus: state.lastFocus,
+  }
+}
diff --git a/lib/walk.js b/lib/walk.js
new file mode 100644
index 0000000..db0cd20
--- /dev/null
+++ b/lib/walk.js
@@ -0,0 +1,207 @@
+/**
+ * Workspace file discovery.
+ *
+ * Two rules shape everything here.
+ *
+ * **The walk never follows a symlink.** A symlink loop turns a bounded walk into
+ * an unbounded one, and a symlink out of the workspace turns "index this
+ * project" into "index this machine". Both are worse than missing a file.
+ *
+ * **The walk is deterministic.** Candidates come back in sorted path order, so
+ * a partially-completed cold index covers the same prefix on the next run. A
+ * filesystem-ordered walk would re-embed a different subset every time and
+ * never converge on a warm index.
+ */
+
+import { readdir } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+
+/**
+ * Directory names skipped at any depth.
+ *
+ * These are dependency stores and build output: large, machine-generated, and
+ * never the answer to a question about this codebase. Indexing them would
+ * multiply the embedding cost of a cold start by an order of magnitude and
+ * return vendored copies of code the user does not own.
+ */
+export const DEFAULT_SKIP_DIRS = Object.freeze([
+  'node_modules',
+  '.git',
+  '.hg',
+  '.svn',
+  'dist',
+  'build',
+  'out',
+  'output',
+  'target',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.output',
+  '.turbo',
+  '.cache',
+  '.parcel-cache',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  'vendor',
+  'Pods',
+  '.idea',
+  '.vscode',
+  '.gradle',
+  '.terraform',
+  'tmp',
+  '.tmp',
+])
+
+/**
+ * Extensions indexed by default.
+ *
+ * Markup and prose are deliberately absent. A question that names a symbol wants
+ * the code that defines it, and a README that mentions the symbol is a worse
+ * answer that still costs tokens. Deployments that want documentation indexed
+ * add the extension through `extensions` in the config.
+ */
+export const DEFAULT_EXTENSIONS = Object.freeze([
+  'ts', 'tsx', 'mts', 'cts',
+  'js', 'jsx', 'mjs', 'cjs',
+  'py', 'rb', 'go', 'rs', 'java', 'kt', 'kts', 'scala', 'swift',
+  'c', 'h', 'cc', 'cpp', 'cxx', 'hpp', 'hh', 'cs',
+  'php', 'pl', 'lua', 'sh', 'bash', 'zsh',
+  'sql', 'graphql', 'proto', 'vue', 'svelte',
+])
+
+/**
+ * Translate a glob into an anchored regular expression.
+ *
+ * Supports `**` (any depth, including none), `*` (within one path segment), `?`
+ * (one non-separator character) and a trailing `/` (directory and everything
+ * under it). Written out rather than pulled from a dependency because the plugin
+ * ships with no build step and no install-time code.
+ *
+ * @param {string} pattern glob, using `/` as the separator on every platform
+ * @returns {RegExp} anchored matcher over a `/`-separated relative path
+ */
+export function globToRegExp(pattern) {
+  const normalized = pattern.trim().replace(/\\/g, '/').replace(/^\.\//, '')
+  let source = ''
+  for (let at = 0; at < normalized.length; at += 1) {
+    const char = normalized[at]
+    if (char === '*') {
+      const doubled = normalized[at + 1] === '*'
+      if (doubled) {
+        // `**/` consumes any number of segments, so `**/foo` also matches `foo`.
+        if (normalized[at + 2] === '/') {
+          source += '(?:[^/]*/)*'
+          at += 2
+        } else {
+          source += '.*'
+          at += 1
+        }
+      } else {
+        source += '[^/]*'
+      }
+    } else if (char === '?') {
+      source += '[^/]'
+    } else if (char === '/') {
+      source += '/'
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  // A trailing `/` names a directory: match it and everything beneath it.
+  if (source.endsWith('/')) source += '.*'
+  return new RegExp(`^(?:${source})$`)
+}
+
+/** Whether a `/`-separated relative path is matched by any of `patterns`. */
+export function matchesAny(relPath, patterns) {
+  for (const pattern of patterns) {
+    if (pattern === '') continue
+    if (globToRegExp(pattern).test(relPath)) return true
+  }
+  return false
+}
+
+/** The extension of a path, lowercased, without the dot. */
+export function extensionOf(path) {
+  const name = path.slice(path.lastIndexOf('/') + 1)
+  const dot = name.lastIndexOf('.')
+  return dot <= 0 ? '' : name.slice(dot + 1).toLowerCase()
+}
+
+/**
+ * List indexable files beneath `root`.
+ *
+ * @param {string} root absolute directory to walk
+ * @param {object} [options]
+ * @param {readonly string[]} [options.extensions] allowed extensions, without dots
+ * @param {readonly string[]} [options.skipDirs] directory names skipped at any depth
+ * @param {readonly string[]} [options.exclude] glob patterns over the relative path
+ * @param {number} [options.maxFiles] stop after this many candidates
+ * @param {number} [options.maxDepth] deepest directory level to enter
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<{files: {path: string, absolute: string}[], truncated: boolean, skippedFiles: number}>}
+ */
+export async function listCodeFiles(root, options = {}) {
+  const {
+    extensions = DEFAULT_EXTENSIONS,
+    skipDirs = DEFAULT_SKIP_DIRS,
+    exclude = [],
+    maxFiles = 20_000,
+    maxDepth = 24,
+    signal,
+  } = options
+
+  const wanted = new Set(extensions.map((value) => String(value).toLowerCase()))
+  const skip = new Set(skipDirs)
+  const files = []
+  let truncated = false
+  let skippedFiles = 0
+
+  /** Depth-first, pushing directories in reverse so the pop order is alphabetical. */
+  const stack = [{ dir: root, depth: 0 }]
+  while (stack.length > 0) {
+    if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+    const { dir, depth } = stack.pop()
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      // An unreadable directory is a gap in the index, not a failure of it.
+      continue
+    }
+    for (const entry of entries) {
+      // Never traverse a symlink: `dirent.isDirectory()` is false for one, so a
+      // link to a directory is skipped rather than followed.
+      if (entry.isSymbolicLink()) {
+        skippedFiles += 1
+        continue
+      }
+      const absolute = join(dir, entry.name)
+      const relPath = relative(root, absolute).split(sep).join('/')
+      if (entry.isDirectory()) {
+        if (skip.has(entry.name)) continue
+        if (depth >= maxDepth) continue
+        if (matchesAny(relPath, exclude)) continue
+        stack.push({ dir: absolute, depth: depth + 1 })
+        continue
+      }
+      if (!entry.isFile()) continue
+      if (!wanted.has(extensionOf(entry.name))) continue
+      if (matchesAny(relPath, exclude)) continue
+      if (files.length >= maxFiles) {
+        truncated = true
+        continue
+      }
+      files.push({ path: relPath, absolute })
+    }
+  }
+
+  files.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+  return { files, truncated, skippedFiles }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..01fcfe7
--- /dev/null
+++ b/package.json
@@ -0,0 +1,55 @@
+{
+  "name": "dsh-recall",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Local-embedding code recall for DeepSeek Harness — returns ranked excerpts with line ranges instead of whole files, so the context window stops growing with every read.",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./client": {
+      "default": "./client/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "client",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "code-search",
+    "embeddings",
+    "context",
+    "tokens"
+  ],
+  "license": "MIT"
+}
diff --git a/scripts/baseline.mjs b/scripts/baseline.mjs
new file mode 100644
index 0000000..3c9f0ec
--- /dev/null
+++ b/scripts/baseline.mjs
@@ -0,0 +1,259 @@
+/**
+ * The before/after instrument.
+ *
+ * Turns "recall should save tokens" into a number that can be re-run. It reads
+ * two independent stores, because they answer different questions:
+ *
+ *   - the cost ledger knows **money and per-request volume**: requests made,
+ *     cache-read tokens, and therefore the average context each request carried.
+ *     That average is the figure this whole workstream is measured against.
+ *   - the session projection cache knows **context shape**: the surface each
+ *     session reached, and whether that session used recall at all.
+ *
+ * Run it before the plugin sees real use to capture the baseline, then run it
+ * again after. Sessions that used recall are the "after" group; everything else
+ * is the baseline. Nothing is inferred — when there is no "after" group it says
+ * so instead of printing a table of zeroes.
+ *
+ *   node scripts/baseline.mjs [--ledger <path>] [--cache <path>] [--json]
+ */
+
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const DSH_HOME = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+
+function argValue(flag, fallback) {
+  const at = process.argv.indexOf(flag)
+  return at === -1 ? fallback : process.argv[at + 1]
+}
+
+const LEDGER = argValue('--ledger', join(DSH_HOME, 'storages', 'cost-meter', 'ledger.json'))
+const CACHE = argValue('--cache', join(DSH_HOME, 'storages', 'session_projcache.json'))
+const AS_JSON = process.argv.includes('--json')
+
+/** Format an integer with thousands separators. */
+const n = (value) => Math.round(value).toLocaleString('en-GB')
+
+/** A compact human figure. */
+function short(value) {
+  if (value >= 1e9) return (value / 1e9).toFixed(1) + 'B'
+  if (value >= 1e6) return (value / 1e6).toFixed(1) + 'M'
+  if (value >= 1e3) return Math.round(value / 1e3) + 'k'
+  return String(Math.round(value))
+}
+
+async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Per-session request volume and cost, from the ledger.
+ *
+ * The ledger groups by day, and a session that spans midnight appears under both
+ * — so sessions are merged by id rather than listed.
+ */
+function sessionsFromLedger(ledger) {
+  const byId = new Map()
+  for (const day of Object.values(ledger?.days ?? {})) {
+    for (const session of day.sessions ?? []) {
+      const id = session.id
+      if (typeof id !== 'string') continue
+      const entry = byId.get(id) ?? { id, calls: 0, cacheRead: 0, input: 0, output: 0, cost: 0 }
+      entry.calls += session.calls ?? 0
+      entry.cacheRead += session.cacheRead ?? 0
+      entry.input += session.input ?? 0
+      entry.output += session.output ?? 0
+      entry.cost += session.cost ?? 0
+      byId.set(id, entry)
+    }
+  }
+  for (const entry of byId.values()) {
+    // What each request carried: the cached prefix plus the new input.
+    entry.contextPerRequest = entry.calls > 0 ? (entry.cacheRead + entry.input) / entry.calls : 0
+  }
+  return [...byId.values()]
+}
+
+/** Context shape and recall usage, from the projection cache. */
+function sessionsFromCache(cache) {
+  const rows = cache?.tables?.sessions ?? {}
+  const out = []
+  for (const [id, entry] of Object.entries(rows)) {
+    const units = entry?.rows ?? {}
+    const pressure = units.contextPressure?.val
+    const stats = units.sessionStats?.val
+    const usage = units.recallUsage?.val
+    out.push({
+      id,
+      cwd: entry?.identity?.cwd ?? '(unknown)',
+      surfaceTokens: pressure?.surfaceTokens ?? 0,
+      contextWindow: pressure?.contextWindow ?? 0,
+      steps: stats?.steps ?? 0,
+      turns: stats?.turns ?? 0,
+      recalls: usage?.searches ?? 0,
+      usedRecall: (usage?.searches ?? 0) > 0,
+    })
+  }
+  return out
+}
+
+/** Mean and median of a numeric list. */
+function describe(values) {
+  if (values.length === 0) return { count: 0, mean: 0, median: 0, max: 0 }
+  const sorted = [...values].sort((a, b) => a - b)
+  const mean = sorted.reduce((sum, value) => sum + value, 0) / sorted.length
+  return {
+    count: sorted.length,
+    mean,
+    median: sorted[Math.floor(sorted.length / 2)],
+    max: sorted[sorted.length - 1],
+  }
+}
+
+async function main() {
+  const ledger = await readJson(LEDGER, undefined)
+  const cache = await readJson(CACHE, undefined)
+
+  if (ledger === undefined && cache === undefined) {
+    console.error(`no data. Looked for:\n  ${LEDGER}\n  ${CACHE}`)
+    process.exitCode = 1
+    return
+  }
+
+  const money = sessionsFromLedger(ledger)
+  const shape = sessionsFromCache(cache)
+  const shapeById = new Map(shape.map((row) => [row.id, row]))
+
+  const totalCalls = money.reduce((sum, row) => sum + row.calls, 0)
+  const totalCacheRead = money.reduce((sum, row) => sum + row.cacheRead, 0)
+  const totalInput = money.reduce((sum, row) => sum + row.input, 0)
+  const totalCost = money.reduce((sum, row) => sum + row.cost, 0)
+  const averageContext = totalCalls > 0 ? (totalCacheRead + totalInput) / totalCalls : 0
+
+  // Workspaces, so a comparison is not an average over unrelated projects.
+  const byWorkspace = new Map()
+  for (const row of money) {
+    const cwd = shapeById.get(row.id)?.cwd ?? '(not in projection cache)'
+    const entry = byWorkspace.get(cwd) ?? { cwd, sessions: 0, calls: 0, cacheRead: 0, input: 0, cost: 0 }
+    entry.sessions += 1
+    entry.calls += row.calls
+    entry.cacheRead += row.cacheRead
+    entry.input += row.input
+    entry.cost += row.cost
+    byWorkspace.set(cwd, entry)
+  }
+
+  // The comparison the objective names: average context PER REQUEST, which only
+  // the ledger knows, split by whether that session used recall. Peak surface is
+  // reported separately because it answers a different question — what a session
+  // grew to, not what each request carried.
+  const withRecall = money.filter((row) => shapeById.get(row.id)?.usedRecall === true)
+  const without = money.filter((row) => shapeById.get(row.id)?.usedRecall !== true)
+  const pressure = shape.filter((row) => row.surfaceTokens > 0)
+  const window = pressure[0]?.contextWindow ?? 0
+  const trigger = Math.round(window * 0.8)
+
+  const report = {
+    baseline: {
+      sessions: money.length,
+      requests: totalCalls,
+      cacheReadTokens: totalCacheRead,
+      inputTokens: totalInput,
+      costUsd: Number(totalCost.toFixed(2)),
+      // Cost-weighted: every request counts once. This is the figure that maps
+      // to money, and the one the objective names.
+      pooledAverageContextPerRequest: Math.round(averageContext),
+      // Typical: every session counts once. Differs from the pooled figure by
+      // whatever the largest sessions do, which here is a factor of two — so
+      // quoting only one of them would mislead in a different direction
+      // depending on which was chosen.
+      meanSessionContextPerRequest: Math.round(describe(money.map((row) => row.contextPerRequest)).mean),
+    },
+    workspaces: [...byWorkspace.values()]
+      .sort((a, b) => b.calls - a.calls)
+      .map((entry) => ({
+        cwd: entry.cwd,
+        sessions: entry.sessions,
+        requests: entry.calls,
+        averageContextPerRequest: entry.calls > 0 ? Math.round((entry.cacheRead + entry.input) / entry.calls) : 0,
+        costUsd: Number(entry.cost.toFixed(2)),
+      })),
+    contextShape: {
+      sessionsMeasured: pressure.length,
+      contextWindow: window,
+      compactionTrigger: trigger,
+      surface: describe(pressure.map((row) => row.surfaceTokens)),
+      reachedCompaction: pressure.filter((row) => row.surfaceTokens >= trigger && trigger > 0).length,
+    },
+    recall: {
+      sessionsWithRecallUsage: withRecall.length,
+      sessionsWithout: without.length,
+      comparable: withRecall.length > 0 && without.length > 0,
+      after: withRecall.length > 0 ? describe(withRecall.map((row) => row.contextPerRequest)) : null,
+      before: without.length > 0 ? describe(without.map((row) => row.contextPerRequest)) : null,
+    },
+    sources: { ledger: LEDGER, cache: CACHE },
+  }
+
+  if (AS_JSON) {
+    console.log(JSON.stringify(report, null, 2))
+    return
+  }
+
+  const B = report.baseline
+  console.log('BASELINE — every session on this machine')
+  console.log(`  sessions                      ${n(B.sessions)}`)
+  console.log(`  requests                      ${n(B.requests)}`)
+  console.log(`  cache-read tokens             ${n(B.cacheReadTokens)}`)
+  console.log(`  avg context/request (pooled)  ${n(B.pooledAverageContextPerRequest)}`)
+  console.log(`  avg context/request (typical) ${n(B.meanSessionContextPerRequest)}   mean of per-session averages`)
+  console.log(`  cost                          $${B.costUsd.toFixed(2)}`)
+  console.log('')
+
+  console.log('BY WORKSPACE')
+  for (const entry of report.workspaces.slice(0, 6)) {
+    console.log(
+      `  ${String(entry.requests).padStart(7)} req  ${String(entry.averageContextPerRequest).padStart(8)} ctx/req  ` +
+        `$${entry.costUsd.toFixed(2).padStart(8)}  ${entry.cwd}`,
+    )
+  }
+  if (report.workspaces.length > 6) console.log(`  … and ${report.workspaces.length - 6} more`)
+  console.log('')
+
+  const S = report.contextShape
+  console.log('CONTEXT SHAPE — what sessions reach')
+  console.log(`  sessions with a reading       ${n(S.sessionsMeasured)} of ${n(shape.length)}`)
+  console.log(`  peak surface                  ${n(S.surface.max)}`)
+  console.log(`  median surface                ${n(S.surface.median)}`)
+  console.log(`  compaction trigger            ${n(S.compactionTrigger)}`)
+  console.log(`  sessions that reached it      ${n(S.reachedCompaction)} of ${n(S.sessionsMeasured)}`)
+  console.log('')
+
+  console.log('BEFORE / AFTER — recall usage')
+  const R = report.recall
+  console.log(`  sessions with recall usage    ${n(R.sessionsWithRecallUsage)}`)
+  console.log(`  sessions without              ${n(R.sessionsWithout)}`)
+  console.log('  metric: each session\'s own average context per request (ledger),')
+  console.log('          not peak surface — the two answer different questions')
+  if (!R.comparable) {
+    // The honest output while the plugin has not run. A table here would be a
+    // comparison of nothing against nothing.
+    console.log('')
+    console.log('  Nothing to compare yet: no session has used recall. Run this again')
+    console.log('  after a week of use and the two groups will report side by side.')
+  } else {
+    console.log('')
+    console.log(`  before  ${n(R.before.mean)} ctx/req over ${n(R.before.count)} sessions (median ${n(R.before.median)})`)
+    console.log(`  after   ${n(R.after.mean)} ctx/req over ${n(R.after.count)} sessions (median ${n(R.after.median)})`)
+    const delta = R.before.mean > 0 ? ((R.before.mean - R.after.mean) / R.before.mean) * 100 : 0
+    console.log(`  change  ${delta >= 0 ? '-' : '+'}${Math.abs(delta).toFixed(1)}%`)
+  }
+}
+
+await main()
diff --git a/scripts/measure.mjs b/scripts/measure.mjs
new file mode 100644
index 0000000..7938a1d
--- /dev/null
+++ b/scripts/measure.mjs
@@ -0,0 +1,146 @@
+/**
+ * Real-scale measurement.
+ *
+ * Runs the actual plugin — `apply` plus the registered tool — against a real
+ * workspace and a real embedding endpoint, then reports what the tool costs the
+ * context window versus what reading the files would have cost.
+ *
+ * The comparison is the whole point of the plugin, so it is measured rather than
+ * asserted: the excerpt characters are counted from the tool's own output, and
+ * the "read instead" figure is the character count of the files the results came
+ * from. Token counts are `characters / 4`, which is an approximation and is
+ * labelled as one everywhere it appears.
+ *
+ *   node scripts/measure.mjs [workspace] [query] [budgetMs]
+ */
+
+import { readFile } from 'node:fs/promises'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { apply } from '../index.js'
+
+const WORKSPACE = process.argv[2] ?? '/root/workspaces/ha-runtime'
+const QUERY = process.argv[3] ?? 'how does the occupancy state machine decide a room is occupied'
+const BUDGET_MS = Number(process.argv[4] ?? 90_000)
+
+const API_BASE = process.env.RECALL_API_BASE ?? 'http://10.50.1.2:11434'
+const MODEL = process.env.RECALL_MODEL ?? 'unclemusclez/jina-embeddings-v2-base-code:latest'
+
+const config = {
+  embeddingApiBase: API_BASE,
+  embeddingModel: MODEL,
+  embeddingDimensions: 768,
+  embeddingApiKey: '',
+  embeddingBatchSize: 32,
+  embeddingConcurrency: 4,
+  embeddingTimeoutMs: 120_000,
+  extensions: [],
+  exclude: [],
+  maxFiles: 20_000,
+  maxFileBytes: 1_048_576,
+  chunkLines: 48,
+  maxChunkLines: 80,
+  overlapLines: 8,
+  defaultLimit: 8,
+  maxLimit: 25,
+  perFileLimit: 2,
+  excerptLines: 40,
+  minSimilarity: 0.2,
+  syncBudgetMs: BUDGET_MS,
+  stateDir: '',
+}
+
+/** The smallest context `apply` touches, with no settings provider mounted. */
+function context() {
+  const tools = []
+  const cleanups = []
+  return {
+    tools,
+    ctx: {
+      logger: () => ({ warn() {}, info() {}, error() {} }),
+      effect: (fn) => {
+        const dispose = fn()
+        if (typeof dispose === 'function') cleanups.push(dispose)
+      },
+      get: () => undefined,
+      inject: () => {},
+      tools: { register: (tool) => tools.push(tool) },
+    },
+    dispose: () => cleanups.forEach((fn) => fn()),
+  }
+}
+
+const tokens = (text) => Math.round(text.length / 4)
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), 'recall-measure-'))
+  const { ctx, tools, dispose } = context()
+  apply(ctx, { ...config, stateDir })
+  const tool = tools[0]
+  const exec = { signal: new AbortController().signal, agent: { session: { header: { cwd: WORKSPACE } } } }
+
+  console.log(`workspace : ${WORKSPACE}`)
+  console.log(`endpoint  : ${API_BASE}  model: ${MODEL}`)
+  console.log(`query     : ${QUERY}`)
+  console.log('')
+
+  // --- cold start, bounded -------------------------------------------------
+  const coldStart = Date.now()
+  const first = await tool.execute({ query: QUERY }, exec)
+  const coldMs = Date.now() - coldStart
+  console.log('--- FIRST SEARCH (bounded cold start) ---')
+  console.log(`elapsed        : ${(coldMs / 1000).toFixed(1)}s  (budget ${BUDGET_MS / 1000}s)`)
+  console.log(`scanned files  : ${first.index.scanned}`)
+  console.log(`indexed files  : ${first.index.files}`)
+  console.log(`chunks         : ${first.index.chunks}`)
+  console.log(`embedded now   : ${first.index.embedded}`)
+  console.log(`still pending  : ${first.index.pending}`)
+  console.log(`skipped (big)  : ${first.index.oversized}`)
+  console.log(`results        : ${first.results.length}  best similarity ${first.best}`)
+  console.log('')
+
+  // --- the token comparison ------------------------------------------------
+  const rendered = tool.output.render({ query: QUERY }, first)[0].text
+  let wholeFileChars = 0
+  const seen = new Set()
+  for (const result of first.results) {
+    if (seen.has(result.path)) continue
+    seen.add(result.path)
+    try {
+      wholeFileChars += (await readFile(join(WORKSPACE, result.path), 'utf8')).length
+    } catch {
+      // A result for a file that has since moved does not change the argument.
+    }
+  }
+
+  console.log('--- WHAT THE MODEL RECEIVED ---')
+  console.log(`recall output  : ${rendered.length} chars  ~${tokens(rendered)} tokens`)
+  console.log(`whole files    : ${wholeFileChars} chars  ~${Math.round(wholeFileChars / 4)} tokens across ${seen.size} file(s)`)
+  if (wholeFileChars > 0) {
+    console.log(`ratio          : ${(wholeFileChars / rendered.length).toFixed(1)}x smaller`)
+  }
+  console.log('')
+  for (const [at, result] of first.results.entries()) {
+    console.log(`${at + 1}. ${result.path}:${result.startLine}-${result.endLine}  sim ${result.similarity}  ${result.truncated ? '(truncated)' : ''}`)
+  }
+  console.log('')
+
+  // --- incremental ---------------------------------------------------------
+  const secondStart = Date.now()
+  const second = await tool.execute({ query: 'what happens when the SSE stream reconnects' }, exec)
+  const secondMs = Date.now() - secondStart
+  console.log('--- SECOND SEARCH (warm index, different query) ---')
+  console.log(`elapsed        : ${secondMs}ms`)
+  console.log(`embedded       : ${second.index.embedded} file(s)`)
+  console.log(`pending        : ${second.index.pending}`)
+  console.log(`results        : ${second.results.length}`)
+  console.log('')
+  console.log('(token figures are characters/4 — an approximation, not a measurement)')
+
+  dispose()
+  await rm(stateDir, { recursive: true, force: true })
+}
+
+await main()
diff --git a/scripts/scope-measure.mjs b/scripts/scope-measure.mjs
new file mode 100644
index 0000000..019cefd
--- /dev/null
+++ b/scripts/scope-measure.mjs
@@ -0,0 +1,114 @@
+/**
+ * What focus scoping does to the index, measured without an embedding endpoint.
+ *
+ * The semantic half of the claim — that a focused search ranks better — needs a
+ * live model. This half does not: index size, per-scope chunk counts, and the
+ * cold-start cost they imply are all arithmetic over the chunker, which is
+ * deterministic and offline.
+ *
+ * The cold-start projection uses the throughput actually measured against the
+ * real endpoint on this repository: 2,257 chunks embedded in 90s, about 25
+ * chunks/s. It is a projection from a real figure, not a guess, and it is
+ * labelled as a projection.
+ *
+ *   node scripts/scope-measure.mjs [workspace]
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { chunkFile } from '../lib/chunk.js'
+import { listCodeFiles } from '../lib/walk.js'
+
+const WORKSPACE = process.argv[2] ?? '/root/workspaces/ha-runtime'
+
+/** Chunks per second, measured on this repository against the live endpoint. */
+const MEASURED_CHUNKS_PER_SECOND = 2257 / 90
+
+/** Count files and chunks for one directory, relative to a base for display. */
+async function measure(root, label) {
+  const { files } = await listCodeFiles(root)
+  let chunks = 0
+  let lines = 0
+  let skipped = 0
+  for (const file of files) {
+    let content
+    try {
+      content = await readFile(file.absolute, 'utf8')
+    } catch {
+      continue
+    }
+    lines += content.split('\n').length
+    const split = chunkFile({ path: file.path, content })
+    if (split.chunks.length === 0) skipped += 1
+    chunks += split.chunks.length
+  }
+  return { label, files: files.length, chunks, lines, skipped }
+}
+
+/** Directories under src/controllers that hold code directly. */
+async function controllerRoots(root) {
+  const { files } = await listCodeFiles(root)
+  const seen = new Map()
+  for (const file of files) {
+    if (!file.path.startsWith('src/controllers/')) continue
+    const dir = file.path.slice(0, file.path.lastIndexOf('/'))
+    if (dir === '' || dir.endsWith('__tests__')) continue
+    seen.set(dir, true)
+  }
+  return [...seen.keys()].sort()
+}
+
+function seconds(chunks) {
+  return chunks / MEASURED_CHUNKS_PER_SECOND
+}
+
+function human(sec) {
+  if (sec < 60) return `${sec.toFixed(0)}s`
+  return `${(sec / 60).toFixed(1)}min`
+}
+
+async function main() {
+  console.log(`workspace: ${WORKSPACE}`)
+  console.log(`throughput: ${MEASURED_CHUNKS_PER_SECOND.toFixed(1)} chunks/s (measured on this repo)`)
+  console.log('')
+
+  const whole = await measure(WORKSPACE, 'whole workspace')
+  console.log('=== WHOLE WORKSPACE ===')
+  console.log(`  files ${whole.files}  chunks ${whole.chunks}  lines ${whole.lines.toLocaleString()}`)
+  console.log(`  cold index (projected): ${human(seconds(whole.chunks))}`)
+  console.log('')
+
+  const roots = await controllerRoots(WORKSPACE)
+  const scopes = []
+  for (const dir of roots) {
+    scopes.push(await measure(join(WORKSPACE, dir), dir))
+  }
+  scopes.sort((left, right) => right.chunks - left.chunks)
+
+  console.log(`=== ${scopes.length} CONTROLLER SCOPES ===`)
+  console.log(`  ${'scope'.padEnd(52)} ${'files'.padStart(5)} ${'chunks'.padStart(7)} ${'share'.padStart(7)} ${'cold'.padStart(7)}`)
+  for (const scope of scopes.slice(0, 10)) {
+    const share = ((scope.chunks / whole.chunks) * 100).toFixed(1)
+    console.log(
+      `  ${scope.label.replace('src/controllers/', '').padEnd(52)} ${String(scope.files).padStart(5)} ` +
+        `${String(scope.chunks).padStart(7)} ${`${share}%`.padStart(7)} ${human(seconds(scope.chunks)).padStart(7)}`,
+    )
+  }
+  if (scopes.length > 10) console.log(`  … and ${scopes.length - 10} more`)
+  console.log('')
+
+  const median = scopes[Math.floor(scopes.length / 2)]
+  const totalScoped = scopes.reduce((sum, scope) => sum + scope.chunks, 0)
+  console.log('=== WHAT SCOPING BUYS ===')
+  console.log(`  median scope          : ${median.chunks} chunks (${((median.chunks / whole.chunks) * 100).toFixed(1)}% of the workspace)`)
+  console.log(`  largest scope         : ${scopes[0].chunks} chunks (${((scopes[0].chunks / whole.chunks) * 100).toFixed(1)}%)`)
+  console.log(`  candidate pool        : ${whole.chunks} -> ${median.chunks} chunks, a ${(whole.chunks / median.chunks).toFixed(1)}x smaller haystack`)
+  console.log(`  cold start (projected): ${human(seconds(whole.chunks))} -> ${human(seconds(median.chunks))}`)
+  console.log(`  all scopes together   : ${totalScoped} chunks, ${((totalScoped / whole.chunks) * 100).toFixed(1)}% of the workspace`)
+  console.log('')
+  console.log('(the candidate-pool figure is the precision argument; whether ranking actually')
+  console.log(' improves needs the live endpoint, which is currently unable to load the model)')
+}
+
+await main()
diff --git a/scripts/smoke.mjs b/scripts/smoke.mjs
new file mode 100644
index 0000000..608f67a
--- /dev/null
+++ b/scripts/smoke.mjs
@@ -0,0 +1,148 @@
+/**
+ * Live smoke test: the real pipeline against the real embedding endpoint.
+ *
+ * Not part of `npm test`, because it needs a running Ollama and a model that is
+ * already pulled. It exists because the unit tests can only prove the code does
+ * what the test author believed; this proves the retrieval actually returns the
+ * right file for a question about it, which is the only claim that matters.
+ *
+ *   node scripts/smoke.mjs [workspace] [query]
+ */
+
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { chunkFile, embedText } from '../lib/chunk.js'
+import { createEmbedder } from '../lib/embed.js'
+import { rankChunks } from '../lib/rank.js'
+import { RecallIndex } from '../lib/store.js'
+import { listCodeFiles } from '../lib/walk.js'
+
+const API_BASE = process.env.RECALL_API_BASE ?? 'http://10.50.1.2:11434'
+const MODEL = process.env.RECALL_MODEL ?? 'unclemusclez/jina-embeddings-v2-base-code:latest'
+const DIMENSIONS = Number(process.env.RECALL_DIMENSIONS ?? 768)
+
+const FIXTURE = {
+  'src/services/auth/session.ts': `import { createHash, randomBytes } from 'node:crypto'
+
+const SESSION_TTL_MS = 1000 * 60 * 60 * 12
+
+export interface SessionRecord {
+  userId: string
+  issuedAt: number
+  expiresAt: number
+}
+
+export function issueSession(userId: string): SessionRecord {
+  const now = Date.now()
+  return { userId, issuedAt: now, expiresAt: now + SESSION_TTL_MS }
+}
+
+export function isExpired(record: SessionRecord, now = Date.now()): boolean {
+  return record.expiresAt <= now
+}
+
+export function rotateToken(record: SessionRecord): string {
+  if (isExpired(record)) throw new Error('cannot rotate an expired session')
+  return randomBytes(32).toString('hex')
+}
+
+export function fingerprint(token: string): string {
+  return createHash('sha256').update(token).digest('hex').slice(0, 16)
+}
+`,
+  'src/services/weather/forecast.ts': `export interface ForecastDay {
+  date: string
+  minC: number
+  maxC: number
+  rainMm: number
+}
+
+export function averageTemperature(days: ForecastDay[]): number {
+  if (days.length === 0) return 0
+  const total = days.reduce((sum, day) => sum + (day.minC + day.maxC) / 2, 0)
+  return total / days.length
+}
+
+export function totalRainfall(days: ForecastDay[]): number {
+  return days.reduce((sum, day) => sum + day.rainMm, 0)
+}
+`,
+  'src/store/sqlite.ts': `import { DatabaseSync } from 'node:sqlite'
+
+export function openDatabase(path: string): DatabaseSync {
+  const db = new DatabaseSync(path)
+  db.exec('PRAGMA journal_mode = WAL')
+  return db
+}
+
+export function pruneRows(db: DatabaseSync, table: string, olderThan: number): number {
+  const statement = db.prepare(\`DELETE FROM \${table} WHERE created_at < ?\`)
+  const result = statement.run(olderThan)
+  return Number(result.changes)
+}
+`,
+}
+
+/** Write the fixture into a fresh temporary directory. */
+async function makeWorkspace() {
+  const root = await mkdtemp(join(tmpdir(), 'recall-smoke-'))
+  for (const [path, content] of Object.entries(FIXTURE)) {
+    const absolute = join(root, path)
+    await mkdir(join(absolute, '..'), { recursive: true })
+    await writeFile(absolute, content, 'utf8')
+  }
+  return root
+}
+
+async function main() {
+  const query = process.argv[3] ?? 'how long does a user session stay valid before it expires'
+  const root = process.argv[2] ?? (await makeWorkspace())
+  const indexDir = await mkdtemp(join(tmpdir(), 'recall-index-'))
+  const database = join(indexDir, 'index.sqlite')
+
+  const embedder = createEmbedder({ apiBase: API_BASE, model: MODEL, dimensions: DIMENSIONS })
+  const index = new RecallIndex(database)
+  index.open({ model: MODEL, dimensions: DIMENSIONS, apiBase: API_BASE })
+
+  const started = Date.now()
+  const walk = await listCodeFiles(root)
+  let chunks = 0
+  for (const file of walk.files) {
+    const { readFile } = await import('node:fs/promises')
+    const content = await readFile(file.absolute, 'utf8')
+    const split = chunkFile({ path: file.path, content })
+    if (split.chunks.length === 0) continue
+    const vectors = await embedder.embed(split.chunks.map((chunk) => embedText(file.path, chunk)))
+    index.replaceFile(file.path, 'smoke', Buffer.byteLength(content), split.chunks.map((c, at) => ({ ...c, vec: vectors[at] })))
+    chunks += split.chunks.length
+  }
+  const indexMs = Date.now() - started
+
+  const matrix = index.matrix()
+  const queryVector = await embedder.embedOne(query)
+  const searchStart = Date.now()
+  const ranked = rankChunks({ matrix, queryVector, query, limit: 5 })
+  const searchMs = Date.now() - searchStart
+
+  console.log(`workspace : ${root}`)
+  console.log(`files     : ${walk.files.length}  chunks: ${chunks}  indexed in ${indexMs}ms`)
+  console.log(`query     : ${query}`)
+  console.log(`search    : ${searchMs}ms  batch endpoint: ${embedder.batchEnabled}`)
+  console.log('')
+  for (const [at, result] of ranked.results.entries()) {
+    console.log(`${at + 1}. ${result.path}:${result.startLine}-${result.endLine}  similarity ${result.similarity}`)
+    console.log(`   ${result.excerpt.split('\n')[0]}`)
+  }
+  console.log('')
+  const top = ranked.results[0]
+  const expected = 'src/services/auth/session.ts'
+  console.log(top?.path === expected ? `PASS top hit is ${expected}` : `FAIL top hit was ${top?.path}, expected ${expected}`)
+
+  index.close()
+  await rm(indexDir, { recursive: true, force: true })
+  if (process.argv[2] === undefined) await rm(root, { recursive: true, force: true })
+}
+
+await main()
diff --git a/test/chunk.test.js b/test/chunk.test.js
new file mode 100644
index 0000000..5089c13
--- /dev/null
+++ b/test/chunk.test.js
@@ -0,0 +1,150 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import {
+  chunkFile,
+  embedText,
+  isLikelyMinified,
+  languageOf,
+  symbolLabel,
+  symbolOf,
+} from '../lib/chunk.js'
+
+const TS = `import { readFile } from 'node:fs/promises'
+
+const CACHE = new Map()
+
+export function loadConfig(path) {
+  if (CACHE.has(path)) return CACHE.get(path)
+  const value = { path, loaded: true }
+  CACHE.set(path, value)
+  return value
+}
+
+export function clearCache() {
+  CACHE.clear()
+}
+
+export class Store {
+  constructor() {
+    this.rows = []
+  }
+
+  add(row) {
+    this.rows.push(row)
+  }
+}
+`
+
+/** A module long enough that its declarations cannot all merge into one chunk. */
+function bigModule(count = 6, bodyLines = 14) {
+  const parts = []
+  for (let at = 0; at < count; at += 1) {
+    const body = Array.from({ length: bodyLines }, (_, line) => `  const step_${at}_${line} = compute(${line})`).join('\n')
+    parts.push(`export function handler_${at}(input) {\n${body}\n  return input\n}`)
+  }
+  return `${parts.join('\n\n')}\n`
+}
+
+test('languageOf maps known extensions and ignores unknown ones', () => {
+  assert.equal(languageOf('a/b.ts'), 'javascript')
+  assert.equal(languageOf('a/b.PY'), 'python')
+  assert.equal(languageOf('a/b.rs'), 'rust')
+  assert.equal(languageOf('a/b.unknownext'), undefined)
+  assert.equal(languageOf('Makefile'), undefined)
+})
+
+test('symbolOf reads a declaration name', () => {
+  assert.equal(symbolOf('export function loadConfig(path) {'), 'loadConfig')
+  assert.equal(symbolOf('export class Store {'), 'Store')
+  assert.equal(symbolOf('def compute_total(items):'), 'compute_total')
+  assert.equal(symbolOf('// just a comment'), undefined)
+})
+
+test('symbolLabel lists merged declarations and caps a long list', () => {
+  assert.equal(symbolLabel([]), undefined)
+  assert.equal(symbolLabel(['a']), 'a')
+  assert.equal(symbolLabel(['a', 'b']), 'a, b')
+  assert.equal(symbolLabel(['a', 'a', 'b']), 'a, b')
+  assert.equal(symbolLabel(['a', 'b', 'c', 'd', 'e', 'f']), 'a, b, c, d +2')
+})
+
+test('a small file merges into one chunk labelled with every declaration it holds', () => {
+  const { chunks } = chunkFile({ path: 'src/config.ts', content: TS })
+  assert.equal(chunks.length, 1, 'a 25-line file belongs in a single chunk')
+  // The label must describe the whole chunk, not just its first declaration:
+  // for a small file this label is the module's only description in the index.
+  assert.equal(chunks[0].symbol, 'CACHE, loadConfig, clearCache, Store')
+  assert.equal(chunks[0].startLine, 1)
+})
+
+test('a larger file splits at declarations, and each chunk is a real source slice', () => {
+  const content = bigModule()
+  const { chunks } = chunkFile({ path: 'src/handlers.ts', content })
+  assert.ok(chunks.length >= 3, `expected several chunks, got ${chunks.length}`)
+  const lines = content.split('\n')
+  for (const chunk of chunks) {
+    assert.equal(chunk.text, lines.slice(chunk.startLine - 1, chunk.endLine).join('\n'))
+  }
+  assert.equal(chunks[0].startLine, 1)
+  assert.match(chunks[0].symbol, /handler_0/)
+})
+
+test('chunkFile merges adjacent small declarations instead of emitting fragments', () => {
+  const source = ['export function a() { return 1 }', '', 'export function b() { return 2 }', '', 'export function c() { return 3 }', ''].join('\n')
+  const { chunks } = chunkFile({ path: 'x.ts', content: source, chunkLines: 48 })
+  assert.equal(chunks.length, 1, 'three one-line functions should merge into one chunk')
+  assert.equal(chunks[0].symbol, 'a, b, c')
+})
+
+test('chunkFile splits an oversized declaration with overlap', () => {
+  const body = Array.from({ length: 300 }, (_, at) => `  const value_${at} = compute(${at})`).join('\n')
+  const source = `export function huge() {\n${body}\n}\n`
+  const { chunks } = chunkFile({ path: 'x.ts', content: source, maxChunkLines: 80, overlapLines: 8 })
+  assert.ok(chunks.length > 1, 'a 300-line function must be split')
+  for (const chunk of chunks) {
+    assert.ok(chunk.endLine - chunk.startLine + 1 <= 80, `chunk was ${chunk.endLine - chunk.startLine + 1} lines`)
+  }
+  // Overlap means consecutive chunks share lines, so no boundary is lost.
+  for (let at = 1; at < chunks.length; at += 1) {
+    assert.ok(chunks[at].startLine <= chunks[at - 1].endLine, 'consecutive chunks should overlap')
+  }
+  // Only the piece holding the signature is labelled with the declaration.
+  assert.equal(chunks[0].symbol, 'huge')
+  assert.equal(chunks[1].symbol, undefined)
+})
+
+test('chunkFile falls back to windows when the language has no anchor set', () => {
+  const source = Array.from({ length: 200 }, (_, at) => `line ${at} of an unknown dialect`).join('\n')
+  const { chunks } = chunkFile({ path: 'thing.weird', content: source, maxChunkLines: 80, overlapLines: 8 })
+  assert.ok(chunks.length > 1)
+  assert.equal(chunks[0].startLine, 1)
+  assert.equal(chunks[0].symbol, undefined)
+})
+
+test('chunkFile refuses generated files rather than indexing noise', () => {
+  const minified = `var a=${'x'.repeat(50_000)};`
+  assert.equal(isLikelyMinified(minified), true)
+  const result = chunkFile({ path: 'bundle.js', content: minified })
+  assert.deepEqual(result.chunks, [])
+  assert.equal(result.skipped, 'generated-or-minified')
+})
+
+test('chunkFile reports an empty file as empty', () => {
+  const result = chunkFile({ path: 'a.ts', content: '   \n\n' })
+  assert.deepEqual(result.chunks, [])
+  assert.equal(result.skipped, 'empty')
+})
+
+test('chunkFile caps chunks per file', () => {
+  const source = Array.from({ length: 400 }, (_, at) => `export function fn_${at}() { return ${at} }`).join('\n')
+  const { chunks, skipped } = chunkFile({ path: 'many.ts', content: source, chunkLines: 2, maxChunkLines: 2, maxChunks: 10 })
+  assert.equal(chunks.length, 10)
+  assert.equal(skipped, 'chunk-cap-reached')
+})
+
+test('embedText carries the path, so a question about a name can find it', () => {
+  const text = embedText('src/auth/session.ts', { symbol: 'issueSession', text: 'export function issueSession() {}' })
+  assert.match(text, /src\/auth\/session\.ts :: issueSession/)
+  assert.match(text, /export function issueSession/)
+})
diff --git a/test/client.test.js b/test/client.test.js
new file mode 100644
index 0000000..937d7a7
--- /dev/null
+++ b/test/client.test.js
@@ -0,0 +1,410 @@
+/**
+ * The browser half, without a browser.
+ *
+ * `client/client.js` is a plain script that hands a factory to the platform's
+ * module loader, so it can be exercised in Node by stubbing `window` and
+ * `require('react')`. That is worth doing rather than leaving the card to be
+ * eyeballed in a running app, because the two things most likely to be wrong are
+ * both structural and both invisible until someone opens Settings:
+ *
+ *   - the root element must be an `<li>`, because the tab renders every card
+ *     into a `<ul>` and a `<div>` never receives the list styling;
+ *   - the card must start collapsed and disclose on click, because that is the
+ *     framework's card contract and the thing that was wrong the first time.
+ */
+
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+/** A React good enough to run one component: element, state, effect, memo. */
+function makeReact() {
+  const hooks = []
+  let cursor = 0
+  return {
+    createElement(type, props, ...children) {
+      const merged = { ...(props ?? {}) }
+      if (children.length > 0) merged.children = children.length === 1 ? children[0] : children
+      return { type, props: merged }
+    },
+    useState(initial) {
+      const at = cursor
+      cursor += 1
+      if (!(at in hooks)) hooks[at] = typeof initial === 'function' ? initial() : initial
+      return [
+        hooks[at],
+        (next) => {
+          hooks[at] = typeof next === 'function' ? next(hooks[at]) : next
+        },
+      ]
+    },
+    useEffect(fn) {
+      fn()
+    },
+    useMemo(fn) {
+      return fn()
+    },
+    /** Prepare for one more render, keeping hook state. */
+    __render() {
+      cursor = 0
+    },
+  }
+}
+
+/**
+ * Expand a function element the way React would.
+ *
+ * The card renders each control as `h(Field, …)`, and those elements are only
+ * real DOM once React calls them — so a walk that stops at `type === 'input'`
+ * finds nothing without this.
+ */
+function expand(node) {
+  if (node === null || typeof node !== 'object') return node
+  return typeof node.type === 'function' ? expand(node.type(node.props)) : node
+}
+
+/** Depth-first search over a rendered tree, expanding function components. */
+function find(node, predicate, found = []) {
+  const current = expand(node)
+  if (current === null || typeof current !== 'object') return found
+  if (predicate(current)) found.push(current)
+  const children = current.props?.children
+  if (Array.isArray(children)) children.forEach((child) => find(child, predicate, found))
+  else find(children, predicate, found)
+  return found
+}
+
+/** The input carrying a given accessible label. */
+function inputFor(tree, label) {
+  return find(tree, (node) => node.type === 'input' && node.props['aria-label'] === label)[0]
+}
+
+/** The save button, whatever its current label. */
+function saveButton(tree) {
+  return find(tree, (node) => node.type === 'button' && String(node.props.children).startsWith('Save'))[0]
+}
+
+/** A settings scope that records writes instead of performing them. */
+function makeScope(options = {}) {
+  const { value = {}, user = null, status = 'ready', writable = true } = options
+  const calls = []
+  const snapshot = { status, value, user, writable }
+  return {
+    calls,
+    getSnapshot: () => snapshot,
+    subscribe: () => () => {},
+    set: async (key, next) => {
+      calls.push({ op: 'set', key, value: next })
+    },
+    unset: async (key) => {
+      calls.push({ op: 'unset', key })
+    },
+  }
+}
+
+// Load the browser bundle once, the way the platform loader would.
+const loaded = []
+globalThis.window = { __ModuleLoader__: { load: (entry) => loaded.push(entry) } }
+await import('../client/client.js')
+
+const entry = loaded[0]
+
+/** Instantiate the module with a stubbed `react`. */
+function makeModule() {
+  const react = makeReact()
+  const factory = entry.factory((name) => {
+    if (name === 'react') return react
+    throw new Error(`unexpected import: ${name}`)
+  })
+  return { react, module: factory }
+}
+
+/** Register every slot the browser half contributes, and render any of them. */
+function mount(scope) {
+  const { react, module } = makeModule()
+  const registered = []
+  const slots = {
+    inject: (name, fn) => fn(),
+    register: (meta, component) => {
+      registered.push({ meta, component })
+      return () => {}
+    },
+  }
+  const ctx = {
+    slots,
+    inject: (deps, cb) =>
+      cb({
+        settingsScope: {
+          bind: (options) => {
+            assert.equal(options.namespace, 'dsh-recall')
+            return scope
+          },
+        },
+        slots,
+      }),
+  }
+  module.apply(ctx)
+
+  const byName = new Map(registered.map((entry) => [entry.meta.name, entry]))
+
+  /** Render one registered slot with the props its occupant would receive. */
+  const renderSlot = (name, props = {}) => {
+    const entry = byName.get(name)
+    assert.ok(entry !== undefined, `nothing registered for ${name}`)
+    react.__render()
+    const element = entry.component(props)
+    if (element === null) return null
+    return element.type(element.props)
+  }
+
+  /** Render the settings card, at its current state. */
+  const render = () => {
+    react.__render()
+    const element = byName.get('settings.plugin.item').component({ scope })
+    return element.type(element.props)
+  }
+
+  return { react, module, meta: byName.get('settings.plugin.item').meta, registered, render, renderSlot }
+}
+
+/** Open the card, and hand back a function returning the CURRENT body. */
+function openCard(render) {
+  render().props.children[0].props.onClick()
+  // Call this after any edit: React re-renders then, and the Save button the
+  // user actually clicks is the one created by that later render.
+  return () => render().props.children[1]
+}
+
+test('the bundle registers under the loader with the plugin id', () => {
+  assert.equal(loaded.length, 1)
+  assert.equal(entry.id, 'dsh-recall')
+  assert.equal(typeof entry.factory, 'function')
+})
+
+test('the client module claims slots and reports the host namespace', () => {
+  const { module } = makeModule()
+  assert.equal(module.name, 'dsh-recall')
+  assert.deepEqual(module.inject, ['slots'])
+})
+
+test('the card is registered under the same key the host half serves', () => {
+  const { meta } = mount(makeScope())
+  assert.equal(meta.name, 'settings.plugin.item')
+  assert.equal(meta.key, 'dsh-recall', 'the host namespace and the card key must match, or nothing renders')
+  assert.equal(typeof meta.inject, 'function')
+})
+
+test('the root is an <li>, because the tab renders cards into a <ul>', () => {
+  const { render } = mount(makeScope())
+  assert.equal(render().type, 'li')
+})
+
+test('the card starts collapsed and discloses on click', () => {
+  const { render } = mount(makeScope())
+  const closed = render()
+  const [closedHeader, closedBody] = closed.props.children
+  assert.equal(closedHeader.type, 'button')
+  assert.equal(closedHeader.props['aria-expanded'], false, 'the card must start collapsed')
+  assert.equal(closedBody, null, 'a collapsed card renders no body')
+
+  // Click the header, then render again — hook state persists across renders.
+  closedHeader.props.onClick()
+  const [openHeader, openBodyNode] = render().props.children
+  assert.equal(openHeader.props['aria-expanded'], true)
+  assert.notEqual(openBodyNode, null, 'an expanded card renders its controls')
+  assert.equal(openBodyNode.type, 'div')
+})
+
+test('every host setting appears as a control', () => {
+  const { render } = mount(makeScope())
+  const body = openCard(render)
+  const labels = find(body(), (node) => node.type === 'input').map((node) => node.props['aria-label'])
+  for (const label of [
+    'Embedding endpoint',
+    'Embedding model',
+    'Embedding dimensions',
+    'Embedding API key',
+    'Lines per excerpt',
+    'Index warm-up budget per search (ms)',
+  ]) {
+    assert.ok(labels.includes(label), `expected a control labelled ${label}, saw ${labels.join(' | ')}`)
+  }
+})
+
+test('an unavailable namespace renders nothing at all', () => {
+  const { render } = mount(makeScope({ status: 'unavailable' }))
+  assert.equal(render(), null)
+})
+
+test('a read-only namespace says so rather than offering a dead form', () => {
+  const { render } = mount(makeScope({ writable: false }))
+  const body = openCard(render)
+  assert.ok(find(body(), (node) => node.props?.role === 'status').length > 0)
+})
+
+test('a save writes only the fields the user changed', async () => {
+  const scope = makeScope({ value: { embeddingApiBase: 'http://a:11434', excerptLines: 40 } })
+  const { render } = mount(scope)
+  const body = openCard(render)
+
+  inputFor(body(), 'Lines per excerpt').props.onChange({ target: { value: '25' } })
+  const button = saveButton(body())
+  assert.match(String(button.props.children), /Save 1 change/)
+
+  await button.props.onClick()
+  assert.deepEqual(scope.calls, [{ op: 'set', key: 'excerptLines', value: 25 }])
+})
+
+test('clearing a non-secret field unsets it rather than writing an empty value', async () => {
+  const scope = makeScope({ value: { embeddingApiBase: 'http://a:11434' } })
+  const { render } = mount(scope)
+  const body = openCard(render)
+
+  inputFor(body(), 'Embedding endpoint').props.onChange({ target: { value: '' } })
+  await saveButton(body()).props.onClick()
+
+  assert.deepEqual(scope.calls, [{ op: 'unset', key: 'embeddingApiBase' }])
+})
+
+test('a list field round-trips as a comma separated string', async () => {
+  const scope = makeScope({ value: { exclude: ['dist/', 'vendor/'] } })
+  const { render } = mount(scope)
+  const body = openCard(render)
+
+  const input = inputFor(body(), 'Extra exclude patterns')
+  assert.equal(input.props.value, 'dist/, vendor/')
+  input.props.onChange({ target: { value: 'dist/, vendor/, tmp/' } })
+  await saveButton(body()).props.onClick()
+
+  assert.deepEqual(scope.calls, [{ op: 'set', key: 'exclude', value: ['dist/', 'vendor/', 'tmp/'] }])
+})
+
+test('the API key is never sent back to the page, and blank does not clear it', async () => {
+  // The host marks this field role('secret'), so it arrives absent. A save with
+  // the field untouched must not write anything for it — otherwise opening the
+  // card and pressing Save would delete the key.
+  const scope = makeScope({ value: { embeddingApiBase: 'http://a:11434' }, user: { embeddingApiKey: 'stored' } })
+  const { render } = mount(scope)
+  const body = openCard(render)
+
+  const keyInput = inputFor(body(), 'Embedding API key')
+  assert.ok(keyInput !== undefined)
+  assert.equal(keyInput.props.type, 'password')
+  assert.equal(keyInput.props.value, '', 'a redacted secret must render blank')
+  assert.equal(keyInput.props.placeholder, '(unchanged)')
+
+  // Nothing is dirty, so there is nothing to save and the button is inert.
+  const button = saveButton(body())
+  assert.equal(button.props.disabled, true)
+  await button.props.onClick()
+  assert.deepEqual(scope.calls, [], 'an untouched secret must never be written or unset')
+})
+
+test('an unsaved edit is marked on the header while collapsed', () => {
+  const { render } = mount(makeScope({ value: { excerptLines: 40 } }))
+  const body = openCard(render)
+  inputFor(body(), 'Lines per excerpt').props.onChange({ target: { value: '25' } })
+
+  // Collapse again and look at the header.
+  render().props.children[0].props.onClick()
+  const collapsed = render()
+  const marked = find(collapsed.props.children[0], (node) => node.props?.children === 'unsaved')
+  assert.equal(marked.length, 1, 'unsaved edits must be visible while the card is folded away')
+})
+
+test('the browser half contributes four slots, one of them the header corner', () => {
+  const { registered } = mount(makeScope())
+  const names = registered.map((entry) => entry.meta.name).sort()
+  assert.deepEqual(names, [
+    'conversation.session.header.corner',
+    'settings.plugin.item',
+    'sidebar.right.pane.tab',
+    'sidebar.right.pane.tab.title',
+  ])
+})
+
+/** A projection value shaped like the host unit's wire view. */
+function usageView(overrides = {}) {
+  return {
+    searches: 3,
+    indexes: 0,
+    failed: 0,
+    excerpts: 9,
+    files: 5,
+    weak: 0,
+    returnedBytes: 12_000,
+    sourceBytes: 480_000,
+    avoidedBytes: 468_000,
+    avoidedTokens: 117_000,
+    compression: 40,
+    rereadTokens: 0,
+    avoidedUsd: 0.0008,
+    lastFocus: '.',
+    ...overrides,
+  }
+}
+
+test('the header chip renders nothing when the conversation never used it', () => {
+  const { renderSlot } = mount(makeScope())
+  // The corner is laid out only while its occupant renders something, so this
+  // is the state that must cost no space at all.
+  assert.equal(renderSlot('conversation.session.header.corner', { useProjection: () => undefined }), null)
+  assert.equal(renderSlot('conversation.session.header.corner', { useProjection: () => usageView({ searches: 0, excerpts: 0 }) }), null)
+  // And a host without the projection service at all.
+  assert.equal(renderSlot('conversation.session.header.corner', {}), null)
+})
+
+test('the header chip leads with what was kept out, not what it cost', () => {
+  const { renderSlot } = mount(makeScope())
+  const chip = renderSlot('conversation.session.header.corner', { useProjection: () => usageView() })
+  assert.ok(chip !== null)
+  const text = String(chip.props.children)
+  assert.match(text, /Recall 3/)
+  assert.match(text, /40/)
+  assert.match(text, /kept out/)
+  // Money is deliberately absent from the chip: a fraction of a penny reads as
+  // the tool being useless rather than as the arithmetic being honest.
+  assert.ok(!text.includes('$'), `chip showed a price: ${text}`)
+})
+
+test('the chip tooltip carries the figures the chip has no room for', () => {
+  const { renderSlot } = mount(makeScope())
+  const chip = renderSlot('conversation.session.header.corner', { useProjection: () => usageView({ rereadTokens: 500_000 }) })
+  const detail = chip.props.title
+  assert.match(detail, /3 searches/)
+  assert.match(detail, /9 excerpts from 5 files/)
+  assert.match(detail, /would have been read/)
+  assert.match(detail, /estimate/i, 'the comparison must be labelled as one')
+})
+
+test('the sidebar panel explains an unused conversation instead of showing zeroes', () => {
+  const { renderSlot } = mount(makeScope())
+  const empty = renderSlot('sidebar.right.pane.tab', { useProjection: () => usageView({ searches: 0, indexes: 0, excerpts: 0 }) })
+  const text = JSON.stringify(empty)
+  assert.match(text, /has not used recall yet/)
+  assert.ok(!/\b0 B\b/.test(text), 'zeroes would read as "this did nothing"')
+})
+
+test('the sidebar panel says so when the projection is absent', () => {
+  const { renderSlot } = mount(makeScope())
+  const missing = renderSlot('sidebar.right.pane.tab', {})
+  assert.match(JSON.stringify(missing), /not available for this conversation/)
+})
+
+test('the sidebar panel reports the comparison and the compounding', () => {
+  const { renderSlot } = mount(makeScope())
+  const panel = renderSlot('sidebar.right.pane.tab', { useProjection: () => usageView({ rereadTokens: 1_200_000 }) })
+  const text = JSON.stringify(panel)
+  assert.match(text, /Kept out of this conversation/)
+  assert.match(text, /Smaller than reading the files/)
+  assert.match(text, /Re-read since/)
+  assert.match(text, /1,200,000 tokens/)
+  assert.match(text, /upper bound/, 'the panel must say what the figure is not')
+})
+
+test('the tab title is registered under the same key as the panel', () => {
+  const { registered } = mount(makeScope())
+  const panel = registered.find((entry) => entry.meta.name === 'sidebar.right.pane.tab')
+  const title = registered.find((entry) => entry.meta.name === 'sidebar.right.pane.tab.title')
+  assert.equal(panel.meta.key, 'dsh-recall')
+  assert.equal(title.meta.key, panel.meta.key, 'the title must bind to the panel it names')
+})
diff --git a/test/config.test.js b/test/config.test.js
new file mode 100644
index 0000000..8a22264
--- /dev/null
+++ b/test/config.test.js
@@ -0,0 +1,97 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { Config, SETTING_KEYS, validateSettings } from '../index.js'
+
+/**
+ * The load-time contract.
+ *
+ * `apply` never runs when Cordis rejects a plugin's `Config`, so these are the
+ * only failures a plugin cannot report from inside itself — the profile simply
+ * refuses to boot. The rest of the suite calls `apply` directly and would never
+ * notice, which is exactly why this file exists separately.
+ */
+
+test('Config is a Standard Schema, which is what Cordis requires', () => {
+  assert.ok(Config !== undefined, 'Config must be exported')
+  assert.ok(Config['~standard'] !== undefined, 'Config must implement the Standard Schema interface')
+})
+
+test('Config fills every field from an empty input, so apply can rely on defaults', () => {
+  const filled = Config({})
+  for (const key of SETTING_KEYS) {
+    assert.ok(key in filled, `${key} has no default and would be undefined in apply`)
+  }
+  assert.equal(filled.embeddingApiBase, 'http://127.0.0.1:11434')
+  assert.equal(filled.embeddingDimensions, 768)
+  assert.equal(filled.syncBudgetMs, 20_000)
+  assert.deepEqual(filled.exclude, [])
+  assert.deepEqual(filled.extensions, [])
+})
+
+test('Config keeps an explicit value and fills the rest', () => {
+  const filled = Config({ embeddingApiBase: 'http://10.50.1.2:11434', embeddingConcurrency: 8 })
+  assert.equal(filled.embeddingApiBase, 'http://10.50.1.2:11434')
+  assert.equal(filled.embeddingConcurrency, 8)
+  assert.equal(filled.embeddingBatchSize, 16)
+  assert.equal(filled.embeddingTimeoutMs, 30_000)
+  assert.equal(filled.embeddingKeepAlive, '5m')
+  // The per-excerpt cap equals the chunk cap, so chunks arrive whole.
+  assert.equal(filled.excerptLines, 80)
+  assert.equal(filled.totalExcerptLines, 400)
+  assert.equal(filled.maxChunkLines, 80)
+})
+
+test('a wrongly typed value fails loudly at load rather than silently in apply', () => {
+  assert.throws(() => Config({ embeddingDimensions: 'seven hundred' }))
+  assert.throws(() => Config({ exclude: 'src/generated/' }))
+  assert.throws(() => Config({ embeddingApiBase: { host: 'localhost' } }))
+})
+
+test('every declared setting is a real schema key, so none is dead config', () => {
+  const filled = Config({})
+  for (const key of SETTING_KEYS) {
+    assert.ok(Object.hasOwn(filled, key), `${key} is listed in SETTING_KEYS but is not in the schema`)
+  }
+  // And the reverse: no schema field is missing from the documented list, or
+  // `configure` would reject a setting the schema happily accepts.
+  for (const key of Object.keys(filled)) {
+    assert.ok(SETTING_KEYS.includes(key), `${key} is in the schema but not in SETTING_KEYS`)
+  }
+})
+
+/** The defaults plus an override, as the settings provider would resolve them. */
+function settingsWith(patch) {
+  return { ...Config({}), ...patch }
+}
+
+test('validateSettings accepts the defaults', () => {
+  assert.doesNotThrow(() => validateSettings(Config({})))
+})
+
+test('validateSettings rejects an endpoint that is not a URL', () => {
+  // A bare host:port parses successfully — `localhost:` is read as the scheme —
+  // so it is the protocol check that actually catches the common mistake.
+  assert.throws(() => validateSettings(settingsWith({ embeddingApiBase: 'localhost:11434' })), /must be http or https/)
+  assert.throws(() => validateSettings(settingsWith({ embeddingApiBase: '' })), /not a URL/)
+  assert.doesNotThrow(() => validateSettings(settingsWith({ embeddingApiBase: 'http://10.50.1.2:11434' })))
+})
+
+test('validateSettings rejects a non-http protocol', () => {
+  assert.throws(() => validateSettings(settingsWith({ embeddingApiBase: 'file:///tmp/socket' })), /must be http or https/)
+})
+
+test('validateSettings rejects values that would break the pipeline', () => {
+  assert.throws(() => validateSettings(settingsWith({ embeddingDimensions: 0 })), /positive number/)
+  assert.throws(() => validateSettings(settingsWith({ embeddingConcurrency: 0 })), /at least 1/)
+  assert.throws(() => validateSettings(settingsWith({ excerptLines: 0 })), /at least 1/)
+  assert.throws(() => validateSettings(settingsWith({ syncBudgetMs: -1 })), /cannot be negative/)
+})
+
+test('validateSettings rejects cross-field contradictions the schema cannot see', () => {
+  assert.throws(() => validateSettings(settingsWith({ defaultLimit: 50, maxLimit: 10 })), /cannot exceed maxLimit/)
+  assert.throws(() => validateSettings(settingsWith({ chunkLines: 100, maxChunkLines: 80 })), /below chunkLines/)
+  // An overlap at or above the cap means a split never advances.
+  assert.throws(() => validateSettings(settingsWith({ chunkLines: 10, maxChunkLines: 10, overlapLines: 10 })), /never advances/)
+  assert.throws(() => validateSettings(settingsWith({ minSimilarity: 1.5 })), /between 0 and 1/)
+})
diff --git a/test/embed.test.js b/test/embed.test.js
new file mode 100644
index 0000000..6a1644d
--- /dev/null
+++ b/test/embed.test.js
@@ -0,0 +1,173 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { EmbeddingError, clampInput, createEmbedder, dot, normalize } from '../lib/embed.js'
+import { makeStubFetch } from './helpers.js'
+
+function embedder(fetchImpl, overrides = {}) {
+  return createEmbedder({
+    apiBase: 'http://stub',
+    model: 'test-model',
+    dimensions: 768,
+    fetchImpl,
+    concurrency: 2,
+    ...overrides,
+  })
+}
+
+test('normalize produces a unit vector and leaves zero alone', () => {
+  const unit = normalize(Float32Array.from([3, 4]))
+  assert.equal(Math.round(Math.hypot(unit[0], unit[1]) * 1000) / 1000, 1)
+  assert.deepEqual(Array.from(normalize(Float32Array.from([0, 0]))), [0, 0])
+})
+
+test('dot is the cosine similarity of unit vectors', () => {
+  assert.equal(dot(Float32Array.from([1, 0]), Float32Array.from([1, 0])), 1)
+  assert.equal(dot(Float32Array.from([1, 0]), Float32Array.from([0, 1])), 0)
+})
+
+test('clampInput truncates to the character budget', () => {
+  assert.equal(clampInput('abc').length, 3)
+  assert.equal(clampInput('x'.repeat(50_000)).length, 24_000)
+})
+
+test('embed uses the batch endpoint and preserves order', async () => {
+  const fetchImpl = makeStubFetch()
+  const result = await embedder(fetchImpl).embed(['alpha alpha', 'beta beta'])
+  assert.equal(result.length, 2)
+  assert.equal(fetchImpl.calls.filter((call) => call.url.endsWith('/api/embed')).length, 1)
+  // The two texts share no tokens, so their vectors must be orthogonal-ish.
+  assert.ok(dot(result[0], result[1]) < 0.05)
+})
+
+test('embed returns unit vectors', async () => {
+  const [vector] = await embedder(makeStubFetch()).embed(['some real code here'])
+  let sum = 0
+  for (const value of vector) sum += value * value
+  assert.ok(Math.abs(sum - 1) < 1e-5)
+})
+
+test('an endpoint without the batch API falls back to single requests', async () => {
+  const fetchImpl = makeStubFetch({ unsupportedBatch: true })
+  const subject = embedder(fetchImpl)
+  const result = await subject.embed(['one two', 'three four'])
+  assert.equal(result.length, 2)
+  assert.equal(subject.batchEnabled, false)
+  assert.equal(fetchImpl.calls.filter((call) => call.url.endsWith('/api/embeddings')).length, 2)
+})
+
+test('a dimension mismatch is fatal and explains itself', async () => {
+  const fetchImpl = makeStubFetch({ width: 128 })
+  await assert.rejects(
+    () => embedder(fetchImpl).embed(['x']),
+    (error) => {
+      assert.ok(error instanceof EmbeddingError)
+      assert.equal(error.code, 'DIMENSION_MISMATCH')
+      assert.match(error.message, /128-dimensional .* 768 are configured/)
+      return true
+    },
+  )
+})
+
+test('a persistent server error surfaces as UNREACHABLE after retrying', async () => {
+  let attempts = 0
+  const fetchImpl = async () => {
+    attempts += 1
+    return { ok: false, status: 500, text: async () => 'boom', json: async () => ({}) }
+  }
+  await assert.rejects(
+    () => embedder(fetchImpl).embed(['x']),
+    (error) => {
+      assert.equal(error.code, 'UNREACHABLE')
+      return true
+    },
+  )
+  assert.equal(attempts, 3, 'the request should be attempted MAX_ATTEMPTS times')
+})
+
+test('a transient failure is retried and then succeeds', async () => {
+  const good = makeStubFetch()
+  let calls = 0
+  const fetchImpl = async (url, init) => {
+    calls += 1
+    if (calls === 1) throw new Error('socket hang up')
+    return good(url, init)
+  }
+  const [vector] = await embedder(fetchImpl).embed(['retry me'])
+  assert.equal(vector.length, 768)
+  assert.equal(calls, 2)
+})
+
+test('a client error is not retried', async () => {
+  let attempts = 0
+  const fetchImpl = async () => {
+    attempts += 1
+    return { ok: false, status: 400, text: async () => 'bad model', json: async () => ({}) }
+  }
+  await assert.rejects(
+    () => embedder(fetchImpl).embed(['x']),
+    (error) => {
+      assert.equal(error.code, 'HTTP_ERROR')
+      return true
+    },
+  )
+  assert.equal(attempts, 1, 'a 400 is a configuration fault, not a transient one')
+})
+
+test('embedding nothing makes no request', async () => {
+  const fetchImpl = makeStubFetch()
+  const result = await embedder(fetchImpl).embed([])
+  assert.deepEqual(result, [])
+  assert.equal(fetchImpl.calls.length, 0)
+})
+
+test('cancellation stops the work', async () => {
+  const fetchImpl = makeStubFetch()
+  const controller = new AbortController()
+  controller.abort()
+  await assert.rejects(() => embedder(fetchImpl).embed(['x'], controller.signal))
+})
+
+test('keepAlive and maxAttempts are sent only when configured', async () => {
+  const withKeepAlive = makeStubFetch()
+  await embedder(withKeepAlive, { keepAlive: '10m' }).embed(['x'])
+  assert.equal(withKeepAlive.calls[0].body.keep_alive, '10m')
+
+  const without = makeStubFetch()
+  await embedder(without).embed(['x'])
+  assert.equal('keep_alive' in without.calls[0].body, false, 'an unset keep-alive must not be sent')
+})
+
+test('the keep-alive also reaches the single-text endpoint', async () => {
+  const fetchImpl = makeStubFetch({ unsupportedBatch: true })
+  await embedder(fetchImpl, { keepAlive: '2m' }).embed(['x'])
+  const legacy = fetchImpl.calls.find((call) => call.url.endsWith('/api/embeddings'))
+  assert.equal(legacy.body.keep_alive, '2m')
+})
+
+test('maxAttempts of one gives a probe a single chance', async () => {
+  let attempts = 0
+  const fetchImpl = async () => {
+    attempts += 1
+    return { ok: false, status: 500, text: async () => 'boom', json: async () => ({}) }
+  }
+  await assert.rejects(() => embedder(fetchImpl, { maxAttempts: 1 }).embed(['x']))
+  assert.equal(attempts, 1)
+})
+
+test('a socket that accepts and never answers fails on the timeout, not forever', async () => {
+  // The real failure mode observed in development: connection opens, no bytes.
+  const fetchImpl = (url, init) =>
+    new Promise((_resolve, reject) => {
+      init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true })
+    })
+  const started = Date.now()
+  await assert.rejects(
+    () => embedder(fetchImpl, { timeoutMs: 300, maxAttempts: 1 }).embed(['x']),
+    (error) => {
+      assert.equal(error.code, 'UNREACHABLE')
+      return true
+    },
+  )
+  assert.ok(Date.now() - started < 5_000, 'the timeout must bound the wait')
+})
diff --git a/test/expand.test.js b/test/expand.test.js
new file mode 100644
index 0000000..bd4c0b5
--- /dev/null
+++ b/test/expand.test.js
@@ -0,0 +1,120 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { cleanVariant, createExpander, parseVariants } from '../lib/expand.js'
+
+/** A stub endpoint that answers with a canned model response. */
+function stubFetch(response, options = {}) {
+  const { status = 200, hang = false } = options
+  const calls = []
+  const impl = async (url, init) => {
+    calls.push({ url, body: JSON.parse(init.body) })
+    if (hang) {
+      return new Promise((_resolve, reject) => {
+        init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true })
+      })
+    }
+    return { ok: status === 200, status, json: async () => ({ response }) }
+  }
+  impl.calls = calls
+  return impl
+}
+
+const MODEL = { apiBase: 'http://stub:11434', model: 'small-model', timeoutMs: 2_000, count: 4 }
+
+test('cleanVariant strips what models add around a list', () => {
+  assert.equal(cleanVariant('1. occupancy state machine'), 'occupancy state machine')
+  assert.equal(cleanVariant('- presence detection'), 'presence detection')
+  assert.equal(cleanVariant('* room occupied handler'), 'room occupied handler')
+  assert.equal(cleanVariant('"roomOccupied"'), 'roomOccupied')
+  assert.equal(cleanVariant('occupancy check — this finds the handler'), 'occupancy check')
+  assert.equal(cleanVariant('   '), undefined)
+  assert.equal(cleanVariant('x'.repeat(300)), undefined, 'a paragraph is not a search phrase')
+  assert.equal(cleanVariant('Here are some phrasings:'), undefined)
+})
+
+test('model commentary is never mistaken for a phrasing', () => {
+  // A line like this is not a weak variant, it is not a variant at all:
+  // embedding it would search the codebase for the model's apology.
+  for (const line of ['I cannot help with that.', "I can't do that.", 'Sorry, I need more context.', 'Unfortunately I do not have enough information.', 'Here are some phrasings:']) {
+    assert.equal(cleanVariant(line), undefined, `accepted ${line}`)
+  }
+  // But a question-shaped phrasing is entirely legitimate, and must survive.
+  assert.equal(cleanVariant('how does a room decide it is occupied'), 'how does a room decide it is occupied')
+  assert.equal(cleanVariant('where is the occupancy handler'), 'where is the occupancy handler')
+})
+
+test('parseVariants dedupes, drops the original, and caps the count', () => {
+  const body = ['occupancy state machine', 'room occupied detection', 'OCCUPANCY STATE MACHINE', 'presence tracking', 'extra one', 'extra two'].join('\n')
+  const variants = parseVariants(body, 'how does a room decide it is occupied', 3)
+  assert.deepEqual(variants, ['occupancy state machine', 'room occupied detection', 'presence tracking'])
+})
+
+test('expansion returns the original first, then the variants', async () => {
+  const fetchImpl = stubFetch('occupancy state machine\nroom occupied handler')
+  const variants = await createExpander({ ...MODEL, fetchImpl }).expand('how does a room decide it is occupied')
+  assert.equal(variants[0], 'how does a room decide it is occupied')
+  assert.deepEqual(variants.slice(1), ['occupancy state machine', 'room occupied handler'])
+  // The query must actually reach the model.
+  assert.match(fetchImpl.calls[0].body.prompt, /how does a room decide it is occupied/)
+  assert.equal(fetchImpl.calls[0].body.stream, false)
+})
+
+test('an unreachable endpoint degrades to the original query, never an error', async () => {
+  const fetchImpl = async () => {
+    throw new Error('ECONNREFUSED')
+  }
+  const variants = await createExpander({ ...MODEL, fetchImpl }).expand('some query')
+  assert.deepEqual(variants, ['some query'])
+})
+
+test('a WEDGED endpoint degrades to the original query, and does not hang', async () => {
+  // The failure actually observed on the box: the socket opens and nothing ever
+  // comes back. Expansion must give up on its own deadline rather than pass the
+  // wait on to a search that has nothing to do with the local model.
+  const fetchImpl = stubFetch('', { hang: true })
+  const started = Date.now()
+  const variants = await createExpander({ ...MODEL, fetchImpl, timeoutMs: 120 }).expand('some query')
+  assert.deepEqual(variants, ['some query'])
+  assert.ok(Date.now() - started < 3_000, 'the internal deadline must bound the wait')
+})
+
+test('a non-200 response degrades rather than throwing', async () => {
+  const variants = await createExpander({ ...MODEL, fetchImpl: stubFetch('', { status: 500 }) }).expand('q')
+  assert.deepEqual(variants, ['q'])
+})
+
+test('a response with nothing usable leaves just the original', async () => {
+  const variants = await createExpander({ ...MODEL, fetchImpl: stubFetch('I cannot help with that.') }).expand('q')
+  assert.deepEqual(variants, ['q'])
+})
+
+test('a non-finite timeout is clamped, not turned into a silent fallback', async () => {
+  // Without the clamp, AbortSignal.timeout(NaN) throws and the catch below
+  // reports it as "the model had nothing to say" — a misconfiguration wearing
+  // the disguise of a slow model.
+  const fetchImpl = stubFetch('occupancy handler')
+  const variants = await createExpander({ ...MODEL, fetchImpl, timeoutMs: Number.NaN }).expand('q')
+  assert.deepEqual(variants, ['q', 'occupancy handler'])
+})
+
+test('a malformed payload degrades rather than throwing', async () => {
+  const fetchImpl = async () => ({ ok: true, status: 200, json: async () => ({}) })
+  assert.deepEqual(await createExpander({ ...MODEL, fetchImpl }).expand('q'), ['q'])
+})
+
+test('an empty or oversized query is not sent at all', async () => {
+  const fetchImpl = stubFetch('variant one')
+  const expander = createExpander({ ...MODEL, fetchImpl })
+  assert.deepEqual(await expander.expand('   '), [''])
+  assert.deepEqual(await expander.expand('x'.repeat(600)), ['x'.repeat(600)])
+  assert.equal(fetchImpl.calls.length, 0, 'nothing worth asking about')
+})
+
+test('caller cancellation stops expansion and returns the original', async () => {
+  const controller = new AbortController()
+  controller.abort()
+  const fetchImpl = stubFetch('variant one')
+  assert.deepEqual(await createExpander({ ...MODEL, fetchImpl }).expand('q', controller.signal), ['q'])
+  assert.equal(fetchImpl.calls.length, 0)
+})
diff --git a/test/focus.test.js b/test/focus.test.js
new file mode 100644
index 0000000..9dbab4e
--- /dev/null
+++ b/test/focus.test.js
@@ -0,0 +1,222 @@
+import { strict as assert } from 'node:assert'
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test } from 'node:test'
+
+import {
+  DEFAULT_FOCUS_MARKERS,
+  ancestorsTo,
+  discoverScopes,
+  focusKey,
+  isInside,
+  resolveFocus,
+} from '../lib/focus.js'
+
+const WORKSPACE = '/repo'
+
+/**
+ * The two filesystem injection points, faked.
+ *
+ * `exists` and `isDirectory` are separate because the real code distinguishes
+ * them: a focus path must not merely exist, it must be a directory. A single
+ * predicate would let a test pass a file where a directory is required.
+ *
+ * @param {string[]} files paths that exist
+ * @param {string[]} [directories] paths that are directories (defaults to `files`)
+ */
+function fakeFs(files, directories = files) {
+  const fileSet = new Set(files)
+  const dirSet = new Set(directories)
+  return { exists: (path) => fileSet.has(path), isDirectory: (path) => dirSet.has(path) }
+}
+
+test('isInside treats a directory as inside itself and rejects siblings', () => {
+  assert.equal(isInside('/repo', '/repo'), true)
+  assert.equal(isInside('/repo', '/repo/src'), true)
+  assert.equal(isInside('/repo', '/repository'), false, 'a shared prefix is not a child')
+  assert.equal(isInside('/repo', '/other'), false)
+})
+
+test('ancestorsTo walks up to the stop directory and no further', () => {
+  assert.deepEqual(ancestorsTo('/repo/src/a/b', '/repo'), ['/repo/src/a/b', '/repo/src/a', '/repo/src', '/repo'])
+  assert.deepEqual(ancestorsTo('/repo', '/repo'), ['/repo'])
+  // A start outside the stop does not run away to the filesystem root.
+  assert.deepEqual(ancestorsTo('/elsewhere/x', '/repo'), ['/elsewhere/x'])
+})
+
+test('no markers anywhere means the workspace, which is the old behaviour', () => {
+  const result = resolveFocus({ workspace: WORKSPACE, cwd: WORKSPACE, ...fakeFs([]) })
+  assert.equal(result.root, '/repo')
+  assert.equal(result.source, 'workspace')
+})
+
+test('a marker at the workspace root keeps the scope at the workspace', () => {
+  // This is the live case today: AGENTS.md sits at the repository root, so
+  // adopting focus changes nothing until a nested folder carries a marker.
+  const result = resolveFocus({ workspace: WORKSPACE, cwd: WORKSPACE, ...fakeFs(['/repo/AGENTS.md']) })
+  assert.equal(result.root, '/repo')
+  assert.equal(result.source, 'marker')
+  assert.equal(result.marker, 'AGENTS.md')
+})
+
+test('a nested controller marker narrows the scope to that controller', () => {
+  const controller = '/repo/src/controllers/room/occupancy'
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: controller,
+    ...fakeFs(['/repo/AGENTS.md', `${controller}/CONTROLLER.md`]),
+  })
+  assert.equal(result.root, controller)
+  assert.equal(result.source, 'marker')
+  assert.equal(result.marker, 'CONTROLLER.md')
+})
+
+test('the nearest marker wins over a further one', () => {
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: '/repo/src/controllers/room/occupancy/state_machine',
+    ...fakeFs(['/repo/AGENTS.md', '/repo/src/controllers/room/occupancy/CONTROLLER.md']),
+  })
+  assert.equal(result.root, '/repo/src/controllers/room/occupancy')
+})
+
+test('CONTROLLER.md outranks AGENTS.md in the same directory', () => {
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: WORKSPACE,
+    ...fakeFs(['/repo/AGENTS.md', '/repo/CONTROLLER.md']),
+  })
+  assert.equal(result.marker, 'CONTROLLER.md', 'the more specific marker should be reported')
+})
+
+test('an explicit focus wins over any marker', () => {
+  const lights = '/repo/src/controllers/room/device/lights'
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: WORKSPACE,
+    explicit: 'src/controllers/room/device/lights',
+    ...fakeFs(['/repo/AGENTS.md', lights]),
+  })
+  assert.equal(result.root, lights)
+  assert.equal(result.source, 'explicit')
+})
+
+test('an explicit focus may be absolute', () => {
+  const result = resolveFocus({ workspace: WORKSPACE, explicit: '/repo/src/x', ...fakeFs(['/repo/src/x']) })
+  assert.equal(result.root, '/repo/src/x')
+  assert.equal(result.source, 'explicit')
+})
+
+test('an explicit focus that is a file, not a directory, is refused', () => {
+  // The two predicates must genuinely differ, or this passes by accident.
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    explicit: 'src/AGENTS.md',
+    ...fakeFs(['/repo/src/AGENTS.md'], ['/repo', '/repo/src']),
+  })
+  assert.equal(result.root, '/repo')
+  assert.match(result.problem, /not a directory/)
+})
+
+test('a focus outside the workspace is refused and reported, not obeyed', () => {
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    explicit: '../elsewhere',
+    ...fakeFs(['/elsewhere'], ['/elsewhere']),
+  })
+  assert.equal(result.root, '/repo', 'must fall back to the workspace')
+  assert.match(result.problem, /outside the workspace/)
+})
+
+test('a focus that does not exist is refused and reported', () => {
+  const result = resolveFocus({ workspace: WORKSPACE, explicit: 'src/typo', ...fakeFs([]) })
+  assert.equal(result.root, '/repo')
+  assert.match(result.problem, /not a directory/)
+})
+
+test('an empty marker list still resolves, to the workspace', () => {
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: WORKSPACE,
+    markers: [],
+    ...fakeFs(['/repo/AGENTS.md']),
+  })
+  assert.equal(result.root, '/repo')
+  assert.equal(result.source, 'workspace')
+})
+
+test('a cwd outside the workspace cannot escape it', () => {
+  const result = resolveFocus({
+    workspace: WORKSPACE,
+    cwd: '/somewhere/else',
+    ...fakeFs(['/somewhere/else/AGENTS.md', '/repo/AGENTS.md']),
+  })
+  assert.equal(result.root, '/repo', 'a stray cwd must not pull the scope out of the workspace')
+})
+
+test('focusKey is a stable relative path, with "." for the workspace itself', () => {
+  assert.equal(focusKey('/repo', '/repo'), '.')
+  assert.equal(focusKey('/repo', '/repo/src/controllers/room/occupancy'), 'src/controllers/room/occupancy')
+})
+
+test('the default markers include the controller instruction files', () => {
+  assert.ok(DEFAULT_FOCUS_MARKERS.includes('CONTROLLER.md'))
+  assert.ok(DEFAULT_FOCUS_MARKERS.includes('DEBUG_UI.md'))
+  // CONTROLLER.md must be tried before AGENTS.md, since both may be present.
+  assert.ok(DEFAULT_FOCUS_MARKERS.indexOf('CONTROLLER.md') < DEFAULT_FOCUS_MARKERS.indexOf('AGENTS.md'))
+})
+
+test('discoverScopes finds marker directories, sorted and workspace-relative', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-scopes-'))
+  try {
+    await mkdir(join(root, 'src', 'weather'), { recursive: true })
+    await mkdir(join(root, 'src', 'auth'), { recursive: true })
+    await mkdir(join(root, 'node_modules', 'dep'), { recursive: true })
+    await writeFile(join(root, 'src', 'auth', 'CONTROLLER.md'), '# auth\n')
+    await writeFile(join(root, 'src', 'weather', 'CONTROLLER.md'), '# weather\n')
+    await writeFile(join(root, 'AGENTS.md'), '# repo\n')
+    // A marker inside a dependency describes somebody else's project.
+    await writeFile(join(root, 'node_modules', 'dep', 'CONTROLLER.md'), '# not ours\n')
+    await writeFile(join(root, 'src', 'code.ts'), 'export const x = 1\n')
+
+    const scopes = await discoverScopes({ workspace: root })
+    assert.deepEqual(
+      scopes.map((scope) => scope.path),
+      ['.', 'src/auth', 'src/weather'],
+      'sorted, relative, and node_modules excluded',
+    )
+    assert.equal(scopes[0].marker, 'AGENTS.md')
+    assert.equal(scopes[1].marker, 'CONTROLLER.md')
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('discoverScopes honours a custom marker list and maxDepth', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-scopes-'))
+  try {
+    await mkdir(join(root, 'deep', 'deeper', 'deepest'), { recursive: true })
+    await writeFile(join(root, 'deep', 'SCOPE.md'), '# scope\n')
+    await writeFile(join(root, 'deep', 'deeper', 'deepest', 'SCOPE.md'), '# scope\n')
+
+    const shallow = await discoverScopes({ workspace: root, markers: ['SCOPE.md'], maxDepth: 1 })
+    assert.deepEqual(shallow.map((scope) => scope.path), ['deep'])
+
+    const deep = await discoverScopes({ workspace: root, markers: ['SCOPE.md'], maxDepth: 4 })
+    assert.deepEqual(deep.map((scope) => scope.path), ['deep', 'deep/deeper/deepest'])
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('discoverScopes returns nothing for a directory with no markers', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-scopes-'))
+  try {
+    await mkdir(join(root, 'src'), { recursive: true })
+    await writeFile(join(root, 'src', 'a.ts'), 'a\n')
+    assert.deepEqual(await discoverScopes({ workspace: root }), [])
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
diff --git a/test/helpers.js b/test/helpers.js
new file mode 100644
index 0000000..5df71ab
--- /dev/null
+++ b/test/helpers.js
@@ -0,0 +1,123 @@
+/**
+ * Shared test scaffolding.
+ *
+ * The embedding stub is a bag-of-words hash rather than the real model, for two
+ * reasons: the suite must run without a network, and a deterministic vector
+ * makes a ranking assertion a statement about the ranking code rather than a
+ * statement about a model that may change under it. Whether the real model
+ * retrieves the right file is a different question, answered by
+ * `scripts/smoke.mjs` against a live endpoint.
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** Deterministic unit vector for a piece of text. */
+export function hashEmbed(text, width) {
+  const vector = new Float32Array(width)
+  for (const token of String(text).toLowerCase().split(/[^a-z0-9]+/)) {
+    if (token.length < 3) continue
+    const digest = createHash('sha1').update(token).digest()
+    const slot = ((digest[0] << 8) | digest[1]) % width
+    vector[slot] += 1
+  }
+  let sum = 0
+  for (let at = 0; at < width; at += 1) sum += vector[at] * vector[at]
+  if (sum === 0) return vector
+  const scale = 1 / Math.sqrt(sum)
+  for (let at = 0; at < width; at += 1) vector[at] *= scale
+  return vector
+}
+
+/** A `fetch` that answers the Ollama embedding API deterministically. */
+export function makeStubFetch(options = {}) {
+  const { width = 768, onCall, unsupportedBatch = false, generate = undefined } = options
+  const calls = []
+  const impl = async (url, init) => {
+    const address = String(url)
+    const body = JSON.parse(init.body)
+    calls.push({ url: address, body })
+    onCall?.(address, body)
+    // The generation endpoint the expander and the re-ranker share. Left
+    // unanswered unless a test supplies a response, so a caller that expects
+    // the local model to be absent gets that for free.
+    if (address.endsWith('/api/generate')) {
+      if (generate === undefined) return { ok: false, status: 404, text: async () => 'no model', json: async () => ({}) }
+      const response = typeof generate === 'function' ? generate(body) : generate
+      return { ok: true, status: 200, json: async () => ({ response }) }
+    }
+    if (address.endsWith('/api/embed')) {
+      if (unsupportedBatch) {
+        return { ok: false, status: 404, text: async () => 'not found', json: async () => ({}) }
+      }
+      const inputs = body.input
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ embeddings: inputs.map((text) => Array.from(hashEmbed(text, width))) }),
+      }
+    }
+    if (address.endsWith('/api/embeddings')) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ embedding: Array.from(hashEmbed(body.prompt, width)) }),
+      }
+    }
+    return { ok: false, status: 404, text: async () => 'unknown endpoint', json: async () => ({}) }
+  }
+  impl.calls = calls
+  return impl
+}
+
+/**
+ * The smallest context shape `apply` actually touches.
+ *
+ * `services` mounts optional dependencies: `ctx.inject` invokes its callback
+ * only when every named dependency is present, which is how the plugin decides
+ * whether it can offer a settings namespace or a projection. Passing none
+ * exercises the composition-config path every minimal profile takes.
+ */
+export function makeContext(options = {}) {
+  const { services = {} } = options
+  const tools = []
+  const cleanups = []
+  const ctx = {
+    logger: () => ({ warn() {}, info() {}, error() {}, debug() {} }),
+    effect: (fn) => {
+      const dispose = fn()
+      if (typeof dispose === 'function') cleanups.push(dispose)
+    },
+    get: (name) => services[name],
+    inject: (deps, callback) => {
+      const missing = deps.filter((dep) => services[dep] === undefined)
+      if (missing.length > 0) return
+      callback({ ...ctx, ...Object.fromEntries(deps.map((dep) => [dep, services[dep]])) })
+    },
+    tools: { register: (tool) => tools.push(tool) },
+  }
+  return { ctx, tools, dispose: () => cleanups.forEach((fn) => fn()) }
+}
+
+/** An `exec` argument for one tool call. */
+export function makeExec(cwd, signal) {
+  return { signal: signal ?? new AbortController().signal, agent: { session: { header: { cwd } } } }
+}
+
+/** Write a map of relative path to content into a fresh temporary directory. */
+export async function makeWorkspace(files) {
+  const root = await mkdtemp(join(tmpdir(), 'recall-test-'))
+  for (const [path, content] of Object.entries(files)) {
+    const absolute = join(root, path)
+    await mkdir(dirname(absolute), { recursive: true })
+    await writeFile(absolute, content, 'utf8')
+  }
+  return root
+}
+
+/** A fresh temporary directory, for index state. */
+export async function makeStateDir() {
+  return mkdtemp(join(tmpdir(), 'recall-state-'))
+}
diff --git a/test/plugin.test.js b/test/plugin.test.js
new file mode 100644
index 0000000..c840cdc
--- /dev/null
+++ b/test/plugin.test.js
@@ -0,0 +1,690 @@
+import { strict as assert } from 'node:assert'
+import { readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { test } from 'node:test'
+
+import { apply } from '../index.js'
+import { makeContext, makeExec, makeStateDir, makeStubFetch, makeWorkspace } from './helpers.js'
+
+/**
+ * Validate a value against the tool's own declared output schema.
+ *
+ * This exists because the schema is `additionalProperties: false` and the host
+ * enforces it before the model ever sees a result — so an internal field leaking
+ * into the returned object is not a cosmetic extra, it is a failed call. The
+ * check is deliberately written against the declared schema rather than a copy
+ * of it, so the two cannot drift apart.
+ */
+function schemaErrors(schema, value, at = '$') {
+  const errors = []
+  if (schema.oneOf !== undefined) {
+    if (!schema.oneOf.some((branch) => schemaErrors(branch, value, at).length === 0)) {
+      errors.push(`${at}: matched no oneOf branch`)
+    }
+    return errors
+  }
+  const type = schema.type
+  if (type === 'object') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      errors.push(`${at}: expected an object`)
+      return errors
+    }
+    const properties = schema.properties ?? {}
+    for (const [key, sub] of Object.entries(properties)) {
+      if (sub.required === true && value[key] === undefined) errors.push(`${at}.${key}: required but missing`)
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) errors.push(`${at}.${key}: not declared, but additionalProperties is false`)
+      }
+    }
+    for (const [key, sub] of Object.entries(properties)) {
+      if (value[key] !== undefined) errors.push(...schemaErrors(sub, value[key], `${at}.${key}`))
+    }
+    return errors
+  }
+  if (type === 'array') {
+    if (!Array.isArray(value)) {
+      errors.push(`${at}: expected an array`)
+      return errors
+    }
+    value.forEach((item, index) => errors.push(...schemaErrors(schema.items ?? {}, item, `${at}[${index}]`)))
+    return errors
+  }
+  if (type === 'json') return errors
+  if (type === 'string' && typeof value !== 'string') errors.push(`${at}: expected a string`)
+  if (type === 'boolean' && typeof value !== 'boolean') errors.push(`${at}: expected a boolean`)
+  if (type === 'integer' && !Number.isInteger(value)) errors.push(`${at}: expected an integer`)
+  if (type === 'number' && typeof value !== 'number') errors.push(`${at}: expected a number`)
+  if (schema.enum !== undefined && !schema.enum.includes(value)) errors.push(`${at}: not one of ${schema.enum.join(', ')}`)
+  return errors
+}
+
+const SESSION = `import { randomBytes } from 'node:crypto'
+
+const SESSION_TTL_MS = 1000 * 60 * 60 * 12
+
+export interface SessionRecord {
+  userId: string
+  issuedAt: number
+  expiresAt: number
+}
+
+export function issueSession(userId: string): SessionRecord {
+  const now = Date.now()
+  return { userId, issuedAt: now, expiresAt: now + SESSION_TTL_MS }
+}
+
+export function isSessionExpired(record: SessionRecord, now = Date.now()): boolean {
+  return record.expiresAt <= now
+}
+
+export function rotateSessionToken(record: SessionRecord): string {
+  if (isSessionExpired(record)) throw new Error('cannot rotate an expired session')
+  return randomBytes(32).toString('hex')
+}
+
+export function sessionTimeRemaining(record: SessionRecord, now = Date.now()): number {
+  return Math.max(0, record.expiresAt - now)
+}
+
+export function describeSession(record: SessionRecord): string {
+  const remaining = sessionTimeRemaining(record)
+  return remaining === 0 ? 'expired' : 'active for ' + remaining + 'ms'
+}
+`
+
+const FORECAST = `export interface ForecastDay {
+  date: string
+  minC: number
+  maxC: number
+  rainMm: number
+}
+
+export function averageTemperature(days: ForecastDay[]): number {
+  if (days.length === 0) return 0
+  return days.reduce((sum, day) => sum + (day.minC + day.maxC) / 2, 0) / days.length
+}
+
+export function totalRainfall(days: ForecastDay[]): number {
+  return days.reduce((sum, day) => sum + day.rainMm, 0)
+}
+`
+
+const SQLITE = `import { DatabaseSync } from 'node:sqlite'
+
+export function openDatabase(path: string): DatabaseSync {
+  const db = new DatabaseSync(path)
+  db.exec('PRAGMA journal_mode = WAL')
+  return db
+}
+`
+
+const FILES = {
+  'src/auth/session.ts': SESSION,
+  'src/weather/forecast.ts': FORECAST,
+  'src/store/sqlite.ts': SQLITE,
+}
+
+function configFor(stateDir, extra = {}) {
+  return {
+    embeddingApiBase: 'http://stub',
+    embeddingModel: 'test-model',
+    embeddingDimensions: 768,
+    embeddingApiKey: '',
+    embeddingBatchSize: 32,
+    embeddingConcurrency: 2,
+    embeddingTimeoutMs: 5_000,
+    extensions: [],
+    exclude: [],
+    maxFiles: 500,
+    maxFileBytes: 1_048_576,
+    chunkLines: 48,
+    maxChunkLines: 80,
+    overlapLines: 8,
+    defaultLimit: 8,
+    maxLimit: 25,
+    perFileLimit: 2,
+    excerptLines: 40,
+    minSimilarity: 0.2,
+    syncBudgetMs: 20_000,
+    // These mirror the Config schema exactly. Cordis fills schema defaults
+    // before `apply`, and this object stands in for that validated config — so
+    // any key the code reads and this object omits arrives as `undefined`, which
+    // is how `AbortSignal.timeout(NaN)` came to throw inside the expander.
+    focus: '',
+    focusMarkers: [],
+    expansionEnabled: false,
+    expansionModel: '',
+    expansionCount: 4,
+    expansionTimeoutMs: 8_000,
+    rerankEnabled: false,
+    rerankModel: '',
+    rerankCandidates: 8,
+    rerankTimeoutMs: 15_000,
+    stateDir,
+    ...extra,
+  }
+}
+
+/** Apply the plugin to a fresh workspace with a stubbed embedding endpoint. */
+async function setup(t, files = FILES, extra = {}, stubOptions = {}) {
+  const workspace = await makeWorkspace(files)
+  const stateDir = await makeStateDir()
+  const stub = makeStubFetch(stubOptions)
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = stub
+  t.after(async () => {
+    globalThis.fetch = originalFetch
+    await rm(workspace, { recursive: true, force: true })
+    await rm(stateDir, { recursive: true, force: true })
+  })
+
+  const { ctx, tools, dispose } = makeContext()
+  t.after(() => dispose())
+  apply(ctx, configFor(stateDir, extra))
+  assert.equal(tools.length, 1, 'exactly one tool should be registered')
+  return { tool: tools[0], workspace, stub }
+}
+
+test('the plugin registers one tool whose declared schema is closed', async (t) => {
+  const { tool } = await setup(t)
+  assert.equal(tool.name, 'recall')
+  assert.equal(tool.output.schema.additionalProperties, false)
+  // defineTool normalises the parameter DSL into a JSON Schema object.
+  assert.deepEqual(tool.parameters.properties.action.enum, ['search', 'index', 'status', 'configure'])
+  assert.equal(tool.parameters.properties.query.type, 'string')
+  // A long index must not run in parallel with sibling tool calls.
+  assert.equal(tool.isConcurrencySafe({ action: 'search' }), true)
+  assert.equal(tool.isConcurrencySafe({ action: 'index' }), false)
+})
+
+test('a search returns the right file, as an excerpt rather than a whole file', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute(
+    { query: 'how long until a user session token expires' },
+    makeExec(workspace),
+  )
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, true)
+  assert.equal(value.results.length > 0, true)
+  assert.equal(value.results[0].path, 'src/auth/session.ts')
+
+  // The excerpt must be a real slice of the file on disk, not paraphrase.
+  const onDisk = await readFile(join(workspace, 'src/auth/session.ts'), 'utf8')
+  assert.ok(onDisk.includes(value.results[0].excerpt), 'the excerpt must come from the file')
+  assert.ok(
+    value.results[0].excerpt.split('\n').length <= 40,
+    'the excerpt must respect the configured line cap',
+  )
+  assert.ok(
+    value.results[0].excerpt.length < onDisk.length,
+    'the point of the tool is to return less than the whole file',
+  )
+})
+
+test('a second search re-embeds nothing, because the index is incremental', async (t) => {
+  const { tool, workspace, stub } = await setup(t)
+  await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  const afterFirst = stub.calls.length
+  assert.ok(afterFirst > 1, 'the first search should have embedded the workspace')
+
+  await tool.execute({ query: 'rainfall totals' }, makeExec(workspace))
+  const second = stub.calls.slice(afterFirst)
+  // Exactly one request: the query vector. A warm index embeds no files.
+  assert.equal(second.length, 1, `expected only a query embed, saw ${second.length} requests`)
+})
+
+test('an edited file is re-embedded on the next search', async (t) => {
+  const { tool, workspace, stub } = await setup(t)
+  await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  const afterFirst = stub.calls.length
+
+  await writeFile(
+    join(workspace, 'src/weather/forecast.ts'),
+    `${FORECAST}\nexport function humidityPercent(days: ForecastDay[]): number {\n  return days.length\n}\n`,
+    'utf8',
+  )
+  await tool.execute({ query: 'humidityPercent' }, makeExec(workspace))
+  const second = stub.calls.slice(afterFirst)
+  assert.ok(second.length >= 2, 'the changed file plus the query should both be embedded')
+  assert.deepEqual(second[second.length - 1].body.input, ['humidityPercent'])
+})
+
+test('a spent sync budget leaves the rest pending rather than lying about it', async (t) => {
+  const { tool, workspace } = await setup(t, FILES, { syncBudgetMs: 0 })
+  // First search indexes one file, then the budget stops it.
+  const first = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.ok(first.index.pending >= 1, `expected pending work, saw ${first.index.pending}`)
+
+  // A full index action catches up.
+  const full = await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, full), [])
+  assert.equal(full.index.pending, 0)
+
+  const third = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.equal(third.index.pending, 0)
+})
+
+test('the index action builds the whole workspace', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, true)
+  assert.equal(value.index.files, 3)
+  assert.ok(value.index.chunks >= 3)
+})
+
+test('status probes the endpoint once and reports it healthy', async (t) => {
+  const { tool, workspace, stub } = await setup(t)
+  const value = await tool.execute({ action: 'status' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, true)
+  // Exactly one request: the probe. Status must not index or search.
+  assert.equal(stub.calls.length, 1, `status should probe once, saw ${stub.calls.length}`)
+  assert.equal(value.endpoint.ok, true)
+  assert.match(value.note, /endpoint answered/)
+})
+
+test('status reports an endpoint that accepts the connection and never answers', async (t) => {
+  // The failure mode that a plain reachability check misses, and the one that
+  // actually happened in development: the socket opens, no bytes ever come back.
+  const workspace = await makeWorkspace(FILES)
+  const stateDir = await makeStateDir()
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = (url, init) =>
+    new Promise((_resolve, reject) => {
+      init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true })
+    })
+  t.after(async () => {
+    globalThis.fetch = originalFetch
+    await rm(workspace, { recursive: true, force: true })
+    await rm(stateDir, { recursive: true, force: true })
+  })
+
+  const { ctx, tools, dispose } = makeContext()
+  t.after(() => dispose())
+  // A short timeout keeps the probe honest about how long it will wait.
+  apply(ctx, configFor(stateDir, { embeddingTimeoutMs: 1_000 }))
+  const value = await tools[0].execute({ action: 'status' }, makeExec(workspace))
+
+  assert.deepEqual(schemaErrors(tools[0].output.schema, value), [])
+  assert.equal(value.ok, true, 'status itself succeeded; it is reporting a fault, not failing')
+  assert.equal(value.endpoint.ok, false)
+  assert.equal(value.endpoint.errorCode, 'UNREACHABLE')
+  assert.match(value.note, /did NOT answer/)
+})
+
+test('a search without a query is refused with advice', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({}, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, false)
+  assert.equal(value.errorCode, 'NO_QUERY')
+  assert.ok(value.remedy !== undefined)
+})
+
+test('a path filter restricts results to that directory', async (t) => {
+  const { tool, workspace } = await setup(t)
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute(
+    { query: 'function', path: 'src/weather' },
+    makeExec(workspace),
+  )
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.ok(value.results.length > 0)
+  for (const result of value.results) assert.match(result.path, /^src\/weather\//)
+})
+
+test('configure reports the missing settings provider instead of pretending to save', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute(
+    { action: 'configure', config: { embeddingApiBase: 'http://elsewhere:11434' } },
+    makeExec(workspace),
+  )
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, false)
+  assert.equal(value.errorCode, 'NO_SETTINGS_PROVIDER')
+  assert.match(value.remedy, /cordis layer/)
+})
+
+test('configure rejects an unknown setting by name', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute(
+    { action: 'configure', config: { nonsense: 1 } },
+    makeExec(workspace),
+  )
+  assert.equal(value.errorCode, 'UNKNOWN_SETTING')
+  assert.match(value.note, /nonsense/)
+})
+
+test('an unreachable endpoint fails with a remedy, not a stack trace', async (t) => {
+  const workspace = await makeWorkspace(FILES)
+  const stateDir = await makeStateDir()
+  const originalFetch = globalThis.fetch
+  // A persistent 5xx, which the client retries and then reports as unreachable.
+  globalThis.fetch = async () => ({ ok: false, status: 500, text: async () => 'boom', json: async () => ({}) })
+  t.after(async () => {
+    globalThis.fetch = originalFetch
+    await rm(workspace, { recursive: true, force: true })
+    await rm(stateDir, { recursive: true, force: true })
+  })
+
+  const { ctx, tools, dispose } = makeContext()
+  t.after(() => dispose())
+  apply(ctx, configFor(stateDir))
+  const value = await tools[0].execute({ query: 'anything at all' }, makeExec(workspace))
+
+  assert.deepEqual(schemaErrors(tools[0].output.schema, value), [])
+  assert.equal(value.ok, false)
+  assert.equal(value.errorCode, 'UNREACHABLE')
+  assert.match(value.remedy, /embeddingApiBase/)
+})
+
+test('a workspace with no indexable code says so plainly', async (t) => {
+  const { tool, workspace } = await setup(t, { 'README.md': '# prose only\n' })
+  const value = await tool.execute({ query: 'anything' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.ok, true)
+  assert.deepEqual(value.results, [])
+  assert.match(value.note, /Nothing is indexed/)
+})
+
+test('the rendered result is compact and names the file and line range', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({ query: 'session token rotation' }, makeExec(workspace))
+  const blocks = tool.output.render({ query: 'session token rotation' }, value)
+  assert.equal(blocks.length, 1)
+  assert.equal(blocks[0].type, 'text')
+  assert.match(blocks[0].text, /src\/auth\/session\.ts:\d+-\d+/)
+  // It must not dump the whole file into the conversation.
+  assert.ok(blocks[0].text.length < SESSION.length * 3)
+})
+
+test('an empty result tells the model to prefer grep', async (t) => {
+  const { tool, workspace } = await setup(t)
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute(
+    { query: 'zzzz-nothing-matches-this-zzzz', path: 'src/store' },
+    makeExec(workspace),
+  )
+  const blocks = tool.output.render({ query: 'zzzz' }, value)
+  if (value.results.length === 0) {
+    assert.match(blocks[0].text, /grep/)
+  } else {
+    assert.equal(value.weak, true)
+    assert.match(blocks[0].text, /No strong match/)
+  }
+})
+
+test('focus narrows the index to one directory, and paths stay workspace-relative', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute(
+    { action: 'index', focus: 'src/auth', run_in_background: false },
+    makeExec(workspace),
+  )
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.focus.path, 'src/auth')
+  assert.equal(value.focus.source, 'explicit')
+  assert.equal(value.index.files, 1, 'only src/auth should be indexed')
+
+  const search = await tool.execute({ query: 'session expiry', focus: 'src/auth' }, makeExec(workspace))
+  assert.ok(search.results.length > 0)
+  for (const result of search.results) {
+    // The critical invariant: a result path must be usable with `read`, which
+    // resolves against the workspace. A focus-relative path here would read the
+    // wrong file.
+    assert.match(result.path, /^src\/auth\//, `path was ${result.path}`)
+    const onDisk = await readFile(join(workspace, result.path), 'utf8')
+    assert.ok(onDisk.includes(result.excerpt), `${result.path} should resolve from the workspace root`)
+  }
+})
+
+test('each focus keeps its own index', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const auth = await tool.execute({ action: 'index', focus: 'src/auth', run_in_background: false }, makeExec(workspace))
+  const weather = await tool.execute({ action: 'index', focus: 'src/weather', run_in_background: false }, makeExec(workspace))
+
+  assert.equal(auth.index.files, 1)
+  assert.equal(weather.index.files, 1)
+  assert.notEqual(auth.index.database, weather.index.database, 'focuses must not share an index file')
+  assert.notEqual(auth.index.database, (await tool.execute({ action: 'status' }, makeExec(workspace))).index.database)
+})
+
+test('a search in one focus cannot see another focus', async (t) => {
+  const { tool, workspace } = await setup(t)
+  await tool.execute({ action: 'index', focus: 'src/weather', run_in_background: false }, makeExec(workspace))
+  // A tolerant query that would match the auth module if it were in scope.
+  const value = await tool.execute({ query: 'issueSession session expiry', focus: 'src/weather' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  for (const result of value.results) assert.match(result.path, /^src\/weather\//)
+})
+
+test('an unusable focus is reported and falls back, never silently obeyed', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute(
+    { action: 'index', focus: 'src/does-not-exist', run_in_background: false },
+    makeExec(workspace),
+  )
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.focus.path, '.', 'must fall back to the workspace')
+  assert.match(value.focus.problem, /not a directory/)
+  assert.equal(value.index.files, 3, 'the fallback index covers the whole workspace')
+})
+
+test('status reports which focus is in effect, and why', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({ action: 'status' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.focus.path, '.')
+  // This fixture has no AGENTS.md, so resolution reaches the final fallback.
+  assert.equal(value.focus.source, 'workspace')
+  assert.match(value.note, /scoped to the whole workspace/)
+})
+
+test('a session at the workspace root keeps the whole workspace, even with nested scopes', async (t) => {
+  // Inheritance and discovery are different questions. The root's own AGENTS.md
+  // is what contains this session; the controller below is merely available.
+  // Auto-adopting it would hide the other two thirds of the workspace.
+  const { tool, workspace } = await setup(t, {
+    'AGENTS.md': '# repo instructions\n',
+    'src/auth/CONTROLLER.md': '# the auth controller\n',
+    ...FILES,
+  })
+  const value = await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.equal(value.focus.path, '.')
+  assert.equal(value.focus.source, 'marker')
+  assert.equal(value.focus.marker, 'AGENTS.md')
+  assert.equal(value.index.files, 3)
+})
+
+test('discovered scopes are listed, so a caller can name one', async (t) => {
+  const { tool, workspace } = await setup(t, {
+    'src/auth/CONTROLLER.md': '# the auth controller\n',
+    'src/weather/CONTROLLER.md': '# the weather controller\n',
+    ...FILES,
+  })
+  const value = await tool.execute({ action: 'status' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.deepEqual(value.scopes, [
+    { path: 'src/auth', marker: 'CONTROLLER.md' },
+    { path: 'src/weather', marker: 'CONTROLLER.md' },
+  ])
+  assert.match(value.note, /Available scopes: src\/auth, src\/weather/)
+})
+
+test('a workspace with no markers says so rather than listing nothing', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({ action: 'status' }, makeExec(workspace))
+  assert.deepEqual(value.scopes, [])
+  assert.match(value.note, /No focusable scopes/)
+})
+
+test('a scope found by discovery indexes only itself when named', async (t) => {
+  const { tool, workspace } = await setup(t, {
+    'src/auth/CONTROLLER.md': '# the auth controller\n',
+    ...FILES,
+  })
+  const listed = await tool.execute({ action: 'status' }, makeExec(workspace))
+  const [scope] = listed.scopes
+  const value = await tool.execute({ action: 'index', focus: scope.path, run_in_background: false }, makeExec(workspace))
+  assert.equal(value.focus.source, 'explicit')
+  assert.equal(value.index.files, 1, 'naming a discovered scope must confine the index to it')
+})
+
+test('the rendered search header names the scope when there is one', async (t) => {
+  const { tool, workspace } = await setup(t)
+  await tool.execute({ action: 'index', focus: 'src/auth', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute({ query: 'session', focus: 'src/auth' }, makeExec(workspace))
+  const blocks = tool.output.render({ query: 'session' }, value)
+  assert.match(blocks[0].text, /in src\/auth/)
+})
+
+test('the tool records what it saved, for the session log to carry', async (t) => {
+  const { tool, workspace } = await setup(t)
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+
+  // The comparison is against the whole of each file the excerpts came from.
+  assert.ok(value.measure.sourceBytes > 0)
+  assert.ok(
+    value.measure.sourceBytes > value.measure.returnedBytes,
+    `expected a saving, got ${value.measure.returnedBytes} of ${value.measure.sourceBytes}`,
+  )
+  assert.ok(value.measure.files >= 1)
+
+  const meta = tool.output.presentationMeta({ query: 'session expiry' }, value)
+  assert.equal(meta.recall.action, 'search')
+  assert.equal(meta.recall.excerpts, value.results.length)
+  assert.equal(meta.recall.sourceBytes, value.measure.sourceBytes)
+  assert.equal(meta.recall.returnedBytes, value.measure.returnedBytes)
+  // Pure: replayed on projection rebuilds, so it may not vary between calls.
+  assert.deepEqual(tool.output.presentationMeta({ query: 'session expiry' }, value), meta)
+  // And JSON-safe, because this is what actually lands in the log.
+  assert.deepEqual(JSON.parse(JSON.stringify(meta)), meta)
+})
+
+test('an index call records differently from a search', async (t) => {
+  const { tool, workspace } = await setup(t)
+  const value = await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const meta = tool.output.presentationMeta({ action: 'index' }, value)
+  assert.equal(meta.recall.action, 'index')
+  assert.equal(meta.recall.excerpts, undefined, 'indexing returns no excerpts to account for')
+})
+
+test('a failed search still leaves a record worth folding', async (t) => {
+  const workspace = await makeWorkspace(FILES)
+  const stateDir = await makeStateDir()
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async () => ({ ok: false, status: 500, text: async () => 'boom', json: async () => ({}) })
+  t.after(async () => {
+    globalThis.fetch = originalFetch
+    await rm(workspace, { recursive: true, force: true })
+    await rm(stateDir, { recursive: true, force: true })
+  })
+  const { ctx, tools, dispose } = makeContext()
+  t.after(() => dispose())
+  apply(ctx, configFor(stateDir))
+  const value = await tools[0].execute({ query: 'anything' }, makeExec(workspace))
+  const meta = tools[0].output.presentationMeta({ query: 'anything' }, value)
+  assert.equal(meta.recall.failed, 1, 'a failure should be counted, not silently dropped')
+})
+
+test('the usage projection is registered when the service is mounted', async (t) => {
+  const registered = []
+  const { ctx, tools, dispose } = makeContext({
+    services: { sessionProjections: { register: (unit) => registered.push(unit) } },
+  })
+  t.after(() => dispose())
+  apply(ctx, configFor('/tmp/dsh-recall-projection-test'))
+
+  assert.equal(tools.length, 1, 'the tool registers regardless')
+  assert.equal(registered.length, 1, 'exactly one projection unit')
+  assert.equal(registered[0].key, 'recallUsage', 'the key the client reads')
+  assert.equal(typeof registered[0].apply, 'function')
+  assert.equal(typeof registered[0].wire.view, 'function', 'the unit must be client-visible')
+  assert.equal(typeof registered[0].wire.viewSchema.parse, 'function')
+})
+
+test('a profile without projections still gets a working tool', async (t) => {
+  // The projection is an optional surface, not a dependency of retrieval: a
+  // composition that mounts no projection service must lose the reporting and
+  // nothing else.
+  const { ctx, tools, dispose } = makeContext()
+  t.after(() => dispose())
+  apply(ctx, configFor('/tmp/dsh-recall-no-projection'))
+  assert.equal(tools.length, 1)
+  assert.equal(tools[0].name, 'recall')
+})
+
+test('a projection that refuses to register is reported, not fatal', async (t) => {
+  const { ctx, tools, dispose } = makeContext({
+    services: {
+      sessionProjections: {
+        register: () => {
+          throw new Error('duplicate key')
+        },
+      },
+    },
+  })
+  t.after(() => dispose())
+  // The warning is logged rather than thrown: a conflicting unit must not take
+  // the whole plugin, and therefore retrieval, down with it.
+  assert.doesNotThrow(() => apply(ctx, configFor('/tmp/dsh-recall-bad-projection')))
+  assert.equal(tools.length, 1)
+})
+
+test('expansion is off by default and changes nothing', async (t) => {
+  const { tool, workspace, stub } = await setup(t)
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.ok(value.results.length > 0)
+  assert.equal(
+    stub.calls.filter((call) => call.url.endsWith('/api/generate')).length,
+    0,
+    'the local model must not be called unless the setting is on',
+  )
+})
+
+test('with expansion on and no model answering, the search still runs', async (t) => {
+  // The stub only answers /api/generate when a test supplies a response, so this
+  // is the wedged-endpoint case: expansion must degrade, not fail the search.
+  const { tool, workspace } = await setup(t, FILES, { expansionEnabled: true, expansionModel: 'local-small' })
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.ok(value.results.length > 0, 'a failed expansion must not fail the search')
+})
+
+test('expansion asks the model once and still returns results', async (t) => {
+  const { tool, workspace, stub } = await setup(
+    t,
+    FILES,
+    { expansionEnabled: true, expansionModel: 'local-small', expansionCount: 3 },
+    { generate: 'issueSession\nsession expiry check' },
+  )
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const value = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, value), [])
+  assert.ok(value.results.length > 0)
+  const generations = stub.calls.filter((call) => call.url.endsWith('/api/generate'))
+  assert.equal(generations.length, 1, 'one generation for the query, not one per variant')
+  assert.match(generations[0].body.prompt, /session expiry/)
+  assert.equal(generations[0].body.model, 'local-small', 'the configured expansion model is used')
+})
+
+test('re-ranking degrades to the fused order when the model has no opinion', async (t) => {
+  const { tool, workspace } = await setup(t, FILES, { rerankEnabled: true, rerankModel: 'local-small' })
+  await tool.execute({ action: 'index', run_in_background: false }, makeExec(workspace))
+  const plain = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  const reranked = await tool.execute({ query: 'session expiry' }, makeExec(workspace))
+  assert.deepEqual(schemaErrors(tool.output.schema, reranked), [])
+  // No usable scores means the ranking is untouched rather than emptied.
+  assert.deepEqual(
+    reranked.results.map((result) => result.path),
+    plain.results.map((result) => result.path),
+  )
+  assert.ok(reranked.results.length > 0, 'no opinion must not mean no results')
+})
diff --git a/test/projection.test.js b/test/projection.test.js
new file mode 100644
index 0000000..235c2ce
--- /dev/null
+++ b/test/projection.test.js
@@ -0,0 +1,116 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { usageProjection } from '../index.js'
+import { deriveUsage, emptyUsage, foldUsage, usageSummary } from '../lib/usage.js'
+
+/**
+ * The projection contract, tested against the framework's stated requirements
+ * rather than against the shape of my own code:
+ *
+ *   - the state schema validates the persisted checkpoint before it seeds a fold,
+ *     so a stale or corrupt row must be *rejected*, not coerced;
+ *   - `apply` must return the same reference for an event it does not own, or the
+ *     unit republishes on every step of every session;
+ *   - the view is compared by `Object.is`, so one state must yield one object.
+ */
+
+/** A folded state, as a conversation with a couple of searches would produce. */
+function foldedState() {
+  const value = {
+    action: 'search',
+    ok: true,
+    weak: false,
+    focus: { path: 'src/auth' },
+    results: [{ excerpt: 'x'.repeat(400) }, { excerpt: 'y'.repeat(200) }],
+    measure: { excerpts: 2, returnedBytes: 600, sourceBytes: 24_000, files: 2 },
+  }
+  const event = { type: 'tool/result', meta: deriveUsage({ action: 'search' }, value) }
+  return foldUsage(foldUsage(emptyUsage(), event), event)
+}
+
+test('the unit owns the key the client will read', () => {
+  assert.equal(usageProjection.key, 'recallUsage')
+  assert.equal(usageProjection.stateVersion, 1)
+  assert.ok(Number.isInteger(usageProjection.stateVersion) && usageProjection.stateVersion >= 0)
+})
+
+test('init produces the empty state, and it survives a round trip', () => {
+  const state = usageProjection.init()
+  assert.deepEqual(state, emptyUsage())
+  assert.deepEqual(usageProjection.stateSchema.parse(state), state)
+})
+
+test('the state schema accepts a folded state and preserves it', () => {
+  const state = foldedState()
+  assert.equal(state.searches, 2)
+  // Persisted as JSON and re-parsed on restore, so that round trip must hold.
+  const restored = usageProjection.stateSchema.parse(JSON.parse(JSON.stringify(state)))
+  assert.deepEqual(restored, state)
+})
+
+test('the state schema REJECTS a corrupt checkpoint rather than coercing it', () => {
+  // The service catches a parse failure and skips the row; coercing garbage
+  // would forward-apply nonsense into every later total instead.
+  for (const bad of [null, undefined, 42, 'state', {}, { searches: 'two' }, { ...emptyUsage(), searches: null }]) {
+    assert.equal(usageProjection.stateSchema.safeParse(bad).success, false, `accepted ${JSON.stringify(bad)}`)
+  }
+})
+
+test('apply returns the SAME reference for events the unit does not own', () => {
+  const state = foldedState()
+  assert.equal(usageProjection.apply(state, { type: 'user/message' }), state)
+  assert.equal(usageProjection.apply(state, { type: 'tool/result', meta: { other: 1 } }), state)
+  assert.equal(usageProjection.apply(state, { type: 'assistant/message' }), state)
+})
+
+test('apply folds an event the unit does own', () => {
+  const state = usageProjection.init()
+  const value = {
+    action: 'search',
+    ok: true,
+    results: [{ excerpt: 'abc' }],
+    measure: { excerpts: 1, returnedBytes: 3, sourceBytes: 900, files: 1 },
+  }
+  const event = { type: 'tool/result', meta: deriveUsage({ action: 'search' }, value) }
+  const next = usageProjection.apply(state, event)
+  assert.notEqual(next, state, 'a real event must produce a new state')
+  assert.equal(next.searches, 1)
+  assert.equal(next.sourceBytes, 900)
+})
+
+test('the view validates against its own schema', () => {
+  const state = foldedState()
+  const view = usageProjection.wire.view(state)
+  assert.deepEqual(usageProjection.wire.viewSchema.parse(view), view)
+})
+
+test('one state yields ONE view object, by reference', () => {
+  // The live drive compares the two latest views with Object.is; returning a
+  // fresh object per call would republish on every event that touched the state
+  // even when the numbers a surface shows had not moved.
+  const state = foldedState()
+  const first = usageProjection.wire.view(state)
+  const second = usageProjection.wire.view(state)
+  assert.equal(first, second)
+})
+
+test('a different state yields a different view', () => {
+  const one = usageProjection.wire.view(foldedState())
+  const two = usageProjection.wire.view(emptyUsage())
+  assert.notEqual(one, two)
+  assert.equal(one.searches, 2)
+  assert.equal(two.searches, 0)
+})
+
+test('the view carries the comparison and the compounding figure', () => {
+  const view = usageProjection.wire.view(foldedState())
+  assert.equal(view.searches, 2)
+  assert.equal(view.sourceBytes, 48_000)
+  assert.equal(view.returnedBytes, 1200)
+  assert.equal(view.avoidedBytes, 46_800)
+  // bytes/4 is an approximation and is labelled as one where it is displayed.
+  assert.equal(view.avoidedTokens, Math.round(46_800 / 4))
+  assert.ok(view.compression > 1)
+  assert.equal(view.avoidedUsd, usageSummary(foldedState()).avoidedUsd)
+})
diff --git a/test/rank.test.js b/test/rank.test.js
new file mode 100644
index 0000000..05303f9
--- /dev/null
+++ b/test/rank.test.js
@@ -0,0 +1,183 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { excerptOf, queryTerms, rankChunks, splitIdentifier } from '../lib/rank.js'
+import { hashEmbed } from './helpers.js'
+
+const DIMENSIONS = 128
+
+/** Build a scoring matrix from a list of chunks. */
+function makeMatrix(chunks) {
+  const vectors = new Float32Array(chunks.length * DIMENSIONS)
+  chunks.forEach((chunk, at) => {
+    vectors.set(hashEmbed(`${chunk.path} ${chunk.symbol ?? ''} ${chunk.text}`, DIMENSIONS), at * DIMENSIONS)
+  })
+  return {
+    vectors,
+    dimensions: DIMENSIONS,
+    rows: chunks.map((chunk, at) => ({
+      id: at + 1,
+      path: chunk.path,
+      startLine: chunk.startLine,
+      endLine: chunk.endLine,
+      ...(chunk.symbol === undefined ? {} : { symbol: chunk.symbol }),
+      text: chunk.text,
+    })),
+  }
+}
+
+test('splitIdentifier breaks camelCase and snake_case alike', () => {
+  assert.deepEqual(splitIdentifier('getUserById'), ['get', 'User', 'By', 'Id'])
+  assert.deepEqual(splitIdentifier('get_user_by_id'), ['get', 'user', 'by', 'id'])
+  assert.deepEqual(splitIdentifier('HTTPResponseParser'), ['HTTP', 'Response', 'Parser'])
+})
+
+test('queryTerms keeps identifier sub-words and drops stopwords', () => {
+  const terms = queryTerms('where is the getUserById function')
+  assert.ok(terms.includes('get'))
+  assert.ok(terms.includes('user'))
+  assert.ok(!terms.includes('the'), 'stopwords must not rank anything')
+})
+
+test('a named identifier wins even against a topically similar decoy', () => {
+  const matrix = makeMatrix([
+    {
+      path: 'src/services/auth/session.ts',
+      symbol: 'issueSession',
+      startLine: 1,
+      endLine: 10,
+      text: 'export function issueSession(userId) { return { userId, expiresAt: Date.now() } }',
+    },
+    {
+      path: 'src/services/auth/other.ts',
+      symbol: 'revokeSession',
+      startLine: 1,
+      endLine: 10,
+      text: 'export function revokeSession(record) { record.revoked = true; return record }',
+    },
+    { path: 'src/weather/forecast.ts', symbol: 'average', startLine: 1, endLine: 5, text: 'export function average(days) { return days.length }' },
+  ])
+  const query = 'issueSession'
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 3 })
+  assert.equal(ranked.results[0].path, 'src/services/auth/session.ts')
+  assert.equal(ranked.results[0].symbol, 'issueSession')
+})
+
+test('a behavioural query still finds the right file without naming it', () => {
+  const matrix = makeMatrix([
+    {
+      path: 'src/services/auth/session.ts',
+      symbol: 'issueSession',
+      startLine: 1,
+      endLine: 6,
+      text: 'export function issueSession(userId) { const expiresAt = Date.now() + ttl; return { userId, expiresAt } }',
+    },
+    { path: 'src/weather/forecast.ts', symbol: 'averageTemperature', startLine: 1, endLine: 6, text: 'export function averageTemperature(days) { return days.reduce(sum, 0) }' },
+  ])
+  const query = 'session expiry userId expiresAt'
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 2 })
+  assert.equal(ranked.results[0].path, 'src/services/auth/session.ts')
+})
+
+test('at most perFile chunks come from one file', () => {
+  const chunks = Array.from({ length: 6 }, (_, at) => ({
+    path: 'src/big.ts',
+    symbol: `fn_${at}`,
+    startLine: at * 10 + 1,
+    endLine: at * 10 + 9,
+    text: `export function fn_${at}(handler) { return handler(${at}) }`,
+  }))
+  chunks.push({ path: 'src/other.ts', symbol: 'fn_x', startLine: 1, endLine: 5, text: 'export function fn_x(handler) { return handler }' })
+  const matrix = makeMatrix(chunks)
+  const query = 'fn handler'
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 6, perFile: 2 })
+  const fromBig = ranked.results.filter((result) => result.path === 'src/big.ts')
+  assert.ok(fromBig.length <= 2, `expected at most 2 from one file, got ${fromBig.length}`)
+})
+
+test('excerptOf keeps the head and reports truncation', () => {
+  const text = Array.from({ length: 100 }, (_, at) => `line ${at}`).join('\n')
+  const short = excerptOf(text, 200)
+  assert.equal(short.truncated, false)
+  assert.equal(short.excerpt, text)
+  const long = excerptOf(text, 10)
+  assert.equal(long.truncated, true)
+  assert.equal(long.excerpt.split('\n').length, 10)
+  assert.equal(long.excerpt.split('\n')[0], 'line 0')
+})
+
+test('rankChunks handles an empty matrix without inventing results', () => {
+  const ranked = rankChunks({
+    matrix: { vectors: new Float32Array(0), rows: [], dimensions: 0 },
+    queryVector: new Float32Array(0),
+    query: 'anything',
+  })
+  assert.deepEqual(ranked.results, [])
+  assert.equal(ranked.vectorBest, 0)
+})
+
+test('ranking is deterministic for equal scores', () => {
+  const chunks = Array.from({ length: 4 }, (_, at) => ({
+    path: `src/f${at}.ts`,
+    startLine: 1,
+    endLine: 2,
+    text: 'export const same = 1',
+  }))
+  const matrix = makeMatrix(chunks)
+  const query = 'same'
+  const first = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 4 })
+  const second = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 4 })
+  assert.deepEqual(
+    first.results.map((result) => result.path),
+    second.results.map((result) => result.path),
+  )
+})
+test('a chunk that fits is returned whole rather than cut in half', () => {
+  // The default cap equals the chunk cap, so a chunk — already a semantic unit —
+  // is not truncated. Cutting below it is what forces a follow-up read.
+  const body = Array.from({ length: 60 }, (_, at) => `  const line_${at} = compute(${at})`).join('\n')
+  const text = `export function handler() {\n${body}\n}`
+  const matrix = makeMatrix([{ path: 'src/a.ts', symbol: 'handler', startLine: 1, endLine: 62, text }])
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed('handler', DIMENSIONS), query: 'handler', limit: 1 })
+  assert.equal(ranked.results[0].truncated, false, 'a 62-line chunk should arrive whole')
+  assert.equal(ranked.results[0].excerpt, text)
+})
+
+test('a per-excerpt cap still truncates, and says so', () => {
+  const text = Array.from({ length: 60 }, (_, at) => `line ${at}`).join('\n')
+  const matrix = makeMatrix([{ path: 'src/a.ts', startLine: 1, endLine: 60, text }])
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed('line', DIMENSIONS), query: 'line', limit: 1, excerptLines: 10 })
+  assert.equal(ranked.results[0].truncated, true)
+  assert.equal(ranked.results[0].excerpt.split('\n').length, 10)
+})
+
+test('the total line budget bounds the whole set, allocating by rank', () => {
+  const chunks = Array.from({ length: 6 }, (_, at) => ({
+    path: `src/f${at}.ts`,
+    symbol: `fn_${at}`,
+    startLine: 1,
+    endLine: 40,
+    text: Array.from({ length: 40 }, (_, line) => `fn_${at} line ${line} handler`).join('\n'),
+  }))
+  const matrix = makeMatrix(chunks)
+  const query = 'fn handler'
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed(query, DIMENSIONS), query, limit: 6, excerptLines: 40, totalLines: 90 })
+
+  const total = ranked.results.reduce((sum, result) => sum + result.excerpt.split('\n').length, 0)
+  assert.ok(total <= 90 + 40, `budget should bind, total was ${total}`)
+  assert.ok(ranked.results.length < 6, 'the budget should have stopped the set early')
+  assert.ok(ranked.results.length >= 1, 'at least one result must survive any budget')
+})
+
+test('at least one result is returned even with no budget at all', () => {
+  const chunks = Array.from({ length: 3 }, (_, at) => ({
+    path: `src/f${at}.ts`,
+    startLine: 1,
+    endLine: 30,
+    text: Array.from({ length: 30 }, (_, line) => `handler line ${line}`).join('\n'),
+  }))
+  const matrix = makeMatrix(chunks)
+  const ranked = rankChunks({ matrix, queryVector: hashEmbed('handler', DIMENSIONS), query: 'handler', limit: 3, totalLines: 0 })
+  assert.equal(ranked.results.length, 1, 'an empty budget must still answer with something')
+  assert.equal(ranked.results[0].excerpt.split('\n').length, 1, 'squeezed to the minimum, not dropped')
+})
diff --git a/test/rerank.test.js b/test/rerank.test.js
new file mode 100644
index 0000000..5d491db
--- /dev/null
+++ b/test/rerank.test.js
@@ -0,0 +1,118 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { fuseRankings } from '../lib/rank.js'
+import { createReranker, parseScores } from '../lib/rerank.js'
+
+/** A stub endpoint answering with a canned model response. */
+function stubFetch(response, options = {}) {
+  const { hang = false, status = 200 } = options
+  const calls = []
+  const impl = async (url, init) => {
+    calls.push({ url, body: JSON.parse(init.body) })
+    if (hang) {
+      return new Promise((_resolve, reject) => {
+        init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true })
+      })
+    }
+    return { ok: status === 200, status, json: async () => ({ response }) }
+  }
+  impl.calls = calls
+  return impl
+}
+
+const MODEL = { apiBase: 'http://stub:11434', model: 'small-model', timeoutMs: 2_000 }
+
+test('parseScores accepts the documented shape and a bare array', () => {
+  assert.deepEqual(parseScores('{"scores": [10, 4, 0]}'), [10, 4, 0])
+  assert.deepEqual(parseScores('Sure: [8, 2, 6]'), [8, 2, 6])
+  assert.deepEqual(parseScores('{"scores":[7]}'), [7])
+})
+
+test('parseScores returns undefined rather than guessing', () => {
+  assert.equal(parseScores('no numbers here'), undefined)
+  assert.equal(parseScores('{"scores": []}'), undefined)
+  assert.equal(parseScores(''), undefined)
+  assert.equal(parseScores(undefined), undefined)
+})
+
+test('an unusable response is no opinion, not a zero', async () => {
+  // The distinction the whole module rests on: returning zeros here would
+  // replace a good embedding ranking with nothing at all.
+  for (const fetchImpl of [
+    async () => {
+      throw new Error('ECONNREFUSED')
+    },
+    stubFetch('I think the first one is best.'),
+    stubFetch('{"scores": [10, 5]}'), // wrong length for 3 candidates
+    stubFetch('', { status: 500 }),
+  ]) {
+    assert.equal(await createReranker({ ...MODEL, fetchImpl }).score('q', ['a', 'b', 'c']), undefined)
+  }
+})
+
+test('a WEDGED endpoint yields no opinion, and does not hang', async () => {
+  const started = Date.now()
+  const scores = await createReranker({ ...MODEL, fetchImpl: stubFetch('', { hang: true }), timeoutMs: 120 }).score('q', ['a', 'b'])
+  assert.equal(scores, undefined)
+  assert.ok(Date.now() - started < 3_000, 'the deadline must bound the wait')
+})
+
+test('scores come back normalised and clamped, in candidate order', async () => {
+  const fetchImpl = stubFetch('{"scores": [10, 0, 5, 42, -3]}')
+  const scores = await createReranker({ ...MODEL, fetchImpl }).score('q', ['a', 'b', 'c', 'd', 'e'])
+  assert.deepEqual(scores, [1, 0, 0.5, 1, 0], 'out-of-range values are clamped, not trusted')
+})
+
+test('a non-finite timeout is clamped rather than read as no opinion', async () => {
+  const fetchImpl = stubFetch('{"scores": [9, 1]}')
+  const scores = await createReranker({ ...MODEL, fetchImpl, timeoutMs: Number.NaN }).score('q', ['a', 'b'])
+  assert.deepEqual(scores, [0.9, 0.1])
+})
+
+test('the prompt carries the query and every candidate', async () => {
+  const fetchImpl = stubFetch('{"scores": [1, 1]}')
+  await createReranker({ ...MODEL, fetchImpl }).score('occupancy detection', ['excerpt one', 'excerpt two'])
+  const prompt = fetchImpl.calls[0].body.prompt
+  assert.match(prompt, /occupancy detection/)
+  assert.match(prompt, /excerpt one/)
+  assert.match(prompt, /excerpt two/)
+})
+
+test('nothing to score is no opinion, and no request', async () => {
+  const fetchImpl = stubFetch('{"scores": []}')
+  const reranker = createReranker({ ...MODEL, fetchImpl })
+  assert.equal(await reranker.score('q', []), undefined)
+  assert.equal(await reranker.score('   ', ['a']), undefined)
+  assert.equal(fetchImpl.calls.length, 0)
+})
+
+test('caller cancellation yields no opinion without a request', async () => {
+  const controller = new AbortController()
+  controller.abort()
+  const fetchImpl = stubFetch('{"scores": [1]}')
+  assert.equal(await createReranker({ ...MODEL, fetchImpl }).score('q', ['a'], controller.signal), undefined)
+  assert.equal(fetchImpl.calls.length, 0)
+})
+
+test('fusing one ranking keeps its order', () => {
+  assert.deepEqual(fuseRankings([[3, 1, 2]]), [3, 1, 2])
+})
+
+test('a chunk several queries agree on outranks one that a single query liked', () => {
+  // Row 7 is second for both queries; row 1 is first for one and absent from the
+  // other. Agreement should win, which is the whole point of expansion.
+  const fused = fuseRankings([
+    [1, 7, 2],
+    [5, 7, 9],
+  ])
+  assert.equal(fused[0], 7)
+})
+
+test('fusion is empty for no rankings and stable for ties', () => {
+  assert.deepEqual(fuseRankings([]), [])
+  assert.deepEqual(fuseRankings([[], []]), [])
+  const once = fuseRankings([[2, 1, 3], [1, 2, 3]])
+  const twice = fuseRankings([[2, 1, 3], [1, 2, 3]])
+  assert.deepEqual(once, twice, 'the same input must give the same order')
+})
diff --git a/test/store.test.js b/test/store.test.js
new file mode 100644
index 0000000..2682daf
--- /dev/null
+++ b/test/store.test.js
@@ -0,0 +1,113 @@
+import { strict as assert } from 'node:assert'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { test } from 'node:test'
+
+import { RecallIndex } from '../lib/store.js'
+import { makeStateDir } from './helpers.js'
+
+const IDENTITY = { model: 'test-model', dimensions: 4, apiBase: 'http://stub' }
+
+/** A chunk with a hand-written vector, so assertions are exact. */
+function chunk(startLine, vector, symbol) {
+  return {
+    startLine,
+    endLine: startLine + 2,
+    ...(symbol === undefined ? {} : { symbol }),
+    text: `line ${startLine}`,
+    vec: Float32Array.from(vector),
+  }
+}
+
+async function withIndex(t, work) {
+  const dir = await makeStateDir()
+  const index = new RecallIndex(join(dir, 'index.sqlite'))
+  t.after(async () => {
+    index.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+  index.open(IDENTITY)
+  return work(index)
+}
+
+test('replaceFile round-trips chunks and their vectors', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'hash-a', 100, [chunk(1, [1, 0, 0, 0], 'alpha'), chunk(10, [0, 1, 0, 0], 'beta')])
+    const stats = index.stats()
+    assert.equal(stats.files, 1)
+    assert.equal(stats.chunks, 2)
+
+    const matrix = index.matrix()
+    assert.equal(matrix.dimensions, 4)
+    assert.equal(matrix.rows.length, 2)
+    assert.deepEqual(Array.from(matrix.vectors.slice(0, 4)), [1, 0, 0, 0])
+    assert.equal(matrix.rows[0].symbol, 'alpha')
+    assert.equal(matrix.rows[0].path, 'a.ts')
+  })
+})
+
+test('replacing a file drops its previous chunks rather than appending', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'hash-1', 10, [chunk(1, [1, 0, 0, 0])])
+    index.replaceFile('a.ts', 'hash-2', 20, [chunk(1, [0, 1, 0, 0]), chunk(5, [0, 0, 1, 0])])
+    assert.equal(index.stats().chunks, 2)
+    assert.equal(index.fileHashes().get('a.ts'), 'hash-2')
+  })
+})
+
+test('prune forgets files that disappeared from disk', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'ha', 1, [chunk(1, [1, 0, 0, 0])])
+    index.replaceFile('b.ts', 'hb', 1, [chunk(1, [0, 1, 0, 0])])
+    assert.equal(index.prune(['a.ts']), 1)
+    assert.equal(index.stats().files, 1)
+    assert.equal(index.matrix().rows[0].path, 'b.ts')
+    assert.equal(index.prune([]), 0)
+  })
+})
+
+test('changing the embedding model discards the index instead of mixing spaces', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'ha', 1, [chunk(1, [1, 0, 0, 0])])
+    assert.equal(index.stats().chunks, 1)
+
+    const outcome = index.recheck({ model: 'other-model', dimensions: 4, apiBase: 'http://stub' })
+    assert.match(outcome.discarded, /embedding model changed/)
+    assert.equal(index.stats().chunks, 0)
+    assert.equal(index.stats().files, 0)
+  })
+})
+
+test('changing the embedding width discards the index', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'ha', 1, [chunk(1, [1, 0, 0, 0])])
+    const outcome = index.recheck({ model: 'test-model', dimensions: 8, apiBase: 'http://stub' })
+    assert.match(outcome.discarded, /embedding width changed/)
+    assert.equal(index.stats().chunks, 0)
+  })
+})
+
+test('recheck is a no-op when nothing about the identity moved', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'ha', 1, [chunk(1, [1, 0, 0, 0])])
+    assert.deepEqual(index.recheck(IDENTITY), {})
+    assert.equal(index.stats().chunks, 1)
+  })
+})
+
+test('a write invalidates the cached matrix', async (t) => {
+  await withIndex(t, (index) => {
+    index.replaceFile('a.ts', 'ha', 1, [chunk(1, [1, 0, 0, 0])])
+    assert.equal(index.matrix().rows.length, 1)
+    index.replaceFile('b.ts', 'hb', 1, [chunk(1, [0, 1, 0, 0])])
+    assert.equal(index.matrix().rows.length, 2, 'the matrix must not serve a stale cache')
+  })
+})
+
+test('an index with no chunks reports a zero-width matrix', async (t) => {
+  await withIndex(t, (index) => {
+    const matrix = index.matrix()
+    assert.equal(matrix.rows.length, 0)
+    assert.equal(matrix.dimensions, 0)
+  })
+})
diff --git a/test/usage.test.js b/test/usage.test.js
new file mode 100644
index 0000000..fb40e3f
--- /dev/null
+++ b/test/usage.test.js
@@ -0,0 +1,139 @@
+import { strict as assert } from 'node:assert'
+import { test } from 'node:test'
+
+import { deriveUsage, emptyUsage, foldUsage, usageSummary } from '../lib/usage.js'
+
+/** A tool result shaped like the ones the tool actually returns. */
+function searchValue(overrides = {}) {
+  return {
+    action: 'search',
+    ok: true,
+    focus: { path: '.', source: 'workspace' },
+    weak: false,
+    results: [
+      { path: 'src/auth/session.ts', excerpt: 'x'.repeat(1000), similarity: 0.6 },
+      { path: 'src/weather/forecast.ts', excerpt: 'y'.repeat(500), similarity: 0.4 },
+    ],
+    measure: { excerpts: 2, returnedBytes: 1500, sourceBytes: 60_000, files: 2 },
+    ...overrides,
+  }
+}
+
+/** Wrap a record the way the harness wraps the tool's metadata. */
+function asEvent(meta) {
+  return { type: 'tool/result', turn: 1, step: 1, message: {}, meta }
+}
+
+test('emptyUsage is a plain zeroed record', () => {
+  const state = emptyUsage()
+  assert.equal(state.searches, 0)
+  assert.equal(state.sourceBytes, 0)
+  // The projection stores this as plain JSON, so nothing exotic may appear.
+  assert.deepEqual(JSON.parse(JSON.stringify(state)), state)
+})
+
+test('deriveUsage records a search without carrying any content', () => {
+  const { recall } = deriveUsage({ action: 'search' }, searchValue())
+  assert.equal(recall.action, 'search')
+  assert.equal(recall.excerpts, 2)
+  assert.equal(recall.returnedBytes, 1500)
+  assert.equal(recall.sourceBytes, 60_000)
+  assert.equal(recall.files, 2)
+  assert.equal(recall.focus, '.')
+  // The whole point of the record is that it is tiny: no excerpts, no query.
+  const serialised = JSON.stringify(recall)
+  assert.ok(!serialised.includes('x'.repeat(50)), 'excerpt text must not reach the log')
+  assert.ok(serialised.length < 300, `record was ${serialised.length} bytes`)
+})
+
+test('deriveUsage marks a failure and a weak result', () => {
+  assert.equal(deriveUsage({ action: 'search' }, { action: 'search', ok: false }).recall.failed, 1)
+  assert.equal(deriveUsage({ action: 'search' }, searchValue({ weak: true })).recall.weak, 1)
+})
+
+test('deriveUsage records an index without pretending it returned excerpts', () => {
+  const { recall } = deriveUsage({ action: 'index' }, { action: 'index', ok: true, index: { embedded: 4 } })
+  assert.equal(recall.action, 'index')
+  assert.equal(recall.embedded, 4)
+  assert.equal(recall.excerpts, undefined)
+})
+
+test('foldUsage returns the SAME reference for events it does not care about', () => {
+  const state = emptyUsage()
+  // A fresh object here would republish the projection on every step of every
+  // session, which is why the framework states this requirement explicitly.
+  assert.equal(foldUsage(state, { type: 'user/message' }), state)
+  assert.equal(foldUsage(state, { type: 'tool/result', meta: {} }), state)
+  assert.equal(foldUsage(state, { type: 'tool/result' }), state)
+  assert.equal(foldUsage(state, { type: 'tool/result', meta: { other: 1 } }), state)
+  assert.equal(foldUsage(state, { type: 'tool/result', meta: { recall: null } }), state)
+})
+
+test('foldUsage accumulates one conversation', () => {
+  let state = emptyUsage()
+  state = foldUsage(state, asEvent(deriveUsage({}, searchValue())))
+  state = foldUsage(state, asEvent(deriveUsage({}, searchValue())))
+  state = foldUsage(state, asEvent(deriveUsage({ action: 'index' }, { action: 'index', index: { embedded: 3 } })))
+
+  assert.equal(state.searches, 2)
+  assert.equal(state.indexes, 1)
+  assert.equal(state.excerpts, 4)
+  assert.equal(state.returnedBytes, 3000)
+  assert.equal(state.sourceBytes, 120_000)
+  assert.equal(state.files, 4)
+})
+
+test('a fold and a direct derive agree on the same numbers', () => {
+  // Guards against the two paths drifting: whatever the tool writes must be
+  // what the running total adds up to.
+  const value = searchValue()
+  const folded = foldUsage(emptyUsage(), asEvent(deriveUsage({}, value)))
+  const summary = usageSummary(folded)
+  assert.equal(summary.searches, 1)
+  assert.equal(summary.sourceBytes, value.measure.sourceBytes)
+  assert.equal(summary.returnedBytes, value.measure.returnedBytes)
+})
+
+test('usageSummary reports the comparison, and calls it an upper bound', () => {
+  const state = foldUsage(emptyUsage(), asEvent(deriveUsage({}, searchValue())))
+  const summary = usageSummary(state)
+  assert.equal(summary.avoidedBytes, 58_500)
+  assert.equal(summary.avoidedTokens, Math.round(58_500 / 4))
+  assert.equal(summary.compression, 40)
+  // The dollars are real rather than rounded to nothing: the direct saving is
+  // small, which is exactly why the surface must not lead with it.
+  assert.ok(summary.avoidedUsd > 0)
+})
+
+test('each step re-reads the avoided context, so the fold compounds it', () => {
+  let state = foldUsage(emptyUsage(), asEvent(deriveUsage({}, searchValue())))
+  const after = usageSummary(state)
+  assert.equal(after.rereadTokens, 0, 'nothing has been re-read yet')
+
+  // Every step after the search re-reads what the conversation is carrying.
+  for (let step = 0; step < 100; step += 1) state = foldUsage(state, { type: 'step/start' })
+  const later = usageSummary(state)
+  assert.equal(later.rereadTokens, after.avoidedTokens * 100)
+  assert.ok(later.avoidedUsd > after.avoidedUsd)
+  assert.equal(later.avoidedUsd, Number((((after.avoidedTokens + later.rereadTokens) / 1e6) * 0.007).toFixed(4)))
+})
+
+test('a step before anything was avoided adds nothing', () => {
+  const state = emptyUsage()
+  assert.equal(foldUsage(state, { type: 'step/start' }), state, 'and keeps the same reference')
+})
+
+test('usageSummary survives a conversation with no calls', () => {
+  const summary = usageSummary(emptyUsage())
+  assert.equal(summary.searches, 0)
+  assert.equal(summary.avoidedTokens, 0)
+  assert.equal(summary.compression, 0, 'no division by zero')
+  assert.equal(summary.avoidedUsd, 0)
+})
+
+test('an excerpt larger than its source cannot produce a negative saving', () => {
+  const state = foldUsage(emptyUsage(), asEvent({
+    recall: { action: 'search', excerpts: 1, returnedBytes: 900, sourceBytes: 100 },
+  }))
+  assert.equal(usageSummary(state).avoidedBytes, 0)
+})
diff --git a/test/walk.test.js b/test/walk.test.js
new file mode 100644
index 0000000..3a7c917
--- /dev/null
+++ b/test/walk.test.js
@@ -0,0 +1,104 @@
+import { strict as assert } from 'node:assert'
+import { mkdtemp, mkdir, symlink, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test } from 'node:test'
+
+import { DEFAULT_EXTENSIONS, extensionOf, globToRegExp, listCodeFiles, matchesAny } from '../lib/walk.js'
+
+test('globToRegExp anchors and handles star and double-star', () => {
+  assert.equal(globToRegExp('src/*.ts').test('src/a.ts'), true)
+  assert.equal(globToRegExp('src/*.ts').test('src/nested/a.ts'), false)
+  assert.equal(globToRegExp('**/*.ts').test('a/b/c.ts'), true)
+  assert.equal(globToRegExp('**/*.ts').test('c.ts'), true)
+  assert.equal(globToRegExp('src/**').test('src/a/b/c.ts'), true)
+  assert.equal(globToRegExp('dist/').test('dist/a/b.js'), true)
+  assert.equal(globToRegExp('src/a?.ts').test('src/ab.ts'), true)
+  assert.equal(globToRegExp('src/a?.ts').test('src/abc.ts'), false)
+  // Dots must be literal, not wildcards.
+  assert.equal(globToRegExp('a.ts').test('axts'), false)
+})
+
+test('matchesAny ignores empty patterns', () => {
+  assert.equal(matchesAny('a/b.ts', ['']), false)
+  assert.equal(matchesAny('a/b.ts', ['', 'a/*.ts']), true)
+})
+
+test('extensionOf lowercases and rejects dotfiles', () => {
+  assert.equal(extensionOf('a/B.TS'), 'ts')
+  assert.equal(extensionOf('.gitignore'), '')
+  assert.equal(extensionOf('Makefile'), '')
+})
+
+test('listCodeFiles returns a deterministic sorted list of code files only', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-walk-'))
+  try {
+    await mkdir(join(root, 'src', 'nested'), { recursive: true })
+    await mkdir(join(root, 'node_modules', 'dep'), { recursive: true })
+    await writeFile(join(root, 'src', 'b.ts'), 'export const b = 1\n')
+    await writeFile(join(root, 'src', 'a.ts'), 'export const a = 1\n')
+    await writeFile(join(root, 'src', 'nested', 'c.py'), 'c = 1\n')
+    await writeFile(join(root, 'README.md'), '# not code\n')
+    await writeFile(join(root, 'node_modules', 'dep', 'index.js'), 'module.exports = 1\n')
+
+    const { files } = await listCodeFiles(root)
+    assert.deepEqual(
+      files.map((file) => file.path),
+      ['src/a.ts', 'src/b.ts', 'src/nested/c.py'],
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('listCodeFiles honours an extension filter and an exclude glob', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-walk-'))
+  try {
+    await mkdir(join(root, 'src', 'generated'), { recursive: true })
+    await writeFile(join(root, 'src', 'a.ts'), 'a\n')
+    await writeFile(join(root, 'src', 'generated', 'b.ts'), 'b\n')
+    await writeFile(join(root, 'src', 'c.py'), 'c\n')
+
+    const onlyTs = await listCodeFiles(root, { extensions: ['ts'] })
+    assert.deepEqual(onlyTs.files.map((file) => file.path), ['src/a.ts', 'src/generated/b.ts'])
+
+    const excluded = await listCodeFiles(root, { exclude: ['src/generated/'] })
+    assert.deepEqual(excluded.files.map((file) => file.path), ['src/a.ts', 'src/c.py'])
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('listCodeFiles reports truncation instead of silently dropping files', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-walk-'))
+  try {
+    for (let at = 0; at < 5; at += 1) await writeFile(join(root, `f${at}.ts`), `${at}\n`)
+    const { files, truncated } = await listCodeFiles(root, { maxFiles: 2 })
+    assert.equal(files.length, 2)
+    assert.equal(truncated, true)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('listCodeFiles does not follow symlinks', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'recall-walk-'))
+  const outside = await mkdtemp(join(tmpdir(), 'recall-outside-'))
+  try {
+    await writeFile(join(outside, 'secret.ts'), 'export const secret = 1\n')
+    await writeFile(join(root, 'real.ts'), 'export const real = 1\n')
+    await symlink(outside, join(root, 'linked'), 'dir')
+
+    const { files } = await listCodeFiles(root)
+    assert.deepEqual(files.map((file) => file.path), ['real.ts'])
+  } finally {
+    await rm(root, { recursive: true, force: true })
+    await rm(outside, { recursive: true, force: true })
+  }
+})
+
+test('the default extension set is code, not prose', () => {
+  assert.ok(DEFAULT_EXTENSIONS.includes('ts'))
+  assert.ok(DEFAULT_EXTENSIONS.includes('py'))
+  assert.ok(!DEFAULT_EXTENSIONS.includes('md'))
+})