feat(cli): grok-style clap completions with tiny rc hook

PR_REVIEW_20260830_043010.md

@@ -0,0 +1,99 @@
+# PR Review — #37 feat(cli): grok-style clap completions with tiny rc hook
+
+**Branch:** `feat/clap-completion-install` → `main`  
+**PR:** https://github.com/Blankeos/crabcode/pull/37  
+**HEAD:** `56b69cc` + drop `.github/workflows/pr.yml` (Actions too expensive; remote-client `build.rs` gate)  
+**Merge confidence:** **4.5 / 5**
+
+---
+
+## Body (GitHub comment)
+
+Grok-style `crabcode completion [shell]` (+ `--install`). Clap prints the script; `--install` writes the autoload file and a marked rc block (zsh: `fpath` + `autoload` + `compdef`, no startup `source`). Fish is file-only. Zsh `#compdef` picks up `alias foo=crabcode` from `.zshrc` at install time. clap#6282 workaround drops the unused `[PROMPT]` slot so nested commands complete on `$line[1]`.
+
+Bare `crabcode completion` still prints (shell from `$SHELL`). `--install` strips an old `>> ~/.zshrc` dump. No DB/config migrations.
+
+Verified locally: 19/19 completion tests (incl. rc stripper, grok-hook idempotence, `$HOME` pwsh, zsh `-n` + command-list smoke). `cargo fmt --check` clean. **No PR Actions** — `build.rs` needs `just remote-client-build`; skipping CI on purpose.
+
+---
+
+## Diff summary
+
+| File | Change |
+| --- | --- |
+| `src/completion.rs` | generate / install / rc upsert / alias scan / clap#6282 patch; XDG; bash `.bashrc` else `.bash_profile`; pwsh `"$HOME/..."`; strip + hook tests |
+| `src/main.rs` | `Completion { shell: Option<Shell>, install }`; default from `$SHELL` |
+| `README.md` / `npm/README.md` | `--install` docs, XDG, `$SHELL` default, re-run note for old dumps |
+
+`.github/workflows/pr.yml` was added then **removed** (cost + `remote-client/dist` missing in CI).
+
+---
+
+## Regressions?
+
+**No remaining CLI break.** Previously `completion` required `<SHELL>` (`exit 2`); now `shell` is optional and defaults from `$SHELL` (zsh/fish/elvish/pwsh, else bash). Tab still lists shells for `crabcode completion <tab>`.
+
+Remaining (non-blocking):
+
+1. Old inline dumps in `.zshrc` are only stripped on `--install` (documented). Stripper is unit-tested (dump, usage-argv header, missing end marker = no-op, installer hook left alone, strip-then-append after grok).
+2. Zsh hook skips `compdef` if `compinit` has not run yet (`(( $+functions[compdef] ))`). Deliberate; block is appended at EOF.
+3. PowerShell completions path is still XDG-ish, not the usual pwsh profile completions dir. Hook now dotsources `"$HOME/..."` (tested).
+4. No `--uninstall`. CHANGELOG is git-cliff at tag time — don’t invent Unreleased.
+
+TUI / agent / persistence paths are untouched.
+
+---
+
+## Migrations?
+
+**No.**
+
+- No SQLite / `prefs` schema change
+- No `auth.json` format change
+- No `crabcode.json(c)` contract change
+
+`--install` mutates shell rc + autoload files (user-config install, not app state). Idempotent via markers.
+
+---
+
+## Checks run (non-mutating)
+
+| Check | Result |
+| --- | --- |
+| `cargo test --bin crabcode -- completion` | **19 passed** |
+| `cargo fmt --check` | **clean** |
+| `crabcode completion` (no shell) | parses; prints from `$SHELL` |
+| `crabcode completion zsh` | `#compdef crabcode`; `$line[1]`; no `::prompt` / `$line[2]` |
+| `--install` | **not run** (mutates rc) |
+| GitHub Actions PR CI | **skipped on purpose** |
+
+---
+
+## Checklist before merge
+
+- [x] Default `shell` from `$SHELL` so bare `crabcode completion` still prints
+- [x] Tests for `strip_inline_usage_completion`
+- [x] HOME-independent grok-hook test
+- [x] zsh smoke: parse (`zsh -n`) + command list includes `completion`
+- [x] `--install` idempotent after grok block (unit-tested)
+- [x] PowerShell `"$HOME/..."`
+- [x] XDG data/config; bash `.bashrc` else `.bash_profile`
+- [x] README: re-run `--install` if you used `>> ~/.zshrc`
+- [x] No PR Actions (too expensive; `build.rs` requires remote-client assets)
+- [ ] CHANGELOG: git-cliff on next `just tag` — no Unreleased section
+- [ ] No migration / prefs / auth follow-up
+
+---
+
+## Confidence bumps
+
+Was **3.5 / 5**. Now **4.5 / 5**.
+
+| Done | Score |
+| --- | --- |
+| Unit-test `strip_inline_usage_completion` + HOME-independent grok-hook test | 4.0 |
+| PowerShell `$HOME` + README re-run note | 4.25 |
+| `$SHELL` default **and** zsh Tab/parse smoke | **4.5** |
+| rust tests in CI on PRs | skipped (cost + remote-client `build.rs`) — would have been 4.75 |
+
+**5/5** would need a real `compadd` / `compgen` integration test or a dry-run `--install` that never touches `$HOME`. Not blocking if you dogfood zsh after merge.

