quilltap 4.8.0-dev.186 → 4.8.0-dev.192

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__/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

@@ -126,7 +126,7 @@ _quilltap_complete() {
       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"

package/lib/completion/fish.template

@@ -136,6 +136,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'

package/lib/completion/zsh.template

@@ -168,6 +168,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,6 +71,8 @@ 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>
@@ -210,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;
@@ -229,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;
@@ -487,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
 // ----------------------------------------------------------------------------
@@ -3033,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/package.json

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