brainstorm-companion 2.0.0 → 2.0.3

package/README.md

@@ -4,7 +4,7 @@ Visual brainstorming tool for AI coding sessions. Opens a browser window where a
 
 Zero dependencies. Node.js >= 18 only.
 
-**Sessions are persistent** — they never time out. Sessions stay alive until you explicitly stop them with `stop` or `brainstorm_stop_session`.
+**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
 
@@ -39,34 +39,43 @@ Once configured, the agent has access to 5 tools: `brainstorm_start_session`, `b
 
 ## Complete Usage Guide
 
-### Quick Start (CLI)
+### Quick Start (CLI) — 3 commands, zero config
 
 ```bash
-# 1. Start server (opens browser automatically)
-brainstorm-companion start --project-dir .
+brainstorm-companion start                                    # opens browser
+brainstorm-companion push --html '<h2>Hello World</h2>'       # shows content
+brainstorm-companion stop                                     # cleans up
+```
+
+That's it. No arguments required. Now a fuller example:
+
+```bash
+# 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 — auto-isolates by working directory
+- `start` reuses an existing session — never opens duplicate browsers
+- `push` auto-reloads the browser every time — no restart or refresh needed
 
-### Quick Start (MCP / Agent)
+### Quick Start (MCP / Agent) — 3 calls, zero config
 
 ```
-1. brainstorm_start_session({ project_dir: "/path/to/project" })
+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" })
@@ -80,7 +89,7 @@ brainstorm-companion stop
 5. 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. Sessions never time out.
+**No arguments required.** Sessions auto-isolate by working directory — different projects never collide. Sessions persist until `brainstorm_stop_session()` — use `idle_timeout_minutes` for auto-cleanup.
 
 ---
 
@@ -221,7 +230,7 @@ graph TD
 
 | Tool | Description |
 |------|-------------|
-| `brainstorm_start_session` | Start server (or reuse existing). Returns URL. Always pass `project_dir`. |
+| `brainstorm_start_session` | Start server (or reuse existing). No args needed. Returns URL. |
 | `brainstorm_push_screen` | Push HTML content. Browser auto-reloads. Use `slot` + `label` for comparison. |
 | `brainstorm_read_events` | Read user interaction events. Option to clear after reading. |
 | `brainstorm_clear_screen` | Clear a specific slot or all content. |
@@ -234,7 +243,7 @@ graph TD
 ### Single Decision
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...options with data-choice..." })
 3. → Tell user to make their selection in the browser
 4. brainstorm_read_events({})
@@ -245,7 +254,7 @@ graph TD
 ### A/B/C Comparison
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 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
@@ -257,7 +266,7 @@ graph TD
 ### Multi-Round Brainstorming
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 
 // Round 1: Layout
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Grid" })
@@ -280,7 +289,7 @@ graph TD
 ### Progressive Refinement
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 
 // Show initial mockup
 2. brainstorm_push_screen({ html: "...v1 mockup..." })
@@ -318,10 +327,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`
 
@@ -373,26 +382,25 @@ Shows Session ID, URL, uptime, event count, and active slots.
 
 ## 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
+1. **Zero config** — `brainstorm_start_session()` and `brainstorm-companion start` work with no arguments; sessions auto-isolate by working directory
+3. **Never restart to update content** — just call `push_screen` / `push` again; the browser auto-reloads
+4. **One start per workflow** — `start` reuses the existing session automatically
+5. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+6. **Start with a heading** — `<h2>` describes what the user is looking at
+7. **Add a `.subtitle`** — describes the decision being made
+8. **One decision per screen** — don't combine unrelated choices
+9. **Use slot labels** — `label` makes comparison tabs readable
+10. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+11. **Tell the user to interact** — after pushing content, let them know the browser is ready
+12. **Read events after user has time** — don't immediately read; wait for user to respond
+13. **Use `--timeout <min>` for auto-cleanup** — or call `stop` / `brainstorm_stop_session` when done
 
 ## 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.
