quilltap 4.10.0-dev.18 → 4.10.0-dev.183

package/README.md

@@ -100,15 +100,19 @@ quilltap instances default Friday                        # Make it the fall-thro
 quilltap instances rename Friday Weekday                 # Rename, preserving the stored passphrase
 quilltap instances remove Friday                         # Unregister
 quilltap instances restore-key Friday                    # Rebuild a lost or passphrase-locked .dbkey
+quilltap instances default --clear                       # Revert to the OS platform default
+quilltap instances list --json                           # The registry as JSON, for scripts
 ```
 
-If an instance's `quilltap.dbkey` goes missing — or its passphrase does — `instances restore-key` rebuilds it. The file only *wraps* the pepper; the pepper itself is the database key, so an operator who kept the one printed at first-run setup can get back in. The pepper is read from `ENCRYPTION_MASTER_PEPPER` or prompted for hidden, never passed as a flag, and it is proved against the encrypted databases on disk before anything is written. Run it with the server down — the command refuses while the instance lock is held. Flags: `--passphrase <pass>` / `--no-passphrase` (the new wrapping), `-d, --data-dir <path>`, `--force`, `-y, --yes`.
+If an instance's `quilltap.dbkey` goes missing — or its passphrase does — `instances restore-key` rebuilds it. The file only *wraps* the pepper; the pepper itself is the database key, so an operator who kept the one printed at first-run setup can get back in. The pepper is read from `ENCRYPTION_MASTER_PEPPER` or prompted for hidden, never passed as a flag, and it is proved against the encrypted databases on disk before anything is written. Run it with the server down — the command refuses while the instance lock is held. Flags: `--passphrase <pass>` / `--no-passphrase` (the new wrapping), `-d, --data-dir <path>`, `--force` (proceed when there is no encrypted database to prove against — a fresh or still-plaintext instance), `-y, --yes`. An existing key file is backed up to `quilltap.dbkey.bak-<timestamp>` first, and a registered instance's stored passphrase is updated to match.
 
-Every subcommand then accepts `--instance <name>` in place of `--data-dir`. The registry lives at `<app-support>/Quilltap/instances.json` (mode 0600; e.g. `~/Library/Application Support/Quilltap/instances.json` on macOS). **Resolution precedence:** `--data-dir` > `--instance` > registered default > `QUILLTAP_DATA_DIR` > the OS platform default. Pass the **instance root** (e.g. `~/iCloud/Quilltap/Friday`), not its `data/` subdirectory.
+**It does not re-encrypt character archive bundles.** Those are keyed on the *passphrase*, not the pepper; only the server's Change Passphrase card rewrites them. Bundles made under a passphrase you have just replaced still want the old one.
+
+Every subcommand then accepts `--instance <name>` in place of `--data-dir`. The registry lives at `<app-support>/Quilltap/instances.json` (mode 0600; e.g. `~/Library/Application Support/Quilltap/instances.json` on macOS). **Resolution precedence:** `--data-dir` > `--instance` > registered default > `QUILLTAP_DATA_DIR` > the OS platform default. Pass the **instance root** (e.g. `~/iCloud/Quilltap/Friday`), not its `data/` subdirectory — the CLI appends `data/quilltap.db` itself. `instances list --json` emits the registry (`name`, `path`, `hasPassphrase`, `isDefault`) for scripting.
 
 ## Database Tool
 
-The encrypted SQLite databases (main, LLM logs, mount index) can be queried directly via `quilltap db`. There are two modes: high-level subcommands that auto-pick the right database and resolve characters/chats/projects by name, and a low-level path for arbitrary SQL.
+The encrypted SQLite databases (main, LLM logs, mount index) can be queried directly via `quilltap db`. They are SQLCipher-encrypted, so the stock `sqlite3` binary **cannot** open them — this is the way in. There are two modes: high-level subcommands that auto-pick the right database and resolve characters/chats/projects by name, and a low-level path for arbitrary SQL.
 
 ### Subcommands
 
@@ -131,10 +135,31 @@ quilltap db logs --tail 20                  # Recent LLM logs
 
 quilltap db message <id>                    # Full content of one message
 quilltap db log <id> [--field request|response|both]
-quilltap db memories --character Friday [--about Amy] [--source AUTO]
+quilltap db memories --character Friday [--about Amy] [--source AUTO] [--tier hot|cold]
 quilltap db characters status               # Per-character vault readiness (--id, --diverged, --blocked)
 ```
 
