@dmsdc-ai/aigentry-deliberation 0.0.39 → 0.0.41

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 --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 --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install --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 --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
-```
-
-Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제를 진단합니다.
-
 ## MCP Tools
 
 | Tool | Description |
@@ -101,25 +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 external experiment history into an active session |
+| `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_run_until_blocked` | Auto-run mixed transports until completion or a manual block |
-| `deliberation_request_review` | Request code review |
-| `deliberation_cli_auto_turn` | Auto-send turn to CLI speaker |
-| `deliberation_ingest_remote_reply` | Canonical semantic ingress for remote replies with explicit source metadata |
+| `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(...)
@@ -128,72 +94,65 @@ 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`
-- `deliberation_run_until_blocked` can continue across `cli_respond`, `browser_auto`, and `telepty_bus` speakers until a manual block is reached
-- 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
-- telepty envelopes now carry top-level `version: 1` and optional `source_host`
-
-### Cross-Machine Event Catalog
-
-Canonical boundary split with telepty:
-
-- **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
+## Speaker Ordering Strategies
 
-If a remote participant cannot call local MCP tools directly, do **not** proxy-synthesize a reply. Use the deliberation-owned semantic ingress:
+| Strategy | Description |
+|----------|-------------|
+| `cyclic` | Sequential round-robin (default) |
+| `random` | Random selection each turn |
+| `weighted-random` | Less-spoken speakers prioritized |
 
-```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"]
-)
-```
+## Persona Roles
 
-This preserves explicit provenance instead of inferring semantics from raw bus events.
+| Role | Focus |
+|------|-------|
+| `critic` | Risk analysis, weaknesses, counterarguments |
+| `implementer` | Technical feasibility, code design |
+| `mediator` | Consensus building, synthesis |
+| `researcher` | Data, benchmarks, references |
+| `free` | No role constraint (default) |
 
-### Gemini Recovery
+## Supported CLI Speakers
 
-Canonical repair path today is still installer-based:
+| 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 |
 
-```bash
-npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
-npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
-```
+## Supported Browser LLMs
 
-Use doctor first; if Gemini MCP registration/path/runtime drift is detected, rerun install and restart Gemini CLI.
+| 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 |
+
+## 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`.
 
-Recommended rules:
-- keep the injected JSON around `1.5KB` to `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
-
-Example:
+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(...)
@@ -204,7 +163,7 @@ deliberation_inject_context(
 )
 ```
 
-If your synthesis needs an explicit experiment verdict, `structured` can now include `experiment_outcome`:
+Synthesis output with an explicit experiment verdict:
 
 ```json
 {
@@ -214,7 +173,7 @@ If your synthesis needs an explicit experiment verdict, `structured` can now inc
     "Retry after restoring the failing test baseline"
   ],
   "actionable_tasks": [
-    { "id": 1, "task": "Tighten editable globs", "project": "aigentry-devkit", "priority": "high" }
+    { "id": 1, "task": "Tighten editable globs", "priority": "high" }
   ],
   "experiment_outcome": {
     "verdict": "modify",
@@ -225,123 +184,82 @@ If your synthesis needs an explicit experiment verdict, `structured` can now inc
 }
 ```
 
-## Speaker Ordering Strategies
+## deliberation-gate (Superpowers Integration)
 
-| Strategy | Description |
-|----------|-------------|
-| `cyclic` | Sequential round-robin (default) |
-| `random` | Random selection each turn |
-| `weighted-random` | Less-spoken speakers prioritized |
+Installs a skill that inserts multi-AI verification gates at key [superpowers](https://github.com/obra/superpowers) workflow decision points.
 
-## Persona Roles
+**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
 
-| Role | Focus |
-|------|-------|
-| `critic` | Risk analysis, weaknesses, counterarguments |
-| `implementer` | Technical feasibility, code design |
-| `mediator` | Consensus building, synthesis |
-| `researcher` | Data, benchmarks, references |
-| `free` | No role constraint (default) |
+**Trigger:** Semi-automatic — skill recommends deliberation, user approves.
 
-### Supported CLI Speakers
+**Fallback:** Without MCP installed, falls back to self-criticism-based verification. With MCP installed, runs full multi-AI discussion.
 
-| 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 |
+**Auto-installed** by `deliberation-install`. Manual install:
 
-### Supported Browser LLMs
+```bash
+cp skills/deliberation-gate/SKILL.md ~/.claude/skills/deliberation-gate/SKILL.md
+```
 
-| 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.
+**RFC:** [Prerequisites header for tool-dependent skills](https://github.com/obra/superpowers/issues/589)
 
-**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
+## Telepty Transport (Advanced)
 
-**Trigger:** Semi-automatic — skill recommends deliberation, user approves.
+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.
 
-**Fallback:** MCP 미설치 시 self-criticism 기반 자가 검증으로 대체 (Silver 등급). MCP 설치 시 멀티-AI 토론 (Gold 등급).
+- `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
 
-**Install:** `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install` 실행 시 자동 설치됩니다.
+### Cross-Machine Event Catalog
 
-수동 설치:
-```bash
-cp skills/deliberation-gate/SKILL.md ~/.claude/skills/deliberation-gate/SKILL.md
+- **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"]
+)
 ```
 
-**RFC:** [Prerequisites header for tool-dependent skills](https://github.com/obra/superpowers/issues/589)
+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/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" }
+  ]
+}
+```