@balpal4495/quorum 3.4.0 → 3.6.0

package/README.md

@@ -205,6 +205,79 @@ quorum advisor brief
 
 ---
 
+## LLM setup
+
+LLM-powered commands (`advisor`, `evolve`, `check`, `compass`, `serve`) auto-detect whichever provider is available. No config file is needed — Quorum picks the first working option from the list below.
+
+**Recommended: use a CLI tool you're already logged into.** No API key required.
+
+### Option 1 — Claude Code CLI (recommended)
+
+If you have [Claude Code](https://claude.ai/code) installed and are logged in, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+echo "say hi" | claude --print
+```
+
+Quorum detects the `Claude Code-credentials` keychain entry (macOS) or a session file in `~/.claude/sessions/`. If the command above works, Quorum will use it.
+
+### Option 2 — GitHub Copilot CLI
+
+If you have the [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) installed and are logged in via VS Code, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+copilot -p "say hi"
+```
+
+Quorum detects `~/.copilot/session-state/` having at least one session (created after first auth). If the command above works, Quorum will use it.
+
+### Option 3 — API keys
+
+Set any one of these environment variables:
+
+| Variable | Provider |
+|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic Claude |
+| `OPENAI_API_KEY` | OpenAI |
+| `GEMINI_API_KEY` | Google Gemini |
+| `OPENAI_BASE_URL` | Any OpenAI-compatible endpoint (Azure, Groq, etc.) |
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Option 4 — Gemini CLI
+
+If you have the [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+gemini -p "say hi"
+```
+
+### Option 5 — Ollama (local, last resort)
+
+If Ollama is running at `localhost:11434`, Quorum uses the first available model. Set `OLLAMA_MODEL` to pin a specific model, or `OLLAMA_HOST` for a non-default address.
+
+```bash
+ollama serve
+export OLLAMA_MODEL=llama3.2   # optional
+```
+
+### Checking what was detected
+
+```bash
+quorum serve   # startup line shows: LLM: Claude Code CLI
+```
+
+### No LLM — still useful
+
+Without any provider, `advisor query`, `advisor brief`, `check`, and `coverage` all work with no LLM. Commands output Chronicle evidence and a synthesis request that your agent (Claude Code, Copilot, Codex) can answer inline.
+
+---
+
 ## Upgrading from v1
 
 If your project has a `quorum/modules/` folder (the v1 vendored pattern), migrate in one step:
@@ -380,6 +453,43 @@ Writes to `.chronicle/committed/`, updates `SUMMARY.md`, removes the proposal. A
 
 ---
 
+### `quorum serve` — governance UI + MCP server
+
+```bash
+quorum serve              # starts on http://localhost:4242
+quorum serve --port 8080  # custom port
+quorum serve --no-llm     # disable LLM auto-detection
+```
+
+Starts a single HTTP server that provides:
+
+- **Governance UI** at `/` — browse committed entries, review and approve pending proposals (with inline evidence, Jury breakdown, and Council conditions), track Chronicle health, and run Compass product-direction analysis.
+- **MCP server** at `POST /mcp` — JSON-RPC 2.0 endpoint exposing 10 tools and 6 resources to any MCP-compatible agent.
+- **REST API** — used by the UI and accessible directly:
+
+| Route | Description |
+|---|---|
+| `GET /api/entries?q=<query>` | Search committed Chronicle entries |
+| `GET /api/proposals` | List pending proposals |
+| `GET /api/coverage` | Chronicle coverage map |
+| `GET /api/growth` | Chronicle health score |
+| `GET /api/compass?subcommand=map\|brief\|opportunities\|bets` | Compass product direction |
+| `PATCH /api/proposals/:id` | Edit a pending proposal before committing |
+
+**MCP resources** (readable by agents via `resources/read`):
+
+```
+chronicle://summary          chronicle://proposals
+chronicle://coverage         chronicle://growth
+chronicle://compass          chronicle://entry/{id}
+```
+
+**MCP tools**: `quorum_query`, `quorum_brief`, `quorum_stage`, `quorum_pending`, `quorum_coverage`, `quorum_growth`, `quorum_help`, `quorum_advisor`\*, `quorum_check`, `quorum_compass`\*
+
+\* LLM-powered tools auto-activate when `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` is set. Without a key they return a `no-llm` status with CLI fallback instructions.
+
+---
+
 ### `quorum growth` — is Chronicle actually learning?
 
 ```bash
@@ -565,7 +675,7 @@ Refuted entries always elevate risk by at least one level. Citation validation s
 
 ### LLM auto-detection
 
-Quorum finds whichever LLM is available: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY` → `OPENAI_BASE_URL` → Ollama at `localhost:11434` → authenticated `gemini` CLI. When running inside an AI agent with no separate key, commands output Chronicle evidence and a synthesis request — the agent answers inline.
+Quorum tries providers in this order: **Claude Code CLI** → **Copilot CLI** → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY` → `OPENAI_BASE_URL` → Gemini CLI → Ollama. See [LLM setup](#llm-setup) for how to configure each option.
 
 ---
 

package/bin/__tests__/mcp-server.test.js

@@ -474,7 +474,7 @@ describe("POST /mcp — tools/call", () => {
     expect(typeof result.content).toBe("string")
   })
 
-  it("quorum_advisor returns todo status", async () => {
+  it("quorum_advisor returns no-llm status when no provider is configured", async () => {
     const { dir } = await makeChronicle(tmpDir)
     srv = await startServer(tmpDir, dir)
 
@@ -485,7 +485,7 @@ describe("POST /mcp — tools/call", () => {
 
     expect(body.error).toBeUndefined()
     const result = JSON.parse(body.result.content[0].text)
-    expect(result.status).toBe("todo")
+    expect(result.status).toBe("no-llm")
   })
 
   it("returns -32601 for unknown tool name", async () => {
@@ -555,7 +555,7 @@ describe("unknown route", () => {
 // ── MCP Resources ─────────────────────────────────────────────────────────────
 
 describe("POST /mcp — resources/list", () => {
-  it("returns all five chronicle:// resources", async () => {
+  it("returns all six chronicle:// resources", async () => {
     const { dir } = await makeChronicle(tmpDir)
     srv = await startServer(tmpDir, dir)
 
@@ -570,7 +570,8 @@ describe("POST /mcp — resources/list", () => {
     expect(uris).toContain("chronicle://coverage")
     expect(uris).toContain("chronicle://growth")
     expect(uris).toContain("chronicle://entry/{id}")
-    expect(uris).toHaveLength(5)
+    expect(uris).toContain("chronicle://compass")
+    expect(uris).toHaveLength(6)
   })
 
   it("each resource has a name, description, and mimeType", async () => {

package/bin/__tests__/mcp-tools.test.js

@@ -489,37 +489,37 @@ describe("toolHelp", () => {
   })
 })
 
-// ── TODO placeholder tools ────────────────────────────────────────────────────
+// ── LLM-powered tools (no-llm fallback when no provider configured) ───────────
 
-describe("toolAdvisor (TODO placeholder)", () => {
+describe("toolAdvisor", () => {
   it("throws when question is missing", async () => {
     await expect(toolAdvisor({})).rejects.toThrow("question is required")
   })
 
-  it("returns status=todo with a message", async () => {
+  it("returns status=no-llm with a message when no provider is set", async () => {
     const result = await toolAdvisor({ question: "what was decided about retries?" })
-    expect(result.status).toBe("todo")
-    expect(result.message).toMatch(/todo|quorum advisor/i)
+    expect(result.status).toBe("no-llm")
+    expect(result.message).toMatch(/quorum advisor/i)
   })
 })
 
-describe("toolCheck (TODO placeholder)", () => {
+describe("toolCheck", () => {
   it("throws when neither outcome nor design is provided", async () => {
     await expect(toolCheck({})).rejects.toThrow("outcome or design is required")
   })
 
-  it("returns status=todo with a message", async () => {
+  it("returns preflight and risk when called with outcome and design", async () => {
     const result = await toolCheck({ outcome: "ship safely", design: "use feature flags" })
-    expect(result.status).toBe("todo")
-    expect(result.message).toMatch(/todo|quorum check/i)
+    expect(result).toHaveProperty("preflight")
+    expect(result).toHaveProperty("risk")
   })
 })
 
-describe("toolCompass (TODO placeholder)", () => {
-  it("returns status=todo with a message", async () => {
+describe("toolCompass", () => {
+  it("returns status=no-llm with a message when no provider is set", async () => {
     const result = await toolCompass({ subcommand: "brief" })
-    expect(result.status).toBe("todo")
-    expect(result.message).toMatch(/todo|quorum compass/i)
+    expect(result.status).toBe("no-llm")
+    expect(result.message).toMatch(/quorum compass/i)
   })
 })
 

package/bin/commands/llm.js

@@ -0,0 +1,108 @@
+import { probeAll, detectProvider } from "../shared/llm.js"
+import { c } from "../shared/colors.js"
+
+function row(detected, name, note, suffix = "") {
+  const icon  = detected ? c.green("✓") : c.dim("·")
+  const label = detected ? c.bold(name) : c.dim(name)
+  const right  = detected
+    ? (note ? c.dim(`  ${note}`) : "") + (suffix ? `  ${suffix}` : "")
+    : (note ? `  ${c.dim(note)}` : "")
+  return `  ${icon}  ${label.padEnd(26)}${right}`
+}
+
+export async function run(args) {
+  const test = args.includes("--test")
+
+  console.log("")
+  console.log(`${c.bold("quorum llm")}  ${c.dim("— LLM provider status")}`)
+  console.log("")
+
+  // Run all probes in parallel with active provider detection
+  const [providers, active] = await Promise.all([probeAll(), detectProvider()])
+  const activeName = active?.name ?? null
+
+  console.log("  Provider scan")
+  console.log(c.dim("  ─────────────────────────────────────────────────────"))
+
+  // Normalize names for active matching (gatherCandidates uses "Gemini", probeAll uses "Gemini API")
+  const norm = n => n.replace(/ API$/, "").replace(/ \(.*?\)$/, "").toLowerCase()
+
+  for (const p of providers) {
+    const isActive = p.detected && !!activeName && norm(p.name) === norm(activeName)
+
+    const badges = []
+    if (isActive)                                  badges.push(c.green("← active"))
+    if (p.detected && p.id === "ollama" && p.note) badges.push(c.dim(`(${p.note})`))
+    const suffix = badges.join("  ")
+
+    console.log(row(p.detected, p.name, null, suffix))
+    if (!p.detected && p.note) {
+      console.log(`       ${c.dim(p.note)}`)
+    }
+  }
+
+  console.log("")
+
+  if (!activeName) {
+    console.log(`  ${c.yellow("No provider detected.")}`)
+    console.log("")
+    printSetupGuide()
+    return
+  }
+
+  console.log(`  Active: ${c.bold(activeName)}`)
+  console.log("")
+
+  if (!test) {
+    console.log(c.dim("  Run 'quorum llm --test' to send a live request and verify it works."))
+    console.log("")
+    return
+  }
+
+  // ── Live test ──────────────────────────────────────────────────────────────
+  process.stdout.write(`  Testing ${c.bold(activeName)}… `)
+  const t0 = Date.now()
+
+  try {
+    const result = await active.llm([
+      { role: "user", content: "Respond with exactly the word OK and nothing else." },
+    ])
+    const ms = Date.now() - t0
+    const ok = /\bOK\b/i.test(result?.trim() ?? "")
+    if (ok) {
+      console.log(`${c.green("✓")}  ${c.dim(`(${ms}ms)`)}`)
+    } else {
+      console.log(`${c.yellow("✓ (unexpected response)")}  ${c.dim(`(${ms}ms)`)}`)
+      console.log(c.dim(`     → ${(result ?? "").slice(0, 120)}`))
+    }
+  } catch (err) {
+    console.log(c.red("✗"))
+    console.log(`     ${c.red(err.message?.slice(0, 200) ?? String(err))}`)
+    console.log("")
+    console.log(`  ${c.yellow("The detected provider failed.")} Check that you're signed in, then retry.`)
+  }
+  console.log("")
+}
+
+function printSetupGuide() {
+  console.log("  Quickest options:")
+  console.log("")
+  console.log(`  ${c.bold("A")}  ${c.bold("Claude Code CLI")}  ${c.dim("(no API key needed)")}`)
+  console.log(c.dim("     Install and sign in: https://claude.ai/code"))
+  console.log(c.dim("     Quorum auto-detects it once you're signed in."))
+  console.log("")
+  console.log(`  ${c.bold("B")}  ${c.bold("GitHub Copilot CLI")}  ${c.dim("(no API key needed)")}`)
+  console.log(c.dim("     Install VS Code + GitHub Copilot Chat extension, then sign in."))
+  console.log(c.dim("     Quorum auto-detects it once a session exists."))
+  console.log("")
+  console.log(`  ${c.bold("C")}  ${c.bold("API key")}  ${c.dim("(Anthropic, OpenAI, or Gemini)")}`)
+  console.log(c.dim("     export ANTHROPIC_API_KEY=sk-ant-…"))
+  console.log(c.dim("     export OPENAI_API_KEY=sk-…"))
+  console.log(c.dim("     export GEMINI_API_KEY=…"))
+  console.log("")
+  console.log(`  ${c.bold("D")}  ${c.bold("Ollama")}  ${c.dim("(local, free)")}`)
+  console.log(c.dim("     brew install ollama && ollama serve && ollama pull llama3.2"))
+  console.log("")
+  console.log(`  ${c.dim("After setup, run 'quorum llm' again to confirm detection.")}`)
+  console.log("")
+}

package/bin/commands/serve.js

@@ -1,6 +1,7 @@
 import { c } from "../shared/colors.js"
 import { findChronicleDir } from "../shared/chronicle.js"
 import { createServer } from "../mcp/server.js"
+import { detectProvider } from "../shared/llm.js"
 
 function parseArgs(argv) {
   const portIdx = argv.indexOf("--port")
@@ -9,11 +10,12 @@ function parseArgs(argv) {
     : Number(argv.find(a => /^\d{2,5}$/.test(a)) ?? 3000)
   const hostIdx = argv.indexOf("--host")
   const host = hostIdx !== -1 ? argv[hostIdx + 1] : "localhost"
-  return { port: isNaN(port) ? 3000 : port, host }
+  const noLlm = argv.includes("--no-llm")
+  return { port: isNaN(port) ? 3000 : port, host, noLlm }
 }
 
 export async function run(argv) {
-  const { port, host } = parseArgs(argv)
+  const { port, host, noLlm } = parseArgs(argv)
 
   const projectRoot  = process.cwd()
   const chronicleDir = await findChronicleDir(projectRoot)
@@ -23,14 +25,31 @@ export async function run(argv) {
     process.exit(1)
   }
 
-  const server = await createServer({ projectRoot, chronicleDir })
+  // Auto-detect LLM provider unless --no-llm is passed
+  let llmProvider = null
+  let llmName = null
+  if (!noLlm) {
+    const detected = await detectProvider()
+    if (detected) {
+      llmProvider = detected.llm
+      llmName     = detected.name
+    }
+  }
+
+  const server = await createServer({ projectRoot, chronicleDir, llm: llmProvider })
 
   server.listen(port, host, () => {
     const base = `http://${host}:${port}`
     console.log(`\n${c.bold("Quorum")}  ${c.dim(`serving ${projectRoot}`)}\n`)
     console.log(`  ${c.cyan("UI")}         ${c.dim(base + "/")}`)
     console.log(`  ${c.cyan("MCP")}        ${c.dim(base + "/mcp")}`)
-    console.log(`  ${c.cyan("Chronicle")}  ${c.dim(chronicleDir)}\n`)
+    console.log(`  ${c.cyan("Chronicle")}  ${c.dim(chronicleDir)}`)
+    if (llmName) {
+      console.log(`  ${c.cyan("LLM")}        ${c.dim(llmName + " (advisor/check/compass enabled)")}`)
+    } else {
+      console.log(`  ${c.cyan("LLM")}        ${c.dim("none — LLM tools return CLI fallback hints")}`)
+    }
+    console.log()
     console.log(c.bold("Claude Desktop") + c.dim(" — add to claude_desktop_config.json:"))
     console.log(c.dim(JSON.stringify({
       mcpServers: { quorum: { type: "streamable-http", url: `${base}/mcp` } }

package/bin/mcp/server.js

@@ -27,8 +27,11 @@ import {
   toolBrief,
   toolCoverage,
   toolGrowth,
+  toolCompass,
   commitProposal,
   deleteProposal,
+  updateProposal,
+  setLLM,
 } from "./tools.js"
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -124,10 +127,16 @@ async function handleMCP(body, defaultProjectRoot) {
           description: "Chronicle health score, entry counts, and guidance.",
           mimeType:    "application/json",
         },
+        {
+          uri:         "chronicle://compass",
+          name:        "Compass product direction",
+          description: "Latest Compass map: behaviours, gaps, and opportunities detected from the codebase.",
+          mimeType:    "application/json",
+        },
         {
           uriTemplate: "chronicle://entry/{id}",
           name:        "Chronicle entry",
-          description: "A single committed Chronicle entry by ID (prefix or full UUID).",
+          description: "A single committed Chronicle entry by id or 8-char prefix.",
           mimeType:    "application/json",
         },
       ],
@@ -160,6 +169,11 @@ async function handleMCP(body, defaultProjectRoot) {
       return rpcOk(id, { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }] })
     }
 
+    if (uri === "chronicle://compass") {
+      const result = await toolCompass({ subcommand: "map", projectRoot: defaultProjectRoot })
+      return rpcOk(id, { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }] })
+    }
+
     // chronicle://entry/{id}
     const entryMatch = uri.match(/^chronicle:\/\/entry\/(.+)$/)
     if (entryMatch) {
@@ -198,7 +212,9 @@ function setCORS(res) {
 
 // ── Server factory ────────────────────────────────────────────────────────────
 
-export async function createServer({ projectRoot, chronicleDir }) {
+export async function createServer({ projectRoot, chronicleDir, llm = null }) {
+  // Wire LLM into tools module so advisor/check/compass MCP tools work
+  setLLM(llm)
   let uiHtml
   try {
     uiHtml = await fs.readFile(UI_PATH, "utf8")
@@ -284,6 +300,24 @@ export async function createServer({ projectRoot, chronicleDir }) {
         }
       }
 
+      // ── REST: edit/patch proposal ───────────────────────────────────────────
+      if (proposalMatch && req.method === "PATCH") {
+        try {
+          const body   = await readBody(req)
+          const result = await updateProposal(proposalMatch[1], body, chronicleDir)
+          return json(res, 200, result)
+        } catch (err) {
+          return json(res, 400, { error: err.message })
+        }
+      }
+
+      // ── REST: compass ───────────────────────────────────────────────────────
+      if (pathname === "/api/compass" && req.method === "GET") {
+        const subcommand = new URL(req.url, "http://localhost").searchParams.get("subcommand") ?? "map"
+        const result = await toolCompass({ subcommand, projectRoot })
+        return json(res, 200, result)
+      }
+
       // ── Web UI ──────────────────────────────────────────────────────────────
       if ((pathname === "/" || pathname === "/index.html") && req.method === "GET") {
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" })

package/bin/mcp/tools.js

@@ -263,26 +263,70 @@ export async function toolHelp({ topic } = {}) {
   return { topic, content: section }
 }
 
-// ── [TODO] LLM-powered placeholders ──────────────────────────────────────────
-// These tools require a live LLM provider wired into quorum serve (--llm flag).
-// They are registered so AI clients can discover them, but return a clear
-// "not yet available" message rather than silently failing.
+// ── LLM-powered tools ─────────────────────────────────────────────────────────
+// These are activated when quorum serve detects an LLM provider.
+// Without a provider they return a clear CLI-fallback hint.
 
-const TODO_MESSAGE = (name) =>
-  `${name} requires an LLM provider. This is planned — run 'quorum ${name.replace("quorum_", "")}' from the CLI for now, or watch for a future 'quorum serve --llm' flag.`
+let _llm = null  // set by createTools() at server startup
 
-export async function toolAdvisor({ question } = {}) {
+const NO_LLM = (name) => ({
+  status: "no-llm",
+  message: `${name} requires an LLM provider. No provider was detected at startup. ` +
+    `Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY and restart quorum serve. ` +
+    `Alternatively run 'quorum ${name.replace("quorum_", "")}' from the CLI.`,
+})
+
+export async function toolAdvisor({ question, projectRoot } = {}) {
   if (!question) throw new Error("question is required")
-  return { status: "todo", message: TODO_MESSAGE("quorum_advisor") }
+  if (!_llm) return NO_LLM("quorum_advisor")
+
+  const { ask } = await import("../../dist/advisor/index.js")
+  const { chronicleDir } = await resolve(projectRoot)
+  const { createOracleClient } = await import("../../dist/oracle/index.js")
+  const { xenovaEmbed } = await import("../../dist/oracle/adapters/xenova-embedder.js")
+  const { createLanceDBStore } = await import("../../dist/oracle/adapters/lance-db.js")
+
+  const store  = await createLanceDBStore(chronicleDir)
+  const oracle = createOracleClient({ store, embed: xenovaEmbed })
+  const result = await ask({ question, oracle, llm: _llm })
+  return result
 }
 
-export async function toolCheck({ outcome, design } = {}) {
+export async function toolCheck({ outcome, design, projectRoot } = {}) {
+  // quorum check is LLM-free — uses the same preflight + risk classifier as the CLI
   if (!outcome && !design) throw new Error("outcome or design is required")
-  return { status: "todo", message: TODO_MESSAGE("quorum_check") }
+  const { runPreflight, classifyRisk } = await import("../shared/patterns.js")
+  const preflight = runPreflight(outcome ?? "", design ?? "")
+  const risk      = classifyRisk(outcome ?? "", design ?? "")
+  return { preflight, risk }
 }
 
-export async function toolCompass({ subcommand } = {}) {
-  return { status: "todo", message: TODO_MESSAGE("quorum_compass") }
+export async function toolCompass({ subcommand = "brief", goal, idea, projectRoot } = {}) {
+  if (!_llm) return NO_LLM("quorum_compass")
+
+  const { chronicleDir } = await resolve(projectRoot)
+  // Delegate to the compass CLI command handler for now
+  const { run: compassRun } = await import("../commands/compass.js")
+  // Capture stdout
+  const captured = []
+  const origWrite = process.stdout.write.bind(process.stdout)
+  process.stdout.write = (chunk, ...rest) => { captured.push(String(chunk)); return true }
+  try {
+    const extraArgs = []
+    if (subcommand === "pathways" && goal) extraArgs.push("--goal", goal)
+    if (subcommand === "score"    && idea) extraArgs.push("--idea", idea)
+    await compassRun([subcommand, ...extraArgs])
+  } finally {
+    process.stdout.write = origWrite
+  }
+  return { subcommand, output: captured.join("").trim() }
+}
+
+/**
+ * Call once at server startup to wire the LLM provider into LLM-powered tools.
+ */
+export function setLLM(llmProvider) {
+  _llm = llmProvider
 }
 
 // ── Proposal commit (human-gate — UI only, never an MCP AI tool) ──────────────
@@ -316,6 +360,27 @@ export async function deleteProposal(proposalId, chronicleDir) {
   return { deleted: match.replace(".json", "") }
 }
 
+export async function updateProposal(proposalId, patch, chronicleDir) {
+  const ALLOWED = ["topic", "decision", "key_insight", "status", "confidence",
+                   "affected_areas", "scope", "alternatives_considered", "rejected_reason"]
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  const files = await fs.readdir(proposalsDir).catch(() => [])
+  const match = files.find(f => f === `${proposalId}.json` || f.startsWith(proposalId))
+  if (!match) throw new Error(`Proposal not found: ${proposalId}`)
+
+  const proposalPath = path.join(proposalsDir, match)
+  const raw     = await fs.readFile(proposalPath, "utf8")
+  const current = JSON.parse(raw)
+
+  // Only apply allowed fields — never let PATCH overwrite id/proposalId/schema_version
+  for (const key of ALLOWED) {
+    if (patch[key] !== undefined) current[key] = patch[key]
+  }
+
+  await fs.writeFile(proposalPath, JSON.stringify(current, null, 2), "utf8")
+  return { updated: match.replace(".json", ""), topic: current.topic }
+}
+
 // ── MCP tool registry ─────────────────────────────────────────────────────────
 
 export const MCP_TOOLS = [
@@ -416,7 +481,7 @@ export const MCP_TOOLS = [
   // ── [TODO] LLM-powered tools ──
   {
     name: "quorum_advisor",
-    description: "[TODO] Ask a plain-language question answered from Chronicle using an LLM. Requires 'quorum serve --llm'. Use 'quorum advisor' CLI for now.",
+    description: "Ask a plain-language question answered from Chronicle using an LLM. Returns a synthesised answer with evidence citations. Auto-activated when quorum serve detects an API key.",
     inputSchema: {
       type: "object",
       properties: {
@@ -428,7 +493,7 @@ export const MCP_TOOLS = [
   },
   {
     name: "quorum_check",
-    description: "[TODO] Run instant risk triage on a design against Chronicle evidence. Requires 'quorum serve --llm'. Use 'quorum check' CLI for now.",
+    description: "Run instant risk triage on a design against Chronicle patterns — no LLM required. Returns preflight flags and a risk level (low/medium/high/critical).",
     inputSchema: {
       type: "object",
       properties: {
@@ -440,7 +505,7 @@ export const MCP_TOOLS = [
   },
   {
     name: "quorum_compass",
-    description: "[TODO] Product-direction synthesis — behaviours, pathways, bets, idea scoring. Requires 'quorum serve --llm'. Use 'quorum compass' CLI for now.",
+    description: "Product-direction synthesis — behaviours, pathways, bets, idea scoring. Auto-activated when quorum serve detects an LLM provider. Use subcommand: brief | map | pathways | bets | score | opportunities.",
     inputSchema: {
       type: "object",
       properties: {

package/bin/quorum.js

@@ -23,6 +23,8 @@ ${c.bold("Usage:")}
   ${c.cyan("quorum advisor")} ${c.dim('"question"')}             Ask a plain-language question (uses LLM)
   ${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.cyan("quorum llm")}                           Show LLM provider status and setup guide
+  ${c.cyan("quorum llm --test")}                    Send a live test request to the active provider
   ${c.cyan("quorum init")}                          Scaffold Quorum into a project
   ${c.cyan("quorum status")}                        Show Chronicle health and pending proposals
   ${c.cyan("quorum check")} --outcome <x> --design <y>  Preflight + risk (no LLM)
@@ -116,6 +118,12 @@ async function cli() {
     return
   }
 
+  if (command === "llm") {
+    const { run } = await import(path.join(__dirname, "commands/llm.js"))
+    await run(rest)
+    return
+  }
+
   if (command === "init") {
     const { run } = await import(path.join(__dirname, "commands/init.js"))
     await run(PKG_VERSION)