quilltap 4.9.0-dev.62 → 4.9.0-dev.65

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

@@ -0,0 +1,146 @@
+/**
+ * Behavioural guard for the shell-completion templates.
+ *
+ * The static coverage test next door proves every subcommand is *mentioned*.
+ * This one proves the completions still fire once flags are on the line — the
+ * failure the templates actually shipped with: `quilltap docs --instance
+ * Friday <TAB>` offered nothing, because the verb was looked up by counting
+ * words rather than by parsing them.
+ *
+ * Bash is driven for real (source the script, set COMP_WORDS/COMP_CWORD, read
+ * COMPREPLY back). Zsh's completion system can only be driven from inside a
+ * completion widget, so its template is checked structurally instead.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const COMPLETION_DIR = path.join(__dirname, '..', 'completion');
+
+/** A `quilltap` on PATH that answers the completion lookups deterministically. */
+function makeStubBin() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'quilltap-completion-'));
+  const stub = path.join(dir, 'quilltap');
+  fs.writeFileSync(
+    stub,
+    [
+      '#!/bin/sh',
+      'case "$*" in',
+      '  *"instances list --names-only"*) printf "StubInstance\\n" ;;',
+      '  *"docs list --names-only"*) printf "Stub Store\\nOther Store\\n" ;;',
+      'esac',
+      'exit 0',
+      '',
+    ].join('\n'),
+    { mode: 0o755 }
+  );
+  return dir;
+}
+
+const STUB_BIN = makeStubBin();
+afterAll(() => fs.rmSync(STUB_BIN, { recursive: true, force: true }));
+
+/**
+ * Complete `line` with the bash template and return the candidate list.
+ * A trailing space means "start a new word", exactly as at a real prompt.
+ */
+function bashComplete(line) {
+  const script = `
+    source ${JSON.stringify(path.join(COMPLETION_DIR, 'bash.template'))}
+    COMP_LINE=${JSON.stringify(line)}
+    COMP_POINT=\${#COMP_LINE}
+    eval "COMP_WORDS=(\$COMP_LINE)"
+    [[ "\$COMP_LINE" =~ [[:space:]]$ ]] && COMP_WORDS+=("")
+    COMP_CWORD=\$(( \${#COMP_WORDS[@]} - 1 ))
+    _quilltap_complete
+    printf '%s\\n' "\${COMPREPLY[@]}"
+  `;
+  return execFileSync('bash', ['-c', script], {
+    encoding: 'utf8',
+    env: { ...process.env, PATH: `${STUB_BIN}:${process.env.PATH}` },
+  })
+    .split('\n')
+    .filter(Boolean);
+}
+
+describe('bash completion survives flags on the line', () => {
+  it('offers docs verbs with no flags', () => {
+    expect(bashComplete('quilltap docs ')).toContain('list');
+  });
+
+  it.each([
+    ['an instance flag', 'quilltap docs --instance Friday '],
+    ['a short instance flag', 'quilltap docs -i Friday '],
+    ['a subcommand flag that takes a value', 'quilltap docs --limit 5 '],
+    ['a valueless flag', 'quilltap docs --json '],
+    ['flags on both sides', 'quilltap --instance Friday docs --json '],
+  ])('still offers docs verbs after %s', (_label, line) => {
+    expect(bashComplete(line)).toContain('list');
+  });
+
+  it('still offers db verbs after a flag', () => {
+    expect(bashComplete('quilltap db --limit 5 ')).toContain('characters');
+  });
+
+  it('still offers db characters verbs after a flag', () => {
+    expect(bashComplete('quilltap db characters --instance Friday ')).toContain('status');
+  });
+
+  it('treats -i as --ignore-case under memories, not --instance', () => {
+    const got = bashComplete('quilltap memories -i ');
+    expect(got).toContain('ls');
+    expect(got).not.toContain('StubInstance');
+  });
+});
+
+describe('bash completion looks up names against the addressed instance', () => {
+  it('completes --mount from the document stores', () => {
+    expect(bashComplete('quilltap docs --mount ')).toContain('Stub\\ Store');
+  });
+
+  it('completes a store positional for verbs that take one', () => {
+    expect(bashComplete('quilltap docs ls ')).toContain('Stub\\ Store');
+  });
+
+  it('completes the destination store of a move', () => {
+    expect(bashComplete('quilltap docs move Src a.md ')).toContain('Stub\\ Store');
+  });
+
+  it('does not offer stores where the verb takes none', () => {
+    expect(bashComplete('quilltap docs find ')).not.toContain('Stub\\ Store');
+  });
+});
+
+describe('zsh completion parses positions instead of counting words', () => {
+  const tpl = fs.readFileSync(path.join(COMPLETION_DIR, 'zsh.template'), 'utf8');
+
+  it('has no hard-coded word-index tests', () => {
+    // `(( CURRENT == 2 ))` is the bug: it only holds when the verb sits
+    // immediately after the subcommand, so any preceding flag hides it.
+    expect(tpl).not.toMatch(/\(\(\s*CURRENT\s*==/);
+  });
+
+  it('stops the top-level _arguments swallowing flags typed after the subcommand', () => {
+    // Without the (-) prefixes the rest-argument array comes back empty and
+    // _quilltap_subcommand has nothing to dispatch on.
+    expect(tpl).toContain("'(-): :->subcommand'");
+    expect(tpl).toContain("'(-)*::arg:->args'");
+  });
+
+  it('hands every subcommand verb to _arguments as a positional', () => {
+    const dispatchers = tpl.match(/'\(?-?\)?1: :->\w+'/g) || [];
+    expect(dispatchers.length).toBeGreaterThanOrEqual(6);
+  });
+
+  it('is syntactically valid', () => {
+    const file = path.join(STUB_BIN, '_quilltap');
+    fs.writeFileSync(file, tpl);
+    expect(() => execFileSync('zsh', ['-n', file], { stdio: 'pipe' })).not.toThrow();
+  });
+});

package/lib/completion/bash.template

@@ -3,6 +3,52 @@
 # Bash completion for quilltap
 # Source this file or place it in /etc/bash_completion.d/ or ~/.bash_completion.d/
 
+# Fill COMPREPLY from newline-separated candidates on stdin. Store and
+# instance names routinely contain spaces ("Project Files: The Estate"), which
+# `compgen -W` would chop into separate candidates.
+_quilltap_lines_compreply() {
+  local cur="$1" line
+  local oldifs="$IFS"
+  COMPREPLY=()
+  IFS=$'\n'
+  while read -r line; do
+    [[ -n "$line" ]] || continue
+    [[ "$line" == "$cur"* ]] && COMPREPLY+=("$(printf '%q' "$line")")
+  done
+  IFS="$oldifs"
+}
+
+# Which docs positionals name a document store, and which name a local path.
+# move/copy/link take <srcMount> <srcPath> <dstMount> <dstPath>, so a store is
+# wanted at both 2 and 4; every other store-taking verb takes it first.
+_quilltap_docs_positional() {
+  local verb="$1" argpos="$2" cur="$3"
+  local store_verbs=" show files ls dir tree read export scan reindex embed write delete mkdir rmdir mvdir move copy link "
+
+  if [[ "$argpos" == "2" ]] && [[ "$store_verbs" == *" $verb "* ]]; then
+    _quilltap_lines_compreply "$cur" \
+      <<< "$(command quilltap docs list --names-only "${ctx_flags[@]}" 2>/dev/null)"
+    return
+  fi
+
+  case "$verb" in
+    move|copy|link)
+      if [[ "$argpos" == "4" ]]; then
+        _quilltap_lines_compreply "$cur" \
+          <<< "$(command quilltap docs list --names-only "${ctx_flags[@]}" 2>/dev/null)"
+      fi
+      ;;
+    export)
+      # `docs export <mount> <outputDir>` — the second one is a local directory.
+      [[ "$argpos" == "3" ]] && COMPREPLY=($(compgen -d -- "$cur"))
+      ;;
+    write)
+      # `docs write <mount> <path> [file]` — the optional source is local.
+      [[ "$argpos" == "4" ]] && COMPREPLY=($(compgen -f -- "$cur"))
+      ;;
+  esac
+}
+
 _quilltap_complete() {
   local cur prev words cword
   COMPREPLY=()
@@ -17,23 +63,62 @@ _quilltap_complete() {
   # Top-level subcommands
   local top_cmds="db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion"
 
+  # Flags that swallow the word after them. A flat list will not do: -o is the
+  # valueless global --open but themes' valued --output, and `memories`
+  # reserves -i for --ignore-case rather than --instance. Counting those wrong
+  # makes a flag's value look like the subcommand's verb, which is how
+  # `quilltap docs --limit 5 <TAB>` used to lose the verb list.
+  local vf_global=" -d --data-dir -i --instance -p --port --passphrase "
+  local vf_db=" --limit --grep --character --project --about --source --chat --message --field --tail --last --from --type --out --id --count "
+  local vf_docs=" --mount --folder --type --ext --limit --max --context --top --threshold --sort --depth --max-nodes "
+  local vf_themes=" -o --output -k --key -n --name "
+  local vf_memories=" -d --data-dir --instance --passphrase --port --character --about --source --chat --project --since --until --min-importance --min-reinforced --sort --limit --in --max --context --depth --max-nodes --top --threshold "
+  local vf_logs=" --stream --tail --grep "
+  local vf_memory_diff=" --concurrency --out "
+  local vf_recall_replay=" --turn --char --limit --port "
+  local vf_file_verify=" --stall-ms "
+
   # Get the subcommand (first non-option word after quilltap)
   local subcommand=""
   local subverb=""
+  local -a ctx_flags=()
+  local positional_count=0
   local i=1
   while [[ $i -lt $cword ]]; do
     local word="${words[$i]}"
+
+    # Which flags take a value depends on the subcommand seen so far; before
+    # one is seen, only the global flags are in play.
+    local valued="$vf_global"
+    case "$subcommand" in
+      db)            valued="$vf_global$vf_db" ;;
+      docs)          valued="$vf_global$vf_docs" ;;
+      themes)        valued="$vf_global$vf_themes" ;;
+      memories)      valued="$vf_memories" ;;
+      logs)          valued="$vf_global$vf_logs" ;;
+      memory-diff)   valued="$vf_global$vf_memory_diff" ;;
+      recall-replay) valued="$vf_global$vf_recall_replay" ;;
+      file-verify)   valued="$vf_global$vf_file_verify" ;;
+    esac
+
+    if [[ "$valued" == *" $word "* ]]; then
+      # Remember how the user is addressing an instance so the live lookups
+      # below query that database rather than the default one.
+      case "$word" in
+        -d|--data-dir|-i|--instance|--passphrase)
+          if (( i + 1 < cword )); then
+            ctx_flags+=("$word" "${words[$((i + 1))]}")
+          fi
+          ;;
+      esac
+      # Takes a value, skip the next word
+      ((i += 2))
+      continue
+    fi
+
     case "$word" in
