diff --git a/docs/feature-changes.md b/docs/feature-changes.md
new file mode 100644
index 00000000..a6473a6d
--- /dev/null
+++ b/docs/feature-changes.md
@@ -0,0 +1,79 @@
+# Full-stack feature changes
+
+How a Pipelines feature that crosses layers is built, checked and handed over.
+The **Feature** workflow (`docs/workflows/feature.md`) follows this guide; it
+records what worked for the chat, terminal, file and discovery features built on
+2026-11-08/09 (turn diffs, shell commands and the interactive terminal, the
+permanent terminal, Pipelines chat tools, thinking levels, file upload, rename,
+move and delete, dismissible commands, connection recovery).
+
+## Layers and where a feature touches them
+
+| Layer | Where | Typical change |
+|---|---|---|
+| Protocol | `internal/protocol/` | New request/frame types in their own file; the `Message` field in `message.go` is additive and `omitempty` so older peers keep working |
+| Persistence | `internal/pipeline/` | A new table in its own file with `init…` called from `store.go`; bounded rows; survives restarts |
+| Server | `internal/server/` | Handlers in new files named for the area (`chat_*`, `terminal_*`, `home_files_*`), routed from `chat.go`/`websocket.go`; pushed frames to every client watching |
+| Harness adapters | `internal/claude`, `internal/codex`, `internal/opencode` | Per-harness mechanism checked against the installed CLI or app-server schema; unsupported means no feature, never a fake |
+| Web proxy | `web/serve.mjs`, `web/src/peerRelay.js` | Only for new HTTP paths: authenticated route plus the peer-relay allowlist |
+| App | `app/lib/features//` | Small files; Material and Cupertino; reached through the chat's own gateway so multi-machine chats work |
+| Fixture | `app/tool/perf/*_fixture.dart`, `app/tool/search_selection_probe_entry.dart` | A `?param=1` option that renders the new states for captures |
+
+Shared files every feature touches (`message.go`, `chat_hub.go`, `store.go`,
+`chat_thread_view.dart`, `perf_fixture.dart`): keep edits there to a few lines
+and put the logic in new files. Parallel features then merge with small,
+additive conflicts.
+
+## Rules that held up
+
+- **Security boundary.** Everything goes through the authenticated `/connect`
+ websocket. Home-folder access uses `expandHomePath`, `resolveInsideHome` and
+ `specialFilesystem`; symlinks are operated on, not followed. Internal
+ endpoints (for example `/mcp`) must not be reachable through the web proxy;
+ add a proxy test. Typed input, passwords and tokens are never logged or
+ stored. Credentials never cross machines.
+- **Bounds.** Every retained buffer, list and payload has a limit (for example
+ 1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports
+ truncation instead of failing silently.
+- **Platform reality.** Check what the installed tools accept (for example
+ `codex app-server generate-json-schema`, `claude` control requests,
+ OpenCode's API). Browsers reserve some shortcuts (Ctrl/Cmd+T, Ctrl+Tab); say
+ which ones work where.
+- **Desktop vs phone.** Web themes are pinned to Android, so desktop checks use
+ `prefersCompactHitTargets` (device platform), not the theme platform.
+- **Shared environments.** Never use the production server (127.0.0.1:8080,
+ web 8083), real chats, the personal Fold, or restart shared services.
+
+## Verification
+
+- **Focused tests while editing.** Go: `go test ./internal/ -run `.
+ App: `cd app && tool/memwatch/full.sh 'test/a_test.dart test/b'` (the whole
+ path list is one quoted argument) and `tool/analyze.sh`. Web:
+ `cd web && node --test test/`. Never bare `flutter test`.
+- **Scratch end-to-end** for server behaviour: build `./cmd/pipelines-server`,
+ run it with an isolated `HOME`, a scratch `-db`, `-addr 127.0.0.1:0` (an OS-chosen port) and
+ `PIPELINES_MDNS=off`, drive it over the websocket, then stop every process.
+ Real harness runs need credentials; when they are missing, say so rather
+ than claim them.
+- **Rendered evidence** for visible changes: build the full-app fixture once
+ (`flutter build web --target tool/search_selection_probe_entry.dart --output
+ build/probe-app`) and capture with `app/tool/capture/` at wide (1400x900) and
+ narrow (560x1000) sizes, light and dark, Material and Cupertino where
+ relevant. Open every PNG cited.
+- **Known pre-existing failures** (as of 2026-11-09, on untouched main): 44
+ tests in `app/test/application/*` (pending launch-update timer) and, under a
+ `umask 077` shell, `internal/claude` `TestServiceTokenIsPassedOnlyFromAPrivateFile`
+ and `internal/opencode` `TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork`.
+ The installed server (and so the delivery gate) runs with `Umask 63`
+ (077), so the gate's Go check sets `umask 022` first. Compare against a
+ worktree of main before blaming a change.
+- **Notes.** Each feature leaves `app/notes/.md` with behaviour,
+ protocol, limits, security and the exact verification output.
+
+## Delivery (manager, not the workflow)
+
+The workflow commits a reviewed candidate; the server's delivery gate checks it
+and lands it on main. Deployment is separate and only on request: `./install`
+(web and server), a restart only when no chat or run is active, then
+`./install --apk` (native build), `./install --macos --publish --flutter
+` and `./install --linux --publish`.
diff --git a/docs/workflows/feature.md b/docs/workflows/feature.md
new file mode 100644
index 00000000..a2fc1db5
--- /dev/null
+++ b/docs/workflows/feature.md
@@ -0,0 +1,201 @@
+# stage prepare
+
+```prompt
+Prepare this branch for the task; do not implement it. Follow AGENTS.md. Preserve unfinished task edits in a local commit if any; a clean tree is a successful no-op, never an empty commit. Merge current main into this branch, resolving conflicts by keeping both intents and leaving unrelated files untouched. Run `cd app && /Users/alan/development/flutter/bin/flutter pub get` once. Run no test suites. Report HEAD and any task-owned paths.
+```
+
+```tools
+read
+glob
+grep
+edit
+shell
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=30m
+```
+
+```checks
+none: preparation only; implement runs focused tests and the land delivery gate runs the suites
+```
+
+```edges
+success -> plan
+blocked -> #failure
+error -> #failure
+```
+
+# stage plan
+
+```prompt
+Plan the task as one full-stack Pipelines feature using docs/feature-changes.md. Read only the code the task touches. Produce a short plan: the behaviour and acceptance checks; per layer (protocol, persistence, server, harness adapters, web proxy, app, fixture) what changes and in which files, keeping shared files to small hooks; security boundary and limits; how each harness or platform supports it, or that it does not; and the focused tests, scratch end-to-end check and rendered states to capture. Name open questions instead of guessing. Do not edit.
+```
+
+```tools
+read
+glob
+grep
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=20m
+```
+
+```edges
+success -> implement
+blocked -> #failure
+error -> #failure
+```
+
+# stage implement
+
+```limits
+{"max_visits":5,"on":["blocked_retryable"]}
+```
+
+```prompt
+Implement the task and plan across every layer it needs, following AGENTS.md, app/AGENTS.md and docs/feature-changes.md. Put logic in new small files; keep shared files to hooks; keep protocol fields additive. Add a fixture option for new rendered states.
+Run focused, quiet checks for what you touched (Go package tests, `tool/memwatch/full.sh` with one quoted path list, `tool/analyze.sh`, `node --test` for web changes). For server behaviour run the scratch end-to-end check from the guide and stop every process afterwards. Do not build or capture UI here; ui-review does that. Write app/notes/.md with behaviour, limits, security and the exact verification output, stating what was not tested.
+On re-entry fix only the handed-off must-fix findings. Do not commit, push, deploy or restart anything. Use blocked_retryable only for an evidenced transient prerequisite, otherwise blocked.
+```
+
+```tools
+read
+glob
+grep
+edit
+shell
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=90m
+```
+
+```checks
+none: focused tests and the scratch end-to-end check only; the land delivery gate runs the suites
+```
+
+```edges
+success -> review
+blocked_retryable -> implement
+blocked -> #failure
+error -> #failure
+```
+
+# stage review
+
+```limits
+{"max_visits":3,"on":["rejected"]}
+```
+
+```prompt
+Review this run's diff against the task, the plan (in history.md) and docs/feature-changes.md. Start from the changed-file list and `git diff --stat`, then read per-file hunks and the code around them. Check correctness across layers, the authentication and home-folder boundary, nothing exposed through the web proxy, no logged or stored secrets or input, bounds on retained data, restart and reconnect behaviour, multi-machine routing through the chat's own gateway, additive protocol changes, harness support claims, Material and Cupertino controls, desktop vs phone behaviour, and meaningful tests including the reported end-to-end check.
+Run no suites, builds or captures; ui-review owns rendered evidence. Do not edit or commit. On a revisit inspect only the fixes and new hunks. Return rejected for a concrete must-fix with location, evidence and fix; advisory for non-blocking notes; otherwise success.
+```
+
+```tools
+read
+glob
+grep
+shell
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=45m
+```
+
+```checks
+none: read-only review; shell is used only for git status and git diff
+```
+
+```edges
+success -> ui-review
+advisory -> ui-review
+rejected -> implement
+error -> #failure
+```
+
+# stage ui-review
+
+```limits
+{"max_visits":3,"on":["rejected"]}
+```
+
+```prompt
+Verify the changed UI in a real browser, per app/AGENTS.md, app/tool/capture/README.md and docs/feature-changes.md. Build the full-app fixture once, use the task's fixture option, and interact with every affected state: wide and narrow, light and dark, Material and Cupertino where relevant, including hover, keyboard and focus on desktop. Open every screenshot you cite and save captures and a short report in public/. Use only owned loopback servers and browsers; stop them afterwards.
+Run no suites; do not edit or commit. Return skipped only when the change has no rendered effect; rejected for a concrete visual or interaction defect with evidence and fix; blocked for an evidenced capture failure; advisory for non-blocking findings; otherwise approved.
+```
+
+```tools
+read
+glob
+grep
+shell
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=45m
+```
+
+```checks
+none: read-only visual review; shell only builds the fixture and captures, the land delivery gate runs the suites
+```
+
+```edges
+approved -> land
+advisory -> land
+skipped -> land
+rejected -> implement
+blocked -> #failure
+error -> #failure
+```
+
+# stage land
+
+```prompt
+Commit this run's reviewed change locally and leave a clean candidate. Inspect `git status --short` and the changed-file list; stage only this task's changes and its app/notes entry; check the staged diff (`git diff --cached --stat`, then per file as needed) for unrelated work, secrets and generated artifacts. Create no empty commit: when nothing is staged, report success with a clear note. Commit with a plain imperative subject and report the hash. Do not push, tag, amend, rebase or merge main, and run no suites: the server's delivery gate merges a moved main, runs the checks and lands the candidate. Do not deploy or restart anything. Return blocked with the paths if a clean candidate cannot be produced safely.
+```
+
+```tools
+read
+glob
+grep
+shell
+```
+
+```configs
+provider=openai
+model=gpt-5.6-luna
+retries=1
+timeout=45m
+delivery=true
+```
+
+```checks
+git diff --check main...HEAD
+cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- '*.go' go.mod go.sum; then echo "go: no Go changes since main"; else umask 022 && go build ./... && go vet ./... && go test ./...; fi
+cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- web; then echo "web: no web changes since main"; else cd web && node --test test/; fi
+cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- app; then echo "app: no app changes since main"; else cd app && /Users/alan/development/flutter/bin/flutter pub get >/dev/null && tool/analyze.sh && tool/memwatch/full.sh test; fi
+```
+
+```edges
+success -> #success
+blocked -> #failure
+error -> #failure
+```