brainstorm-companion 1.2.1 → 2.0.1

package/README.md

@@ -4,6 +4,8 @@ Visual brainstorming tool for AI coding sessions. Opens a browser window where a
 
 Zero dependencies. Node.js >= 18 only.
 
+**Sessions are persistent** — they stay alive until you explicitly stop them with `stop` or `brainstorm_stop_session`. Use `--timeout <minutes>` if you want auto-cleanup.
+
 ## Install
 
 ```bash
@@ -16,33 +18,83 @@ Or run directly:
 npx brainstorm-companion start
 ```
 
-## Quick Start
+### Claude Code MCP Setup
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "brainstorm": {
+      "command": "npx",
+      "args": ["brainstorm-companion", "--mcp"]
+    }
+  }
+}
+```
+
+Once configured, the agent has access to 5 tools: `brainstorm_start_session`, `brainstorm_push_screen`, `brainstorm_read_events`, `brainstorm_clear_screen`, and `brainstorm_stop_session`. Full documentation is embedded in the tool descriptions — the agent becomes an expert immediately upon connecting.
+
+---
+
+## Complete Usage Guide
+
+### Quick Start (CLI) — 3 commands, zero config
+
+```bash
+brainstorm-companion start                                    # opens browser
+brainstorm-companion push --html '<h2>Hello World</h2>'       # shows content
+brainstorm-companion stop                                     # cleans up
+```
 
-### CLI
+That's it. No arguments required. Now a fuller example:
 
 ```bash
-# 1. Start server (opens browser automatically)
-brainstorm-companion start --project-dir .
+# Start (opens browser, prints URL)
+brainstorm-companion start
 # → Server started: http://127.0.0.1:54321
-# → Session ID: 1234-1700000000000
 
-# 2. Push content — browser updates instantly
-brainstorm-companion push --html '<h2>Dashboard Layout</h2><div class="options"><div class="option" data-choice="grid" onclick="toggleSelect(this)"><div class="letter">A</div><div class="content"><h3>Grid Layout</h3><p>Cards in a responsive grid</p></div></div><div class="option" data-choice="list" onclick="toggleSelect(this)"><div class="letter">B</div><div class="content"><h3>List Layout</h3><p>Vertical scrolling list</p></div></div></div>'
+# Push content — browser updates instantly
+brainstorm-companion push --html '<h2>Dashboard</h2><p>First draft</p>'
 
-# 3. Update content — same browser, no restart needed
-brainstorm-companion push --html '<h2>Updated Layout</h2><p>Refined version based on feedback</p>'
+# Update — same browser, auto-reloads
+brainstorm-companion push --html '<h2>Dashboard v2</h2><p>Refined</p>'
 
-# 4. Read user's selection
+# Read what user clicked
 brainstorm-companion events
-# → [{"type":"click","choice":"grid","text":"A Grid Layout Cards in a responsive grid","timestamp":1700000001234}]
 
-# 5. Stop when done
+# Done
 brainstorm-companion stop
 ```
 
-**Key behavior:** Calling `start` when a session is already running reuses it — no duplicate browsers. Just keep calling `push` to update the same window. The browser auto-reloads on every push.
+**Key behaviors:**
+- `start` with no args works immediately (stores in `/tmp/brainstorm-companion/`)
+- `start` reuses an existing session — never opens duplicate browsers
+- `push` auto-reloads the browser every time — no restart or refresh needed
+- Add `--project-dir .` for project-local storage
 
-### Side-by-Side Comparison
+### Quick Start (MCP / Agent) — 3 calls, zero config
+
+```
+1. brainstorm_start_session()
+   → { url: "http://127.0.0.1:54321", session_dir: "..." }
+
+2. brainstorm_push_screen({ html: "<h2>Option A</h2>...", slot: "a", label: "Minimal" })
+   brainstorm_push_screen({ html: "<h2>Option B</h2>...", slot: "b", label: "Sidebar" })
+
+3. brainstorm_read_events({})
+   → { events: [{ type: "preference", choice: "a" }], count: 1 }
+
+4. brainstorm_push_screen({ html: "<h2>Revised A</h2>...", slot: "a", label: "Minimal v2" })
+
+5. brainstorm_stop_session({})
+```
+
+**No arguments required.** `brainstorm_start_session()` works with zero config. Pass `project_dir` for project-local storage or when multiple agents run simultaneously. Sessions persist until `brainstorm_stop_session()` — use `idle_timeout_minutes` for auto-cleanup.
+
+---
+
+## Side-by-Side Comparison
 
 Push to named slots for comparison mode with tabs and preference selection:
 
@@ -54,7 +106,7 @@ brainstorm-companion push --html '<h2>Hybrid</h2><p>Collapsible sidebar + top ba
 
 Browser shows all three side-by-side with tabs, keyboard shortcuts (1/2/3), and a preference bar.
 
-### Updating Content In-Place
+## Updating Content In-Place
 
 The browser auto-reloads whenever content is pushed. No need to restart the session or manually refresh:
 
@@ -72,7 +124,7 @@ brainstorm-companion push --html '<h2>Updated Option A</h2>' --slot a --label "R
 # → Only slot A updates, others stay
 ```
 
