@dmsdc-ai/aigentry-deliberation 0.0.38 → 0.0.40

package/README.md

@@ -1,97 +1,63 @@
 # @dmsdc-ai/aigentry-deliberation
 
-Part of aigentry — the open-source engine that makes AI decisions auditable.
-
-**The only tool that lets multiple AIs debate before deciding.**
-
-MCP Deliberation Server — Multi-session AI deliberation with smart speaker ordering and persona roles. No competitor has this: aigentry-deliberation is the killer feature of the aigentry platform, enabling structured multi-AI debate with full audit trails before any decision is committed.
-
-## Features
-
-- **Multi-session** parallel deliberation support
-- **Smart speaker ordering**: cyclic, random, weighted-random strategies
-- **Persona roles**: critic, implementer, mediator, researcher, free — with prompt templates
-- **Vote parsing**: [AGREE] / [DISAGREE] / [CONDITIONAL] extraction
-- **Browser LLM integration**: CDP-based auto-turn for ChatGPT, Claude, Gemini browser tabs
-- **Chrome Extension support**: Side panel detection via title-based matching
-- **Cross-platform**: macOS (tmux + Terminal.app), Windows (Windows Terminal), Linux
-- **Telepty bus transport**: structured `turn_request` delivery for telepty-managed sessions
-- **User-confirmed speaker selection**: candidates must be confirmed before a session can start
-- **Obsidian archiving**: Auto-archive deliberation results to Obsidian vault
-- **Session monitoring**: Real-time tmux/terminal monitoring
-- **Vote enforcement**: Automatic [AGREE]/[DISAGREE]/[CONDITIONAL] vote marker requirement
-- **Dynamic CLI timeout**: Smart cold-start handling (180s first turn, 120s subsequent)
-- **Split telepty timeouts**: 5s transport ack + 60s semantic response tracking
-- **Typed synthesis envelopes**: validated structured payloads for downstream automation
-- **Runtime logging**: Session lifecycle event logging for observability
-- **Resilient browser automation**: 5-stage degradation state machine with 60s SLO
-- **Model routing**: Dynamic per-provider model selection based on prompt analysis
-- **Role drift detection**: Structural heading markers + keyword analysis for accurate role inference
+**Structured multi-AI discussions via MCP.**
+
+The only MCP server that lets multiple AI agents debate a question before committing to a decision. Run structured discussions across CLI agents (Claude Code, Codex, Gemini) and browser LLMs (ChatGPT, Claude Web, Gemini Web) with full audit trails, vote tracking, and synthesis.
+
+## What it does
+
+- **Structured deliberation sessions** — pose a topic, route turns to each speaker, collect [AGREE]/[DISAGREE]/[CONDITIONAL] votes, synthesize consensus
+- **Smart speaker ordering** — cyclic, random, or weighted-random strategies to balance participation
+- **Persona roles** — assign critic, implementer, mediator, researcher, or free roles with built-in prompt templates
+- **Browser LLM integration** — CDP-based auto-turn for ChatGPT, Claude Web, Gemini Web and more; clipboard fallback for unsupported providers
+- **Typed synthesis output** — structured `ExecutionContractV2` envelopes with decisions, actionable tasks, and optional experiment verdicts for downstream automation
 
 ## Installation
 
-원클릭 설치 — 어떤 프로젝트 환경에서든 동작합니다:
+One-command install — registers the MCP server with Claude Code and Gemini CLI automatically:
 
 ```bash
-npx @dmsdc-ai/aigentry-deliberation install
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
 ```
 
-이 명령은:
-1. `~/.local/lib/mcp-deliberation/`에 서버 파일 설치 (Windows: `%LOCALAPPDATA%/mcp-deliberation/`)
-2. npm 의존성 설치
-3. `~/.claude/.mcp.json`에 MCP 서버 자동 등록
-4. Claude Code 재시작하면 바로 사용 가능
-5. Gemini CLI MCP 서버 자동 등록 (`~/.gemini/settings.json`)
-6. deliberation-gate 스킬 자동 설치 (`~/.claude/skills/deliberation-gate/`)
+This installs the server to `~/.local/lib/mcp-deliberation/` (Windows: `%LOCALAPPDATA%/mcp-deliberation/`), registers it in `~/.claude/.mcp.json` and `~/.gemini/settings.json`, and installs the `deliberation-gate` skill to `~/.claude/skills/`.
 
