Merge asks first; Work>work lists runs with a log tab; Shell says where everything is

.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md

@@ -709,3 +709,86 @@ Committed as `e44b0df`, documentation only — the running layout is untouched.
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclip-2026-11-10-21-58-38|Rich discovery: .paperclip 2026-11-10 21:58:38]]
 - context: [[packs/paperclip-harness/20-context/paperclipai|.paperclip]]
 - observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|.paperclip repository structure and configuration patterns]]
+
+
+---
+
+## Update (2026-11-11 01:02:31)
+
+Trigger: need to review or merge a completed task in paperclip-harness.
+
+Procedure:
+1. In `Work>work` press `o` and choose the task from the list (IDs like `AUD-168`). All tabs switch to it.
+2. Check the `review` and `change` tabs.
+3. Press `m` to merge; watch the `merge` tab for live progress. Log file: `/tmp/paperclip-harness-merge.log`.
+4. Success line looks like `merged into main at <sha>` then `merge finished <time>`.
+
+Expected log details: worktree `<project>/.paperclip/worktrees/<TASK-id>-<slug>`, branch `<TASK-id>-<slug>` rebased onto `main`; warnings `no verify command` and `review saw nothing to review (0 files); recorded, not hidden` are informational.
+
+Troubleshooting:
+- `refused: ocr is not installed` then `merge stopped: exit status 2` → PATH too small. `bin/lib/harness.py` should add `~/.local/bin`, `~/.nix-profile/bin`, system profile, per-user profile; verify `ocr` resolves in the environment the pane runs in.
+- Second merge attempt while one is running is refused by the merge lock — expected, not an error.
+- If `Shell>shell` behaves oddly, `bin/board` should detect cwd ≠ project folder and recreate that pane.
+
+Rollback: merges land on `main`; revert with git as usual from the recorded sha.
+
+## Detailed procedure from completed turn
+
+Both complaints are fair, and both are now fixed in the program rather than in the instructions.
+
+## Work>work selects its own task and merges
+
+- **`o`** in `Work>work` opens a list of the project's tasks. Choose one and the runs, change, facts, review and merge tabs all switch to it. You no longer start in `Board>board`.
+- **`m`** runs the merge for the task you are looking at, and the new **merge** tab shows it live:
+
+```
+merge of AUD-168 started 12:01:39
+  worktree …/worktrees/AUD-168-tidy-the-readme-introduction
+  rebased onto main
+  no verify command: this would pass on the agent's word
+  review saw nothing to review (0 files); recorded, not hidden
+  merged into main at 4a44473
+merge finished 12:01:43
+```
+
+That is a real merge I ran from the pane a minute ago, with no shell. Starting it twice is safe — the merge takes a lock and the second is refused.
+
+## Why the Shell step failed you
+
+Two real bugs, not your memory:
+
+1. The pane that merges inherited the pane's small `PATH`, so `bin/merge` could not find `ocr` and refused with `ocr is not installed`. Fixed at the source: `bin/lib/harness.py` now adds `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile before looking for anything.
+2. `Shell>shell` was created in one folder and later adopted without checking. `bin/board` now compares the pane's real working directory with the project folder and **replaces** the shell pane when they differ, saying so.
+
+## The principle you are pointing at
+
+The terminal was creeping in as the normal path. It should not be. From now on:
+
+- anything you do regularly is a key in a pane;
+- `Shell>shell` exists for the things we deliberately do not wrap, and for emergencies;
+- a test plan that needs me to write `git log` is a bad test plan.
+
+`docs/TEST-PLAN.md` is rewritten accordingly: step 4 is now "press `m` and wait", and the whole plan contains no terminal commands at all. `Shell>shell` appears once, as the escape hatch it is.
+
+## What I would do next, in your order
+
+1. You run the plan as written (nine steps, keys only) and tell me where the screen and Paperclip disagree.
+2. `Repair>cleanup` — sessions listed with age and pane count, kill only what you select, and never touching the Pi session files.
+3. The Pi session browser — `pi --resume` in a tool pane, or the folder in Yazi.
+
+Committed as `7198c34`; the eight workspaces are rebuilt and running.
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Repeatable procedure plus failure modes with concrete strings a future agent can match.; enriched with final-answer detail because persistence should be reusable
+
+## Related learned memories <!-- same-turn-2026-11-11 01:02:31 -->
+
+- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Pane-first UX: repeated actions become keys, Shell only as escape hatch]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Implemented task picker, in-pane merge, PATH and shell-folder fixes (commit 7198c34)]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Merging a paperclip-harness task from the TUI and diagnosing merge failures]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-bin-2026-11-11-01-02-31|Rich discovery: bin 2026-11-11 01:02:31]]
+- context: [[packs/paperclip-harness/20-context/tmp|bin]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|bin repository structure and configuration patterns]]