# 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. The server answers only loopback `Host`s, refuses
`/connect` with an `Origin`, and requires the shared server token
(`docs/notes/security-boundary.md`); a new local client of the server
sends the token, and the peer relay's address policy covers new remote
paths. 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`.