@balpal4495/quorum 0.4.2 → 2.0.0

package/SETUP.md

@@ -12,9 +12,16 @@ If you have Node.js 18+ available, run this from the project root:
 npx @balpal4495/quorum@latest init
 ```
 
-This handles all steps below automatically — copying modules, merging instruction files, updating `package.json`, `.gitignore`, and creating the Chronicle directory.
+This handles all steps below automatically — writing Quorum docs, merging instruction files,
+updating `package.json`, `.gitignore`, and creating the Chronicle directory.
 
-After it completes, run `npm install` and wire `setup()` into your entry point (see Step 6 below).
+After it completes, run `npm install`. The CLI is immediately usable:
+
+```bash
+quorum advisor brief
+quorum advisor "what has the team decided about X?"
+quorum check --outcome '...' --design '...'
+```
 
 ---
 
@@ -29,9 +36,9 @@ Do not skip steps. Do not ask for confirmation between steps — complete the fu
 
 Read these files in full before proceeding:
 
-- `quorum/modules/README.md` — module overview and quick-start
-- `quorum/modules/AGENTS.md` — file ownership and invariants
-- `.github/copilot-instructions.md` — workflow rules for AI agents (installed at project root by init)
+- `quorum/AGENTS.md` — module file ownership and invariants
+- `quorum/CLAUDE.md` — design decisions and constraints
+- `.github/copilot-instructions.md` — workflow rules for AI agents
 
 These are your operating instructions for everything that follows.
 
@@ -52,14 +59,12 @@ Does .chronicle/ exist?                             yes / no
 
 ---
 
-## Step 3 — Install dependencies
+## Step 3 — Install Quorum
 
-Open `package.json` at the project root. Add the following to `dependencies` if they are not already present:
+Open `package.json` at the project root. Add to `devDependencies` if not already present:
 
 ```json
-"zod": "^3.23.0",
-"vectordb": "^0.4.0",
-"@xenova/transformers": "^2.17.0"
+"@balpal4495/quorum": "^2.0.0"
 ```
 
 Then run:
@@ -70,77 +75,57 @@ npm install
 
 If the project uses `yarn` or `pnpm`, use the appropriate installer instead.
 
-> `zod` is required for all structured LLM output validation.
-> `vectordb` is the LanceDB adapter (swappable — see `quorum/modules/oracle/adapters/`).
-> `@xenova/transformers` is the local ONNX embedder (swappable — see `quorum/modules/oracle/adapters/xenova-embedder.ts`).
-
 ---
 
 ## Step 4 — Merge AI instruction files
 
 ### 4a. `.github/copilot-instructions.md`
 
-The automated init command (`npx @balpal4495/quorum@latest init`) handles this step automatically — it creates or appends to `.github/copilot-instructions.md` at the project root.
+The automated init command handles this step automatically.
 
-**If you are completing this step manually:**
-
-Check whether `.github/copilot-instructions.md` already exists.
-
-**If it does not exist:** Fetch the Quorum copilot instructions from the Quorum GitHub repo (`balpal4495/Quorum`) at `.github/copilot-instructions.md` and write it to `.github/copilot-instructions.md` in the project root.
-
-**If it already exists and does not contain `<!-- quorum -->`:** Append the Quorum instructions to the existing file, preceded by:
+**If completing manually:** fetch `.github/copilot-instructions.md` from the Quorum GitHub repo (`balpal4495/Quorum`) and write it to `.github/copilot-instructions.md` in the project root. If the file already exists and does not contain `<!-- quorum:start -->`, append:
 
 ```markdown
 ---
 
-<!-- quorum -->
+<!-- quorum:start -->
+<content from Quorum repo>
+<!-- quorum:end -->
 ```
 
-Do not replace or overwrite existing content.
-
 ### 4b. `AGENTS.md`
 
 **If it does not exist:**
-Create `AGENTS.md` at the project root with this content:
 
 ```markdown
 # Agent Instructions
 
