dsh-superpower 6.3.0

package/skills/brainstorming/scripts/start-server.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# Start the brainstorm server and output connection info
+# Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
+#
+# Starts server on a random high port, outputs JSON with URL.
+# Each session gets its own directory to avoid conflicts.
+#
+# Options:
+#   --project-dir <path>  Store session files under <path>/.superpowers/brainstorm/
+#                         instead of /tmp. Files persist after server stops.
+#   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
+#                         Use 0.0.0.0 in remote/containerized environments.
+#   --url-host <host>     Hostname shown in returned URL JSON.
+#   --idle-timeout-minutes <n>  Shut down after n minutes idle (default 240 = 4h).
+#   --open                Auto-open the browser on the first screen (use only
+#                         after the user approves the visual companion).
+#   --foreground          Run server in the current terminal (no backgrounding).
+#   --background          Force background mode (overrides Codex auto-foreground).
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Parse arguments
+PROJECT_DIR=""
+FOREGROUND="false"
+FORCE_BACKGROUND="false"
+BIND_HOST="127.0.0.1"
+URL_HOST=""
+IDLE_TIMEOUT_MINUTES=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project-dir)
+      PROJECT_DIR="$2"
+      shift 2
+      ;;
+    --host)
+      BIND_HOST="$2"
+      shift 2
+      ;;
+    --url-host)
+      URL_HOST="$2"
+      shift 2
+      ;;
+    --idle-timeout-minutes)
+      IDLE_TIMEOUT_MINUTES="$2"
+      shift 2
+      ;;
+    --open)
+      export BRAINSTORM_OPEN=1
+      shift
+      ;;
+    --foreground|--no-daemon)
+      FOREGROUND="true"
+      shift
+      ;;
+    --background|--daemon)
+      FORCE_BACKGROUND="true"
+      shift
+      ;;
+    *)
+      echo "{\"error\": \"Unknown argument: $1\"}"
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$URL_HOST" ]]; then
+  if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
+    URL_HOST="localhost"
+  else
+    URL_HOST="$BIND_HOST"
+  fi
+fi
+
+if [[ -n "$IDLE_TIMEOUT_MINUTES" ]]; then
+  if ! [[ "$IDLE_TIMEOUT_MINUTES" =~ ^[0-9]+$ ]] || [[ "$IDLE_TIMEOUT_MINUTES" -lt 1 ]]; then
+    echo "{\"error\": \"--idle-timeout-minutes must be a positive integer\"}"
+    exit 1
+  fi
+  export BRAINSTORM_IDLE_TIMEOUT_MS=$(( IDLE_TIMEOUT_MINUTES * 60 * 1000 ))
+fi
+
+is_windows_like_shell() {
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) return 0 ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    return 0
+  fi
+  local uname_s
+  uname_s="$(uname -s 2>/dev/null || true)"
+  case "$uname_s" in
+    MSYS*|MINGW*|CYGWIN*) return 0 ;;
+  esac
+  return 1
+}
+
+# Some environments reap detached/background processes. Auto-foreground when detected.
+if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  FOREGROUND="true"
+fi
+
+# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
+if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  if is_windows_like_shell; then
+    FOREGROUND="true"
+  fi
+fi
+
+# Session files (server.log, server-info, .last-token) embed the session key —
+# keep everything this script and the server create owner-only.
+umask 077
+
+# Generate unique session directory
+SESSION_ID="$$-$(date +%s)"
+
+if [[ -n "$PROJECT_DIR" ]]; then
+  SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  # Persist the bound port and key per project so a restart reuses them and an
+  # already-open browser tab reconnects to the same URL with a valid cookie.
+  export BRAINSTORM_PORT_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-port"
+  export BRAINSTORM_TOKEN_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-token"
+else
+  SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
+fi
+
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+LOG_FILE="${STATE_DIR}/server.log"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+# Create fresh session directory with content and state peers
+mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
+
+SERVER_ID=""
+if [[ -r /dev/urandom ]]; then
+  SERVER_ID="$(od -An -N24 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || true)"
+fi
+if ! [[ "$SERVER_ID" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
+  SERVER_ID="$(printf '%08x%08x%08x%08x' "$$" "$(date +%s)" "${RANDOM:-0}" "${RANDOM:-0}")"
+fi
+printf '%s\n' "$SERVER_ID" > "$SERVER_ID_FILE"
+chmod 600 "$SERVER_ID_FILE" 2>/dev/null || true
+
+# Kill any existing server
+if [[ -f "$PID_FILE" ]]; then
+  old_pid=$(cat "$PID_FILE")
+  kill "$old_pid" 2>/dev/null
+  rm -f "$PID_FILE"
+fi
+
+cd "$SCRIPT_DIR" || exit 1
+
+# Resolve the harness PID (grandparent of this script).
+# $PPID is the ephemeral shell the harness spawned to run us — it dies
+# when this script exits. The harness itself is $PPID's parent.
+OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
+if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
+  OWNER_PID="$PPID"
+fi
+
+# Windows/MSYS2: Node.js cannot see POSIX PIDs from the MSYS2 namespace.
+# Passing a PID node cannot verify causes server to log owner-pid-invalid
+# and self-terminate at the 60-second lifecycle check. Clear it so the
+# watchdog is disabled and the idle timeout becomes the only shutdown trigger.
+if is_windows_like_shell; then
+  OWNER_PID=""
+fi
+
+# Foreground mode for environments that reap detached/background processes.
+if [[ "$FOREGROUND" == "true" ]]; then
+  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" &
+  SERVER_PID=$!
+  echo "$SERVER_PID" > "$PID_FILE"
+  wait "$SERVER_PID"
+  exit $?
+fi
+
+# Start server, capturing output to log file
+# Use nohup to survive shell exit; disown to remove from job table
+nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" > "$LOG_FILE" 2>&1 &
+SERVER_PID=$!
+disown "$SERVER_PID" 2>/dev/null
+echo "$SERVER_PID" > "$PID_FILE"
+
+# Wait for server-started message (check log file)
+for _ in {1..50}; do
+  if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
+    # Verify server is still alive after a short window (catches process reapers)
+    alive="true"
+    for _ in {1..20}; do
+      if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        alive="false"
+        break
+      fi
+      sleep 0.1
+    done
+    if [[ "$alive" != "true" ]]; then
+      echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-server.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
+      exit 1
+    fi
+    grep "server-started" "$LOG_FILE" | head -1
+    exit 0
+  fi
+  sleep 0.1
+done
+
+# Timeout - server didn't start
+echo '{"error": "Server failed to start within 5 seconds"}'
+exit 1

package/skills/brainstorming/scripts/stop-server.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Stop the brainstorm server and clean up
+# Usage: stop-server.sh <session_dir>
+#
+# Kills the server process. Only deletes session directory if it's
+# under /tmp (ephemeral). Persistent directories (.superpowers/) are
+# kept so mockups can be reviewed later.
+
+SESSION_DIR="$1"
+
+if [[ -z "$SESSION_DIR" ]]; then
+  echo '{"error": "Usage: stop-server.sh <session_dir>"}'
+  exit 1
+fi
+
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+mark_stopped() {
+  local reason="$1"
+  rm -f "${STATE_DIR}/server-info"
+  printf '{"reason":"%s","timestamp":%s}\n' "$reason" "$(date +%s)" > "${STATE_DIR}/server-stopped"
+}
+
+read_expected_server_id() {
+  [[ -f "$SERVER_ID_FILE" ]] || return 1
+  local id
+  id="$(tr -d '\r\n' < "$SERVER_ID_FILE" 2>/dev/null || true)"
+  [[ "$id" =~ ^[A-Za-z0-9_-]{32,64}$ ]] || return 1
+  printf '%s\n' "$id"
+}
+
+command_line_for_pid() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null || true
+    return 0
+  fi
+  ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true
+}
+
+command_has_server_id() {
+  local pid="$1"
+  local expected="$2"
+  local expected_arg="--brainstorm-server-id=$expected"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    local arg
+    while IFS= read -r -d '' arg || [[ -n "$arg" ]]; do
+      [[ "$arg" == "$expected_arg" ]] && return 0
+    done < "/proc/$pid/cmdline"
+    return 1
+  fi
+  local command_line
+  command_line="$(command_line_for_pid "$pid")"
+  [[ -n "$command_line" ]] || return 1
+  case " $command_line " in
+    *" $expected_arg "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Confirm a PID has this session's per-start instance id, not just a familiar
+# process name. Ambiguous or legacy metadata fails closed as stale_pid.
+is_brainstorm_server() {
+  kill -0 "$1" 2>/dev/null || return 1
+  local expected_id
+  expected_id="$(read_expected_server_id)" || return 1
+  command_has_server_id "$1" "$expected_id" || return 1
+  return 0
+}
+
+if [[ -f "$PID_FILE" ]]; then
+  pid=$(cat "$PID_FILE")
+
+  # Refuse to signal a PID we can't prove is our server. A stale pid file may
+  # point at an unrelated process after a reboot/PID wraparound.
+  if ! is_brainstorm_server "$pid"; then
+    rm -f "$PID_FILE" "$SERVER_ID_FILE"
+    mark_stopped "stale_pid"
+    echo '{"status": "stale_pid"}'
+    exit 0
+  fi
+
+  # Try to stop gracefully, fallback to force if still alive
+  kill "$pid" 2>/dev/null || true
+
+  # Wait for graceful shutdown (up to ~2s)
+  for _ in {1..20}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      break
+    fi
+    sleep 0.1
+  done
+
+  # If still running, escalate to SIGKILL
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -9 "$pid" 2>/dev/null || true
+
+    # Give SIGKILL a moment to take effect
+    sleep 0.1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    echo '{"status": "failed", "error": "process still running"}'
+    exit 1
+  fi
+
+  rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
+  mark_stopped "stop-server.sh"
+
+  # Only delete ephemeral /tmp directories
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
+  fi
+
+  echo '{"status": "stopped"}'
+else
+  echo '{"status": "not_running"}'
+fi

package/skills/brainstorming/spec-document-reviewer-prompt.md

@@ -0,0 +1,47 @@
+# Spec 文档审查提示词模板
+
+在派发 Spec 文档审查子代理时使用本模板。
+
+**目标：** 验证 Spec 是否完整、一致且已就绪，可进入实现规划阶段。
+
+**派发时机：** Spec 文档已写入 docs/superpowers/specs/ 之后
+
+```
+Subagent (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    你是一名 Spec 文档审查员，请验证该 Spec 是否完整且已就绪，可进入规划阶段。
+
+    **待审查 Spec：** [SPEC_FILE_PATH]
+
+    ## 检查项
+
+    | 类别 | 检查内容 |
+    |----------|------------------|
+    | 完整性 | TODO、占位符、"TBD"、未完成的章节 |
+    | 一致性 | 内部矛盾、相互冲突的需求 |
+    | 清晰度 | 需求是否模糊到可能导致实现错误 |
+    | 范围 | 是否聚焦于单一规划——未涵盖多个独立子系统 |
+    | YAGNI | 未被要求的功能、过度设计 |
+
+    ## 判定标准
+
+    **仅标记会在实现规划阶段引发实际问题的缺陷。**
+    缺失章节、矛盾之处，或模糊到可能产生两种不同解读的需求——这些才算问题。措辞上的细微优化、风格偏好以及“某些章节不如其他章节详细”不算问题。
+
+    除非存在会导致规划缺陷的严重缺口，否则应予以通过。
+
+    ## 输出格式
+
+    ## Spec 审查
+
+    **状态：** 已通过 | 发现问题
+
+    **问题（如有）：**
+    - [章节 X]：[具体问题] - [对规划的影响]
+
+    **建议（仅供参考，不影响通过结论）：**
+    - [改进建议]
+```
+
+**审查员返回：** 状态、问题（如有）、建议

package/skills/brainstorming/visual-companion.md

@@ -0,0 +1,293 @@
+# 可视化辅助指南
+
+基于浏览器的可视化头脑风暴辅助工具，用于展示原型、图表和选项。
+
+## 何时使用
+
+按问题逐个判断，而非按会话判断。判断标准：**用户看图是否比看文字更易理解？**
+
+**内容本身是可视化的场景，适合使用浏览器：**
+
+- **界面原型** — 线框图、布局、导航结构、组件设计
+- **架构图** — 系统组件、数据流、关系图谱
+- **并排可视化对比** — 对比两种布局、两种配色方案、两种设计方向
+- **设计打磨** — 问题涉及外观与质感、间距、视觉层级
+- **空间关系** — 状态机、流程图、实体关系等以图形方式呈现
+
+**内容为文本或表格的场景，适合使用终端：**
+
+- **需求与范围问题** — “X 是什么意思？”，“哪些功能在范围内？”
+- **概念性的 A/B/C 选择** — 在文字描述的方案之间做选择
+- **权衡清单** — 优缺点、对比表格
+- **技术决策** — API 设计、数据建模、架构方案选型
+- **澄清性问题** — 任何答案是文字而非视觉偏好的问题
+
+一个*关于*界面主题的问题并不自动等同于可视化问题。“你想要哪种向导？”是概念性问题——使用终端。“这些向导布局中哪一个更合适？”是可视化问题——使用浏览器。
+
+## 工作原理
+
+服务器监听目录中的 HTML 文件，并将最新的文件提供给浏览器。你将 HTML 内容写入 `screen_dir`，用户在浏览器中即可看到，并可点击选择选项。选择结果会记录到 `state_dir/events`，你在下一轮对话中读取即可。
+
+**内容片段与完整文档：** 如果你的 HTML 文件以 `<!DOCTYPE` 或 `<html` 开头，服务器将原样提供（仅注入辅助脚本）。否则，服务器会自动将你的内容包裹到框架模板中——添加页头、CSS 主题、连接状态及所有交互基础设施。**默认编写内容片段。** 仅在需要完全控制页面时才编写完整文档。
+
+## 启动会话
+
+```bash
+# Start AFTER the user approves the companion. --open auto-opens their browser on
+# the first screen; --project-dir persists mockups and enables same-port restart.
+scripts/start-server.sh --project-dir /path/to/project --open
+
+# Returns: {"type":"server-started","port":52341,
+#           "url":"http://localhost:52341/?key=ab12…",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+保存响应中的 `screen_dir` 和 `state_dir`。使用 `--open` 时，浏览器会在你推送首屏时自动打开——你无需让用户手动打开，但仍需分享 URL 作为备用方案（无头/远程环境无法自动打开）。
+
+**URL 中包含会话密钥（`?key=…`）。** 服务器会拒绝任何不带该密钥的请求，因此务必向用户提供 `url` 字段中的**完整** URL——不要去除查询字符串，也不要只给裸的 `http://host:port`。该密钥用于控制 HTTP 和 WebSocket 访问，防止随意的浏览器标签页或同一网络中的其他机器读取页面或注入事件。首次加载后，浏览器会通过 Cookie 记住该密钥，因此重新加载和访问 `/files/*` 资源时无需重复携带。
+
+**查找连接信息：** 服务器会将启动时的 JSON 写入 `$STATE_DIR/server-info`。如果你在后台启动了服务器且未捕获标准输出，可读取该文件以获取 URL 和端口。使用 `--project-dir` 时，请在 `<project>/.superpowers/brainstorm/` 下查找会话目录。
+
+**注意：** 将项目根目录作为 `--project-dir` 传入，这样原型会持久化到 `.superpowers/brainstorm/` 并在服务器重启后依然保留。若不传，文件会写入 `/tmp` 并被清理。如果 `.gitignore` 中尚未包含 `.superpowers/`，请提醒用户添加。
+
+**按平台启动服务器：**
+
+**Claude Code：**
+```bash
+# Default mode works — the script backgrounds the server itself.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+在 Windows 上，脚本会自动检测并切换到前台模式（会阻塞工具调用）。请在 Bash 工具调用上使用 `run_in_background: true`，使服务器在对话轮次之间保持运行，然后在下一轮读取 `$STATE_DIR/server-info` 以获取 URL 和端口。
+
+**Codex：**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+**Gemini CLI：**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Copilot CLI：**
+```bash
+# Start it with Copilot CLI's non-blocking/background shell mechanism so the
+# server survives across turns. Keep --foreground so the harness, not the
+# script, owns backgrounding. The launcher is a .sh, so invoke it via bash
+# (on Windows, call Git Bash's bash.exe from the PowerShell tool).
+bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**其他环境：** 服务器必须在后台持续运行并跨越对话轮次。如果你的环境会回收 detached 进程，请使用 `--foreground` 并通过平台提供的后台执行机制来启动命令。
+
+如果 URL 在你的浏览器中无法访问（在远程/容器化环境中很常见），请绑定非回环地址：
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+使用 `--url-host` 控制返回的 URL JSON 中显示的主机名。
+
+## 循环流程
+
+1. **检查服务器是否存活**，然后**向 `screen_dir` 写入 HTML 新文件**：
+   - **必须：在引用 URL 或推送页面前确认服务器存活。** 检查 `$STATE_DIR/server-info` 是否存在且 `$STATE_DIR/server-stopped` 是否不存在。如果已关闭，请使用**相同的 `--project-dir`** 通过 `start-server.sh` 重启——它会复用同一端口，用户的已打开标签页会自动重连（服务器宕机期间会显示“已暂停”遮罩），无需发送新 URL。服务器在空闲 4 小时后自动退出（可通过 `--idle-timeout-minutes` 配置）。
+   - 使用语义化文件名：`platform.html`、`visual-style.html`、`layout.html`
+   - **不要复用文件名**——每个页面都使用全新文件
+   - 使用你的文件创建工具——**不要使用 cat/heredoc**（会在终端产生大量噪音）
+   - 服务器自动提供最新的文件
+
+2. **告知用户预期内容并结束本轮：**
+   - 提醒他们 URL（每一步都要，不只是第一步）
+   - 简要文字概括屏幕内容（例如：“正在展示首页的 3 种布局方案”）
+   - 请他们在终端中回应：“请查看后告诉我你的想法。如果愿意，可以点击选择一个选项。”
+
+3. **在你的下一轮**——用户在终端回应后：
+   - 如果存在，读取 `$STATE_DIR/events`——其中包含用户在浏览器中的交互（点击、选择），以 JSON 行格式记录
+   - 将其与用户的终端文本合并，以获得完整信息
+   - 终端消息是主要反馈；`state_dir/events` 提供结构化的交互数据
+
+4. **迭代或推进**——如果反馈改变了当前页面，写入新文件（例如 `layout-v2.html`）。仅在当前步骤已确认后再进入下一步。
+
+5. **回到终端时卸载**——当下一步不需要浏览器时（例如澄清问题、权衡讨论），推送一个等待页面以清除过时内容：
+
+    ```html
+    <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+    <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+      <p class="subtitle">Continuing in terminal...</p>
+    </div>
+    ```
+
+    这样可避免用户在对话已推进后仍盯着已解决的选择。当下一个可视化问题出现时，像往常一样推送新的内容文件即可。
+
+6. 重复上述流程直至完成。
+
+## 编写内容片段
+
+只需编写页面内部的内容。服务器会自动将其包裹到框架模板中（页头、主题 CSS、连接状态及所有交互基础设施）。
+
+**最小示例：**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+就是这样。无需 `<html>`、CSS 或 `<script>` 标签。服务器会提供所有这些。
+
+## 可用 CSS 类
+
+框架模板为你的内容提供以下 CSS 类：
+
+### 选项（A/B/C 选择）
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**多选：** 在容器上添加 `data-multiselect` 以允许用户选择多个选项。每次点击都会切换项目的选中样式。
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### 卡片（视觉设计）
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### 原型容器
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### 分栏视图（并排）
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### 优缺点
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### 模拟元素（线框图构建块）
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### 排版与区块
+
+- `h2` — 页面标题
+- `h3` — 区块标题
+- `.subtitle` — 标题下方的次级文本
+- `.section` — 带底部边距的内容块
+- `.label` — 小号大写标签文本
+
+## 浏览器事件格式
+
+当用户在浏览器中点击选项时，其交互会被记录到 `$STATE_DIR/events`（每行一个 JSON 对象）。当你推送新页面时，该文件会自动清空。
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+完整的事件流展示了用户的探索路径——他们在确定前可能会点击多个选项。最后一个 `choice` 事件通常是最终选择，但点击模式可能揭示犹豫或偏好，值得进一步询问。
+
+如果 `$STATE_DIR/events` 不存在，说明用户未与浏览器交互——仅使用其终端文本即可。
+
+## 设计建议
+
+- **根据问题匹配保真度**——布局问题用线框图，视觉打磨问题再做精细化
+- **在每页上说明问题**——“哪种布局更显专业？”而非仅仅“选一个”
+- **先迭代再推进**——如果反馈改变了当前页面，先写一个新版本
+- **每屏最多 2-4 个选项**
+- **在重要场景使用真实内容**——例如摄影作品集应使用真实图片（Unsplash）。占位内容会掩盖设计问题。
+- **保持原型简洁**——聚焦布局与结构，而非像素级完美
+
+## 文件命名
+
+- 使用语义化名称：`platform.html`、`visual-style.html`、`layout.html`
+- 不要复用文件名——每个页面必须是新文件
+- 迭代时：追加版本后缀，如 `layout-v2.html`、`layout-v3.html`
+- 服务器按修改时间提供最新的文件
+
+## 清理
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+如果会话使用了 `--project-dir`，原型文件会保留在 `.superpowers/brainstorm/` 中以便后续查阅。仅 `/tmp` 会话在停止时会被删除。
+
+## 参考
+
+- 框架模板（CSS 参考）：`scripts/frame-template.html`
+- 辅助脚本（客户端）：`scripts/helper.js`