+- **Forgetting to stop** — always call `brainstorm_stop_session` / `stop` when done, or use `--timeout`.
 
 ## Author
 

package/package.json

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

package/skill/SKILL.md

@@ -5,24 +5,32 @@ description: Visual brainstorming companion — opens a browser window for compa
 
 # 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 output, simple data, or anything that works fine in the terminal.
+**Don't use** for plain text, simple data, or anything fine in the terminal.
 
 ## Session Lifecycle
 
-Sessions are **persistent** — they never time out. A session stays alive until explicitly stopped via `brainstorm_stop_session`. This means:
-- No 30-minute idle timeout
-- Sessions survive long user breaks
-- You only need to start once per workflow
-- Always clean up with `brainstorm_stop_session` when done
+- **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
 
 ---
 
@@ -30,20 +38,24 @@ Sessions are **persistent** — they never time out. A session stays alive until
 
 ### 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.
+**No arguments required.** Sessions are auto-isolated by working directory — different projects never collide, even without `project_dir`. Pass `project_dir` only if you want session files stored inside the project folder.
 
-**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.
+**Calling it multiple times is safe** — returns the existing session. Just call `brainstorm_push_screen` to update content.
 
 ### brainstorm_push_screen
 
@@ -332,7 +344,7 @@ All events include a `timestamp` field (Unix ms).
 ### Single Decision
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...options with data-choice..." })
 3. → Tell user to make their selection in the browser
 4. brainstorm_read_events({})
@@ -343,7 +355,7 @@ All events include a `timestamp` field (Unix ms).
 ### A/B/C Comparison
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 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
@@ -355,7 +367,7 @@ All events include a `timestamp` field (Unix ms).
 ### Multi-Round Brainstorming
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 
 // Round 1: Layout
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Grid" })
@@ -378,7 +390,7 @@ All events include a `timestamp` field (Unix ms).
 ### Progressive Refinement
 
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 
 // Show initial mockup
 2. brainstorm_push_screen({ html: "...v1 mockup..." })
@@ -395,23 +407,22 @@ All events include a `timestamp` field (Unix ms).
 
 ## 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
+1. **Zero config** — `brainstorm_start_session()` works with no arguments; isolation is automatic
+3. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
+4. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
+5. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+6. **Start with a heading** — `<h2>` describes what the user is looking at
+7. **Add a `.subtitle`** — describes the decision being made
+8. **One decision per screen** — don't combine unrelated choices
+9. **Use slot labels** — `label` makes comparison tabs readable
+10. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+11. **Tell the user to interact** — after pushing content, let them know the browser is ready
+12. **Read events after user has time** — don't immediately read; wait for user to respond
+13. **Clean up with `brainstorm_stop_session`** — or use `idle_timeout_minutes` for auto-cleanup
 
 ## 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.
+- **Forgetting to stop** — always call `brainstorm_stop_session` when done, or use `idle_timeout_minutes`.

package/skill/visual-companion.md

@@ -152,9 +152,9 @@ brainstorm_read_events()
 When running multi-round comparisons, clear events between rounds to avoid stale data:
 
 ```
-brainstorm_read_events()           // read current events
-brainstorm_clear_screen({ target: "events" })  // clear event queue
-brainstorm_push_screen({ html: "Round 2..." }) // push next round
+brainstorm_read_events({ clear_after_read: true })  // read and clear in one call
+brainstorm_clear_screen({})                          // clear content for next round
+brainstorm_push_screen({ html: "Round 2..." })       // push next round
 ```
 
 ### Interpreting Events
@@ -250,10 +250,10 @@ stateDiagram-v2
 
 This example shows a full workflow for choosing a navigation pattern for a new app.
 
