quilltap 4.10.0-dev.50 → 4.10.0-dev.54

package/README.md

@@ -219,6 +219,33 @@ Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous na
 
 `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`).
 
+## 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
+```
+
+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. 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, an archived character's vault, a store mid-conversion or mid-scan, and a manifest belonging to another store.
+
 ## 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.

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.50",
+  "version": "4.10.0-dev.54",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",