docs: prune STATE into a decision archive; record the branch rule

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 16 insertions, 4 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 0008428..5e206ee 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -69,8 +69,9 @@ User-visible server messages are English; the TUI is Swedish.
 
 ## TUI work
 
-Read `docs/STATE.md` first for status, locked decisions, pending decisions
-and the prioritized backlog. Then read `docs/TUI-GUIDELINES.md` and follow it. Summary: one shared line editor,
+Read `docs/STATE.md` first for status, open decisions and the prioritized
+backlog (settled decisions are archived in `docs/DECISIONS.md`; consult it
+only when you need the history behind a rule). Then read `docs/TUI-GUIDELINES.md` and follow it. Summary: one shared line editor,
 universal keys (Ctrl+N new, F5 refresh, Esc/q back, digits jump, `g` goto),
 forms behave the same everywhere, hints always visible, errors shown as
 `CODE: message`. Screens call only the widget layer (`clients/tui.[ch]`:
@@ -95,8 +96,10 @@ helpers and `struct app` are in `clients/ui.[ch]`; the scene registry
   `test_core` in `build-asan`/`build-ubsan`. Run them after touching
   allocation or arithmetic paths.
 - Before you stop: `make gate` — a clean rebuild with `WERROR=1`, the full
-  suite and `test-asan`. `sh scripts/install-hooks.sh` points
-  `core.hooksPath` at `.githooks/` so the pre-push hook runs it automatically.
+  suite and `test-asan`, in its own `build-gate/` (it never touches
+  `build/`). Run `sh scripts/install-hooks.sh` once per checkout: it points
+  `core.hooksPath` at `.githooks/` so the pre-push hook runs `make gate`
+  automatically.
 - Never run `bokftui` for tests without `scripts/tui-sandbox.sh`: it
   isolates `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` so a run cannot overwrite the
   human's `~/.config/bokf/tui.conf`, `~/.cache/bokf/tui.log` or bw session.
@@ -104,3 +107,12 @@ helpers and `struct app` are in `clients/ui.[ch]`; the scene registry
   `~/bokf-demo` or the live NAS volume.
 - Never commit unless the human asks. When asked, keep the message short and
   in the repo's style.
+
+## Parallel work
+
+Anything that touches more than one domain file goes on an `eff/*` (or
+`feat/*`) branch in a git worktree under `/tmp/opencode/wt-*`
+(`git worktree add /tmp/opencode/wt-<name> -b eff/<name> main`), never in
+the main checkout. Verify the branch with `make gate`; the lead merges it
+after review. Protocol and docs updates (`PROTOCOL.md`, `SCHEMA.md`,
+`STATE.md`) stay in the same branch as the code they describe.