-See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Quorum module internals.
+<!-- quorum:start -->
+## Quorum
+
+See [quorum/AGENTS.md](quorum/AGENTS.md) for module file ownership and internals.
 See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+<!-- quorum:end -->
 ```
 
-**If it already exists:**
-Append to it:
-
-```markdown
-
-## Quorum modules
-
-See [quorum/modules/AGENTS.md](quorum/modules/AGENTS.md) for Oracle, Jury, and Council internals.
-```
+**If it already exists:** append the `<!-- quorum:start --> ... <!-- quorum:end -->` block above.
 
 ### 4c. `CLAUDE.md`
 
 **If it does not exist:**
-Create `CLAUDE.md` at the project root with this content:
 
 ```markdown
 # Claude Instructions
 
-See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Quorum module internals.
+<!-- quorum:start -->
+## Quorum
+
+See [quorum/CLAUDE.md](quorum/CLAUDE.md) for design decisions and invariants.
 See [.github/copilot-instructions.md](.github/copilot-instructions.md) for workflow rules.
+<!-- quorum:end -->
 ```
 
-**If it already exists:**
-Append to it:
-
-```markdown
-
-## Quorum modules
-
-See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and Council internals.
-```
+**If it already exists:** append the `<!-- quorum:start --> ... <!-- quorum:end -->` block above.
 
 ---
 
@@ -148,39 +133,37 @@ See [quorum/modules/CLAUDE.md](quorum/modules/CLAUDE.md) for Oracle, Jury, and C
 
 **If `.gitignore` does not exist**, create it.
 
-Add the following block if it is not already present:
+Add the following block if not already present:
 
 ```gitignore
 # Quorum — Chronicle
 # entries/ is a LanceDB binary vector store — do not commit
 .chronicle/entries/
-
-# proposals/ contains pending human-approval writes — commit these
-# (remove the line above if you want to ignore the whole store)
+.chronicle/query-log.jsonl
 ```
 
 ---
 
-## Step 6 — Wire setup() into the project
+## Step 6 — Wire setup() into the project (programmatic use only)
 
-Find the application entry point (e.g. `index.ts`, `server.ts`, `app.ts`, or equivalent).
+Skip this step if you are using only the CLI (`quorum advisor`, `quorum check`, etc.).
 
-Add the following import and call at startup, **before** any agent or workflow code runs:
+For programmatic use, find the application entry point (e.g. `index.ts`, `server.ts`, `app.ts`).
 
 ```typescript
-import { setup } from "./quorum/modules/setup"
+import { setup } from "@balpal4495/quorum"
 
