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/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"