brainstorm-companion 2.0.1 → 2.0.4

package/README.md

@@ -68,10 +68,9 @@ brainstorm-companion stop
 ```
 
 **Key behaviors:**
-- `start` with no args works immediately (stores in `/tmp/brainstorm-companion/`)
+- `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
-- Add `--project-dir .` for project-local storage
 
 ### Quick Start (MCP / Agent) — 3 calls, zero config
 
@@ -90,7 +89,7 @@ brainstorm-companion stop
 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.
+**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.
 
 ---
 
@@ -231,9 +230,9 @@ 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_read_events` | Read user interactions. Use `wait_seconds: 120` to get clicks automatically. Never blocks other tools. |
 | `brainstorm_clear_screen` | Clear a specific slot or all content. |
 | `brainstorm_stop_session` | Stop server and clean up session files. |
 
@@ -244,30 +243,28 @@ 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({})
-5. → Use the choice to proceed
-6. brainstorm_stop_session({})
+3. brainstorm_read_events({ wait_seconds: 120 })   // returns when user clicks
+4. → User's choice arrives automatically
+5. brainstorm_stop_session()
 ```
 
 ### 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
-5. brainstorm_read_events({})
-6. → Look for { type: "preference", choice: "a"|"b" }
-7. brainstorm_stop_session({})
+4. brainstorm_read_events({ wait_seconds: 120 })   // returns when user picks
+5. → { type: "preference", choice: "a"|"b" }
+6. brainstorm_stop_session()
 ```
 
 ### 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" })
@@ -290,7 +287,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..." })
@@ -344,10 +341,10 @@ Three input methods: file path, stdin (`-`), or inline (`--html`). Use `--slot`
 ### `events`
 
 ```
-brainstorm-companion events [--format json|text] [--clear]
+brainstorm-companion events [--wait <seconds>] [--format json|text] [--clear]
 ```
 
-Returns JSON array of user interaction events. Event types: `click`, `preference`, `tab-switch`, `view-change`.
+Use `--wait 120` to wait for the user's click and return it automatically. Without `--wait`, returns immediately. Never blocks other operations. Event types: `click`, `preference`, `tab-switch`, `view-change`.
 
 ### `clear`
 
@@ -377,32 +374,31 @@ Shows Session ID, URL, uptime, event count, and active slots.
 2. `push` writes HTML files to the session directory; the file watcher detects changes and broadcasts reload to the browser via WebSocket
 3. The browser auto-reloads and renders content in a themed frame with click capture on `[data-choice]` elements
 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
+5. `events` reads the JSONL file and returns structured JSON; with `wait_seconds`, it waits for the user's click and returns it automatically (non-blocking — other tools still work)
 6. Each session is fully isolated: own port, own directory, own event log
 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
+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.1",
+  "version": "2.0.4",
   "description": "AI-assisted visual brainstorming companion",
   "type": "commonjs",
   "license": "MIT",

package/skill/SKILL.md

@@ -5,15 +5,16 @@ description: Visual brainstorming companion — opens a browser window for compa
 
 # Brainstorm Companion — Complete Agent Reference
 
-## Quickstart (3 calls, no setup)
+## Quickstart (4 calls, no setup, user's choice comes back automatically)
 
 ```
 brainstorm_start_session()
-brainstorm_push_screen({ html: "<h2>Hello World</h2><p>Your content here</p>" })
+brainstorm_push_screen({ html: "<h2>Pick a layout</h2><div class='options'><div class='option' data-choice='grid' onclick='toggleSelect(this)'><div class='letter'>A</div><div class='content'><h3>Grid</h3></div></div><div class='option' data-choice='list' onclick='toggleSelect(this)'><div class='letter'>B</div><div class='content'><h3>List</h3></div></div></div>" })
+brainstorm_read_events({ wait_seconds: 120 })   // ← blocks until user clicks, returns their choice
 brainstorm_stop_session()
 ```
 
-That's it. No arguments required. A browser opens, your HTML appears, and cleanup happens automatically.
+No arguments required. Browser opens, content appears, user clicks, event returns to you automatically.
 
 ## When to Use
 
@@ -53,7 +54,7 @@ brainstorm_start_session({
 })
 ```
 