-const { oracle, evaluate, deliberate } = await setup({
+const { oracle, evaluate, deliberate, ask } = await setup({
   llm: yourLLMProvider, // replace with your project's LLM provider function
 })
 ```
 
 `setup()` creates `.chronicle/` directories, warms the embedder, and wires all module dependencies.
-It must be called once before any `oracle.query()`, `evaluate()`, or `deliberate()` call.
+Must be called once before any `oracle.query()`, `evaluate()`, `deliberate()`, or `ask()` call.
 
-If no entry point exists yet, note that `setup()` must be called before first use — do not inline it.
+`ask(question)` is the plain-language interface — it queries Oracle automatically, synthesises Chronicle evidence into a concise answer, and retries internally until the answer meets a confidence threshold.
 
-**Approving Chronicle proposals:** after an agent calls `oracle.propose()`, approve and index the entry from the terminal:
+**Approving Chronicle proposals:**
 
 ```bash
 quorum commit --list         # see pending proposals
@@ -188,39 +171,33 @@ quorum commit <id>           # approve and index a proposal
 quorum commit <id> --dry-run # preview without writing
 ```
 
-Requires `@xenova/transformers` and `vectordb` (both added in Step 3).
-
 ---
 
 ## Step 7 — Verify Chronicle is created
 
-Run the project (or call `setup()` in isolation). Confirm that `.chronicle/proposals/` exists after startup.
+Confirm `.chronicle/proposals/` and `.chronicle/committed/` exist:
 
 ```bash
 ls .chronicle/
-# expected: proposals/
-# entries/ will appear after the first oracle.commit()
+# expected: committed/  proposals/
 ```
 
-If the directory is not created, re-check that `setup()` is being awaited correctly.
-
 ---
 
-## Step 8 — Run module tests
-
-Confirm the modules are working in this environment:
+## Step 8 — Verify the CLI works
 
 ```bash
-# Module unit tests
-npx vitest run quorum/modules/
-
-# Eval suite — deterministic assertions, no LLM required
-npx vitest run quorum/evals/
+quorum advisor brief
+quorum growth
 ```
 
-All tests should pass. If they fail due to missing dependencies, re-run Step 3.
+Both commands run without any LLM. If they fail, check that `npm install` completed successfully.
+
+To run Quorum's eval suite (optional — tests Quorum's own correctness):
 
-The eval suite runs canonical test cases (known-bad proposals that should block, known-good ones that should pass) through the deterministic preflight and risk classifier. These pass without any LLM. If you later want to test Jury confidence and Council recommendations against a real LLM, set `EVAL_LLM=1` when running.
+```bash
+npx vitest run node_modules/@balpal4495/quorum/evals/
+```
 
 ---
 
@@ -229,10 +206,9 @@ The eval suite runs canonical test cases (known-bad proposals that should block,
 Once all steps are complete, report:
 
 1. Which files were created vs appended
-2. Which dependencies were added (if any were already present, note that)
-3. Whether tests passed
-4. The path to `setup()` in the entry point, and the LLM provider that was wired (or a note if it was left as a placeholder)
-5. Any step that could not be completed and why
+2. Whether `npm install` succeeded
+3. The path to `setup()` in the entry point if wired (or note if CLI-only)
+4. Any step that could not be completed and why
 
 ---
 
@@ -240,10 +216,7 @@ Once all steps are complete, report:
 
 Skip this step if you do not have Google Gemini CLI installed. Quorum is fully functional without it.
 
-If you do have it (or want to add it later), this enables Claude Code to delegate large-context
-analysis to Gemini — useful when a task requires surveying the whole codebase at once.
-
-**10a. Install Gemini CLI** (if not already installed — requires Node.js 18+):
+**10a. Install Gemini CLI** (if not already installed):
 
 ```bash
 npm install -g @google/gemini-cli
@@ -256,35 +229,36 @@ export GEMINI_API_KEY="your-key-here"
 export GEMINI_CLI_TRUST_WORKSPACE=true
 ```
 
-**10c. Create `GEMINI.md`** at the project root so Gemini understands the codebase.
-Copy `quorum/modules/AGENTS.md` content as a starting point, or write a brief description of
-the project and the Quorum architecture. The `GEMINI.md` in the Quorum repo itself is a
-working example.
+**10c. Create `GEMINI.md`** at the project root. Use `quorum/AGENTS.md` content as a starting point, or write a brief description of the project and the Quorum architecture.
 
-Once the key is set and `gemini -p "hello"` responds, Claude Code will automatically detect
-Gemini and use it for large-context tasks.
+Once the key is set and `gemini -p "hello"` responds, Claude Code will automatically detect Gemini and use it for large-context tasks.
 
 ---
 
 ## After setup
 
-You are now operating under Quorum. The rules in `quorum/modules/AGENTS.md` and `.github/copilot-instructions.md` apply to all subsequent work.
+You are now operating under Quorum. The rules in `quorum/AGENTS.md` and `.github/copilot-instructions.md` apply to all subsequent work.
 
 Key reminders:
-- **Query Oracle before proposing anything.** `oracle.query("what you're about to do")` first.
+- **Ask Advisor for context.** `quorum advisor "what has the team decided about X?"` before starting any meaningful work.
 - **Never call `oracle.commit()` autonomously.** Only `oracle.propose()`. A human commits.
 - **Chronicle entries are ground truth.** Respect `refuted` entries — do not retry what has already failed.
 
 ### CLI quick reference
 
-These commands are available globally after `npm install -g @balpal4495/quorum`:
-
 | Command | What it does |
 |---|---|
+| `quorum advisor "question"` | Ask a plain-language question — answer synthesised from Chronicle (needs LLM) |
+| `quorum advisor query "topic"` | Search Chronicle entries by keyword (no LLM) |
+| `quorum advisor brief` | High-level Chronicle summary (no LLM) |
 | `quorum status` | Chronicle health — pending proposals, committed entries |
 | `quorum check --outcome X --design Y` | Preflight + risk classifier (no LLM) |
 | `quorum commit --list` | List pending proposals |
 | `quorum commit <id>` | Approve and index a proposal |
 | `quorum sentinel coverage [--path <dir>]` | Chronicle coverage of source files |
+| `quorum growth` | Chronicle learning health — growth rate, last commit, pending proposals |
+| `quorum evolve` | Consolidate Chronicle — merges duplicates, resolves contradictions, promotes open entries |
 
 `quorum check` exit codes: `0` = low/medium risk · `1` = high · `2` = critical
+
+`quorum advisor ask` and `quorum evolve` auto-detect any available LLM: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENAI_BASE_URL`, Ollama at localhost:11434, or an authenticated `gemini` CLI. When running inside an AI agent with no separate key, they output Chronicle evidence and a synthesis request for the agent to answer inline.

package/bin/commands/advisor.js

@@ -0,0 +1,301 @@
+import { c } from "../shared/colors.js"
+import { findChronicleDir, readCommitted } from "../shared/chronicle.js"
+import { detectProvider } from "../shared/llm.js"
+
+const SATISFACTION_THRESHOLD = 0.7
+const MAX_RETRIES = 2
+
+// ── Evidence helpers ──────────────────────────────────────────────────────────
+
+function tokenize(text) {
+  return text.toLowerCase().split(/\W+/).filter(t => t.length > 2)
+}
+
+function scoreEntry(query, entry) {
+  const qTokens = new Set(tokenize(query))
+  const text = [
+    entry.key_insight ?? "",
+    entry.decision    ?? "",
+    ...(entry.affected_areas ?? []),
+    ...(entry.scope          ?? []),
+  ].join(" ")
+  const eTokens = tokenize(text)
+  const overlap = eTokens.filter(t => qTokens.has(t)).length
+  return overlap / Math.sqrt(qTokens.size * eTokens.length + 1)
+}
+
+function entryText(entry) {
+  return (entry.decision ?? entry.key_insight ?? "").trim()
+}
+
+function findRelevant(entries, query, limit = 6) {
+  return entries
+    .map(e => ({ entry: e, score: scoreEntry(query, e) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ entry }) => entry)
+}
+
+function formatEvidenceForLLM(entries) {
+  if (entries.length === 0) return "Chronicle has no prior entries on this topic."
+  return entries.map(e => {
+    const statusTag =
+      e.status === "refuted"   ? " [REJECTED]"  :
+      e.status === "validated" ? " [VALIDATED]" : ""
+    return `[${(e.id ?? "").slice(0, 8)}]${statusTag} ${entryText(e)}\n  Areas: ${(e.affected_areas ?? []).join(", ")}`
+  }).join("\n\n")
+}
+
+// ── LLM + validation loop ─────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are the Quorum Advisor — the plain-language interface to a team's collective knowledge.
+
+You receive a question from a developer or engineering manager, along with relevant Chronicle evidence.
+Synthesise that evidence into a clear, concise answer a human can act on.
+
+Rules:
+- Write for a human who does not know what "Chronicle entries" or "vector search" mean.
+- Be direct. One clear recommendation.
+- If Chronicle has relevant evidence, reference it plainly: "the team already decided X".
+- If Chronicle has no evidence, say so honestly — do not invent history.
+- Blockers are hard blockers only — things that MUST be resolved before moving forward.
+
+Return ONLY valid JSON matching this schema (no markdown fences, no explanation):
+{
+  "confidence": <number 0–1>,
+  "what_we_know": <string — what Chronicle knows, plain English, 1–3 sentences>,
+  "risks": [<string>],
+  "blockers": [<string — hard blockers only, empty array if none>],
+  "recommendation": <string — one clear action>,
+  "next_step": <string — specific next step or quorum command>
+}`
+
+async function callLLM(llm, question, evidence, attempt, previous) {
+  let userPrompt = `## Question\n${question}\n\n## Chronicle Evidence\n${formatEvidenceForLLM(evidence)}`
+
+  if (attempt > 0 && previous) {
+    const lines = [
+      "",
+      `## Previous Answer (attempt ${attempt} — quality threshold not met)`,
+      `Confidence: ${previous.confidence.toFixed(2)} (need ≥ ${SATISFACTION_THRESHOLD})`,
+    ]
+    if (previous.blockers?.length > 0) {
+      lines.push(`Unresolved blockers: ${previous.blockers.join("; ")}`)
+    }
+    lines.push("Please produce a more specific and concrete answer.")
+    userPrompt += lines.join("\n")
+  }
+
+  const raw = await llm([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user",   content: userPrompt },
+  ])
+
+  let parsed
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, "").replace(/\s*```$/m, "").trim()
+    parsed = JSON.parse(cleaned)
+  } catch {
+    throw new Error(`LLM returned non-JSON. Raw: ${raw.slice(0, 200)}`)
+  }
+
+  if (typeof parsed.confidence !== "number" || !parsed.what_we_know || !parsed.recommendation) {
+    throw new Error("LLM response missing required fields (confidence, what_we_know, recommendation)")
+  }
+
+  return parsed
+}
+
+async function runAdvisor(llm, question, evidence) {
+  let last = null
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const answer = await callLLM(llm, question, evidence, attempt, last)
+    last = answer
+    const satisfied = answer.confidence >= SATISFACTION_THRESHOLD && (answer.blockers?.length ?? 0) === 0
+    if (satisfied || attempt === MAX_RETRIES) return { ...answer, retries: attempt }
+  }
+  return { ...last, retries: MAX_RETRIES }
+}
+
+// ── Output renderers ──────────────────────────────────────────────────────────
+
+function renderAsk(question, result) {
+  console.log(`\n${c.bold("Advisor")}\n`)
+  console.log(`  ${c.dim("Question:")} ${question}\n`)
+
+  console.log(`${c.bold("What we know")}`)
+  console.log(`  ${result.what_we_know}\n`)
+
+  if (result.blockers?.length > 0) {
+    console.log(`${c.bold(c.red("Blockers"))}`)
+    for (const b of result.blockers) console.log(`  ${c.red("✗")}  ${b}`)
+    console.log("")
+  }
+
+  if (result.risks?.length > 0) {
+    console.log(`${c.bold("Risks")}`)
+    for (const r of result.risks) console.log(`  ${c.yellow("⚠")}  ${r}`)
+    console.log("")
+  }
+
+  console.log(`${c.bold("Recommendation")}`)
+  console.log(`  ${result.recommendation}\n`)
+
+  console.log(`${c.bold("Next step")}`)
+  console.log(`  ${c.cyan(result.next_step)}\n`)
+
+  if (result.retries > 0) {
+    console.log(c.dim(`  (Refined over ${result.retries + 1} attempts)\n`))
+  }
+}
+
+function renderQuery(topic, entries) {
+  console.log(`\n${c.bold("Chronicle")}  ${c.dim(`query: "${topic}"`)}\n`)
+
+  if (entries.length === 0) {
+    console.log(`  ${c.dim("No matching entries found.")}\n`)
+    return
+  }
+
+  for (const e of entries) {
+    const statusColor =
+      e.status === "validated" ? c.green :
+      e.status === "refuted"   ? c.red   : c.dim
+    console.log(`  ${c.cyan((e.id ?? "").slice(0, 8))}  ${statusColor(`[${e.status}]`)}  ${entryText(e)}`)
+    if (e.affected_areas?.length) console.log(`           ${c.dim(e.affected_areas.join(", "))}`)
+    console.log("")
+  }
+}
+
+function renderBrief(allEntries) {
+  const validated = allEntries.filter(e => e.status === "validated")
+  const refuted   = allEntries.filter(e => e.status === "refuted")
+  const open      = allEntries.filter(e => e.status === "open")
+  const recent    = allEntries.slice(0, 5)
+
+  console.log(`\n${c.bold("Chronicle Brief")}\n`)
+  console.log(`  ${c.green(validated.length)}  validated   ${c.red(refuted.length)}  refuted   ${c.dim(open.length + "  open")}\n`)
+
+  if (recent.length > 0) {
+    console.log(`${c.bold("Recent entries")}`)
+    for (const e of recent) {
+      const statusColor =
+        e.status === "validated" ? c.green :
+        e.status === "refuted"   ? c.red   : c.dim
+      console.log(`  ${c.cyan((e.id ?? "").slice(0, 8))}  ${statusColor(e.status)}  ${entryText(e).slice(0, 70)}`)
+    }
+    console.log("")
+  }
+}
+
+// ── Subcommand handlers ───────────────────────────────────────────────────────
+
+async function cmdAsk(question, chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  const evidence   = findRelevant(allEntries, question)
+  const provider   = await detectProvider()
+
+  if (!provider) {
+    renderPassthrough(question, evidence)
+    return
+  }
+
+  const { llm, name: llmName } = provider
+  process.stdout.write(c.dim(`\n  Thinking (${llmName})…`))
+  try {
+    const result = await runAdvisor(llm, question, evidence)
+    process.stdout.write("\r" + " ".repeat(50) + "\r")
+    renderAsk(question, result)
+  } catch (err) {
+    process.stdout.write("\r" + " ".repeat(50) + "\r")
+    console.error(`\n${c.red("Advisor failed:")} ${err.message}\n`)
+    process.exit(1)
+  }
+}
+
+function renderPassthrough(question, evidence) {
+  console.log(`\n${c.bold("Chronicle evidence")}  ${c.dim(`for: "${question}"`)}\n`)
+  if (evidence.length === 0) {
+    console.log(c.dim("  No relevant Chronicle entries found.\n"))
+  } else {
+    for (const e of evidence) {
+      console.log(`  ${c.cyan(e.id.slice(0, 8))}  ${c.bold(entryText(e))}`)
+      console.log(`  ${c.dim(`status: ${e.status} · confidence: ${e.confidence} · areas: ${(e.affected_areas ?? []).join(", ")}`)}`)
+      console.log("")
+    }
+  }
+  console.log(c.dim("─".repeat(60)))
+  console.log(`\n${c.bold("Synthesis request")}`)
+  console.log(`\n  ${question}`)
+  console.log(`\n${c.dim("  No LLM configured — answer from the Chronicle evidence above.")}`)
+  console.log(c.dim("  (Set ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or run Ollama for auto-synthesis.)\n"))
+}
+
+async function cmdQuery(topic, chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  const matches    = findRelevant(allEntries, topic, 8)
+  renderQuery(topic, matches)
+}
+
+async function cmdBrief(chronicleDir) {
+  const allEntries = await readCommitted(chronicleDir)
+  renderBrief(allEntries)
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export async function run(argv) {
+  const [subOrQuestion, ...rest] = argv
+
+  const chronicleDir = await findChronicleDir(process.cwd())
+  if (!chronicleDir) {
+    console.error(`\n${c.red("No .chronicle/ directory found.")} Run ${c.bold("quorum init")} first.\n`)
+    process.exit(1)
+  }
+
+  // `quorum advisor ask "..."` or `quorum advisor "..."` (default to ask)
+  if (subOrQuestion === "ask") {
+    const question = rest.join(" ").trim()
+    if (!question) return printUsage()
+    return cmdAsk(question, chronicleDir)
+  }
+
+  // `quorum advisor query "topic"` — Chronicle lookup, no LLM
+  if (subOrQuestion === "query") {
+    const topic = rest.join(" ").trim()
+    if (!topic) return printUsage()
+    return cmdQuery(topic, chronicleDir)
+  }
+
+  // `quorum advisor brief` — high-level Chronicle summary
+  if (subOrQuestion === "brief") {
+    return cmdBrief(chronicleDir)
+  }
+
+  // No subcommand — treat the whole argv as a question (default: ask)
+  const question = argv.join(" ").trim()
+  if (!question) return printUsage()
+  return cmdAsk(question, chronicleDir)
+}
+
+function printUsage() {
+  console.log(`
+${c.bold("quorum advisor")} — ask plain-language questions about your codebase
+
+${c.bold("Subcommands:")}
+  ${c.cyan("quorum advisor")} ${c.dim('"question"')}              Ask a question (default — uses LLM)
+  ${c.cyan("quorum advisor ask")} ${c.dim('"question"')}          Ask explicitly
+  ${c.cyan("quorum advisor query")} ${c.dim('"topic"')}           Search Chronicle entries (no LLM)
+  ${c.cyan("quorum advisor brief")}                  High-level Chronicle summary (no LLM)
+
+${c.bold("Examples:")}
+  quorum advisor "what happens if we change the auth system?"
+  quorum advisor ask "is it safe to add a NOT NULL column to users?"
+  quorum advisor query "authentication"
+  quorum advisor brief
+
+${c.dim("ask requires ANTHROPIC_API_KEY or OPENAI_API_KEY in your environment.")}
+`)
+  process.exit(1)
+}