-### From Files or Stdin
+## From Files or Stdin
 
 ```bash
 brainstorm-companion push mockup.html
@@ -80,7 +132,7 @@ brainstorm-companion push mockup.html --slot a --label "v1"
 cat design.html | brainstorm-companion push -
 ```
 
-### Parallel Instances
+## Parallel Instances
 
 Multiple agents can run simultaneously on the same project. Use `--new` to force a separate session:
 
@@ -102,26 +154,80 @@ brainstorm-companion stop --session 1111-000
 
 Without `--new`, `start` reuses the existing session (the default for single-agent use).
 
-## MCP Server
+---
 
-Brainstorm Companion runs as an [MCP](https://modelcontextprotocol.io) server for direct integration with AI coding tools.
+## HTML Content Guide
 
-### Claude Code
+### Built-in CSS Classes
 
-Add to `~/.claude/settings.json`:
+The frame template provides themed styles (auto light/dark mode). Push HTML **fragments**, not full documents — the frame wraps your content with theming, a header, and a selection indicator bar.
 
-```json
-{
-  "mcpServers": {
-    "brainstorm": {
-      "command": "npx",
-      "args": ["brainstorm-companion", "--mcp"]
-    }
-  }
-}
+| Class | Purpose |
+|-------|---------|
+| `.options` + `.option` | Selectable vertical option cards with letter badges |
+| `.option .letter` | A/B/C badge inside an option |
+| `.option .content` | Text content inside an option |
+| `.cards` + `.card` | Grid cards with `.card-image` and `.card-body` |
+| `.mockup` | Browser-window container with `.mockup-header` and `.mockup-body` |
+| `.split` | Side-by-side two-column layout |
+| `.pros-cons` | Pros/cons comparison with `.pros` (green) and `.cons` (red) |
+| `.placeholder` | Dashed placeholder area |
+| `.subtitle` | Muted text below headings |
+| `.section` | Block with top margin spacing |
+| `.label` | Small uppercase badge |
+| `.mock-nav`, `.mock-sidebar`, `.mock-content` | UI mockup building blocks |
+| `.mock-button`, `.mock-input` | Styled form elements |
+
+### Making Elements Interactive
+
+Add `data-choice` and `onclick="toggleSelect(this)"` to capture user selections:
+
+```html
+<div class="option" data-choice="grid" onclick="toggleSelect(this)">
+  <div class="letter">A</div>
+  <div class="content"><h3>Grid Layout</h3></div>
+</div>
+```
+
+For multi-select, add `data-multiselect` to the container:
+
+```html
+<div class="options" data-multiselect>...</div>
+```
+
+### Auto-detected Libraries
+
+Content is automatically enhanced when these patterns are detected (CDN injected automatically):
+
+| Pattern | Library | What it does |
+|---------|---------|-------------|
+| `class="mermaid"` | Mermaid | Renders diagrams (flowchart, sequence, class, state, ER, Gantt, pie) |
+| `class="language-*"` | Prism.js | Syntax highlighting |
+| `$$...$$` or `class="math"` | KaTeX | Math rendering |
+
+```html
+<div class="mermaid">
+graph TD
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Action]
+  B -->|No| D[Other]
+</div>
 ```
 
-### MCP Tools
+---
+
+## Event Types
+
+| Event | When | Key Fields |
+|-------|------|-----------|
+| `click` | User clicks a `[data-choice]` element | `choice`, `text`, `id`, `timestamp` |
+| `preference` | User picks a preferred slot in comparison mode | `choice` (slot id), `timestamp` |
+| `tab-switch` | User switches tabs in comparison mode | `slot`, `timestamp` |
+| `view-change` | User toggles side-by-side vs single view | `mode`, `timestamp` |
+
+---
+
+## MCP Tools Reference
 
 | Tool | Description |
 |------|-------------|
@@ -131,25 +237,73 @@ Add to `~/.claude/settings.json`:
 | `brainstorm_clear_screen` | Clear a specific slot or all content. |
 | `brainstorm_stop_session` | Stop server and clean up session files. |
 
-### MCP Workflow Example
+---
+
+## Workflow Patterns
+
+### Single Decision
 
 ```
