quilltap 4.4.0 → 4.5.0-dev.0

package/README.md

@@ -89,6 +89,109 @@ Quilltap stores its database, files, and logs in a platform-specific directory:
 
 Override with `--data-dir` or the `QUILLTAP_DATA_DIR` environment variable.
 
+## Database Tool
+
+The encrypted SQLite databases (main, LLM logs, mount index) can be queried directly via `quilltap db`. There are two modes: high-level subcommands that auto-pick the right database and resolve characters/chats/projects by name, and a low-level path for arbitrary SQL.
+
+### Subcommands
+
+```bash
+quilltap db schema                          # Tables grouped by domain
+quilltap db schema chat_messages            # Columns, indexes, DDL.md link
+quilltap db schema --grep memory            # Find tables/columns by substring
+
+quilltap db find character Friday           # Resolve a name to a UUID (fuzzy)
+quilltap db find chat "physical prompts"
+quilltap db find project "Quilltap"
+
+quilltap db chats --character Friday        # All chats containing a character
+quilltap db chats --project "Quilltap"      # All chats in a project
+quilltap db messages --chat <id|title> --last 50 --full
+quilltap db logs --chat <id|title>          # LLM logs for a chat
+quilltap db logs --message <id>             # LLM logs for a single message
+quilltap db logs --character Friday         # LLM logs by character
+quilltap db logs --tail 20                  # Recent LLM logs
+
+quilltap db message <id>                    # Full content of one message
+quilltap db log <id> [--field request|response|both]
+quilltap db memories --character Friday [--about Amy] [--source AUTO]
+```
+
+### Maintenance and Snapshots
+
+```bash
+quilltap db optimize                        # VACUUM + ANALYZE + PRAGMA optimize (all DBs)
+quilltap db optimize main                   # one DB; refuses while server is running
+
+quilltap db backup                          # online snapshot of all three DBs
+quilltap db backup main --out /tmp/snap     # one DB to a chosen directory
+quilltap db backup --json                   # parseable per-target sizes + durations
+
+quilltap db integrity                       # cipher_integrity_check + integrity_check
+quilltap db integrity llm-logs              # one DB; exit 0 ok, 1 issues, 2 open failure
+```
+
+`backup` and `integrity` are safe to run while the server is up; `optimize` refuses while a live lock is held. Backups default to `<dataDir>/backups/<timestamp>/` and inherit the source's encryption key transparently.
+
+Most subcommands accept `--json` (for piping) and `--limit N`. Names are case-insensitive; aliases are searched alongside character names. Ambiguous matches print all candidates and exit non-zero.
+
+### Low-level options
+
+```bash
+quilltap db --tables                                # List tables in active DB
+quilltap db --count chat_messages                   # Row count
+quilltap db "SELECT id FROM characters LIMIT 5"     # Raw SQL
+quilltap db --repl                                  # Interactive prompt
+quilltap db --llm-logs --tables                     # Target the LLM logs DB
+quilltap db --mount-points --tables                 # Target the mount index DB
+```
+
+In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
+
+## Document Stores (Scriptorium)
+
+`quilltap docs` exposes the document-store machinery from the command line. Read-only verbs open the mount-index DB directly and work without the server; write and pipeline verbs talk to the running server via `/api/v1/mount-points/[id]`.
+
+```bash
+# Read
+quilltap docs list                              # All mounts
+quilltap docs show <mount>                      # One mount, with counts
+quilltap docs ls <mount> [path] [--links]       # POSIX-flavoured listing (alias: dir)
+quilltap docs read [--rendered] <mount> <path>  # File contents → stdout
+quilltap docs export <mount> <outputDir>        # Mount → directory
+quilltap docs find <pattern>                    # Substring match on file names (--mount, --ext, --type, --limit)
+quilltap docs grep <pattern>                    # Substring match on extracted text (--mount, --ignore-case, -l, --max, --context)
+quilltap docs status                            # Per-mount extraction + embedding rollup (--mount, --top)
+
+# Server-required
+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 write [--force] <mount> <path> [file]           # Stdin or file → mount
+quilltap docs delete <mount> <path>                           # Idempotent delete
+quilltap docs mkdir <mount> <path>                            # Idempotent folder create
+quilltap docs move <srcMount> <srcPath> <dstMount> <dstPath>  # Move (hard-link when possible)
+quilltap docs copy [--force] <srcMount> <srcPath> <dstMount> <dstPath>
+```
+
+Mount arguments accept the mount name (case-insensitive) or a UUID; ambiguous names print candidates and exit non-zero. `--json` is supported by every verb; `reindex` and `embed` refuse to run without a reachable server.
+
+## Memories
+
+`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable, but never writable. All verbs open the main encrypted DB read-only.
+
+```bash
+quilltap memories ls                                                   # All holders, default sort: reinforcedImportance DESC
+quilltap memories ls --character Ariadne --sort created --limit 10     # One holder, newest first
+quilltap memories find "concrete examples"                             # Substring match on summary (--in content|both)
+quilltap memories grep -i --max 3 --context 1 "concrete examples"      # Pattern search inside content, with snippets
+quilltap memories 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
+```
+
+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.
+
 ## Theme Management
 
 The CLI includes theme management commands:
@@ -106,6 +209,81 @@ quilltap themes registry list           # List configured registries
 quilltap themes registry add <url>      # Add a registry source
 ```
 