-      -d|--data-dir|-i|--instance|-p|--port|--passphrase)
-        # 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
+        # Valueless (or unknown) flag
         ((i += 1))
         ;;
       *)
@@ -42,6 +127,10 @@ _quilltap_complete() {
         elif [[ -z "$subverb" ]]; then
           subverb="$word"
         fi
+        # Counts the subcommand itself, so the word under the cursor sits at
+        # positional_count within the subcommand: 1 is its verb, 2 the verb's
+        # first argument, and so on.
+        ((positional_count += 1))
         ((i += 1))
         ;;
     esac
@@ -56,9 +145,9 @@ _quilltap_complete() {
   if [[ "$prev" == "-p" ]] || [[ "$prev" == "--port" ]] || [[ "$prev" == "--passphrase" ]]; then
     return
   fi
-  if [[ "$prev" == "-i" ]] || [[ "$prev" == "--instance" ]]; then
-    local instances=$(command quilltap instances list --names-only 2>/dev/null)
-    COMPREPLY=($(compgen -W "$instances" -- "$cur"))
+  if [[ "$prev" == "--instance" ]] || { [[ "$prev" == "-i" ]] && [[ "$subcommand" != "memories" ]]; }; then
+    _quilltap_lines_compreply "$cur" \
+      <<< "$(command quilltap instances list --names-only 2>/dev/null)"
     return
   fi
 
@@ -75,8 +164,8 @@ _quilltap_complete() {
   # Shared flag-value completions for any subcommand
   case "$prev" in
     --mount)
-      local mounts=$(command quilltap docs list --names-only 2>/dev/null)
-      COMPREPLY=($(compgen -W "$mounts" -- "$cur"))
+      _quilltap_lines_compreply "$cur" \
+        <<< "$(command quilltap docs list --names-only "${ctx_flags[@]}" 2>/dev/null)"
       return
       ;;
     --character|--about)
@@ -137,16 +226,14 @@ _quilltap_complete() {
     docs)
       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 \
+        --uri --base64 --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"
-      if [[ -z "$subverb" ]]; then
-        if [[ "$cur" == -* ]]; then
-          COMPREPLY=($(compgen -W "$docs_flags" -- "$cur"))
-        else
-          COMPREPLY=($(compgen -W "$docs_verbs" -- "$cur"))
-        fi
-      else
+      if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "$docs_flags" -- "$cur"))
+      elif [[ -z "$subverb" ]]; then
+        COMPREPLY=($(compgen -W "$docs_verbs" -- "$cur"))
+      else
+        _quilltap_docs_positional "$subverb" "$positional_count" "$cur"
       fi
       ;;
     themes)

