78 78 --html-file /tmp/first-mockup.html
81 +**Thinking time rule:** Do not use short blocking waits for visual decisions that need real thinking time: logo direction, style exploration, layout comparison, subjective polish, multi-option mockups, or anything the user may want to inspect. Blocking commands now default to 10 minutes and allow up to 1 hour, but for open-ended design thinking prefer `write-screen` or `start-screen`, give the URL, and later read clicks with `events`.
83 +**Human notes rule:** Every visual screen includes a human notes textarea. Browser click events include `humanNotes`; use those notes as first-class user feedback, not an afterthought. If the notes contradict the clicked option, ask one clarifying question or iterate toward the notes.
85 +**NON-NEGOTIABLE FIRST ACTION after any visual screen:** before replying, before reading files, before making new mockups, before explaining, run:
88 +node scripts/companion.mjs listen --project-dir PROJECT --clear
91 +This finds the newest project session, so there is no session ID for the agent to remember. Skipping this is a skill violation. Do not use `events SESSION_DIR` unless debugging the companion itself. Treat returned clicks and `humanNotes` as the user's current visual answer unless the terminal message explicitly overrides them. Never ask the user to repeat a clicked choice in chat. If there are no events, proceed from the terminal text.
81 93 If `open-choice` / `open-screen` cannot open a browser in the current environment, fall back to `start-choice` / `start-screen`, save `session_dir` from the response, and tell the user to open the URL. Never use `start` alone; it is rejected because the browser would show the waiting page.
83 95 **Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.super/brainstorm/` for the session directory.
116 -1. **For visual choices, ask and wait in one deterministic command.** It checks the server, writes a fresh filename, clears old events, blocks for the browser click, then prints the selected event JSON:
128 +1. **For quick visual choices only, ask and wait in one deterministic command.** It checks the server, writes a fresh filename, clears old events, blocks for the browser click, then prints the selected event JSON. Do not use this path for subjective design thinking; use the thinking time rule above.
119 131 node scripts/companion.mjs ask-choice
"$SESSION_DIR" \
122 134 --subtitle "Consider readability and visual hierarchy" \
123 135 --option "single|Single Column|Clean, focused reading experience" \
124 136 --option "two|Two Column|Sidebar navigation with main content" \
137 + --timeout-ms 600000
128 - Do not tell the user "reply here after clicking" for normal visual choices. The click itself returns to the agent through the tool result while the turn is active. Never set `--timeout-ms` above `30000`; the script rejects slower waits.
140 + Do not tell the user "reply here after clicking" for normal visual choices. The click itself returns to the agent through the tool result while the turn is active. Use long waits for user-facing visual choices; never rush subjective decisions.
130 142 2. **For custom visual choices, write HTML to a file, then ask and wait.** Do not embed large HTML in shell args or heredocs.
134 146 node scripts/companion.mjs ask-screen "$SESSION_DIR" \
135 147 --name layout-custom \
136 148 --html-file /tmp/layout-options.html \
149 + --timeout-ms 600000
140 152 The HTML must include clickable elements with `data-choice` and `onclick="toggleSelect(this)"`.
151 163 Remind them of the URL and ask for terminal feedback only when the answer is open-ended text, not a choice.
153 -4. **For existing browser feedback, use the script:**
165 +4. **For existing browser feedback, only use `listen`:**
156 - node scripts/companion.mjs events
"$SESSION_DIR" 157 - node scripts/companion.mjs wait-choice
"$SESSION_DIR" --timeout-ms 30000
158 - node scripts/companion.mjs events
"$SESSION_DIR" --clear
168 + node scripts/companion.mjs listen --project-dir /path/to/project --clear
169 + node scripts/companion.mjs listen --project-dir /path/to/project --timeout-ms 600000 --clear
161 - Merge browser events with any terminal text if both exist. Terminal text is primary for open-ended feedback; browser events are primary for visual choices.
172 + Required before every response while visual mode is active. Merge browser events with any terminal text if both exist. Terminal text is primary only when it explicitly overrides browser feedback; otherwise browser clicks + `humanNotes` are primary.
163 174 5. **Iterate or advance** — if feedback changes current screen, push a new screen name (e.g., `layout-v2`). Only move to the next question when the current step is validated.