+## Shell Completion
+
+Tab-completion for bash, zsh, and fish. Pick the block that matches your shell.
+
+### Bash
+
+Append the generated script to `~/.bashrc`:
+
+```bash
+quilltap completion bash >> ~/.bashrc
+```
+
+Or drop it into a system completion directory:
+
+```bash
+quilltap completion bash > /usr/local/etc/bash_completion.d/quilltap
+# Linux with admin rights: /etc/bash_completion.d/quilltap
+```
+
+Restart the shell, or `source ~/.bashrc`.
+
+### Zsh
+
+Two reasonable ways to wire this up; pick one.
+
+**Option A — one line in `.zshrc`** (simpler; adds noticeable shell-startup latency because `quilltap` runs every time you open a new shell):
+
+```zsh
+# In ~/.zshrc:
+source <(quilltap completion zsh)
+```
+
+**Option B — canonical `fpath` setup** (faster; what zsh expects):
+
+```zsh
+# In ~/.zshrc, before compinit runs:
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit
+compinit
+```
+
+Then once, from any shell:
+
+```zsh
+mkdir -p ~/.zsh/completions
+quilltap completion zsh > ~/.zsh/completions/_quilltap
+```
+
+The leading underscore on `_quilltap` is the zsh convention — it tells `compinit` this is a completion definition file rather than a regular autoloaded function.
+
+**oh-my-zsh users:** the framework runs `compinit` for you, so either set the `fpath` line *before* the framework loads, or delete the cache (`rm -f ~/.zcompdump*`) after dropping the file in and start a new shell. The more idiomatic location under oh-my-zsh is:
+
+```zsh
+mkdir -p ~/.oh-my-zsh/custom/plugins/quilltap
+quilltap completion zsh > ~/.oh-my-zsh/custom/plugins/quilltap/_quilltap
+# then add `quilltap` to the plugins=(...) line in ~/.zshrc
+```
+
+### Fish
+
+```fish
+quilltap completion fish > ~/.config/fish/completions/quilltap.fish
+```
+
+Fish picks new completion files up automatically — no shell restart needed.
+
+### What gets completed
+
+- **Subcommands**: `quilltap d<TAB>` → `db docs`
+- **Sub-verbs per namespace**: `quilltap db s<TAB>` → `schema show`
+- **Instance names**: `quilltap --instance Fr<TAB>` → registered instances
+- **Mount names**: `quilltap docs ls --mount Qu<TAB>` → mount points in the active instance
+
+Dynamic completions shell out to `quilltap`'s own subcommands. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
+
 ## Requirements
 
 - Node.js 18 or later

package/bin/quilltap.js

