refactor: simplify visual companion workflow, improve guidance

Scripts:
- Rename show-and-wait.sh -> wait-for-feedback.sh (just waits, no HTML piping)
- Remove wait-for-event.sh (used hanging tail -f)
- Workflow now: Write tool for HTML, wait-for-feedback.sh to block

Documentation rewrite:
- Broader "when to use" (UI, architecture, complex choices, spatial)
- Always ask user first before starting
- Scale fidelity to the question being asked
- Explain the question on each page
- Iterate before moving on - validate changes address feedback
- Use real content (Unsplash images) when it matters

lib/brainstorm-server/wait-for-event.sh

@@ -1,20 +0,0 @@
-#!/bin/bash
-# Wait for a browser event from the brainstorm server
-# Usage: wait-for-event.sh <output-file> [event-type]
-#
-# Blocks until a matching event arrives, then prints it and exits.
-# Default event type: "send-to-claude"
-
-OUTPUT_FILE="${1:?Usage: wait-for-event.sh <output-file> [event-type]}"
-EVENT_TYPE="${2:-send-to-claude}"
-
-if [[ ! -f "$OUTPUT_FILE" ]]; then
-  echo "Error: Output file not found: $OUTPUT_FILE" >&2
-  exit 1
-fi
-
-# Wait for new lines matching the event type
-# -n 0: start at end (only new content)
-# -f: follow
-# grep -m 1: exit after first match
-tail -n 0 -f "$OUTPUT_FILE" | grep -m 1 "$EVENT_TYPE"

lib/brainstorm-server/show-and-wait.sh → lib/brainstorm-server/wait-for-feedback.sh

@@ -1,12 +1,11 @@
 #!/bin/bash
-# Write HTML to screen and wait for user feedback
-# Usage: show-and-wait.sh <screen_dir> < html_content
+# Wait for user feedback from the brainstorm browser
+# Usage: wait-for-feedback.sh <screen_dir>
 #
-# Reads HTML from stdin, writes to screen_file, waits for feedback.
-# Outputs the feedback JSON when user sends from browser.
+# Blocks until user sends feedback, then outputs the JSON.
+# Write HTML to screen_file BEFORE calling this.
 
-SCREEN_DIR="${1:?Usage: show-and-wait.sh <screen_dir>}"
-SCREEN_FILE="${SCREEN_DIR}/screen.html"
+SCREEN_DIR="${1:?Usage: wait-for-feedback.sh <screen_dir>}"
 LOG_FILE="${SCREEN_DIR}/.server.log"
 
 if [[ ! -d "$SCREEN_DIR" ]]; then
@@ -14,15 +13,11 @@ if [[ ! -d "$SCREEN_DIR" ]]; then
   exit 1
 fi
 
-# Write HTML from stdin to screen file
-cat > "$SCREEN_FILE"
-
 # Record current position in log file
 LOG_POS=$(wc -l < "$LOG_FILE" 2>/dev/null || echo 0)
 
 # Poll for new lines containing the event
 while true; do
-  # Check for new matching lines since our starting position
   RESULT=$(tail -n +$((LOG_POS + 1)) "$LOG_FILE" 2>/dev/null | grep -m 1 "send-to-claude")
   if [[ -n "$RESULT" ]]; then
     echo "$RESULT"

skills/brainstorming/SKILL.md

@@ -55,81 +55,74 @@ Start by understanding the current project context, then ask questions one at a
 
 ## Visual Companion (Claude Code Only)
 
-When brainstorming involves visual elements - UI mockups, layouts, design comparisons - you can use a browser-based visual companion instead of ASCII art. **This only works in Claude Code.**
+A browser-based visual companion for showing mockups, diagrams, and options. Use it whenever visual representation makes feedback easier. **Only works in Claude Code.**
 
-### When to Offer
+### When to Use
 
-If the brainstorm involves visual decisions (UI layouts, design choices, mockups), ask the user:
+Use the visual companion when seeing beats describing:
+- **UI mockups** - layouts, navigation, component designs
+- **Architecture diagrams** - system components, data flow, relationships
+- **Complex choices** - multi-option decisions with visual trade-offs
+- **Design polish** - when the question is about look and feel
+- **Spatial relationships** - file structures, database schemas, state machines
 
+**Always ask first:**
 > "This involves some visual decisions. Would you like me to show mockups in a browser window? (Requires opening a local URL)"
 
-Only proceed with visual companion if they agree. Otherwise, describe options in text.
+Only proceed if they agree. Otherwise, describe options in text.
 
-### Starting the Visual Companion
+### How to Use Effectively
 
-```bash
-# Start server (creates unique session directory)
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
+**Scale fidelity to the question.** If you're asking about layout structure, simple wireframes suffice. If you're asking about visual polish, show polish. Match the mockup's detail level to what you're trying to learn.
 
-# Output looks like:
-# {"type":"server-started","port":52341,"url":"http://localhost:52341",
-#  "screen_dir":"/tmp/brainstorm-12345-1234567890",
-#  "screen_file":"/tmp/brainstorm-12345-1234567890/screen.html"}
-```
+**Explain the question on each page.** Don't just show options—state what decision you're seeking. "Which layout feels more professional?" not just "Pick one."
 
-**Save the `screen_dir` and `screen_file` paths from the response** - you'll need them throughout the session.
+**Iterate before moving on.** If feedback changes the current screen, update it and show again. Validate that your changes address their feedback before proceeding to the next question.
 
-Tell the user to open the URL in their browser.
+**Limit choices to 2-4 options.** More gets overwhelming. If you have more alternatives, narrow them down first or group them.
 
-### Showing Content
+**Use real content when it matters.** For a photography portfolio, use actual images (Unsplash). For a blog, use realistic text. Placeholder content obscures design issues.
 
