quilltap 4.10.0-dev.51 → 4.10.0-dev.57

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
 
@@ -135,6 +139,27 @@ quilltap db memories --character Friday [--about Amy] [--source AUTO]
 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,37 @@ 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).
 
 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,6 +230,7 @@ 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 read [--rendered] <mount> <path>  # File contents → stdout
@@ -203,7 +256,24 @@ 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.
+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,12 +283,49 @@ 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.
@@ -231,10 +338,11 @@ quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern
 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 validate [--character <name|id>] [--list]            # Dangling-edge health check; exit 1 if any remain
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
 ```
 
-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`, `--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. `validate` is `status`'s terse twin — read-only, exit 1 if any dangling related-memory edge remains, `--list` to print the offending source IDs and their dangling targets. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, `--port 3000`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
 
 ## Memory Extraction Dry-Run
 

package/bin/quilltap.js

@@ -92,6 +92,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
@@ -1174,7 +1175,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', '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']);
@@ -1213,6 +1214,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 => {

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'],

package/lib/__tests__/sync-report.test.js

@@ -0,0 +1,158 @@
+/**
+ * How `quilltap sync` renders a plan.
+ *
+ * The formatter is the operator's whole view of what the verb did, and its
+ * two load-bearing claims are easy to get subtly wrong: the second column is
+ * the side that CHANGES (so `modify store` means the store is rewritten from
+ * disk, not the other way round), and the exit code distinguishes "an
+ * unresolved conflict" from "something failed" so a script can tell them apart.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const {
+  formatActionLine,
+  formatActionLines,
+  formatSummary,
+  exitCodeFor,
+  displayPath,
+  formatBytes,
+} = require('../sync-report');
+
+function action(over = {}) {
+  return { kind: 'create', side: 'disk', relativePath: 'a.md', entryKind: 'file', ...over };
+}
+
+function summary(over = {}) {
+  return {
+    created: 0, modified: 0, deleted: 0, touched: 0,
+    described: 0, conflicts: 0, skipped: 0, failed: 0, ...over,
+  };
+}
+
+describe('one action, one line', () => {
+  it('puts the action first and the side that changes second', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', relativePath: 'ch.md' }), false))
+      .toBe('modify   store  ch.md');
+  });
+
+  it('pads the columns so paths line up under each other', () => {
+    const lines = formatActionLines([
+      action({ kind: 'mkdir', side: 'disk', relativePath: 'lore', entryKind: 'folder' }),
+      action({ kind: 'conflict', side: null, relativePath: 'ch.md' }),
+    ], false);
+    const column = lines.map((l) => l.indexOf(l.trim().split(/\s+/)[2] || ''));
+    expect(new Set(column).size).toBe(1);
+  });
+
+  it('marks a folder with a trailing slash so it cannot be mistaken for a file', () => {
+    expect(displayPath(action({ entryKind: 'folder', relativePath: 'drafts' }))).toBe('drafts/');
+    expect(displayPath(action({ entryKind: 'file', relativePath: 'drafts' }))).toBe('drafts');
+  });
+
+  it('writes an em dash where no side changes', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), false))
+      .toContain('conflict —');
+  });
+
+  it('appends the engine’s reason in parentheses', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', reason: 'disk newer by 2h 14m' }), false))
+      .toContain('(disk newer by 2h 14m)');
+  });
+
+  it('shows the sha and size on a line that moved bytes', () => {
+    const line = formatActionLine(
+      action({ sha256: '3f9a' + '0'.repeat(60), sizeBytes: 421888 }), false
+    );
+    expect(line).toContain('sha 3f9a…');
+    expect(line).toContain('412.0 KB');
+  });
+
+  it('says nothing about bytes on a delete', () => {
+    expect(formatActionLine(action({ kind: 'delete', side: 'store', sha256: 'x'.repeat(64) }), false))
+      .not.toContain('sha');
+  });
+
+  it('leads with the error when an action failed', () => {
+    const line = formatActionLine(
+      action({ outcome: 'failed', error: 'EACCES', reason: 'store newer' }), false
+    );
+    expect(line).toContain('FAILED: EACCES');
+    expect(line).not.toContain('store newer');
+  });
+
+  it('emits no escape codes when colour is off', () => {
+    const lines = formatActionLines(
+      [action(), action({ kind: 'conflict', side: null }), action({ kind: 'delete', side: 'store' })],
+      false
+    );
+    expect(lines.join('\n')).not.toMatch(/\x1b\[/);
+  });
+
+  it('tints the line when colour is on', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), true)).toMatch(/\x1b\[31m/);
+  });
+
+  it('caps the path column so one long path does not push every detail off screen', () => {
+    const lines = formatActionLines([
+      action({ relativePath: 'a/'.repeat(60) + 'deep.md', reason: 'why' }),
+      action({ relativePath: 'b.md', reason: 'why' }),
+    ], false);
+    expect(lines[1].indexOf('(why)')).toBeLessThan(80);
+  });
+});
+
+describe('the summary', () => {
+  it('names only the categories that actually happened', () => {
+    expect(formatSummary(summary({ created: 3, modified: 1 }), 800, false))
+      .toBe('3 created, 1 modified — 0.8 s');
+  });
+
+  it('says so plainly when there was nothing to do', () => {
+    expect(formatSummary(summary(), 120, false)).toBe('Already in step — 0.1 s');
+  });
+
+  it('speaks in the conditional under --dry-run', () => {
+    expect(formatSummary(summary({ created: 2 }), 300, true)).toBe('Would do: 2 created — 0.3 s');
+    expect(formatSummary(summary(), 300, true)).toBe('Nothing to do — 0.3 s');
+  });
+
+  it('pluralises conflicts', () => {
+    expect(formatSummary(summary({ conflicts: 1 }), 0, false)).toContain('1 conflict —');
+    expect(formatSummary(summary({ conflicts: 2 }), 0, false)).toContain('2 conflicts');
+  });
+
+  it('reports failures last, where they are hardest to miss', () => {
+    const line = formatSummary(summary({ created: 1, failed: 2 }), 0, false);
+    expect(line.indexOf('2 failed')).toBeGreaterThan(line.indexOf('1 created'));
+  });
+});
+
+describe('the exit code', () => {
+  it('is 0 when the run was clean', () => {
+    expect(exitCodeFor(summary({ created: 5, touched: 2 }))).toBe(0);
+  });
+
+  it('is 2 for an unresolved conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1 }))).toBe(2);
+  });
+
+  it('is 1 when something failed outright, even alongside a conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1, failed: 1 }))).toBe(1);
+  });
+});
+
+describe('byte formatting', () => {
+  it('scales through the units', () => {
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB');
+    expect(formatBytes(3 * 1024 ** 3)).toBe('3.00 GB');
+  });
+
+  it('says nothing for a size it was not given', () => {
+    expect(formatBytes(undefined)).toBe('');
+  });
+});

package/lib/completion/bash.template

@@ -61,7 +61,7 @@ _quilltap_complete() {
   local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update --passphrase"
 
   # Top-level subcommands
-  local top_cmds="db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion"
+  local top_cmds="db docs sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion"
 
   # Flags that swallow the word after them. A flat list will not do: -o is the
   # valueless global --open but themes' valued --output, and `memories`
@@ -71,6 +71,7 @@ _quilltap_complete() {
   local vf_global=" -d --data-dir -i --instance -p --port --passphrase "
   local vf_db=" --limit --grep --character --project --about --source --chat --message --field --tail --last --from --type --out --id --count "
   local vf_docs=" --mount --folder --type --ext --limit --max --context --top --threshold --sort --depth --max-nodes --format "
+  local vf_sync=" --direction --prefer "
   local vf_themes=" -o --output -k --key -n --name "
   local vf_memories=" -d --data-dir --instance --passphrase --port --character --about --source --chat --project --since --until --min-importance --min-reinforced --sort --limit --in --max --context --depth --max-nodes --top --threshold "
   local vf_logs=" --stream --tail --grep "
@@ -93,6 +94,7 @@ _quilltap_complete() {
     case "$subcommand" in
       db)            valued="$vf_global$vf_db" ;;
       docs)          valued="$vf_global$vf_docs" ;;
+      sync)          valued="$vf_global$vf_sync" ;;
       themes)        valued="$vf_global$vf_themes" ;;
       memories)      valued="$vf_memories" ;;
       logs)          valued="$vf_global$vf_logs" ;;
@@ -197,6 +199,14 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "args json" -- "$cur"))
       return
       ;;
+    --direction)
+      COMPREPLY=($(compgen -W "both to-disk to-store" -- "$cur"))
+      return
+      ;;
+    --prefer)
+      COMPREPLY=($(compgen -W "newer store disk" -- "$cur"))
+      return
+      ;;
   esac
 
   # Subcommand-specific completion
@@ -241,6 +251,18 @@ _quilltap_complete() {
         _quilltap_docs_positional "$subverb" "$positional_count" "$cur"
       fi
       ;;
+    sync)
+      local sync_flags="--dry-run --direction --prefer --no-delete --no-manifest \
+        --json --instance --data-dir --passphrase --port --help"
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "$sync_flags" -- "$cur"))
+      elif [[ "$positional_count" == "1" ]]; then
+        _quilltap_lines_compreply "$cur" \
+          <<< "$(command quilltap docs list --names-only "${ctx_flags[@]}" 2>/dev/null)"
+      else
+        COMPREPLY=($(compgen -d -- "$cur"))
+      fi
+      ;;
     themes)
       local themes_verbs="list install uninstall validate export create search update registry"
       local themes_flags="--instance --data-dir --output -o --help"

package/lib/completion/fish.template

@@ -19,7 +19,7 @@ function __quilltap_no_subcommand
   end
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
+      case db docs sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
         return 1
     end
   end
@@ -31,7 +31,7 @@ function __quilltap_using_subcommand
   set -l cmd (commandline -opc)
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
+      case db docs sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
         test "$cmd[$i]" = "$target"
         return $status
     end
@@ -55,6 +55,7 @@ end
 
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'db' -d 'Query encrypted databases'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'docs' -d 'Inspect and read document mounts'
+complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'sync' -d 'Mirror a database-backed store to a directory'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'themes' -d 'Manage theme bundles'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'instances' -d 'Register or inspect instances'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memories' -d 'Search and browse memories'
@@ -188,6 +189,22 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'uri' -d 'Show can
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'base64' -d 'Base64 transfer for binary files'
 complete -c quilltap -n '__quilltap_using_subverb docs docker-mounts' -l 'format' -d 'Output shape' -x -a 'args json'
 
+# ---------- sync ----------
+# `quilltap sync <store> <path>`: the first positional is a store, the second a
+# local directory — so the verb is not -f (file completion stays available).
+complete -c quilltap -n '__quilltap_using_subcommand sync' -f -a '(__quilltap_mount_names)' -d 'Document store'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'dry-run' -d 'Plan and print; change nothing'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'direction' -d 'Which side may change' -x -a 'both to-disk to-store'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'prefer' -d 'How to resolve a conflict' -x -a 'newer store disk'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'no-delete' -d 'Never propagate a deletion'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'no-manifest' -d 'Ignore .quilltap-sync.json'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'json' -d 'Machine-readable plan and results'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'port' -s 'p' -d 'Server port' -x
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'instance' -s 'i' -d 'Registered instance' -x -a '(__quilltap_instance_names)'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'data-dir' -s 'd' -d 'Data directory' -x -a '(__fish_complete_directories)'
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'passphrase' -d 'Database passphrase' -x
+complete -c quilltap -n '__quilltap_using_subcommand sync' -l 'help' -s 'h' -d 'Show help'
+
 # ---------- themes verbs ----------
 complete -c quilltap -n '__quilltap_using_subcommand themes' -f -a 'list' -d 'List themes'
 complete -c quilltap -n '__quilltap_using_subcommand themes' -f -a 'install' -d 'Install theme'

package/lib/completion/zsh.template

@@ -37,6 +37,7 @@ _quilltap() {
   subcommands=(
     'db:Query encrypted databases'
     'docs:Inspect, read, and export document mounts'
+    'sync:Mirror a database-backed store to a directory'
     'themes:Manage theme bundles'
     'instances:Register or inspect named Quilltap instances'
     'memories:Search, browse, and graph memories'
@@ -80,6 +81,9 @@ _quilltap_subcommand() {
     docs)
       _quilltap_docs
       ;;
+    sync)
+      _quilltap_sync
+      ;;
     themes)
       _quilltap_themes
       ;;
@@ -314,6 +318,38 @@ _quilltap_docs() {
   esac
 }
 
+# `quilltap sync <store> <path>` — a store, then a local directory.
+_quilltap_sync() {
+  local -a sync_opts
+  sync_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '(-p --port)'{-p,--port}'[Server port]:port:'
+    '--json[Machine-readable plan and results]'
+    '--dry-run[Plan and print; change nothing]'
+    '--direction[Which side may change]:direction:(both to-disk to-store)'
+    '--prefer[How to resolve a conflict]:prefer:(newer store disk)'
+    '--no-delete[Never propagate a deletion]'
+    '--no-manifest[Ignore .quilltap-sync.json]'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  _arguments -C $sync_opts \
+    '1: :->store' \
+    '2: :->target' \
+    '*: :'
+
+  case "$state" in
+    store)
+      _quilltap_mount_names
+      ;;
+    target)
+      _directories
+      ;;
+  esac
+}
+
 # Which docs positionals name a document store, and which name a local path.
 # `move`/`copy`/`link` take <srcMount> <srcPath> <dstMount> <dstPath>, so a
 # store is wanted at both 2 and 4; everything else that takes a store takes it

package/lib/sync-command.js

@@ -0,0 +1,323 @@
+'use strict';
+
+/**
+ * `quilltap sync <store> <path>` — keep a database-backed document store and a
+ * directory on disk in step with each other.
+ *
+ * This file is a thin client. Every decision the sync makes — which side wins,
+ * what counts as a deletion, when to refuse — is made by the engine in the
+ * server (`lib/mount-index/sync/`), and every flag is validated by the route's
+ * own schema, which is the single source of truth. The CLI resolves the store
+ * name to a UUID (the one thing it opens the database for, read-only), posts
+ * the request, and prints what came back.
+ *
+ * The engine lives in the server rather than here because the sync writes
+ * through the store's own chokepoints — `linkDocumentContent`, the folder-row
+ * helper, the hard-link fan-out, the post-write re-chunk — and those are
+ * TypeScript in `lib/`, unreachable from this plain-JS package. A direct
+ * SQLite writer would be a second copy of all of them, and a lock-gated one
+ * could not re-chunk at all. `docs write` on a database store already requires
+ * the server for exactly this reason; `deconvert` already takes a server-local
+ * target path. This is that shape, not a new one.
+ *
+ * `<path>` is therefore resolved on the SERVER. Running under Docker, it must
+ * sit inside a bind mount — `quilltap docs docker-mounts` plans those.
+ *
+ * @module sync-command
+ */
+
+const path = require('path');
+const os = require('os');
+const {
+  resolveDataDirAndPassphrase,
+  printDefaultInstanceHint,
+  loadDbKey,
+  openMountIndexDb,
+  UUID_RE,
+} = require('./db-helpers');
+const { isQtapUri, parseQtapUri } = require('./qtap-uri');
+const { formatActionLines, formatSummary, exitCodeFor } = require('./sync-report');
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const YELLOW = '\x1b[33m';
+
+function printSyncHelp() {
+  console.log(`
+Quilltap Document Store Sync
+
+Usage: quilltap sync <store|qtap://store/> <path> [options]
+
+Mirrors a database-backed document store and a directory on disk in both
+directions. The two sides are compared by SHA-256 first and by modification
+time second: equal bytes with unequal clocks are re-stamped, not re-copied.
+Whichever side changed is copied to the other; when both changed since the
+last run it is reported as a conflict and left alone.
+
+The directory is created if it is missing. A document store is never created.
+
+Options:
+  --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 to the other side
+  --no-manifest             Ignore .quilltap-sync.json (first-run rules every time)
+  --json                    Machine-readable plan and results on stdout
+  -p, --port <number>       Server port (default: 3000)
+  -d, --data-dir <path>     Override data directory
+  -i, --instance <name>     Use a registered instance
+  --passphrase <pass>       Decrypt .dbkey if peppered
+  -h, --help                Show this help
+
+Exit codes: 0 clean, 1 an error or a failed action, 2 an unresolved conflict.
+--dry-run uses the same codes, so a script can gate on a clean plan.
+
+Files and folders whose names begin with a dot are INVISIBLE to the sync in
+both directions — never copied, never deleted, on either side. The one
+exception is .quilltap-sync.json, the record the verb keeps of what the last
+run left; it lives in the directory and never enters the store.
+
+A binary's description travels beside it as <file>.description.md. Editing
+that file changes the caption in the store; deleting it clears the caption.
+A text document's description is not synced.
+
+The server must be running: a database-backed store's writes go through it,
+as they already do for 'quilltap docs write'. <path> is resolved on the
+server — under Docker it must sit inside a bind mount (see
+'quilltap docs docker-mounts').
+
+Examples:
+  quilltap sync Lore ~/Documents/lore --dry-run
+  quilltap sync Lore ~/Documents/lore
+  quilltap sync Lore ~/Documents/lore --prefer disk
+  quilltap sync qtap://Lore/ ~/Documents/lore --direction to-disk
+`);
+}
+
+function parseFlags(args) {
+  const flags = {
+    dataDir: '',
+    instance: '',
+    passphrase: '',
+    port: 3000,
+    json: false,
+    dryRun: false,
+    direction: 'both',
+    prefer: 'newer',
+    noDelete: false,
+    noManifest: false,
+    help: false,
+  };
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '-d': case '--data-dir':    flags.dataDir = args[++i] || ''; break;
+      case '-i': case '--instance':    flags.instance = args[++i] || ''; break;
+      case '--passphrase':             flags.passphrase = args[++i] || ''; break;
+      case '-p': case '--port':        flags.port = parseInt(args[++i], 10) || 3000; break;
+      case '--json':                   flags.json = true; break;
+      case '--dry-run':                flags.dryRun = true; break;
+      case '--direction':              flags.direction = args[++i] || ''; break;
+      case '--prefer':                 flags.prefer = args[++i] || ''; break;
+      case '--no-delete':              flags.noDelete = true; break;
+      case '--no-manifest':            flags.noManifest = true; break;
+      case '-h': case '--help':        flags.help = true; break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Unknown option: ${arg}`);
+          process.exit(1);
+        }
+        positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+/** `~/x` → an absolute path. The server sees only what we send it. */
+function expandPath(input) {
+  let expanded = input;
+  if (expanded === '~') expanded = os.homedir();
+  else if (expanded.startsWith('~/')) expanded = path.join(os.homedir(), expanded.slice(2));
+  return path.resolve(expanded);
+}
+
+/**
+ * A store name or UUID, or a `qtap://store/` URI with an empty path. This is
+ * the only thing the verb opens the database for, and it opens it read-only.
+ */
+function resolveStoreSpec(spec) {
+  if (!isQtapUri(spec)) return spec;
+  const parsed = parseQtapUri(spec);
+  if (parsed.scope !== 'document_store') {
+    throw new Error(
+      'sync addresses document stores only; qtap://project/… and qtap://general/… are not CLI-addressable.'
+    );
+  }
+  if (parsed.path) {
+    throw new Error(`sync takes a whole store, not a path inside one: ${spec}`);
+  }
+  if (!parsed.mountPoint || parsed.mountPoint.toLowerCase() === 'self') {
+    throw new Error('"self" requires a character context and is not resolvable from the CLI.');
+  }
+  return parsed.mountPoint;
+}
+
+/** Name-first, UUID fallback — the same resolution the `docs` verbs use. */
+function requireMount(db, spec) {
+  if (UUID_RE.test(spec)) {
+    const row = db.prepare('SELECT * FROM doc_mount_points WHERE id = ?').get(spec);
+    if (!row) {
+      console.error(`No document store found with id ${spec}`);
+      process.exit(1);
+    }
+    return row;
+  }
+  const rows = db.prepare(
+    `SELECT * FROM doc_mount_points WHERE LOWER(name) = LOWER(?) ORDER BY name COLLATE NOCASE`
+  ).all(spec);
+  if (rows.length === 0) {
+    console.error(`No document store found with name "${spec}"`);
+    process.exit(1);
+  }
+  if (rows.length > 1) {
+    console.error(`Ambiguous store name "${spec}" matches multiple stores:`);
+    for (const r of rows) console.error(`  ${r.id}  ${r.name}  (${r.mountType})`);
+    console.error('Pass the UUID instead.');
+    process.exit(1);
+  }
+  return rows[0];
+}
+
+function isConnectionRefused(err) {
+  if (!err) return false;
+  const code = err.cause && err.cause.code ? err.cause.code : err.code;
+  return code === 'ECONNREFUSED' || code === 'ENOTFOUND' ||
+         code === 'EHOSTUNREACH' || code === 'ECONNRESET';
+}
+
+async function syncCommand(args) {
+  const { flags, positional } = parseFlags(args);
+  if (flags.help || positional.length === 0) {
+    printSyncHelp();
+    process.exit(flags.help ? 0 : 1);
+  }
+
+  const [storeSpec, targetSpec] = positional;
+  if (!targetSpec) {
+    console.error('Usage: quilltap sync <store> <path> [options]');
+    console.error("Run 'quilltap sync --help' for the full list of options.");
+    process.exit(1);
+  }
+  if (positional.length > 2) {
+    console.error(`sync takes one store and one path; got ${positional.length} arguments.`);
+    process.exit(1);
+  }
+
+  let storeName;
+  try {
+    storeName = resolveStoreSpec(storeSpec);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const targetPath = expandPath(targetSpec);
+
+  // Resolve the store from the local database — read-only, and the only thing
+  // the CLI opens it for.
+  const resolved = resolveDataDirAndPassphrase({
+    dataDir: flags.dataDir,
+    instance: flags.instance,
+    passphrase: flags.passphrase,
+  });
+  printDefaultInstanceHint(resolved);
+  const pepper = await loadDbKey(resolved.dataDir, resolved.passphrase);
+  const db = openMountIndexDb(resolved.dataDir, pepper, { readonly: true });
+  let mount;
+  try {
+    mount = requireMount(db, storeName);
+  } finally {
+    db.close();
+  }
+
+  if (mount.mountType !== 'database') {
+    console.error(
+      `"${mount.name}" is a ${mount.mountType} store — it already IS a directory` +
+      (mount.basePath ? ` (${mount.basePath})` : '') + '.'
+    );
+    console.error('sync mirrors database-backed stores only.');
+    process.exit(1);
+  }
+
+  const url =
+    `http://localhost:${flags.port}/api/v1/mount-points/${encodeURIComponent(mount.id)}?action=sync`;
+
+  // The route's schema is the single source of truth for these; the CLI does
+  // not re-validate, so a bad --direction is refused by the server with the
+  // server's own wording.
+  const body = {
+    targetPath,
+    dryRun: flags.dryRun,
+    direction: flags.direction,
+    prefer: flags.prefer,
+    propagateDeletes: !flags.noDelete,
+    useManifest: !flags.noManifest,
+  };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    if (isConnectionRefused(err)) {
+      console.error(
+        `Cannot sync database-backed store "${mount.name}" without the Quilltap server.`
+      );
+      console.error('Start the server (`quilltap`) or pass --port to match a non-default port.');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const payload = await res.json().catch(() => null);
+  if (!res.ok) {
+    const message = payload && payload.error ? payload.error : `HTTP ${res.status}`;
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+
+  const report = payload && payload.data !== undefined ? payload.data : payload;
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(exitCodeFor(report.summary));
+  }
+
+  const colour = Boolean(process.stdout.isTTY);
+  for (const line of formatActionLines(report.actions, colour)) {
+    console.log(line);
+  }
+
+  // Advisory text goes to stderr so stdout stays greppable.
+  for (const warning of report.warnings || []) {
+    console.error(colour ? `${YELLOW}warning:${RESET} ${warning}` : `warning: ${warning}`);
+  }
+  const summary = formatSummary(report.summary, report.elapsedMs, report.dryRun);
+  console.error(colour ? `${DIM}${summary}${RESET}` : summary);
+  if (report.summary.conflicts > 0) {
+    console.error(
+      colour
+        ? `${DIM}Re-run with --prefer store or --prefer disk to resolve the conflicts.${RESET}`
+        : 'Re-run with --prefer store or --prefer disk to resolve the conflicts.'
+    );
+  }
+
+  process.exit(exitCodeFor(report.summary));
+}
+
+module.exports = { syncCommand, printSyncHelp, expandPath, resolveStoreSpec };

package/lib/sync-report.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * Rendering for `quilltap sync`.
+ *
+ * Deliberately pure — actions and a colour switch in, lines out — so the
+ * report's shape can be tested without a server, a store, or a directory, the
+ * way `docker-mounts` is.
+ *
+ * ## The shape of a line
+ *
+ *     modify   store  chapters/03.md                (disk newer by 2h 14m)
+ *     ^        ^      ^                             ^
+ *     action   side   path                          why
+ *
+ * The first two columns are fixed width so the paths line up under each other,
+ * because the thing an operator actually reads down is the path column. The
+ * side is the side that CHANGES: `modify store` means the store is rewritten
+ * from disk, which is the opposite of the intuition some people bring and so
+ * is worth being unambiguous about.
+ *
+ * Advisory text — warnings, the summary — goes to stderr in the caller, so
+ * stdout stays greppable.
+ *
+ * @module sync-report
+ */
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+
+/** Column widths. `conflict` is the longest action word at 8. */
+const ACTION_WIDTH = 8;
+const SIDE_WIDTH = 6;
+
+/** Which colour an action's line takes. */
+const ACTION_COLOURS = {
+  create: GREEN,
+  mkdir: GREEN,
+  modify: GREEN,
+  describe: GREEN,
+  delete: YELLOW,
+  rmdir: YELLOW,
+  touch: DIM,
+  skip: DIM,
+  conflict: RED,
+};
+
+function pad(text, width) {
+  return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+
+function formatBytes(n) {
+  if (n === undefined || n === null) return '';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+
+/**
+ * The parenthetical after a path: whatever the engine said, plus the sha and
+ * size on a line that put bytes somewhere.
+ */
+function detailFor(action) {
+  const parts = [];
+  if (action.outcome === 'failed' && action.error) {
+    parts.push(`FAILED: ${action.error}`);
+  } else if (action.reason) {
+    parts.push(action.reason);
+  }
+  if ((action.kind === 'create' || action.kind === 'modify') && action.sha256) {
+    const size = formatBytes(action.sizeBytes);
+    parts.push(`sha ${action.sha256.slice(0, 4)}…${size ? `, ${size}` : ''}`);
+  }
+  return parts.join('; ');
+}
+
+/**
+ * A trailing slash marks a folder, so `drafts/` and a file called `drafts`
+ * are not the same line.
+ */
+function displayPath(action) {
+  return action.entryKind === 'folder' ? `${action.relativePath}/` : action.relativePath;
+}
+
+/**
+ * One line per action.
+ *
+ * `pathWidth` aligns the parenthetical into a column of its own; the caller
+ * computes it once across the whole plan, so a single very long path does not
+ * push every other line's detail off the screen — it is capped.
+ */
+function formatActionLine(action, colour, pathWidth = 0) {
+  const tint = colour
+    ? (action.outcome === 'failed' ? RED : ACTION_COLOURS[action.kind] || '')
+    : '';
+  const reset = tint ? RESET : '';
+  const side = action.side || '—';
+  const detail = detailFor(action);
+  const shownPath = detail ? pad(displayPath(action), pathWidth) : displayPath(action);
+  const head = `${tint}${pad(action.kind, ACTION_WIDTH)}${reset} ${pad(side, SIDE_WIDTH)} ${shownPath}`;
+  if (!detail) return head;
+  return colour ? `${head}  ${DIM}(${detail})${RESET}` : `${head}  (${detail})`;
+}
+
+/** Longest path that carries a detail, capped so one outlier cannot ruin the column. */
+const MAX_PATH_COLUMN = 44;
+
+function formatActionLines(actions, colour) {
+  const pathWidth = Math.min(
+    MAX_PATH_COLUMN,
+    actions.reduce(
+      (widest, action) => (detailFor(action) ? Math.max(widest, displayPath(action).length) : widest),
+      0
+    )
+  );
+  return actions.map((action) => formatActionLine(action, colour, pathWidth));
+}
+
+/** `3 created, 1 modified, … — 0.8 s`, or a plain "nothing to do". */
+function formatSummary(summary, elapsedMs, dryRun) {
+  const bits = [];
+  if (summary.created) bits.push(`${summary.created} created`);
+  if (summary.modified) bits.push(`${summary.modified} modified`);
+  if (summary.deleted) bits.push(`${summary.deleted} deleted`);
+  if (summary.touched) bits.push(`${summary.touched} touched`);
+  if (summary.described) bits.push(`${summary.described} described`);
+  if (summary.skipped) bits.push(`${summary.skipped} skipped`);
+  if (summary.conflicts) bits.push(`${summary.conflicts} conflict${summary.conflicts === 1 ? '' : 's'}`);
+  if (summary.failed) bits.push(`${summary.failed} failed`);
+
+  const seconds = `${(elapsedMs / 1000).toFixed(1)} s`;
+  const prefix = dryRun ? 'Would do: ' : '';
+  if (bits.length === 0) {
+    return dryRun ? `Nothing to do — ${seconds}` : `Already in step — ${seconds}`;
+  }
+  return `${prefix}${bits.join(', ')} — ${seconds}`;
+}
+
+/**
+ * The process exit code a report earns.
+ *
+ *   0  clean
+ *   1  something failed outright
+ *   2  at least one conflict is still unresolved
+ *
+ * `--dry-run` uses the same codes, so a script can gate on a clean plan before
+ * it lets a real run proceed.
+ */
+function exitCodeFor(summary) {
+  if (summary.failed > 0) return 1;
+  if (summary.conflicts > 0) return 2;
+  return 0;
+}
+
+module.exports = {
+  formatActionLine,
+  formatActionLines,
+  formatSummary,
+  exitCodeFor,
+  detailFor,
+  displayPath,
+  formatBytes,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.10.0-dev.51",
+  "version": "4.10.0-dev.57",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",