-1. brainstorm_start_session({ project_dir: "/path/to/project" })
-   → { url: "http://127.0.0.1:54321", session_dir: "..." }
+1. brainstorm_start_session({ project_dir: "..." })
+2. brainstorm_push_screen({ html: "...options with data-choice..." })
+3. → Tell user to make their selection in the browser
+4. brainstorm_read_events({})
+5. → Use the choice to proceed
+6. brainstorm_stop_session({})
+```
 
-2. brainstorm_push_screen({ html: "<h2>Option A</h2>...", slot: "a", label: "Minimal" })
-   brainstorm_push_screen({ html: "<h2>Option B</h2>...", slot: "b", label: "Sidebar" })
+### A/B/C Comparison
 
-3. brainstorm_read_events({})
-   → { events: [{ type: "preference", choice: "a" }], count: 1 }
+```
+1. brainstorm_start_session({ project_dir: "..." })
+2. brainstorm_push_screen({ html: "...", slot: "a", label: "Option A" })
+3. brainstorm_push_screen({ html: "...", slot: "b", label: "Option B" })
+4. → Tell user to compare and pick a preference
+5. brainstorm_read_events({})
+6. → Look for { type: "preference", choice: "a"|"b" }
+7. brainstorm_stop_session({})
+```
 
-   // Update content — same browser, no restart
-4. brainstorm_push_screen({ html: "<h2>Revised A</h2>...", slot: "a", label: "Minimal v2" })
+### Multi-Round Brainstorming
 
-5. brainstorm_stop_session({})
+```
+1. brainstorm_start_session({ project_dir: "..." })
+
+// Round 1: Layout
+2. brainstorm_push_screen({ html: "...", slot: "a", label: "Grid" })
+3. brainstorm_push_screen({ html: "...", slot: "b", label: "List" })
+4. brainstorm_read_events({ clear_after_read: true })
+5. → User chose "Grid"
+
+// Round 2: Color scheme (clear old slots first)
+6. brainstorm_clear_screen({})
+7. brainstorm_push_screen({ html: "...", slot: "a", label: "Light" })
+8. brainstorm_push_screen({ html: "...", slot: "b", label: "Dark" })
+9. brainstorm_read_events({ clear_after_read: true })
+10. → User chose "Dark"
+
+// Show final summary
+11. brainstorm_push_screen({ html: "<h2>Decisions: Grid + Dark</h2>..." })
+12. brainstorm_stop_session({})
+```
+
+### Progressive Refinement
+
+```
+1. brainstorm_start_session({ project_dir: "..." })
+
+// Show initial mockup
+2. brainstorm_push_screen({ html: "...v1 mockup..." })
+3. → Get feedback from user (text in chat, not events)
+
+// Push refined version — browser auto-reloads
+4. brainstorm_push_screen({ html: "...v2 mockup with changes..." })
+5. → Iterate until user is satisfied
+
+6. brainstorm_stop_session({})
 ```
 
-**Important:** Call `brainstorm_start_session` once. It returns the existing session if already running. Update content by calling `brainstorm_push_screen` repeatedly — the browser auto-reloads each time.
+---
 
 ## CLI Reference
 
@@ -174,10 +328,10 @@ Global Options:
 ### `start`
 
 ```
-brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--foreground] [--no-open] [--new]
+brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--timeout <min>] [--foreground] [--no-open] [--new]
 ```
 
-If a session is already running, prints its URL and reuses it. Use `--new` to force a separate parallel session.
+If a session is already running, prints its URL and reuses it. Use `--new` to force a separate parallel session. Use `--timeout 30` for auto-cleanup after 30 minutes idle (default: no timeout).
 
 ### `push`
 
@@ -215,58 +369,7 @@ brainstorm-companion status
 
 Shows Session ID, URL, uptime, event count, and active slots.
 
-## HTML Content Guide
-
-### Built-in CSS Classes
-
-The frame template provides themed styles (auto light/dark mode):
-
-| Class | Purpose |
-|-------|---------|
-| `.options` + `.option` | Selectable vertical option cards with letter badges |
-| `.cards` + `.card` | Grid cards with `.card-image` and `.card-body` |
-| `.mockup` | Container with `.mockup-header` and `.mockup-body` |
-| `.split` | Side-by-side two-column layout |
-| `.pros-cons` | Pros/cons comparison with `.pros` and `.cons` |
-| `.placeholder` | Dashed placeholder area |
-| `.mock-nav`, `.mock-sidebar`, `.mock-content` | UI mockup building blocks |
-| `.mock-button`, `.mock-input` | Styled form elements |
-
-### Making Elements Interactive
-
-Add `data-choice` and `onclick="toggleSelect(this)"` to capture user selections:
-
-```html
-<div class="option" data-choice="grid" onclick="toggleSelect(this)">
-  <div class="letter">A</div>
-  <div class="content"><h3>Grid Layout</h3></div>
-</div>
-```
-
-For multi-select, add `data-multiselect` to the container:
-
-```html
-<div class="options" data-multiselect>...</div>
-```
-
-### Auto-detected Libraries
-
-Content is automatically enhanced when these patterns are detected:
-
-| Pattern | Library | What it does |
-|---------|---------|-------------|
-| `class="mermaid"` | Mermaid | Renders diagrams from text |
-| `class="language-*"` | Prism.js | Syntax highlighting |
-| `$$...$$` or `class="math"` | KaTeX | Math rendering |
-
-```html
-<div class="mermaid">
-graph TD
-  A[Start] --> B{Decision}
-  B -->|Yes| C[Action]
-  B -->|No| D[Other]
-</div>
-```
+---
 
 ## How It Works
 
@@ -276,7 +379,30 @@ graph TD
 4. Click events are sent over WebSocket to the server and appended to a `.events` JSONL file
 5. `events` reads the JSONL file and returns structured JSON
 6. Each session is fully isolated: own port, own directory, own event log
-7. Server runs independently with a 30-minute idle timeout; `stop` cleans up immediately
+7. Sessions are persistent — they stay alive until explicitly stopped with `stop` or `brainstorm_stop_session`
+
+## Best Practices
+
+1. **Always pass `project_dir`** to `brainstorm_start_session` — avoids cross-agent conflicts
+2. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
+3. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
+4. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+5. **Start with a heading** — `<h2>` describes what the user is looking at
+6. **Add a `.subtitle`** — describes the decision being made
+7. **One decision per screen** — don't combine unrelated choices
+8. **Use slot labels** — `label` makes comparison tabs readable
+9. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+10. **Tell the user to interact** — after pushing content, let them know the browser is ready
+11. **Read events after user has time** — don't immediately read; wait for user to respond
+12. **Clean up with `brainstorm_stop_session`** — frees the port and removes temp files
+
+## Common Mistakes
+
+- **Starting a new session for each update** — DON'T. Call `push_screen` to update the existing browser.
+- **Omitting `project_dir`** — leads to `/tmp` collisions between agents.
+- **Pushing full HTML documents** — push fragments; the frame template adds theming and structure.
+- **Reading events immediately after push** — give the user time to interact first.
+- **Forgetting to stop** — always call `brainstorm_stop_session` when done.
 
 ## Author
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainstorm-companion",
-  "version": "1.2.1",
+  "version": "2.0.1",
   "description": "AI-assisted visual brainstorming companion",
   "type": "commonjs",
   "license": "MIT",

package/skill/SKILL.md

@@ -1,41 +1,61 @@
 ---
 name: brainstorm-companion
-description: Visual brainstorming companion — opens a browser window for comparing design mockups, architecture options, and UI prototypes. Agents push HTML content and users interact visually.
+description: Visual brainstorming companion — opens a browser window for comparing design mockups, architecture options, and UI prototypes. Agents push HTML content and users interact visually. Sessions are persistent and never time out.
 ---
 
-# Brainstorm Companion
+# Brainstorm Companion — Complete Agent Reference
+
+## Quickstart (3 calls, no setup)
+
+```
+brainstorm_start_session()
+brainstorm_push_screen({ html: "<h2>Hello World</h2><p>Your content here</p>" })
+brainstorm_stop_session()
+```
+
+That's it. No arguments required. A browser opens, your HTML appears, and cleanup happens automatically.
 
 ## When to Use
 
-Use this tool when you need to:
-- Show visual mockups, UI designs, or layout options to the user
-- Compare multiple design alternatives side-by-side (A/B/C comparison)
+- Show visual mockups, UI designs, or layout options
+- Compare design alternatives side-by-side (A/B/C)
 - Present architecture diagrams (Mermaid), code samples (Prism), or math (KaTeX)
-- Get visual feedback — user clicks and preferences are captured as events
-- Show interactive prototypes or wireframes
+- Get visual feedback — user clicks and preferences captured as events
+
+**Don't use** for plain text, simple data, or anything fine in the terminal.
 
-**Don't use** for plain text output, simple data, or anything that works fine in the terminal.
+## Session Lifecycle
+
+- **No setup needed** — `brainstorm_start_session()` works with zero arguments
+- **Sessions are persistent** — they stay alive until you call `brainstorm_stop_session`
+- **Safe to call start multiple times** — reuses existing session, never duplicates
+- **Optional timeout** — pass `idle_timeout_minutes` for auto-cleanup
+- **Always stop when done** — `brainstorm_stop_session()` frees port and cleans up
+
+---
 
 ## MCP Tools Reference
 
 ### brainstorm_start_session
 
-Start the server and open a browser window. If a session is already running, it reuses it — no duplicate browsers.
+Start the server and open a browser. Works with no arguments. Reuses existing session if one is running.
 
 ```