-### 기타 설치 방법
+Restart Claude Code / Gemini CLI after install. That's it.
+
+**Global install (alternative):**
 
 ```bash
-# 글로벌 설치
-npm install -g @dmsdc-ai/aigentry-deliberation
-deliberation-install
+npm install -g @dmsdc-ai/aigentry-deliberation && deliberation-install
+```
 
-# aigentry-devkit 통합 설치
-npx @dmsdc-ai/aigentry-devkit setup
+**Uninstall:**
 
-# 소스에서 직접 설치
-git clone https://github.com/dmsdc-ai/aigentry-deliberation.git
-cd aigentry-deliberation && npm install && node install.js
+```bash
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install --uninstall
 ```
 
-### 제거
+Removes MCP registrations, installed files, and skill files automatically.
+
+**Diagnostics:**
 
 ```bash
-npx @dmsdc-ai/aigentry-deliberation uninstall
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
 ```
 
-MCP 서버 등록 해제 + 설치 파일 삭제 + 스킬 파일 정리까지 자동 처리됩니다.
+Auto-diagnoses MCP configuration for Claude Code, Codex CLI, and Gemini CLI.
 
 ## Forum Demo
 
-Deliberation이 완료되면 결과를 시각화하는 Forum View를 생성합니다.
+When a deliberation completes, the synthesized result can be visualized as a Forum view.
 
-> **Deliberation = 프로세스, Forum = 출력물.**
-> Deliberation이 끝나면 Forum이 생성되고, 그게 끝입니다.
+> Deliberation is the process. Forum is the output. When deliberation ends, the Forum is generated.
 
 ![Forum Demo](demo/forum/assets/hero.png)
 
-정적 데모를 브라우저에서 확인하려면:
-
 ```bash
 open demo/forum/index.html
 ```
 
-## Diagnostics
-
-MCP 연결 문제 자동 진단:
-
-```bash
-npx @dmsdc-ai/aigentry-deliberation doctor
-```
-
-Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제를 진단합니다.
-
 ## MCP Tools
 
 | Tool | Description |
@@ -101,22 +67,25 @@ Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제
 | `deliberation_synthesize` | Generate synthesis report |
 | `deliberation_status` | Check session status |
 | `deliberation_context` | Load project context |
+| `deliberation_inject_context` | Inject structured context or experiment history into an active session |
 | `deliberation_history` | View discussion history |
 | `deliberation_list_active` | List active sessions |
 | `deliberation_list` | List archived sessions |
 | `deliberation_reset` | Reset session(s) |
 | `deliberation_speaker_candidates` | List available speakers |
 | `deliberation_confirm_speakers` | Confirm the exact user-selected speaker set |
-| `deliberation_browser_llm_tabs` | List browser LLM tabs |
-| `deliberation_browser_auto_turn` | Auto-send turn to browser LLM |
+| `deliberation_browser_llm_tabs` | List open browser LLM tabs |
+| `deliberation_browser_auto_turn` | Auto-send turn to a browser LLM via CDP |
 | `deliberation_route_turn` | Route turn to appropriate transport |
-| `deliberation_request_review` | Request code review |
-| `deliberation_cli_auto_turn` | Auto-send turn to CLI speaker |
+| `deliberation_run_until_blocked` | Auto-run mixed transports until completion or a manual block |
+| `deliberation_request_review` | Request code review from deliberation participants |
+| `deliberation_cli_auto_turn` | Auto-send turn to a CLI speaker |
+| `deliberation_ingest_remote_reply` | Ingest a reply from a remote participant with explicit source metadata |
 | `deliberation_cli_config` | Configure CLI settings |
 
 ## Start Flow
 
