quilltap 4.8.0-dev.98 → 4.9.0-dev

package/README.md

@@ -187,6 +187,7 @@ quilltap docs status                            # Per-mount extraction + embeddi
 quilltap docs scan <mount>                                    # Trigger a rescan
 quilltap docs reindex <mount> [path] [--force]                # Re-extract + re-chunk
 quilltap docs embed <mount> [path] [--force] [--wait]         # Enqueue embedding jobs
+quilltap docs grep --semantic [--top N] [--threshold 0..1] <query>  # Embedding search over indexed chunks
 quilltap docs write [--force] [--base64] <mount> <path> [file]  # Stdin or file → mount
 quilltap docs read [--rendered] [--base64] <mount> <path>       # File contents → stdout
 quilltap docs delete <mount> <path>                           # Idempotent delete
@@ -226,6 +227,7 @@ 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 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.

package/bin/quilltap.js

@@ -717,6 +717,20 @@ Subcommands (high-level shortcuts; auto-pick the right database):
                               Prompts/ and Scenarios/ folder counts, and any
                               divergence between DB columns and vault content.
                               (flags: --id <id|name> --diverged --blocked --limit N)
+  characters archives         List archived characters and ARCHIVE bundles on
+                              the shelf, loose bundles included. Read-only.
+  characters archive <name|id> --write [--port N]
+                              Archive a character via the RUNNING server (it
+                              holds the export pipeline and the passphrase).
+  characters rehydrate <name|id> --write [--port N]
+                              Wake an archived character via the running server.
+  characters export <name|id> [--out <path>] [--port N]
+                              Write a PLAINTEXT .qtap for a character. Archived:
+                              decrypts the bundle offline (prompts for the
+                              passphrase on protected instances) — the only way
+                              to reach packed-away mail/photos/summaries without
+                              rehydrating. Live: runs the server's export
+                              pipeline (server must be up). Read-only.
   optimize [target...]        Run maintenance (VACUUM + ANALYZE + PRAGMA optimize)
                               on the named databases, or all of them if no
                               target is given. Targets: main, llm-logs,

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

@@ -59,3 +59,38 @@ describe('CLI subcommand surface stays documented', () => {
     expect(missing).toEqual([]);
   });
 });
+
+/**
+ * A bare substring match is too weak: a subcommand named only in a shared
+ * `case` list still tab-completes its own flags as nothing. These check that
+ * each shell actually has a per-subcommand completion arm — the gap that let
+ * `file-verify` (all three shells) and `recall-replay` (fish) ship with the
+ * verb completing but none of its flags.
+ */
+describe('every subcommand has its own completion arm', () => {
+  function template(shell) {
+    return fs.readFileSync(path.join(COMPLETION_DIR, `${shell}.template`), 'utf8');
+  }
+
+  it('bash has a case arm per subcommand', () => {
+    const tpl = template('bash');
+    const missing = SUBCOMMANDS.filter((sub) => !new RegExp(`^\\s*${sub}\\)\\s*$`, 'm').test(tpl));
+    expect(missing).toEqual([]);
+  });
+
+  it('zsh dispatches every subcommand from _quilltap_subcommand', () => {
+    const tpl = template('zsh');
+    const body = tpl.match(/_quilltap_subcommand\(\) \{([\s\S]*?)\n\}/);
+    expect(body).toBeTruthy();
+    const missing = SUBCOMMANDS.filter((sub) => !new RegExp(`^\\s*${sub}\\)\\s*$`, 'm').test(body[1]));
+    expect(missing).toEqual([]);
+  });
+
+  it('fish offers every subcommand at top level and completes inside it', () => {
+    const tpl = template('fish');
+    const notOffered = SUBCOMMANDS.filter((sub) => !tpl.includes(`-a '${sub}'`));
+    expect(notOffered).toEqual([]);
+    const noFlags = SUBCOMMANDS.filter((sub) => !tpl.includes(`__quilltap_using_subcommand ${sub}'`));
+    expect(noFlags).toEqual([]);
+  });
+});

package/lib/__tests__/docker-mounts.test.js

