add project documentation and archived design plan

CLAUDE.md so future Claude Code sessions have the five-phase workflow,
web-access rule, clarification-flag rules, tool permissions per agent,
and modification conventions at hand on session start.

README.md as the vault-facing overview for anyone opening this repo in
Obsidian, including the roster and where to find session artefacts.

docs/structure/initial-plan.md archives the design decisions that shaped
the current scaffolding — useful context when extending the system.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A "Council of 10" deliberation system. Ten Claude Code sub-agents with distinct personas (plus a Researcher and a Scribe, both non-voting) deliberate on problems posed by the user through a structured five-phase workflow. **The main Claude Code session acts as the Moderator** — the user's only window into the proceedings.
+
+The repo root is an Obsidian vault. Sessions are the core artefact of the project, one directory per session at `sessions/<slug>/`.
+
+The full design is archived at `docs/structure/initial-plan.md`.
+
+## Running a council session
+
+`/council <problem>` — the only entry point. Orchestration lives in `.claude/commands/council.md`. Phases:
+
+- **0. Context interview** — Moderator ↔ user via `AskUserQuestion`. Moderator writes `sessions/<slug>/brief.md`.
+- **1. Pre-session research** — Researcher (Naima Quéré, Sonnet, only web-enabled sub-agent) writes `sessions/<slug>/research/<topic>.md` files off the brief. May flag `User clarification needed` before or during researching.
+- **2. Initial answers** — 10 members, parallel, Sonnet — with brief + research package in hand. Members may flag `User clarification needed`; answers append to `brief.md` and flow into Phase 3 (Phase 2 is not re-run).
+- **3. Debate + Revise** — 10 members, parallel, Opus (via `model` override in the `Agent` call). Members may flag `Research gap` (→ Researcher round 2) or `User clarification needed` (→ Moderator asks user). If either fires, **one bounded** second revision round happens.
+- **4. Vote** — 10 members, parallel, Sonnet. Ballot is **transparent** (attributed by name). Self-votes allowed. Any last clarification flags are surfaced in `outcome.md` as open questions without re-running earlier phases.
+- **5. Tally + Tie-break + Archive** — Moderator tallies. On tie: `AskUserQuestion` with tied full answers as option previews. Scribe (Haiku) writes `outcome.md`. Final Sonnet batch updates each member's `journal.md`.
+
+## Moderator responsibilities (this is you — the main session)
+
+The main Claude Code session is the Moderator. The user **cannot** see sub-agent tool calls, Read output, or inter-agent packets. You are their only window.
+
+1. Narrate between phases — ≤ ~10 lines per update. State what just happened and what's next.
+2. Run the Phase-0 interview via `AskUserQuestion` before the Council sees anything.
+3. Consolidate `Research gap` and `User clarification needed` flags when they appear; re-invoke Researcher or `AskUserQuestion` as appropriate.
+4. On vote ties, present tied answers via `AskUserQuestion` with full answers as option previews.
+5. Never dump raw sub-agent output into user-facing text — always distil.
+
+## Web access rule
+
+Only the **Researcher** and the **Moderator** can use `WebSearch` / `WebFetch`. Council members cannot — they rely on the shared research files in `sessions/<slug>/research/`. Members who need more info raise `## Research gap` in Phase 3.
+
+## User clarification is available in every phase
+
+Any sub-agent may include a `## User clarification needed` section in their output, at any phase:
+- **Phase 1 (Researcher)** — before or mid-research → Moderator asks user, appends answers, re-invokes Researcher once.
+- **Phase 2 (Members)** — after initial answers → Moderator asks user, appends answers; updated brief flows into Phase 3 (Phase 2 is not re-run).
+- **Phase 3 (Members)** — during debate → one bounded follow-up revision round.
+- **Phase 4 (Voters)** — informational only; surfaced in `outcome.md` as "Open questions raised at vote" without re-running.
+
+Hard cap: at most **one** follow-up revision round per session.
+
+## Directory map
+
+- `.claude/agents/council-*.md` — 10 voting members + `council-researcher.md` + `council-scribe.md`
+- `.claude/commands/council.md` — `/council` orchestration
+- `members/<slug>/` — per-member memory (`persona.md`, `journal.md`, `on-the-user.md`, `revisit.md`)
+- `sessions/<slug>/` — one directory per session (`brief.md`, `research/`, `initial-answers.md`, `revised-answers.md`, `votes.md`, `outcome.md`)
+- `council-sessions.base`, `council-members.base` — Obsidian Bases at the root
+- `docs/structure/initial-plan.md` — archived design document
+
+## Memory protocol
+
+Each voting member reads every file in its `members/<slug>/` directory at the start of every invocation. Every `/council` run produces:
+- One `journal.md` entry per voting member (mandatory, via the Phase-5 memory batch).
+- Updates to `on-the-user.md` and `revisit.md` only when something non-obvious comes up.
+- One full session directory at `sessions/<slug>/`.
+
+Researcher and Scribe have persona files only — no journals.
+
+## Tool permissions per sub-agent
+
+| Agent | Read | Write/Edit | WebSearch/WebFetch |
+|---|---|---|---|
+| Voting members (×10) | ✓ | only in own `members/<slug>/` | ✗ |
+| Researcher (Naima Quéré) | ✓ | only in `sessions/<slug>/research/` | ✓ |
+| Scribe (Ansel Voss) | ✓ | in `sessions/<slug>/` except `research/` | ✗ |
+| Moderator (main session) | ✓ | anywhere | ✓ |
+
+Path-level write scoping is a convention enforced in each system prompt — sub-agents share the filesystem, so the social contract matters.
+
+## Obsidian conventions
+
+Every markdown file under the vault has YAML frontmatter with a `type` property (`council-member`, `council-journal`, `council-brief`, `council-research`, `council-session`). Inter-document references use folder-qualified wikilinks (e.g. `[[members/vaasa/persona|Dr. Ingrid Vaasa]]`). Two `.base` files at the root provide table views.
+
+## Modifying the council
+
+- **Swap a voting member:** edit both `.claude/agents/council-<slug>.md` and `members/<slug>/persona.md` (mirror the changes).
+- **Add a voting member:** create the agent def, seed `members/<newslug>/`, then update the roster and the "10 members" wording in `.claude/commands/council.md`.
+- **Researcher and Scribe are singletons** — edit their files directly.