+// Simplest — no args needed:
+brainstorm_start_session()
+→ { url: "http://127.0.0.1:54321", session_dir: "..." }
+
+// With options:
 brainstorm_start_session({
-  project_dir: "/path/to/project",  // ALWAYS pass this — use the current working directory
+  project_dir: "/path/to/project",  // optional — use cwd for project-local storage
   open_browser: true,                // default: true
-  port: 0                            // default: random
+  idle_timeout_minutes: 0            // default: 0 = no timeout. Set 30 for auto-cleanup.
 })
-→ { url: "http://127.0.0.1:54321", session_dir: "..." }
 ```
 
-**Always pass `project_dir`** — this keeps session files with the project and avoids conflicts between agents. Without it, all sessions go to `/tmp/brainstorm-companion/` and may collide.
+**`project_dir` is optional.** Without it, sessions go to `/tmp/brainstorm-companion/`. Pass the current working directory for project-local storage or when multiple agents may run simultaneously.
 
-**Calling `brainstorm_start_session` multiple times is safe** — it returns the existing session URL if one is already running. You do NOT need to stop and restart to update content. Just call `brainstorm_push_screen` to update the same browser window.
-
-The server runs independently in the background with a 30-minute idle timeout.
+**Calling it multiple times is safe** — returns the existing session. Just call `brainstorm_push_screen` to update content.
 
 ### brainstorm_push_screen
 
@@ -94,6 +114,8 @@ brainstorm_stop_session({})
 
 Always call this when done brainstorming to free the port and clean up files.
 
+---
+
 ## HTML Content — What to Push
 
 You push HTML **fragments**, not full documents. The frame template wraps your content with theming (auto light/dark mode), a header, and a selection indicator bar.
@@ -271,6 +293,8 @@ Use `$$...$$` for display math. KaTeX CDN is injected automatically.
 <p>$$L = -\sum_{i} y_i \log(\hat{y}_i)$$</p>
 ```
 
+---
+
 ## CSS Classes Quick Reference
 
 | Class | Purpose |
@@ -300,6 +324,8 @@ Use `$$...$$` for display math. KaTeX CDN is injected automatically.
 | `.mock-button` | Styled button element |
 | `.mock-input` | Styled input field |
 
+---
+
 ## Event Types
 
 | Event | When | Key Fields |
@@ -311,6 +337,8 @@ Use `$$...$$` for display math. KaTeX CDN is injected automatically.
 
 All events include a `timestamp` field (Unix ms).
 
+---
+
 ## Workflow Patterns
 
 ### Single Decision
@@ -375,6 +403,8 @@ All events include a `timestamp` field (Unix ms).
 6. brainstorm_stop_session({})
 ```
 
+---
+
 ## Best Practices
 
 1. **Always pass `project_dir`** to `brainstorm_start_session` — avoids cross-agent conflicts

package/src/cli.js

@@ -14,30 +14,44 @@ const { SessionManager } = require('./session');
 const HELP = {
   main: `Usage: brainstorm-companion <command> [options]
 
-Opens a browser window for visual brainstorming alongside AI coding sessions.
-Agents push HTML content and users interact visually.
+Visual brainstorming tool. Opens a browser, you push HTML, users interact.
+
+Quickstart (3 commands):
+  brainstorm-companion start
+  brainstorm-companion push --html '<h2>Hello World</h2>'
+  brainstorm-companion stop
+
+How it works:
+  1. "start" opens a browser (reuses existing session if one is running)
+  2. "push" sends HTML to the browser — auto-reloads instantly, every time
+  3. "events" reads what the user clicked (choices, preferences)
+  4. "stop" ends the session
 
 Commands:
-  start    Start the brainstorm server and open browser
-  push     Push HTML content to the browser
-  events   Read user interaction events
+  start    Start server and open browser (or reuse existing session)
+  push     Push HTML content — browser auto-reloads each time
+  events   Read user interaction events (clicks, preferences)
   clear    Clear content or events
-  stop     Stop the server
-  status   Show server status
+  stop     Stop the server and clean up
+  status   Show session info (URL, uptime, slots, events)
 
 Global Options:
-  --project-dir <path>  Session storage location (default: /tmp/brainstorm-companion/)
-  --session <id>        Target a specific session (required for parallel instances)
+  --project-dir <path>  Session storage (default: /tmp/brainstorm-companion/)
+  --session <id>        Target a specific session (for parallel use)
   --mcp                 Run as MCP server (stdio JSON-RPC)
