copa-cli 0.3.1__tar.gz → 0.6.0__tar.gz

{copa_cli-0.3.1 → copa_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.3.1
+Version: 0.6.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -52,11 +52,14 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **MCP server** — expose your commands to Claude Code (or any MCP client)
 - **Zero latency** — precmd hook records usage in the background
 
+> **Note:** Copa requires **zsh**. It is not compatible with bash, fish, or PowerShell.
+
 ## Install
 
 ### Prerequisites
 
 - **Python 3.12+**
+- **zsh** — Copa's shell integration (precmd hooks, ZLE widgets, inline suggestions) is zsh-only
 - **fzf** — required for Ctrl+R command palette
 
 ```bash
@@ -94,7 +97,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 +146,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 +166,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>
@@ -188,9 +213,62 @@ This works automatically once `copa.zsh` is sourced — no extra setup needed. T
 
 Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as before via Click's built-in completion.
 
+## Inline Suggestions (Ghost Text)
+
+Copa shows grey ghost text after your cursor as you type — the best matching command from your database, ranked by frequency and recency. This works like fish shell's autosuggestions or zsh-autosuggestions, with zero plugin dependencies.
+
+### How it works
+
+As you type, Copa queries its database for commands starting with your current input and displays the highest-scored match as dim grey text after the cursor. The suggestion updates on every keystroke.
+
+```
+$ git pu█sh origin main     ← grey ghost text
+```
+
+### Keybindings
+
+| Key | Suggestion showing | No suggestion |
+|-----|-------------------|---------------|
+| Type chars | Insert char, re-fetch suggestion | Insert char, fetch suggestion |
+| Backspace | Delete char, **latch** (suppress suggestions) | Delete char normally |
+| **Tab** | `tab_accept=1`: accept full suggestion. `tab_accept=2` (default): first Tab highlights suggestion (cyan), second Tab accepts | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
+| **Down** | Highlight suggestion (enter confirming state) | History navigation |
+| **Right arrow** | Accept one word, re-fetch | Move cursor right |
+| Enter | Clear suggestion, execute | Execute |
+| Esc | Dismiss suggestion | Normal Esc |
+| Up | Clear suggestion, navigate history | History navigation |
+| Ctrl+R | Clear suggestion, open fzf | Open fzf |
+
+### Tab accept mode
+
+By default (`tab_accept = 2`), pressing Tab when a suggestion is showing highlights the ghost text (changes from dim grey to cyan/bold) to indicate it's ready to be accepted. Pressing Tab again accepts it into the buffer. Pressing Esc reverts to dim grey without accepting. This two-step flow gives you a visual confirmation before committing.
+
+Set `tab_accept = 1` to restore the old behavior where a single Tab directly accepts the suggestion.
+
+### Backspace latch
+
+Pressing Backspace clears the current suggestion and **latches** — suppresses further suggestions while you edit. This prevents suggestions from re-appearing as you retype after correcting a mistake. Ctrl+W (backward-kill-word) also latches.
+
+Press **Tab** to unlatch and re-enable suggestions. The next new prompt (Enter) also resets the latch automatically.
+
+### Configuration
+
+```toml
+# ~/.copa/config.toml
+[suggest]
+enabled = true       # set to false to disable inline suggestions
+min_length = 2       # minimum characters before querying (default: 2)
+tab_accept = 2       # 1 = Tab accepts directly, 2 = Tab opens menu first (default)
+```
+
+Inline suggestions are enabled by default. Set `enabled = false` to disable them entirely (zero performance overhead when disabled).
+
 ## Quick Start
 
 ```bash
+# Check your setup
+copa doctor
+
 # Import your shell history
 copa sync
 
@@ -200,15 +278,24 @@ copa add "adb shell cmd bluetooth_manager enable" -d "Enable Bluetooth" -g bluet
 # Add a command with flag documentation
 copa add "flash_all" -d "Flash AOSP build" -f "--wipe: Wipe userdata" -f "-v: Verbose"
 
-# Create a .copa file from a group (or scaffold an empty one)
-copa create -g bluetooth
+# Pin your most important commands to the top
+copa pin 42
+
+# Edit a command's metadata
+copa edit 42 -d "New description" -g mygroup
 
 # List top commands by score
 copa list
 
+# List as JSON (for scripting)
+copa list --json
+
 # Search by keyword
 copa search bluetooth
 
+# Create a .copa file from a group (or scaffold an empty one)
+copa create -g bluetooth
+
 # Auto-promote frequent commands from history
 copa evolve -k 20
 
@@ -334,7 +421,7 @@ copa create -g bluetooth
 copa share export bluetooth -o bluetooth.copa
 ```
 
-Share it with your team (via git, fbsource, or any file share):
+Share it with your team (via git, Slack, or any file share):
 
 ```bash
 copa share load bluetooth.copa
@@ -342,6 +429,27 @@ copa share load /path/to/team/commands.copa
 copa share sync /path/to/team/copa-files/
 ```
 
+### Example shared sets
+
+Copa ships with ready-to-use `.copa` files in the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`git.copa`](examples/git.copa) | Essential Git commands |
+| [`docker.copa`](examples/docker.copa) | Docker container management |
+| [`python-dev.copa`](examples/python-dev.copa) | Python development workflow |
+| [`network.copa`](examples/network.copa) | Network diagnostics |
+| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
+| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
+| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
+
+Load any of them:
+
+```bash
+copa share load examples/git.copa
+copa share load examples/docker.copa
+```
+
 ### Filtering by shared set
 
 Once you've loaded shared sets, you can scope commands to just that set:
@@ -430,16 +538,85 @@ 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
+
+# Inline suggestions (ghost text)
+[suggest]
+enabled = true              # set to false to disable
+min_length = 2              # minimum chars before querying
+tab_accept = 2              # 1 = accept directly, 2 = open menu first
+
+# Composition key behavior (continue vs close)
+# "continue" keys re-open fzf so you can chain another command
+# All other composition keys close fzf immediately
+[composition]
+continue = ["pipe", "chain", "redirect"]  # default: |, &&, > re-open fzf
+```
+
+### Composition key behavior
+
+When you press a composition key (like Ctrl-A for `&&`), Copa can either **close fzf** (placing the command + operator in your prompt) or **continue** (appending the operator and re-opening fzf so you can select the next command to chain).
+
+By default, "connector" operators re-open fzf:
+- `pipe` (`|`) — continue
+- `chain` (`&&`) — continue
+- `redirect` (`>`) — continue
+
+And "terminal" operators close fzf:
+- `background` (`&`) — close
+- `merge_output` (`2>&1`) — close
+- `suppress` (`2>/dev/null`) — close
+
+When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.
+
+To revert to the old behavior (all keys close immediately), set:
+
+```toml
+[composition]
+continue = []
+```
+
 ## CLI Reference
 
 | Command | Purpose |
 |---------|---------|
 | `copa add "cmd" -d "desc" -g group -f "flag: desc"` | Save a command (with optional flags) |
-| `copa create -g group [-o file]` | Create a .copa file from a group |
-| `copa list [-g group] [-s source] [--set name]` | List by score |
-| `copa search "query" [-g group] [-s source] [--set name]` | FTS search |
+| `copa edit ID [-d desc] [-g group] [-f flags] [--pin]` | Edit a command's metadata |
 | `copa remove ID` | Remove a command |
+| `copa pin ID` | Pin a command to the top |
+| `copa unpin ID` | Unpin a command |
+| `copa list [-g group] [-s source] [--set name] [--json]` | List by score |
+| `copa search "query" [-g group] [--set name] [--json]` | FTS search |
+| `copa create -g group [-o file]` | Create a .copa file from a group |
 | `copa stats` | Usage statistics |
+| `copa doctor` | Check setup and diagnose issues |
 | `copa sync` | Import from zsh history |
 | `copa scan [--dir path]` | Import script metadata from $PATH |
 | `copa evolve [-k 20] [--auto]` | Auto-add frequent commands (with optional LLM descriptions) |
@@ -451,6 +628,7 @@ Available MCP tools:
 | `copa share list` | List shared sets |
 | `copa share sync DIR` | Sync .copa files from dir |
 | `copa import FILE [-g group]` | Import commands from markdown |
+| `copa uninstall` | Remove Copa data and show cleanup steps |
 
 ## How Scoring Works
 

{copa_cli-0.3.1 → copa_cli-0.6.0}/README.md

@@ -22,11 +22,14 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **MCP server** — expose your commands to Claude Code (or any MCP client)
 - **Zero latency** — precmd hook records usage in the background
 
+> **Note:** Copa requires **zsh**. It is not compatible with bash, fish, or PowerShell.
+
 ## Install
 
 ### Prerequisites
 
 - **Python 3.12+**
+- **zsh** — Copa's shell integration (precmd hooks, ZLE widgets, inline suggestions) is zsh-only
 - **fzf** — required for Ctrl+R command palette
 
 ```bash
@@ -64,7 +67,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 +116,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 +136,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>
@@ -158,9 +183,62 @@ This works automatically once `copa.zsh` is sourced — no extra setup needed. T
 
 Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as before via Click's built-in completion.
 
+## Inline Suggestions (Ghost Text)
+
+Copa shows grey ghost text after your cursor as you type — the best matching command from your database, ranked by frequency and recency. This works like fish shell's autosuggestions or zsh-autosuggestions, with zero plugin dependencies.
+
+### How it works
+
+As you type, Copa queries its database for commands starting with your current input and displays the highest-scored match as dim grey text after the cursor. The suggestion updates on every keystroke.
+
+```
+$ git pu█sh origin main     ← grey ghost text
+```
+
+### Keybindings
+
+| Key | Suggestion showing | No suggestion |
+|-----|-------------------|---------------|
+| Type chars | Insert char, re-fetch suggestion | Insert char, fetch suggestion |
+| Backspace | Delete char, **latch** (suppress suggestions) | Delete char normally |
+| **Tab** | `tab_accept=1`: accept full suggestion. `tab_accept=2` (default): first Tab highlights suggestion (cyan), second Tab accepts | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
+| **Down** | Highlight suggestion (enter confirming state) | History navigation |
+| **Right arrow** | Accept one word, re-fetch | Move cursor right |
+| Enter | Clear suggestion, execute | Execute |
+| Esc | Dismiss suggestion | Normal Esc |
+| Up | Clear suggestion, navigate history | History navigation |
+| Ctrl+R | Clear suggestion, open fzf | Open fzf |
+
+### Tab accept mode
+
+By default (`tab_accept = 2`), pressing Tab when a suggestion is showing highlights the ghost text (changes from dim grey to cyan/bold) to indicate it's ready to be accepted. Pressing Tab again accepts it into the buffer. Pressing Esc reverts to dim grey without accepting. This two-step flow gives you a visual confirmation before committing.
+
+Set `tab_accept = 1` to restore the old behavior where a single Tab directly accepts the suggestion.
+
+### Backspace latch
+
+Pressing Backspace clears the current suggestion and **latches** — suppresses further suggestions while you edit. This prevents suggestions from re-appearing as you retype after correcting a mistake. Ctrl+W (backward-kill-word) also latches.
+
+Press **Tab** to unlatch and re-enable suggestions. The next new prompt (Enter) also resets the latch automatically.
+
+### Configuration
+
+```toml
+# ~/.copa/config.toml
+[suggest]
+enabled = true       # set to false to disable inline suggestions
+min_length = 2       # minimum characters before querying (default: 2)
+tab_accept = 2       # 1 = Tab accepts directly, 2 = Tab opens menu first (default)
+```
+
+Inline suggestions are enabled by default. Set `enabled = false` to disable them entirely (zero performance overhead when disabled).
+
 ## Quick Start
 
 ```bash
+# Check your setup
+copa doctor
+
 # Import your shell history
 copa sync
 
@@ -170,15 +248,24 @@ copa add "adb shell cmd bluetooth_manager enable" -d "Enable Bluetooth" -g bluet
 # Add a command with flag documentation
 copa add "flash_all" -d "Flash AOSP build" -f "--wipe: Wipe userdata" -f "-v: Verbose"
 
-# Create a .copa file from a group (or scaffold an empty one)
-copa create -g bluetooth
+# Pin your most important commands to the top
+copa pin 42
+
+# Edit a command's metadata
+copa edit 42 -d "New description" -g mygroup
 
 # List top commands by score
 copa list
 
+# List as JSON (for scripting)
+copa list --json
+
 # Search by keyword
 copa search bluetooth
 
+# Create a .copa file from a group (or scaffold an empty one)
+copa create -g bluetooth
+
 # Auto-promote frequent commands from history
 copa evolve -k 20
 
@@ -304,7 +391,7 @@ copa create -g bluetooth
 copa share export bluetooth -o bluetooth.copa
 ```
 
-Share it with your team (via git, fbsource, or any file share):
+Share it with your team (via git, Slack, or any file share):
 
 ```bash
 copa share load bluetooth.copa
@@ -312,6 +399,27 @@ copa share load /path/to/team/commands.copa
 copa share sync /path/to/team/copa-files/
 ```
 
+### Example shared sets
+
+Copa ships with ready-to-use `.copa` files in the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`git.copa`](examples/git.copa) | Essential Git commands |
+| [`docker.copa`](examples/docker.copa) | Docker container management |
+| [`python-dev.copa`](examples/python-dev.copa) | Python development workflow |
+| [`network.copa`](examples/network.copa) | Network diagnostics |
+| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
+| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
+| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
+
+Load any of them:
+
+```bash
+copa share load examples/git.copa
+copa share load examples/docker.copa
+```
+
 ### Filtering by shared set
 
 Once you've loaded shared sets, you can scope commands to just that set:
@@ -400,16 +508,85 @@ 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
+
+# Inline suggestions (ghost text)
+[suggest]
+enabled = true              # set to false to disable
+min_length = 2              # minimum chars before querying
+tab_accept = 2              # 1 = accept directly, 2 = open menu first
+
+# Composition key behavior (continue vs close)
+# "continue" keys re-open fzf so you can chain another command
+# All other composition keys close fzf immediately
+[composition]
+continue = ["pipe", "chain", "redirect"]  # default: |, &&, > re-open fzf
+```
+
+### Composition key behavior
+
+When you press a composition key (like Ctrl-A for `&&`), Copa can either **close fzf** (placing the command + operator in your prompt) or **continue** (appending the operator and re-opening fzf so you can select the next command to chain).
+
+By default, "connector" operators re-open fzf:
+- `pipe` (`|`) — continue
+- `chain` (`&&`) — continue
+- `redirect` (`>`) — continue
+
+And "terminal" operators close fzf:
+- `background` (`&`) — close
+- `merge_output` (`2>&1`) — close
+- `suppress` (`2>/dev/null`) — close
+
+When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.
+
+To revert to the old behavior (all keys close immediately), set:
+
+```toml
+[composition]
+continue = []
+```
+
 ## CLI Reference
 
 | Command | Purpose |
 |---------|---------|
 | `copa add "cmd" -d "desc" -g group -f "flag: desc"` | Save a command (with optional flags) |
-| `copa create -g group [-o file]` | Create a .copa file from a group |
-| `copa list [-g group] [-s source] [--set name]` | List by score |
-| `copa search "query" [-g group] [-s source] [--set name]` | FTS search |
+| `copa edit ID [-d desc] [-g group] [-f flags] [--pin]` | Edit a command's metadata |
 | `copa remove ID` | Remove a command |
+| `copa pin ID` | Pin a command to the top |
+| `copa unpin ID` | Unpin a command |
+| `copa list [-g group] [-s source] [--set name] [--json]` | List by score |
+| `copa search "query" [-g group] [--set name] [--json]` | FTS search |
+| `copa create -g group [-o file]` | Create a .copa file from a group |
 | `copa stats` | Usage statistics |
+| `copa doctor` | Check setup and diagnose issues |
 | `copa sync` | Import from zsh history |
 | `copa scan [--dir path]` | Import script metadata from $PATH |
 | `copa evolve [-k 20] [--auto]` | Auto-add frequent commands (with optional LLM descriptions) |
@@ -421,6 +598,7 @@ Available MCP tools:
 | `copa share list` | List shared sets |
 | `copa share sync DIR` | Sync .copa files from dir |
 | `copa import FILE [-g group]` | Import commands from markdown |
+| `copa uninstall` | Remove Copa data and show cleanup steps |
 
 ## How Scoring Works