package/lib/completion/fish.template

@@ -8,6 +8,10 @@ function __quilltap_instance_names
   command quilltap instances list --names-only 2>/dev/null
 end
 
+function __quilltap_mount_names
+  command quilltap docs list --names-only 2>/dev/null
+end
+
 function __quilltap_no_subcommand
   set -l cmd (commandline -opc)
   if test (count $cmd) -lt 2
@@ -157,7 +161,7 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'rmdir' -d 'Rem
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'mvdir' -d 'Rename or move a folder'
 
 # docs flags
-complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'mount' -d 'Mount name or id' -x
+complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'mount' -d 'Mount name or id' -x -a '(__quilltap_mount_names)'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'port' -s 'p' -d 'Server port' -x
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'folder' -d 'Folder filter' -x
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'force' -d 'Force operation'

package/lib/completion/zsh.template

@@ -2,12 +2,27 @@
 
 # Zsh completion for quilltap
 
+# Position is worked out by _arguments, never by counting words. A hard-coded
+# `CURRENT == 2` test means the verb only completes when it sits immediately
+# after the subcommand, so `quilltap docs --instance Friday <TAB>` offers
+# nothing at all. Every function below hands its option list *and* its
+# positional specs to one `_arguments -C` call and branches on $state, so flags
+# may appear anywhere the CLI itself accepts them.
+
 local ret=1
 
 _quilltap() {
   local -a subcommands
   local -a global_options
 
+  # The whole command line, kept before _arguments rebases `words` for the
+  # subcommand dispatch. The lookup helpers read it so that an --instance
+  # typed anywhere picks which database they query.
+  local -a _quilltap_line
+  local -i _quilltap_cword
+  _quilltap_line=("${words[@]}")
+  _quilltap_cword=$CURRENT
+
   global_options=(
     '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
     '(-i --instance)'{-i,--instance}'[Use a registered instance]:instance:_quilltap_instance_names'
@@ -34,10 +49,14 @@ _quilltap() {
     'completion:Generate shell completion scripts'
   )
 
+  # (-) on both positionals stops the top-level _arguments from swallowing a
+  # flag typed *after* the subcommand: without it `quilltap docs --instance
+  # Friday <TAB>` parses --instance as a global option, leaving the rest-arg
+  # array empty and the subcommand dispatch with nothing to dispatch on.
   _arguments -C \
-    '1: :->subcommand' \
     "${global_options[@]}" \
-    '*::arg:->args'
+    '(-): :->subcommand' \
+    '(-)*::arg:->args'
 
   case "$state" in
     subcommand)
@@ -74,7 +93,7 @@ _quilltap_subcommand() {
       _quilltap_memory_diff
       ;;
     recall-replay)
-      _arguments '--turn[interchange to replay]:turn:' '--char[character id]:char:' '--limit[rows per path]:limit:' '--port[server port]:port:' '--json[raw JSON output]' '--help[show help]'
+      _quilltap_recall_replay
       ;;
     logs)
       _quilltap_logs
