acstack 0.0.0-stage → 0.47.1

package/docs/dev-setups.md

@@ -0,0 +1,164 @@
+# Dev setups
+
+*One file per machine records what that machine has installed. A skill never has to guess.*
+
+You run ACStack on more than one machine. Those machines are not the same.
+
+- **One has herdr installed, another has Orca, a third has neither**
+- **One can drive a real Chrome window**
+- **Another has no display at all**
+- **A skill cannot guess which**
+    - Each machine answers nine questions once, with `/acstack:host` and `/acstack:setup`
+- **The answers live in `~/.config/acstack/config.json`** as `host.*` keys
+- **The worktree skills and the frontend verifier read them** instead of probing
+
+Four terms first.
+
+- **A dev setup** is the machine-level tools a session runs inside
+- **An axis** is one setting of it, recorded as one `host.*` key
+- **An orchestrator** owns terminal panes and git worktrees: herdr or Orca
+- **A checkout** is one git worktree directory
+
+```mermaid
+flowchart TD
+    HOST["Describe this machine once<br/>(/acstack:host - section 4)"] --> AXES["Every axis, and what reads it<br/>(host.* in ~/.config/acstack/config.json - section 1)"]
+    AXES --> ORCH["Orchestrator axes<br/>(host.orchestrators.* - section 2)"]
+    AXES --> BROW["Browser axes<br/>(host.browser.* - section 3)"]
+    AXES --> OPT["Optional axes<br/>(preview, terminal workspace, element picker, Orca topology)"]
+    ORCH -->|"pick the worktree tool"| WT["new-worktree, teardown-worktree"]
+    BROW -->|"pick the browser"| FV["frontend-verifier"]
+    PROJ["What this project prefers<br/>(frontend.browser.* in acstack/project.yaml)"] --> FV
+    OPT -.->|"nothing reads them yet"| CHK["acstack config check lists them"]
+```
+
+## 1. Every axis, and what reads it
+
+*Nine `host.*` axes describe the machine. Three `frontend.browser.*` keys state what one project would like.*
+
+| Axis | Values | Required | Stored in | What changes behaviour on it |
+| --- | --- | --- | --- | --- |
+| `host.orchestrators.herdr` | `true`, `false` | yes | global config | `detect-orchestrator.sh`, so both worktree skills; check 2 runs `herdr api snapshot` |
+| `host.orchestrators.orca` | `true`, `false` | yes | global config | the same detector; check 2 runs `orca-ide status --json` |
+| `host.browser.remote` | `true`, `false` | yes, with a frontend | global config | `acstack config browser-mode`, so `frontend-verifier`; checks 3 and 4 |
+| `host.browser.headless` | `true`, `false` | yes, with a frontend | global config | the same |
+| `host.browser.local` | `true`, `false` | yes, with a frontend | global config | the same |
+| `host.preview.tailscale_serve` | `true`, `false` | no | global config | nothing; check 5 lists it |
+| `host.terminal_workspace` | `true`, `false` | no | global config | `/acstack:setup` offers the workspace once, and never asks again after this is set |
+| `host.element_picker` | `stagewise`, `orca-design-mode`, `none` | no | global config | nothing; check 5 lists it |
+| `host.orca.topology` | `local`, `remote` | no | global config | nothing; check 5 marks it inert unless `host.orchestrators.orca` is `true` |
+| `frontend.browser.mode` | `remote`, `headless`, `local` | no | `acstack/project.yaml` | the preference, weighed against the three host axes |
+| `frontend.browser.cdp_port` | a port number | no | `acstack/project.yaml` | `frontend-verifier`; defaults to `19988` for `remote` and `9555` otherwise |
+| `frontend.browser.fallback` | `none`, or any word | no | `acstack/project.yaml` | only `none` acts: it forbids a stand-in mode |
+
+Where the file lives, and how the CLI reads a value:
+
+- The global config is a JSON file at `~/.config/acstack/config.json`
+    - It moves under `$XDG_CONFIG_HOME` when you set that variable
+    - Run `~/.claude/acstack/bin/acstack config path` for the real location
+- `acstack config show` prints every axis with the project's settings
+- The CLI matches an enum value case-sensitively
+    - `stagewise` works, and `Stagewise` does not
+- The CLI matches a boolean loosely: `true`, `yes`, and `on` all mean true, and `false`, `no`, and `off` all mean false
+
+## 2. Orchestrator axes
+
+*Each orchestrator is its own yes-or-no. Declared means installed. The environment says which one hosts this session.*
+
+- A machine can have both installed, one, or neither
+    - An answer about herdr says nothing about Orca
+- Answering no to both is a real answer
+    - The worktree skills then use plain git under `.claude/worktrees`
+- `skills/new-worktree/detect-orchestrator.sh` prints six lines: `declared_herdr`, `declared_orca`, `detected`, `active`, `owner`, and `warning`
+    - `detected` reads the markers an orchestrator sets in its terminals
+    - `active` always equals it
+    - herdr sets `HERDR_ENV` and `HERDR_PANE_ID`
+    - orca sets `ORCA_PANE_KEY`
+- `owner` comes from the checkout's path root, not from the session
+    - orca owns `~/orca/workspaces/<repo>/`
+    - herdr owns everything under its worktree root, `~/.herdr/worktrees` by default
+    - Any other path is plain git
+    - The session's host creates a checkout
+    - The checkout's owner removes it
+
+**herdr.**
+
+- `new-worktree` creates the checkout, then moves this pane into the new workspace with `herdr pane move`
+- The session then sits in the sidebar row for the worktree it works in
+- One limit matters: a herdr server serves one client at a time
+
+**Orca.**
+
+- The Linux executable is `orca-ide`
+    - Some installs put it on `PATH` as plain `orca`
+- orca runs as a desktop application, or as a headless `orca serve` that the user views through a paired client
+- `host.orca.topology` records which one
+- Five limits matter
+    - No command moves a running terminal into a worktree
+        - The session changes directory instead
+    - `worktree rm` always deletes the branch, and removes a checkout with live agents in it
+        - `teardown-worktree` therefore reads `agents[]` and `liveTerminalCount` from `worktree ps --json` first
+    - Nobody has tested Claude Code Agent Teams under `orca serve`
+        - Upstream issue 11739 reports that the tmux-compatibility layer can break them
+    - Nobody has tested Design Mode either
+        - It needs the browser pane on the developer's own machine
+    - The Orca web client cannot create terminals behind a reverse proxy
+        - Pair a desktop or phone client instead
+        - Upstream issue 9047 tracks it
+
+Neither tool sees the other's sessions.
+
+- orca and a paired phone list herdr checkouts only after you turn on one switch per repository
+- orca's desktop application holds that switch, named "show in worktree list"
+- No command sets it
+
+## 3. Browser axes
+
+*The three modes are not alternatives. A machine can offer any combination. Each one needs something different.*
+
+- **remote** drives a real browser on the developer's own machine, over the Playwriter bridge
+    - Something must answer HTTP on the bridge's port, `19988`
+    - The bridge listens there whatever the project says, so check 3 knocks on `19988` even for a project with no frontend
+    - Only a project that sets `frontend.browser.mode: remote` moves that port, with `frontend.browser.cdp_port`
+- **headless** launches headless Chromium here and needs no display
+    - It needs `chromium`, `chromium-browser`, `google-chrome`, or `google-chrome-stable` on `PATH`
+- **local** launches a visible browser here
+    - It needs one of those binaries and a graphical display
+
+How the two sides meet:
+
+- The host declares what works
+- The project states a preference in `frontend.browser.mode`
+- The first mode the host does declare stands in, when the host does not declare that mode
+- The order is remote, headless, local
+- Setting `frontend.browser.fallback` to `none` refuses any stand-in and fails instead
+- `~/.claude/acstack/bin/acstack config browser-mode` applies those rules and prints the answer with its reason
+- The frontend verifier runs that command instead of choosing for itself
+
+## 4. Describe this machine once
+
+*Eight steps. Each install plans before it touches anything.*
+
+1. Run `/acstack:host`. It detects what is here, then asks about every axis.
+2. Detection never decides a required axis. It only pre-fills the recommended answer.
+3. On Linux the skill offers two installs. Each one plans first and waits for approval.
+4. `install-orca.sh --plan` lists the steps, and `--apply` runs them. It installs the AppImage, the `orca-ide` and `orca` symlinks, and a systemd user unit.
+5. The apply prints the pairing URL only when it started or restarted the server. The journal must already hold the readiness line. Otherwise it prints the `journalctl` command to run by hand.
+6. `install-herdr-block.sh --plan` lists the steps, and `--apply` writes the block. The block goes into `~/.config/herdr/config.toml`. It names the directory herdr creates worktrees under.
+7. Run `~/.claude/acstack/bin/acstack config check`. It prints five numbered checks.
+8. Read its exit code. It exits 2 on an unset required axis, 1 on any other failure, and 0 when everything passes.
+
+This skill asks eight of the nine axes. `/acstack:setup` asks the ninth, at
+the end of its own run, and writes `host.terminal_workspace` from the answer.
+
+- The offer comes last on purpose: the workspace installs binaries, and nothing in ACStack needs it
+- Either answer ends the offer for good
+- After a `true` answer, `/acstack:setup` re-checks this machine on every later run and offers `upgrade` when a tool or a component has moved on
+- The key records the answer, never the install: `true` means the user said yes, not that the workspace is on the machine
+- `/acstack:terminal-workspace` is the only thing that installs it, and only you can start it
+
+Four things stay yours.
+
+- Log in to Tailscale
+- Connect the Playwriter bridge
+- Pair a client to Orca
+- Turn on "show in worktree list" for each repository in Orca's desktop application

