the-high-council 0.7.5 → 0.7.7

package/.env.example

@@ -3,7 +3,6 @@
 ANTHROPIC_API_KEY=
 OPENAI_API_KEY=
 GOOGLE_API_KEY=
-XAI_API_KEY=
 MISTRAL_API_KEY=
 DEEPSEEK_API_KEY=
 GROQ_API_KEY=
@@ -14,6 +13,6 @@ ZAI_API_KEY=
 
 # Default per-run spend ceiling in USD. Overridden per run by --max-usd.
 # A run stops cleanly before any stage that could take it past this, and
-# resumes with a higher ceiling. Unset means $5. Use --max-usd none to run
+# resumes with a higher ceiling. Unset means $7. Use --max-usd none to run
 # without a ceiling.
-MAX_USD_PER_RUN=5
+MAX_USD_PER_RUN=7

package/README.md

@@ -1,24 +1,29 @@
 # The High Council
 
-[![Test](https://github.com/muad-yasin/the-high-council-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/muad-yasin/the-high-council-mcp/actions/workflows/test.yml)
+A planning harness that runs one idea past several AI models from different labs, makes them
+argue about software engineering, architecture, specific features, roadmaps and philosophy, and
+stops at a checkable result at an estimated price, with a variable number of debate rounds, model
+seats and labs (except xAI) and variable token limits per response and model.
 
 See it work right now - no keys, no setup, no cost:
 
-    npx github:muad-yasin/the-high-council-mcp council demo
-
-Add it to Claude Code as an MCP server the same way:
+    npx the-high-council council demo
 
-    claude mcp add council -- npx -y github:muad-yasin/the-high-council-mcp council --mcp
+The demo takes one example request (a tool that renames holiday photos by date) through every
+stage: blind proposals, an anonymised debate in which one proposal is withdrawn and two are
+amended, a panel that splits in round 1 and signs off in round 2, and the handoff file. Every
+model reply in it is written in advance; what is real is the code that runs the stages around
+them.
 
-*(An npm package is coming - not yet published. Both lines above work today, straight from this
-GitHub repo, no npm account needed.)*
+Add it to Claude Code as an MCP server:
 
-A planning harness that runs one idea past several AI models from different labs, makes them
-argue about it on the record, and stops at a checkable result.
+    claude mcp add council -- npx -y the-high-council council --mcp
 
 Runs as an **MCP server** (so an agent like Claude Code can drive it) or as a **CLI**. Bring your
-own API keys. Nothing is resold, nothing is hosted for you, and no key ever leaves your machine.
-Run `npx github:muad-yasin/the-high-council-mcp council doctor` to see which of your own keys are
+own API keys. Nothing is resold, nothing is hosted for you, and your keys go only to the
+providers you choose, never to us.
+
+Run `npx the-high-council council doctor` to see which of your own keys are
 set, which shipped chains you can already run with them, and what each would cost - before
 spending anything.
 
@@ -28,10 +33,65 @@ spending anything.
 > disagreement between models *visible and recorded* instead of averaged away - you can read who
 > objected to what, who withdrew a proposal under argument, and who held their position.
 
-**A visual walkthrough of all of this - the stages, one real run's debate board, and what that run
-cost - is at [muad-yasin.github.io/the-high-council-mcp](https://muad-yasin.github.io/the-high-council-mcp/).**
-A different write-up, built around one run's actual debate board, is at
-[sower-industries.de/en/MCP/](https://sower-industries.de/en/MCP/).
+## Your first ten minutes
+
+New to API keys, or to this? This path costs nothing until step 4, and step 4 tells you the price
+before anything is spent.
+
+1. **Watch one.** `npx the-high-council demo` walks an example request through every stage with
+   scripted replies. No key, no network, $0.
+2. **Make it yours.** `npx the-high-council init` writes `tasks/my-first-task.md` (edit it into
+   your own idea, in plain words) and `chains/my-first-chain.json`, and runs a $0 mock pass so
+   you can look inside a real run folder.
+3. **Find the least setup.** `npx the-high-council doctor` lists what your keys can run. Its
+   "Start here" block names the chains that need **one key only**: a single `OPENROUTER_API_KEY`
+   (one account at [openrouter.ai](https://openrouter.ai) that reaches many labs' models) is
+   enough for a seven-lab panel. Put the key in a file called `.env` in the folder you run from,
+   as `OPENROUTER_API_KEY=...`, and add `.env` to your `.gitignore` so it is never committed.
+4. **Price it, then run it.** Add `--dry-run` to see the worst-case price for your task, then run
+   it without:
+
+       npx the-high-council --task tasks/my-first-task.md --chain cheap-7-v2 --dry-run
+       npx the-high-council --task tasks/my-first-task.md --chain cheap-7-v2
+
+   Every run stops before it would pass its spend cap ($7 unless you set `--max-usd`). A run
+   stopped by the cap keeps what it paid for but has no plan yet, so pick a cap at or above the
+   dry run's price. A panel that signs off early costs less than the worst case.
+
+   The plan lands in `runs/<time>/deliverable.md`; the argument behind it is in `BOARD.md`.
+
+No key and no budget? A chain can run on models on your own machine through
+[Ollama](#local-models-ollama-lm-studio-) at $0, if your computer can run them.
+Everywhere below, `council` means `npx the-high-council` unless you installed it globally.
+
+## Words used here
+
+- **Lab** - a company that makes AI models (Anthropic, OpenAI, Google, DeepSeek, ...). "Different
+  labs" means models trained by different companies.
+- **Provider** - where a call goes and who bills it: a lab's own API, OpenRouter (many labs, one
+  key and one bill), or `ollama` (your own machine).
+- **API key** - a secret string from a provider that lets a program use your account there. You
+  pay the provider for what the program uses; nobody else sees the key.
+- **Seat** - one job in a run, filled by one model: the one that writes criteria, the builder, a
+  critic, and so on.
+- **Chain** - a JSON file that says which model sits in which seat and which stages run. Pick one
+  with `--chain`; `council doctor` lists them all.
+- **Task** - your request, a plain text file in `tasks/`. No format.
+- **Criteria** - yes/no checks the plan has to pass, written from your task before anyone plans.
+- **Proposal, debate** - each lab suggests parts of the plan without seeing the others, then
+  they read each other's (with names hidden) and object, support or merge.
+- **Panel, round, sign-off** - the critics grade the draft against the criteria; each failed check
+  goes back for a revision, which is one round. Sign-off means a critic found nothing failing.
+- **Dry run** - `--dry-run`: price a run, call nothing.
+- **Spend cap** - the most one run may cost. It is checked before every paid call.
+- **Mock** - a fake provider with scripted replies, for trying the machinery for free.
+- **External** - a seat that waits for a person or another agent (such as your Claude Code session)
+  to answer it from a file.
+- **Handoff** - `HANDOFF.md`, the build instructions a coding agent works from.
+
+**A visual write-up of all of this, built around one real run, is at
+[sower-industries.de/MCP](https://sower-industries.de/MCP).** What changed in each release:
+[CHANGELOG.md](CHANGELOG.md).
 
 ## How it works
 
@@ -58,11 +118,13 @@ withdrawal), `HANDOFF.md`, a per-lab scoreboard, and the real token/cost account
 ### Reading a run with a program
 
 `BOARD.md` is for people. **`report.json` is the same board, structured** - if you are building
-anything on top of a run, read that instead. Do not parse the markdown.
+anything on top of a run, read that instead. Do not parse the markdown. The format is versioned
+(`schemaVersion`) and published as a JSON Schema, `schemas/report-v1.json`; which fields are stable,
+which are experimental, and how versions change: [docs/report-format.md](docs/report-format.md).
 
 ```jsonc
 {
-  "runId": "...", "chain": "...", "passed": false, "maxUsd": 5,
+  "schemaVersion": 1, "runId": "...", "chain": "...", "passed": false, "maxUsd": 5,
   "criteria":  [ "each acceptance criterion, as written before the debate" ],
   "questions": [ { "question": "...", "why": "...", "default": "..." } ],  // null if the chain skipped them
   "proposals": [ { "id": "DEEPSEEK-1", "lab": "deepseek", "model": "...",
@@ -76,7 +138,26 @@ anything on top of a run, read that instead. Do not parse the markdown.
     "replies": [ { "id": "DEEPSEEK-1", "action": "keep|amend|withdraw",
                    "text": "...", "replaced_by": "GLM-1" } ]
   },
-  "signoff": [ { "provider": "qwen", "model": "...", "signedOff": false,
+  // Only on chains with `alternatives: { enabled: true }`: one whole architecture per lab, written
+  // blind before the skeleton, and the same post/reply board the proposals get.
+  "alternatives": {
+    "items":   [ { "id": "GLM-ALT", "lab": "glm", "model": "...", "name": "...", "shape": "...",
+                   "key_tradeoffs": "...", "bad_at": "...", "amended": true, "withdrawn": false } ],
+    "posts":   [ { "by": "qwen", "on": "GLM-ALT", "stance": "object|support|merge", "text": "..." } ],
+    "replies": [ { "id": "GLM-ALT", "action": "keep|amend|withdraw", "text": "..." } ],
+    "dropouts": [ { "lab": "...", "model": "...", "stage": "alternatives", "reason": "..." } ]
+  },
+  // Only on chains with `argued: { enabled: true }` (off by default, on in no shipped chain): the
+  // "How this plan was argued" section, written to ARGUED.md next to deliverable.md (never inside it)
+  // by the handoff seat, from a fact pack of this run's own record. unknown_refs / unknown_labs are
+  // ids and labs it named that the run never had; each is also a line in WARNINGS.md.
+  "argued": {
+    "file": "ARGUED.md",
+    "facts_counts": { "labs": 7, "alternatives": 7, "proposals": 14, "objections": 9, "...": 0 },
+    "unknown_refs": [], "unknown_labs": [], "missing_labs": [], "missing_sections": [],
+    "refs_cited": 23, "ok": true
+  },
+  "signoff": [ { "lab": "qwen", "provider": "qwen", "model": "...", "signedOff": false,
                  "objections": [ { "criterion": "...", "problem": "...", "fix": "..." } ] } ],
   "lastCritique": { "meets": false, "failures": [ { "criterion": "...", "lab": "qwen" } ] },
   "scoreboard": {
@@ -108,6 +189,8 @@ those plus `text` and may carry more (an `amend` often brings a `how`). `replace
 when the action is `withdraw`. `proposals[]` likewise carries `withdrawn` / `amended` /
 `replaced_by` only when they apply. Read defensively: check for a field, do not assume it.
 
+`signoff[].lab` is the seat's lab; `signoff[].provider` holds the same value under an older,
+misleading name and is deprecated (kept until the report format's version 2).
 `signoff[].objections` is why a seat declined, on the seat's own record. `signedOff: null` means
 the seat gave no usable reply and abstained - neither a pass nor an objection, and `objections` is
 `null` rather than empty so the two stay apart. A seat that agreed has an empty list.
@@ -115,7 +198,7 @@ The same objections also appear flattened in `lastCritique.failures[]`, tagged w
 the reviser wants the union across the whole panel. Both are built in one pass; they cannot drift.
 
 **Before you publish a run,** note that `report.json` records `task` as the path to your task file
-on your own disk. Nothing transmits it anywhere - but if you are rendering a board onto a public
+(relative to where you started the run, never absolute). Nothing transmits it anywhere - but if you are rendering a board onto a public
 page, drop that field. The debate itself is the part worth showing.
 
 ## Requirements
@@ -125,22 +208,59 @@ page, drop that field. The debate itself is the part worth showing.
 
 ## Setup
 
+Nothing to install beyond Node: `npx the-high-council council <command>` fetches the published
+package and runs it. To keep a `council` command on your PATH instead:
+
 ```bash
-git clone https://github.com/muad-yasin/the-high-council-mcp.git
-cd the-high-council-mcp
-npm install
-cp .env.example .env
+npm install -g the-high-council
+council doctor
 ```
 
-Fill in `.env` with only the keys your chosen chain needs. Supported providers:
+`council` reads and writes in the directory you run it from: `.env` for keys, `tasks/` for
+requests, `runs/` for output, and a `chains/` of your own there takes precedence over the bundled
+ones. Put only the keys your chosen chain needs in that `.env`, one `NAME=value` per line
+(`.env.example` in the package lists them all). Supported providers:
 
 `ANTHROPIC_API_KEY` · `OPENAI_API_KEY` · `GOOGLE_API_KEY` · `MISTRAL_API_KEY` ·
 `DEEPSEEK_API_KEY` · `GROQ_API_KEY` · `TOGETHER_API_KEY` · `COHERE_API_KEY` ·
-`OPENROUTER_API_KEY` · `ZAI_API_KEY` · `XAI_API_KEY`
+`OPENROUTER_API_KEY` · `ZAI_API_KEY`
+
+xAI/Grok and Kimi/Moonshot are never seated, and neither is a router id (`openrouter/auto`, the
+Pareto Code router) that could route to them: chain-lint refuses such a chain and the run itself
+refuses such a seat, with no override. There is no `xai` provider.
 
 The CLI refuses to start if any seat in the chosen chain is missing its key, rather than failing
 halfway through a paid run. `ollama` (below) is the one exception - it needs no key at all.
 
+### From source
+
+```bash
+git clone https://github.com/muad-yasin/the-high-council-mcp.git
+cd the-high-council-mcp
+npm install
+cp .env.example .env
+```
+
+In a clone, `node src/cli.js` does what `council` does, on the current source rather than the
+published package. `npx github:muad-yasin/the-high-council-mcp council demo` runs the current
+source without cloning.
+
+### Standalone binaries (build them yourself)
+
+There are no published binary downloads yet. From a clone you can build a single-file `council`
+that needs no Node install to run: a Linux binary, a Linux AppImage, and a Windows `.exe`, all
+built on Linux.
+
+```bash
+npm run build:bin                 # dist/the-high-council-linux, dist/the-high-council-win.exe
+npm run build:appimage            # dist/the-high-council-x86_64.AppImage (downloads a pinned appimagetool)
+npm run smoke:bin -- dist/the-high-council-linux   # demo + an MCP session, offline, $0
+```
+
+Stated plainly: the `.exe` is tested under Wine on Linux, not on a real Windows machine, and none
+of the binaries are code-signed, so Windows SmartScreen will warn. Put `.env` in the directory you
+run the binary from.
+
 ### Local models (Ollama, LM Studio, ...)
 
 A seat can run on a model you're hosting yourself instead of a paid API. Set its provider to
@@ -165,6 +285,15 @@ example chain with every seat local. As with every other seat in this project: B
 BYO-compute here, and no efficacy claim is made about local models versus hosted ones - nothing
 has been measured.
 
+### Final security-review gate
+
+`"security_review": { "enabled": true }` adds one read-only reviewer as the last stage of a chain,
+after the build and everything else. It returns typed findings, and any critical or high finding
+fails the run (exit 7). A reviewer with no usable verdict fails it too (exit 8); that never counts
+as a pass. The default reviewer is `anthropic/claude-fable-5-1` (your key, priced, capped);
+`seats.security_reviewer` can be any seat, including a local `ollama` one as an offline option.
+Full details: [docs/security-review-gate.md](docs/security-review-gate.md).
+
 ## Quick start (CLI)
 
 A task file is the request the council plans against: plain prose, written by you. There is no
@@ -175,17 +304,48 @@ mkdir -p tasks
 echo "Plan the data model for a bookmarking app. Single user, offline-first." > tasks/your-idea.md
 
 # see what's available and what it would cost
-node src/cli.js --help
-npm run dry -- --task tasks/your-idea.md --chain verify
+council --help
+council --task tasks/your-idea.md --chain verify --dry-run
 
 # a real run
-node src/cli.js --task tasks/your-idea.md --chain verify
+council --task tasks/your-idea.md --chain verify
 ```
 
-`tasks/` and `runs/` are both gitignored. Your requests and everything the council writes about
-them stay on your machine - if you fork this repo, you will not accidentally publish them.
+Your requests and everything the council writes about them stay on your machine, in `tasks/` and
+`runs/` under the directory you ran from. In a clone of this repo both are gitignored, so a fork
+will not accidentally publish them.
+
+`verify` is the default when you name no chain: a panel of two labs, a hard two-round cap. It
+needs three keys (Anthropic, OpenAI and Google, one account each). With one OpenRouter key, start
+with `cheap-7-v2` instead; `council doctor` lists every chain that runs on the keys you have.
 
-`verify` is the cheap default: two labs, a hard two-round cap. Start there.
+### Exit codes
+
+Each outcome has its own code, so a script or CI job can branch on it:
+
+| Code | Meaning |
+|---|---|
+| 0 | Finished: a deliverable and `report.json` were written. |
+| 1 | The chain failed lint, or an input is missing (no task file, a resume from the wrong directory). |
+| 2 | Usage error: a flag is missing its value or has an invalid one. |
+| 3 | Paused at an external seat: answer `NEEDS-<stage>.md`, then `--resume`. |
+| 4 | Stopped at the per-run spend cap before the next stage was paid for; resume with a higher `--max-usd`. |
+| 5 | A provider key the chain needs is missing (degradable: set it and run again). |
+| 6 | Fatal: the chain file cannot be parsed, or the audit key cannot be loaded. |
+| 7 | Finished, but the final security review blocked the deliverable. |
+| 8 | Finished, but the final security review could not judge it (never a pass). |
+| 9 | Artifact gate: the task names files whose content it never includes (`BLOCKED-ARTIFACTS.md`). |
+| 10 | Preflight: a seat objected to the task description itself (`STOPPED-preflight.md`). |
+| 11 | PII gate (`--pii-gate hard-stop`): the input matches a PII shape or one of the key formats listed in `src/secret-patterns.js`. |
+| 12 | `policy.json` refused the chain. |
+| 13 | Another process is already running this run folder. |
+| 14 | The task file changed since the run started and `AMENDMENTS.md` does not cover it. |
+| 15 | `--resume` of a run that already finished (it has a `report.json`); nothing is run or spent. |
+| 16 | The run stopped at an unexpected error (a seat that could not be reached, a crash); `STOPPED-error.md` says what, and `--resume` continues from the completed stages. |
+| 17 | A draft (build, revise, dispute, final edit or handoff) was cut off at its token cap, and its one larger-cap retry was cut off too; the fragment is never graded or shipped (`STOPPED-truncated.md`). |
+
+Codes 9-17 were split out or added on 2026-09-23. Before that, several of these outcomes shared a code (2, 5,
+6 or 1).
 
 ### Telling the council what your build session can actually use
 
@@ -211,13 +371,13 @@ before building it."*
 
 ### The spend cap
 
-Every run has a per-run ceiling in USD. It defaults to **$5**, and is checked *before* each paid
+Every run has a per-run ceiling in USD. It defaults to **$7**, and is checked *before* each paid
 stage - a stage that could take the run past the ceiling is never called, so the cap holds rather
 than reporting the overspend afterwards.
 
 ```bash
-node src/cli.js --task tasks/x.md --max-usd 2     # this run stops at $2
-node src/cli.js --task tasks/x.md --max-usd none  # no ceiling
+council --task tasks/x.md --max-usd 2     # this run stops at $2
+council --task tasks/x.md --max-usd none  # no ceiling
 export MAX_USD_PER_RUN=20                         # change the default
 ```
 
@@ -227,17 +387,25 @@ stage it stopped at, and what that stage would have cost. Nothing is half-writte
 with a higher ceiling - completed stages replay from disk and cost nothing the second time:
 
 ```bash
-node src/cli.js --resume runs/<id> --max-usd 10
+council --resume runs/<id> --max-usd 10
 ```
 
+A stage replays only if it would be asked the same thing again: the task text, the chain config
+and the stage's own prompt must all match what it answered. If one changed (you edited the chain,
+or an earlier stage came out differently this time), the stage runs again and its old files move
+into `superseded/` inside the run folder. What the old answer cost still counts toward the ceiling,
+`--spend` and `report.json`'s `totals.usd` (shown separately as `totals.supersededUsd`), so a resume
+cannot spend past the cap. An answer you wrote for an external stage is never re-used against a
+changed prompt: it is set aside the same way and the run asks you again.
+
 The cap governs one run. To see what you have spent across all of them:
 
 ```bash
-node src/cli.js --spend            # today
-node src/cli.js --spend --days 7   # the last week
-node src/cli.js --cost-today       # today by calendar day, with a per-model breakdown
-node src/cli.js --cost-today --date 2026-09-01
-node src/cli.js --stats --days 30    # how the debate mechanism itself is doing
+council --spend            # today
+council --spend --days 7   # the last week
+council --cost-today       # today by calendar day, with a per-model breakdown
+council --cost-today --date 2026-09-01
+council --stats --days 30    # how the debate mechanism itself is doing
 ```
 
 That is read back off the run folders on disk - there is no ledger file, nothing is recorded
@@ -249,7 +417,7 @@ To watch this work without spending anything, the `mock-budget` chain calls no A
 fixture prices:
 
 ```bash
-node src/cli.js --task tasks/your-idea.md --chain mock-budget --max-usd 1
+council --task tasks/your-idea.md --chain mock-budget --max-usd 1
 ```
 
 If a chain pauses for your input, it writes `NEEDS-<stage>.md` into the run folder and tells you
@@ -257,17 +425,20 @@ how to resume:
 
 ```bash
 # write your answer to runs/<id>/answers.md, then:
-node src/cli.js --resume runs/<id>
+council --resume runs/<id>
 ```
 
 ## Quick start (MCP)
 
-Register the server with your MCP client. No clone needed - straight from GitHub:
+Register the server with your MCP client. No clone needed - from the published npm package:
 
 ```bash
-claude mcp add council -- npx -y github:muad-yasin/the-high-council-mcp council --mcp
+claude mcp add council -- npx -y the-high-council council --mcp
 ```
 
+The same line with `npx -y github:muad-yasin/the-high-council-mcp` runs the current source
+instead.
+
 Or from a clone of this repo:
 
 ```bash
@@ -277,20 +448,34 @@ claude mcp add high-council -- node /absolute/path/to/the-high-council-mcp/src/m
 **The path must be absolute.** The client starts the server from its own working directory, not
 from this one, so a relative path resolves somewhere unexpected and the server never starts.
 
-An npm package is coming - not yet published, no date. Once it lands:
+Or as a Claude Code plugin, which registers the same server and also installs the skills in
+[`skills/`](skills/README.md):
 
 ```bash
-claude mcp add high-council -- npx -y the-high-council --mcp
+claude plugin marketplace add muad-yasin/the-high-council-mcp
+claude plugin install the-high-council@the-high-council
 ```
 
-Either way the server reads and writes in **your** working directory, not inside the package:
-`.env` for keys, `tasks/` for requests, `runs/` for output, and a `chains/` of your own takes
-precedence over the bundled ones.
+Claude Code copies the plugin into its plugin cache and runs `npm ci` there itself, so the first
+install takes a little longer. Start a new session (or run `/reload-plugins`) and the server shows
+up in `claude mcp list` as `plugin:the-high-council:high-council`. Remove it with
+`claude plugin uninstall the-high-council@the-high-council`. If you add the marketplace from a
+local clone instead (`claude plugin marketplace add /path/to/clone`), the server runs from the
+clone itself, so run `npm install` in it first.
 
-To run it by hand, from a clone:
+Registering with a client other than Claude Code (DeepSeek Harness, OpenHands, Cline, goose,
+Continue): [docs/mcp-clients.md](docs/mcp-clients.md) has the real config for each.
+
+Whichever way you add it, the server reads and writes in **your** working directory, not inside
+the package: `.env` for keys, `tasks/` for requests, `runs/` for output, and a `chains/` of your
+own takes precedence over the bundled ones. In a git project, add `.env` (and `runs/` if your
+ideas are private) to `.gitignore` before an agent commits everything; `council doctor` warns
+when `.env` is not ignored.
+
+To run it by hand:
 
 ```bash
-npm run mcp          # or: node src/cli.js --mcp
+council --mcp        # from a clone: npm run mcp
 ```
 
 Then drive it with these tools:
@@ -324,7 +509,7 @@ for anyone with a subscription, since the project's cost story depends on it.
 
 ## Chains
 
-31 chain configs live in `chains/`. Each one is plain JSON - the seat roster, which models fill
+49 chain configs live in `chains/`. Each one is plain JSON - the seat roster, which models fill
 which seat, the round cap, and whether proposals/debate/handoff stages run. They are meant to be
 copied and edited.
 
@@ -334,7 +519,8 @@ A few worth knowing:
 - **`cheap`** - small models throughout. For testing the harness itself, not for real work.
 - **`plan-debate`** - five labs propose blind, debate each other's proposals anonymised, then a
   blind panel grades the integrated draft.
-- **`plan-auto`** - the full open-scope chain, every seat on a real API, runs unattended end to end.
+- **`plan-auto`** - the full open-scope chain with every seat on a real API, so no stage waits for
+  an external session. It still pauses once for your answers to its questions.
 - **`plan-unanimous`** - every critic must independently sign off on the *same* draft. Three rounds
   here means up to fifteen critic calls, not five.
 
@@ -359,56 +545,6 @@ Read a chain's `description` field before running it; they say what they cost yo
   before. **No efficacy claim**: this ships the mechanism, not evidence that it helps - see
   CHANGELOG.md's 0.6.0 entry.
 
-## New in 0.6.0
-
-- **Role-assigned debate seats** - see the `role` field above. Ships the mechanism only; whether
-  it changes anything about a real debate is untested by this release.
-- **`report.json`'s `debate.diagnostics`** - four failure-mode signals computed from a run's own
-  real debate output (never from an offline probe): a seat quoting no evidence despite objecting
-  or merging, textual overlap between differently-lensed seats' posts on the same proposal, a
-  same-run gap between role-bearing and role-less seats' evidence quoting, and the share of a
-  seat's own words that fall inside quoted evidence versus voice. Present (with nulls/empty
-  flags where there's nothing to compute) on any run that had a debate stage; absent otherwise.
-- **`debate.tie_break`** - a `report.json` field recording a weighted-tiebreak event, when one
-  fires. Not yet wired into a live vote-counting decision in this release.
-- **`PERSONAS.md`** - the five default public persona names and their voice directives, and how
-  an operator replaces the whole set with their own via `COUNCIL_PERSONAS_FILE`.
-
-## New in 0.5.0
-
-- **`council init [--yes]`** - the first thing to run in a fresh clone with no keys yet. Prints a
-  key check, writes a starter chain and task file you own (`chains/my-first-chain.json`,
-  `tasks/my-first-task.md` - a rerun never overwrites an edit you made to either), prices the
-  starter chain with no network call, then runs a canned, all-mock, $0 task end to end so the
-  first thing you inspect is a real run folder, not just terminal output.
-- **`council doctor --chain <file>`** - lints one chain config before you ever run it: a seat
-  under a misspelled key (never wired to any stage), a missing or empty `seats.critics` (the
-  review round can't run), or a seat naming a provider this codebase doesn't know. The same check
-  also runs automatically, fail-loud, the moment you try to actually run a broken chain - before
-  any paid call.
-- **`council doctor --scan-artifacts`** - scans your `tasks/` and `chains/` for API-key-shaped
-  strings before you commit or share them. Reports the file and line, never the matched text.
-- **`council --forecast-cost --chain <name> [--days N]`** - a realistic-case USD range for a
-  chain, built from its own historical runs on your machine and repriced at today's rates -
-  distinct from `--dry-run`'s worst-case estimate from a chain's declared token assumptions.
-- **`council export-board --run <folder> --out <file>`** - a run's proposals, debate, replies and
-  verdict as one self-contained HTML file. No external assets, no server, `<details>` sections.
-- **`council replay --run <folder> [--json]`** - a numbered, step-by-step transcript of a run's
-  reasoning in your terminal, with a `--json` mode for scripting.
-- **A structured error catalog** (`COUNCIL-E001`-`COUNCIL-E004`, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md))
-  for the hard-fail paths this project actually has - a missing key, an unpriced model, a
-  malformed chain file, an unreadable stage reply - each with a plain-words cause, a concrete fix
-  naming the real file, and a doc pointer. Degradable conditions exit 5; fatal ones exit 6.
-- **Structured per-stage JSON logs** - every run now also writes `stage-log.jsonl` (one line per
-  stage: seat, lab, token counts, cost, timing - no prompt content) alongside the existing
-  markdown/`report.json` artifacts.
-- **[CONTRIBUTING.md](CONTRIBUTING.md)** - the three smallest landable contribution shapes, for
-  anyone who wants to send a PR rather than only file an issue.
-
-None of the above change any existing chain's behaviour. `schemaVersion` and
-`max_proposals_per_seat` are both opt-in; a chain file that predates 0.5.0 runs exactly as it did
-before.
-
 ## How this was built
 
 Vibecoded, with **Claude Code** doing the writing, by one person at
@@ -444,13 +580,21 @@ No claim is made here that any of this produces better plans. It has not been me
 
 ## Skills
 
-`skills/` carries two Claude Code skill files shipped alongside this harness, not part of it:
-`backend-developer` and `frontend-developer` - general backend and frontend engineering rules
-(contract-first design, save/persistence integrity, accessibility, verification discipline) that
-apply to any codebase, not just this one. Same MIT/BYOK ethos as the harness itself. They don't
-claim to make code better; they describe what each rule guards against and why. Point Claude Code
-at this repo's `skills/` directory (or copy the two folders into your own project's
-`.claude/skills/`) to use them.
+`skills/` carries a small set of Claude Code skills shipped alongside this harness, not part of
+it - usable in any project, with or without the harness, and needing no API key:
+
+- **Core agentic work:** `task-scoping`, `research-and-sourcing`, `verification-and-critique`,
+  `context-and-handoff`, `tool-and-action-discipline` - the work around the work, for any agent
+  task, including setups where several models propose, critique, and hand off to each other.
+- **Building software:** `backend-developer`, `frontend-developer`, `ux-design`, `visual-craft`.
+- **Writing:** `good-news-writing`.
+
+The full catalog, with when to use each and what it guards against, is
+[`skills/README.md`](skills/README.md); a shareable presentation page is `docs/skills.html`. Both
+are checked by the test suite against the real `skills/` folder. Same MIT/BYOK ethos as the
+harness: the skills don't claim to make results better - nothing has been measured - they describe
+what each rule guards against and why. Copy the folders you want into your project's
+`.claude/skills/`, or point Claude Code at this repo's `skills/` directory.
 
 ## Known limits, stated plainly
 
@@ -463,6 +607,17 @@ at this repo's `skills/` directory (or copy the two folders into your own projec
   for `unpriced` before trusting a ceiling. `ollama` seats are the one deliberate exception: they
   price at an explicit $0 for any model name (they are genuinely free to run), so they never show
   up in that `unpriced` list and never need a pricing.json entry.
+- A call that fails **after** it reached the provider - the connection drops while a 200 reply is
+  being read, a 200 carries a body that is not JSON, or the request times out waiting for headers -
+  is not retried, because the generation was probably already billed. Its real usage cannot be
+  read, so it is counted toward the per-run cap at its worst-case projection. It leaves no
+  `<label>.usage.json`, so `council --spend` does not see it.
+- Some hosted reasoning models stop at a provider-side reasoning ceiling well below the seat's own
+  cap, before writing any answer (seen 2026-09-23: `deepseek/deepseek-v4.1-flash` via OpenRouter, 6 of
+  28 calls stopped at ~4.2k tokens, all reasoning, under a 36k cap). A bigger cap cannot fix that, so
+  such a reply is recorded as `REASONING_EXHAUSTED` and is not retried: the seat abstains, which
+  blocks unanimity and never counts as consent. Whether to change a chain's reasoning settings for it
+  is a roster decision, not something the harness does for you.
 - Prices in `src/pricing.json` are hand-maintained list prices, last verified 2026-09-06. They are
   estimates, not invoices. Your provider's bill is the real number.
 - Chains with many labs and high round caps get expensive quickly. `plan-unanimous` at three rounds
@@ -473,27 +628,34 @@ at this repo's `skills/` directory (or copy the two folders into your own projec
   produce sign-offs that mean nothing - the quality of the run depends heavily on the quality of
   the criteria stage.
 - Some chains pause for human input by design. They are not stuck.
+- The audit log (`audit.jsonl`) detects an edited line or a cut-off end, but **with no HMAC key,
+  which is the default, it does not detect a full rewrite**: anyone who can edit the file can
+  recompute every hash. Set `AUDIT_HMAC_KEY_FILE` to a key kept outside the run folder if the log
+  has to stand up to that.
 
 ## Privacy
 
-This tool and the [demo page](https://muad-yasin.github.io/the-high-council-mcp/demo.html)
-collect nothing. Stated plainly, not as a claim about quality:
+This tool collects nothing. Stated plainly, not as a claim about quality:
 
 - No telemetry, no analytics, no tracking of any kind, anywhere in this repo.
 - The only network calls this tool ever makes are to the AI provider APIs you configure with
   your own keys (`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, and so on) - and only when you start
   a real run with a non-mock, non-external seat. `council doctor` and `council demo` make zero
   network calls; both are implemented to read only local files and environment variable names.
-- The GitHub Pages site (`docs/`) ships no JavaScript and loads no third-party resource - see
+- The landing page in `docs/` ships no JavaScript and loads no third-party resource - see
   `test/landing-page.test.js`, which fails the build if either ever changes.
 - Everything a run produces - the task, the debate, the deliverable, the cost - is written to a
   folder on your own disk (`runs/<id>/`) and nowhere else. Deleting that folder deletes the
   record. See `src/spend.js`'s own documentation for why spend accounting is derived from those
   folders rather than kept in a separate log.
+- If you opt in to the audit export (`"audit": true`, and on automatically whenever a `policy.json`
+  exists), each run also writes `audit.jsonl` into its own folder: signed, hash-chained lines (each carries the previous line's hash) that
+  `verifyAuditLog` in `src/audit.js` checks offline. Seat, cost and timing only, never task or
+  prompt text. Format: `docs/audit-schema.md`.
 
 ## Accessibility
 
-The GitHub Pages site (`docs/`) uses only native HTML elements for interaction - `<a href>`
+The landing page (`docs/`) uses only native HTML elements for interaction - `<a href>`
 links and `<details>/<summary>` for the expandable demo sections - specifically because those
 are keyboard-operable by the browser itself, with no custom JavaScript to get wrong. Tested by
 hand, 2026-09-13, on the live site:
@@ -515,8 +677,10 @@ hand, 2026-09-13, on the live site:
 
 ## Reporting a bug
 
-Open an issue: [github.com/muad-yasin/the-high-council-mcp/issues](https://github.com/muad-yasin/the-high-council-mcp/issues).
-Or write to [contact@sower-industries.de](mailto:contact@sower-industries.de).
+Open an issue at
+[github.com/muad-yasin/the-high-council-mcp/issues](https://github.com/muad-yasin/the-high-council-mcp/issues).
+For anything security-related, or that should not be public, write to
+[contact@sower-industries.de](mailto:contact@sower-industries.de) instead.
 
 ## If this makes you money