better-grill 0.1.0 → 0.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "better-grill",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run grill sessions in a local browser UI instead of the terminal: rounds of questions with options and a recommendation, a discussion thread per question, driven by your open Claude Code session.",
   "author": {
     "name": "Jakub Stastny",
@@ -10,9 +10,12 @@
   "repository": "https://github.com/devbaj-stastny-jakub/better-grill",
   "license": "MIT",
   "keywords": [
+    "ai",
+    "browser-ui",
+    "claude",
+    "claude-code-skill",
     "grill",
     "interview",
-    "planning",
-    "browser-ui"
+    "planning"
   ]
 }

package/README.md

@@ -1,12 +1,28 @@
-# better grill
+# better-grill
 
-Run grill sessions in a browser instead of the terminal. Claude posts rounds of questions with options and a recommendation; you lock in each question when ready (pick, type your own answer, or both), or open a discussion thread per question. When everything is locked in, **Send to Claude** sends the round; discussion messages go right away. From a discussion, Claude can resolve, edit, drop or add questions in the UI. Everything runs through your open Claude Code session, so it uses your Claude Code subscription. No API key.
+[![npm](https://img.shields.io/npm/v/better-grill)](https://www.npmjs.com/package/better-grill)
+[![license](https://img.shields.io/npm/l/better-grill)](LICENSE)
+[![node](https://img.shields.io/node/v/better-grill)](https://nodejs.org)
+
+Grill sessions for Claude Code, in your browser instead of the terminal.
+
+![A grill round in better-grill: one question locked in, the next with Claude's recommended option picked](https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/round.png)
+
+A grill session is Claude interviewing you about a plan until nothing is left unsaid. It maps the decisions as a tree, asks every question it can answer right now in one round with a recommended answer each, and keeps going until every branch is settled. The method comes from Matt Pocock's [`grilling`](https://github.com/mattpocock/skills) skill; better-grill gives it a proper UI.
+
+Why a browser:
+
+- **Options side by side**, each with a description and Claude's pick marked, instead of a wall of terminal text.
+- **A discussion thread per question.** Push back on one question without derailing the rest; Claude can reword, resolve, drop or add questions from the talk.
+- **Answer at your own pace.** Lock in questions in any order, change your mind, then send the whole round at once.
+- **Runs on your Claude Code session.** Uses your existing subscription. No API key, no hosted service.
 
 ## Requirements
 
 - [Claude Code](https://code.claude.com)
 - [Node.js](https://nodejs.org) 20 or newer on your `PATH`
-- Matt Pocock's `grilling` skill from [mattpocock/skills](https://github.com/mattpocock/skills). better-grill brings the UI; `grilling` brings the method (design tree, frontier, recommended answers).
+- The `grilling` skill from [mattpocock/skills](https://github.com/mattpocock/skills). better-grill brings the UI; `grilling` brings the method.
+- For the docs variant, also `domain-modeling` from the same repo.
 
 ## Install
 
@@ -17,125 +33,42 @@ In Claude Code:
 /plugin install better-grill@better-grill
 ```
 
-Then, in any session:
-
-```
-/better-grill:better-grill <what you want grilled>
-```
+## Usage
 
-Your browser opens on the session. Claude keeps the terminal quiet and talks to you in the UI until you confirm the final summary.
+In any Claude Code session:
 
-Several Claude sessions can grill at the same time; each gets its own bridge, port and browser tab.
-
-## How it talks to Claude Code
-
-Claude Code has no port or socket to call, so the browser cannot reach it. A small local **bridge** sits between them:
-
-```
-Claude Code session                 bridge (node, 127.0.0.1)            browser
-───────────────────                 ────────────────────────            ───────
-grill round  ── POST /api/rounds ─▶ session state ── SSE /api/stream ─▶ UI
-grill wait   ── GET  /api/wait ───▶ (held open)
-                                    ◀── POST answer / chat ──────────── click
-             ◀── events JSON ─────  releases the wait
-grill reply  ── POST /reply ──────▶ ── SSE ────────────────────────────▶ chat thread
 ```
-
-- Claude drives the bridge with the `grill` CLI from its Bash tool.
-- `grill wait` is a long-poll Claude runs in the background. It returns when you press Send or write in a discussion, and Claude Code wakes the session with the events.
-- The bridge never calls Claude. It only holds state and releases waits.
-- A bridge exits on its own after 30 minutes with no wait running, no browser tab open and no requests.
-
-### Security
-
-The bridge listens on `127.0.0.1` only and:
-
-- refuses requests whose `Host` isn't localhost (DNS rebinding),
-- refuses requests whose `Origin` isn't the page it serves, and requires JSON bodies, so other websites open in your browser can't post into the session,
-- refuses Claude-side calls without its session id (see below).
-
-## CLI
-
-The plugin runs it as `node <skill dir>/dist/cli.js`; outside Claude Code it is also `npx better-grill`.
-
-```
-grill start [--title T] [--port N] [--no-open]   # prints {"session":"62950-a1b2c3","url","log"}
-grill round   -s SESSION < round.json
-grill add     -s SESSION < questions.json      # into the latest round, while unsent
-grill wait    -s SESSION
-grill reply   -s SESSION Q3 < text.md
-grill resolve -s SESSION Q3 < resolution.json  # {"options":[1],"text":"…"}
-grill edit    -s SESSION Q3 < patch.json
-grill drop    -s SESSION Q3 < reason.txt
-grill summary -s SESSION < summary.md
-grill state   -s SESSION
-grill stop    -s SESSION
+/better-grill:better-grill <what you want grilled>
 ```
 
-Each `grill start` runs its own bridge on a free port. The session handle is `<port>-<id>`: the CLI sends the id in an `x-grill-session` header and the bridge refuses Claude-side calls whose id doesn't match, so a session that mixes up ports gets an error instead of writing into someone else's grill.
-
-Exit codes: 0 ok, 1 bridge rejected the input, 2 usage error or bridge unreachable.
-
-## Development
-
-Needs Node 24 (`.nvmrc`) and pnpm.
+Or, to also keep a glossary (`CONTEXT.md`) and ADRs as decisions settle, like `grill-with-docs`:
 
-```sh
-pnpm install
-pnpm dev          # bridge from TypeScript on :4777 as session 4777-dev (node --watch) + Vite on :5173 proxying /api
-pnpm demo         # fake Claude: posts rounds, echoes chat replies, ends in a summary
-pnpm check-types
-pnpm build        # web UI + bridge bundle into skills/better-grill/dist
 ```
-
-Open http://localhost:5173 after `pnpm dev`, then run `pnpm demo` in a second terminal.
-
-To use your checkout from real Claude Code sessions, either load it as a plugin with `claude --plugin-dir .`, or symlink the skill:
-
-```sh
-ln -s "$PWD/skills/better-grill" ~/.claude/skills/better-grill
+/better-grill:better-grill-docs <what you want grilled>
 ```
 
-The skill runs the bundle in `skills/better-grill/dist`, so rebuild after bridge changes (`pnpm --filter @better-grill/bridge build:watch` keeps it fresh).
-
-### Layout
+1. Your browser opens on the session. The terminal stays quiet; everything happens in the UI.
+2. Claude posts a round of questions. For each one, pick an option, write your own answer, or both, then **Lock in**.
+3. Not sure about a question? Hit **Discuss** and talk it through. Claude answers in the thread and updates the question when you agree on something.
+4. When every question is locked in, **Send to Claude**. The next round builds on your answers.
+5. When nothing is left open, Claude posts a summary of every decision. Confirm it, or say what's wrong and the grilling continues.
 
-| Path                    | What                                                                          |
-| ----------------------- | ----------------------------------------------------------------------------- |
-| `packages/protocol`     | Zod schemas and types shared by bridge and UI: rounds, answers, events         |
-| `apps/bridge`           | Node server (`server.ts`), session logic, `grill` CLI, demo and build scripts  |
-| `apps/web`              | Vite + React + Tailwind + shadcn/ui (Base UI) UI                               |
-| `skills/better-grill`   | `SKILL.md`, plus the built `dist/` (bridge bundle and web UI) it runs          |
-| `.claude-plugin`        | Plugin manifest and the marketplace that points at the npm package             |
+![A discussion thread next to the question it is about](https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/discussion.png)
 
-In development the bridge runs TypeScript directly with Node's type stripping. For release, esbuild bundles it into dependency-free JS for Node 20+.
+Several Claude sessions can grill at the same time; each gets its own browser tab.
 
-`apps/web/src` follows [bulletproof-react](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md):
+## How it works
 
-| Path                 | What                                                                                |
-| -------------------- | ----------------------------------------------------------------------------------- |
-| `app/`               | Providers and `session-screen.tsx`, which composes the features                      |
-| `features/<name>/`   | `session`, `rounds`, `discussion`, `navigation`, `summary`: each with `api/`, `components/`, `hooks/`, `utils/` as needed |
-| `components/ui/`     | shadcn components (Base UI, `base-nova` style). Add more with `pnpm dlx shadcn@latest add <name>` in `apps/web` |
-| `components/`        | Shared app components: markdown, errors, feedback notes, brand, theme toggle         |
-| `hooks/` `lib/` `utils/` `types/` `config/` | Shared hooks, bridge client + theme + lock, pure helpers, types, constants |
+- Claude Code has no port the browser could call, so better-grill starts a small local **bridge** server for each session.
+- Claude talks to the bridge with a CLI from its Bash tool: it posts rounds, then waits in the background until you send a round or write in a discussion.
+- The bridge never calls Claude or any API. It holds the session state and hands your answers back.
+- It listens on `127.0.0.1` only, rejects requests from other websites, and shuts down on its own after 30 idle minutes.
 
-Features never import from each other; only `app/` combines them. Theme tokens (stone + orange accent, light and dark) live in `src/index.css`.
-
-### Releasing
-
-The plugin ships as the `better-grill` npm package; the marketplace in `.claude-plugin/marketplace.json` points at it, so nothing built is committed.
-
-```sh
-npm version patch      # bumps package.json and .claude-plugin/plugin.json together
-npm publish            # prepublishOnly runs check-types and build
-git push --follow-tags
-```
+Details, security model, CLI reference and known limits: [ARCHITECTURE.md](ARCHITECTURE.md).
 
-## Known limits
+## Contributing
 
-- State lives in bridge memory. Browser refresh is fine; a bridge crash loses the session.
-- One Claude session per bridge. Events queue while Claude is busy and arrive as one batch.
+Issues and pull requests welcome. Dev setup: [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "better-grill",
-  "version": "0.1.0",
-  "description": "Run grill sessions in a local browser UI instead of the terminal, driven by your open Claude Code session.",
+  "version": "0.2.0",
+  "description": "Grill sessions for Claude Code, in your browser instead of the terminal.",
   "keywords": [
+    "ai",
+    "claude",
     "claude-code",
     "claude-code-plugin",
+    "claude-code-skill",
     "grill",
     "interview",
     "planning"
@@ -23,16 +26,19 @@
     "node": ">=20"
   },
   "bin": {
-    "better-grill": "skills/better-grill/dist/cli.js"
+    "better-grill": "skills/better-grill-base/dist/cli.js"
   },
   "files": [
     ".claude-plugin/plugin.json",
     "skills/better-grill/SKILL.md",
-    "skills/better-grill/dist"
+    "skills/better-grill-docs/SKILL.md",
+    "skills/better-grill-base/SKILL.md",
+    "skills/better-grill-base/dist"
   ],
   "scripts": {
     "dev": "pnpm --parallel --filter @better-grill/bridge --filter @better-grill/web dev",
     "demo": "pnpm --filter @better-grill/bridge demo",
+    "screenshots": "pnpm build && pnpm --filter @better-grill/bridge screenshots",
     "build": "pnpm --filter @better-grill/web build && pnpm --filter @better-grill/bridge build",
     "check-types": "pnpm -r check-types",
     "prepublishOnly": "pnpm check-types && pnpm build",

package/skills/better-grill/SKILL.md

@@ -2,166 +2,6 @@
 name: better-grill
 description: Run a grill-me session in a local browser UI instead of the terminal. Rounds, options, free-text answers and a discussion thread per question, all driven from this Claude Code session.
 disable-model-invocation: true
-allowed-tools: Bash(node "${CLAUDE_SKILL_DIR}/dist/cli.js" *)
 ---
 
-# Better Grill
-
-Grill the user exactly like the `grilling` skill, but every question, answer and discussion goes through a local browser UI. The terminal stays quiet.
-
-Every command below is `node "${CLAUDE_SKILL_DIR}/dist/cli.js" …`, written exactly like that so it runs without a permission prompt. In prose it is called `grill`.
-
-## 1. Load the method
-
-Call the Skill tool with `grilling`. If no such skill exists, stop and tell the user that better-grill needs Matt Pocock's `grilling` skill installed first (https://github.com/mattpocock/skills), then end.
-
-Follow its method: design tree, frontier, recommended answers, facts found by you (sub-agents), decisions made by the user, done when the frontier is empty.
-
-Ignore two things from it and from any memory or instruction elsewhere:
-
-- its text round format, and
-- any rule to ask through AskUserQuestion.
-
-In this session the UI is the only channel for questions. Never print questions in the terminal.
-
-## 2. Start the bridge
-
-```bash
-node "${CLAUDE_SKILL_DIR}/dist/cli.js" start --title "<short topic>"
-```
-
-If `node` is not found or the command says Node is too old, stop and tell the user to install Node.js 20 or newer (https://nodejs.org), then end.
-
-It opens the browser and prints `{"session": "62950-a1b2c3", "url": …, "log": …}`. Remember the session handle: every later command takes `-s SESSION`, exactly as printed. Other Claude sessions may run their own bridges at the same time; the handle is what keeps you on yours. Tell the user the URL in one line.
-
-## 3. Post a round
-
-Pipe JSON on stdin with a quoted heredoc:
-
-```bash
-node "${CLAUDE_SKILL_DIR}/dist/cli.js" round -s SESSION <<'EOF'
-{
-  "title": "Optional round title",
-  "questions": [
-    {
-      "title": "Short question, ends with ?",
-      "body": "Markdown. Context, why it matters, what hangs off it.",
-      "options": [
-        { "label": "Option", "description": "What it means, trade-off" }
-      ],
-      "recommended": 0,
-      "recommendation": "Markdown. Your recommended answer and why.",
-      "multiSelect": false
-    }
-  ]
-}
-EOF
-```
-
-- The bridge numbers questions `Q1`, `Q2`, … across the whole session and prints the ids. Use them in later commands.
-- `recommended` is an index into `options`. Do not write "(Recommended)" into labels; the UI marks it.
-- Do not add an "Other" option. The user can always type an own answer and open a discussion.
-- `options` may be empty for an open question.
-
-## 4. Wait for the user
-
-```bash
-node "${CLAUDE_SKILL_DIR}/dist/cli.js" wait -s SESSION
-```
-
-**Always run it with `run_in_background: true`.** It blocks until the user does something, which can take hours. You are notified when it exits; then read its output. Keep exactly one wait running: after handling events, start the next wait straight away. While a wait runs you may do other work (sub-agents for facts).
-
-Output:
-
-```json
-{
-  "events": [
-    { "type": "answer", "questionId": "Q2", "title": "…", "choices": ["Label"], "text": "note or own answer", "revised": false, "by": "user" },
-    { "type": "chat", "questionId": "Q3", "title": "…", "text": "user message" }
-  ],
-  "open": [{ "id": "Q3", "title": "…" }]
-}
-```
-
-`open` lists questions still unanswered after these events. A wait that returns only `chat` events means the round is still in progress: handle the chat, then wait again.
-
-## 5. Handle events
-
-- **answer**: the user pressed **Send**, which only works when every question is answered, so answers arrive together as one complete round. Recompute the frontier and post the next round, exactly as in `grilling`.
-  - `by: "claude"`: your own resolution (below), which the user sent back unchanged.
-  - `revised: true`: the user changed an answer you already had. Re-check everything that depended on it.
-- **chat**: the user wants to talk about that question. Reply in its thread:
-
-  ```bash
-  node "${CLAUDE_SKILL_DIR}/dist/cli.js" reply -s SESSION Q3 <<'EOF'
-  Markdown reply.
-  EOF
-  ```
-
-  Keep replies conversational and short. Then act on what the talk settled (next section). Never tell the user to go lock in an answer the two of you already agreed on.
-- **summary_confirmed / summary_rejected / ended**: see step 6.
-
-## 5b. Shape questions from the discussion
-
-The UI is yours to keep accurate. After a chat, change the questions to match what was said:
-
-- **Settled in the discussion** → resolve it for the user. Pick option indexes, write text, or both. Use text alone when the agreed answer is none of the options (a custom solution). The user sees "resolved by Claude" and can still change it before Send.
-
-  ```bash
-  node "${CLAUDE_SKILL_DIR}/dist/cli.js" resolve -s SESSION Q6 <<'EOF'
-  { "options": [1], "text": "TanStack Query, and the SSE stream writes into the `['session']` cache." }
-  EOF
-  ```
-
-- **Question was framed wrong, or options need changing** → edit it. Send only the fields that change. `null` clears `recommended` / `recommendation`. Sending `options` clears any answer on it, because the answer may point at old options.
-
-  ```bash
-  node "${CLAUDE_SKILL_DIR}/dist/cli.js" edit -s SESSION Q4 <<'EOF'
-  { "title": "Better title?", "options": [{ "label": "A" }, { "label": "B" }], "recommended": 0 }
-  EOF
-  ```
-
-- **No longer matters** → drop it (it stays visible, struck through, with your reason):
-
-  ```bash
-  node "${CLAUDE_SKILL_DIR}/dist/cli.js" drop -s SESSION Q4 <<'EOF'
-  Moot: you chose memory-only state.
-  EOF
-  ```
-
-- **Discussion surfaced a new question for this round** → add it to the current round instead of starting a new one. Fails once the user has sent that round; then it belongs in the next round.
-
-  ```bash
-  node "${CLAUDE_SKILL_DIR}/dist/cli.js" add -s SESSION <<'EOF'
-  { "questions": [{ "title": "…?", "body": "…", "options": [] }] }
-  EOF
-  ```
-
-In the thread, say in one line what you changed ("Resolved Q6 as TanStack Query + SSE cache.").
-
-## 6. Finish
-
-When the frontier is empty and `open` is empty, post a summary of every settled decision (by question id) and remaining risks, then wait:
-
-```bash
-node "${CLAUDE_SKILL_DIR}/dist/cli.js" summary -s SESSION <<'EOF'
-### Settled
-- **Q1 First user:** solo developers
-EOF
-```
-
-- `summary_confirmed`: run `grill stop -s SESSION`, then print the summary in the terminal as your final output. Act on it only if the user asks.
-- `summary_rejected`: its `text` is new input. Keep grilling, then post a new summary.
-- `ended` (user closed the session in the UI, at any time): run `grill stop -s SESSION` and print what was settled so far.
-
-## Terminal etiquette
-
-Between tool calls print at most one short line (for example "Round 3 posted."). All content belongs in the UI.
-
-## Troubleshooting
-
-- `No bridge for session …` (exit 2): the bridge is gone. It exits on its own after 30 minutes with no wait running and no browser tab open, and it can crash. Start a new one; the old session state is gone.
-- `Wrong session: …` (exit 1): you used a handle that isn't yours, and it reached another session's bridge. Find the `session` your own `grill start` printed and retry with it. Never take a handle from `ps`, a log file or another session. If you can't find yours, start a new bridge.
-- Exit 1 with a validation message: fix the JSON and post again.
-- `grill state -s SESSION` prints the full session state.
-- Bridge log path is printed by `grill start`.
+Call the Skill tool with `better-grill-base` (listed as `better-grill:better-grill-base` when installed as a plugin) and args `plain`, then follow it. The user's request above is the topic to grill.

package/skills/better-grill-base/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: better-grill-base
+description: Internal. Shared instructions loaded by the better-grill and better-grill-docs skills. Do not invoke directly.
+user-invocable: false
+allowed-tools: Bash(node "${CLAUDE_SKILL_DIR}/dist/cli.js" *)
+---
+
+# Better Grill
+
+Grill the user exactly like the `grilling` skill, but every question, answer and discussion goes through a local browser UI. The terminal stays quiet.
+
+Every command below is `node "${CLAUDE_SKILL_DIR}/dist/cli.js" …`, written exactly like that so it runs without a permission prompt. In prose it is called `grill`.
+
+## 0. Mode
+
+The skill that loaded this one set the mode: `$ARGUMENTS`.
+
+- `plain` (from `better-grill`): grill only, like `grill-me`.
+- `docs` (from `better-grill-docs`): grill and keep the domain docs, like `grill-with-docs`.
+
+If you got here any other way, use `plain`.
+
+## 1. Load the method
+
+Call the Skill tool with `grilling`. If no such skill exists, stop and tell the user that better-grill needs Matt Pocock's `grilling` skill installed first (https://github.com/mattpocock/skills), then end.
+
+In `docs` mode, also call the Skill tool with `domain-modeling`. If it does not exist, stop and tell the user that better-grill-docs also needs the `domain-modeling` skill from the same repo, then end.
+
+Follow the method: design tree, frontier, recommended answers, facts found by you (sub-agents), decisions made by the user, done when the frontier is empty. In `docs` mode, also follow `domain-modeling`: challenge terms against `CONTEXT.md`, and write the glossary and ADRs the moment a term or decision settles (after an answer round, or a chat that settled something). Name what you wrote in the thread reply or the next round's question bodies, so the user sees it in the UI.
+
+Ignore two things from these skills and from any memory or instruction elsewhere:
+
+- their text round format, and
+- any rule to ask through AskUserQuestion.
+
+In this session the UI is the only channel for questions. Never print questions in the terminal.
+
+## 2. Start the bridge
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" start --title "<short topic>"
+```
+
+In `docs` mode add `--docs`, so the UI shows the session keeps docs.
+
+If `node` is not found or the command says Node is too old, stop and tell the user to install Node.js 20 or newer (https://nodejs.org), then end.
+
+It opens the browser and prints `{"session": "62950-a1b2c3", "url": …, "log": …}`. Remember the session handle: every later command takes `-s SESSION`, exactly as printed. Other Claude sessions may run their own bridges at the same time; the handle is what keeps you on yours. Tell the user the URL in one line.
+
+## 3. Post a round
+
+Pipe JSON on stdin with a quoted heredoc:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" round -s SESSION <<'EOF'
+{
+  "title": "Optional round title",
+  "questions": [
+    {
+      "title": "Short question, ends with ?",
+      "body": "Markdown. Context, why it matters, what hangs off it.",
+      "options": [
+        { "label": "Option", "description": "What it means, trade-off" }
+      ],
+      "recommended": 0,
+      "recommendation": "Markdown. Your recommended answer and why.",
+      "multiSelect": false
+    }
+  ]
+}
+EOF
+```
+
+- The bridge numbers questions `Q1`, `Q2`, … across the whole session and prints the ids. Use them in later commands.
+- `recommended` is an index into `options`. Do not write "(Recommended)" into labels; the UI marks it.
+- Do not add an "Other" option. The user can always type an own answer and open a discussion.
+- `options` may be empty for an open question.
+
+## 4. Wait for the user
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" wait -s SESSION
+```
+
+**Always run it with `run_in_background: true`.** It blocks until the user does something, which can take hours. You are notified when it exits; then read its output. Keep exactly one wait running: after handling events, start the next wait straight away. While a wait runs you may do other work (sub-agents for facts).
+
+Output:
+
+```json
+{
+  "events": [
+    { "type": "answer", "questionId": "Q2", "title": "…", "choices": ["Label"], "text": "note or own answer", "revised": false, "by": "user" },
+    { "type": "chat", "questionId": "Q3", "title": "…", "text": "user message" }
+  ],
+  "open": [{ "id": "Q3", "title": "…" }]
+}
+```
+
+`open` lists questions still unanswered after these events. A wait that returns only `chat` events means the round is still in progress: handle the chat, then wait again.
+
+## 5. Handle events
+
+- **answer**: the user pressed **Send**, which only works when every question is answered, so answers arrive together as one complete round. Recompute the frontier and post the next round, exactly as in `grilling`.
+  - `by: "claude"`: your own resolution (below), which the user sent back unchanged.
+  - `revised: true`: the user changed an answer you already had. Re-check everything that depended on it.
+- **chat**: the user wants to talk about that question. Reply in its thread:
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" reply -s SESSION Q3 <<'EOF'
+  Markdown reply.
+  EOF
+  ```
+
+  Keep replies conversational and short. Then act on what the talk settled (next section). Never tell the user to go lock in an answer the two of you already agreed on.
+- **summary_confirmed / summary_rejected / ended**: see step 6.
+
+## 5b. Shape questions from the discussion
+
+The UI is yours to keep accurate. After a chat, change the questions to match what was said:
+
+- **Settled in the discussion** → resolve it for the user. Pick option indexes, write text, or both. Use text alone when the agreed answer is none of the options (a custom solution). The user sees "resolved by Claude" and can still change it before Send.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" resolve -s SESSION Q6 <<'EOF'
+  { "options": [1], "text": "TanStack Query, and the SSE stream writes into the `['session']` cache." }
+  EOF
+  ```
+
+- **Question was framed wrong, or options need changing** → edit it. Send only the fields that change. `null` clears `recommended` / `recommendation`. Sending `options` clears any answer on it, because the answer may point at old options.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" edit -s SESSION Q4 <<'EOF'
+  { "title": "Better title?", "options": [{ "label": "A" }, { "label": "B" }], "recommended": 0 }
+  EOF
+  ```
+
+- **No longer matters** → drop it (it stays visible, struck through, with your reason):
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" drop -s SESSION Q4 <<'EOF'
+  Moot: you chose memory-only state.
+  EOF
+  ```
+
+- **Discussion surfaced a new question for this round** → add it to the current round instead of starting a new one. Fails once the user has sent that round; then it belongs in the next round.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" add -s SESSION <<'EOF'
+  { "questions": [{ "title": "…?", "body": "…", "options": [] }] }
+  EOF
+  ```
+
+In the thread, say in one line what you changed ("Resolved Q6 as TanStack Query + SSE cache.").
+
+## 6. Finish
+
+When the frontier is empty and `open` is empty, post a summary of every settled decision (by question id) and remaining risks, then wait:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" summary -s SESSION <<'EOF'
+### Settled
+- **Q1 First user:** solo developers
+EOF
+```
+
+In `docs` mode, end the summary with a `### Docs` section listing every file you created or changed (`CONTEXT.md`, each ADR).
+
+- `summary_confirmed`: run `grill stop -s SESSION`, then print the summary in the terminal as your final output. Act on it only if the user asks.
+- `summary_rejected`: its `text` is new input. Keep grilling, then post a new summary.
+- `ended` (user closed the session in the UI, at any time): run `grill stop -s SESSION` and print what was settled so far.
+
+## Terminal etiquette
+
+Between tool calls print at most one short line (for example "Round 3 posted." or "ADR 0003 written."). All content belongs in the UI.
+
+## Troubleshooting
+
+- `No bridge for session …` (exit 2): the bridge is gone. It exits on its own after 30 minutes with no wait running and no browser tab open, and it can crash. Start a new one; the old session state is gone.
+- `Wrong session: …` (exit 1): you used a handle that isn't yours, and it reached another session's bridge. Find the `session` your own `grill start` printed and retry with it. Never take a handle from `ps`, a log file or another session. If you can't find yours, start a new bridge.
+- Exit 1 with a validation message: fix the JSON and post again.
+- `grill state -s SESSION` prints the full session state.
+- Bridge log path is printed by `grill start`.