brainstorm-companion 1.1.3 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Maya / Foresight AI Partners
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,17 +26,22 @@ brainstorm-companion start --project-dir .
 # → Server started: http://127.0.0.1:54321
 # → Session ID: 1234-1700000000000
 
-# 2. Push content
+# 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>'
 
-# 3. Read user's selection
+# 3. Update content — same browser, no restart needed
+brainstorm-companion push --html '<h2>Updated Layout</h2><p>Refined version based on feedback</p>'
+
+# 4. Read user's selection
 brainstorm-companion events
 # → [{"type":"click","choice":"grid","text":"A Grid Layout Cards in a responsive grid","timestamp":1700000001234}]
 
-# 4. Stop when done
+# 5. Stop when 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.
+
 ### Side-by-Side Comparison
 
 Push to named slots for comparison mode with tabs and preference selection:
@@ -49,6 +54,24 @@ brainstorm-companion push --html '<h2>Hybrid</h2><p>Collapsible sidebar + top ba
 
 Browser shows all three side-by-side with tabs, keyboard shortcuts (1/2/3), and a preference bar.
 
+### Updating Content In-Place
+
+The browser auto-reloads whenever content is pushed. No need to restart the session or manually refresh:
+
+```bash
+# Initial mockup
+brainstorm-companion push --html '<h2>v1</h2><p>First draft</p>'
+# → Browser shows v1
+
+# Refined mockup — same browser window updates automatically
+brainstorm-companion push --html '<h2>v2</h2><p>Improved based on feedback</p>'
+# → Browser shows v2
+
+# Update a single slot in comparison mode
+brainstorm-companion push --html '<h2>Updated Option A</h2>' --slot a --label "Revised"
+# → Only slot A updates, others stay
+```
+
 ### From Files or Stdin
 
 ```bash
@@ -59,15 +82,15 @@ cat design.html | brainstorm-companion push -
 
 ### Parallel Instances
 
-Multiple agents can run simultaneously on the same project without interference:
+Multiple agents can run simultaneously on the same project. Use `--new` to force a separate session:
 
 ```bash
 # Agent A
-brainstorm-companion start --project-dir .
+brainstorm-companion start --project-dir . --new
 # → Session ID: 1111-000
 
 # Agent B
-brainstorm-companion start --project-dir .
+brainstorm-companion start --project-dir . --new
 # → Session ID: 2222-000
 
 # Each targets its own session
@@ -77,6 +100,8 @@ brainstorm-companion events --session 1111-000
 brainstorm-companion stop --session 1111-000
 ```
 
+Without `--new`, `start` reuses the existing session (the default for single-agent use).
+
 ## MCP Server
 
 Brainstorm Companion runs as an [MCP](https://modelcontextprotocol.io) server for direct integration with AI coding tools.
@@ -100,8 +125,8 @@ Add to `~/.claude/settings.json`:
 
 | Tool | Description |
 |------|-------------|
-| `brainstorm_start_session` | Start server and open browser. Returns URL and session directory. |
-| `brainstorm_push_screen` | Push HTML content. Use `slot` + `label` for comparison mode. |
+| `brainstorm_start_session` | Start server (or reuse existing). Returns URL. Always pass `project_dir`. |
+| `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. |
 | `brainstorm_stop_session` | Stop server and clean up session files. |
@@ -118,17 +143,22 @@ Add to `~/.claude/settings.json`:
 3. brainstorm_read_events({})
    → { events: [{ type: "preference", choice: "a" }], count: 1 }
 
-4. brainstorm_stop_session({})
+   // Update content — same browser, no restart
+4. brainstorm_push_screen({ html: "<h2>Revised A</h2>...", slot: "a", label: "Minimal v2" })
+
+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.
+
 ## CLI Reference
 
 ```
 brainstorm-companion <command> [options]
 
 Commands:
-  start    Start the brainstorm server and open browser
-  push     Push HTML content to the browser
+  start    Start the brainstorm server (reuses existing session by default)
+  push     Push HTML content to the browser (auto-reloads)
   events   Read user interaction events
   clear    Clear content or events
   stop     Stop the server
@@ -144,10 +174,10 @@ Global Options:
 ### `start`
 
 ```
-brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--foreground] [--no-open]
+brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--foreground] [--no-open] [--new]
 ```
 
-Creates a new session, starts the HTTP+WebSocket server on a random port, and opens the default browser. Prints the URL and Session ID.
+If a session is already running, prints its URL and reuses it. Use `--new` to force a separate parallel session.
 
 ### `push`
 
@@ -155,7 +185,7 @@ Creates a new session, starts the HTTP+WebSocket server on a random port, and op
 brainstorm-companion push [<file|->] [--html <content>] [--slot a|b|c] [--label <name>]
 ```
 
-Three input methods: file path, stdin (`-`), or inline (`--html`). Use `--slot` for comparison mode.
+Three input methods: file path, stdin (`-`), or inline (`--html`). Use `--slot` for comparison mode. The browser auto-reloads on every push — no restart needed.
 
 ### `events`
 
@@ -240,13 +270,18 @@ graph TD
 
 ## How It Works
 
