brainstorm-companion 2.0.0 → 2.0.1

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,44 @@ 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 (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
 
-### 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 +90,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.** `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.
 
 ---
 
@@ -318,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`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainstorm-companion",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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.
+**`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.
+**Calling it multiple times is safe** — returns the existing session. Just call `brainstorm_push_screen` to update content.
 
 ### brainstorm_push_screen
 

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]
 
@@ -231,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 },
@@ -241,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'];
@@ -269,6 +288,7 @@ async function start(argv) {
       host,
       port,
       ownerPid: process.pid,
+      idleTimeoutMs,
     });
 
     instance.server.once('listening', () => {
@@ -304,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.
-        // No idle timeout — session persists until explicitly stopped.
+        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: '2.0.0' }
+          serverInfo: { name: 'brainstorm-companion', version: '2.0.1' }
         });
         break;
 
@@ -126,67 +126,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.
 
-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.
+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
 
-SINGLE SCREEN MODE: Push HTML fragments (not full documents). The frame template wraps content with themed CSS (auto light/dark mode).
+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.
 
-COMPARISON MODE: Push to slots a/b/c with labels for side-by-side comparison with tabs and preference buttons.
+If a session is already running, this returns the existing URL (safe to call repeatedly).
+Sessions persist until explicitly stopped — no timeout by default.
 
-BUILT-IN CSS CLASSES (themed light/dark):
-  .options + .option — Selectable vertical option cards with .letter (A/B/C badge) and .content
+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 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: '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: '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,7 +242,7 @@ 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
@@ -271,6 +258,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),
     });