-### Step 1: Present the question
+### Step 1: Start session and present the question
 
 ```
-brainstorm_start_session()
+brainstorm_start_session()  // no args needed — opens browser automatically
 
 brainstorm_push_screen({
   html: `

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,12 +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 are persistent — they never time out. Stop explicitly with "stop".
+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
@@ -62,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]
 
@@ -169,6 +185,18 @@ function printHelp(command) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+function printNextSteps() {
+  console.log(`
+Next steps:
+  brainstorm-companion push --html '<h2>Your content</h2>'   Push content to browser
+  brainstorm-companion push file.html --slot a --label "A"   Comparison mode
+  brainstorm-companion events                                 Read user interactions
+  brainstorm-companion stop                                   Stop when done
+
+Full docs: https://www.npmjs.com/package/brainstorm-companion
+Run: brainstorm-companion push --help    for all CSS classes and options`);
+}
+
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -231,6 +259,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 },
@@ -241,6 +270,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'];
@@ -253,6 +284,7 @@ async function start(argv) {
     const url = existing.serverInfo.url;
     console.log(`Server already running: ${url}`);
     console.log(`Session ID: ${existing.sessionId}`);
+    printNextSteps();
     if (!noOpen) {
       openBrowser(url);
     }
@@ -269,11 +301,13 @@ async function start(argv) {
       host,
       port,
       ownerPid: process.pid,
+      idleTimeoutMs,
     });
 
     instance.server.once('listening', () => {
       console.log(`Server started: ${instance.url}`);
       console.log(`Session ID: ${path.basename(sessionDir)}`);
+      printNextSteps();
       if (!noOpen) {
         openBrowser(instance.url);
       }
@@ -304,9 +338,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.
-        // No idle timeout — session persists until explicitly stopped.
+        BRAINSTORM_IDLE_TIMEOUT: String(idleTimeoutMs),
       },
     });
     child.unref();
