docs(councils): add quickstart, API doc, and state tracking

README.md

@@ -520,6 +520,7 @@ pnpm tui:fs
 | `/reset` | Clear history |
 | `/status` | Show session info |
 | `/research <task>` | Delegate a task to `agent_configs.research` |
+| `/council <task>` | Run dual D/P councils pipeline with bridge+meta merge |
 | `/compact` | Compact conversation context |
 | `/usage` | Show token usage and cost |
 | `/context` | Show estimated context-window usage |
@@ -591,6 +592,49 @@ look up best practices for k8s backup retention
 If the `research` agent is not configured, Flynn returns a setup hint with available agent names.
 `flynn setup` can configure this under the Security section.
 
+### Councils Pipeline Quickstart
+
+Enable deterministic dual-council orchestration and define required role agents:
+
+```yaml
+councils:
+  enabled: true
+
+agent_configs:
+  council_d_arbiter:
+    model_tier: default
+    tool_profile: messaging
+    system_prompt: You are the D arbiter. Score and shortlist ideas conservatively.
+  council_d_freethinker:
+    model_tier: default
+    tool_profile: messaging
+    system_prompt: You are the D freethinker. Generate and ground ideas in JSON only.
+  council_p_arbiter:
+    model_tier: default
+    tool_profile: messaging
+    system_prompt: You are the P arbiter. Prefer novelty and leverage while scoring.
+  council_p_freethinker:
+    model_tier: default
+    tool_profile: messaging
+    system_prompt: You are the P freethinker. Generate contrarian ideas in JSON only.
+  council_meta_arbiter:
+    model_tier: default
+    tool_profile: messaging
+    system_prompt: You are the meta arbiter. Select from provided IDs only; no novel mechanisms.
+```
+
+Run from chat:
+
+```bash
+/council design a 30-day plan to cut CI flakiness by 50%
+```
+
+Or via tools:
+
+```json
+{"name":"council.run","args":{"task":"design a 30-day plan to cut CI flakiness by 50%"}}
+```
+
 ## Running as Service
 
 ```bash