Use semantic filenames for visual companion screens

Server now watches directory for new .html files instead of a single
screen file. Claude writes to semantically named files like
platform.html, style.html, layout.html - each screen is a new file.

Benefits:
- No need to read before write (files are always new)
- Semantic filenames describe what's on screen
- History preserved in directory for debugging
- Server serves newest file by mtime automatically

Updated: index.js, start-server.sh, and all documentation.

skills/brainstorming/SKILL.md

@@ -90,10 +90,10 @@ Only proceed if they agree. Otherwise, describe options in text.
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
 
 # Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
-#           "screen_dir":"/tmp/brainstorm-12345","screen_file":"/tmp/brainstorm-12345/screen.html"}
+#           "screen_dir":"/tmp/brainstorm-12345"}
 ```
 
-Save `screen_dir` and `screen_file` from the response. Tell user to open the URL.
+Save `screen_dir` from the response. Tell user to open the URL.
 
 ### The Loop
 
@@ -102,10 +102,11 @@ Save `screen_dir` and `screen_file` from the response. Tell user to open the URL
    ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
    ```
 
-2. **Write HTML** to `screen_file`:
-   - First `Read` the screen_file (even if empty) so Write tool works
-   - Then use Write tool - **never use cat/heredoc** (dumps noise into terminal)
-   - If Write fails, read first then retry
+2. **Write HTML** to a new file in `screen_dir`:
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** - each screen gets a fresh file
+   - Use Write tool - **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
 
 3. **Tell user what to expect:**
    - Remind them of the URL (every step, not just first)
@@ -118,7 +119,7 @@ Save `screen_dir` and `screen_file` from the response. Tell user to open the URL
 
 5. **Process feedback** - returns JSON like `{"choice": "a", "feedback": "make header smaller"}`
 
-6. **Iterate or advance** - if feedback changes current screen, update and re-show. Only move to next question when current step is validated.
+6. **Iterate or advance** - if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to next question when current step is validated.
 
 7. Repeat until done.
 

skills/brainstorming/visual-companion.md

@@ -17,18 +17,19 @@ Quick reference for the browser-based visual brainstorming companion.
 ```bash
 # 1. Start server
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
-# Returns: {"screen_dir":"/tmp/brainstorm-xxx","screen_file":"...","url":"http://localhost:PORT"}
+# Returns: {"screen_dir":"/tmp/brainstorm-xxx","url":"http://localhost:PORT"}
 
 # 2. Start watcher FIRST (background bash) - avoids race condition
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
 
-# 3. Write HTML to screen_file using Write tool (browser auto-refreshes)
+# 3. Write HTML to a NEW file in screen_dir (e.g., platform.html, style.html)
+#    Never reuse filenames - server serves newest file automatically
 
 # 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. Iterate or advance - update screen if feedback changes it, else next question
+# 5. Iterate or advance - write new file if feedback changes it (e.g., style-v2.html)
 
 # 6. Clean up when done
 ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
@@ -39,13 +40,19 @@ ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
 - **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
+- **Iterate before advancing** - if feedback changes current screen, write new version
 - **2-4 options max** per screen
 
+## File Naming
+
+- **Use semantic names**: `platform.html`, `visual-style.html`, `layout.html`, `controls.html`
+- **Never reuse filenames** - each screen is a new file
+- **For iterations**: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server automatically serves the newest file by modification time
+
 ## Terminal UX
 
 - **Never use cat/heredoc for HTML** - dumps noise into terminal. Use Write tool instead.
-- **Read screen_file first** before Write (even if empty) to avoid tool errors
 - **Remind user of URL** on every step, not just the first
 - **Give text summary** of what's on screen before they look (e.g., "Showing 3 API structure options")