-Manual participant selection is enforced for both CLI speakers and telepty sessions.
+Speaker selection is enforced before a session can start. Raw candidate tokens cannot initiate a deliberation.
 
 ```text
 1. deliberation_speaker_candidates(...)
@@ -125,18 +94,6 @@ Manual participant selection is enforced for both CLI speakers and telepty sessi
 4. deliberation_start(selection_token: "<confirmed-token>", speakers: [...])
 ```
 
-Raw candidate tokens cannot start a deliberation.
-
-## Telepty Transport
-
-Telepty-managed sessions are now routed through the telepty bus instead of raw PTY inject guidance.
-
-- `deliberation_route_turn` publishes a typed `turn_request` envelope on `ws://localhost:3848/api/bus`
-- transport delivery is tracked with a 5-second `inject_written` ack window
-- semantic completion is tracked with a 60-second self-submit window
-- `session_health` bus events are cached for operator visibility
-- `deliberation_synthesize` validates and emits typed `deliberation_completed` envelopes for downstream automation
-
 ## Speaker Ordering Strategies
 
 | Strategy | Description |
@@ -155,105 +112,154 @@ Telepty-managed sessions are now routed through the telepty bus instead of raw P
 | `researcher` | Data, benchmarks, references |
 | `free` | No role constraint (default) |
 
-### Supported CLI Speakers
+## Supported CLI Speakers
 
 | CLI | Command | Status |
 |-----|---------|--------|
-| Claude Code | `claude` | ✅ Tested |
-| Codex CLI | `codex` | ✅ Tested |
-| Gemini CLI | `gemini` | ✅ Tested |
-| Aider | `aider` | 🔧 Supported |
-| Cursor Agent | `cursor` | 🔧 Supported |
-| OpenCode | `opencode` | 🔧 Supported |
-| Continue | `continue` | 🔧 Supported |
+| Claude Code | `claude` | Tested |
+| Codex CLI | `codex` | Tested |
+| Gemini CLI | `gemini` | Tested |
+| Aider | `aider` | Supported |
+| Cursor Agent | `cursor` | Supported |
+| OpenCode | `opencode` | Supported |
+| Continue | `continue` | Supported |
 
-### Supported Browser LLMs
+## Supported Browser LLMs
 
 | Provider | Transport | Status |
 |----------|-----------|--------|