package/docs/migrate-0.8.md

@@ -0,0 +1,28 @@
+# Migrating to ACStack 0.8.0
+
+*Delete one `@import` line from your project `CLAUDE.md`, and nothing else.*
+
+A project initialized before version 0.8.0 holds a line like this in its `CLAUDE.md`:
+
+```
+@import /home/<user>/.claude/plugins/cache/ac8318740-plugins/acstack/<version>/CLAUDE.md
+```
+
+As of 0.8.0 a SessionStart hook loads the orchestrator instructions, and it always resolves to the currently installed plugin version.
+
+## 1. Why remove it
+
+*Three reasons, and any one of them is enough.*
+
+- **Silent staleness** – the path pins your project to a single plugin version
+    - An upgrade leaves the `@import` pointing at old orchestrator rules
+- **Time-bomb breakage** – Claude Code cleans an orphaned plugin version out of its cache after 7 days, and the pinned path then 404s
+- **Duplication** – leaving the line in place under 0.8.0 or later loads the same content twice
+
+## 2. What to do
+
+1. Open your project's `CLAUDE.md`.
+2. Remove any line matching `@import .../plugins/cache/ac8318740-plugins/acstack/<version>/CLAUDE.md`.
+3. Save the file.
+
+The hook loads ACStack's orchestrator instructions next time you start a session in that project. Nothing else changes.

