@k-leumas/queque-cli 0.3.8 → 0.4.0

package/README.md

@@ -1,25 +1,35 @@
-# QueQue - your inline AI terminal helper
+# QueQue — copy-pasting shell commands is dead
 
-**Turn natural-language intent into a shell command — without leaving the terminal.**
+**Before:** Google it → copy → paste → tweak → pray.
 
-Type your intent, hit `??`, pick a command. It lands in your buffer ready to run or edit. No browser, no prompt takeover, no clipboard gymnastics.
+**Now:** Type your intent, hit `??`, pick a command — it lands in your buffer, ready to tweak and run.
 
-![QueQue demo](assets/demo.gif)
 
-## Install
+#### Copy-pasting commands from the browser is dead.
 
-```zsh
-brew install k-leumas/tap/queque
-```
+Welcome to the **future** –
+`
+ brew install k-leumas/tap/queque
+`
+
+
+![QueQue demo](assets/demo.gif)
 
 > [!NOTE]
-> The homebrew script automagically appends the shell-integration command and sources your `.zshrc`, which is shown during install.
+> After install, run `qq init zsh >> ~/.zshrc && source ~/.zshrc` to wire up the `??` keybinding.
 
 
 <details>
-<summary>Install via npm or source</summary>
+<summary>Install via npm</summary>
+
+## Requirements
 
-```zsh
+- zsh
+- Node.js ≥ 20
+- [jq](https://jqlang.github.io/jq/)
+
+
+```shell
 npm install -g @k-leumas/queque-cli
 qq init zsh >> ~/.zshrc && source ~/.zshrc
 ```
@@ -32,7 +42,7 @@ QueQue resolves `ANTHROPIC_API_KEY` in order:
 
 1. **Environment variable** — `export ANTHROPIC_API_KEY="sk-ant-..."` in your shell or `.zshrc`
 2. **`.env.local` file** — place a `.env.local` in your project directory (or any parent). QueQue searches upward from the current working directory:
-   ```
+   ```shell
    ANTHROPIC_API_KEY=sk-ant-...
    ```
 
@@ -42,7 +52,7 @@ The `.env.local` option is useful for project-specific keys or keeping the key o
 
 Type anything before `??` and QueQue turns it into a shell command:
 
-```
+```shell
 list files by size??
 find docker containers using port 3000??
 git undo last commit but keep changes??
@@ -50,45 +60,49 @@ git undo last commit but keep changes??
 
 A selection UI opens in-terminal. Pick a command with arrow keys or fuzzy search, press `Enter`, and the command lands in your buffer — ready to run or edit before you commit.
 
-Press `Esc` to cancel and return to what you were typing.
+Press `Esc` to cancel and return to what you were typing, you can even tweak your intent and hit `??` again.
 
 ### Inside Zellij
 
 QueQue detects Zellij automatically and opens in a floating pane instead of inline. Same trigger, same result, better layout.
 
-## Requirements
+Set `QQ_PANE_WIDTH` (default `80`) and `QQ_PANE_HEIGHT` (default `24`) to resize the floating pane.
 
-- zsh
-- Node.js ≥ 20
-- [jq](https://jqlang.github.io/jq/)
-- `ANTHROPIC_API_KEY`
+Without Zellij, QueQue falls back to an inline TUI in your current terminal session.
 
-## Configuration
+## Privacy defaults
 
-| Variable | Default | Description |
-|---|---|---|
-| `ANTHROPIC_API_KEY` | — | Required. Your Anthropic API key. |
-| `QQ_MODEL` | `claude-haiku-4-5-20251001` | Override the Claude model. |
-| `QQ_DEBUG_LOG_FILE` | — | Path to write a debug log (e.g. `/tmp/qq.log`). |
+QueQue is **insertion-only**: it writes commands into your shell buffer — you press Enter to run them. QueQue never auto-executes suggestions.
 
-Both env vars and `.env.local` are supported for all variables.
+**What leaves your machine (when using Claude):**
 
-## Contributing
+- Your query text and current working directory
+- Git metadata (branch, dirty flag, changed file *names* — not file contents)
+- Parsed filename hints from your query (no disk reads)
 
-```zsh
-git clone https://github.com/k-leumas/queque
-cd queque
-pnpm install
-pnpm dev        # watch build
-pnpm test:run   # run tests
-```
+**What QueQue never sends:**
 
-To wire up the dev build as the live `??` trigger:
+- File contents (unless you explicitly opt in later with `QQ_ALLOW_FILE_READ=1`)
+- Paths matching sensitive patterns (`.env`, credentials, `.pem`, `id_rsa`, etc.) are stripped from git context
+
+**Debug logging:** Off by default. When enabled, logs redact shell buffer text unless `QQ_DEBUG_VERBOSE=1`.
+
+**User config:** Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/config.json` to add extra sensitive path patterns, log redaction keys, or destructive-command warnings. Built-in defaults always apply — your patterns are merged on top. Override the file path with `QQ_CONFIG_FILE`. Malformed `config.json` is ignored with a warning; QueQue falls back to built-in defaults (fail-closed).
+
+See [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for the expansion path (local learning, multi-provider, plugins).
+
+## Configuration reference
+
+Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/config.json` (or set `QQ_CONFIG_FILE`). Field meanings:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `privacy.sensitivePathPatterns` | `string[]` | Extra regex patterns merged onto built-in defaults (`.env`, credentials, keys, etc.). Built-in patterns are never removed. |
+| `privacy.redactLogKeys` | `string[]` | Extra JSON keys to redact in debug logs (merged with defaults: `lbuffer`, `rbuffer`, `queryText`, `request`). |
+| `privacy.allowFileRead` | `boolean` | Opt-in gate for future file-content context. Env `QQ_ALLOW_FILE_READ=1` overrides this. No file reads in v1. |
+| `privacy.useGitignore` | `boolean` | Reserved for future gitignore-based filtering. Ignored today. |
+| `safety.destructiveCommandPatterns` | `string[]` | Extra warn-only UI patterns merged onto built-in defaults (`rm`, `sudo`, etc.). |
+
+See [docs/SYSTEM_DESIGN.md](docs/SYSTEM_DESIGN.md) for architecture and [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for Phase 7/8 expansion.
 
-```zsh
-export QQ_DEV_ROOT="$PWD"
-qq init zsh >> ~/.zshrc
-source ~/.zshrc
-```
 
-Changes to `src/` rebuild automatically and the widget picks them up immediately.