+SQLite columns are **camelCase**, mirroring the Zod/TypeScript types — `createdAt`, `updatedAt`, `chatType`, `messageCount`, `projectId`, *not* `created_at`. When in doubt, run `quilltap db schema <table>`.
+
+### Character Archive
+
+Archiving prunes a character down to a tombstone and packs everything else into an encrypted `ARCHIVE` bundle in the file library; rehydrating puts it all back at its original ids.
+
+```bash
+quilltap db characters archives                     # Archived characters + the bundles on the shelf
+quilltap db characters archive Ariadne --write      # Archive her (server must be running)
+quilltap db characters rehydrate Ariadne --write    # Wake her again
+quilltap db characters export Ariadne --out /tmp    # Plaintext .qtap, archived or live
+```
+
+`archives` is read-only, and flags **loose** bundles — survivors of a "keep archived bundles" wipe, which are importable but not rehydratable.
+
+`archive` and `rehydrate` run **through the running server's API** (`--port`, default 3000), because the export pipeline and the unlocked passphrase live only in the server process; the server, not the CLI, holds the instance lock for the duration. `--write` is still required as the explicit opt-in. A rehydrate restores the pruned material at its original ids (skip-if-present), clears the tombstone, and queues re-embedding; the bundle stays in the file library afterwards as a spare copy. On failure — wrong-era passphrase, missing bundle, import refusal — the character stays archived and re-running is safe.
+
+`export` writes a **plaintext** `.qtap` and takes no `--write`. For an **archived** character it decrypts the bundle straight off the disk, offline (it tries the internal no-passphrase key, then `QUILLTAP_DB_PASSPHRASE`, then prompts) — the only way to reach packed-away mail, photographs, and summaries without rehydrating. For a **live** character it runs the server's export pipeline, so the server must be up.
+
+**Pre-emptive, not recovery:** exporting an archive needs an instance that can still decrypt it. It is no help to someone holding only a restored backup and a forgotten passphrase — which is also why changing an instance's passphrase rewrites every archive bundle. A bundle reported left behind by a partial rewrite still wants the old one.
+
 ### Maintenance and Snapshots
 
 ```bash
@@ -149,7 +174,7 @@ quilltap db integrity                       # cipher_integrity_check + integrity
 quilltap db integrity llm-logs              # one DB; exit 0 ok, 1 issues, 2 open failure
 ```
 