@@ -86,7 +105,7 @@ _quilltap_subcommand() {
       _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]'
+      _quilltap_file_verify
       ;;
     completion)
       _quilltap_completion
@@ -95,7 +114,10 @@ _quilltap_subcommand() {
 }
 
 _quilltap_db() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs db_opts
+
   subverbs=(
     'schema:Show database schema'
     'find:Find entities by name'
@@ -147,46 +169,74 @@ _quilltap_db() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'db subcommand' subverbs
-    return
-  fi
+  # (-) again: a flag typed after the verb belongs to the verb's own
+  # _arguments call below, not to this one.
+  _arguments -C $db_opts \
+    '(-): :->verb' \
+    '(-)*::arg:->rest'
 
-  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
+  case "$state" in
+    verb)
+      _describe -t commands 'db subcommand' subverbs
+      ;;
+    rest)
+      case "$line[1]" in
+        characters)
+          _quilltap_db_characters
+          ;;
+        *)
+          # Nothing to complete positionally, but the flags still apply.
+          _arguments $db_opts
+          ;;
+      esac
+      ;;
+  esac
+}
 
-  _arguments $db_opts
+_quilltap_db_characters() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+  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]'
+  )
+
+  _arguments -C $char_opts \
+    '1: :->cverb' \
+    '*: :'
+
+  case "$state" in
+    cverb)
+      _describe -t commands 'characters subcommand' char_verbs
+      ;;
+  esac
 }
 
 _quilltap_docs() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs docs_opts