-**`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.
+**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 it multiple times is safe** — returns the existing session. Just call `brainstorm_push_screen` to update content.
 
@@ -85,14 +86,22 @@ When slots are used, the browser switches to comparison mode with:
 
 ### brainstorm_read_events
 
-Read user interaction events (clicks, preferences).
+Read user interaction events. **Use `wait_seconds` to get the user's click automatically** — returns as soon as the user interacts.
+
+**Non-blocking:** If you call any other tool (push, clear, stop) while waiting, the wait is cancelled immediately and the new tool runs. You can always push updated content or stop the session — `wait_seconds` never blocks anything.
 
 ```
-brainstorm_read_events({ clear_after_read: false })
+// Recommended — waits for user's click, returns it automatically:
+brainstorm_read_events({ wait_seconds: 120 })
+→ { events: [{ type: "click", choice: "grid", text: "Grid Layout" }], count: 1 }
+
+// Immediate (returns whatever is available now):
+brainstorm_read_events({})
 → { events: [...], count: N }
 ```
 
 Set `clear_after_read: true` between brainstorming rounds to avoid stale events.
+If the user never clicks, returns `{ events: [], count: 0 }` after the timeout.
 
 ### brainstorm_clear_screen
 
@@ -344,43 +353,41 @@ 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({})
-5. → Use the choice to proceed
-6. brainstorm_stop_session({})
+3. brainstorm_read_events({ wait_seconds: 120 })   // blocks until user clicks
+4. → User's choice arrives automatically — use it to proceed
+5. brainstorm_stop_session()
 ```
 
 ### 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
-5. brainstorm_read_events({})
-6. → Look for { type: "preference", choice: "a"|"b" }
-7. brainstorm_stop_session({})
+4. brainstorm_read_events({ wait_seconds: 120 })   // blocks until user picks preference
+5. → Look for { type: "preference", choice: "a"|"b" }
+6. brainstorm_stop_session()
 ```
 
 ### 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" })
 3. brainstorm_push_screen({ html: "...", slot: "b", label: "List" })
-4. brainstorm_read_events({ clear_after_read: true })
-5. → User chose "Grid"
+4. brainstorm_read_events({ wait_seconds: 120, clear_after_read: true })
+5. → User chose "Grid" (returned automatically)
 
 // 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"
+9. brainstorm_read_events({ wait_seconds: 120, clear_after_read: true })
+10. → User chose "Dark" (returned automatically)
 
 // Show final summary
 11. brainstorm_push_screen({ html: "<h2>Decisions: Grid + Dark</h2>..." })
@@ -390,7 +397,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..." })
@@ -407,23 +414,32 @@ 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`.
+
+---
+
+## Related Documentation
+
+For deeper reference beyond this skill file:
+
+- **[visual-companion.md](./visual-companion.md)** — Detailed usage guide: complete CSS class descriptions, all auto-detected library examples (Mermaid flowcharts/sequence/state, Prism languages, KaTeX math), event handling patterns, content design best practices, and a full multi-step brainstorming workflow walkthrough.
+- **[README](https://www.npmjs.com/package/brainstorm-companion)** — Install instructions, CLI reference with all flags, MCP setup for Claude Code, parallel instance usage, and architecture overview.
+- **CLI help** — Run `brainstorm-companion --help` or `brainstorm-companion <command> --help` for per-command documentation with examples and CSS class reference.

package/skill/visual-companion.md

@@ -2,6 +2,8 @@
 
 This guide covers advanced usage patterns for the Brainstorm Companion tool.
 
+**See also:** [SKILL.md](./SKILL.md) for the complete agent reference (quickstart, MCP tools, workflow patterns, best practices). [README](https://www.npmjs.com/package/brainstorm-companion) for install, CLI reference, and MCP setup.
+
 ---
 
 ## When to Use Browser vs Terminal
@@ -137,14 +139,21 @@ Inline math with `$...$`, display math with `$$...$$`:
 
 ## Event Handling Patterns
 
-### Basic Polling
+### Automatic (Recommended)
 
-After pushing content, give the user time to interact, then read events:
+Use `wait_seconds` — the user's click comes back automatically. Non-blocking: you can still push content or stop the session while waiting.
 
 ```
 brainstorm_push_screen({ html: "..." })
-// ... wait for user to interact ...
-brainstorm_read_events()
+brainstorm_read_events({ wait_seconds: 120 })  // returns when user clicks
+```
+
+### Immediate
+
+Returns whatever events exist right now, without waiting:
+
+```
+brainstorm_read_events({})
 ```
 
 ### Clearing Events Between Rounds
@@ -152,9 +161,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({ wait_seconds: 120, clear_after_read: true })  // wait + clear
+brainstorm_clear_screen({})                          // clear content for next round
+brainstorm_push_screen({ html: "Round 2..." })       // push next round
 ```
 
 ### Interpreting Events
@@ -250,10 +259,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

@@ -122,6 +122,7 @@ Read user interaction events from the active brainstorm session.
 Events are generated when users click interactive elements in the browser.
 
 Options:
+  --wait <seconds>      Wait for an event to arrive (returns immediately when one does)
   --format <json|text>  Output format (default: json)
   --clear               Clear events after reading
   --project-dir <path>  Session storage location
@@ -134,9 +135,9 @@ Event Types:
   view-change User toggled view mode in comparison mode
 
 Examples:
-  brainstorm-companion events
-  brainstorm-companion events --format text --clear
-  brainstorm-companion events --session 1234-567890`,
+  brainstorm-companion events --wait 120           # wait for user click, return it
+  brainstorm-companion events                       # return events immediately
+  brainstorm-companion events --format text --clear`,
 
   clear: `Usage: brainstorm-companion clear [options]
 
@@ -185,6 +186,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));
 }
