crow-cli 0.1.40__tar.gz → 0.1.41__tar.gz

crow_cli-0.1.41/.env.example

@@ -0,0 +1,2 @@
+ZAI_API_KEY=lm-studio
+ZAI_BASE_URL=http://coast-after-3:1234/v1

crow_cli-0.1.41/.github/workflows/build-binaries.yml

@@ -0,0 +1,101 @@
+name: Build Binaries
+
+on:
+  push:
+    tags:
+      - "v*" # Trigger on version tags like v0.1.13
+
+jobs:
+  build:
+    name: Build ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          [
+            ubuntu-22.04,
+            macos-15-intel,
+            macos-latest,
+            windows-latest,
+            ubuntu-24.04-arm,
+          ]
+        include:
+          - os: ubuntu-22.04
+            target: linux-x86_64
+            archive_name: crow-cli-linux-x86_64.tar.gz
+          - os: macos-15-intel
+            target: darwin-x86_64
+            archive_name: crow-cli-darwin-x86_64.tar.gz
+          - os: macos-latest
+            target: darwin-aarch64
+            archive_name: crow-cli-darwin-aarch64.tar.gz
+          - os: windows-latest
+            target: windows-x86_64
+            archive_name: crow-cli-windows-x86_64.zip
+          - os: ubuntu-24.04-arm
+            target: linux-aarch64
+            archive_name: crow-cli-linux-aarch64.tar.gz
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system pyinstaller
+
+      - name: Build with PyInstaller
+        run: |
+          uv run pyinstaller crow-cli.spec --noconfirm
+
+      - name: Create archive
+        shell: bash
+        run: |
+          cd dist
+          if [ "${{ runner.os }}" == "Windows" ]; then
+            7z a -tzip ${{ matrix.archive_name }} crow-cli.exe
+          else
+            tar -czvf ${{ matrix.archive_name }} crow-cli
+          fi
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: crow-cli-${{ matrix.target }}
+          path: ${{ matrix.archive_name }}
+          retention-days: 30
+
+  release:
+    name: Create Release
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: crow-cli-*
+          merge-multiple: true
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            crow-cli-*.tar.gz
+            crow-cli-*.zip
+          draft: false
+          prerelease: false
+          generate_release_notes: true

crow_cli-0.1.41/.github/workflows/publish-crow-cli.yml

@@ -0,0 +1,42 @@
+name: Publish crow-cli to PyPI
+
+# Manual-only publish of the single package in this repo. Idempotent: a
+# version already live on PyPI is skipped, so a failed run can simply be
+# re-dispatched.
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/crow-cli
+    permissions:
+      id-token: write  # Required for trusted publishing
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Build and publish (skip if already on PyPI)
+        run: |
+          set -euo pipefail
+          VERSION=$(grep -m1 '^version' pyproject.toml | sed -E 's/.*"(.*)".*/\1/')
+          if curl -fsS "https://pypi.org/pypi/crow-cli/$VERSION/json" -o /dev/null; then
+            echo "crow-cli $VERSION is already on PyPI — skipping publish"
+          else
+            uv build
+            uv publish
+          fi

crow_cli-0.1.41/.python-version

@@ -0,0 +1 @@
+3.14

crow_cli-0.1.41/AGENTS.md

