# 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`.