-1. `start` creates an isolated session directory and spawns an HTTP+WebSocket server on a random port
-2. `push` writes HTML files to the session directory; the file watcher detects changes and broadcasts reload to connected browsers via WebSocket
-3. The browser renders content in a themed frame with click capture on `[data-choice]` elements
+1. `start` checks for an existing active session — reuses it if found, otherwise creates a new one with its own port and directory
+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
 6. Each session is fully isolated: own port, own directory, own event log
+7. Server runs independently with a 30-minute idle timeout; `stop` cleans up immediately
+
+## Author
+
+Created by [Rafael Maya](https://github.com/rafaforesightai) at [Foresight AI Partners](https://github.com/rafaforesightai).
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "brainstorm-companion",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "AI-assisted visual brainstorming companion",
   "type": "commonjs",
   "license": "MIT",
+  "author": "Rafael Maya <rafa@foresightaipartners.com> (https://github.com/rafaforesightai)",
   "keywords": [
     "brainstorm",
     "visual",

package/skill/SKILL.md

@@ -20,7 +20,7 @@ Use this tool when you need to:
 
 ### brainstorm_start_session
 
-Start the server and open a browser window.
+Start the server and open a browser window. If a session is already running, it reuses it — no duplicate browsers.
 
 ```
 brainstorm_start_session({
@@ -33,11 +33,13 @@ brainstorm_start_session({
 
 **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.
 
-The server runs independently in the background with a 30-minute idle timeout. It survives the calling process exiting.
+**Calling `brainstorm_start_session` multiple times is safe** — it returns the existing session URL if one is already running. You do NOT need to stop and restart to update content. Just call `brainstorm_push_screen` to update the same browser window.
+
+The server runs independently in the background with a 30-minute idle timeout.
 
 ### brainstorm_push_screen
 
-Push HTML content to the browser. The browser auto-reloads — no manual refresh needed.
+Push HTML content to the browser. **The browser auto-reloads instantly** — no manual refresh needed. Call this repeatedly to update the same browser window with new content. You do NOT need to restart the session.
 
 **Single screen mode:**
 ```
@@ -376,12 +378,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. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
-3. **Start with a heading** — `<h2>` describes what the user is looking at
-4. **Add a `.subtitle`** — describes the decision being made
-5. **One decision per screen** — don't combine unrelated choices
-6. **Use slot labels** — `label` makes comparison tabs readable
-7. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
-8. **Tell the user to interact** — after pushing content, let them know the browser is ready
-9. **Read events after user has time** — don't immediately read; wait for user to respond
-10. **Clean up with `brainstorm_stop_session`** — frees the port and removes temp files
+2. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
+3. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
+4. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+5. **Start with a heading** — `<h2>` describes what the user is looking at
+6. **Add a `.subtitle`** — describes the decision being made
+7. **One decision per screen** — don't combine unrelated choices
+8. **Use slot labels** — `label` makes comparison tabs readable
+9. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+10. **Tell the user to interact** — after pushing content, let them know the browser is ready
+11. **Read events after user has time** — don't immediately read; wait for user to respond
+12. **Clean up with `brainstorm_stop_session`** — frees the port and removes temp files
+
+## Common Mistakes
+
+- **Starting a new session for each update** — DON'T. Call `push_screen` to update the existing browser.
+- **Omitting `project_dir`** — leads to `/tmp` collisions between agents.
+- **Pushing full HTML documents** — push fragments; the frame template adds theming and structure.
+- **Reading events immediately after push** — give the user time to interact first.
+- **Forgetting to stop** — always call `brainstorm_stop_session` when done.

package/src/templates/frame.html

@@ -78,6 +78,26 @@
       font-size: 0.875rem;
       color: var(--text-secondary);
       z-index: 100;
+      transition: transform 0.2s ease;
+    }
+    .indicator-bar.hidden {
+      transform: translateY(100%);
+    }
+    .indicator-bar .dismiss {
+      position: absolute;
+      right: 0.75rem;
+      top: 50%;
+      transform: translateY(-50%);
+      background: none;
+      border: none;
+      color: var(--text-secondary);
+      cursor: pointer;
+      font-size: 1rem;
+      padding: 0.25rem 0.5rem;
+      opacity: 0.6;
+    }
+    .indicator-bar .dismiss:hover {
+      opacity: 1;
     }
 
     .selected-text {
@@ -276,8 +296,9 @@
       <!-- CONTENT -->
     </div>
   </div>
-  <div class="indicator-bar">
+  <div class="indicator-bar" id="indicator-bar">
     <span id="indicator-text">Click an option above, then return to the terminal</span>
+    <button class="dismiss" onclick="document.getElementById('indicator-bar').classList.add('hidden')" title="Dismiss">&times;</button>
   </div>
 </body>
 </html>

package/src/templates/helper.js

@@ -74,5 +74,13 @@
     choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
   };
 
+  // Auto-hide indicator bar if no interactive elements exist
+  document.addEventListener('DOMContentLoaded', () => {
+    const bar = document.getElementById('indicator-bar');
+    if (bar && !document.querySelector('[data-choice]')) {
+      bar.classList.add('hidden');
+    }
+  });
+
   connect();
 })();