@@ -0,0 +1,30 @@
+# RULES
+
+- Never mention the user's emotional state. I'm here to work, NOT be psychoanalyzed by a machine.
+
+# TUI TERMINAL KNOWLEDGE (verified, don't re-derive)
+
+- ANSI emulator resize semantics ARE the product: alternate-screen buffers
+  must resize like pyte/real terminals (truncate columns on width shrink,
+  top-trim/pad on height change, 1:1 grid rows <-> buffer lines, clamp
+  cursor) — folding stale wide lines breaks CUP row addressing = garble.
+  Scrollback (normal) screen keeps folding. Oracle test: pyte dev dep.
+- Two terminal pathways by mandate: `tui/agent_terminal.py::AgentTerminal`
+  (headless PTY + raw byte capture) backs the ACP terminal tool; the
+  human-facing emulator (TerminalTool/EditorTerminal) is separate. A
+  suspended conversation has window size 0 — never size a PTY from it.
+- Textual gotchas: `Widget.screen` is a Textual property (name pyte
+  screens `pyte_screen`); `Strip` API is cell-based in Textual 8
+  (`crop_extend(0, w, None)`, `adjust_cell_length`); Textual 8.2.x breaks
+  on rich>=15 (uses Style internals rich dropped) — pin rich<15.
+- pyte color values are "default", ANSI names, or 6-char hex strings for
+  BOTH 256-color and truecolor — never numeric palette indices (an
+  all-digit hex like "281733" is truecolor).
+- A TUI only sends DIFFS: any fresh out-of-process terminal client
+  (riotermjs, reconnect) sees a blank/stale screen unless the child is
+  forced to full-repaint (winsize nudge: set cols-1 then cols).
+- sandbox/textual-term-toy: the terminal-in-a-column experiment + the
+  riotermjs browser harness (bridge.py = PTY<->websocket; harness/ = page
+  with importmap to ~/src/riotermjs dist). How to view the TUI in a
+  browser: run bridge.py + `python -m http.server --directory harness`,
+  open the page, screenshot via playwright-cli.

