copa-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{copa_cli-0.3.0/copa_cli.egg-info → copa_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -94,7 +94,7 @@ Then restart your shell or run `source ~/.zshrc`. This does three things:
 
 1. **Records every command you run** — a `precmd` hook silently calls `copa _record` in the background after each command, building up frequency and recency data with zero latency impact.
 2. **Replaces Ctrl+R** — the default zsh reverse-history-search is replaced with Copa's fzf-powered command palette (see below).
-3. **Supplements tab completion** — Copa registers as a fallback completer so that any command gets completion candidates from your Copa database (see [Tab Completion](#tab-completion) below).
+3. **Supplements tab completion** — Copa registers as a completer so that any command gets completion candidates from your Copa database. The behavior is configurable (`fallback`, `hybrid`, `always`, or `never`) — see [Tab Completion](#tab-completion).
 
 Initialize the database:
 
@@ -143,11 +143,15 @@ While the fzf palette is open, these keys are available:
 | **Ctrl+T** | Append `>` | Redirect output |
 | **Ctrl+A** | Append `&&` | Chain with next command |
 | **Ctrl+/** | Append `2>/dev/null` | Suppress stderr |
-| **Ctrl+G** | Set group | Assign or change the group for the highlighted command |
-| **Ctrl+D** | Describe | Generate/edit a description for the highlighted command |
+| **Ctrl+S** | Scope by group | Opens inline group list — Enter filters to that group, ESC returns to all |
+| **Ctrl+G** | Assign group | Opens inline group list — Enter assigns the group to the highlighted command |
+| **Ctrl+N** | Cycle group | Cycles through groups: (all) → group1 → group2 → ... → (all) |
+| **Ctrl+D** | Describe | Generate/edit a description using LLM (with tty-aware input) |
 | **Ctrl+F** | Edit flags | Add flag documentation to the highlighted command |
+| **Ctrl+H** | Toggle header | Show/hide the key hints for more screen space |
+| **ESC** | Cancel/back | In scope/group mode: returns to command list. Otherwise: closes fzf |
 
-Keybindings are configurable via `~/.copa/config.toml`. See the `[keys]` section.
+Keybindings are configurable via `~/.copa/config.toml`. See [Configuration](#configuration).
 
 ### Preview pane
 
@@ -159,11 +163,29 @@ Selecting a command places it directly into your shell prompt (without executing
 
 ## Tab Completion
 
-Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a fallback completer in zsh's completion system.
+Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a completer in zsh's completion system.
+
+### Completion modes
+
+Copa supports four completion modes, configured via `~/.copa/config.toml`:
+
+| Mode | Behavior |
+|------|----------|
+| `fallback` | **(default)** Only show Copa completions when native completers found nothing |
+| `hybrid` | Show Copa completions alongside native completions (in a separate group) |
+| `always` | Copa completions replace native completions |
+| `never` | Disable Copa tab completion entirely |
+
+```toml
+# ~/.copa/config.toml
+[completion]
+mode = "fallback"    # fallback | hybrid | always | never
+branding = true      # show "Copa history" group header
+```
 
 ### How it works
 
-When you press Tab, zsh runs its normal completers first. If Copa's fallback also fires, it queries the Copa database for commands matching what you've typed so far and suggests the next word(s):
+When you press Tab, Copa queries its database for commands matching what you've typed so far and suggests the next word(s):
 
 ```
 $ adb shell dump<TAB>
@@ -430,6 +452,36 @@ Available MCP tools:
 - `copa_create_group` — create a group with commands
 - `copa_bulk_add` — bulk add commands
 
+## Configuration
+
+Copa is configured via `~/.copa/config.toml`. All settings are optional — Copa uses sensible defaults.
+
+```toml
+# ~/.copa/config.toml
+
+# Keybindings for the Ctrl+R fzf palette
+# Values are fzf key names: ctrl-<letter>, alt-<letter>, ctrl-/
+# ctrl-r and enter are reserved and cannot be reassigned
+[keys]
+background = "ctrl-v"       # append &
+merge_output = "ctrl-o"     # append 2>&1
+pipe = "ctrl-x"             # append |
+redirect = "ctrl-t"         # append >
+chain = "ctrl-a"            # append &&
+suppress = "ctrl-/"         # append 2>/dev/null
+describe = "ctrl-d"         # LLM describe
+group = "ctrl-g"            # assign group (inline modal)
+flags = "ctrl-f"            # edit flags
+filter_group = "ctrl-s"     # scope by group (inline modal)
+cycle_group = "ctrl-n"      # cycle through groups
+toggle_header = "ctrl-h"    # show/hide key hints
+
+# Tab completion behavior
+[completion]
+mode = "fallback"           # fallback | hybrid | always | never
+branding = true             # show "Copa history" group header
+```
+
 ## CLI Reference
 
 | Command | Purpose |

{copa_cli-0.3.0 → copa_cli-0.4.0}/README.md

@@ -64,7 +64,7 @@ Then restart your shell or run `source ~/.zshrc`. This does three things:
 
 1. **Records every command you run** — a `precmd` hook silently calls `copa _record` in the background after each command, building up frequency and recency data with zero latency impact.
 2. **Replaces Ctrl+R** — the default zsh reverse-history-search is replaced with Copa's fzf-powered command palette (see below).
-3. **Supplements tab completion** — Copa registers as a fallback completer so that any command gets completion candidates from your Copa database (see [Tab Completion](#tab-completion) below).
+3. **Supplements tab completion** — Copa registers as a completer so that any command gets completion candidates from your Copa database. The behavior is configurable (`fallback`, `hybrid`, `always`, or `never`) — see [Tab Completion](#tab-completion).
 
 Initialize the database:
 
@@ -113,11 +113,15 @@ While the fzf palette is open, these keys are available:
 | **Ctrl+T** | Append `>` | Redirect output |
 | **Ctrl+A** | Append `&&` | Chain with next command |
 | **Ctrl+/** | Append `2>/dev/null` | Suppress stderr |
-| **Ctrl+G** | Set group | Assign or change the group for the highlighted command |
-| **Ctrl+D** | Describe | Generate/edit a description for the highlighted command |
+| **Ctrl+S** | Scope by group | Opens inline group list — Enter filters to that group, ESC returns to all |
+| **Ctrl+G** | Assign group | Opens inline group list — Enter assigns the group to the highlighted command |
+| **Ctrl+N** | Cycle group | Cycles through groups: (all) → group1 → group2 → ... → (all) |
+| **Ctrl+D** | Describe | Generate/edit a description using LLM (with tty-aware input) |
 | **Ctrl+F** | Edit flags | Add flag documentation to the highlighted command |
+| **Ctrl+H** | Toggle header | Show/hide the key hints for more screen space |
+| **ESC** | Cancel/back | In scope/group mode: returns to command list. Otherwise: closes fzf |
 
-Keybindings are configurable via `~/.copa/config.toml`. See the `[keys]` section.
+Keybindings are configurable via `~/.copa/config.toml`. See [Configuration](#configuration).
 
 ### Preview pane
 
@@ -129,11 +133,29 @@ Selecting a command places it directly into your shell prompt (without executing
 
 ## Tab Completion
 
-Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a fallback completer in zsh's completion system.
+Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a completer in zsh's completion system.
+
+### Completion modes
+
+Copa supports four completion modes, configured via `~/.copa/config.toml`:
+
+| Mode | Behavior |
+|------|----------|
+| `fallback` | **(default)** Only show Copa completions when native completers found nothing |
+| `hybrid` | Show Copa completions alongside native completions (in a separate group) |
+| `always` | Copa completions replace native completions |
+| `never` | Disable Copa tab completion entirely |
+
+```toml
+# ~/.copa/config.toml
+[completion]
+mode = "fallback"    # fallback | hybrid | always | never
+branding = true      # show "Copa history" group header
+```
 
 ### How it works
 
-When you press Tab, zsh runs its normal completers first. If Copa's fallback also fires, it queries the Copa database for commands matching what you've typed so far and suggests the next word(s):
+When you press Tab, Copa queries its database for commands matching what you've typed so far and suggests the next word(s):
 
 ```
 $ adb shell dump<TAB>
@@ -400,6 +422,36 @@ Available MCP tools:
 - `copa_create_group` — create a group with commands
 - `copa_bulk_add` — bulk add commands
 
+## Configuration
+
+Copa is configured via `~/.copa/config.toml`. All settings are optional — Copa uses sensible defaults.
+
+```toml
+# ~/.copa/config.toml
+
+# Keybindings for the Ctrl+R fzf palette
+# Values are fzf key names: ctrl-<letter>, alt-<letter>, ctrl-/
+# ctrl-r and enter are reserved and cannot be reassigned
+[keys]
+background = "ctrl-v"       # append &
+merge_output = "ctrl-o"     # append 2>&1
+pipe = "ctrl-x"             # append |
+redirect = "ctrl-t"         # append >
+chain = "ctrl-a"            # append &&
+suppress = "ctrl-/"         # append 2>/dev/null
+describe = "ctrl-d"         # LLM describe
+group = "ctrl-g"            # assign group (inline modal)
+flags = "ctrl-f"            # edit flags
+filter_group = "ctrl-s"     # scope by group (inline modal)
+cycle_group = "ctrl-n"      # cycle through groups
+toggle_header = "ctrl-h"    # show/hide key hints
+
+# Tab completion behavior
+[completion]
+mode = "fallback"           # fallback | hybrid | always | never
+branding = true             # show "Copa history" group header
+```
+
 ## CLI Reference
 
 | Command | Purpose |

{copa_cli-0.3.0 → copa_cli-0.4.0}/copa/cli_internal.py

@@ -175,20 +175,20 @@ def set_flags(cmd_id: int):
 
 @click.command("_list-groups", hidden=True)
 def list_groups():
-    """Output group names for fzf group picker."""
+    """Output group names for fzf group picker (delimited for --with-nth)."""
     db = get_db()
-    click.echo("(all)")
+    click.echo("0┃(all)┃")
     for g in db.get_groups():
-        click.echo(g)
+        click.echo(f"0┃{g}┃")
 
 
 @click.command("_list-groups-for-assign", hidden=True)
 def list_groups_for_assign():
-    """Output group names for group-assign modal."""
+    """Output group names for group-assign modal (delimited for --with-nth)."""
     db = get_db()
-    click.echo("(none)")
+    click.echo("0┃(none)┃")
     for g in db.get_groups():
-        click.echo(g)
+        click.echo(f"0┃{g}┃")
 
 
 @click.command("_set-group-direct", hidden=True)

{copa_cli-0.3.0 → copa_cli-0.4.0}/copa/config.py

@@ -71,12 +71,14 @@ def load_config(path: Path | None = None) -> dict:
     Returns a dict with:
     - All action_name -> fzf_key entries (keybindings)
     - "_completion_branding" -> bool (whether to show Copa branding on tab completions)
+    - "_completion_mode" -> str (fallback|always|hybrid|never)
 
     Silently ignores: unknown actions, invalid key names, reserved keys,
     duplicate assignments. Falls back to all defaults on malformed TOML.
     """
     config: dict = dict(DEFAULT_KEYS)
     config["_completion_branding"] = True  # default: show branding
+    config["_completion_mode"] = "fallback"  # default: only when native completers found nothing
 
     if path is None:
         path = Path.home() / ".copa" / "config.toml"
@@ -97,6 +99,9 @@ def load_config(path: Path | None = None) -> dict:
         branding = completion_section.get("branding")
         if isinstance(branding, bool):
             config["_completion_branding"] = branding
+        mode = completion_section.get("mode")
+        if isinstance(mode, str) and mode in ("fallback", "always", "hybrid", "never"):
+            config["_completion_mode"] = mode
 
     keys_section = data.get("keys")
     if not isinstance(keys_section, dict):
@@ -177,9 +182,11 @@ def emit_zsh_config(config: dict[str, str]) -> str:
     # Use $'...\n...' quoting so zsh interprets the newline
     lines.append(f"_COPA_HEADER=$'{row1}\\n{row2}'")
 
-    # Completion branding
+    # Completion config
     branding = config.get("_completion_branding", True)
     lines.append(f"_COPA_COMPLETION_BRANDING='{'true' if branding else 'false'}'")
+    completion_mode = config.get("_completion_mode", "fallback")
+    lines.append(f"_COPA_COMPLETION_MODE='{completion_mode}'")
 
     # Suffix associative array
     lines.append("typeset -gA _COPA_SUFFIXES")

{copa_cli-0.3.0 → copa_cli-0.4.0}/copa/copa.zsh

@@ -19,6 +19,7 @@ eval "$(copa _fzf-config 2>/dev/null)" || {
   _COPA_CYCLE_GROUP_KEY='ctrl-n'
   _COPA_TOGGLE_HEADER_KEY='ctrl-h'
   _COPA_COMPLETION_BRANDING='true'
+  _COPA_COMPLETION_MODE='fallback'
   _COPA_HEADER=$'Copa | ^R:cycle | ^V:& | ^O:2>&1 | ^X:| | ^T:> | ^A:&& | ^/:quiet | ^H:keys\n^G:grp | ^D:desc | ^F:flag | ^S:scope | ^N:↻grp'
   typeset -gA _COPA_SUFFIXES
   _COPA_SUFFIXES[ctrl-v]=' &'
@@ -73,10 +74,10 @@ _copa_fzf_widget() {
         --expect "$_COPA_EXPECT" \
         --bind "${_COPA_DESCRIBE_KEY}:execute($copa_bin describe {1})+refresh-preview" \
         --bind "${_COPA_FLAGS_KEY}:execute($copa_bin _set-flags {1})+reload($copa_bin fzf-list)+refresh-preview" \
-        --bind "${_COPA_FILTER_GROUP_KEY}:reload($copa_bin _list-groups)+change-prompt(scope> )+clear-query" \
+        --bind "${_COPA_FILTER_GROUP_KEY}:reload($copa_bin _list-groups)+change-prompt(scope> )+clear-query+hide-preview" \
         --bind "${_COPA_GROUP_KEY}:transform:
           echo {1} > ${_copa_modal_file};
-          echo \"reload(${copa_bin} _list-groups-for-assign)+change-prompt(group> )+clear-query\"" \
+          echo \"reload(${copa_bin} _list-groups-for-assign)+change-prompt(group> )+clear-query+hide-preview\"" \
         --bind "${_COPA_CYCLE_GROUP_KEY}:transform:
           cur_group='(all)';
           if [[ \$FZF_PROMPT =~ 'copa \\[(.+)\\]> ' ]]; then
@@ -99,23 +100,23 @@ _copa_fzf_widget() {
         --bind "${_COPA_TOGGLE_HEADER_KEY}:toggle-header" \
         --bind 'enter:transform:
           if [[ $FZF_PROMPT == "scope> " ]]; then
-            selected={};
+            selected={2};
             if [[ $selected == "(all)" ]]; then
-              echo "reload('"$copa_bin"' fzf-list --mode all)+change-prompt(copa> )+clear-query"
+              echo "reload('"$copa_bin"' fzf-list --mode all)+change-prompt(copa> )+clear-query+show-preview"
             else
-              echo "reload('"$copa_bin"' fzf-list --mode group --group $selected)+change-prompt(copa [$selected]> )+clear-query"
+              echo "reload('"$copa_bin"' fzf-list --mode group --group $selected)+change-prompt(copa [$selected]> )+clear-query+show-preview"
             fi
           elif [[ $FZF_PROMPT == "group> " ]]; then
             cmd_id=$(cat '"${_copa_modal_file}"');
-            selected={};
+            selected={2};
             '"$copa_bin"' _set-group-direct $cmd_id $selected;
-            echo "reload('"$copa_bin"' fzf-list)+change-prompt(copa> )+clear-query"
+            echo "reload('"$copa_bin"' fzf-list)+change-prompt(copa> )+clear-query+show-preview"
           else
             echo "accept"
           fi' \
         --bind 'esc:transform:
           if [[ $FZF_PROMPT == "scope> " || $FZF_PROMPT == "group> " ]]; then
-            echo "reload('"$copa_bin"' fzf-list)+change-prompt(copa> )+clear-query"
+            echo "reload('"$copa_bin"' fzf-list)+change-prompt(copa> )+clear-query+show-preview"
           else
             echo "abort"
           fi' \
@@ -151,18 +152,33 @@ fi
 eval "$(copa completion zsh)"
 
 # --- Supplemental tab completion from Copa database ---
-# Registers as a fallback completer so that any command (e.g. adb <TAB>)
-# gets completion candidates from Copa's command history.
+# Mode is controlled by _COPA_COMPLETION_MODE (set via copa _fzf-config):
+#   fallback — only when native completers found nothing (default)
+#   always   — Copa completions replace native completions
+#   hybrid   — Copa completions shown alongside native completions
+#   never    — disable Copa tab completion entirely
+if [[ "$_COPA_COMPLETION_MODE" != 'never' ]]; then
+
 _copa_history_complete() {
-    # Only provide Copa completions when primary completers found nothing
-    (( compstate[nmatches] > 0 )) && return
+    # In fallback mode, only show when native completers found nothing
+    if [[ "$_COPA_COMPLETION_MODE" == 'fallback' ]]; then
+        (( compstate[nmatches] > 0 )) && return
+    fi
     # Skip empty tokens (bare <TAB> with no partial input)
     [[ -z "${words[CURRENT]}" ]] && return
     # Skip internal copa commands
     [[ "${words[CURRENT]}" == _copa_* ]] && return
     local -a results
     results=("${(@f)$(copa _complete-word "${(@)words[1,CURRENT]}" 2>/dev/null)}")
-    (( ${#results} )) && compadd -V 'copa-history' -o nosort -- "${results[@]}"
+    if (( ${#results} )); then
+        if [[ "$_COPA_COMPLETION_MODE" == 'always' ]]; then
+            # Replace: clear native matches, add only Copa results
+            compadd -U -V 'copa-history' -o nosort -- "${results[@]}"
+        else
+            # fallback & hybrid: add Copa results as a separate group
+            compadd -V 'copa-history' -o nosort -- "${results[@]}"
+        fi
+    fi
 }
 
 # Append to existing completers without clobbering user config
@@ -177,3 +193,5 @@ _copa_history_complete() {
         zstyle ':completion:*:*:*:copa-history' group-header '%F{magenta}-- Copa history --%f'
     fi
 }
+
+fi  # end _COPA_COMPLETION_MODE != 'never'

{copa_cli-0.3.0 → copa_cli-0.4.0}/copa/fzf.py

@@ -37,7 +37,7 @@ def format_lines(commands: list[Command]) -> list[str]:
         return []
 
     # Compute column widths from the full list
-    max_cmd = min(max(len(c.command) for c in commands), 60)
+    max_cmd = max(len(c.command) for c in commands)
     max_grp = max(
         (len(f"[{c.group_name}]") for c in commands if c.group_name),
         default=0,
@@ -48,11 +48,10 @@ def format_lines(commands: list[Command]) -> list[str]:
         # Field 1: hidden ID
         id_field = f"{cmd.id:>5}"
 
-        # Field 2: command text, padded for column alignment
-        cmd_text = cmd.command
-        if len(cmd_text) > 60:
-            cmd_text = cmd_text[:57] + "..."
-        cmd_field = f" {cmd_text:<{max_cmd}} "
+        # Field 2: command text — full text, never truncated.
+        # fzf handles overflow with horizontal scrolling.
+        # Padding uses max_cmd for column alignment on shorter commands.
+        cmd_field = f" {cmd.command:<{max_cmd}} "
 
         # Field 3: metadata — pin indicator, group badge, frequency
         pin = f"{_YELLOW}*{_RESET} " if cmd.is_pinned else "  "

{copa_cli-0.3.0 → copa_cli-0.4.0/copa_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -94,7 +94,7 @@ Then restart your shell or run `source ~/.zshrc`. This does three things:
 
 1. **Records every command you run** — a `precmd` hook silently calls `copa _record` in the background after each command, building up frequency and recency data with zero latency impact.
 2. **Replaces Ctrl+R** — the default zsh reverse-history-search is replaced with Copa's fzf-powered command palette (see below).
-3. **Supplements tab completion** — Copa registers as a fallback completer so that any command gets completion candidates from your Copa database (see [Tab Completion](#tab-completion) below).
+3. **Supplements tab completion** — Copa registers as a completer so that any command gets completion candidates from your Copa database. The behavior is configurable (`fallback`, `hybrid`, `always`, or `never`) — see [Tab Completion](#tab-completion).
 
 Initialize the database:
 
@@ -143,11 +143,15 @@ While the fzf palette is open, these keys are available:
 | **Ctrl+T** | Append `>` | Redirect output |
 | **Ctrl+A** | Append `&&` | Chain with next command |
 | **Ctrl+/** | Append `2>/dev/null` | Suppress stderr |
-| **Ctrl+G** | Set group | Assign or change the group for the highlighted command |
-| **Ctrl+D** | Describe | Generate/edit a description for the highlighted command |
+| **Ctrl+S** | Scope by group | Opens inline group list — Enter filters to that group, ESC returns to all |
+| **Ctrl+G** | Assign group | Opens inline group list — Enter assigns the group to the highlighted command |
+| **Ctrl+N** | Cycle group | Cycles through groups: (all) → group1 → group2 → ... → (all) |
+| **Ctrl+D** | Describe | Generate/edit a description using LLM (with tty-aware input) |
 | **Ctrl+F** | Edit flags | Add flag documentation to the highlighted command |
+| **Ctrl+H** | Toggle header | Show/hide the key hints for more screen space |
+| **ESC** | Cancel/back | In scope/group mode: returns to command list. Otherwise: closes fzf |
 
-Keybindings are configurable via `~/.copa/config.toml`. See the `[keys]` section.
+Keybindings are configurable via `~/.copa/config.toml`. See [Configuration](#configuration).
 
 ### Preview pane
 
@@ -159,11 +163,29 @@ Selecting a command places it directly into your shell prompt (without executing
 
 ## Tab Completion
 
-Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a fallback completer in zsh's completion system.
+Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a completer in zsh's completion system.
+
+### Completion modes
+
+Copa supports four completion modes, configured via `~/.copa/config.toml`:
+
+| Mode | Behavior |
+|------|----------|
+| `fallback` | **(default)** Only show Copa completions when native completers found nothing |
+| `hybrid` | Show Copa completions alongside native completions (in a separate group) |
+| `always` | Copa completions replace native completions |
+| `never` | Disable Copa tab completion entirely |
+
+```toml
+# ~/.copa/config.toml
+[completion]
+mode = "fallback"    # fallback | hybrid | always | never
+branding = true      # show "Copa history" group header
+```
 
 ### How it works
 
-When you press Tab, zsh runs its normal completers first. If Copa's fallback also fires, it queries the Copa database for commands matching what you've typed so far and suggests the next word(s):
+When you press Tab, Copa queries its database for commands matching what you've typed so far and suggests the next word(s):
 
 ```
 $ adb shell dump<TAB>
@@ -430,6 +452,36 @@ Available MCP tools:
 - `copa_create_group` — create a group with commands
 - `copa_bulk_add` — bulk add commands
 
+## Configuration
+
+Copa is configured via `~/.copa/config.toml`. All settings are optional — Copa uses sensible defaults.
+
+```toml
+# ~/.copa/config.toml
+
+# Keybindings for the Ctrl+R fzf palette
+# Values are fzf key names: ctrl-<letter>, alt-<letter>, ctrl-/
+# ctrl-r and enter are reserved and cannot be reassigned
+[keys]
+background = "ctrl-v"       # append &
+merge_output = "ctrl-o"     # append 2>&1
+pipe = "ctrl-x"             # append |
+redirect = "ctrl-t"         # append >
+chain = "ctrl-a"            # append &&
+suppress = "ctrl-/"         # append 2>/dev/null
+describe = "ctrl-d"         # LLM describe
+group = "ctrl-g"            # assign group (inline modal)
+flags = "ctrl-f"            # edit flags
+filter_group = "ctrl-s"     # scope by group (inline modal)
+cycle_group = "ctrl-n"      # cycle through groups
+toggle_header = "ctrl-h"    # show/hide key hints
+
+# Tab completion behavior
+[completion]
+mode = "fallback"           # fallback | hybrid | always | never
+branding = true             # show "Copa history" group header
+```
+
 ## CLI Reference
 
 | Command | Purpose |

{copa_cli-0.3.0 → copa_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "copa-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Command Palette — smart command tracking, ranking, and sharing for your shell"
 readme = "README.md"
 license = "MIT"

{copa_cli-0.3.0 → copa_cli-0.4.0}/tests/test_modal.py

@@ -27,7 +27,9 @@ class TestListGroupsForAssign:
         result = runner.invoke(cli, ["_list-groups-for-assign"])
         assert result.exit_code == 0
         lines = result.output.strip().split("\n")
-        assert lines[0] == "(none)"
+        # Delimited format: 0┃(none)┃
+        assert "(none)" in lines[0]
+        assert "┃" in lines[0]
 
     def test_outputs_groups(self, tmp_path, monkeypatch):
         db = self._make_db(tmp_path, monkeypatch)
@@ -37,16 +39,19 @@ class TestListGroupsForAssign:
         result = runner.invoke(cli, ["_list-groups-for-assign"])
         assert result.exit_code == 0
         lines = result.output.strip().split("\n")
-        assert lines[0] == "(none)"
-        assert "alpha" in lines
-        assert "beta" in lines
+        assert "(none)" in lines[0]
+        group_names = [line.split("┃")[1] for line in lines]
+        assert "alpha" in group_names
+        assert "beta" in group_names
 
     def test_no_groups_just_none(self, tmp_path, monkeypatch):
         self._make_db(tmp_path, monkeypatch)
         runner = CliRunner()
         result = runner.invoke(cli, ["_list-groups-for-assign"])
         assert result.exit_code == 0
-        assert result.output.strip() == "(none)"
+        lines = result.output.strip().split("\n")
+        assert len(lines) == 1
+        assert "(none)" in lines[0]
 
 
 class TestSetGroupDirect:
@@ -144,6 +149,39 @@ class TestConfigToggleHeader:
                 break
 
 
+class TestCompletionMode:
+    """Test completion mode config."""
+
+    def test_default_mode_is_fallback(self):
+        config = load_config()
+        assert config["_completion_mode"] == "fallback"
+
+    def test_emit_zsh_config_has_completion_mode(self):
+        config = load_config()
+        output = emit_zsh_config(config)
+        assert "_COPA_COMPLETION_MODE='fallback'" in output
+
+    def test_load_config_accepts_valid_modes(self, tmp_path):
+        for mode in ("fallback", "always", "hybrid", "never"):
+            config_file = tmp_path / f"config_{mode}.toml"
+            config_file.write_text(f'[completion]\nmode = "{mode}"\n')
+            config = load_config(config_file)
+            assert config["_completion_mode"] == mode
+
+    def test_load_config_rejects_invalid_mode(self, tmp_path):
+        config_file = tmp_path / "config.toml"
+        config_file.write_text('[completion]\nmode = "bogus"\n')
+        config = load_config(config_file)
+        assert config["_completion_mode"] == "fallback"
+
+    def test_emit_modes_in_output(self):
+        config = load_config()
+        for mode in ("fallback", "always", "hybrid", "never"):
+            config["_completion_mode"] = mode
+            output = emit_zsh_config(config)
+            assert f"_COPA_COMPLETION_MODE='{mode}'" in output
+
+
 class TestTtyHelpersInCommon:
     """Test that tty helpers are accessible from cli_common."""