# Web Console Contract: the Why Maintainer notes for the agent-facing console docs in `src/web-console/`. Installed skills never ship or load this file (nothing under `.agents-docs/` is in `install.js` `additionalReferences`), and the shipped files carry only what an agent must do. Put an explanation here, not there. If a shipped file starts to explain, move the sentence into this file and keep the instruction. The shape: a short card (`console.md`) read once per session, topic files the console names in its own `read` output at the moment each is due, and refusals for the silent slips the console can see. Size budgets in `npm test` stop the docs growing back (Phase 7 of `specs/console-wire-format`). ## Why pointers and refusals instead of repeated rules A rule stated in six files is read six times and still skipped. The console sees most slips (a `stop` with no `finish`, a `finish` with `stopWarning` set, a reply left unanswered), so it refuses them and says the fix, and it names a topic file once per session per topic when that topic's moment arrives. The card states each silent rule once. A rule that was broken twice in repeated prose becomes a check in the console, not another sentence. ## console.md (the card) - **Print then stamp.** `wait` prints a result and only then marks it collected (`advanceCursor`). A kill between the two repeats a delivery and never loses one. That is why "handle it once" is in `console-trouble.md`, and why `thread` (which appends) needs care on a repeat. - **Bounded slices.** A wait runs for a limited number of seconds sized under the agent's shell timeout, so the command returns by itself. A killed wait loses nothing. People step away for hours, so there is no cap on the number of slices. - **Every turn ends on a `wait`.** The page tells the person "the next question will appear here on its own". A turn that ends on text leaves that promise unkept and strands their next click. The console cannot see this slip, which is why the card states it. - **Three open questions at most.** More than three open cards turns the page into a form to fill in, not a conversation, and people answer the first three and skip the rest. The server enforces the cap. - **`settle`.** The server records a send on an item but only the agent decides it is final (a pick that still owes its recap is not). `settle` marks cards answered in the same post that moves on; a card left open stays on the page as a question still owed. - **Defaults are filled by the console** (`status`, `required`, `allowOther`, empty `options` and `thread`, option keys by position, doc `version` and `stale`): an obvious default costs tokens every patch and carries no decision. A default the console fills is the only thing the card may leave out. - **Recommend sparingly.** "Which format survives Excel?" is the agent's to recommend; "Who is this for?" is not, because a recommendation there is an anchor people rubber-stamp. - **A placeholder is an offer.** The Autofill button drops it into the box as a real answer, so it must be a whole answer in the person's voice and satisfy any `pattern`. - **Titles in plain words.** Internal vocabulary (grill, frontier, fog) means nothing to a newcomer and the server refuses it. The metric words rule exists because the metrics collector scrapes `Requirements`, `Feasibility`, `Integration` and `Risk` followed by a number. - **Loop markers refused.** `TASK_COMPLETE`, `PHASE_COMPLETE` and the rest are read by the loop CLI as completion; one in page text would end a run. - **The page owns its stream.** The agent never writes timestamps, versions or `agent.status` for a turn: the server stamps them, and collecting a send already sets the page to working. A second source of truth for them would drift. - **Quoted heredoc.** Unquoted `<`) are refused because a rendered command is copied and run verbatim. - **Continue here and Commit it now** are buttons the page derives from `command` and `commit`, so the agent writes nothing extra for them. ## console-chat.md - **Every message gets a reply.** The Ask tab shows "working on the answer" until one lands. The console warns on `post` and `wait` about unanswered Quick questions for that reason. - **Chat never steers the workflow.** A chat answer that approved a gate would make the record under `specs/` depend on a side channel. - **Edits need approval first** and happen only at check-ins, so a change cannot land mid-task. - **Prompts to carry away** start with prose because the page treats a fenced block whose first line looks like a shell command as a command, not a prompt. - **Replies merge by `id`,** so a repeated delivery is answered by re-posting the same reply, not by answering twice. ## console-workspace.md Added folders are read-only reference because the person added them as context, not as a place to work. The first read of a folder's `AGENTS.md` is once per folder per skill run so layout rules are known without re-reading. A `folderIssue` goes to the ledger, not the page state, so a failed read is reported once. ## console-subagents.md The setting arrives as a standing instruction only when it changes, so a long session is not repeated at. Pathfinder research always uses helpers whatever the switch says; the switch governs recon and lookups. Questions for the person stay with the agent, because a helper has no way to ask and an answer only reaches the agent holding the session. Helpers add no session meter points. ## building.md and building-review.md A build is mostly the agent working, so each task's checkbox write is posted at once (the Disk Write Rule): a session that dies mid-phase must leave disk true. `quietMinutes` exists because the page calls a working agent stuck after two silent minutes and a task can honestly take twenty. A question stops the build because the page reads `working` as "not your turn". The review runs inside the build's session and scores itself once on the meter, so it never resumes under `--workflow review` as well. The way back from a review lands on the sign-off without the review verdict, because re-offering a review that just ran reads as though nothing happened. ## console-launches.md and console-trouble.md A session handed over by the dashboard is resumed, never re-opened, because a fresh `open` strands the page the person is watching. The console never writes into a project, so deletes go through `delete-spec` and `delete-handoff`, which refuse links and anything outside `specs/`. ## console-meter.md The meter is advice, not a gate: it tells the person when a fresh session would be sharper. Per-unit work is reported by the agent with `run`; the same `id` is ignored in the same run so a repeat never double counts. ## Wire format (outputs) Outputs carry what the agent acts on and nothing else. Anything kept in the session files (`type`, `at`, `rev`, answer actions, full chat entries, structured workspace and subagents objects) is dropped from stdout. The desktop app reads `sid`, `url`, `pid`, `port` and `embed` from `open` in every context, so those stay. See `specs/console-wire-format/overview.md` (API Design) for the table.