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

docs/api/COUNCILS.md

@@ -0,0 +1,51 @@
+# Councils Pipeline
+
+Flynn supports a deterministic dual-council orchestration pipeline (`council.run`) that runs two isolated groups (`D`, `P`) through ideation, assessment, grounding, bridge exchange, and meta merge.
+
+## Guarantees
+
+- Bridge-only cross-council communication.
+- Strict JSON schemas for artifacts (`.strict()` validation).
+- Deterministic orchestrator-owned idea IDs (`D.r1.01`, `P.r2.03`, ...).
+- Canonical JSON serialization for hashing and reproducibility.
+- Deterministic writer-side brief + diff generation (model does not write diffs).
+
+## Key Artifacts
+
+- `IdeaCard` (content + optional grounding, schema versioned)
+- `IdeaAssessment` (scores/decision per `idea_id`, schema versioned)
+- `CouncilBrief` (`v1`/`v2` group artifact)
+- `BridgePacket` (whitelisted transfer contract)
+- `CouncilDiff` (code-computed deterministic diff)
+- `MetaSelection` (JSON-only selection/merge record)
+- `CouncilRunResult` (`pipeline_version`, hashes, trace, stop snapshot)
+
+## Tool Interface
+
+`council.run` input:
+
+```json
+{
+  "task": "string",
+  "constraints": "object|string?",
+  "success_definition": "string?",
+  "budget": "object?",
+  "timebox": "string|number?",
+  "output_format": "string?",
+  "max_rounds": "number?",
+  "session_id": "string?"
+}
+```
+
+## Determinism Notes
+
+- `prompt_payload_hash` is computed from canonical JSON payload passed to model.
+- `artifact_hash` is computed from canonical validated artifact JSON.
+- Trace ordering is deterministic (`phase_index`, then `call_id`), independent of async completion order.
+
+## Safety Rules
+
+- Unknown schema keys are rejected.
+- Meta stage may reference existing IDs only.
+- Bridge packets are parse+validate+whitelist+re-serialize before exchange.
+- On bridge validation failure, phase 2 is skipped (fail closed).