+
   subverbs=(
     'list:List all mount points'
     'show:Details for one mount point'
@@ -219,10 +269,12 @@ _quilltap_docs() {
     '--passphrase[Database passphrase]:passphrase:'
     '(-p --port)'{-p,--port}'[Server port]:port:'
     '--json[JSON output]'
-    '--mount[Mount name or id]:mount:'
+    '--uri[Show canonical qtap:// URIs as the locator]'
+    '--mount[Mount name or id]:mount:_quilltap_mount_names'
     '--folder[Folder filter]:folder:'
     '--force[Force operation]'
     '--rendered[Render rich content]'
+    '--base64[Base64 transfer for binary files]'
     '--links[Include link details]'
     '--type[Filter by type]:type:(file folder)'
     '--ext[Extension filter]:ext:'
@@ -244,14 +296,61 @@ _quilltap_docs() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'docs subcommand' subverbs
+  _arguments -C $docs_opts \
+    '1: :->verb' \
+    '2: :->pos2' \
+    '3: :->pos3' \
+    '4: :->pos4' \
+    '*: :'
+
+  case "$state" in
+    verb)
+      _describe -t commands 'docs subcommand' subverbs
+      ;;
+    pos2|pos3|pos4)
+      _quilltap_docs_positional ${state#pos}
+      ;;
+  esac
+}
+
+# Which docs positionals name a document store, and which name a local path.
+# `move`/`copy`/`link` take <srcMount> <srcPath> <dstMount> <dstPath>, so a
+# store is wanted at both 2 and 4; everything else that takes a store takes it
+# first. `$line` comes from the caller's _arguments -C.
+_quilltap_docs_positional() {
+  local -i n=$1
+  local verb="$line[1]"
+  local -a store_verbs
+  store_verbs=(
+    show files ls dir tree read export scan reindex embed
+    write delete mkdir rmdir mvdir move copy link
+  )
+
+  if (( n == 2 )) && (( ${store_verbs[(I)$verb]} )); then
+    _quilltap_mount_names
+    return
   fi
-  _arguments $docs_opts
+
+  case "$verb" in
+    move|copy|link)
+      (( n == 4 )) && _quilltap_mount_names
+      ;;
+    export)
+      # `docs export <mount> <outputDir>` — the second one is a local directory.
+      (( n == 3 )) && _directories
+      ;;
+    write)
+      # `docs write <mount> <path> [file]` — the optional source is local.
+      (( n == 4 )) && _files
+      ;;
+  esac
 }
 
 _quilltap_themes() {
-  local -a subverbs registry_verbs themes_opts registry_opts
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+  local -a subverbs themes_opts
+
   subverbs=(
     'list:List available themes'
     'install:Install a theme'
@@ -271,37 +370,70 @@ _quilltap_themes() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'themes subcommand' subverbs
-    return
-  fi
+  # (-) again: a flag typed after the verb belongs to the verb's own
+  # _arguments call below, not to this one.
+  _arguments -C $themes_opts \
+    '(-): :->verb' \
+    '(-)*::arg:->rest'
 
-  if [[ "$words[2]" == "registry" ]]; then
-    registry_verbs=(
-      'list:List registries'
-      'add:Add a registry'
-      'remove:Remove a registry'
-      'refresh:Refresh registries'
-      'keygen:Generate Ed25519 key'
-      'sign:Sign a registry or bundle'
-    )
-    registry_opts=(
-      '(-k --key)'{-k,--key}'[Signing key path]:path:_files'
-      '(-n --name)'{-n,--name}'[Registry name]:name:'
-      '(-o --output)'{-o,--output}'[Output path]:path:_files'
-    )
-    if (( CURRENT == 3 )); then
-      _describe 'registry subcommand' registry_verbs
-    fi
-    _arguments $registry_opts
-    return
-  fi
+  case "$state" in
+    verb)
+      _describe -t commands 'themes subcommand' subverbs
+      ;;
+    rest)
+      case "$line[1]" in
+        registry)
+          _quilltap_themes_registry
+          ;;
+        *)
+          _arguments $themes_opts
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_quilltap_themes_registry() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+  local -a registry_verbs registry_opts
+
+  registry_verbs=(
+    'list:List registries'
+    'add:Add a registry'
+    'remove:Remove a registry'
+    'refresh:Refresh registries'
+    'keygen:Generate Ed25519 key'
+    'sign:Sign a registry or bundle'
+  )
 