@@ -320,6 +352,7 @@ async function start(argv) {
 
     console.log(`Server started: ${serverInfo.url}`);
     console.log(`Session ID: ${path.basename(sessionDir)}`);
+    printNextSteps();
 
     if (!noOpen) {
       openBrowser(serverInfo.url);

package/src/mcp.js

@@ -1,10 +1,15 @@
 'use strict';
 
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { exec } = require('node:child_process');
 const { startServer } = require('./server');
 
+function cwdHash() {
+  return crypto.createHash('md5').update(process.cwd()).digest('hex').slice(0, 8);
+}
+
 class McpServer {
   constructor() {
     this.sessionDir = null;     // absolute path once session is started
@@ -50,7 +55,7 @@ class McpServer {
         this.respond(id, {
           protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: 'brainstorm-companion', version: '2.0.0' }
+          serverInfo: { name: 'brainstorm-companion', version: '2.0.1' }
         });
         break;
 
@@ -126,67 +131,54 @@ class McpServer {
     return [
       {
         name: 'brainstorm_start_session',
-        description: `Start a visual brainstorming session — opens a browser window where you push HTML content and the user interacts visually. Returns the session URL. Sessions have NO timeout and persist until explicitly stopped.
+        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
 
-COMPLETE USAGE GUIDE:
-1. Call brainstorm_start_session ONCE with project_dir set to the current working directory. It returns { url, session_dir }.
-2. Call brainstorm_push_screen to send HTML content — the browser auto-reloads instantly. Call it as many times as needed to update content without restarting.
-3. Call brainstorm_read_events to get user clicks/preferences. Use clear_after_read:true between rounds.
-4. Call brainstorm_stop_session when done to free the port and clean 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.
 
-SINGLE SCREEN MODE: Push HTML fragments (not full documents). The frame template wraps content with themed CSS (auto light/dark mode).
+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 comparison with tabs and preference buttons.
+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" })
 
-BUILT-IN CSS CLASSES (themed light/dark):
-  .options + .option — Selectable vertical option cards with .letter (A/B/C badge) and .content
+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 with .mockup-header and .mockup-body
-  .split — Two-column 50/50 side-by-side layout
-  .pros-cons — Pros/cons grid with .pros (green) and .cons (red)
-  .placeholder — Dashed placeholder area
-  .mock-nav, .mock-sidebar, .mock-content, .mock-button, .mock-input — UI mockup blocks
-  .subtitle — Muted text below headings
-  .section — Block with top margin spacing
-  .label — Small uppercase badge
-
-MAKING ELEMENTS INTERACTIVE:
-  Add data-choice="value" and onclick="toggleSelect(this)" to any element to capture clicks as events.
-  For multi-select, add data-multiselect to the container.
+  .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 LIBRARIES (CDN injected automatically):
-  class="mermaid" → Mermaid diagrams (flowchart, sequence, class, state, ER, Gantt, pie)
-  class="language-*" → Prism.js syntax highlighting
-  $$...$$ or class="math" → KaTeX math rendering
-
-EVENT TYPES returned by brainstorm_read_events:
-  click — User clicked a [data-choice] element. Fields: choice, text, id, timestamp
-  preference — User picked a preferred slot in comparison mode. Fields: choice (slot id), timestamp
-  tab-switch — User switched tabs. Fields: slot, timestamp
-  view-change — User toggled view mode. Fields: mode, timestamp
-
-WORKFLOW PATTERNS:
-  Single Decision: start → push (options with data-choice) → tell user to select → read_events → use choice → stop
-  A/B/C Comparison: start → push slot a → push slot b → tell user to compare → read_events → look for preference → stop
-  Multi-Round: start → push round 1 → read_events(clear_after_read:true) → clear_screen → push round 2 → read_events → stop
-  Progressive Refinement: start → push v1 → get feedback → push v2 (same browser updates) → iterate → stop
-
-BEST PRACTICES:
-  - ALWAYS pass project_dir (use cwd) to avoid cross-agent conflicts
-  - NEVER restart to update content — just call push_screen again
-  - Push HTML fragments, not full documents
-  - Start with <h2> heading + .subtitle describing the decision
-  - One decision per screen
-  - Tell the user the browser is ready after pushing
+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 call stop_session when done`,
+  - Always stop_session when done`,
         inputSchema: {
           type: 'object',
           properties: {
-            project_dir: { type: 'string', description: 'Project directory for session storage (ALWAYS pass this — use cwd)' },
+            project_dir: { type: 'string', description: 'Optional. Stores session files under <dir>/.superpowers/brainstorm/. If omitted, auto-isolates by working directory.' },
             port: { type: 'number', description: 'Port to bind to (default: random ephemeral)' },
-            open_browser: { type: 'boolean', description: 'Whether to open the browser automatically (default: true)' }
+            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)' }
           }
         }
       },
@@ -255,12 +247,12 @@ Give the user time to interact before reading — don't read immediately after p
       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
       ? path.join(project_dir, '.superpowers', 'brainstorm')
-      : '/tmp/brainstorm-companion';
+      : path.join('/tmp', 'brainstorm-companion', cwdHash());
     const sessionId = `${process.pid}-${Date.now()}`;
     const sessionDir = path.join(baseDir, sessionId);
     fs.mkdirSync(sessionDir, { recursive: true });
@@ -271,6 +263,7 @@ Give the user time to interact before reading — don't read immediately after p
       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/session.js

@@ -1,13 +1,18 @@
 'use strict';
 
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 
+function cwdHash() {
+  return crypto.createHash('md5').update(process.cwd()).digest('hex').slice(0, 8);
+}
+
 class SessionManager {
   constructor(projectDir, targetSessionId) {
     this.baseDir = projectDir
-      ? `${projectDir}/.superpowers/brainstorm/`
-      : `/tmp/brainstorm-companion/`;
+      ? path.join(projectDir, '.superpowers', 'brainstorm')
+      : path.join('/tmp', 'brainstorm-companion', cwdHash());
     this.targetSessionId = targetSessionId || null;
   }