@@ -0,0 +1,216 @@
+/**
+ * Bind planning for filesystem-backed document stores.
+ *
+ * The planner decides what a container is allowed to see, so its edges matter
+ * more than its happy path: a nested store that shadows its parent, a missing
+ * path that Docker would helpfully materialise as an empty directory, or a
+ * Windows host where the whole path-identical scheme cannot work.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const {
+  planStoreMounts,
+  toDockerArgs,
+  findMissingBinds,
+  normalisePath,
+} = require('../docker-mounts');
+
+/** Build a doc_mount_points-shaped row with sensible defaults. */
+function store(overrides = {}) {
+  return {
+    id: 'id-' + (overrides.name || 'x'),
+    name: 'Store',
+    mountType: 'filesystem',
+    storeType: 'documents',
+    basePath: '/vaults/one',
+    enabled: 1,
+    ...overrides,
+  };
+}
+
+/** A path probe that treats the given list as the only existing directories. */
+const existsIn = (paths) => (p) => paths.includes(p);
+
+const linux = (rows, exists) => planStoreMounts(rows, { platform: 'linux', exists });
+const macos = (rows, exists) => planStoreMounts(rows, { platform: 'darwin', exists });
+
+describe('planStoreMounts', () => {
+  it('binds an enabled filesystem store at its own host path', () => {
+    const plan = linux([store({ name: 'Church', basePath: '/vaults/church' })], existsIn(['/vaults/church']));
+
+    expect(plan.binds).toEqual([
+      { hostPath: '/vaults/church', containerPath: '/vaults/church', stores: ['Church'] },
+    ]);
+  });
+
+  it('treats obsidian stores as filesystem-backed', () => {
+    const plan = linux(
+      [store({ name: 'Malory', mountType: 'obsidian', basePath: '/vaults/malory' })],
+      existsIn(['/vaults/malory'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/malory']);
+  });
+
+  it('ignores database-backed and disabled stores', () => {
+    const plan = linux(
+      [
+        store({ name: 'Vault', mountType: 'database', basePath: '' }),
+        store({ name: 'Off', basePath: '/vaults/off', enabled: 0 }),
+      ],
+      existsIn(['/vaults/off'])
+    );
+
+    expect(plan.binds).toEqual([]);
+  });
+
+  it('emits one bind for several stores sharing a path', () => {
+    const plan = linux(
+      [
+        store({ name: 'Church', basePath: '/vaults/shared' }),
+        store({ name: 'Small Group', basePath: '/vaults/shared/' }),
+      ],
+      existsIn(['/vaults/shared'])
+    );
+
+    expect(plan.binds).toHaveLength(1);
+    expect(plan.binds[0].stores).toEqual(['Church', 'Small Group']);
+  });
+
+  it('drops a store nested inside another bound store', () => {
+    // Binding both would mount the child independently and shadow the
+    // parent's view of that subdirectory.
+    const plan = linux(
+      [
+        store({ name: 'Vault', basePath: '/vaults/obsidian' }),
+        store({ name: 'Notes', basePath: '/vaults/obsidian/notes' }),
+      ],
+      existsIn(['/vaults/obsidian', '/vaults/obsidian/notes'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/obsidian']);
+  });
+
+  it('does not treat a sibling with a shared prefix as nested', () => {
+    const plan = linux(
+      [
+        store({ name: 'A', basePath: '/vaults/notes' }),
+        store({ name: 'B', basePath: '/vaults/notes-archive' }),
+      ],
+      existsIn(['/vaults/notes', '/vaults/notes-archive'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/notes', '/vaults/notes-archive']);
+  });
+
+  it('skips a missing path rather than letting Docker fabricate it', () => {
+    const plan = linux([store({ name: 'Gone', basePath: '/vaults/gone' })], existsIn([]));
+
+    expect(plan.binds).toEqual([]);
+    expect(plan.skipped).toEqual([
+      { hostPath: '/vaults/gone', stores: ['Gone'], reason: 'missing' },
+    ]);
+    expect(plan.warnings.join(' ')).toContain('does not exist');
+  });
+
+  it('rejects a relative base path', () => {
+    const plan = linux([store({ name: 'Rel', basePath: 'relative/path' })], existsIn(['relative/path']));
+
+    expect(plan.binds).toEqual([]);
+    expect(plan.warnings.join(' ')).toContain('not absolute');
+  });
+
+  it('refuses path-identical binds on Windows', () => {
+    const plan = planStoreMounts([store({ basePath: 'C:\\Users\\me\\Vault' })], {
+      platform: 'win32',
+      exists: () => true,
+    });
+
+    expect(plan.unsupported).toBe(true);
+    expect(plan.binds).toEqual([]);
+    expect(plan.warnings.join(' ')).toContain('not supported on Windows');
+  });
+
+  it('warns about macOS paths outside Docker Desktop default shares', () => {
+    const plan = macos([store({ name: 'Odd', basePath: '/data/vault' })], existsIn(['/data/vault']));
+
+    expect(plan.binds).toHaveLength(1);
+    expect(plan.warnings.join(' ')).toContain('File sharing');
+  });
+
+  it('does not warn for macOS paths under a shared prefix', () => {
+    const plan = macos([store({ name: 'Home', basePath: '/Users/me/Vault' })], existsIn(['/Users/me/Vault']));
+
+    expect(plan.warnings.join(' ')).not.toContain('File sharing');
+  });
+
+  it('warns about host ownership on Linux', () => {
+    const plan = linux([store({ basePath: '/vaults/one' })], existsIn(['/vaults/one']));
+
+    expect(plan.warnings.join(' ')).toContain('--user');
+  });
+});
+
+describe('toDockerArgs', () => {
+  it('renders each bind as a -v pair', () => {
+    const plan = linux(
+      [
+        store({ name: 'A', basePath: '/vaults/a' }),
+        store({ name: 'B', basePath: '/vaults/b' }),
+      ],
+      existsIn(['/vaults/a', '/vaults/b'])
+    );
+
+    expect(toDockerArgs(plan)).toEqual([
+      '-v', '/vaults/a:/vaults/a',
+      '-v', '/vaults/b:/vaults/b',
+    ]);
+  });
+
+  it('keeps a path containing spaces in a single argument', () => {
+    // The argv is handed to execFileSync, so a space must not split the pair.
+    const plan = linux([store({ basePath: '/vaults/Local Obsidian' })], existsIn(['/vaults/Local Obsidian']));
+
+    expect(toDockerArgs(plan)).toEqual([
+      '-v', '/vaults/Local Obsidian:/vaults/Local Obsidian',
+    ]);
+  });
+});
+
+describe('findMissingBinds', () => {
+  const plan = () =>
+    linux(
+      [
+        store({ name: 'A', basePath: '/vaults/a' }),
+        store({ name: 'B', basePath: '/vaults/b' }),
+      ],
+      existsIn(['/vaults/a', '/vaults/b'])
+    );
+
+  it('reports binds a container was not created with', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a']).map((b) => b.hostPath)).toEqual(['/vaults/b']);
+  });
+
+  it('reports nothing when every bind is present', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a', '/vaults/b', '/data'])).toEqual([]);
+  });
+
+  it('ignores a trailing separator when comparing', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a/', '/vaults/b/'])).toEqual([]);
+  });
+});
+
+describe('normalisePath', () => {
+  it.each([
+    ['/a/b/', '/a/b'],
+    ['/a//b', '/a/b'],
+    ['/a/./b', '/a/b'],
+    ['/a/c/../b', '/a/b'],
+    ['/', '/'],
+  ])('normalises %s to %s', (input, expected) => {
+    expect(normalisePath(input)).toBe(expected);
+  });
+});

package/lib/completion/bash.template

@@ -121,12 +121,21 @@ _quilltap_complete() {
         else
           COMPREPLY=($(compgen -W "$db_verbs" -- "$cur"))
         fi
+      elif [[ "$subverb" == "characters" ]]; then
+        local char_verbs="status archives archive rehydrate export"
+        local char_flags="--instance --data-dir --passphrase --json --limit --diverged --blocked --id \
+          --write -p --port --out --help"
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$char_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$char_verbs" -- "$cur"))
+        fi
       else
         COMPREPLY=($(compgen -W "$db_flags" -- "$cur"))
       fi
       ;;
     docs)
-      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy link rmdir mvdir status find grep reindex embed"
+      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy link rmdir mvdir status docker-mounts find grep reindex embed"
       local docs_flags="--mount --instance --data-dir --passphrase --port --json --help \
         --force --rendered --links --folder --type --ext --limit --max --context --top --threshold \
         --ignore-case -l --wait -R --recursive --sort -r --reverse --depth --max-nodes --long --semantic"
@@ -244,6 +253,10 @@ _quilltap_complete() {
         COMPREPLY=($(compgen -W "$maint_flags" -- "$cur"))
       fi
       ;;
+    file-verify)
+      local fv_flags="--all --stall-ms --json --instance --data-dir --help"
+      COMPREPLY=($(compgen -W "$fv_flags" -- "$cur"))
+      ;;
     completion)
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--help" -- "$cur"))

package/lib/completion/fish.template

@@ -55,6 +55,7 @@ complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'themes' -d 'Manage the
 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'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memory-diff' -d 'Memory extraction dry-run'
+complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'recall-replay' -d 'Replay memory recall for a turn'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'logs' -d 'Tail or print log files'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'migrations' -d 'Inspect migration status'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'maintenance' -d 'Run retention/cleanup sweeps'
@@ -92,6 +93,14 @@ complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'optimize' -d 'Op
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'backup' -d 'Backup database'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'integrity' -d 'Check integrity'
 
+# db characters sub-subverbs
+complete -c quilltap -n '__quilltap_using_subverb db characters' -f -a 'status' -d 'Per-character vault status report'
+complete -c quilltap -n '__quilltap_using_subverb db characters' -f -a 'archives' -d 'List archived characters and bundles'
+complete -c quilltap -n '__quilltap_using_subverb db characters' -f -a 'archive' -d 'Archive a character (server required)'
+complete -c quilltap -n '__quilltap_using_subverb db characters' -f -a 'rehydrate' -d 'Wake an archived character (server required)'
+complete -c quilltap -n '__quilltap_using_subverb db characters' -f -a 'export' -d 'Write a plaintext .qtap for a character'
+complete -c quilltap -n '__quilltap_using_subverb db characters' -l 'port' -s 'p' -d 'Server port' -x
+
 # db flags
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'limit' -d 'Result limit' -x
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'grep' -d 'Substring search' -x
@@ -135,6 +144,7 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'scan' -d 'Trig
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'find' -d 'Substring search'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'grep' -d 'Pattern search in text'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'status' -d 'Per-mount status'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'docker-mounts' -d 'Binds needed under Docker'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'reindex' -d 'Re-extract and chunk'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'embed' -d 'Enqueue embeddings'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'write' -d 'Write a file'
@@ -261,6 +271,16 @@ complete -c quilltap -n '__quilltap_using_subcommand memory-diff' -l 'port' -s '
 complete -c quilltap -n '__quilltap_using_subcommand memory-diff' -l 'concurrency' -d 'Concurrency limit' -x
 complete -c quilltap -n '__quilltap_using_subcommand memory-diff' -l 'out' -d 'Output file' -r -F
 
+# ---------- recall-replay flags ----------
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'turn' -d 'Interchange to replay (1-based)' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'char' -d 'Character whose memories are searched' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'limit' -d 'Candidate rows per path' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'port' -d 'Server port' -x
+
+# ---------- file-verify flags ----------
+complete -c quilltap -n '__quilltap_using_subcommand file-verify' -l 'all' -d 'Read every top-level file, not just dataless ones'
+complete -c quilltap -n '__quilltap_using_subcommand file-verify' -l 'stall-ms' -d 'Per-chunk stall threshold (ms)' -x
+
 # ---------- logs flags ----------
 complete -c quilltap -n '__quilltap_using_subcommand logs' -l 'stream' -d 'Log stream' -x -a 'combined error stdout stderr startup'
 complete -c quilltap -n '__quilltap_using_subcommand logs' -l 'tail' -d 'Last N lines (0=full)' -x

package/lib/completion/zsh.template

@@ -85,6 +85,9 @@ _quilltap_subcommand() {
     maintenance)
       _quilltap_maintenance
       ;;
+    file-verify)
+      _arguments '--all[read every top-level file, not just dataless ones]' '--stall-ms[per-chunk stall threshold in ms]:ms:' '--json[machine-readable output]' '--help[show help]'
+      ;;
     completion)
       _quilltap_completion
       ;;
@@ -146,7 +149,39 @@ _quilltap_db() {
 
   if (( CURRENT == 2 )); then
     _describe 'db subcommand' subverbs
+    return
+  fi
+
+  if [[ "$words[2]" == "characters" ]]; then
+    local -a char_verbs char_opts
+    char_verbs=(
+      'status:Per-character vault status report'
+      'archives:List archived characters and ARCHIVE bundles'
+      'archive:Archive a character (runs through the server)'
+      'rehydrate:Wake an archived character (runs through the server)'
+      'export:Write a plaintext .qtap for a character'
+    )
+    char_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:'
+      '--json[JSON output]'
+      '--limit[Result limit]:limit:'
+      '--diverged[Only characters whose DB and vault differ]'
+      '--blocked[Only characters with vault issues]'
+      '--id[Single character by name or id]:character:'
+      '--write[Perform the archive/rehydrate write]'
+      '(-p --port)'{-p,--port}'[Server port]:port:'
+      '--out[Output .qtap path]:path:_files'
+      '(-h --help)'{-h,--help}'[Show help]'
+    )
+    if (( CURRENT == 3 )); then
+      _describe 'characters subcommand' char_verbs
+    fi
+    _arguments $char_opts
+    return
   fi
+
   _arguments $db_opts
 }
 
@@ -165,6 +200,7 @@ _quilltap_docs() {
     'find:Substring search'
     'grep:Pattern search inside text'
     'status:Per-mount status'
+    'docker-mounts:Bind mounts needed under Docker'
     'reindex:Re-extract and re-chunk'
     'embed:Enqueue embedding jobs'
     'write:Write a file'

package/lib/db-commands.js

@@ -922,13 +922,26 @@ function inspectCharacterVault(row, mounts) {
   return status;
 }
 
-function cmdCharacters(args, ctx) {
+async function cmdCharacters(args, ctx) {
   const { flags, positional } = parseSubArgs(args);
   const sub = positional[0] || 'status';
-  if (sub !== 'status') {
-    throw new Error(`Unknown characters subcommand: ${sub}. Try: status`);
+  switch (sub) {
+    case 'status':
+      return cmdCharactersStatus(flags, ctx);
+    case 'archives':
+      return cmdCharactersArchives(flags, ctx);
+    case 'archive':
+      return cmdCharactersArchiveVerb('archive', positional[1], flags, ctx);
+    case 'rehydrate':
+      return cmdCharactersArchiveVerb('rehydrate', positional[1], flags, ctx);
+    case 'export':
+      return cmdCharactersExport(positional[1], flags, ctx);
+    default:
+      throw new Error(`Unknown characters subcommand: ${sub}. Try: status, archives, archive, rehydrate, export`);
   }
+}
 
+function cmdCharactersStatus(flags, ctx) {
   const json = asBool(flags.json);
   const limit = asInt(flags.limit, 0);
   const onlyDiverged = asBool(flags.diverged);
@@ -1042,6 +1055,258 @@ function summarizeCharacterStatuses(all) {
   return { ok, diverged, missingFiles, noVault, empty, physIncomplete };
 }
 
+// ---------- characters: archive shelf ----------
+
+const ARCHIVE_MAGIC = Buffer.from('QTAPARC1', 'ascii');
+const ARCHIVE_INTERNAL_PASSPHRASE = '__quilltap_no_passphrase__';
+
+/**
+ * List archived characters and the ARCHIVE bundle files on the shelf,
+ * including loose bundles (files rows no character points at — the survivors
+ * of a "keep archived bundles" wipe). Read-only.
+ */
+function cmdCharactersArchives(flags, ctx) {
+  const json = asBool(flags.json);
+  const main = ctx.openMain();
+  try {
+    const cols = new Set(main.prepare('PRAGMA table_info(characters)').all().map(r => r.name));
+    if (!cols.has('archivedAt')) {
+      console.log('This database predates character archiving (no archivedAt column).');
+      return;
+    }
+    const archived = main.prepare(
+      'SELECT id, name, archivedAt, archiveFileId FROM characters WHERE archivedAt IS NOT NULL ORDER BY archivedAt DESC'
+    ).all();
+    const bundles = main.prepare(
+      "SELECT id, originalFilename, storageKey, size, createdAt FROM files WHERE category = 'ARCHIVE' ORDER BY createdAt DESC"
+    ).all();
+
+    const referenced = new Set(archived.map(c => c.archiveFileId).filter(Boolean));
+    const looseBundles = bundles.filter(b => !referenced.has(b.id));
+
+    if (json) {
+      return printJson({ archivedCharacters: archived, bundles, looseBundles });
+    }
+
+    if (archived.length === 0 && bundles.length === 0) {
+      console.log('The archive shelf stands empty — no archived characters, no bundles.');
+      return;
+    }
+
+    if (archived.length > 0) {
+      console.log(`Archived characters (${archived.length}):`);
+      printTable(archived.map(c => ({
+        id: c.id.slice(0, 8),
+        name: truncate(c.name, 28),
+        archivedAt: c.archivedAt,
+        bundle: c.archiveFileId ? c.archiveFileId.slice(0, 8) : '(none — pre-bundle tombstone)',
+      })));
+    }
+    if (bundles.length > 0) {
+      console.log('');
+      console.log(`Archive bundles (${bundles.length}${looseBundles.length > 0 ? `, ${looseBundles.length} loose` : ''}):`);
+      printTable(bundles.map(b => ({
+        id: b.id.slice(0, 8),
+        file: truncate(b.originalFilename, 44),
+        bytes: b.size,
+        createdAt: b.createdAt,
+        state: referenced.has(b.id) ? 'held by character' : 'loose (importable only)',
+      })));
+    }
+  } finally {
+    try { main.close(); } catch {}
+  }
+}
+
+/**
+ * Archive or rehydrate a character through the RUNNING server's API. The
+ * archive pipeline (export, encryption, prune) and the passphrase cache live
+ * in the server process — the CLI cannot run them against the raw database —
+ * so the server must be up, and it is the server that holds the instance
+ * lock. `--write` is still required as the explicit opt-in to a write.
+ */
+async function cmdCharactersArchiveVerb(verb, query, flags, ctx) {
+  if (!query) {
+    throw new Error(`Usage: characters ${verb} <name|id> --write [--port N]`);
+  }
+  if (!asBool(flags.write)) {
+    throw new Error(`characters ${verb} changes data; add --write to proceed.`);
+  }
+  const port = asInt(flags.port, 3000);
+
+  const main = ctx.openMain();
+  let character;
+  try {
+    character = resolveCharacter(main, String(query), ctx.openMounts);
+  } finally {
+    try { main.close(); } catch {}
+  }
+
+  const url = `http://localhost:${port}/api/v1/characters/${encodeURIComponent(character.id)}?action=${verb}`;
+  let res;
+  try {
+    res = await fetch(url, { method: 'POST' });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the Quilltap server at http://localhost:${port}: ${err.message}\n` +
+      `The ${verb} operation runs inside the server (it needs the export pipeline and the ` +
+      'unlocked passphrase), so start the server first.'
+    );
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(body.error || `${verb} failed with HTTP ${res.status}`);
+  }
+
+  if (asBool(flags.json)) return printJson(body);
+  if (verb === 'archive') {
+    console.log(
+      body.pruneComplete === false
+        ? `${character.name} is archived, but the prune did not finish — run the same command again to complete it.`
+        : `${character.name} rests in the archive. Bundle file: ${body.archiveFileId || '(none)'}.`
+    );
+  } else {
+    const r = body.restored;
+    console.log(
+      r
+        ? `${character.name} is awake again — ${r.memories} memories, ${r.documents} documents, ${r.blobs} blobs restored.`
+        : `${character.name} is awake again.`
+    );
+    if (body.archiveBundleFileId) {
+      console.log(`The archive bundle stays in the file library (file ${body.archiveBundleFileId}); delete it there if you no longer want the spare copy.`);
+    }
+    for (const w of body.warnings || []) console.log(`warning: ${w}`);
+  }
+}
+
+/** Parse + decrypt a QTAPARC1 bundle. Returns null on a wrong passphrase. */
+function tryDecryptArchiveBundle(data, passphrase) {
+  const crypto = require('crypto');
+  const headerLength = data.readUInt32BE(ARCHIVE_MAGIC.length);
+  const bodyStart = ARCHIVE_MAGIC.length + 4 + headerLength;
+  if (headerLength <= 0 || data.length < bodyStart + 16) {
+    throw new Error('Archive bundle is truncated (bad header or missing auth tag).');
+  }
+  const header = JSON.parse(data.subarray(ARCHIVE_MAGIC.length + 4, bodyStart).toString('utf8'));
+  const salt = Buffer.from(header.salt, 'hex');
+  const iv = Buffer.from(header.iv, 'hex');
+  const key = crypto.pbkdf2Sync(passphrase, new Uint8Array(salt), header.kdfIterations, 32, header.kdfDigest);
+  const keyHash = crypto.createHash('sha256').update(new Uint8Array(key)).digest('hex');
+  if (keyHash !== header.keyHash) return null;
+
+  const ciphertext = data.subarray(bodyStart, data.length - 16);
+  const authTag = data.subarray(data.length - 16);
+  const decipher = crypto.createDecipheriv(header.algorithm, new Uint8Array(key), new Uint8Array(iv));
+  decipher.setAuthTag(new Uint8Array(authTag));
+  return Buffer.concat([decipher.update(new Uint8Array(ciphertext)), decipher.final()]);
+}
+
+/**
+ * Export a character as a plaintext `.qtap` — the interchange escape hatch.
+ *
+ * Archived characters: decrypt their bundle straight off the disk (offline;
+ * prompts for the passphrase on protected instances). This is the only way to
+ * reach an archived character's packed-away material — mail, photographs,
+ * summaries — without rehydrating. Live characters: proxy to the running
+ * server's export pipeline. Read-only either way.
+ */
+async function cmdCharactersExport(query, flags, ctx) {
+  if (!query) {
+    throw new Error('Usage: characters export <name|id> [--out <path>] [--port N]');
+  }
+
+  const main = ctx.openMain();
+  let character;
+  let archiveFile = null;
+  try {
+    character = resolveCharacter(main, String(query), ctx.openMounts);
+    const cols = new Set(main.prepare('PRAGMA table_info(characters)').all().map(r => r.name));
+    if (cols.has('archivedAt')) {
+      const row = main.prepare('SELECT archivedAt, archiveFileId FROM characters WHERE id = ?').get(character.id);
+      if (row && row.archivedAt && row.archiveFileId) {
+        archiveFile = main.prepare('SELECT id, storageKey, sha256 FROM files WHERE id = ?').get(row.archiveFileId);
+        if (!archiveFile) {
+          throw new Error(`${character.name} is archived but their bundle file row (${row.archiveFileId}) is missing.`);
+        }
+      } else if (row && row.archivedAt) {
+        throw new Error(`${character.name} is a pre-bundle tombstone (no archive bundle exists to export).`);
+      }
+    }
+  } finally {
+    try { main.close(); } catch {}
+  }
+
+  const safeName = String(character.name || character.id).replace(/[\\/:*?"<>|]/g, '_');
+  const outPath = path.resolve(flags.out ? String(flags.out) : `${safeName}.qtap`);
+
+  let plaintext;
+  if (archiveFile) {
+    if (!archiveFile.storageKey) {
+      throw new Error('The bundle row has no storage key; the file was never written.');
+    }
+    const bundlePath = path.join(ctx.dataDir, '..', 'files', archiveFile.storageKey);
+    if (!fs.existsSync(bundlePath)) {
+      throw new Error(`Bundle bytes not found on disk: ${bundlePath}`);
+    }
+    const data = fs.readFileSync(bundlePath);
+
+    if (!data.subarray(0, ARCHIVE_MAGIC.length).equals(ARCHIVE_MAGIC)) {
+      // Pre-encryption plaintext bundle — pass it through untouched.
+      plaintext = data;
+    } else {
+      plaintext = tryDecryptArchiveBundle(data, ARCHIVE_INTERNAL_PASSPHRASE);
+      if (plaintext === null && process.env.QUILLTAP_DB_PASSPHRASE) {
+        plaintext = tryDecryptArchiveBundle(data, process.env.QUILLTAP_DB_PASSPHRASE);
+      }
+      if (plaintext === null) {
+        const { promptPassphrase } = require('./db-helpers');
+        const pass = await promptPassphrase('Archive passphrase: ');
+        if (pass) plaintext = tryDecryptArchiveBundle(data, pass);
+      }
+      if (plaintext === null) {
+        throw new Error(
+          'That passphrase does not open this archive. If you changed your passphrase and this ' +
+          'bundle was reported left behind, it still wants the old one.'
+        );
+      }
+    }
+  } else {
+    // Live character: the export pipeline lives in the server.
+    const port = asInt(flags.port, 3000);
+    const url = `http://localhost:${port}/api/v1/system/tools?action=export`;
+    let res;
+    try {
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          type: 'characters',
+          scope: 'selected',
+          selectedIds: [character.id],
+          includeMemories: true,
+        }),
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not reach the Quilltap server at http://localhost:${port}: ${err.message}\n` +
+        'Exporting a live character runs the server\'s export pipeline, so start the server first. ' +
+        '(Archived characters export offline from their bundle.)'
+      );
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body.error || `Export failed with HTTP ${res.status}`);
+    }
+    plaintext = Buffer.from(await res.arrayBuffer());
+  }
+
+  fs.writeFileSync(outPath, plaintext);
+  console.log(`Wrote ${plaintext.length} bytes to ${outPath}`);
+  if (archiveFile) {
+    console.log('This is the decrypted archive bundle — a plaintext .qtap. Guard it accordingly.');
+  }
+}
+
 // ---------- verb: optimize ----------
 
 const OPTIMIZE_TARGETS = {

package/lib/docker-mounts.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Docker Bind Planning for Filesystem Document Stores
+ *
+ * A container sees only the host paths handed to it at creation time. Database
+ * -backed stores live inside the data directory and ride along on the single
+ * bind every Quilltap container already has; filesystem and Obsidian stores
+ * point anywhere on the host and are, by default, simply absent inside the
+ * container — the store lists happily from the cached mount index while every
+ * read and write against the real bytes fails.
+ *
+ * This module turns "what stores does this instance have" into "what -v flags
+ * does the container need". It is deliberately pure: the caller supplies the
+ * store rows, the platform, and a path probe, so the planner can be tested
+ * without a database, a filesystem, or Docker.
+ *
+ * ## Why the binds are path-identical
+ *
+ * Each store is bound at its own host path (`-v /host/vault:/host/vault`) so
+ * the `basePath` recorded in the database resolves unchanged whether Quilltap
+ * runs natively or in a container. The alternative — mounting under some
+ * container-local prefix — would require a translation layer on every path in
+ * and out of the database, and would make the same instance directory
+ * unusable outside the container.
+ *
+ * Docker creates missing destination ancestors itself, as root and mode 0755,
+ * during mount setup — so binding `/Users/you/Vault` into an image that has no
+ * `/Users` works, and the unprivileged app user can still traverse in. Those
+ * ancestors are *not* writable by the app user, which is a feature: a store
+ * that was never bound stays structurally unwritable rather than quietly
+ * accumulating a fabricated directory tree.
+ *
+ * @module docker-mounts
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Prefixes Docker Desktop for macOS shares with the VM out of the box. A bind
+ * whose source falls outside these is accepted by `docker run` but arrives in
+ * the container as an empty directory, which is a uniquely confusing failure —
+ * so it earns a warning rather than silence.
+ */
+const MACOS_DEFAULT_SHARED_PREFIXES = ['/Users', '/Volumes', '/private', '/tmp', '/var/folders'];
+
+/** Store types whose bytes live on the host filesystem rather than in the database. */
+const FILESYSTEM_MOUNT_TYPES = new Set(['filesystem', 'obsidian']);
+
+/**
+ * Normalise a base path for comparison: resolve `.`/`..`, collapse separators,
+ * and drop any trailing separator so `/a/b` and `/a/b/` are one path.
+ */
+function normalisePath(basePath) {
+  const resolved = path.posix.normalize(String(basePath).trim());
+  if (resolved.length > 1 && resolved.endsWith('/')) {
+    return resolved.slice(0, -1);
+  }
+  return resolved;
+}
+
+/** True when `candidate` sits inside `ancestor` (and is not `ancestor` itself). */
+function isDescendantOf(candidate, ancestor) {
+  return candidate.startsWith(ancestor.endsWith('/') ? ancestor : ancestor + '/');
+}
+
+/**
+ * Plan the bind mounts an instance's filesystem-backed stores require.
+ *
+ * @param {Array<object>} rows - doc_mount_points rows (id, name, mountType, basePath, enabled)
+ * @param {object} [options]
+ * @param {string} [options.platform] - process.platform value; defaults to the current host
+ * @param {(p: string) => boolean} [options.exists] - path probe, injectable for tests
+ * @returns {{binds: Array<object>, skipped: Array<object>, warnings: Array<string>, unsupported: boolean}}
+ */
+function planStoreMounts(rows, options = {}) {
+  const platform = options.platform || process.platform;
+  const exists =
+    options.exists ||
+    ((p) => {
+      try {
+        return fs.statSync(p).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+
+  const warnings = [];
+
+  // Windows host paths (C:\Users\…) have no in-container equivalent, so the
+  // path-identical scheme this module depends on cannot work there. Say so
+  // plainly rather than emitting binds that would silently misbehave.
+  if (platform === 'win32') {
+    return {
+      binds: [],
+      skipped: [],
+      warnings: [
+        'Automatic store binds are not supported on Windows: container paths cannot mirror ' +
+          'Windows host paths. Filesystem document stores must be bound manually.',
+      ],
+      unsupported: true,
+    };
+  }
+
+  const candidates = rows.filter(
+    (r) => FILESYSTEM_MOUNT_TYPES.has(r.mountType) && r.enabled && String(r.basePath || '').trim()
+  );
+
+  // Group stores by normalised path first — several stores commonly share one
+  // vault root, and they need exactly one bind between them.
+  const byPath = new Map();
+  for (const row of candidates) {
+    const normalised = normalisePath(row.basePath);
+    if (!path.posix.isAbsolute(normalised)) {
+      warnings.push(`Skipping store '${row.name}': base path '${row.basePath}' is not absolute.`);
+      continue;
+    }
+    if (!byPath.has(normalised)) {
+      byPath.set(normalised, []);
+    }
+    byPath.get(normalised).push(row.name);
+  }
+
+  const allPaths = [...byPath.keys()].sort();
+
+  const binds = [];
+  const skipped = [];
+
+  for (const hostPath of allPaths) {
+    const stores = byPath.get(hostPath);
+
+    // A path nested inside another selected path is already covered by that
+    // bind. Binding both is redundant, and Docker mounts them independently —
+    // which would shadow the parent's view of the child directory.
+    const ancestor = allPaths.find((other) => other !== hostPath && isDescendantOf(hostPath, other));
+    if (ancestor) {
+      continue;
+    }
+
+    if (!exists(hostPath)) {
+      // Never create the source. Docker would happily materialise a missing
+      // bind source as a root-owned empty directory, which presents an empty
+      // store as a healthy one — the exact failure this feature exists to end.
+      skipped.push({ hostPath, stores, reason: 'missing' });
+      continue;
+    }
+
+    if (platform === 'darwin' && !MACOS_DEFAULT_SHARED_PREFIXES.some((p) => hostPath === p || isDescendantOf(hostPath, p))) {
+      warnings.push(
+        `'${hostPath}' is outside Docker Desktop's default shared paths. Add it under ` +
+          'Settings → Resources → File sharing, or the store will appear empty in the container.'
+      );
+    }
+
+    binds.push({ hostPath, containerPath: hostPath, stores });
+  }
+
+  if (platform === 'linux' && binds.length > 0) {
+    warnings.push(
+      'On Linux, bind mounts preserve host ownership. If the container user cannot write to ' +
+        'these paths, start the container with --user "$(id -u):$(id -g)".'
+    );
+  }
+
+  for (const entry of skipped) {
+    warnings.push(
+      `Skipping '${entry.hostPath}' (${entry.stores.join(', ')}): the path does not exist on this host.`
+    );
+  }
+
+  return { binds, skipped, warnings, unsupported: false };
+}
+
+/** Render a plan as `docker run` arguments. */
+function toDockerArgs(plan) {
+  const args = [];
+  for (const bind of plan.binds) {
+    args.push('-v', `${bind.hostPath}:${bind.containerPath}`);
+  }
+  return args;
+}
+
+/**
+ * Compare a plan against the binds a container was actually created with.
+ * Returns the host paths a running container is missing, which is what tells
+ * an operator that a restart is owed.
+ */
+function findMissingBinds(plan, existingSources) {
+  const existing = new Set(existingSources.map(normalisePath));
+  return plan.binds.filter((b) => !existing.has(b.hostPath));
+}
+
+module.exports = {
+  planStoreMounts,
+  toDockerArgs,
+  findMissingBinds,
+  normalisePath,
+  FILESYSTEM_MOUNT_TYPES,
+  MACOS_DEFAULT_SHARED_PREFIXES,
+};

package/lib/docs-commands.js

@@ -71,8 +71,13 @@ Read subcommands:
   grep [--mount <name|id|all>] [--ignore-case] [-l] [--max N] [--context N] <pattern>
                                          Substring search inside extracted text
   status [--mount <name|id>] [--top N]   Per-mount extraction + embedding rollup
+  docker-mounts [--format args|json]     Bind mounts this instance's filesystem
+                                         stores need to be visible in Docker
 
 Server-required subcommands (background-job queue lives in the running server):
+  grep --semantic [--mount <name|id|all>] [--top N] [--threshold 0..1] <query>
+                                         Embedding search over indexed chunks
+                                         (default --top 20, --threshold 0.5)
   reindex <mount> [path] [--force]       Re-extract text + re-chunk affected files
   embed <mount> [path] [--force] [--wait]
                                          Enqueue embedding jobs for un-embedded chunks
@@ -81,9 +86,9 @@ Write subcommands (server required for database-backed mounts):
   write [--force] [--base64] <mount> <path> [file]  Write a file from <file> or stdin
   delete <mount> <path>                              Idempotent file delete
   mkdir <mount> <path>                               Idempotent folder create
-  move <srcMount> <srcPath> <dstMount> <dstPath>                   Move file (hard-link when possible)
-  copy [--force] <srcMount> <srcPath> <dstMount> <dstPath>         Copy file (hard-link unless --force)
-  link <srcMount> <srcPath> <dstMount> <dstPath>                   Hard-link file (server-required)
+  move <srcMount> <srcPath> <dstMount> <dstPath>                   Move file (relocates the link; no byte copy)
+  copy [--force] <srcMount> <srcPath> <dstMount> <dstPath>         Copy file (independent; shares bytes until either side is written)
+  link <srcMount> <srcPath> <dstMount> <dstPath>                   Hard-link file — one file, two paths; edits show at both (server-required)
   rmdir <mount> <path>                               Delete an empty folder (server-required)
   mvdir <mount> <fromPath> <toPath>                  Rename/move a folder (server-required)
 
@@ -114,14 +119,17 @@ Options:
                             file size, or hard-link count
   -r, --reverse             Reverse sort order
   --links                   For 'ls' / 'dir': under each file with more than
-                            one hard link, list the other mount/path entries
+                            one hard link, list the other mount/path entries.
+                            Counts deliberate links made with 'docs link' — not
+                            unrelated files that merely share identical bytes
   --depth N                 For 'tree': maximum nesting depth (default: 20)
   --max-nodes N             For 'tree': maximum nodes to render (default: 1000)
   --long                    For 'tree': include text/emb columns (reserved for future)
   --force                   For 'read': dump binary to TTY anyway
                             For 'write': overwrite existing destination
                             For 'copy':  overwrite + force a real byte copy
-                                         (skips the default hard-link path)
+                                         (skips the default shared-content path;
+                                          the end state is the same either way)
   --base64                  For 'write': send content as base64 JSON via PUT
                                          .../files/{path} (portable path used
                                          by the file browser; server-required)
@@ -158,6 +166,7 @@ Examples:
   quilltap docs find --mount notes --ext md Knowledge
   quilltap docs grep --mount notes --ignore-case "five-point Calvinist"
   quilltap docs grep --mount notes -l "TODO"
+  quilltap docs grep --semantic --mount notes --top 10 "what did we decide about pricing"
   quilltap docs read qtap://notes/today.md
   quilltap docs find --uri Manifesto
   quilltap docs status
@@ -203,6 +212,8 @@ function parseFlags(args) {
     threshold: -1,
     // base64 read/write flag
     base64: false,
+    // docker-mounts output shape: table (human), args (docker run flags), json
+    format: '',
   };
   const positional = [];
   let i = 0;
@@ -222,6 +233,7 @@ function parseFlags(args) {
         break;
       }
       case '--json': flags.json = true; break;
+      case '--format': flags.format = args[++i]; break;
       case '--uri': flags.uri = true; break;
       case '--rendered': flags.rendered = true; break;
       case '--folder': flags.folder = args[++i]; break;
@@ -480,6 +492,95 @@ async function handleList(flags) {
   }
 }
 
+// ----------------------------------------------------------------------------
+// docker-mounts
+// ----------------------------------------------------------------------------
+
+/**
+ * Report the bind mounts this instance's filesystem-backed stores need in
+ * order to be reachable from inside a container.
+ *
+ * `--format args` prints only the flags, one per line, so a start script can
+ * splice them into a `docker run` argv without parsing prose. Everything
+ * advisory goes to stderr for exactly that reason: stdout stays machine-clean
+ * even when there are warnings worth a human's attention.
+ */
+async function handleDockerMounts(flags) {
+  const { planStoreMounts, toDockerArgs } = require('./docker-mounts');
+  const { db } = await openDb(flags);
+
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT id, name, mountType, storeType, basePath, enabled
+      FROM doc_mount_points
+      WHERE mountType != 'database'
+      ORDER BY name COLLATE NOCASE
+    `).all();
+  } finally {
+    db.close();
+  }
+
+  const plan = planStoreMounts(rows);
+  const format = flags.format || (flags.json ? 'json' : 'table');
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+    return;
+  }
+
+  if (format === 'args') {
+    for (const arg of toDockerArgs(plan)) {
+      process.stdout.write(arg + '\n');
+    }
+    for (const warning of plan.warnings) {
+      process.stderr.write(`warning: ${warning}\n`);
+    }
+    return;
+  }
+
+  if (plan.unsupported) {
+    for (const warning of plan.warnings) {
+      console.log(`${YELLOW}${warning}${RESET}`);
+    }
+    return;
+  }
+
+  if (plan.binds.length === 0 && plan.skipped.length === 0) {
+    console.log('(no filesystem-backed document stores — nothing to bind)');
+    return;
+  }
+
+  if (plan.binds.length > 0) {
+    console.log(`${BOLD}Bind mounts required:${RESET}`);
+    console.table(
+      plan.binds.map((b) => ({
+        'host path': b.hostPath,
+        stores: b.stores.join(', '),
+      }))
+    );
+  }
+
+  if (plan.skipped.length > 0) {
+    console.log(`${BOLD}Skipped:${RESET}`);
+    console.table(
+      plan.skipped.map((s) => ({
+        'host path': s.hostPath,
+        stores: s.stores.join(', '),
+        reason: s.reason,
+      }))
+    );
+  }
+
+  for (const warning of plan.warnings) {
+    console.log(`${YELLOW}warning:${RESET} ${warning}`);
+  }
+
+  console.log('');
+  console.log(`${DIM}Binds are applied when a container is created. Re-run the start script`);
+  console.log(`with --recreate to rebuild the container with these stores included.${RESET}`);
+}
+
 // ----------------------------------------------------------------------------
 // show
 // ----------------------------------------------------------------------------
@@ -620,21 +721,51 @@ function formatLsDate(iso) {
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
 }
 
-const LS_FILE_COLUMNS = `
+// Cached per process: one PRAGMA per run, not one per prepared statement.
+let linkGroupColumnPresent = null;
+
+function hasLinkGroupColumn(db) {
+  if (linkGroupColumnPresent !== null) return linkGroupColumnPresent;
+  try {
+    const cols = db.prepare(`PRAGMA table_info("doc_mount_file_links")`).all();
+    linkGroupColumnPresent = cols.some((c) => c.name === 'linkGroupId');
+  } catch {
+    linkGroupColumnPresent = false;
+  }
+  return linkGroupColumnPresent;
+}
+
+// The "links" column counts deliberate hard links — members of this file's
+// linkGroupId — NOT rows sharing a fileId. Content rows are addressed by
+// sha256, so a boilerplate or empty file collects dozens of unrelated links
+// that share its bytes purely by coincidence; reporting those as links told
+// the operator a file was linked into 36 stores when nothing had been linked
+// at all. An instance that hasn't run the linkGroupId migration yet degrades
+// to 1 rather than failing the whole listing.
+function lsFileColumns(db) {
+  const present = hasLinkGroupColumn(db);
+  const linkCount = present
+    ? `(CASE WHEN l.linkGroupId IS NULL THEN 1 ELSE
+         (SELECT COUNT(*) FROM doc_mount_file_links g WHERE g.linkGroupId = l.linkGroupId) END)`
+    : `1`;
+  const linkGroupId = present ? `l.linkGroupId` : `NULL`;
+  return `
+  ${linkGroupId} AS linkGroupId,
   l.id AS linkId, l.fileId, l.relativePath, l.fileName, l.lastModified,
   l.extractionStatus, l.extractedTextSha256, l.chunkCount,
   f.fileType, f.fileSizeBytes, f.source, f.sha256,
-  (SELECT COUNT(*) FROM doc_mount_file_links WHERE fileId = l.fileId) AS linkCount,
+  ${linkCount} AS linkCount,
   (SELECT COUNT(*) FROM doc_mount_chunks
     WHERE linkId = l.id AND embedding IS NOT NULL) AS embeddedChunkCount
 `;
+}
 
 function resolveLsTarget(db, mountId, normalizedPath) {
   if (!normalizedPath) return { kind: 'root', path: '' };
 
   // Exact file match wins — handles the single-file display mode.
   const file = db.prepare(`
-    SELECT ${LS_FILE_COLUMNS}
+    SELECT ${lsFileColumns(db)}
     FROM doc_mount_file_links l
     JOIN doc_mount_files f ON f.id = l.fileId
     WHERE l.mountPointId = ? AND l.relativePath = ?
@@ -688,7 +819,7 @@ function fetchLsRows(db, mountId, parentPath) {
 
   const files = parentPath === ''
     ? db.prepare(`
-        SELECT ${LS_FILE_COLUMNS}
+        SELECT ${lsFileColumns(db)}
         FROM doc_mount_file_links l
         JOIN doc_mount_files f ON f.id = l.fileId
         WHERE l.mountPointId = ?
@@ -696,7 +827,7 @@ function fetchLsRows(db, mountId, parentPath) {
         ORDER BY l.fileName COLLATE NOCASE
       `).all(mountId)
     : db.prepare(`
-        SELECT ${LS_FILE_COLUMNS}
+        SELECT ${lsFileColumns(db)}
         FROM doc_mount_file_links l
         JOIN doc_mount_files f ON f.id = l.fileId
         WHERE l.mountPointId = ?
@@ -708,26 +839,29 @@ function fetchLsRows(db, mountId, parentPath) {
   return { folders, files };
 }
 
-function fetchLinksForFiles(db, fileIds) {
-  if (fileIds.length === 0) return new Map();
-  const placeholders = fileIds.map(() => '?').join(',');
+// Members of each named hard-link group, keyed by linkGroupId. Grouping is by
+// linkGroupId rather than fileId on purpose — see lsFileColumns: a shared
+// fileId only means "identical bytes", which is not a link.
+function fetchLinkGroupMembers(db, groupIds) {
+  if (groupIds.length === 0) return new Map();
+  const placeholders = groupIds.map(() => '?').join(',');
   const rows = db.prepare(`
-    SELECT l.fileId, l.relativePath, l.mountPointId, m.name AS mountName
+    SELECT l.linkGroupId, l.relativePath, l.mountPointId, m.name AS mountName
     FROM doc_mount_file_links l
     JOIN doc_mount_points m ON m.id = l.mountPointId
-    WHERE l.fileId IN (${placeholders})
+    WHERE l.linkGroupId IN (${placeholders})
     ORDER BY m.name COLLATE NOCASE, l.relativePath COLLATE NOCASE
-  `).all(...fileIds);
-  const byFile = new Map();
+  `).all(...groupIds);
+  const byGroup = new Map();
   for (const r of rows) {
-    if (!byFile.has(r.fileId)) byFile.set(r.fileId, []);
-    byFile.get(r.fileId).push({
+    if (!byGroup.has(r.linkGroupId)) byGroup.set(r.linkGroupId, []);
+    byGroup.get(r.linkGroupId).push({
       mountPointId: r.mountPointId,
       mountName: r.mountName,
       relativePath: r.relativePath,
     });
   }
-  return byFile;
+  return byGroup;
 }
 
 function sortLsFiles(files, sortType, reverse) {
@@ -776,14 +910,14 @@ async function handleLs(flags, mountSpec, rawPath) {
       const prefix = normalizedPath ? normalizedPath.replace(/\/+$/, '') + '/' : '';
       const allFiles = normalizedPath
         ? db.prepare(`
-            SELECT ${LS_FILE_COLUMNS}
+            SELECT ${lsFileColumns(db)}
             FROM doc_mount_file_links l
             JOIN doc_mount_files f ON f.id = l.fileId
             WHERE l.mountPointId = ? AND l.relativePath LIKE ?
             ORDER BY l.relativePath
           `).all(mount.id, prefix + '%')
         : db.prepare(`
-            SELECT ${LS_FILE_COLUMNS}
+            SELECT ${lsFileColumns(db)}
             FROM doc_mount_file_links l
             JOIN doc_mount_files f ON f.id = l.fileId
             WHERE l.mountPointId = ?
@@ -820,10 +954,10 @@ async function handleLs(flags, mountSpec, rawPath) {
 
     // Fetch links for JSON or --links flag
     const wantLinks = flags.json || flags.links;
-    const multiLinkFileIds = wantLinks
-      ? files.filter((f) => f.linkCount > 1).map((f) => f.fileId)
+    const linkedGroupIds = wantLinks
+      ? files.filter((f) => f.linkCount > 1 && f.linkGroupId).map((f) => f.linkGroupId)
       : [];
-    const linksByFile = fetchLinksForFiles(db, multiLinkFileIds);
+    const linksByGroup = fetchLinkGroupMembers(db, linkedGroupIds);
 
     // JSON output
     if (flags.json) {
@@ -842,7 +976,7 @@ async function handleLs(flags, mountSpec, rawPath) {
         }
       }
       for (const file of files) {
-        const others = linksByFile.get(file.fileId);
+        const others = file.linkGroupId ? linksByGroup.get(file.linkGroupId) : undefined;
         const links = others && others.length > 0
           ? others
           : [{
@@ -947,6 +1081,7 @@ async function handleLs(flags, mountSpec, rawPath) {
         emb: embedColumnMarker(file.chunkCount, file.embeddedChunkCount),
         name: singleFile ? file.relativePath : file.fileName,
         fileId: file.fileId,
+        linkGroupId: file.linkGroupId,
         relativePath: file.relativePath,
       });
     }
@@ -978,7 +1113,7 @@ async function handleLs(flags, mountSpec, rawPath) {
     for (const r of dataRows) {
       console.log(renderLine(r, false));
       if (flags.links && r.type === '-') {
-        const others = (linksByFile.get(r.fileId) || []).filter(
+        const others = ((r.linkGroupId && linksByGroup.get(r.linkGroupId)) || []).filter(
           (l) => !(l.mountPointId === mount.id && l.relativePath === r.relativePath)
         );
         if (others.length > 0) {
@@ -2992,6 +3127,9 @@ async function docsCommand(args) {
       case 'status':
         await handleStatus(flags);
         break;
+      case 'docker-mounts':
+        await handleDockerMounts(flags);
+        break;
       case 'find':
         await handleFind(flags, positional);
         break;

package/lib/memories-commands.js

@@ -1276,6 +1276,11 @@ Subcommands:
   grep     [filters] [-i] [-l] [--max N] [--context N] <pattern>
                                              Pattern search inside content
                                              with snippets.
+  grep --semantic --character <name|id> [--top N] [--threshold 0..1] <query>
+                                             Embedding search via the running
+                                             server (default --top 20,
+                                             --threshold 0.5). One holder at a
+                                             time; --port sets the server port.
   show     <id|prefix> [--depth N] [--no-related] [--json]
                                              Full record + related-memory
                                              neighbourhood.
@@ -1326,6 +1331,7 @@ Examples:
   quilltap memories ls --character Ariadne --sort created --limit 10
   quilltap memories find "concrete examples"
   quilltap memories grep -i --max 3 --context 1 "concrete examples"
+  quilltap memories grep --semantic --character Ariadne --top 10 "the argument about Calvin"
   quilltap memories show abc12345 --depth 2
   quilltap memories tree abc12345 --depth 3
   quilltap memories status --character Ariadne

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.8.0-dev.98",
+  "version": "4.9.0-dev",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -39,8 +39,8 @@
     "@napi-rs/canvas": "^0.1.100",
     "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
-    "sharp": "^0.34.5",
-    "tar": "^7.5.20",
+    "sharp": "^0.35.3",
+    "tar": "^7.5.22",
     "yauzl": "^3.4.0"
   },
   "engines": {