-  _arguments $themes_opts
+  # themesCommand() parses -d/-i/-o/-h anywhere in the argv, including after
+  # `registry`, so they belong in this list too.
+  registry_opts=(
+    '(-k --key)'{-k,--key}'[Signing key path]:path:_files'
+    '(-n --name)'{-n,--name}'[Registry name]:name:'
+    '(-o --output)'{-o,--output}'[Output path]:path:_files'
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  _arguments -C $registry_opts \
+    '1: :->rverb' \
+    '*: :'
+
+  case "$state" in
+    rverb)
+      _describe -t commands 'registry subcommand' registry_verbs
+      ;;
+  esac
 }
 
 _quilltap_instances() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs inst_opts
+
   subverbs=(
     'list:List registered instances'
     'ls:List registered instances'
@@ -326,25 +458,30 @@ _quilltap_instances() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'instances subcommand' subverbs
-    return
-  fi
+  _arguments -C $inst_opts \
+    '1: :->verb' \
+    '2: :->name' \
+    '*: :'
 
-  case "$words[2]" in
-    show|remove|rm|delete|set-passphrase|passphrase|default|rename)
-      if (( CURRENT == 3 )); then
-        _values 'instance' ${(f)"$(command quilltap instances list --names-only 2>/dev/null)"}
-        return
-      fi
+  case "$state" in
+    verb)
+      _describe -t commands 'instances subcommand' subverbs
+      ;;
+    name)
+      case "$line[1]" in
+        show|remove|rm|delete|set-passphrase|passphrase|default|rename)
+          _quilltap_instance_names
+          ;;
+      esac
       ;;
   esac