-| ChatGPT | CDP / Clipboard | ✅ Tested |
-| Claude Web | CDP / Clipboard | ✅ Tested |
-| Gemini Web | CDP / Clipboard | ✅ Tested |
-| DeepSeek | CDP / Clipboard | ✅ Tested |
-| Qwen | CDP / Clipboard | ✅ Tested |
-| Poe | CDP / Clipboard | ✅ Tested |
-| Copilot | CDP / Clipboard | 🔧 Supported |
-| Perplexity | CDP / Clipboard | 🔧 Supported |
-| Mistral | CDP / Clipboard | 🔧 Supported |
-| Grok | CDP / Clipboard | 🔧 Supported |
-| HuggingChat | CDP / Clipboard | 🔧 Supported |
-
-### deliberation-gate (Superpowers Integration)
-
-Inserts multi-AI verification gates at key [superpowers](https://github.com/obra/superpowers) workflow decision points.
+| ChatGPT | CDP / Clipboard | Tested |
+| Claude Web | CDP / Clipboard | Tested |
+| Gemini Web | CDP / Clipboard | Tested |
+| DeepSeek | CDP / Clipboard | Tested |
+| Qwen | CDP / Clipboard | Tested |
+| Poe | CDP / Clipboard | Tested |
+| Copilot | CDP / Clipboard | Supported |
+| Perplexity | CDP / Clipboard | Supported |
+| Mistral | CDP / Clipboard | Supported |
+| Grok | CDP / Clipboard | Supported |
+| HuggingChat | CDP / Clipboard | Supported |
+
+## Examples
+
+See [`examples/`](examples/) for working session scripts and synthesis output samples.
+
+## Experiment Retrospectives
+
+For autoresearch-style keep/discard reviews, inject a compact experiment bundle after the session starts instead of bloating `topic`.
+
+Guidelines:
+- Keep injected JSON around 1.5–2KB
+- Include only the last 3–5 relevant experiments
+- Keep `key_changes` to at most 3 scalar before/after pairs
+- Reference bulky artifacts (`results.tsv`, full `program.md`, JSONL logs) by path only
+
+```text
+deliberation_start(...)
+deliberation_inject_context(
+  session_id: "experiment-review-123",
+  speaker: "dustcraw",
+  context: "{\"past_experiments\":[{\"experiment_id\":\"dg-20260310-001\",\"signal_kind\":\"INTEREST_DRIFT\",\"patch_summary\":\"Raised relevanceThreshold from 0.30 to 0.35\",\"patch_kind\":\"config\",\"key_changes\":{\"relevanceThreshold\":{\"before\":0.3,\"after\":0.35}},\"score\":0.08,\"score_label\":\"promotion_rate_delta\",\"metric_name\":\"promotion_rate_delta\",\"metric_delta\":0.08,\"verdict\":\"positive\",\"followup_action\":\"kept\",\"reasoning\":\"Threshold raise reduced noise; promotion quality improved 8%\"}],\"experiment_count\":1,\"success_rate\":1.0}"
+)
+```
+
+Synthesis output with an explicit experiment verdict:
+
+```json
+{
+  "summary": "Lower the blast radius and re-run with stricter constraints.",
+  "decisions": [
+    "Keep the experiment loop bounded to one editable file",
+    "Retry after restoring the failing test baseline"
+  ],
+  "actionable_tasks": [
+    { "id": 1, "task": "Tighten editable globs", "priority": "high" }
+  ],
+  "experiment_outcome": {
+    "verdict": "modify",
+    "suggested_action": "iterate",
+    "confidence": 0.78,
+    "measurement_window_hours": 24
+  }
+}
+```
+
+## deliberation-gate (Superpowers Integration)
+
+Installs a skill that inserts multi-AI verification gates at key [superpowers](https://github.com/obra/superpowers) workflow decision points.
 
 **Scenarios:**
-- **brainstorming** → multi-AI design validation before writing plans
-- **code-review** → multi-AI review via `deliberation_request_review`
-- **debugging** → multi-AI hypothesis verification when stuck
+- **brainstorming** — multi-AI design validation before writing plans
+- **code-review** — multi-AI review via `deliberation_request_review`
+- **debugging** — multi-AI hypothesis verification when stuck
 
 **Trigger:** Semi-automatic — skill recommends deliberation, user approves.
 
-**Fallback:** MCP 미설치 시 self-criticism 기반 자가 검증으로 대체 (Silver 등급). MCP 설치 시 멀티-AI 토론 (Gold 등급).
+**Fallback:** Without MCP installed, falls back to self-criticism-based verification. With MCP installed, runs full multi-AI discussion.
 
-**Install:** `npx @dmsdc-ai/aigentry-deliberation install` 실행 시 자동 설치됩니다.
+**Auto-installed** by `deliberation-install`. Manual install:
 
-수동 설치:
 ```bash
 cp skills/deliberation-gate/SKILL.md ~/.claude/skills/deliberation-gate/SKILL.md
 ```
 
 **RFC:** [Prerequisites header for tool-dependent skills](https://github.com/obra/superpowers/issues/589)
 
+## Telepty Transport (Advanced)
+
+For teams using [telepty](https://github.com/dmsdc-ai/telepty) to manage AI sessions, deliberation supports routing turns through the telepty bus — enabling cross-machine and cross-session deliberation flows.
+
+- `deliberation_route_turn` publishes typed `turn_request` envelopes on `ws://localhost:3848/api/bus`
+- `deliberation_run_until_blocked` continues across `cli_respond`, `browser_auto`, and `telepty_bus` speakers until a manual block
+- Transport delivery tracked with a 5-second `inject_written` ack window
+- Semantic completion tracked with a 60-second self-submit window
+- `deliberation_synthesize` validates and emits typed `deliberation_completed` envelopes for downstream automation
+
+### Cross-Machine Event Catalog
+
+- **Guaranteed (daemon-emitted):** `inject_written`, `session_health`, `session_register`, `session.replaced`, `session.idle`, `thread.opened`, `thread.closed`, `handoff.*`, `message_routed`
+- **Best-effort (bus relay only):** `turn_request`, `turn_completed`, `deliberation_completed`
+- `kind` is the canonical event discriminator
+- `target` identifies the telepty session target
+- `payload.prompt` is the canonical prompt field for `turn_request`
+- `source_host` is optional transport metadata for cross-machine tracing
+
+## Remote Reply Ingress
+
+For distributed setups where a remote participant cannot call local MCP tools directly, use the deliberation-owned semantic ingress instead of proxying raw bus events:
+
+```text
+deliberation_ingest_remote_reply(
+  session_id: "...",
+  speaker: "...",
+  turn_id: "...",
+  content: "...",
+  source_machine_id: "peer-01",
+  source_session_id: "remote-gemini-001",
+  transport_scope: "remote_mcp",
+  artifact_refs: ["results.jsonl"]
+)
+```
+
+This preserves explicit provenance rather than inferring semantics from raw bus events.
+
 ## What's New
 
+### v0.0.39
+- Entitlement layer — Free/Pro/Team tier gating for deliberation features
+- Gemini CLI model flags and Codex GPT-5.4 routing improvements
+
 ### v0.0.36
-- **README refresh**: clarified the mandatory TUI speaker-selection flow and the confirmed-token handoff before `deliberation_start`
-- **Telepty candidate docs**: documented active telepty session discovery with lightweight `session_id` + `host/pid` locators instead of heavy persisted process snapshots
-- **Cross-project delivery docs**: clarified that active session lookup now resolves across project state directories, which unblocks cross-project `deliberation_respond` flows
-- **Operator guidance**: documented telepty bus transport as the automation path and unmanaged/manual sessions as the fallback path
+- Clarified mandatory TUI speaker-selection flow and confirmed-token handoff before `deliberation_start`
+- Documented active telepty session discovery with lightweight `session_id` + `host/pid` locators
+- Cross-project delivery: active session lookup now resolves across project state directories
 
 ### v0.0.35
 - **Manual selection enforcement**: `deliberation_confirm_speakers` binds a fresh candidate snapshot to the exact user-picked speaker set before `deliberation_start`
 - **Telepty session candidates**: active telepty sessions appear in speaker discovery with lightweight host/pid locators
-- **Cross-project sessions**: session lookup/load/save now resolves active deliberations across project state directories
 - **Telepty bus routing**: telepty speakers route via typed `turn_request` envelopes with 5s transport and 60s semantic timeout tracking
 - **Structured synthesis envelopes**: `deliberation_synthesize` validates typed payloads before telepty bus publication
-- **Codex CLI hardening**: reduced prompt budgets, lower-friction exec profile, and clearer timeout diagnostics
-- **Packaging**: install path now preserves default config and includes required runtime modules (`clipboard.js`, `decision-engine.js`, `i18n.js`)
-
-### v0.0.24
-- **Role inference**: Heading marker weight increased from +5 to +8, added critic(검증/평가/Review) and researcher(데이터/Data) patterns to reduce false positives
-- **Logging payload**: TURN log includes `suggested_role`, `role_drift`; CLI_TURN log includes `prior_turns`, `effective_timeout`
-- **Vote marker warning**: WARN-level `INVALID_TURN` logged when response lacks [AGREE]/[DISAGREE]/[CONDITIONAL] markers
-- **Auto-deploy**: `postversion` hook auto-installs to MCP server path after `npm version`
-
-### v0.0.23
-- **Vote enforcement**: Turn prompts now require [AGREE]/[DISAGREE]/[CONDITIONAL] markers for reliable consensus measurement
-- **Dynamic CLI timeout**: First CLI invocation gets 180s (cold-start buffer), subsequent turns use default 120s
-- **Runtime logging**: INFO-level lifecycle logging (SESSION_CREATED, TURN, CLI_TURN, SYNTHESIZED) to `runtime.log`
-- **Role inference improvement**: Structural heading markers (e.g., `## 조사 결과` → researcher) with +5 weight prevent false role drift detection
-
-### v0.0.22
-- **Security**: CDP `--remote-allow-origins` restricted to `127.0.0.1:9222` (was `*`)
-- **Security**: Observer CORS restricted to localhost allowlist, server bound to `127.0.0.1`
-- **Performance**: Async sleep for Chrome CDP initialization (was blocking event loop)
-- **Bug fix**: Fabrication guard uses `detectCallerSpeaker()` instead of hardcoded `"claude"`
-- **Bug fix**: CLI reviewer uses per-CLI invocation flags via `CLI_INVOCATION_HINTS`
-- **Bug fix**: Windows monitor state directory path corrected
-- **Memory**: SSE client Map cleanup on disconnect prevents memory leak
-- **Code quality**: Removed unreachable dead code in browser-control-port
-
-## aigentry Ecosystem
-
-aigentry-deliberation is one component of the unified aigentry platform. All packages work together to make AI decisions transparent and auditable.
-
-| Package | Description |
-|---------|-------------|
-| [`@dmsdc-ai/aigentry-brain`](https://github.com/dmsdc-ai/aigentry-brain) | Cross-LLM memory OS |
-| [`@dmsdc-ai/aigentry-devkit`](https://github.com/dmsdc-ai/aigentry-devkit) | Developer tools and hooks |
-| [`aigentry-registry`](https://github.com/dmsdc-ai/aigentry-registry) | AI agent evaluation (Python) |
-| [`aigentry-ssot`](https://github.com/dmsdc-ai/aigentry-ssot) | MCP contract schemas |
+- **Codex CLI hardening**: reduced prompt budgets, lower-friction exec profile, clearer timeout diagnostics
 
 ## License
 

package/doctor.js

@@ -15,7 +15,7 @@
  *
  * Usage:
  *   node doctor.js
- *   npx @dmsdc-ai/aigentry-deliberation doctor
+ *   npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
  */
 
 import fs from "node:fs";
@@ -209,7 +209,7 @@ function suggestFix(serverName, server, issue) {
   switch (issue) {
     case "path_missing":
       if (serverName === "deliberation" || serverName === "mcp-deliberation") {
-        return `npx @dmsdc-ai/aigentry-deliberation install`;
+        return `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`;
       }
       if (serverName.includes("brain") || serverName.includes("aigentry-brain")) {
         return `npx @dmsdc-ai/aigentry-brain install`;
@@ -223,7 +223,7 @@ function suggestFix(serverName, server, issue) {
     case "temp_path": {
       const tempArg = (server.args || []).find((a) => isTempPath(a));
       if (serverName === "deliberation" || serverName === "mcp-deliberation") {
-        return `npx @dmsdc-ai/aigentry-deliberation install  # reinstall to permanent path`;
+        return `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install  # reinstall to permanent path`;
       }
       if (serverName.includes("brain") || serverName.includes("aigentry-brain")) {
         return `npx @dmsdc-ai/aigentry-brain install  # reinstall to permanent path`;
@@ -357,7 +357,7 @@ function runDiagnostics() {
         if (mod.includes("aigentry-brain") || mod.includes("brain")) {
           fix = `npx @dmsdc-ai/aigentry-brain install  # temporary path → reinstall to permanent path`;
         } else if (mod.includes("deliberation") || mod.includes("mcp-deliberation")) {
-          fix = `npx @dmsdc-ai/aigentry-deliberation install  # temporary path → reinstall to permanent path`;
+          fix = `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install  # temporary path -> reinstall to permanent path`;
         } else {
           fix = `# temporary path (${mod}) — change to permanent path in MCP config`;
         }
@@ -387,7 +387,7 @@ function runDiagnostics() {
   } else {
     totalIssues++;
     console.log(`   ❌ Server file not found: ${selfPath}`);
-    console.log(`      fix: npx @dmsdc-ai/aigentry-deliberation install`);
+    console.log(`      fix: npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`);
   }
 
   // Check node_modules
@@ -407,7 +407,7 @@ function runDiagnostics() {
   } catch {
     totalIssues++;
     console.log(`   ❌ Syntax error detected`);
-    console.log(`      fix: npx @dmsdc-ai/aigentry-deliberation install`);
+    console.log(`      fix: npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`);
   }
 
   // ── Summary ──

package/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Practical examples for using the aigentry-deliberation MCP server.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `basic-deliberation.md` | Start a session, collect turns, and synthesize a decision |
+| `code-review.md` | Multi-AI code review using `deliberation_request_review` |
+| `structured-synthesis.md` | Structured JSON output (ExecutionContractV2) for automation |
+| `browser-automation.md` | Include ChatGPT / Gemini via CDP browser automation |
+
+## Prerequisites
+
+- aigentry-deliberation MCP server registered (`node install.js`)
+- At least one speaker available (CLI session, browser tab, or telepty session)
+
+## Quick Start
+
+1. Call `deliberation_speaker_candidates` to discover available speakers.
+2. Confirm speakers with `deliberation_confirm_speakers`.
+3. Start the session with `deliberation_start`.
+4. Route turns with `deliberation_route_turn` or `deliberation_run_until_blocked`.
+5. Call `deliberation_synthesize` to get a structured decision.

package/examples/basic-deliberation.md

@@ -0,0 +1,99 @@
+# Basic Deliberation
+
+A complete walkthrough of starting a deliberation session from scratch.
+
+**Topic:** Should we use REST or GraphQL for our new API?
+
+---
+
+## Step 1 — Discover Available Speakers
+
+```json
+// Tool: deliberation_speaker_candidates
+{}
+```
+
+**Response (example):**
+```json
+{
+  "candidates": [
+    { "id": "claude-opus", "name": "Claude Opus", "transport": "cli_respond" },
+    { "id": "gemini-pro", "name": "Gemini Pro", "transport": "cli_respond" }
+  ]
+}
+```
+
+---
+
+## Step 2 — Confirm Speakers
+
+```json
+// Tool: deliberation_confirm_speakers
+{
+  "speaker_ids": ["claude-opus", "gemini-pro"]
+}
+```
+
+---
+
+## Step 3 — Start the Session
+
+```json
+// Tool: deliberation_start
+{
+  "topic": "Should we use REST or GraphQL for our new API?",
+  "context": "We are building a mobile app with complex nested data requirements and 3 client types.",
+  "max_turns": 4
+}
+```
+
+**Response:**
+```json
+{ "deliberation_id": "delib-a1b2c3", "status": "active", "turn": 0 }
+```
+
+---
+
+## Step 4 — Collect Turns (2 speakers)
+
+```json
+// Tool: deliberation_respond  (speaker: claude-opus)
+{
+  "deliberation_id": "delib-a1b2c3",
+  "speaker_id": "claude-opus",
+  "content": "GraphQL is the stronger choice here. With 3 client types each needing different fields, GraphQL eliminates over-fetching and lets clients declare exactly what they need. The nested data model maps naturally to GraphQL resolvers."
+}
+```
+
+```json
+// Tool: deliberation_respond  (speaker: gemini-pro)
+{
+  "deliberation_id": "delib-a1b2c3",
+  "speaker_id": "gemini-pro",
+  "content": "REST is simpler to cache and easier for teams already familiar with HTTP conventions. For a mobile app, HTTP/2 with REST and sparse fieldsets can achieve similar efficiency. Consider GraphQL only if query flexibility is genuinely required at launch."
+}
+```
+
+---
+
+## Step 5 — Synthesize the Decision
+
+```json
+// Tool: deliberation_synthesize
+{
+  "deliberation_id": "delib-a1b2c3"
+}
+```
+
+**Response:**
+```json
+{
+  "verdict": "GraphQL recommended with phased rollout",
+  "confidence": 0.82,
+  "actionable_tasks": [
+    { "id": 1, "task": "Set up Apollo Server with schema-first design", "priority": "high" },
+    { "id": 2, "task": "Define GraphQL types for core entities", "priority": "high" },
+    { "id": 3, "task": "Add REST compatibility layer for legacy clients", "priority": "medium" }
+  ]
+}
+```