copa-cli 0.7.1__tar.gz → 0.9.0__tar.gz

{copa_cli-0.7.1 → copa_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.7.1
+Version: 0.9.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -36,12 +36,14 @@ Dynamic: license-file
 
 Copa tracks the commands you run, ranks them by frequency and recency, and gives you instant fuzzy search via fzf. Think of it as a smart, searchable, shareable upgrade to shell history.
 
+![Copa Demo](demos/00-hero.gif)
+
 ## Features
 
-- **Smart ranking** — commands scored by `2*log(1+freq) + 8*0.5^(age/3d)`, so frequent *and* recent commands float to the top
+- **Smart ranking** — commands scored by `2*log(1+freq) + 8*0.5^(age/3d)`, so frequent _and_ recent commands float to the top
 - **FTS search** — full-text search across commands and their descriptions
-- **fzf integration** — Ctrl+R opens a fuzzy-searchable command palette with preview pane; searches across commands *and* their descriptions
-- **Tab completion** — Copa supplements zsh's tab completion for *any* command using your command history database
+- **fzf integration** — Ctrl+R opens a fuzzy-searchable command palette with preview pane; searches across commands _and_ their descriptions
+- **Tab completion** — Copa supplements zsh's tab completion for _any_ command using your command history database
 - **Auto-evolution** — `copa evolve` finds your most-used commands from zsh history and promotes them
 - **LLM descriptions** — `copa fix --auto` uses Claude or ollama to generate descriptions for undescribed commands
 - **Script protocol** — `#@ Description:` / `#@ Usage:` / `#@ Purpose:` / `#@ Flag:` headers in your scripts are auto-detected by `copa scan` across all `$PATH` directories
@@ -49,6 +51,8 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **Inline suggestions** — ghost text appears as you type; Tab accepts or opens a completion menu with the suggestion highlighted
 - **Groups & Ctrl+G** — organize commands by project, device, or workflow; assign groups inline from the fzf palette with Ctrl+G
 - **Bulk operations** — Ctrl+B enters select mode for batch group assignment, batch deletion, or batch LLM description
+- **Recipes** — save multi-step command sequences as named recipes; `copa recipe run deploy` executes steps sequentially; share recipes via `.copa` files
+- **Directory-aware suggestions** — commands used in the current directory are boosted in suggestions; automatic, configurable, zero-effort
 - **Sharing & `copa create`** — export/import command sets as `.copa` JSON files; `copa create` scaffolds a `.copa` file from an existing group
 - **Set filtering** — scope list, search, and fzf to a specific shared set with `--set`
 - **MCP server** — expose your commands to Claude Code (or any MCP client)
@@ -96,6 +100,7 @@ copa setup
 ```
 
 This walks you through everything:
+
 1. Checks that **fzf** is installed (tells you how to install if missing)
 2. Creates the Copa database (`~/.copa/copa.db`)
 3. Adds shell integration to your `~/.zshrc` (prompts for confirmation)
@@ -134,6 +139,8 @@ copa sync
 
 Once shell integration is sourced, pressing **Ctrl+R** opens an fzf-powered command palette instead of the default zsh reverse search. This is Copa's primary interface.
 
+![Ctrl+R Palette](demos/04-ctrl-r-palette.gif)
+
 ### What you see
 
 Copa pipes every tracked command into fzf with aligned columns:
@@ -152,38 +159,41 @@ This is the key difference from plain zsh Ctrl+R: you're not just searching raw
 
 The header shows available modes. Press **Ctrl+R** again while fzf is open to cycle:
 
-| Mode | Sort order | Use case |
-|------|-----------|----------|
-| `all` | Score (frequency + recency) | Default — best commands float to top |
-| `frequent` | Frequency only | Find your most-used commands |
-| `recent` | Last used time | Find commands you ran recently |
+| Mode       | Sort order                  | Use case                             |
+| ---------- | --------------------------- | ------------------------------------ |
+| `all`      | Score (frequency + recency) | Default — best commands float to top |
+| `frequent` | Frequency only              | Find your most-used commands         |
+| `recent`   | Last used time              | Find commands you ran recently       |
+| `recipes`  | Run count                   | Browse and run multi-step recipes    |
 
 ### Keybindings
 
 While the fzf palette is open, these keys are available:
 
-| Key | Action | Effect |
-|-----|--------|--------|
-| **Ctrl+R** | Cycle mode | all → frequent → recent → all |
-| **Ctrl+V** | Append `&` | Run selected command in background |
-| **Ctrl+O** | Append `2>&1` | Merge stderr into stdout |
-| **Ctrl+X** | Append `\|` | Pipe into next command |
-| **Ctrl+T** | Append `>` | Redirect output |
-| **Ctrl+A** | Append `&&` | Chain with next command |
-| **Ctrl+/** | Append `2>/dev/null` | Suppress stderr |
-| **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+B** | Select mode | Enter multi-select for bulk operations (see below) |
-| **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 |
+| Key        | Action               | Effect                                                                       |
+| ---------- | -------------------- | ---------------------------------------------------------------------------- |
+| **Ctrl+R** | Cycle mode           | all → frequent → recent → recipes → all                                      |
+| **Ctrl+X** | Compose              | Opens a numbered menu to append shell operators (`\|`, `&&`, `>`, `&`, etc.) |
+| **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 |
+
+![Groups and Scoping](demos/05-groups-and-scoping.gif)
+
+| Key        | Action        | Effect                                                              |
+| ---------- | ------------- | ------------------------------------------------------------------- |
+| **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+B** | Select mode   | Enter multi-select for bulk operations (see below)                  |
+| **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 [Configuration](#configuration).
 
 ### Select mode (bulk operations)
 
+![Bulk Operations](demos/06-bulk-operations.gif)
+
 Press **Ctrl+B** from the Ctrl+R palette to enter **select mode**. This opens a new fzf view with multi-select enabled:
 
 - **Tab** toggles selection on individual commands
@@ -202,11 +212,11 @@ Selected 5 command(s).
 Action:
 ```
 
-| Action | What it does |
-|--------|-------------|
-| **g** | Assign all selected commands to a group (or clear their group) |
-| **d** | Delete all selected commands (with confirmation) |
-| **a** | Auto-generate descriptions for all selected commands using your configured LLM backend |
+| Action | What it does                                                                           |
+| ------ | -------------------------------------------------------------------------------------- |
+| **g**  | Assign all selected commands to a group (or clear their group)                         |
+| **d**  | Delete all selected commands (with confirmation)                                       |
+| **a**  | Auto-generate descriptions for all selected commands using your configured LLM backend |
 
 This is useful for organizing large command sets — select 20 undescribed commands and batch-describe them, or move a set of related commands into a group in one step.
 
@@ -220,18 +230,22 @@ Selecting a command places it directly into your shell prompt (without executing
 
 ## Tab Completion
 
+![Tab Menu Select](demos/03-tab-menu-select.gif)
+
 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
 
+![Completion Modes](demos/10-completion-modes.gif)
+
 Copa supports four completion modes, configured via `~/.copa/config.toml`:
 
-| Mode | Behavior |
-|------|----------|
+| 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 |
+| `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
@@ -269,6 +283,10 @@ Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as befor
 
 ## Inline Suggestions (Ghost Text)
 
+| Tab Mode 1 (direct accept)                         | Tab Mode 2 (menu select, default)                  |
+| -------------------------------------------------- | -------------------------------------------------- |
+| ![Tab Mode 1](demos/02a-suggestions-tab-mode1.gif) | ![Tab Mode 2](demos/02b-suggestions-tab-mode2.gif) |
+
 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
@@ -281,43 +299,49 @@ $ 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): open completion menu with suggestion highlighted at top, native completions below | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
-| **Down** | Open completion menu with suggestion highlighted at top | 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 |
+| 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): open completion menu with suggestion highlighted at top, native completions below | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
+| **Down**            | Open completion menu with suggestion highlighted at top                                                                                             | History navigation                                                     |
+| **Right arrow**     | Accept one word, re-fetch                                                                                                                           | Move cursor right                                                      |
+| **Cmd+Right / End** | Accept full suggestion                                                                                                                              | Move to end of line                                                    |
+| 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
 
 Copa supports two Tab behaviors when a suggestion is showing:
 
 **Menu select** (`tab_accept = 2`, default):
+
 1. Press **Tab** — ghost text clears, a completion menu opens with the Copa suggestion highlighted at the top, alongside native completions below
-2. Press **Tab** or **Space** — accepts the highlighted item
-3. Press **Escape** — cancels the menu, restores your original text
-4. Use **arrow keys** to navigate if you want a different completion
+2. Press **Tab** to cycle through options, **Shift+Tab** to cycle backward
+3. Press **Enter** or **Space** — accepts the highlighted item
+4. Press **Escape** — cancels the menu, restores your original text
+5. Use **arrow keys** to navigate if you want a different completion
 
 This gives you a chance to see alternatives before committing. The Copa suggestion is always the first item in the menu.
 
 **Inline accept** (`tab_accept = 1`):
+
 - Press **Tab** — the suggestion is accepted directly into your command line. One keystroke, done.
 
 ### Completion menu navigation
 
 When the completion menu is open (from Tab in `tab_accept = 2` mode or from normal tab completion):
 
-| Key | Action |
-|-----|--------|
-| **Tab** | Accept the highlighted completion |
-| **Space** | Accept the highlighted completion |
-| **Escape** | Cancel — dismiss menu, restore original text |
-| **Arrow keys** | Navigate between completions |
+| Key            | Action                                       |
+| -------------- | -------------------------------------------- |
+| **Tab**        | Cycle forward through completions                          |
+| **Shift+Tab**  | Cycle backward through completions                         |
+| **Enter**      | Accept the highlighted completion (no trailing space added) |
+| **Space**      | Accept the highlighted completion and add a space           |
+| **Escape**     | Cancel — dismiss menu, restore original text                |
+| **Arrow keys** | Navigate between completions                                |
 
 ### Backspace latch
 
@@ -441,6 +465,8 @@ copa describe 42
 
 Generates a description for a specific command by ID. Same accept/edit flow as `fix --auto`.
 
+![Flags and Describe](demos/09-flags-and-describe.gif)
+
 ## Script Metadata Protocol
 
 Copa recognizes `#@` headers in script files (checked in the first 50 lines):
@@ -470,12 +496,12 @@ Flags:
 
 ### Supported headers
 
-| Header | Effect |
-|--------|--------|
-| `#@ Description: <text>` | Sets the command description (highest priority) |
-| `#@ Usage: <text>` | Usage / invocation syntax |
-| `#@ Purpose: <text>` | Why the script exists / when to use it |
-| `#@ Flag: <flag>: <description>` | Document a flag/option (repeatable) |
+| Header                           | Effect                                          |
+| -------------------------------- | ----------------------------------------------- |
+| `#@ Description: <text>`         | Sets the command description (highest priority) |
+| `#@ Usage: <text>`               | Usage / invocation syntax                       |
+| `#@ Purpose: <text>`             | Why the script exists / when to use it          |
+| `#@ Flag: <flag>: <description>` | Document a flag/option (repeatable)             |
 
 Scripts without `#@` headers still work — Copa falls back to legacy patterns (`# Description:`, `# Purpose:`, Python docstrings, generic comments).
 
@@ -488,6 +514,8 @@ copa scan --dir ~/bin   # scan a specific directory
 
 ## Sharing
 
+![Sharing](demos/07-sharing.gif)
+
 Export a group as a `.copa` file:
 
 ```bash
@@ -510,25 +538,25 @@ copa share sync /path/to/team/copa-files/
 
 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 |
-| [`npm.copa`](examples/npm.copa) | Node.js package management |
-| [`network.copa`](examples/network.copa) | Network diagnostics |
-| [`curl-http.copa`](examples/curl-http.copa) | HTTP requests and API testing |
-| [`ssh-remote.copa`](examples/ssh-remote.copa) | SSH, SCP, and remote server management |
-| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
-| [`aws.copa`](examples/aws.copa) | AWS CLI cloud infrastructure |
-| [`terraform.copa`](examples/terraform.copa) | Terraform infrastructure-as-code |
-| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
-| [`systemd.copa`](examples/systemd.copa) | Linux service management |
-| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
-| [`process-monitoring.copa`](examples/process-monitoring.copa) | Process management and debugging |
-| [`disk-files.copa`](examples/disk-files.copa) | Disk usage and file management |
-| [`tmux.copa`](examples/tmux.copa) | Terminal multiplexer sessions |
-| [`homebrew.copa`](examples/homebrew.copa) | Homebrew package manager (macOS) |
+| 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            |
+| [`npm.copa`](examples/npm.copa)                               | Node.js package management             |
+| [`network.copa`](examples/network.copa)                       | Network diagnostics                    |
+| [`curl-http.copa`](examples/curl-http.copa)                   | HTTP requests and API testing          |
+| [`ssh-remote.copa`](examples/ssh-remote.copa)                 | SSH, SCP, and remote server management |
+| [`adb.copa`](examples/adb.copa)                               | Android Debug Bridge                   |
+| [`aws.copa`](examples/aws.copa)                               | AWS CLI cloud infrastructure           |
+| [`terraform.copa`](examples/terraform.copa)                   | Terraform infrastructure-as-code       |
+| [`k8s.copa`](examples/k8s.copa)                               | Kubernetes cluster management          |
+| [`systemd.copa`](examples/systemd.copa)                       | Linux service management               |
+| [`sysadmin.copa`](examples/sysadmin.copa)                     | System administration                  |
+| [`process-monitoring.copa`](examples/process-monitoring.copa) | Process management and debugging       |
+| [`disk-files.copa`](examples/disk-files.copa)                 | Disk usage and file management         |
+| [`tmux.copa`](examples/tmux.copa)                             | Terminal multiplexer sessions          |
+| [`homebrew.copa`](examples/homebrew.copa)                     | Homebrew package manager (macOS)       |
 
 Load any of them:
 
@@ -569,29 +597,96 @@ alias copa-bt='copa fzf-list --set bluetooth | fzf'
 
 ```json
 {
-    "copa_version": "1.0",
-    "name": "bluetooth",
-    "description": "Bluetooth commands for Android devices",
-    "author": "markstanford",
-    "commands": [
-        {
-            "command": "adb shell cmd bluetooth_manager enable",
-            "description": "Enable Bluetooth",
-            "tags": ["bt", "android"]
-        },
-        {
-            "command": "flash_all",
-            "description": "Flash AOSP build to device",
-            "tags": ["aosp"],
-            "flags": {
-                "-w, --wipe": "Wipe userdata before flashing",
-                "--skip <parts>": "Skip specific partitions"
-            }
-        }
-    ]
+  "copa_version": "1.0",
+  "name": "bluetooth",
+  "description": "Bluetooth commands for Android devices",
+  "author": "markstanford",
+  "commands": [
+    {
+      "command": "adb shell cmd bluetooth_manager enable",
+      "description": "Enable Bluetooth",
+      "tags": ["bt", "android"]
+    },
+    {
+      "command": "flash_all",
+      "description": "Flash AOSP build to device",
+      "tags": ["aosp"],
+      "flags": {
+        "-w, --wipe": "Wipe userdata before flashing",
+        "--skip <parts>": "Skip specific partitions"
+      }
+    }
+  ],
+  "recipes": [
+    {
+      "name": "bt-debug",
+      "description": "Enable BT and start logging",
+      "steps": [
+        {"command": "adb shell cmd bluetooth_manager enable", "description": "Enable BT"},
+        {"command": "adb logcat -s bt_btif | tee bt.log", "description": "Start BT logging"}
+      ]
+    }
+  ]
 }
 ```
 
+## Recipes
+
+![Recipes Demo](demos/12-recipes.gif)
+
+Recipes are named, ordered sequences of commands — like a script, but tracked and shareable through Copa.
+
+### Creating recipes
+
+```bash
+# Simple recipe
+copa recipe add deploy \
+  -s 'npm run build' \
+  -s 'docker build -t app .' \
+  -s 'docker push app'
+
+# With descriptions (use :: separator)
+copa recipe add deploy \
+  -d "Full production deploy" \
+  -g devops \
+  -s 'npm run build :: Build the project' \
+  -s 'npm run test :: Run test suite' \
+  -s 'docker push app :: Push to registry'
+```
+
+### Running recipes
+
+```bash
+# Run all steps sequentially
+copa recipe run deploy
+
+# Preview without executing
+copa recipe run deploy --dry-run
+
+# Continue past failures
+copa recipe run deploy --no-stop-on-error
+```
+
+### Managing recipes
+
+```bash
+copa recipe list              # List all recipes
+copa recipe list --json       # JSON output
+copa recipe show deploy       # Show steps
+copa recipe remove deploy     # Delete a recipe
+```
+
+### Sharing recipes
+
+Recipes are included in `.copa` files automatically — when you export a group, its recipes come along:
+
+```bash
+copa share export devops -o devops.copa    # includes recipes in that group
+copa share load devops.copa                # imports commands AND recipes
+```
+
+See `examples/docker.copa` and `examples/deploy.copa` for recipe examples.
+
 ## MCP Server (Claude Code integration)
 
 Copa includes an MCP server so Claude Code can search and add commands.
@@ -606,24 +701,37 @@ Add to your Claude Code MCP config (`.mcp.json` in your project or home dir):
 
 ```json
 {
-    "mcpServers": {
-        "copa": {
-            "command": "python3",
-            "args": ["-m", "copa.mcp_server"]
-        }
+  "mcpServers": {
+    "copa": {
+      "command": "python3",
+      "args": ["-m", "copa.mcp_server"]
     }
+  }
 }
 ```
 
 Available MCP tools:
+
 - `copa_search` — search commands by keyword
 - `copa_list_commands` — list commands ranked by score
 - `copa_list_groups` — list all groups
 - `copa_get_stats` — usage statistics
 - `copa_add_command` — add a command
 - `copa_update_description` — update a description
+- `copa_delete_command` — delete a command by ID
+- `copa_set_group` — set or change a command's group
+- `copa_update_flags` — update flag documentation for a command
+- `copa_pin_command` — pin or unpin a command
 - `copa_create_group` — create a group with commands
 - `copa_bulk_add` — bulk add commands
+- `copa_share_load` — load a .copa file as a shared set
+- `copa_share_list` — list all loaded shared sets
+- `copa_share_remove` — remove a shared set
+- `copa_export_group` — export a group as a .copa file
+- `copa_recipe_list` — list all recipes
+- `copa_recipe_show` — show a recipe's steps
+- `copa_recipe_add` — create a recipe from ordered steps
+- `copa_recipe_remove` — remove a recipe
 
 ## Configuration
 
@@ -636,12 +744,7 @@ Copa is configured via `~/.copa/config.toml`. All settings are optional — Copa
 # 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
+compose = "ctrl-x"          # open compose submenu (|, &&, >, &, 2>&1, 2>/dev/null)
 describe = "ctrl-d"         # LLM describe
 group = "ctrl-g"            # assign group (inline modal)
 flags = "ctrl-f"            # edit flags
@@ -661,65 +764,75 @@ enabled = true              # set to false to disable
 min_length = 2              # minimum chars before querying
 tab_accept = 2              # 1 = accept directly, 2 = open menu first
 color = 242                 # ghost text color (256-color palette)
+directory_aware = true      # boost suggestions from the current directory
 
-# 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
+# Fzf layout
+[layout]
+height = "80%"              # fzf height (default: 80%)
+preview_size = "40%"        # preview pane width (default: 40%)
 ```
 
-### Composition key behavior
+### Compose submenu
 
-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).
+![Composition](demos/08-composition.gif)
 
-By default, "connector" operators re-open fzf:
-- `pipe` (`|`) — continue
-- `chain` (`&&`) — continue
-- `redirect` (`>`) — continue
+Press **Ctrl+X** while a command is highlighted to open the compose submenu — a numbered menu of shell operators:
 
-And "terminal" operators close fzf:
-- `background` (`&`) — close
-- `merge_output` (`2>&1`) — close
-- `suppress` (`2>/dev/null`) — close
+```
+Compose: 1)| 2)&& 3)> 4)& 5)2>&1 6)2>/dev/null
+Select [1-6]:
+```
+
+| # | Operator      | Behavior   | What happens                                                |
+|---|---------------|------------|-------------------------------------------------------------|
+| 1 | `\|`          | continue   | Appends `\|` and re-opens fzf to select the next command    |
+| 2 | `&&`          | continue   | Appends `&&` and re-opens fzf to chain another command      |
+| 3 | `>`           | continue   | Appends `>` and re-opens fzf for the target                 |
+| 4 | `&`           | close      | Appends `&` and closes — run in background                  |
+| 5 | `2>&1`        | close      | Appends `2>&1` and closes — merge stderr                    |
+| 6 | `2>/dev/null` | close      | Appends `2>/dev/null` and closes — suppress stderr          |
+
+"Continue" operators re-open fzf so you can build multi-command pipelines. "Close" operators place the final command in your prompt.
 
 When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.
 
-To revert to the old behavior (all keys close immediately), set:
+## End-to-End Workflow
 
-```toml
-[composition]
-continue = []
-```
+![Workflow](demos/11-workflow.gif)
 
 ## CLI Reference
 
-| Command | Purpose |
-|---------|---------|
-| `copa setup` | Interactive setup wizard |
-| `copa add "cmd" -d "desc" -g group -f "flag: desc"` | Save a command (with optional flags) |
-| `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) |
-| `copa fix [--auto]` | Add missing descriptions (with optional LLM) |
-| `copa describe ID` | Generate description for one command |
-| `copa configure` | Set LLM backend (claude/ollama) |
-| `copa share export GROUP -o file` | Export group |
-| `copa share load SOURCE` | Load shared set |
-| `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 reset` | Wipe database and start fresh (keeps config) |
-| `copa uninstall` | Remove Copa data and show cleanup steps |
+| Command                                                  | Purpose                                                     |
+| -------------------------------------------------------- | ----------------------------------------------------------- |
+| `copa setup`                                             | Interactive setup wizard                                    |
+| `copa add "cmd" -d "desc" -g group -f "flag: desc"`      | Save a command (with optional flags)                        |
+| `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) |
+| `copa fix [--auto]`                                      | Add missing descriptions (with optional LLM)                |
+| `copa describe ID`                                       | Generate description for one command                        |
+| `copa configure`                                         | Set LLM backend (claude/ollama)                             |
+| `copa share export GROUP -o file`                        | Export group                                                |
+| `copa share load SOURCE`                                 | Load shared set                                             |
+| `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 recipe add NAME -s 'cmd' [-s 'cmd' ...]`          | Create a multi-step recipe                                  |
+| `copa recipe list [--json]`                              | List all recipes                                            |
+| `copa recipe show NAME`                                  | Show a recipe's steps                                       |
+| `copa recipe run NAME [--dry-run]`                       | Run a recipe's steps sequentially                           |
+| `copa recipe remove NAME`                                | Remove a recipe                                             |
+| `copa reset`                                             | Wipe database and start fresh (keeps config)                |
+| `copa uninstall`                                         | Remove Copa data and show cleanup steps                     |
 
 ## How Scoring Works
 
@@ -729,6 +842,8 @@ score = 2.0 * log(1 + frequency) + 8.0 * 0.5^(age_seconds / 3_days)
 
 Pinned commands get a +1000 bonus. The 3-day half-life means commands used in the last few days are strongly favored — a command used today scores ~8.0 recency, after 3 days ~4.0, after a week ~1.6.
 
+When `directory_aware = true` (default), commands get a bonus based on where you are: +5.0 for the same directory, +2.0 for a parent or child directory. This means `git push` suggests your project's branch, not another repo's.
+
 ## License
 
 MIT