-  --help, -h            Show help (use "<command> --help" for command details)
+  --help, -h            Show help (use "<command> --help" for details)
 
-Examples:
-  brainstorm-companion start
-  brainstorm-companion push --html '<h2>Hello</h2>'
-  brainstorm-companion push mockup.html --slot a --label "Option A"
-  echo '<h2>World</h2>' | brainstorm-companion push -
-  brainstorm-companion events --format json
-  brainstorm-companion stop`,
+Comparison mode (side-by-side with tabs):
+  brainstorm-companion push --html '<h2>A</h2>' --slot a --label "Grid"
+  brainstorm-companion push --html '<h2>B</h2>' --slot b --label "List"
+
+Key concepts:
+  - No setup needed — "start" works with zero arguments
+  - Push HTML fragments (not full documents) — theming is automatic
+  - Use --slot a/b/c + --label for side-by-side comparison
+  - Add data-choice="val" onclick="toggleSelect(this)" for clickable elements
+  - class="mermaid", class="language-*", $$math$$ auto-detected
+  - Sessions persist until stopped — use --timeout <min> for auto-cleanup`,
 
   start: `Usage: brainstorm-companion start [options]
 
@@ -46,10 +60,13 @@ Start the brainstorm server and open a browser window.
 If a session is already running for this project, it reuses it (prints the
 existing URL). Use --new to force a separate session.
 
+Sessions persist until explicitly stopped — no timeout by default.
+
 Options:
   --project-dir <path>  Session storage location (default: /tmp/brainstorm-companion/)
   --port <number>       Bind to specific port (default: random ephemeral)
   --host <address>      Bind address (default: 127.0.0.1)
+  --timeout <minutes>   Auto-stop after N minutes of inactivity (default: none)
   --foreground          Run server in foreground (don't background)
   --no-open             Don't auto-open browser
   --new                 Force a new session even if one is already running
@@ -60,8 +77,9 @@ Output:
 
 Examples:
   brainstorm-companion start
-  brainstorm-companion start --project-dir ./my-project --no-open
-  brainstorm-companion start --new  # force separate parallel session`,
+  brainstorm-companion start --project-dir .
+  brainstorm-companion start --timeout 30       # auto-stop after 30min idle
+  brainstorm-companion start --new --no-open    # parallel session, no browser`,
 
   push: `Usage: brainstorm-companion push [<file|->] [options]
 
@@ -229,6 +247,7 @@ async function start(argv) {
       'project-dir': { type: 'string' },
       'port':        { type: 'string', default: '0' },
       'host':        { type: 'string', default: '127.0.0.1' },
+      'timeout':     { type: 'string' },
       'foreground':  { type: 'boolean', default: false },
       'no-open':     { type: 'boolean', default: false },
       'new':         { type: 'boolean', default: false },
@@ -239,6 +258,8 @@ async function start(argv) {
   const projectDir = values['project-dir'] || null;
   const host = values['host'];
   const port = parseInt(values['port'], 10) || 0;
+  const timeoutMin = values['timeout'] ? parseInt(values['timeout'], 10) : 0;
+  const idleTimeoutMs = timeoutMin > 0 ? timeoutMin * 60 * 1000 : 0;
   const foreground = values['foreground'];
   const noOpen = values['no-open'];
   const forceNew = values['new'];
@@ -267,6 +288,7 @@ async function start(argv) {
       host,
       port,
       ownerPid: process.pid,
+      idleTimeoutMs,
     });
 
     instance.server.once('listening', () => {
@@ -302,9 +324,7 @@ async function start(argv) {
         BRAINSTORM_DIR: sessionDir,
         BRAINSTORM_HOST: host,
         BRAINSTORM_PORT: String(port),
-        // No BRAINSTORM_OWNER_PID in background mode — the CLI process
-        // exits immediately, so the server must live independently.
-        // Server still has 30-minute idle timeout for cleanup.
+        BRAINSTORM_IDLE_TIMEOUT: String(idleTimeoutMs),
       },
     });
     child.unref();

package/src/mcp.js

@@ -50,7 +50,7 @@ class McpServer {
         this.respond(id, {
           protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: 'brainstorm-companion', version: '1.1.0' }
+          serverInfo: { name: 'brainstorm-companion', version: '2.0.1' }
         });
         break;
 
@@ -126,52 +126,107 @@ class McpServer {
     return [
       {
         name: 'brainstorm_start_session',
-        description: 'Start a brainstorm companion server and open a browser window for visual brainstorming. Returns the URL.',
+        description: `Start a visual brainstorming session. Opens a browser window where you push HTML and users interact visually.
+
+QUICKSTART — just these 3 calls:
+  brainstorm_start_session()                                          → opens browser
+  brainstorm_push_screen({ html: "<h2>Hello</h2><p>Content</p>" })   → shows content
+  brainstorm_stop_session()                                           → cleans up
+
+FULL WORKFLOW:
+1. Call brainstorm_start_session ONCE (no args required — works immediately). Returns { url, session_dir }.
+2. Call brainstorm_push_screen with HTML — browser auto-reloads. Call as many times as needed.
+3. Call brainstorm_read_events to get user clicks/preferences.
+4. Call brainstorm_stop_session when done.
+
+If a session is already running, this returns the existing URL (safe to call repeatedly).
+Sessions persist until explicitly stopped — no timeout by default.
+
+COMPARISON MODE: Push to slots a/b/c with labels for side-by-side view:
+  brainstorm_push_screen({ html: "...", slot: "a", label: "Option A" })
+  brainstorm_push_screen({ html: "...", slot: "b", label: "Option B" })
+
+CSS CLASSES (themed light/dark, push fragments not full docs):
+  .options + .option — Selectable cards with .letter (A/B/C) and .content
+  .cards + .card — Grid cards with .card-image and .card-body
+  .mockup — Browser-window container (.mockup-header + .mockup-body)
+  .split — Two-column layout | .pros-cons — Tradeoff grid (.pros/.cons)
+  .mock-nav, .mock-sidebar, .mock-content, .mock-button, .mock-input
+
+INTERACTIVE ELEMENTS:
+  Add data-choice="value" onclick="toggleSelect(this)" to capture clicks.
+  Example: <div class="option" data-choice="grid" onclick="toggleSelect(this)"><div class="letter">A</div><div class="content"><h3>Grid</h3></div></div>
+
+AUTO-DETECTED (CDN injected): class="mermaid" (diagrams), class="language-*" (syntax), $$...$$ (math)
+
+EVENTS: click (choice,text), preference (choice), tab-switch (slot), view-change (mode)
+
+RULES:
+  - NEVER restart to update — just push_screen again
+  - Push HTML fragments, not full <html> documents
+  - Tell user the browser is ready after pushing
+  - Give user time before reading events
+  - Always stop_session when done`,
         inputSchema: {
           type: 'object',
           properties: {
-            project_dir: { type: 'string', description: 'Project directory for session storage' },
-            port: { type: 'number', description: 'Port to bind to (default: random)' },
-            open_browser: { type: 'boolean', description: 'Whether to open the browser (default: true)' }
+            project_dir: { type: 'string', description: 'Project directory for session storage. Optional — defaults to /tmp/brainstorm-companion/. Pass cwd for project-local storage.' },
+            port: { type: 'number', description: 'Port to bind to (default: random ephemeral)' },
+            open_browser: { type: 'boolean', description: 'Open browser automatically (default: true)' },
+            idle_timeout_minutes: { type: 'number', description: 'Auto-stop after N minutes idle (default: 0 = no timeout)' }
           }
         }
       },
       {
         name: 'brainstorm_push_screen',
-        description: 'Push HTML content to the brainstorm browser window. Supports comparison mode via slots.',
+        description: `Push HTML content to the brainstorm browser window. The browser auto-reloads instantly — call repeatedly to update content without restarting the session.
+
+SINGLE SCREEN: Pass html only. Previous content is replaced.
+COMPARISON MODE: Pass html + slot (a/b/c) + label. Browser shows tabs, side-by-side view, and preference buttons.
+
+Push HTML fragments (not full <html> documents). The frame template adds theming, fonts, and scroll handling.
+
+Built-in CSS classes: .options/.option (selectable cards), .cards/.card (grid), .mockup (browser frame), .split (two-column), .pros-cons (tradeoffs).
+Interactive: Add data-choice="value" onclick="toggleSelect(this)" to capture clicks as events.
+Auto-detected: class="mermaid" (diagrams), class="language-*" (syntax highlighting), $$...$$ (math).`,
         inputSchema: {
           type: 'object',
           properties: {
-            html: { type: 'string', description: 'HTML content to display' },
-            slot: { type: 'string', description: 'Slot for comparison mode: a, b, or c' },
-            label: { type: 'string', description: 'Label for the slot' }
+            html: { type: 'string', description: 'HTML fragment to display (not a full document — the frame template wraps it)' },
+            slot: { type: 'string', description: 'Slot for comparison mode: a, b, or c. When used, browser shows tabbed comparison view.' },
+            label: { type: 'string', description: 'Display label for the slot tab (e.g., "Option A", "Minimal", "Dark Theme")' }
           },
           required: ['html']
         }
       },
       {
         name: 'brainstorm_read_events',
-        description: 'Read user interaction events (clicks, preferences) from the brainstorm browser.',
+        description: `Read user interaction events from the brainstorm browser. Returns { events: [...], count: N }.
+
+Event types: click (data-choice element clicked — fields: choice, text, id), preference (slot comparison pick — fields: choice), tab-switch (tab changed — fields: slot), view-change (view toggled — fields: mode). All events include timestamp.
+
+Use clear_after_read: true between brainstorming rounds to avoid reading stale events from the previous round.
+Give the user time to interact before reading — don't read immediately after pushing content.`,
         inputSchema: {
           type: 'object',
           properties: {
-            clear_after_read: { type: 'boolean', description: 'Clear events after reading (default: false)' }
+            clear_after_read: { type: 'boolean', description: 'Clear events after reading to avoid stale data in next round (default: false)' }
           }
         }
       },
       {
         name: 'brainstorm_clear_screen',
-        description: 'Clear content from the brainstorm browser window.',
+        description: 'Clear content from the brainstorm browser. Pass slot to clear a specific comparison slot, or omit to clear all content (all slots and screens). Useful between multi-round brainstorming to reset the view before pushing new content.',
         inputSchema: {
           type: 'object',
           properties: {
-            slot: { type: 'string', description: 'Clear specific slot (a, b, or c). Omit to clear all.' }
+            slot: { type: 'string', description: 'Clear specific slot (a, b, or c). Omit to clear all content.' }
           }
         }
       },
       {
         name: 'brainstorm_stop_session',
-        description: 'Stop the brainstorm companion server and clean up.',
+        description: 'Stop the brainstorm companion server and clean up all session files. Always call this when done brainstorming to free the port and remove temp files. Safe to call multiple times.',
         inputSchema: { type: 'object', properties: {} }
       }
     ];