@@ -5,7 +5,14 @@ const { fork, exec, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { getCacheDir, isCacheValid, ensureStandalone } = require('../lib/download-manager');
-const { resolveDataDir, promptPassphrase, loadDbKey } = require('../lib/db-helpers');
+const {
+  resolveDataDir,
+  resolveDataDirAndPassphrase,
+  printDefaultInstanceHint,
+  promptPassphrase,
+  loadDbKey,
+} = require('../lib/db-helpers');
+const { resolveInstance } = require('../lib/instances');
 
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
@@ -20,6 +27,7 @@ function parseArgs(argv) {
   const opts = {
     port: 3000,
     dataDir: '',
+    instance: '',
     open: false,
     help: false,
     version: false,
@@ -42,6 +50,10 @@ function parseArgs(argv) {
       case '-d':
         opts.dataDir = args[++i];
         break;
+      case '--instance':
+      case '-i':
+        opts.instance = args[++i];
+        break;
       case '--open':
       case '-o':
         opts.open = true;
@@ -79,11 +91,14 @@ Subcommands:
   db                            Query encrypted databases
   themes                        Manage theme bundles
   docs                          Inspect, read, and export document mounts
+  memories                      Search, browse, and graph memories
+  instances                     Register / inspect named Quilltap instances
   memory-diff <chatId>          Dump existing memories and dry-run re-extraction for a chat
 
 Options:
   -p, --port <number>     Port to listen on (default: 3000)
   -d, --data-dir <path>   Data directory (default: platform-specific)
+  -i, --instance <name>   Use a registered instance (see 'quilltap instances')
   -o, --open              Open browser after server starts
   -v, --version           Show version number
   --update                Force re-download of application files
@@ -346,7 +361,20 @@ async function main() {
     HOSTNAME: '0.0.0.0',
   };
 
-  if (opts.dataDir) {
+  if (opts.dataDir && opts.instance) {
+    console.error('Error: Specify either --instance or --data-dir, not both.');
+    process.exit(1);
+  }
+  if (opts.instance) {
+    try {
+      const inst = resolveInstance(opts.instance);
+      env.QUILLTAP_DATA_DIR = inst.path;
+      opts.dataDir = inst.path; // surfaced in the startup banner below
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (opts.dataDir) {
     env.QUILLTAP_DATA_DIR = path.resolve(opts.dataDir);
   }
 
@@ -690,16 +718,55 @@ function printDbHelp() {
 Quilltap Database Tool
 
 Usage: quilltap db [options] [sql]
+       quilltap db <subcommand> [args]
 
 Query your encrypted Quilltap database directly.
 
-Options:
-  --tables              List all tables
+Subcommands (high-level shortcuts; auto-pick the right database):
+  schema [table]              Schema overview, or details for one table
+  schema --grep <text>        Find tables/columns whose name matches
+  find character [query]      List or look up characters by name/id
+  find chat [query]           List or look up chats by title/id
+  find project [query]        List or look up projects by name/id
+  chats --character <name|id> Chats containing a character
+  chats --project <name|id>   Chats in a project
+  messages --chat <id|title>  Recent messages in a chat
+                              (flags: --last N --full --from <pid> --type <t>)
+  logs --chat <id|title>      LLM logs for a chat
+  logs --message <id>         LLM logs for a single message
+  logs --character <name|id>  LLM logs for a character
+  logs --tail N               Most recent LLM logs
+  message <id>                Full content of a single chat message
+  log <id>                    Full request/response of a single LLM log
+  memories --character <id>   Memories held by a character
+                              (flags: --about <id|name> --source AUTO|MANUAL)
+  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,
+                              mount-points (or "all"). Refuses to run while a
+                              live Quilltap instance holds the lock.
+  backup [target...] [--out <dir>]
+                              Online consistent snapshot of the encrypted
+                              databases. Safe while the server is running.
+                              Default destination: <dataDir>/backups/<timestamp>/.
+                              Each snapshot is re-opened with the same key and
+                              verified with PRAGMA quick_check.
+  integrity [target...]       Run PRAGMA cipher_integrity_check and
+                              PRAGMA integrity_check on the encrypted
+                              databases. Read-only; safe alongside a live
+                              instance. Exit code: 0 ok, 1 issues, 2 open
+                              failure.
+  Most subcommands also accept --json and --limit N.
+
+Low-level options (legacy; still supported):
+  --tables              List all tables in the active database
   --count <table>       Show row count for a table
-  --repl                Interactive SQL prompt
+  --repl                Interactive SQL prompt (extras: .cols, .find)
   --llm-logs            Target the LLM logs database
   --mount-points        Target the document mount-index database
-  --data-dir <path>     Override data directory
+  --data-dir <path>     Override data directory (pass instance root)
+  -i, --instance <name> Use a registered instance from instances.json
+                        (see 'quilltap instances --help')
   --passphrase <pass>   Provide passphrase for encrypted .dbkey
   -h, --help            Show this help
 
@@ -713,22 +780,85 @@ will check the QUILLTAP_DB_PASSPHRASE environment variable, then prompt
 interactively (with hidden input) if a TTY is available.
 
 Examples:
+  quilltap db schema                                   # tables grouped by domain
+  quilltap db schema chat_messages                     # columns + indexes + DDL link
+  quilltap db find character Friday                    # name → uuid
+  quilltap db chats --character Friday                 # all chats with Friday
+  quilltap db messages --chat <id> --last 50 --full    # recent messages
+  quilltap db logs --chat "physical prompts"           # llm logs for a chat
+  quilltap db log <log-id>                             # full request/response
+  quilltap db optimize                                 # VACUUM + ANALYZE all DBs
+  quilltap db optimize llm-logs                        # only the LLM logs DB
+  quilltap db backup                                   # snapshot all DBs to <dataDir>/backups/<ts>/
+  quilltap db backup main --out /tmp/qtap-snap         # snapshot only the main DB
+  quilltap db integrity                                # cipher_integrity_check + integrity_check
   quilltap db --tables
   quilltap db "SELECT count(*) FROM characters"
   quilltap db --count messages
   quilltap db --repl
-  quilltap db --llm-logs --tables
-  quilltap db --mount-points --tables
-  quilltap db --mount-points "SELECT id, name FROM doc_mount_points"
   quilltap db --lock-status
-  quilltap db --lock-clean
   QUILLTAP_DB_PASSPHRASE=secret quilltap db --tables
 `);
 }
 
 async function dbCommand(args) {
+  // ---- Pre-flight: extract dataDir/passphrase, then check for a verb subcommand
+  //      before the legacy flag loop. This lets `quilltap db <verb>` dispatch
+  //      to the new high-level commands without touching the legacy path.
+  const { isVerb, runVerb, makeCtx } = require('../lib/db-commands');
+
+  // Strip --data-dir / --passphrase / --instance out so they can appear anywhere
+  // on the line, including before or after the verb.
+  const cleaned = [];
   let dataDirOverride = '';
   let passphrase = '';
+  let instanceName = '';
+  for (let j = 0; j < args.length; j++) {
+    const a = args[j];
+    if (a === '--data-dir' || a === '-d') { dataDirOverride = args[++j]; continue; }
+    if (a === '--passphrase') { passphrase = args[++j]; continue; }
+    if (a === '--instance' || a === '-i') { instanceName = args[++j]; continue; }
+    cleaned.push(a);
+  }
+
+  // Find first non-flag arg to test for verb
+  const firstPositional = cleaned.find(a => !a.startsWith('-'));
+  if (firstPositional && isVerb(firstPositional)) {
+    let resolved;
+    try {
+      resolved = resolveDataDirAndPassphrase({
+        dataDir: dataDirOverride,
+        instance: instanceName,
+        passphrase,
+      });
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    printDefaultInstanceHint(resolved);
+    const dataDir = resolved.dataDir;
+    let pepper;
+    try {
+      pepper = await loadDbKey(dataDir, resolved.passphrase);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    // Re-strip global flags but preserve everything else (verb + its flags)
+    const ctx = makeCtx(dataDir, pepper);
+    try {
+      await runVerb(cleaned, ctx);
+    } catch (err) {
+      if (!err.silent) {
+        console.error(`Error: ${err.message}`);
+      }
+      const code = err.exitCode != null ? err.exitCode : (err.ambiguous ? 2 : 1);
+      process.exit(code);
+    }
+    return;
+  }
+
+  // ---- Legacy flag-based path (unchanged) ----
   let useLlmLogs = false;
   let useMountPoints = false;
   let showTables = false;
@@ -741,25 +871,23 @@ async function dbCommand(args) {
   let lockOverride = false;
 
   let i = 0;
-  while (i < args.length) {
-    switch (args[i]) {
-      case '--data-dir': case '-d': dataDirOverride = args[++i]; break;
-      case '--passphrase': passphrase = args[++i]; break;
+  while (i < cleaned.length) {
+    switch (cleaned[i]) {
       case '--llm-logs': useLlmLogs = true; break;
       case '--mount-points': useMountPoints = true; break;
       case '--tables': showTables = true; break;
-      case '--count': countTable = args[++i]; break;
+      case '--count': countTable = cleaned[++i]; break;
       case '--repl': repl = true; break;
       case '--help': case '-h': showHelp = true; break;
       case '--lock-status': lockStatus = true; break;
       case '--lock-clean': lockClean = true; break;
       case '--lock-override': lockOverride = true; break;
       default:
-        if (args[i].startsWith('-')) {
-          console.error(`Unknown option: ${args[i]}`);
+        if (cleaned[i].startsWith('-')) {
+          console.error(`Unknown option: ${cleaned[i]}`);
           process.exit(1);
         }
-        sql = args[i];
+        sql = cleaned[i];
         break;
     }
     i++;
@@ -770,7 +898,20 @@ async function dbCommand(args) {
     process.exit(0);
   }
 
-  const dataDir = resolveDataDir(dataDirOverride);
+  let legacyResolved;
+  try {
+    legacyResolved = resolveDataDirAndPassphrase({
+      dataDir: dataDirOverride,
+      instance: instanceName,
+      passphrase,
+    });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  printDefaultInstanceHint(legacyResolved);
+  const dataDir = legacyResolved.dataDir;
+  passphrase = legacyResolved.passphrase;
 
   // ---- Instance lock commands (no database open required) ----
   if (lockStatus || lockClean || lockOverride) {
@@ -851,7 +992,7 @@ async function dbCommand(args) {
       const readline = require('readline');
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: 'quilltap> ' });
       console.log(`Connected to ${dbPath}`);
-      console.log('Type .tables, .schema <table>, or SQL. Ctrl+D to exit.\n');
+      console.log('Type .tables, .schema <table>, .cols <table>, .find <text>, or SQL. Ctrl+D to exit.\n');
       rl.prompt();
       rl.on('line', (line) => {
         const trimmed = line.trim();
@@ -867,6 +1008,38 @@ async function dbCommand(args) {
               const row = db.prepare("SELECT sql FROM sqlite_master WHERE name = ?").get(table);
               console.log(row ? row.sql : `Table '${table}' not found`);
             }
+          } else if (trimmed.startsWith('.cols')) {
+            const table = trimmed.split(/\s+/)[1];
+            if (!table) { console.log('Usage: .cols <table>'); }
+            else {
+              const cols = db.prepare(`PRAGMA table_info("${table.replace(/"/g, '""')}")`).all();
+              if (cols.length === 0) console.log(`Table '${table}' not found`);
+              else console.table(cols.map(c => ({
+                name: c.name, type: c.type,
+                notNull: c.notnull ? 'NOT NULL' : '',
+                default: c.dflt_value === null ? '' : c.dflt_value,
+                pk: c.pk ? 'pk' : '',
+              })));
+            }
+          } else if (trimmed.startsWith('.find')) {
+            const needle = trimmed.slice(5).trim();
+            if (!needle) { console.log('Usage: .find <text>'); }
+            else {
+              const lc = needle.toLowerCase();
+              const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(r => r.name);
+              const matches = [];
+              for (const t of tables) {
+                const tableHit = t.toLowerCase().includes(lc);
+                const cols = db.prepare(`PRAGMA table_info("${t.replace(/"/g, '""')}")`).all();
+                const colHits = cols.filter(c => c.name.toLowerCase().includes(lc)).map(c => c.name);
+                if (tableHit || colHits.length) matches.push({ table: t, tableMatch: tableHit, columns: colHits });
+              }
+              if (matches.length === 0) console.log(`No tables or columns matching '${needle}'`);
+              else for (const m of matches) {
+                const flag = m.tableMatch ? '*' : ' ';
+                console.log(`${flag} ${m.table}${m.columns.length ? '  ' + m.columns.map(c => '.' + c).join(', ') : ''}`);
+              }
+            }
           } else {
             const stmt = db.prepare(trimmed);
             if (stmt.reader) {
@@ -905,12 +1078,45 @@ if (process.argv[2] === 'db') {
 } else if (process.argv[2] === 'docs') {
   const { docsCommand } = require('../lib/docs-commands');
   docsCommand(process.argv.slice(3));
+} else if (process.argv[2] === 'memories') {
+  const { memoriesCommand } = require('../lib/memories-commands');
+  memoriesCommand(process.argv.slice(3)).catch(err => {
+    if (!err.silent) {
+      console.error(`Error: ${err.message}`);
+    }
+    const code = err.exitCode != null ? err.exitCode : (err.ambiguous ? 2 : 1);
+    process.exit(code);
+  });
+} else if (process.argv[2] === 'instances') {
+  const { instancesCommand } = require('../lib/instances-commands');
+  instancesCommand(process.argv.slice(3)).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (process.argv[2] === 'memory-diff') {
   const { memoryDiffCommand } = require('../lib/memory-diff-command');
   memoryDiffCommand(process.argv.slice(3)).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (process.argv[2] === 'completion') {
+  const { completionCommand } = require('../lib/completion-commands');
+  completionCommand(process.argv.slice(3)).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+} else if (process.argv[2] === 'logs') {
+  const { logsCommand } = require('../lib/logs-commands');
+  logsCommand(process.argv.slice(3)).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+} else if (process.argv[2] === 'migrations') {
+  const { migrationsCommand } = require('../lib/migrations-commands');
+  migrationsCommand(process.argv.slice(3)).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else {
   main();
 }

package/lib/completion/bash.template

@@ -0,0 +1,121 @@
+#!/bin/bash
+
+# Bash completion for quilltap
+# Source this file or place it in /etc/bash_completion.d/ or ~/.bash_completion.d/
+
+_quilltap_complete() {
+  local cur prev words cword
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+  words=("${COMP_WORDS[@]}")
+  cword=$COMP_CWORD
+
+  # Global options that can appear before subcommands
+  local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update"
+
+  # Get the subcommand (first non-option word after quilltap)
+  local subcommand=""
+  local i=1
+  while [[ $i -lt $cword ]]; do
+    local word="${words[$i]}"
+    case "$word" in
+      -d|--data-dir|-i|--instance|-p|--port)
+        # These take a value, skip the next word
+        ((i += 2))
+        ;;
+      -o|--open|-v|--version|-h|--help|--update)
+        # Flags without values
+        ((i += 1))
+        ;;
+      -*)
+        # Unknown flag, skip
+        ((i += 1))
+        ;;
+      *)
+        # This is the subcommand
+        subcommand="$word"
+        break
+        ;;
+    esac
+  done
+
+  # If we're completing a global flag value
+  if [[ "$prev" == "-d" ]] || [[ "$prev" == "--data-dir" ]] || \
+     [[ "$prev" == "-p" ]] || [[ "$prev" == "--port" ]]; then
+    # No completion for paths or ports
+    return
+  fi
+
+  if [[ "$prev" == "-i" ]] || [[ "$prev" == "--instance" ]]; then
+    # Complete with instance names
+    local instances=$(command quilltap instances list --names-only 2>/dev/null)
+    COMPREPLY=($(compgen -W "$instances" -- "$cur"))
+    return
+  fi
+
+  # If no subcommand yet, complete with subcommands and global options
+  if [[ -z "$subcommand" ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=($(compgen -W "$global_opts" -- "$cur"))
+    else
+      COMPREPLY=($(compgen -W "db docs themes instances memories memory-diff completion" -- "$cur"))
+    fi
+    return
+  fi
+
+  # Subcommand-specific completion
+  local subcommand_opts=""
+  case "$subcommand" in
+    db)
+      subcommand_opts="schema find chats messages logs message log memories optimize backup integrity"
+      if [[ "$cur" == -* ]]; then
+        subcommand_opts="$subcommand_opts --instance --data-dir --json --help"
+      fi
+      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
+      ;;
+    docs)
+      local docs_verbs="list show files ls dir read export scan write delete mkdir move copy status find grep reindex embed"
+      if [[ "$cur" == -* ]]; then
+        docs_verbs="$docs_verbs --mount --instance --data-dir --port --json --help --force --rendered --links"
+      fi
+      COMPREPLY=($(compgen -W "$docs_verbs" -- "$cur"))
+      ;;
+    themes)
+      subcommand_opts="list install uninstall validate export create search update registry"
+      if [[ "$cur" == -* ]]; then
+        subcommand_opts="$subcommand_opts --instance --data-dir --output --help"
+      fi
+      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
+      ;;
+    instances)
+      subcommand_opts="list ls show path where add create remove rm delete set-passphrase passphrase"
+      if [[ "$cur" == -* ]]; then
+        subcommand_opts="$subcommand_opts --help"
+      fi
+      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
+      ;;
+    memories)
+      local mem_verbs="ls find grep show tree status validate"
+      if [[ "$cur" == -* ]]; then
+        mem_verbs="$mem_verbs --character --about --source --chat --project --since --until --min-importance --min-reinforced --has-embedding --no-embedding --sort --instance --data-dir --json --help"
+      fi
+      COMPREPLY=($(compgen -W "$mem_verbs" -- "$cur"))
+      ;;
+    memory-diff)
+      if [[ "$cur" == -* ]]; then
+        subcommand_opts="--instance --data-dir --help"
+        COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
+      fi
+      ;;
+    completion)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--help" -- "$cur"))
+      else
+        COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur"))
+      fi
+      ;;
+  esac
+}
+
+complete -F _quilltap_complete quilltap