README.md

@@ -80,13 +80,17 @@ It works (almost) exactly like OpenCode. Just opens faster, with some intuitive
 
 ### Shell Completion
 
-Generate a completion script for the current shell:
-
 ```sh
-crabcode completion >> ~/.zshrc
+crabcode completion zsh --install
 ```
 
-`crabcode completion` generates Zsh completions when `$SHELL` ends in `zsh`; it generates Bash completions for all other shells.
+Same for `bash`, `fish`, `elvish`, `powershell`. Restart the shell, then Tab.
+
+`--install` writes the script to the shell autoload path (`$XDG_DATA_HOME` / `$XDG_CONFIG_HOME` when set) and a small marked block in your rc (zsh/bash/elvish/powershell). Zsh autoloads on first Tab (`fpath` + `compdef`, no `source` of the script at startup). Fish autoloads from `~/.config/fish/completions` with no rc edit. Bash uses `~/.bashrc` if present, otherwise `~/.bash_profile`. PowerShell dotsources `"$HOME/..."`. If `.zshrc` has `alias cc=crabcode` (or similar), that name is included in the zsh script.
+
+Without `--install`, the script is printed to stdout. `crabcode completion` with no shell uses `$SHELL` (zsh/fish/elvish/pwsh, else bash).
+
+If you previously ran `crabcode completion >> ~/.zshrc`, re-run `--install` so that dump is stripped and replaced by the autoload hook.
 
 ### Agent Types
 

npm/README.md

@@ -36,6 +36,15 @@ cargo install crabcode             # or cargo (build from source)
 curl -sSL https://raw.githubusercontent.com/Blankeos/crabcode/main/install.sh | sh # or linux/macos (via curl)
 ```
 
+### Upgrade
+
+Detects how you installed (brew / npm / bun / cargo / install.sh) and upgrades in place:
+
+```sh
+crabcode upgrade          # latest
+crabcode upgrade 0.0.12   # specific version
+```
+
 ## Quick Start
 
 1. Run crabcode:
@@ -71,13 +80,17 @@ It works (almost) exactly like OpenCode. Just opens faster, with some intuitive
 
 ### Shell Completion
 
-Generate a completion script for the current shell:
-
 ```sh
-crabcode completion >> ~/.zshrc
+crabcode completion zsh --install
 ```
 
-`crabcode completion` generates Zsh completions when `$SHELL` ends in `zsh`; it generates Bash completions for all other shells.
+Same for `bash`, `fish`, `elvish`, `powershell`. Restart the shell, then Tab.
+
+`--install` writes the script to the shell autoload path (`$XDG_DATA_HOME` / `$XDG_CONFIG_HOME` when set) and a small marked block in your rc (zsh/bash/elvish/powershell). Zsh autoloads on first Tab (`fpath` + `compdef`, no `source` of the script at startup). Fish autoloads from `~/.config/fish/completions` with no rc edit. Bash uses `~/.bashrc` if present, otherwise `~/.bash_profile`. PowerShell dotsources `"$HOME/..."`. If `.zshrc` has `alias cc=crabcode` (or similar), that name is included in the zsh script.
+
+Without `--install`, the script is printed to stdout. `crabcode completion` with no shell uses `$SHELL` (zsh/fish/elvish/pwsh, else bash).
+
+If you previously ran `crabcode completion >> ~/.zshrc`, re-run `--install` so that dump is stripped and replaced by the autoload hook.
 
 ### Agent Types
 
@@ -134,6 +147,8 @@ Like any benchmark, please take this with a grain of salt. I have a cherry-picke
 | 🔲 opencode |  100% |  19/19 |    34.9s |        4612 |   $0.0279 |
 | ⚛️ codex    |  100% |  19/19 |    33.7s |       36888 |   $0.3506 |
 
+CLI startup / first-frame / idle-CPU vs peers (hyperfine + PTY): see **[PERF.md](PERF.md)** (`just bench-perf`).
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.