-`backup` and `integrity` are safe to run while the server is up; `optimize` refuses while a live lock is held. Backups default to `<dataDir>/backups/<timestamp>/` and inherit the source's encryption key transparently.
+`backup` and `integrity` are safe to run while the server is up; `optimize` refuses while a live lock is held (see [Locking](#locking)). Backups default to `<dataDir>/backups/<timestamp>/` and inherit the source's encryption key transparently.
 
 Most subcommands accept `--json` (for piping) and `--limit N`. Names are case-insensitive; aliases are searched alongside character names. Ambiguous matches print all candidates and exit non-zero.
 
@@ -166,10 +191,39 @@ quilltap db --llm-logs --tables                     # Target the LLM logs DB
 quilltap db --mount-points --tables                 # Target the mount index DB
 ```
 
-The database is opened **read-only by default**. Add `--write` to make changes: it opens the database read-write, **claims the instance lock** (`<dataDir>/quilltap.lock`) for the duration, and releases it on exit. It **refuses — with no override — if a running server or another instance holds the lock**, so stop the server first. `--repl` is read-only unless combined with `--write`. Attempting a write without `--write` fails with a hint to re-run with the flag.
+The database is opened **read-only by default**. Add `--write` to make changes: it opens the database read-write, **claims the instance lock** (`<dataDir>/quilltap.lock`) for the duration, and releases it on exit. It **refuses — with no override — if a running server or another instance holds the lock**, so stop the server first. `--repl` is read-only unless combined with `--write`. Attempting a write without `--write` fails with a hint to re-run with the flag. What "held" means, and how to tell a live lock from a stale one, is [below](#locking).
+
+Compressed text columns (`chat_messages.content`, `llm_logs.request` / `response` and friends) are stored as BLOBs. A raw query's output decodes them for display, so `SELECT content …` prints text. Inside SQL — `WHERE`, `LIKE`, `substr`, `json_extract` — wrap the column in `qt_text()` to work on the text: `SELECT json_extract(qt_text(response), '$.error') …`.
 
 In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 
+## Locking
+
+Everything that writes to an instance claims `<dataDir>/quilltap.lock` — the same lockfile the server itself uses — for the duration, and releases it on exit. That is `db --write` (including `db --repl --write`), `db optimize`, `maintenance run`, and `instances restore-key`. All four **refuse while the lock is held**: stop the server first. Read-only work — plain `db`, the `docs` read verbs, `memories`, `logs`, `migrations`, `maintenance status`, `db backup`, `db integrity` — never touches the lock and is safe alongside a running instance.
+
+### The five-minute heartbeat window
+
+A lock counts as held until its heartbeat is **five minutes** stale, whether or not the process that set it is still alive. Freshness is the fallback for every environment, not just containers: a PID check is not reliable everywhere, and cleaning a *live* instance's lock is much the worse failure.
+
+So for up to five minutes after stopping the server, `--write`, `optimize`, `maintenance run`, `restore-key`, and `--lock-clean` all still refuse. That is correct behaviour, not a stale lock. Wait it out; the next startup reclaims the lock regardless.
+
+```bash
+quilltap db --lock-status      # Who holds it, and how old the heartbeat is
+quilltap db --lock-clean       # Remove a lock whose heartbeat has gone stale
+```
+
+`--lock-status` shows the heartbeat age, which is the tell. `--lock-clean` says so explicitly rather than muttering about liveness, because that arm is only reached once the PID check has come back dead:
+
+```
+Lock heartbeat is still fresh (82s ago). Cannot clean.
+A lock counts as held until its heartbeat is 5 minutes stale, even if its process has gone.
+Wait it out, or use --lock-override to force.
+```
+
+When a live process really does hold the lock, it refuses with "Lock is held by a live Quilltap process" instead.
+
+**`--lock-override` exists and is almost never the right answer** — it defeats the protection the lock provides. Reach for `--lock-status` first.
+
 ## Document Stores (Scriptorium)
 
 `quilltap docs` exposes the document-store machinery from the command line. Read-only verbs open the mount-index DB directly and work without the server; write and pipeline verbs talk to the running server via `/api/v1/mount-points/[id]`.
@@ -178,8 +232,10 @@ In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 # Read
 quilltap docs list                              # All mounts
 quilltap docs show <mount>                      # One mount, with counts
+quilltap docs files <mount> [--folder <path>]   # Flat file list for a mount
 quilltap docs ls <mount> [path] [--links]       # POSIX-flavoured listing (alias: dir)
-quilltap docs tree <mount> [path]               # ASCII tree of a folder hierarchy (--depth, --max-nodes)
+quilltap docs ls <mount> [path] -R --sort time -r  # Recursive, grouped by folder, sorted by time and reversed
+quilltap docs tree <mount> [path]               # ASCII tree of a folder hierarchy (--depth, --max-nodes, --long)
 quilltap docs read [--rendered] <mount> <path>  # File contents → stdout
 quilltap docs export <mount> <outputDir>        # Mount → directory
 quilltap docs find <pattern>                    # Substring match on file names (--mount, --ext, --type, --limit)
@@ -203,7 +259,26 @@ quilltap docs rmdir <mount> <path>                            # Delete an empty
 quilltap docs mvdir <mount> <fromPath> <toPath>               # Rename/move a folder (server-required)
 ```
 
-Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous names print candidates and exit non-zero. `--json` is supported by every verb; `reindex`, `embed`, `link`, `rmdir`, and `mvdir` refuse to run without a reachable server.
+`ls` flags: `--recursive` / `-R` lists every file below the path, grouped by folder; `--sort name|time|size|links` (default `name`) with `--reverse` / `-r` to flip it; `--links` lists the other mount/path entries under each file that has more than one hard link. `tree` takes `--depth N` (default 20), `--max-nodes N` (default 1000) and `--long`, which is accepted but reserved — it does not yet add columns.
+
+Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous names print candidates and exit non-zero. `--json` is supported by every verb; `reindex`, `embed`, `link`, `rmdir`, and `mvdir` refuse to run without a reachable server. `grep --semantic` goes through `POST /api/v1/mount-points?action=semantic-search`, because the embedding provider lives in the server; it defaults to `--top 20`, `--threshold 0.5`, `--port 3000`.
+
+### Addressing documents with `qtap://` URIs
+
+Anywhere a verb takes a positional `<mount> <relativePath>` pair — `read`, `write`, `delete`, `mkdir`, `ls`/`dir`, `tree`, `files`, `move`, `copy`, `link`, `rmdir`, `mvdir` — you may pass a single `qtap://…` URI in its place:
+
+```bash
+quilltap docs read qtap://notes/today.md
+quilltap docs move qtap://drafts/foo.md qtap://notes/2026/foo.md
+quilltap docs grep --mount qtap://notes/ "TODO"
+quilltap docs find --uri Manifesto
+```
+
+The URI authority is matched name-first, UUID as fallback — the same rule as a bare `<mount>` (`qtap://<store name>/…` or `qtap://<uuid>/…`). Two-target verbs (`move` / `copy` / `link` / `mvdir`) take either two `qtap://` URIs or the four legacy positionals; `find` and `grep` take one via `--mount`.
+
+**CLI limitation:** the CLI addresses document stores only. `qtap://self/…` needs a character context, and there is none at a shell prompt, so it is rejected with guidance; `qtap://project/…` and `qtap://general/…` are likewise not CLI-addressable — pass a store name or UUID instead.
+
+**Emitting URIs:** `--json` output for `find`, `grep`, `ls`, `files`, and `tree` carries a `uri` field on every row or node. `--uri` switches the text output of `find`, `grep`, and `files` to show the canonical `qtap://` URI as the locator (name form, UUID when the store name is ambiguous).
 
 ### `--base64` flag
 
@@ -213,28 +288,77 @@ Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous na
 
 ### `link`, `rmdir`, `mvdir`
 
+**`link` vs `copy`:** `docs link` makes two addresses into one document — it shares the content row *and* enrols both link rows in a `linkGroupId`, so a later write through either path repoints both and re-chunks the sibling. `docs copy` produces an independent document that merely shares a deduplicated content row until the first write. The `links` column in `ls` counts group members, not rows that happen to share identical bytes.
+
 `link` calls `POST /api/v1/mount-points/{srcMountId}?action=link-file` with `{sourcePath, destMountPointId, destPath}`. Creates a true hard link with no byte copy; the server reports back a `strategy` field. Errors: `DEST_EXISTS` (exit 2), `UNSUPPORTED` (cross-storage or cross-device), `SOURCE_NOT_FOUND`.
 
 `rmdir` calls `POST /api/v1/mount-points/{mountId}?action=delete-folder` with `{path}`. Fails with a clear message if the folder is not empty (`NOT_EMPTY` / `CONFLICT`).
 
 `mvdir` calls `POST /api/v1/mount-points/{mountId}?action=move-folder` with `{fromPath, toPath}`. Fails with exit 2 if the destination already exists (`DEST_EXISTS`).
 
+### Docker binds
+
+`quilltap docs docker-mounts` reports the bind mounts an instance's filesystem and Obsidian stores need in order to be reachable inside a container. Binds are **path-identical** (`-v /host/vault:/host/vault`), so the `basePath` recorded in the database resolves the same inside and out. Stores sharing a path collapse to a single bind, paths nested inside another bind are dropped, and a path that does not exist is **skipped** rather than handed to Docker to fabricate as an empty directory. It warns about macOS paths outside Docker Desktop's default shares and about a Linux uid mismatch, and refuses on Windows, where path-identical binds are not possible. `--format args` puts only the flags on stdout and all advice on stderr, which is what makes it pipeable into a `docker run`.
+
+## Sync a Store to a Directory
+
+`quilltap sync <store|qtap://store/> <path>` mirrors a **database-backed** document store and a directory on disk in both directions. Edit a file in your own editor and the next run carries it into the store; edit it in the Scriptorium and the next run carries it out.
+
+```bash
+quilltap sync Lore ~/Documents/lore --dry-run   # plan only
+quilltap sync Lore ~/Documents/lore             # apply
+quilltap sync Lore ~/Documents/lore --prefer disk
+```
+
+```text
+--dry-run             Plan and print; change nothing on either side
+--direction <which>   both (default), to-disk, or to-store
+--prefer <which>      newer (default), store, or disk — resolves conflicts
+--no-delete           Never propagate a deletion
+--no-manifest         Ignore .quilltap-sync.json (first-run rules every time)
+--json                Machine-readable plan and results
+-p, --port <n>        Server port (default 3000)
+-i, -d, --passphrase  The usual instance plumbing (used only to resolve <store>)
+```
+
+Compares by SHA-256 first and modification time second, so equal bytes with unequal clocks are re-stamped rather than re-copied. The side that changed wins; when both changed since the last run it is a `conflict` and nothing happens. After a content action both sides carry the winner's `lastModified` and the **older** of the two `createdAt`s. Deletions propagate only when `.quilltap-sync.json` — a manifest the verb keeps in the directory — proves the entry was there at the last run; on a first run an entry present on one side is created on the other, never deleted.
+
+Files and folders whose names begin with a dot are **invisible in both directions**, the manifest being the one exception. A binary's description travels as `<file>.description.md` beside it. Bytes are preserved verbatim: a `.png` pushed from disk stays a `.png`, unlike a Scriptorium upload. Chunks and embedding vectors are never touched by the sync — the store's own post-write hooks re-index.
+
+Exit codes: `0` clean, `1` error or failed action, `2` unresolved conflict; `--dry-run` uses the same codes. Report lines go to stdout, warnings and the summary to stderr.
+
+Server-required (as `docs write` already is for database stores), and the path is resolved **on the server** — under Docker it must sit inside a bind mount (`quilltap docs docker-mounts`). Refused for a filesystem or Obsidian store (one pointed at its own `basePath`), an archived character's vault, a store mid-conversion or mid-scan, a second concurrent run, and a manifest belonging to another store.
+
+A character vault's **keystone files** — `properties.json`, the five required `.md` files, and `Wardrobe/instructions.md` — are never deleted from the store by a sync. The planner reports a `conflict` instead.
+
 ## Memories
 
-`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable, but never writable. All verbs open the main encrypted DB read-only.
+`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable. All verbs open the main encrypted DB read-only; the two that change anything (`maintain`, `validate --repair --write`) ask the running server to do the work.
 
 ```bash
 quilltap memories ls                                                   # All holders, default sort: reinforcedImportance DESC
 quilltap memories ls --character Ariadne --sort created --limit 10     # One holder, newest first
 quilltap memories find "concrete examples"                             # Substring match on summary (--in content|both)
 quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern search inside content, with snippets
+quilltap memories grep -l "concrete examples"                          # Matching memory IDs only, one per line (--paths-only)
 quilltap memories show <id|prefix> [--depth N] [--no-related]          # Full record + related-memory neighbourhood
 quilltap memories tree <id|prefix> [--depth N] [--max-nodes N]         # ASCII walk of the bidirectional related-memory graph
-quilltap memories status [--character <name|id>]                       # Per-holder rollup + dangling-edge check
+quilltap memories status [--character <name|id>] [--port <n>]          # Per-holder rollup, maintenance ledger + dangling-edge check
+quilltap memories validate [--character <name|id>] [--list]            # Graph health check; exit 1 if any dangling link remains
+quilltap memories validate --repair [--write]                          # Rehearse (or, with --write, apply) the server's graph repair
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
+quilltap memories maintain --character Ariadne --dry-run               # Rehearse every maintenance phase (server required)
+quilltap memories maintain --character Ariadne --phases consolidate    # Queue a consolidation-only maintenance job
+quilltap memories maintain --character all [--phases demote,retire]    # Queue maintenance for every character
 ```
 
-Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source`, `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` to reverse) apply to `ls`, `find`, and `grep`. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
+Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` / `--reverse` to flip it, `--limit N` (default 50) and `--full-titles` to stop chat titles being truncated to 32 characters) apply to `ls`, `find`, and `grep`. `grep -l` / `--paths-only` prints only the IDs of matching memories, one per line. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. `validate` is `status`'s terse twin — read-only; it counts dangling `relatedMemoryIds` edges, dangling `consolidatedFrom` members (digests naming notes that are gone), dangling `supersededById` pointers, and rows with no embedding. It exits 1 if any dangling link remains (a missing embedding only warns), and `--list` prints the offending IDs. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains, now with `--tier hot|cold` (rows with no tier count as hot).
+
+Verbs that call the server (`grep --semantic`, `status`'s ledger, `maintain`, `validate --repair`) take `--port`; without it they use the port recorded in the `--instance` / `--data-dir` instance's lock, else 3000.
+
+`maintain` runs the memory maintenance job by hand: `fold-near-duplicates`, `consolidate`, `demote`, `retire`, `mirror`, always in that order. `--character <name|id|all>` is required (`all` is every character you own); `--phases a,b,…` picks a subset (checked by the server, which answers an unknown name with a 400; naming `consolidate` brings `mirror` along, since the Commonplace mirror follows consolidation). The CLI resolves the character locally and asks the running server — the model, the embeddings and the only database writer live there. With `--dry-run` the server rehearses the run and writes nothing: the CLI prints each phase's status (ran / skipped, and why), then the fold groups, the consolidation clusters (member notes, proposed digests, standalones, contradictions, run stats), the demotion arithmetic (cap, hot total, demotable, protected, excess, demoted), the retire count and the mirror subjects. A dry run over `all` gives one table row per character and may not include `consolidate` (each would call the model). Without `--dry-run` the server queues one `MEMORY_MAINTENANCE` job per character and the CLI prints the job ids; manual runs ignore the master `enabled` switches. `--max N` caps clusters consolidated (`maxClustersPerRun`, 1–1000; a dry run defaults to 10, at most 40), `--threshold 0..1` overrides the cluster similarity (neural embedding profiles), `--cap N` overrides the hot-row cap for demotion (100–100000). `--json` prints the raw API payload. There is no `consolidate` verb any more: use `maintain --phases consolidate`.
+
+`validate --repair` asks the running server to repair what `validate` finds. Without `--write` it is a dry run that prints what would be repaired and changes nothing; with `--write` the server scrubs dangling `relatedMemoryIds`, `consolidatedFrom` and `supersededById` links and queues embedding jobs for rows with none (up to 2000 per run; it needs a default embedding profile). As with `db characters archive`, the write runs inside the server, which holds the instance lock, so the server must be up. `status` also shows the character's maintenance ledger — when each phase last ran and whether the last demotion was effective — when it can reach the running server, and the last three maintenance job rows either way.
 
 ## Memory Extraction Dry-Run
 
@@ -245,7 +369,9 @@ quilltap memory-diff <chatId> --instance Friday          # Report to the current
 quilltap memory-diff <chatId> --out /tmp/diff --concurrency 8
 ```
 
-Needs a running server (`--port`, default 3000) to reach the extraction pipeline. `--out <dir>` sets the report destination (default: cwd); `--concurrency N` bounds parallel turns (default 4, max 32).
+Needs a running server to reach the extraction pipeline: pass `--port`, or name the server's instance with `--instance`/`--data-dir` and the port is read from its lock file (see [Finding the server](#finding-the-server)); otherwise 3000. `--out <dir>` sets the report destination (default: cwd); `--concurrency N` bounds parallel turns (default 4, max 32).
+
+The dry run is the live pipeline with nothing written: every turn, then both fold passes (`other-fold`, `episode-fold`) over the history a regenerate would rebuild, autonomous rooms included. Each re-extracted candidate records `extractionPass` and `decision` — what admission would do with it (`insert`, `reinforce`, `absorb`, …). Admission embeds each candidate to decide, so a dry run makes embedding calls.
 
 ## Recall Replay
 
@@ -255,9 +381,45 @@ Needs a running server (`--port`, default 3000) to reach the extraction pipeline
 quilltap recall-replay <chatId>                 # Replay the last turn
 quilltap recall-replay <chatId> --turn 42       # Replay at interchange 42 (its own clock)
 quilltap recall-replay <chatId> --json          # Raw JSON for scripting
+quilltap recall-replay <chatId> --memory-budget 4000  # Budget-sized dynamic head
+quilltap recall-replay <chatId> --turn 42 --json > t42.json
+quilltap recall-replay <chatId> --turn 42 --signals-from t42.json --as-of \
+  --tuning '{"boostGateAbs":0.45,"boostGateMargin":0.15,"boostGateRamp":0.1}'
 ```
 
-Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default 25), `--port <n>` (default 3000), `--json`.
+Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default: the larger of 25 and the new path's head size + 10), `--memory-budget <tokens>` (positive integer; the new path's selected rows then follow the budget-sized dynamic head, which scales with the model's memory budget, while the old path keeps the historical fixed 5-entry head; each path header prints its head size), `--instance <name>` / `--data-dir <path>` (find the server's port, see [Finding the server](#finding-the-server)), `--port <n>` (default: from the instance lock, else 3000), `--json`.
+
+Tuning and comparable runs:
+
+- `--tuning '<json>'` / `--tuning-file <path>` — retuning constants for the new path only (the old path stays the reference): `boostGateAbs`, `boostGateMargin`, `boostGateRamp` (relevance gate on boosts), `boostCap`, `freshBypassesGate`, `windowBypassesGate`, `multipliers` (`{ "freshEvent24h": 1.3, … }`), `specificAnchors`, `anchorMinHits`, `anchorOrder`, `backgroundReserve`. Unknown keys are rejected. The header's `Tuning` line shows what is active.
+- `--signals-from <replay.json>` — reuse the signals saved in an earlier `--json` replay of the same chat and turn. The distillation is a cheap-LLM call and words the same turn differently each time, so runs you mean to compare should share it.
+- `--as-of` — search only memories created before the turn's opening message, with weights decayed to the turn's own clock: the corpus as it stood then. The header's `Harness` line shows the cutoff and how many later memories were left out.
+
+The server memoises the replay's embeddings by text until it restarts, so repeat runs embed identical vectors.
+
+After the two tables the replay prints:
+
+- **TEXT FALLBACK** — what the new path returns with no usable vector (the text strategy over the same question).
+- **STAGE TRACE** — one line per recall stage: `query` (distilled or pinned, embedding calls), `gather` / `hydrate` / `score` / `select` for the head search (pool size, floor, window mode, expansion, the cut), and `assemble` per pool (what the archive held and its budget cut, how many pool rows the archive removed from the head, what the inter-character section took and skipped as already delivered).
+- **Ring** — the anti-repetition ring the replay ranked under: the one in force at that turn, rebuilt from the `[Recall:ring]` lines each reply's `debugMemoryLogs` carries, or the chat's current ring for a chat older than those records.
+
+`--json` adds `fallbackPath`, `trace`, `pools`, `ring` and `ringSource` to the result.
+
+## Anchor Probe
+
+`quilltap anchor-probe <characterId>` measures whether the episodic anchor line embedded with each memory suppresses reinforcement at admission. It re-embeds the character's most recent memories with and without the anchor line, compares each against older rows, asks admission's own decider (the same subject, kind, source and date-guard rules a new memory meets) what it would do each way, and reports how many rows would fold into an older one and how many would be absorbed as near-duplicates, plus a per-row table (rows that would fold only without anchors are highlighted). Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+
+```bash
+quilltap anchor-probe <characterId>             # Sample the 50 most recent memories
+quilltap anchor-probe <characterId> --limit 20  # Smaller, cheaper sample
+quilltap anchor-probe <characterId> --json      # Raw JSON for scripting
+```
+
+Flags: `--limit <n>` (1–200, default 50), `--instance <name>` / `--data-dir <path>` (find the server's port, see [Finding the server](#finding-the-server)), `--port <n>` (default: from the instance lock, else 3000), `--json`.
+
+### Finding the server
+
+`memory-diff`, `recall-replay` and `anchor-probe` call a running server over HTTP. The server records the port it listens on in its instance lock (`<dataDir>/data/quilltap.lock`, field `port`; shown by `quilltap db --lock-status`). Resolution order: an explicit `--port` wins; otherwise, if `--instance` or `--data-dir` is given and that lock is live and records a port, that port is used (a dim note says so); otherwise 3000. Giving both `--instance` and `--data-dir` is an error. `--passphrase` is accepted by all three for uniformity; `recall-replay` and `anchor-probe` ignore it. Locks written before this field existed carry no port, so restart the server once to record it.
 
 ## Maintenance & Cleanup
 
@@ -322,7 +484,13 @@ quilltap themes create sunset           # Scaffold a new theme
 quilltap themes search "dark"           # Search registries
 quilltap themes update                  # Check for theme updates
 quilltap themes registry list           # List configured registries
-quilltap themes registry add <url>      # Add a registry source
+quilltap themes registry add <url>      # Add a registry source (--key <pubkey>, --name <name>)
+quilltap themes registry remove <name>  # Remove a registry source
+quilltap themes registry refresh        # Refresh all registry indexes
+
+# For registry operators
+quilltap themes registry keygen [--output <dir>]     # Generate an Ed25519 keypair
+quilltap themes registry sign <dir> --key <private>  # Sign a registry directory
 ```
 
 ## Shell Completion
@@ -401,7 +569,7 @@ Fish picks new completion files up automatically — no shell restart needed.
 
 Completions **parse the line rather than counting words**, so a flag typed anywhere the CLI itself accepts one does not derail them: `quilltap docs --instance Friday <TAB>` still offers the `docs` verbs. bash and zsh also reuse the `-i` / `-d` / `--passphrase` already on the line when looking store names up, so the names offered come from the instance you are addressing rather than the default one. fish completes `--mount` but not the positionals, and always reads the default instance.
 
-Dynamic completions shell out to `quilltap`'s own subcommands. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
+Dynamic completions shell out to `quilltap`'s own subcommands — `quilltap instances list --names-only` and `quilltap docs list --names-only`, which print one name per line and are handy in scripts too. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
 
 ## Requirements
 

package/bin/quilltap.js

@@ -11,8 +11,10 @@ const {
   printDefaultInstanceHint,
   promptPassphrase,
   loadDbKey,
+  openEncryptedDb,
 } = require('../lib/db-helpers');
 const { resolveInstance } = require('../lib/instances');
+const { decodeCompressedTextInRows } = require('../lib/text-codec');
 const { resolveModuleDir, ensureNativeModules, ensureDatabaseNativeModule } = require('../lib/native-modules');
 
 const PACKAGE_DIR = path.resolve(__dirname, '..');
@@ -92,6 +94,7 @@ Subcommands:
   db                            Query encrypted databases
   themes                        Manage theme bundles
   docs                          Inspect, read, and export document mounts
+  sync <store> <path>           Mirror a database-backed store to a directory
   memories                      Search, browse, and graph memories
   instances                     Register / inspect named Quilltap instances
   logs                          Tail or print an instance log file
@@ -100,6 +103,7 @@ Subcommands:
   file-verify                   Force-download cloud-evicted data files (iCloud, etc.)
   memory-diff <chatId>          Dump existing memories and dry-run re-extraction for a chat
   recall-replay <chatId>        Replay a turn's memory recall, old vs episodic ranking
+  anchor-probe <characterId>    Probe whether episodic anchor lines suppress reinforcement at admission
   completion <shell>            Generate a shell completion script (bash / zsh / fish)
 
 Options:
@@ -486,6 +490,18 @@ function verifyPidIsNode(pid, expectedArgv0) {
 
 const HEARTBEAT_FRESH_MS = 5 * 60 * 1000;
 
+/**
+ * The freshness window in words, derived from the constant the check actually
+ * uses — so the sentence `--lock-clean` prints cannot drift away from the
+ * behaviour it describes.
+ */
+function describeFreshWindow() {
+  const seconds = Math.round(HEARTBEAT_FRESH_MS / 1000);
+  if (seconds % 60 !== 0) return `${seconds} seconds`;
+  const minutes = seconds / 60;
+  return minutes === 1 ? '1 minute' : `${minutes} minutes`;
+}
+
 /**
  * Decide whether a lock record belongs to a live process.
  *
@@ -576,6 +592,9 @@ function handleLockCommand(dataDir, opts) {
     console.log(`  Environment:  ${lock.environment || 'unknown'}`);
     console.log(`  Process:      ${lock.processTitle || 'unknown'}`);
     console.log(`  Started:      ${lock.startedAt || 'unknown'}`);
+    if (Number.isInteger(lock.port)) {
+      console.log(`  Port:         ${lock.port}`);
+    }
 
     // Show heartbeat age if available
     if (lock.lastHeartbeat) {
@@ -628,9 +647,17 @@ function handleLockCommand(dataDir, opts) {
       console.log('Stop the running instance first, or use --lock-override to force.');
       process.exit(1);
     } else if (heartbeatFresh) {
+      // Reached only when `alive` is false — the arm above has already claimed
+      // every confirmed-live case — so this must not assert that anything is
+      // running. Freshness alone is the deliberate fallback (bug 126) for
+      // environments where PID checks are unreliable; the refusal is right,
+      // and what it says is simply what was tested.
       const ageStr = Math.round(heartbeatAgeMs / 1000) + 's';
-      console.log(`Lock is still being refreshed (heartbeat ${ageStr} ago) — its holder is alive. Cannot clean.`);
-      console.log('Stop the running instance first, or use --lock-override to force.');
+      console.log(`Lock heartbeat is still fresh (${ageStr} ago). Cannot clean.`);
+      console.log(
+        `A lock counts as held until its heartbeat is ${describeFreshWindow()} stale, even if its process has gone. ` +
+          'Wait it out, or use --lock-override to force.'
+      );
       process.exit(1);
     } else if (alive && !isNode) {
       console.log(`Lock references PID ${lock.pid} which is alive but does NOT look like a Quilltap process.`);
@@ -742,7 +769,10 @@ Subcommands (high-level shortcuts; auto-pick the right database):
   message <id>                Full content of a single chat message
   log <id>                    Full request/response of a single LLM log
   memories --character <id>   Memories held by a character
-                              (flags: --about <id|name> --source AUTO|MANUAL)
+                              (flags: --about <id|name>
+                              --source AUTO|MANUAL|CONSOLIDATED
+                              --tier hot|cold (NULL tier counts as hot)
+                              --limit N)
   characters status           Per-character vault readiness report:
                               flag value, vault present, single-file count,
                               Prompts/ and Scenarios/ folder counts, and any
@@ -961,9 +991,10 @@ async function dbCommand(args) {
   }
 
   let dbFilename;
-  if (useLlmLogs) dbFilename = 'quilltap-llm-logs.db';
-  else if (useMountPoints) dbFilename = 'quilltap-mount-index.db';
-  else dbFilename = 'quilltap.db';
+  let dbFriendlyName;
+  if (useLlmLogs) { dbFilename = 'quilltap-llm-logs.db'; dbFriendlyName = 'LLM logs database'; }
+  else if (useMountPoints) { dbFilename = 'quilltap-mount-index.db'; dbFriendlyName = 'mount index database'; }
+  else { dbFilename = 'quilltap.db'; dbFriendlyName = 'main database'; }
   const dbPath = path.join(dataDir, dbFilename);
 
   if (!fs.existsSync(dbPath)) {
@@ -993,27 +1024,16 @@ async function dbCommand(args) {
     }
   }
 
-  // Open database — prefer SQLCipher-capable build
-  let Database;
+  // Open through the one shared opener. It picks the SQLCipher-capable build,
+  // keys the connection, verifies it, and — the reason the low-level path may
+  // not roll its own — registers qt_text(). Without it raw SQL cannot read
+  // inside a compressed text column, and a --write to chat_messages fails
+  // outright because the search-index triggers call it (bug 162).
+  let db;
   try {
-    Database = require('better-sqlite3-multiple-ciphers');
-  } catch {
-    Database = require('better-sqlite3');
-  }
-  const db = new Database(dbPath, { readonly: !writable });
-
-  if (pepper) {
-    const keyHex = Buffer.from(pepper, 'base64').toString('hex');
-    db.pragma(`key = "x'${keyHex}'"`);
-  }
-
-  try {
-    // Verify database is readable
-    db.prepare('SELECT 1').get();
+    db = openEncryptedDb(dbPath, pepper, { readonly: !writable, friendlyName: dbFriendlyName });
   } catch (err) {
-    console.error(`Cannot open database: ${err.message}`);
-    console.error('The database may be encrypted with a different key, or the .dbkey file may be missing.');
-    db.close();
+    console.error(err.message);
     process.exit(1);
   }
 
@@ -1030,6 +1050,8 @@ async function dbCommand(args) {
       const stmt = db.prepare(sql);
       if (stmt.reader) {
         const rows = stmt.all();
+        // Compressed text columns arrive as Buffers; print them as text (bug 173).
+        decodeCompressedTextInRows(rows);
         if (asJson) {
           console.log(JSON.stringify(rows, null, 2));
         } else if (rows.length === 0) {
@@ -1098,6 +1120,7 @@ async function dbCommand(args) {
             const stmt = db.prepare(trimmed);
             if (stmt.reader) {
               const rows = stmt.all();
+              decodeCompressedTextInRows(rows);
               if (rows.length === 0) console.log('(no results)');
               else console.table(rows);
             } else {
@@ -1154,7 +1177,7 @@ async function dbCommand(args) {
 // to the subcommand. Each subcommand parses these flags position-independently,
 // so they behave the same before or after the verb.
 const SUBCOMMANDS = new Set([
-  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'recall-replay', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
+  'db', 'themes', 'docs', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', 'anchor-probe', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
 ]);
 // Global flags that consume the following token as their value.
 const GLOBAL_VALUE_FLAGS = new Set(['-p', '--port', '-d', '--data-dir', '-i', '--instance', '--passphrase']);
@@ -1193,6 +1216,12 @@ if (subName === 'db') {
 } else if (subName === 'docs') {
   const { docsCommand } = require('../lib/docs-commands');
   docsCommand(subArgs);
+} else if (subName === 'sync') {
+  const { syncCommand } = require('../lib/sync-command');
+  syncCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (subName === 'memories') {
   const { memoriesCommand } = require('../lib/memories-commands');
   memoriesCommand(subArgs).catch(err => {
@@ -1220,6 +1249,12 @@ if (subName === 'db') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (subName === 'anchor-probe') {
+  const { anchorProbeCommand } = require('../lib/anchor-probe-command');
+  anchorProbeCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (subName === 'completion') {
   const { completionCommand } = require('../lib/completion-commands');
   completionCommand(subArgs).catch(err => {

package/lib/__tests__/completion-coverage.test.js

@@ -108,6 +108,7 @@ describe('every subcommand has its own completion arm', () => {
 const HELP_SOURCES = {
   db: ['bin/quilltap.js', 'printDbHelp'],
   docs: ['lib/docs-commands.js', 'printDocsHelp'],
+  sync: ['lib/sync-command.js', 'printSyncHelp'],
   memories: ['lib/memories-commands.js', 'printMemoriesHelp'],
   themes: ['lib/theme-commands.js', 'printHelp'],
   instances: ['lib/instances-commands.js', 'printHelp'],
@@ -117,6 +118,7 @@ const HELP_SOURCES = {
   'file-verify': ['lib/file-verify-commands.js', 'printHelp'],
   'memory-diff': ['lib/memory-diff-command.js', 'printMemoryDiffHelp'],
   'recall-replay': ['lib/recall-replay-command.js', 'printRecallReplayHelp'],
+  'anchor-probe': ['lib/anchor-probe-command.js', 'printAnchorProbeHelp'],
   completion: ['lib/completion-commands.js', 'printCompletionHelp'],
 };