package/docs/playwriter-bridge-windows.md

@@ -0,0 +1,15 @@
+# Playwriter bridge, Windows laptop setup
+
+*This document has moved. The `bridge` skill covers the bridge now.*
+
+Where each part went:
+
+- **Entry point**, platform detection, and the handoff convention: [`../skills/bridge/SKILL.md`](../skills/bridge/SKILL.md)
+- **Windows runbook**, what used to live in this file: [`../skills/bridge/SKILL-WINDOWS.md`](../skills/bridge/SKILL-WINDOWS.md)
+- **Linux and dev-VM runbook**: [`../skills/bridge/SKILL-VM.md`](../skills/bridge/SKILL-VM.md)
+- **Cross-device handoff format**: [`../skills/bridge/HANDOFF.md`](../skills/bridge/HANDOFF.md)
+
+The scripts still ship under `plugins/acstack/assets/playwriter-bridge/`.
+
+- `stop.ps1`, `doctor.ps1`, and `vm-free-port.sh` are new since this relocation
+- The Windows runbook covers their use

package/docs/terminal-workspace-keys.md

@@ -0,0 +1,137 @@
+# Terminal workspace keys
+
+The keys worth memorising, and nothing else. Run `/acstack:terminal-workspace` to install what they drive.
+
+Two layers:
+
+- **`alt`** reaches herdr from anywhere, including from inside a running tool
+- **`prefix`** is `ctrl+b`, then the key, for what you press rarely
+
+## Move around
+
+| Key | Does |
+|---|---|
+| `alt+h` `alt+j` `alt+k` `alt+l` | move between panes |
+| `alt+1` to `alt+9` | jump to an agent |
+| `alt+n` / `alt+u` | next / previous agent |
+| `alt+left` / `alt+right` | previous / next tab |
+| `alt+up` / `alt+down` | previous / next workspace |
+| `alt+a` | last pane |
+| `alt+z` | zoom this pane |
+| `alt+s` | toggle the sidebar |
+
+## Make things
+
+| Key | Does |
+|---|---|
+| `alt+e` | split vertical |
+| `alt+minus` | split horizontal |
+| `alt+c` | new tab |
+| `alt+w` | new workspace |
+| `alt+r` | new worktree |
+| `prefix+t` | go to a pane by name |
+
+## Open a tool
+
+Add `shift` to any of these to open it in a full tab instead of a popup.
+
+| Key | Opens | For |
+|---|---|---|
+| `alt+f` | diffnav | what changed on this branch |
+| `alt+x` | diffnav picker | choose what to compare |
+| `alt+g` | lazygit | stage, commit, push |
+| `alt+i` | gh-dash | your PRs on GitHub |
+| `alt+y` | yazi | find a file |
+| `alt+q` | harlequin | run a SQL query |
+
+## Inside each tool
+
+`e` means edit in every tool that has an editor key, except diffnav, which spends `e` on its file tree.
+
+### diffnav (`alt+f`)
+
+| Key | Does |
+|---|---|
+| `j` / `k` | next / previous file |
+| `o` | open the file in `$EDITOR` |
+| `s` | toggle side-by-side |
+| `e` | toggle the file tree |
+| `?` | every key |
+
+### lazygit (`alt+g`)
+
+| Key | Does |
+|---|---|
+| `space` | stage the file under the cursor |
+| `a` | stage everything |
+| `c` | commit |
+| `A` | amend the last commit |
+| `P` | push |
+| `?` | every key |
+
+### yazi (`alt+y`)
+
+| Key | Does |
+|---|---|
+| `e` | edit in `$EDITOR` |
+| `o` | open by rule, which for markdown is the reader |
+| `b` | open in the browser you are sitting at |
+| `D` | send the file to your laptop over Taildrop |
+
+### harlequin (`alt+q`)
+
+| Key | Does |
+|---|---|
+| `f2` / `f5` / `f6` | editor / results / catalog |
+| `tab` / `shift+tab` | next / previous pane, from outside the editor |
+| `ctrl+enter` | run the query, or in the catalog insert the name into the editor |
+| `f4` | format the query |
+| `f8` | query history |
+| `f9` | hide the catalog sidebar |
+| `f10` | full-screen the focused pane |
+| `f1` | every key |
+
+### tuicr
+
+`;` is tuicr's leader: press it, release it, then press the second key.
+
+| Key | Does |
+|---|---|
+| `e` | edit the focused file in `$EDITOR` |
+| `c` | comment on the line |
+| `y` | copy the review to the clipboard |
+| `;o` | open the PR on GitHub |
+| `;L` / `;H` | widen / narrow the file tree, then bare `L` / `H` to keep going |
+| `x` | filter files out of the tree |
+| `?` | every key |
+
+`;L` and `;H` need the fork build, which `tuicr.build_from_fork` in the config installs.
+
+### LazyVim
+
+| Key | Does |
+|---|---|
+| `space` | show every key, with labels |
+| `space` `space` | find a file |
+| `space` `/` | grep the project |
+| `space` `e` | file tree |
+| `space` `g` `g` | lazygit |
+| `H` / `L` | previous / next file |
+| `:Tutor` | learn vim in 25 minutes |
+
+## When a key does nothing
+
+- Your terminal emulator ate it, and `alt+shift+d` is the known case in Windows Terminal
+- Run `cat -v` in any pane and press the key
+    - An escape sequence such as `^[Z` means the key arrived, so the problem is the remote config
+    - Nothing printed means the key never left your machine
+- Fix it with `assets/terminal-workspace/client-keybindings.md`, which you hand to an agent running on your own machine
+
+## When a full-screen app draws its rows one column further left each time
+
+- herdr's pane scrollbar costs the pane a column, and setup turns the scrollbar off for that reason
+- The symptom is a wrapped row starting one column left of the row above it
+    - neovim shows it, and so does any other program that draws the whole pane
+- Toggling the sidebar with `alt+s` repairs the display until the next launch, because it recomputes the geometry
+- Check the setting survived with `grep pane_scrollbars ~/.config/herdr/config.toml`
+- Re-apply it with `bash assets/terminal-workspace/setup.sh apply`