@@ -187,7 +242,7 @@ class McpServer {
       return { url: this.serverInstance.url, session_dir: this.sessionDir };
     }
 
-    const { project_dir, port = 0, open_browser = true } = args;
+    const { project_dir, port = 0, open_browser = true, idle_timeout_minutes = 0 } = args;
 
     // Determine base directory and create session dir
     const baseDir = project_dir
@@ -203,6 +258,7 @@ class McpServer {
       host: '127.0.0.1',
       port: port || 0,
       ownerPid: process.pid,
+      idleTimeoutMs: idle_timeout_minutes > 0 ? idle_timeout_minutes * 60 * 1000 : 0,
       logFn: (...a) => console.error(...a),
     });
 

package/src/server.js

@@ -11,7 +11,10 @@ const { detectLibraries, buildInjections } = require('./content-detect');
 // Constants
 // ---------------------------------------------------------------------------
 
-const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+// Idle timeout is DISABLED by default (0 = no timeout).  Sessions stay alive
+// until explicitly stopped via `stop` / `brainstorm_stop_session`, or the
+// owner process exits.  Pass a positive `idleTimeoutMs` to override.
+const DEFAULT_IDLE_TIMEOUT_MS = 0;
 const OWNER_CHECK_INTERVAL_MS = 60 * 1000; // 60 seconds
 
 const MIME_TYPES = {
@@ -110,6 +113,7 @@ function startServer(config = {}) {
     host = '127.0.0.1',
     port: requestedPort = 0,
     ownerPid = null,
+    idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
     logFn = console.log,
   } = config;
 
@@ -141,9 +145,11 @@ function startServer(config = {}) {
 
   function resetIdleTimer() {
     if (idleTimer) clearTimeout(idleTimer);
+    // 0 or falsy = no idle timeout — session stays alive until explicitly stopped
+    if (!idleTimeoutMs) return;
     idleTimer = setTimeout(() => {
       shutdown('idle-timeout');
-    }, IDLE_TIMEOUT_MS);
+    }, idleTimeoutMs);
     // Don't block the event loop
     if (idleTimer.unref) idleTimer.unref();
   }
@@ -614,6 +620,7 @@ if (require.main === module) {
     screenDir,
     host: process.env.BRAINSTORM_HOST || '127.0.0.1',
     port: process.env.BRAINSTORM_PORT ? parseInt(process.env.BRAINSTORM_PORT, 10) : 0,
+    idleTimeoutMs: process.env.BRAINSTORM_IDLE_TIMEOUT ? parseInt(process.env.BRAINSTORM_IDLE_TIMEOUT, 10) : 0,
   });
   instance.server.on('listening', () => {
     console.log(JSON.stringify({ type: 'server-ready', url: instance.url }));