-Write complete HTML to the session's `screen_file` path. The browser auto-refreshes.
+### Starting a Session
 
-Use the frame template structure from `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`:
-- Keep the header and feedback-footer intact
-- Replace `#claude-content` with your content
-- Use the CSS helper classes (`.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`)
+```bash
+# Start server (creates unique session directory)
+${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
 
-See `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md` for detailed examples.
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/tmp/brainstorm-12345","screen_file":"/tmp/brainstorm-12345/screen.html"}
+```
 
-### Waiting for User Feedback
+Save `screen_dir` and `screen_file` from the response. Tell user to open the URL.
 
-Start the watcher as a background bash command, then use TaskOutput with block=true to wait:
+### The Loop
 
-```bash
-# 1. Start watcher in background
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-event.sh $SCREEN_DIR/.server.log
+1. **Start watcher first** (background bash) - avoids race condition:
+   ```bash
+   ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
+   ```
 
-# 2. Call TaskOutput(task_id, block=true, timeout=600000) to wait
-# 3. If timeout, call TaskOutput again (watcher is still running)
-# 4. After 3 timeouts (30 min), say "Let me know when you want to continue" and stop looping
-```
+2. **Write HTML** to `screen_file` using the Write tool (browser auto-refreshes)
 
-When the user clicks Send in the browser, the watcher exits and TaskOutput returns with feedback:
-```json
-{"choice": "a", "feedback": "I like this but make the header smaller"}
-```
+3. **Wait for feedback** - call `TaskOutput(task_id, block=true, timeout=600000)`
+   - If timeout, call TaskOutput again (watcher still running)
+   - After 3 timeouts (30 min), say "Let me know when you want to continue"
 
-### The Loop
+4. **Process feedback** - returns JSON like `{"choice": "a", "feedback": "make header smaller"}`
 
-1. Start watcher (background bash) - must be FIRST to avoid race condition
-2. Write screen HTML to `screen_file`
-3. Call TaskOutput(task_id, block=true, timeout=600000) to wait
-4. TaskOutput returns with feedback
-5. Respond with new screen
-6. Repeat until done
+5. **Iterate or advance** - if feedback changes current screen, update and re-show. Only move to next question when current step is validated.
 
-### Cleaning Up
+6. Repeat until done.
 
-When the visual brainstorming session is complete, pass the screen_dir to stop:
+### Cleaning Up
 
 ```bash
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
 ```
 
-### Tips
+### Resources
 
-- **Keep mockups simple** - Focus on layout and structure, not pixel-perfect design
-- **Limit choices** - 2-4 options is ideal
-- **Regenerate fully** - Write complete HTML each turn; the screen is stateless
-- **Terminal is primary** - The browser shows things; conversation happens in terminal
+- Frame template: `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
+- CSS classes: `.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`
+- Detailed examples: `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md`
+- Quick reference: `${CLAUDE_PLUGIN_ROOT}/skills/brainstorming/visual-companion.md`

skills/brainstorming/visual-companion.md

@@ -1,6 +1,6 @@
 # Visual Companion Reference
 
-Quick reference for using the visual brainstorming companion.
+Quick reference for the browser-based visual brainstorming companion.
 
 ## Files
 
@@ -8,34 +8,40 @@ Quick reference for using the visual brainstorming companion.
 |------|---------|
 | `lib/brainstorm-server/start-server.sh` | Start server, outputs JSON with URL and session paths |
 | `lib/brainstorm-server/stop-server.sh` | Stop server and clean up session directory |
-| `lib/brainstorm-server/wait-for-event.sh` | Wait for user feedback |
+| `lib/brainstorm-server/wait-for-feedback.sh` | Wait for user feedback (polling-based) |
 | `lib/brainstorm-server/frame-template.html` | Base HTML template with CSS |
 | `lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md` | Detailed usage guide |
 
 ## Quick Start
 
 ```bash
-# 1. Start server (creates unique session directory)
+# 1. Start server
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
-# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
-#           "screen_dir":"/tmp/brainstorm-12345-1234567890",
-#           "screen_file":"/tmp/brainstorm-12345-1234567890/screen.html"}
+# Returns: {"screen_dir":"/tmp/brainstorm-xxx","screen_file":"...","url":"http://localhost:PORT"}
 
-# 2. Start watcher FIRST (before writing screen - avoids race condition)
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-event.sh $SCREEN_DIR/.server.log
+# 2. Start watcher FIRST (background bash) - avoids race condition
+${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
 
-# 3. Write screen to the session's screen_file
-# Use Bash with heredoc to write HTML
+# 3. Write HTML to screen_file using Write tool (browser auto-refreshes)
 
-# 4. Wait for feedback - call TaskOutput(task_id, block=true, timeout=600000)
-# If timeout, call TaskOutput again (watcher still running)
-# After 3 timeouts (30 min), say "Let me know when you want to continue"
+# 4. Call TaskOutput(task_id, block=true, timeout=600000)
+#    If timeout, call again. After 3 timeouts (30 min), prompt user.
 # Returns: {"choice":"a","feedback":"user notes"}
 
-# 5. Clean up when done (pass screen_dir as argument)
+# 5. Iterate or advance - update screen if feedback changes it, else next question
+
+# 6. Clean up when done
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
 ```
 
+## Key Principles
+
+- **Always ask first** before starting visual companion
+- **Scale fidelity to the question** - wireframes for layout, polish for polish questions
+- **Explain the question** on each page - what decision are you seeking?
+- **Iterate before advancing** - if feedback changes current screen, update and re-show
+- **2-4 options max** per screen
+
 ## CSS Classes
 
 ### Options (A/B/C choices)