# How the owner works

- **By voice, from the terminal, the web and the phone:** requests are often dictated in Portuguese; read them through transcription slips. Answer in pt-BR; everything committed (code, docs, issues, PRs) stays in English. A cloud session has no local files: whatever a session needs lives in this file or on GitHub, never only in `CLAUDE.local.md`.
- **Spoken summaries are off by default** (owner, 2026-11-20): run `speak "<text>"` after each answer only once the owner asks for it in the current session, and stop when asked. When on: one to three sentences in pt-BR, ending with the turn's question, if any; numbers and issue references as words ("issue oitenta e um"), no code, paths or tables. Without `speak` (web, phone), skip it.
- **Every issue or PR number carries its short title,** every time, in chat, spoken summaries, issues, comments and PR descriptions: `#254 (events contract for Controllers)`; a title seen only in a tool result does not count as shown.
- **A background run can be followed:** when running `make scene`, any `test/scene*` or anything else long in the background, show in the reply, before waiting, the complete `tail --follow /absolute/path/of/the.log` in a code block of its own, with no variable or shortened path, so the owner can paste it into another tmux pane of the same window (owner, 2026-10-31, 2026-11-03).
- **The owner is the only user for now, and for a good while** (2026-11-03): a change of behaviour needs no migration or compatibility step, only a line in the PR.
- **Only the main session speaks aloud:** subagents and background agents never call `speak`, and every prompt given to one says so.
- **End of session as buttons** (owner, 2026-11-14): when proposing how a session ends (`/next save`, `/wrap-up`, `/clear`) or other next steps the agent can run itself, offer them as clickable options (`AskUserQuestion`), the recommended one first; on a click, run it (a skill through the `Skill` tool). `/clear` and other built-in commands only the owner types: say so in the option. The agent cannot write into the prompt box.
- **Flag a long side quest, once:** when about an hour goes into one topic that does not move the MVP (issues labelled `mvp`), say so in one line ("we have spent about an hour on X, which is not on the MVP"); never push to leave it, the owner decides.
- **The visual companion's content stays out of the terminal:** when a browser screen carries a diagram, names or options, the reply only says the screen is up and stops, with no question (the click answers it); never repeat the screen's content.
- **Decisions and spec reviews go through the visual companion:** open questions, triage and spec reviews are one screen per question, with its context, the options and the recommendation first; the terminal only points to it. It is the default for refinements, whenever it fits.
- **Companion screens:** buttons in one compact row fixed at the bottom left (no scrolling), each with a coloured icon, always a "back to the previous" one and never a "change" one (changes are asked in the terminal); a click moves on with no terminal message. Diagrams: boxes and arrows, a readable monospaced font, a comment line before each command and a blank line between commands; a diagram worth keeping goes to the docs, in English. One type scale per screen (body and diagram text the same size, only the title larger), and diagrams as HTML boxes rather than a scaled SVG, so the text keeps its size on a split screen.
- **CLI commands are shown as a terminal** on every rendered surface (companion screens, decks, HTML pages), in the format of the wasp-idp deck (`docs/presentations/diagrams/journey/build.py` there, `command_line`): a dark window (`#070b14`, title bar `#111827` with the three dots and the working directory), a monospaced font; `$ ` in bold blue `#4a9ef4`; `nereus` (formerly `platform`) dim `#9fb3c8`, the command group in violet `#c3a6ff`, the verb in bold white, the names it acts on and option values in amber `#e5c07b`, options (`--name`) in light blue `#7cc4ff`; output in `#9fb3c8`, success lines (`✓ ...`) in green `#7ee787`; a comment line before each command and a blank line between commands; the `Next steps:` block of each output stays in it, with a blank line before and after its label. Long options only, one per line, indented 2 spaces from where `nereus` starts (4 with `$ `). A reef, Nereid, Mandate or secret takes its concept colour in the terminal too (reef `#1D9E75`, Nereid `#7F77DD`, Mandate `#D85A30`, secret `#BA7517`; `docs/agent/decks.md`). Markdown keeps fenced code blocks.