@@ -272,6 +285,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);
     }
@@ -294,6 +308,7 @@ async function start(argv) {
     instance.server.once('listening', () => {
       console.log(`Server started: ${instance.url}`);
       console.log(`Session ID: ${path.basename(sessionDir)}`);
+      printNextSteps();
       if (!noOpen) {
         openBrowser(instance.url);
       }
@@ -338,6 +353,7 @@ async function start(argv) {
 
     console.log(`Server started: ${serverInfo.url}`);
     console.log(`Session ID: ${path.basename(sessionDir)}`);
+    printNextSteps();
 
     if (!noOpen) {
       openBrowser(serverInfo.url);
@@ -399,12 +415,13 @@ async function push(argv) {
 // Command: events
 // ---------------------------------------------------------------------------
 
-function events(argv) {
+async function events(argv) {
   const { values } = parseArgs({
     args: argv,
     options: {
       'project-dir': { type: 'string' },
       'session':     { type: 'string' },
+      'wait':        { type: 'string' },
       'format':      { type: 'string', default: 'json' },
       'clear':       { type: 'boolean', default: false },
     },
@@ -413,11 +430,28 @@ function events(argv) {
 
   const projectDir = values['project-dir'] || null;
   const sessionId = values['session'] || null;
+  const waitSeconds = values['wait'] ? parseInt(values['wait'], 10) : 0;
   const format = values['format'];
   const doClear = values['clear'];
 
-  const { session } = getActiveOrExit(projectDir, sessionId);
-  const eventList = session.readEvents();
+  const { session, active } = getActiveOrExit(projectDir, sessionId);
+
+  let eventList;
+  if (waitSeconds > 0) {
+    // Poll until events arrive or timeout
+    const eventsPath = path.join(active.sessionDir, '.events');
+    const deadlineMs = waitSeconds * 1000;
+    const pollMs = 500;
+    const startTime = Date.now();
+    eventList = [];
+    while (Date.now() - startTime < deadlineMs) {
+      eventList = session.readEvents();
+      if (eventList.length > 0) break;
+      await sleep(pollMs);
+    }
+  } else {
+    eventList = session.readEvents();
+  }
 
   if (format === 'text') {
     if (eventList.length === 0) {
@@ -429,7 +463,6 @@ function events(argv) {
       }
     }
   } else {
-    // Default: json
     console.log(JSON.stringify(eventList, null, 2));
   }
 

package/src/mcp.js

@@ -1,16 +1,22 @@
 '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
     this.serverInstance = null; // startServer() result
     this.buffer = '';           // stdin buffer
     this._pending = null;       // Promise of the in-flight tool call (for serialization)
+    this._cancelWait = null;    // Cancel function for pending read_events wait
   }
 
   start() {
@@ -75,51 +81,60 @@ class McpServer {
   }
 
   handleToolCall(id, params) {
-    // Serialize tool calls: each waits for the previous to finish. This ensures
-    // that brainstorm_start_session (async) responds before subsequent tools run.
-    const prev = this._pending || Promise.resolve();
-    const next = prev.then(() => {
-      const { name, arguments: args = {} } = params || {};
-      let resultOrPromise;
-      try {
-        switch (name) {
-          case 'brainstorm_start_session': resultOrPromise = this.toolStartSession(args); break;
-          case 'brainstorm_push_screen':  resultOrPromise = this.toolPushScreen(args);  break;
-          case 'brainstorm_read_events':  resultOrPromise = this.toolReadEvents(args);  break;
-          case 'brainstorm_clear_screen': resultOrPromise = this.toolClearScreen(args); break;
-          case 'brainstorm_stop_session': resultOrPromise = this.toolStopSession(args); break;
-          default:
-            this.respondError(id, -32602, `Unknown tool: ${name}`);
-            return;
-        }
-      } catch (err) {
-        this.respond(id, {
-          content: [{ type: 'text', text: `Error: ${err.message}` }],
-          isError: true
-        });
-        return;
-      }
+    const { name, arguments: args = {} } = params || {};
 
-      const sendResult = (result) => {
-        this.respond(id, {
-          content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }]
-        });
-      };
-      const sendError = (err) => {
-        this.respond(id, {
-          content: [{ type: 'text', text: `Error: ${err.message}` }],
-          isError: true
-        });
-      };
+    // Cancel any pending read_events wait so it doesn't block new calls
+    if (name !== 'brainstorm_read_events' && this._cancelWait) {
+      this._cancelWait();
+      this._cancelWait = null;
+    }
 
-      if (resultOrPromise && typeof resultOrPromise.then === 'function') {
-        return resultOrPromise.then(sendResult).catch(sendError);
+    const sendResult = (result) => {
+      this.respond(id, {
+        content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }]
+      });
+    };
+    const sendError = (err) => {
+      this.respond(id, {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true
+      });
+    };
+
+    // Start session is async (waits for 'listening') — serialize it
+    if (name === 'brainstorm_start_session') {
+      const prev = this._pending || Promise.resolve();
+      const next = prev.then(() => {
+        try {
+          const result = this.toolStartSession(args);
+          if (result && typeof result.then === 'function') {
+            return result.then(sendResult).catch(sendError);
+          }
+          sendResult(result);
+        } catch (err) { sendError(err); }
+      });
+      this._pending = next.catch(() => {});
+      return;
+    }
+
+    // All other tools run immediately (no serialization)
+    try {
+      let result;
+      switch (name) {
+        case 'brainstorm_push_screen':  result = this.toolPushScreen(args);  break;
+        case 'brainstorm_read_events':  result = this.toolReadEvents(args);  break;
+        case 'brainstorm_clear_screen': result = this.toolClearScreen(args); break;
+        case 'brainstorm_stop_session': result = this.toolStopSession(args); break;
+        default:
+          this.respondError(id, -32602, `Unknown tool: ${name}`);
+          return;
+      }
+      if (result && typeof result.then === 'function') {
+        result.then(sendResult).catch(sendError);
       } else {
-        sendResult(resultOrPromise);
+        sendResult(result);
       }
-    });
-    // Track the tail of the chain; errors in earlier steps shouldn't block later ones
-    this._pending = next.catch(() => {});
+    } catch (err) { sendError(err); }
   }
 
   getToolDefinitions() {
@@ -128,19 +143,21 @@ class McpServer {
         name: 'brainstorm_start_session',
         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
+QUICKSTART — show content and get user's choice:
+  brainstorm_start_session()
+  brainstorm_push_screen({ html: "<h2>Pick one</h2>..." })
+  brainstorm_read_events({ wait_seconds: 120 })    → blocks until user clicks, returns choice
+  brainstorm_stop_session()
 
 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.
+1. brainstorm_start_session() — no args needed. Returns { url, session_dir }.
+2. brainstorm_push_screen({ html }) — browser auto-reloads. Call as many times as needed.
+3. brainstorm_read_events({ wait_seconds: 120 }) — BLOCKS until user interacts, then returns events automatically. No polling needed.
+4. brainstorm_stop_session() — clean up.
+
+KEY: Use wait_seconds in read_events so the user's click comes back to you automatically. No need to ask the user "what did you pick?" — the event arrives on its own.
 
-If a session is already running, this returns the existing URL (safe to call repeatedly).
-Sessions persist until explicitly stopped — no timeout by default.
+Safe to call start repeatedly — reuses existing session. Sessions persist until stopped.
 
 COMPARISON MODE: Push to slots a/b/c with labels for side-by-side view:
   brainstorm_push_screen({ html: "...", slot: "a", label: "Option A" })
@@ -162,15 +179,15 @@ AUTO-DETECTED (CDN injected): class="mermaid" (diagrams), class="language-*" (sy
 EVENTS: click (choice,text), preference (choice), tab-switch (slot), view-change (mode)
 
 RULES:
+  - Use wait_seconds in read_events — the user's choice comes back automatically
   - 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. Optional — defaults to /tmp/brainstorm-companion/. Pass cwd for project-local storage.' },
+            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: 'Open browser automatically (default: true)' },
             idle_timeout_minutes: { type: 'number', description: 'Auto-stop after N minutes idle (default: 0 = no timeout)' }
@@ -203,14 +220,16 @@ Auto-detected: class="mermaid" (diagrams), class="language-*" (syntax highlighti
         name: 'brainstorm_read_events',
         description: `Read user interaction events from the brainstorm browser. Returns { events: [...], count: N }.
 
+RECOMMENDED: Use wait_seconds (e.g. 120) to block until the user clicks something. This way you get the result automatically — no need to poll or ask the user to confirm.
+
 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.`,
+Use clear_after_read: true between brainstorming rounds to avoid stale events.`,
         inputSchema: {
           type: 'object',
           properties: {
-            clear_after_read: { type: 'boolean', description: 'Clear events after reading to avoid stale data in next round (default: false)' }
+            wait_seconds: { type: 'number', description: 'Wait up to N seconds for an event to arrive before returning. Recommended: 120. If 0 or omitted, returns immediately.' },
+            clear_after_read: { type: 'boolean', description: 'Clear events after reading (default: false)' }
           }
         }
       },
@@ -247,7 +266,7 @@ Give the user time to interact before reading — don't read immediately after p
     // 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 });
@@ -314,24 +333,63 @@ Give the user time to interact before reading — don't read immediately after p
     if (!this.sessionDir) {
       return { events: [], count: 0 };
     }
-    const { clear_after_read = false } = args;
+    const { wait_seconds = 0, clear_after_read = false } = args;
     const eventsPath = path.join(this.sessionDir, '.events');
-    let events = [];
-    if (fs.existsSync(eventsPath)) {
+
+    const readEvents = () => {
+      if (!fs.existsSync(eventsPath)) return [];
       try {
         const raw = fs.readFileSync(eventsPath, 'utf8');
-        events = raw
-          .split('\n')
-          .filter(line => line.trim())
-          .map(line => JSON.parse(line));
+        return raw.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
       } catch {
-        events = [];
+        return [];
       }
+    };
+
+    const finish = (events) => {
+      if (clear_after_read) {
+        try { fs.writeFileSync(eventsPath, '', 'utf8'); } catch { /* ignore */ }
+      }
+      return { events, count: events.length };
+    };
+
+    // Immediate mode
+    if (!wait_seconds || wait_seconds <= 0) {
+      return finish(readEvents());
     }
-    if (clear_after_read) {
-      try { fs.writeFileSync(eventsPath, '', 'utf8'); } catch { /* ignore */ }
-    }
-    return { events, count: events.length };
+
+    // Wait mode — poll every 500ms until events arrive, cancelled, or timeout
+    const deadlineMs = wait_seconds * 1000;
+    const pollMs = 500;
+    return new Promise((resolve) => {
+      let cancelled = false;
+      let timer = null;
+
+      // Register cancel so other tool calls can interrupt this wait
+      this._cancelWait = () => {
+        cancelled = true;
+        if (timer) clearTimeout(timer);
+        resolve(finish(readEvents())); // return whatever we have so far
+      };
+
+      const startTime = Date.now();
+      const check = () => {
+        if (cancelled) return;
+        const events = readEvents();
+        if (events.length > 0) {
+          this._cancelWait = null;
+          resolve(finish(events));
+          return;
+        }
+        if (Date.now() - startTime >= deadlineMs) {
+          this._cancelWait = null;
+          resolve(finish([]));
+          return;
+        }
+        timer = setTimeout(check, pollMs);
+      };
+      check();
+    });
   }
 
   toolClearScreen(args) {

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;
   }