-
-  _arguments $inst_opts
 }
 
 _quilltap_memories() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs mem_opts
+
   subverbs=(
     'ls:List memories'
     'find:Substring search'
@@ -356,10 +493,10 @@ _quilltap_memories() {
   )
 
   mem_opts=(
-    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '--instance[Registered instance name]:instance:_quilltap_instance_names'
     '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
     '--passphrase[Database passphrase]:passphrase:'
-    '(-p --port)'{-p,--port}'[Server port]:port:'
+    '--port[Server port]:port:'
     '--json[JSON output]'
     '--character[Character name or id]:character:'
     '--about[Subject of memory]:character:'
@@ -379,7 +516,7 @@ _quilltap_memories() {
     '--in[Restrict find-in field]:field:'
     '--no-related[Hide related neighbors]'
     '--list[List-only output]'
-    '(-i --ignore-case)'{-i,--ignore-case}'[Case-insensitive]'
+    '(-i --ignore-case)'{-i,--ignore-case}'[Case-insensitive (memories reserves -i for this, not --instance)]'
     '(-l --paths-only)'{-l,--paths-only}'[Paths only]'
     '--max[Maximum results]:n:'
     '--context[Context lines]:n:'
@@ -391,10 +528,15 @@ _quilltap_memories() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'memories subcommand' subverbs
-  fi
-  _arguments $mem_opts
+  _arguments -C $mem_opts \
+    '1: :->verb' \
+    '*: :'
+
+  case "$state" in
+    verb)
+      _describe -t commands 'memories subcommand' subverbs
+      ;;
+  esac
 }
 
 _quilltap_memory_diff() {
@@ -405,7 +547,22 @@ _quilltap_memory_diff() {
     '--passphrase[Database passphrase]:passphrase:' \
     '(-p --port)'{-p,--port}'[Server port]:port:' \
     '--concurrency[Concurrency limit]:n:' \
-    '--out[Output file]:path:_files'
+    '--out[Output file]:path:_files' \
+    '*: :'
+}
+
+_quilltap_recall_replay() {
+  _arguments \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '(-i --instance)'{-i,--instance}'[Use instance]:instance:_quilltap_instance_names' \
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories' \
+    '--passphrase[Database passphrase]:passphrase:' \
+    '--turn[interchange to replay]:turn:' \
+    '--char[character id]:char:' \
+    '--limit[rows per path]:limit:' \
+    '--port[server port]:port:' \
+    '--json[raw JSON output]' \
+    '*: :'
 }
 
 _quilltap_logs() {
@@ -417,11 +574,27 @@ _quilltap_logs() {
     '--stream[Which log stream]:stream:(combined error stdout stderr startup)' \
     '--tail[Last N lines (0=full)]:n:' \
     '(-f --follow)'{-f,--follow}'[Stream new lines]' \
-    '--grep[Regex filter]:pattern:'
+    '--grep[Regex filter]:pattern:' \
+    '*: :'
+}
+
+_quilltap_file_verify() {
+  _arguments \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '(-i --instance)'{-i,--instance}'[Use instance]:instance:_quilltap_instance_names' \
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories' \
+    '--passphrase[Database passphrase]:passphrase:' \
+    '--all[read every top-level file, not just dataless ones]' \
+    '--stall-ms[per-chunk stall threshold in ms]:ms:' \
+    '--json[machine-readable output]' \
+    '*: :'
 }
 
 _quilltap_migrations() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs mig_opts
+
   subverbs=(
     'status:Migration status'
     'pending:List pending migrations'
@@ -437,14 +610,22 @@ _quilltap_migrations() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'migrations subcommand' subverbs
-  fi
-  _arguments $mig_opts
+  _arguments -C $mig_opts \
+    '1: :->verb' \
+    '*: :'
+
+  case "$state" in
+    verb)
+      _describe -t commands 'migrations subcommand' subverbs
+      ;;
+  esac
 }
 
 _quilltap_maintenance() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
   local -a subverbs maint_opts
+
   subverbs=(
     'status:Show dry-run retention counts'
     'run:Run retention/cleanup sweeps (lock-gated)'
@@ -458,20 +639,71 @@ _quilltap_maintenance() {
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  if (( CURRENT == 2 )); then
-    _describe 'maintenance subcommand' subverbs
-  fi
-  _arguments $maint_opts
+  _arguments -C $maint_opts \
+    '1: :->verb' \
+    '*: :'
+
+  case "$state" in
+    verb)
+      _describe -t commands 'maintenance subcommand' subverbs
+      ;;
+  esac
 }
 
 _quilltap_completion() {
-  _values 'shell' bash zsh fish
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  _arguments -C \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '1: :(bash zsh fish)' \
+    '*: :'
+}
+
+# ---------------------------------------------------------------------------
+# Lookup helpers
+#
+# These shell out to quilltap itself, so they have to be told which instance
+# the user is addressing — otherwise `--instance Friday` completes mount names
+# from the default instance. _quilltap_ctx_flags rebuilds the addressing flags
+# from the command line being typed and the helpers pass them straight through.
+# ---------------------------------------------------------------------------
+
+_quilltap_ctx_flags() {
+  ctx_flags=()
+  local -i i=2
+  while (( i <= $#_quilltap_line )); do
+    case "$_quilltap_line[i]" in
+      -i|--instance|-d|--data-dir|--passphrase)
+        # The word under the cursor is a half-typed value, not an answer.
+        if (( i + 1 <= $#_quilltap_line && i + 1 != _quilltap_cword )) \
+          && [[ -n "$_quilltap_line[i+1]" ]]; then
+          ctx_flags+=("$_quilltap_line[i]" "${(Q)_quilltap_line[i+1]}")
+        fi
+        (( i += 2 ))
+        ;;
+      *)
+        (( i += 1 ))
+        ;;
+    esac
+  done
 }
 
 _quilltap_instance_names() {
-  local instances
+  local -a instances expl
   instances=(${(f)"$(command quilltap instances list --names-only 2>/dev/null)"})
-  _values 'instance' $instances
+  (( $#instances )) || return 1
+  # compadd -a, not _values: instance and store names may contain spaces and
+  # colons, which _values would chop into value:description pairs.
+  _wanted instances expl 'instance' compadd -a instances
+}
+
+_quilltap_mount_names() {
+  local -a ctx_flags mounts expl
+  _quilltap_ctx_flags
+  mounts=(${(f)"$(command quilltap docs list --names-only $ctx_flags 2>/dev/null)"})
+  (( $#mounts )) || return 1
+  _wanted mounts expl 'document store' compadd -a mounts
 }
 
 _quilltap "$@"

package/package.json

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