{crow_cli-0.1.40 → crow_cli-0.1.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: crow-cli
-Version: 0.1.40
+Version: 0.1.41
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/crow-cli/crow-cli
 Project-URL: Repository, https://github.com/crow-cli/crow-cli

crow_cli-0.1.41/PLAN.md

@@ -0,0 +1,187 @@
+# PLAN — open files in helix inside a terminal tab
+
+## **DO NOT ASK USER FOR FEEDBACK — THIS IS THE USER FEEDBACK.**
+## **DO NOT ASK USER FOR NEXT STEPS — THESE ARE THE NEXT STEPS.**
+
+### The unlock (user, 30Aug2026)
+Clicking a file in the TUI's project explorer must open **helix editing that
+file inside a new session tab**, where the tab body is a **real terminal
+emulator running the `hx` process**. NOT a fullscreen takeover of the TUI,
+NOT an external editor — a terminal-shaped emulator *inside* the tab, as
+pass-through as possible ("open the space for helix to fill like a good TUI
+app"). `:wq!` (helix quitting) closes the tab. The tab model becomes generic:
+`SessionTab: AcpClientChat | Terminal | Editor` (decoupled from session-id).
+The `!command` fire-and-get-text-back shell stays as-is for now — do NOT
+revolutionize the chat interface this sprint.
+
+### Reuse, don't hand-roll
+- `widgets/terminal_tool.py::TerminalTool(Terminal)` already does the full PTY
+  dance (openpty, subprocess, read loop, `write_stdin`, `resize_pty`,
+  `wait_for_exit`, `kill`). EditorTerminal subclasses it.
+- Tabs are Textual **modes**: `CrowApp.new_session_screen(get_screen, title)`
+  registers a mode + screen and tracks it in `SessionTracker`; the
+  `SessionsTabs` widget renders tabs from `session_tracker` (it reads
+  `app.session_tracker` + `app.current_mode`, so it works on ANY screen).
+- `SessionClose` message + `MainScreen.on_session_close` already implement
+  "switch to neighbour, close tracker entry, remove mode".
+
+### Build/test gate
+`uv --project . run pytest tests/unit -q` after each step (there is no TUI
+test dir yet — create `tests/unit/tui/`). Live smoke in tmux session
+`crowtui-test` (NEVER touch other sessions / the user's live rio windows;
+this agent is itself a crow-cli instance — do not kill crow processes).
+Commit when green, `Session-Id: terrific-heron-of-splendid-greatness` trailer.
+
+## Steps
+
+> STATUS (30Aug2026): steps 1–7 DONE. Steps 1–6 committed (a52e3d41,
+> 296a568c, 3d8597e5); step 7 (slice 2) committed this segment. Live smoke
+> green end-to-end: file click → helix renders inside the tab in the chat's
+> column with the sidebar visible, keys pass through, `:wq!` writes & closes
+> the tab; the tab `✕` affordance closes an editor tab gracefully (sends
+> `:wq!\r`, helix exits, no orphan process) and a chat tab directly. Full
+> gate green: 518 passed (unit + integration + e2e + memory).
+>
+> Root-cause fix landed in 3d8597e5: the child PTY was never made the
+> controlling terminal, so helix read /dev/tty size from the OUTER terminal
+> (187 cols) and never got SIGWINCH — that, not the ANSI state, caused the
+> blank/garbled editor. Fixed via preexec setsid()+TIOCSCTTY + pre-spawn
+> PTY sizing.
+>
+> Slice-2 notes: programmatic keys to helix must end in `\r` (TERMINAL_KEY_MAP
+> maps `enter`→`\r`, and helix ignores `\n`). `kill()` now kills the whole
+> process group (os.killpg) and `EditorTerminal.on_unmount` calls it, so a
+> closed tab never leaks `sh`/`hx`.
+
+1. ✅ **`tui/widgets/editor_terminal.py::EditorTerminal(TerminalTool)`**
+   - Pure pass-through `on_key`: forward EVERY key incl. `escape` immediately
+     (no double-tap-to-blur — helix needs ESC). `event.prevent_default();
+     event.stop()` then `state.key_event_to_stdin` → `write_process_stdin`.
+   - Override `update_size` to also `resize_pty(self._shell_fd, w, h)` so
+     helix redraws on tab/window resize (TerminalTool only sizes once).
+   - Post `Exited(return_code)` Message when the process exits.
+   - CSS: fill the tab (`width:100%; height:1fr;`), no border/`-success` noise.
+   - Verify: headless run_test with a trivial program (`cat`/`printf`) →
+     output lands in the buffer; ESC/key bytes reach stdin; Exited fires.
+
+2. ✅ **`tui/screens/editor.py::EditorScreen(Screen)` + `editor.tcss`**
+   - compose: `SessionsTabs()`, `EditorTerminal`, `Footer()`.
+   - on_mount: `terminal.start(w,h)` with the `hx <path>` command, focus it.
+   - Handle `EditorTerminal.Exited` → post `SessionClose(self.id)` (tab closes
+     when helix quits). Reuse the close semantics of MainScreen.on_session_close.
+   - Session-nav bindings (`ctrl+[` / `ctrl+]`) so you can leave the tab;
+     a `ctrl+q` binding → `quit_editor()` sends `:wq!\r` to stdin.
+   - Verify: headless test opens EditorScreen with a quick-exit command →
+     mounts, focuses terminal, closes on exit.
+
+3. ✅ **Generic tab model** — `session_tracker.SessionDetails` gains
+   `kind: Literal["chat","editor"]="chat"`; thread through
+   `SessionTracker.new_session(title, kind)` and
+   `CrowApp.new_session_screen(get_screen, title, kind)`. SessionsTabs may
+   render an editor glyph by kind (keep minimal).
+   - Verify: existing unit tests green; kind defaults to chat.
+
+4. ✅ **`CrowApp.open_file_in_editor(path)`** — build `Command(editor.command,
+   [str(path)], env, cwd=project)` and `new_session_screen(get_screen,
+   title=f"hx {path.name}", kind="editor")`. Editor command from settings key
+   `editor.command` (default `hx`) — add to `settings_schema.py` SCHEMA.
+   - Verify: headless — call it, assert a new editor mode/screen exists.
+
+5. ✅ **Rewire the explorer click** — `MainScreen.on_project_directory_tree_selected`
+   → `self.app.open_file_in_editor(data.path)` (instead of
+   `insert_path_into_prompt`). `@file` path-insert via path_search is unchanged.
+   - Verify: simulate `DirectoryTree.FileSelected` → open_file_in_editor called.
+
+6. ✅ **Live smoke (tmux `crowtui-test`)** — launch TUI, open a file from the
+   explorer, confirm helix renders inside the tab, keys pass through, `:wq!`
+   closes the tab and returns to chat. Capture frames to verify rendering.
+
+7. ✅ **(slice 2) tab `x` close affordance** — every tab label renders a
+   trailing `✕` (`session_tabs.CLOSE_GLYPH`); `SessionLabel.on_click`
+   hit-tests `offset.x >= content_region.width` and posts
+   `messages.SessionRequestClose(mode)`. `CrowApp.on_session_request_close`
+   is graceful for editor tabs (sends `:wq!\r` — `\r`, not `\n` — and lets
+   the resulting Exited→SessionClose cascade remove the tab) and direct for
+   chat tabs. `terminal_tool.kill()` kills the process group and
+   `EditorTerminal.on_unmount` calls it, so closing never orphans `sh`/`hx`.
+   - Verify: unit `test_x_affordance_gracefully_closes_editor_tab` (asserts
+     the editor received `:wq!` and the tab closes on exit) + live tmux
+     smoke (click `✕` → helix exits, no orphan). Both green.
+
+---
+
+# PLAN — mature the ANSI emulator + editor tab = chat page
+
+## **DO NOT ASK USER FOR FEEDBACK — THIS IS THE USER FEEDBACK.**
+## **DO NOT ASK USER FOR NEXT STEPS — THESE ARE THE NEXT STEPS.**
+
+### The unlock (user, this segment)
+Two user reports with screenshots:
+1. **Editor tab must be the SAME page as the chat page** — "they're really
+   the same page… align completely". Chat: tab bar INSIDE the right column
+   (right of sidebar, top of the Conversation widget). Editor: tab bar
+   full-width ABOVE the sidebar. Fix = move `SessionsTabs()` inside
+   `#editor-body` and mirror Conversation's column CSS exactly.
+2. **Holding `down` in helix garbles the display** — jumbled line numbers,
+   statusline fragments scattered at the right edge, scroll dead.
+
+### Research done (verified, don't redo)
+- **pyte oracle**: our `TerminalState` matches pyte with 0 mismatches at
+  fixed size (120×40, 100 downs) AND under the app's real resize sequence
+  (headless 150×50 and user's 187×50). Core emulation is CORRECT.
+- **The divergence is resize semantics**: our `TerminalState.update_size` →
+  `_reflow()` FOLDS stale wide lines on width shrink; pyte `Screen.resize`
+  TRUNCATES columns at the right and deletes rows from the TOP on height
+  shrink. Folded stale alt-screen lines break CUP row addressing
+  (fold-index ≠ row-index) → exactly the garble the user saw.
+- **Copied notes from mitosch/textual-terminal** (the project doing exactly
+  this — pyte inside a Textual widget): `on_resize` sets ncol/nrow from the
+  widget size, tells the PTY via set_size, and calls `screen.resize(nrow,
+  ncol)` — real-terminal semantics, NO folding, NO buffer wipes. Renders by
+  iterating `screen.buffer[y][x]` Char cells; mouse toggled by sniffing
+  DECSET 1000h/l (we already do the equivalent). Also noted:
+  par-term-emu-tui-rust (Textual widget over Rust core) as the mature/perf
+  option; neovim :terminal uses libvterm and still has resize-drift bugs.
+- Widget mitigation (`update_size` wipes alt buffer on alt+size change)
+  exists but is a lossy band-aid; the state itself must be grid-faithful.
+
+## Steps
+
+1. ✅ **pyte-semantics resize in `tui/ansi/_ansi.py::TerminalState.update_size`**
+   - Alternate screen: width shrink → TRUNCATE every line at the new width
+     (never fold — grid rows must stay 1:1 with buffer lines); height
+     shrink → delete rows from the TOP; height grow → pad blank rows at the
+     bottom; clamp the cursor; rebuild fold index; mark all lines updated.
+   - Scrollback (normal) screen: keep the existing fold/reflow behavior
+     (presentation wrapping is a chat feature).
+   - Fix the `width is None` bug (compared `previous_width != width` with
+     `width=None` → spurious reflow).
+   - `widgets/terminal.py::update_size`: pass `self._height` (not the raw
+     arg) to `state.update_size`; drop the lossy alt-buffer wipe — with
+     grid-faithful resize the truncated content is exactly what a real
+     terminal shows until the program's SIGWINCH repaint lands.
+   - Verify: `tests/unit/tui/test_ansi_resize.py` — pyte-oracle regression
+     (helix-shaped paint → shrink → repaint, 0 mismatches), CUP addressing
+     after shrink lands on the right row, scrollback still folds.
+
+2. ✅ **Editor tab = chat page** — `screens/editor.py` compose: move
+   `SessionsTabs()` inside `#editor-body` (above EditorTerminal);
+   `editor.tcss`: `#editor-body` gets Conversation's chrome (`padding-left:
+   1`, `&.-column { max-width: 100; background: black 7%; }`) and
+   `_apply_column_width` toggles `-column` exactly like MainScreen's
+   `watch_column`. Verify: unit test asserts SessionsTabs is a descendant of
+   #editor-body; live smoke compares both tabs' tab bars.
+
+3. ✅ **Gate + live smoke** — `pytest tests/unit -q`, full gate, tmux
+   `crowtui-test`: open file in helix, hold down (100 downs via SGR keys or
+   repeated sends), resize the window, verify no garble; compare chat vs
+   editor tab bar placement via capture-pane.
+
+4. ✅ **Commit** (Session-Id trailer) + PLAN/TODO status updates.
+
+## Deferred (still open, not this sprint)
+- TUI image attachments as ACP image content (previous PLAN, steps preserved
+  in TODO.md item).
+- TUI ACP-client migration onto the official `acp` SDK (TODO.md item).
+- `!command` shell UX improvements (reveal/scroll lag) — fire-and-forget is
+  acceptable for now per user.

crow_cli-0.1.41/PYINSTALLER_BUILD.md

@@ -0,0 +1,112 @@
+# PyInstaller Binary Build Setup
+
+## ✅ What's Been Created
+
+### 1. GitHub Workflow: `.github/workflows/build-binaries.yml`
+
+Builds crow-cli binaries for:
+- **Linux x86_64** (ubuntu-22.04)
+- **macOS x86_64** (macos-13)
+- **macOS ARM64** (macos-latest - Apple Silicon)
+
+**Trigger:** Push version tags (e.g., `v0.1.13`)
+
+**Output:** Creates GitHub release with attached archives:
+- `crow-cli-linux-x86_64.tar.gz`
+- `crow-cli-darwin-x86_64.tar.gz`
+- `crow-cli-darwin-aarch64.tar.gz`
+
+### 2. PyInstaller Spec File: `crow-cli.spec`
+
+Configured with:
+- **Metadata copying** for all packages using `importlib.metadata` (fastmcp, agent-client-protocol, typer, rich, openai, etc.)
+- **Hidden imports** for dynamic imports (coolname.data, etc.)
+- **Data files** included (config.yaml, system_prompt.jinja2, settings.yml, etc.)
+- **One-file executable** with UPX compression
+
+### 3. Dependencies: `pyproject.toml`
+
+Added `pyinstaller>=6.0.0` to dev dependency group
+
+## 🧪 Local Testing
+
+```bash
+cd crow-cli
+uv --project . pip install pyinstaller
+uv --project . run pyinstaller crow-cli.spec --noconfirm
+dist/crow-cli --help
+```
+
+## 🚀 Usage
+
+### To trigger a build:
+
+1. Commit and push the workflow:
+```bash
+git add .github/workflows/build-binaries.yml
+git add crow-cli.spec
+git add pyproject.toml
+git commit -m "Add PyInstaller binary build workflow"
+git push
+```
+
+2. Create a test tag:
+```bash
+git tag v0.1.13-test
+git push origin v0.1.13-test
+```
+
+3. GitHub Actions will build all platforms and create a release
+
+### To update the ACP Registry:
+
+After binaries are built, update `agent.json`:
+
+```json
+{
+  "distribution": {
+    "uvx": {...},
+    "binary": {
+      "darwin-aarch64": {
+        "archive": "https://github.com/crow-cli/crow-cli/releases/download/v0.1.13/crow-cli-darwin-aarch64.tar.gz",
+        "cmd": "./crow-cli",
+        "args": ["acp"]
+      },
+      "darwin-x86_64": {...},
+      "linux-x86_64": {...}
+    }
+  }
+}
+```
+
+Then submit PR to [agentclientprotocol/registry](https://github.com/agentclientprotocol/registry)
+
+## ⚠️ Known Issues & Solutions
+
+### Package Metadata Errors
+If you see `importlib.metadata.PackageNotFoundError`, add the package to the `copy_metadata()` calls in the spec file:
+
+```python
+datas=[
+    ...
+] + copy_metadata('packagename')
+```
+
+### Missing Module Errors
+If you see `ModuleNotFoundError` for submodules, add to `hiddenimports`:
+
+```python
+hiddenimports=[
+    'packagename.submodule',
+    ...
+]
+```
+
+### Build Size
+Current Linux build: ~80MB (compressed with UPX)
+
+## 📝 Notes
+
+- The spec file handles all metadata copying, so no command-line flags needed
+- macOS builds use different runners for Intel (macos-13) vs Apple Silicon (macos-latest)
+- Artifacts are retained for 30 days, but releases are permanent

crow_cli-0.1.41/TERMINAL_STACK.md

@@ -0,0 +1,120 @@
+# Terminal Stack — crow spaceship edition
+
+The dev terminal stack on this box, documented 2026-08-29. Everything is
+installed without sudo (user-local), and rio is built from source — which
+is the whole point, see below.
+
+## Rio terminal (built from source — `~/src/rio`, v0.5.26)
+
+Installed at `~/.cargo/bin/rio`. Config: `~/.config/rio/config.toml`
+(shades-of-dracula crow flavor — chrome accents are Dracula purple
+`#BD93F9`, matching `src/crow_cli/tui/themes.py`; ANSI yellow stays
+yellow for program output). Font: DejaVu Sans Mono 12px, deliberately
+NOT a Nerd Font (won the bake-off against Lilex; tested against Zed).
+All prompt/tool symbols in this stack are DejaVu-safe.
+
+### What building from source buys
+
+The default Linux build uses the native Vulkan backend. Two cargo
+features are off by default and only reachable with a source build
+(`frontends/rioterm/Cargo.toml`):
+
+1. **`wgpu` — RetroArch shader filters.** The librashader filter chain
+   (https://rioterm.com/docs/features/retroarch-shaders) only runs on
+   the wgpu backend. Post-processing for the whole terminal: built-in
+   `newpixiecrt`, or any `.slangp` from libretro/slang-shaders (CRT,
+   bloom, scanlines — the spaceship-cockpit look).
+2. **`audio` — real audio bell** via cpal (`handle_audio_bell` in
+   `frontends/rioterm/src/application.rs`).
+
+Also available in config regardless of build: `[renderer] strategy =
+"Game"` (continuous game-loop rendering) vs the default event-based.
+
+### Rebuild with shaders enabled
+
+```bash
+cd ~/src/rio
+cargo install --path frontends/rioterm --features wgpu,audio --force
+```
+
+Then in `~/.config/rio/config.toml`:
+
+```toml
+[renderer]
+backend = "Webgpu"
+filters = ["newpixiecrt"]            # or a path to any .slangp
+```
+
+Note: wgpu-on-Linux translates through to Vulkan (slightly heavier than
+the native backend); filters cost some GPU. If `filters` is set but the
+backend is native Vulkan, rio accepts the config and silently skips the
+chain — you must set `backend = "Webgpu"`.
+
+Being upstream-from-source also means we can patch rio itself when the
+zellji integration (below) needs something rio doesn't do yet.
+
+## Shell stack (bash 5.2 — no shell switch, bash gets the upgrades)
+
+All user-local; `~/.bashrc` is the spaceship (original at `~/.bashrc.bak`).
+
+| Tool | What it does | Lives at |
+|---|---|---|
+| **starship** | prompt — git/lang/duration, Dracula palette | `~/.local/bin/starship`, config `~/.config/starship.toml` |
+| **ble.sh** | readline replacement: syntax highlighting, autosuggestions, menu completion | `~/.local/share/ble-nightly/`, config `~/.blerc` |
+| **eza** | ls with git status + tree | `~/.local/bin/eza` |
+| **bat** | cat with syntax highlighting | `~/.local/bin/bat` |
+| **zoxide** | `z foo` frecency directory jumps (`zi` interactive) | `~/.local/bin/zoxide` |
+| **fzf** | Ctrl-R fuzzy history, Ctrl-T files, Alt-C dirs (fd-backed) | `~/.local/bin/fzf` + `~/.local/share/fzf/*.bash` |
+| **delta** | git diff pager (wire via `git config --global core.pager delta` when wanted) | `~/.local/bin/delta` |
+| **fd / rg** | already present via cargo | `~/.cargo/bin` |
+| **hx** | helix editor, `$EDITOR` | system |
+
+Update paths: starship re-runs its installer; ble.sh = re-download the
+nightly tarball (`ble.sh/releases/download/nightly/ble-nightly.tar.xz`
+→ extract to `~/.local/share`, no gawk/make needed for the prebuilt
+tarball); the rest are GitHub-release binaries (x86_64).
+
+### `CROW_TERMINAL` — machine-driven PTY convention
+
+The MCP terminal tool (`mcp/terminal/backend.py`) spawns interactive
+bash in a PTY and owns the prompt via a JSON-in-PS1 protocol
+(`###PS1JSON###` markers, exit code in `$__crow_ec`). It sets
+`CROW_TERMINAL=1` in the child env. Prompt frameworks must respect it:
+
+- **starship / ble.sh**: stay OFF under `CROW_TERMINAL` (they re-render
+  PS1 / take over line editing and clobber the protocol).
+- **PROMPT_COMMAND hooks** (zoxide, fnm, ...): fine — the backend
+  captures `$?` into `$__crow_ec` before any hook runs.
+
+Any future shell decoration in `~/.bashrc` must keep the gate.
+
+### bashrc load order (matters)
+
+1. interactive guard → 2. ble.sh `--attach=none` (first) → 3. history →
+4. env (hx, LESS_TERMCAP, GCC_COLORS) → 5. toolchain PATH blocks
+(cargo/fnm/bun/juliaup) → 6. aliases (eza/bat/git) → 7. fzf bindings →
+8. bash-completion → 9. `starship init` + `zoxide init` → 10.
+`ble-attach` (LAST — ble.sh takes over line editing).
+
+## The zellji vision (why this is documented in crow-cli)
+
+Goal: crow-cli grows into the glue of a full terminal IDE, replacing
+the pile of bash scripts in https://github.com/josephschmitt/zide
+(zellij layouts + `zide-pick` yazi wrapper + `zide-edit` editor
+launcher) with Python.
+
+- **zellij** = window/pane manager (the "IDE frame")
+- **yazi** = filesystem pane
+- **helix** (`hx`) = editor pane
+- **crow-cli TUI** = the agent pane AND the orchestrator: spawns the
+  layout, routes "open file" events from yazi into helix, drives the
+  agent — i.e. `crow-cli ide` instead of `zide` + `zide-pick` +
+  `zide-edit`.
+
+Stepping stones: crow-cli already speaks ACP to its own agent and has
+a TUI that drives it; the zide behaviors to absorb are (1) layout
+launch with working-dir propagation, (2) filepicker → editor IPC
+(zide uses zellij's pipe/message), (3) pane auto-resize for the picker.
+Rio-from-source is the display layer: if the IDE glue needs something
+from the terminal (keycodes, shader states, notifications), we patch
+rio rather than work around it.