@balpal4495/quorum 2.0.0 → 3.0.0

package/.github/copilot-instructions.md

@@ -2,11 +2,14 @@
 
 ## Architecture
 
-This project uses three portable reasoning modules: **Oracle**, **Jury**, and **Council**.
-They form the knowledge and validation layer for all agentic work in this codebase.
+This project uses six portable reasoning modules: **Advisor**, **Oracle**, **Jury**, **Council**, **Sentinel**, and **Compass**.
+They form the knowledge, validation, and product-direction layer for all agentic work in this codebase.
 
 ```
-oracle.query()  →  jury.evaluate()  →  council.deliberate()  →  human gate  →  Executor
+Advisor  →  plain-language Chronicle queries
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift
+Compass  →  product-direction synthesis (behaviours, pathways, bets, scoring)
 ```
 
 Source: `modules/` — see [modules/README.md](modules/README.md) for full API reference.
@@ -35,20 +38,23 @@ There are no auto-commits. Do not attempt to bypass this gate.
 
 | Module | What it does | LLM? |
 |---|---|---|
+| `ask()` | Plain-language question answered from Chronicle — validates internally, retries up to 2× | Yes |
 | `oracle.query()` | Retrieves relevant Chronicle entries by semantic + BM25 search | No |
 | `oracle.propose()` | Stages a new entry for human review | No |
 | `oracle.commit()` | Indexes an approved entry — human-triggered only | No |
 | `jury.evaluate()` | Scores a design against evidence across 4 dimensions | Yes |
 | `council.deliberate()` | Adversarial validation via advisor/reviewer fan-out | Yes |
+| `sentinel` | Coverage reporting, drift detection, and PR coverage maps | Optional |
+| `compass` | Product-direction synthesis — behaviours, opportunities, pathways, bets, idea scoring | Optional |
 
 ---
 
 ## Setup
 
 ```typescript
-import { setup } from "./modules/setup"
+import { setup } from "@balpal4495/quorum"
 
-const { oracle, evaluate, deliberate } = await setup({ llm: yourProvider })
+const { oracle, evaluate, deliberate, ask, compass } = await setup({ llm: yourProvider })
 ```
 
 `setup()` creates Chronicle directories, warms the embedder, and wires all dependencies.
@@ -87,8 +93,25 @@ After `council.deliberate()`:
 
 ---
 
+## CLI quick reference
+
+```bash
+quorum advisor brief                        # full Chronicle summary, no LLM
+quorum advisor query "topic"                # keyword search, no LLM
+quorum advisor "plain-language question"    # synthesised answer via LLM
+quorum check --outcome "..." --design "..."  # instant risk triage
+quorum commit --list                        # review pending proposals
+quorum commit <id>                          # approve a Chronicle entry
+quorum compass map                          # map current product behaviours (no LLM)
+quorum compass brief                        # product-direction summary (LLM)
+quorum compass pathways --goal "..."        # generate product pathways (LLM)
+quorum compass score "idea"                 # score a product idea (LLM)
+```
+
+---
+
 ## Build and test
 
 ```bash
-npx vitest run modules/
+npx vitest run modules/ evals/
 ```

package/README.md

@@ -28,6 +28,23 @@ Every new session starts from zero. The same mistakes get proposed again. The sa
 
 ---
 
+## Why not just use agent instructions?
+
+Agent instructions tell the AI how to behave.
+Quorum tells the AI what the project has already learned.
+
+| | Agent instructions | Chronicle |
+|---|---|---|
+| Content | Rules and preferences | Decisions, rejections, outcomes |
+| Growth | Static — you write them | Grows — the agent stages, you approve |
+| Durability | Easy to overwrite or ignore | Git-backed, survives config changes |
+| Failed approaches | Not tracked | Hard stops on refuted patterns |
+| Human approval | Not required | Required for every indexed entry |
+
+Instructions are a starting point. Chronicle is accumulated project knowledge.
+
+---
+
 ## What changes after Quorum
 
 **Without Quorum:**
@@ -125,6 +142,10 @@ Every PR merge posts a growth comment showing what Chronicle learned. `quorum ev
 | See whether memory is growing | `quorum growth` |
 | Consolidate stale or duplicate entries | `quorum evolve` |
 | Find undocumented areas | `quorum sentinel coverage` |
+| Understand what the product currently does | `quorum compass map` |
+| Generate product pathways toward a goal | `quorum compass pathways --goal "..."` |
+| Score a product idea | `quorum compass score "add Slack integration"` |
+| Stage a direction decision for Chronicle | `quorum compass propose --from-last` |
 
 ---
 
@@ -154,12 +175,57 @@ npx @balpal4495/quorum@latest init
 npm install
 ```
 
-Then install the CLI globally for terminal access:
+Then run Quorum from your project:
+
+```bash
+npx quorum advisor brief
+npx quorum advisor "what has the team decided about auth?"
+npx quorum check --outcome "..." --design "..."
+```
+
+**Optional — install the CLI globally:**
 
 ```bash
 npm install -g @balpal4495/quorum
+quorum advisor brief
 ```
 
+> **v2 architecture:** Implementation lives in the npm package (`node_modules/@balpal4495/quorum`). Project memory lives in your repo (`.chronicle/`). Agent docs bridge the two (`quorum/CLAUDE.md`, `.github/copilot-instructions.md`). Nothing is copied into your project that you need to maintain.
+
+---
+
+## Upgrading from v1
+
+If your project has a `quorum/modules/` folder (the v1 vendored pattern), migrate in one step:
+
+```bash
+quorum migrate-v2
+```
+
+After any `npm update @balpal4495/quorum`, refresh agent instruction files:
+
+```bash
+quorum sync
+```
+
+---
+
+## Runtime model
+
+The CLI works in plain Node 18+.
+
+Programmatic imports are TypeScript-native and require a TS-aware runtime such as `tsx`, `ts-node`, Bun, or a bundler. Plain `node` will not resolve `.ts` files.
+
+```bash
+# recommended for scripts
+npx tsx your-script.ts
+
+# or Bun
+bun your-script.ts
+```
+
+For most host-project use cases the CLI is sufficient and requires no loader. See [modules/README.md](modules/README.md) for the full programmatic API.
+
 ---
 
 ## Command reference
@@ -394,7 +460,7 @@ The next person touching that table has the full reasoning. They don't repeat th
 
 ## How it works under the hood
 
-You do not need to understand these internals to use Quorum. They are installed into `quorum/modules/` so any AI working in the codebase can inspect and use them directly.
+You do not need to understand these internals to use Quorum. They live in `node_modules/@balpal4495/quorum` after install. The `quorum/` folder that `init` creates in your project contains agent-readable docs and Chronicle data — not module source.
 
 | Module | What it does | LLM |
 |---|---|---|
@@ -403,6 +469,7 @@ You do not need to understand these internals to use Quorum. They are installed
 | **Jury** | Evaluates a design against Chronicle evidence. Four-dimension confidence score, deterministic preflight, hard-blocker gaps. | Yes |
 | **Council** | Adversarial panel — advisors challenge independently, reviewers critique anonymously, Chairman gives a structured verdict. Risk-scaled fan-out. | Yes |
 | **Sentinel** | Coverage reporting (which files Chronicle knows about), drift detection (are entries still accurate), PR coverage maps. | Optional |
+| **Compass** | Product-direction layer — maps current behaviours from code and docs, identifies gaps and opportunities, generates pathways, strategic bets, and idea scores grounded in Chronicle evidence. All writes go through `oracle.propose()`. | Optional |
 
 ### How Jury works
 

package/bin/commands/compass.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+import path from "path"
+import { c } from "../shared/colors.js"
+import { findChronicleDir } from "../shared/chronicle.js"
+import { detectProvider } from "../shared/llm.js"
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function help() {
+  console.log(`
+${c.bold("quorum compass")} — product-direction synthesis
+
+${c.bold("Usage:")}
+  quorum compass <subcommand> [options]
+
+${c.bold("Subcommands:")}
+  brief                 Summarise current product direction (LLM)
+  map                   Map current product behaviours from code + docs (no LLM)
+  behavior              Answer a product-behaviour question
+  opportunities         List gaps and opportunities from the behaviour map
+  pathways              Generate product pathways toward a goal (LLM)
+  bets                  Generate strategic big bets (LLM)
+  score <idea>          Score a product idea (LLM)
+  spec <title>          Generate a lightweight product brief (LLM)
+  propose               Stage a Chronicle entry from a Compass artifact
+  outcome               Record the outcome of a prior bet or pathway
+
+${c.bold("Options:")}
+  --area <tag>          Focus on a specific product area
+  --goal <text>         Goal for pathways / bets
+  --horizon <text>      Horizon for bets (e.g. "6 months")
+  --appetite small|medium|large
+  --limit <n>           Max results to return
+  --json                Output raw JSON
+  --help                Show this help
+
+${c.bold("Examples:")}
+  quorum compass brief
+  quorum compass map
+  quorum compass map --area advisor
+  quorum compass pathways --goal "onboard new agents faster"
+  quorum compass bets --horizon "6 months"
+  quorum compass score "add Slack integration"
+  quorum compass spec "Smart retry backoff"
+  quorum compass opportunities --limit 5
+  quorum compass propose --from-last
+  quorum compass outcome --entry-id <id> --result validated`)
+}
+
+// ── Render helpers ────────────────────────────────────────────────────────────
+
+function renderBrief(brief) {
+  console.log(`\n${c.bold("Compass Brief")} ${c.dim(`(confidence: ${(brief.confidence * 100).toFixed(0)}%)`)}`)
+  console.log(`\n${c.bold("Direction:")} ${brief.product_direction}`)
+
+  if (brief.known_from_chronicle?.length) {
+    console.log(`\n${c.bold("From Chronicle:")}`)
+    brief.known_from_chronicle.forEach(item => console.log(`  ${c.green("✓")} ${item}`))
+  }
+  if (brief.known_from_behavior?.length) {
+    console.log(`\n${c.bold("From code/docs:")}`)
+    brief.known_from_behavior.slice(0, 6).forEach(item => console.log(`  ${c.green("✓")} ${item}`))
+  }
+  if (brief.inferred?.length) {
+    console.log(`\n${c.bold("Inferred:")}`)
+    brief.inferred.forEach(item => console.log(`  ${c.yellow("~")} ${item}`))
+  }
+  if (brief.unknowns?.length) {
+    console.log(`\n${c.bold("Unknowns:")}`)
+    brief.unknowns.forEach(item => console.log(`  ${c.dim("?")} ${item}`))
+  }
+  if (brief.opportunities?.length) {
+    console.log(`\n${c.bold("Opportunities:")}`)
+    brief.opportunities.slice(0, 4).forEach(o => console.log(`  ${c.cyan("→")} ${o.title}`))
+  }
+  if (brief.recommended_next_step) {
+    console.log(`\n${c.bold("Next step:")} ${brief.recommended_next_step}`)
+  }
+}
+
+function renderBehaviorMap(map) {
+  console.log(`\n${c.bold("Behaviour Map")} ${map.area ? c.dim(`(area: ${map.area})`) : ""} ${c.dim(`(confidence: ${(map.confidence * 100).toFixed(0)}%)`)}`)
+
+  if (map.behaviors.length > 0) {
+    console.log(`\n${c.bold(`Behaviours (${map.behaviors.length}):`)}`)
+    map.behaviors.slice(0, 20).forEach(b => {
+      console.log(`  ${c.green("✓")} ${b.current_behavior.slice(0, 100)}`)
+    })
+  } else {
+    console.log(`\n  ${c.dim("No behaviours found.")}`)
+  }
+
+  if (map.gaps.length > 0) {
+    console.log(`\n${c.bold(`Gaps (${map.gaps.length}):`)}`)
+    map.gaps.forEach(g => {
+      console.log(`  ${c.yellow("?")} [${g.area}] ${g.gap}`)
+    })
+  }
+
+  if (map.contradictions?.length) {
+    console.log(`\n${c.bold(`Contradictions (${map.contradictions.length}):`)}`)
+    map.contradictions.slice(0, 5).forEach(ct => {
+      console.log(`  ${c.red("!")} ${ct.description ?? JSON.stringify(ct).slice(0, 80)}`)
+    })
+  }
+}
+
+function renderPathways(pathways) {
+  console.log(`\n${c.bold(`Pathways (${pathways.length})`)}`)
+  pathways.forEach((p, i) => {
+    const score = p.scores?.total ?? "?"
+    const label =
+      score >= 85 ? c.green(`${score}`) :
+      score >= 70 ? c.cyan(`${score}`) :
+      score >= 55 ? c.yellow(`${score}`) :
+      c.dim(`${score}`)
+
+    console.log(`\n${c.bold(`${i + 1}. ${p.title}`)} ${c.dim("[")}${label}${c.dim("]")}`)
+    if (p.opportunity) console.log(`   ${p.opportunity}`)
+    if (p.smallest_useful_version) console.log(`   ${c.dim("Start:")} ${p.smallest_useful_version}`)
+    if (p.suggested_next_step) console.log(`   ${c.dim("Next:")} ${p.suggested_next_step}`)
+    if (p.assumptions?.length) {
+      console.log(`   ${c.dim("Assumes:")} ${p.assumptions[0]}`)
+    }
+  })
+}
+
+function renderBets(bets) {
+  console.log(`\n${c.bold(`Strategic Bets (${bets.length})`)}`)
+  bets.forEach((b, i) => {
+    const score = b.scores?.total ?? "?"
+    console.log(`\n${c.bold(`${i + 1}. ${b.title}`)} ${c.dim(`[${score}]`)}`)
+    console.log(`   ${c.dim("Thesis:")} ${b.thesis}`)
+    if (b.first_experiment) console.log(`   ${c.dim("First test:")} ${b.first_experiment}`)
+    if (b.kill_criteria?.length) console.log(`   ${c.red("Kill if:")} ${b.kill_criteria[0]}`)
+    if (b.assumptions?.length) console.log(`   ${c.dim("Assumes:")} ${b.assumptions[0]}`)
+  })
+}
+
+function renderScore(score) {
+  const total = score.scores?.total ?? 0
+  const label =
+    total >= 85 ? c.green("Very strong — pursue") :
+    total >= 70 ? c.cyan("Strong — pursue small test") :
+    total >= 55 ? c.yellow("Plausible — investigate more") :
+    total >= 40 ? c.dim("Weak — defer") :
+    c.red("Avoid")
+
+  console.log(`\n${c.bold(`Score: ${total}/100`)} — ${label}`)
+  console.log(`Idea: ${score.idea}`)
+  if (score.summary) console.log(`Summary: ${score.summary}`)
+
+  if (score.supporting_reasons?.length) {
+    console.log(`\n${c.bold("Strengths:")}`)
+    score.supporting_reasons.forEach(r => console.log(`  ${c.green("+")} ${r}`))
+  }
+  if (score.risks?.length) {
+    console.log(`\n${c.bold("Risks:")}`)
+    score.risks.forEach(r => console.log(`  ${c.red("-")} ${r}`))
+  }
+  if (score.open_questions?.length) {
+    console.log(`\n${c.bold("Open questions:")}`)
+    score.open_questions.forEach(q => console.log(`  ${c.dim("?")} ${q}`))
+  }
+  if (score.suggested_next_step) {
+    console.log(`\n${c.bold("Next step:")} ${score.suggested_next_step}`)
+  }
+}
+
+function renderOpportunities(opps) {
+  if (!opps.length) {
+    console.log(c.dim("\nNo gaps or opportunities found from current sources."))
+    return
+  }
+  console.log(`\n${c.bold(`Opportunities (${opps.length})`)}`)
+  opps.forEach((o, i) => {
+    const conf = `${(o.confidence * 100).toFixed(0)}%`
+    console.log(`\n${c.bold(`${i + 1}. ${o.title}`)} ${c.dim(`[${o.area}] [${o.evidence_strength}] [${conf}]`)}`)
+    if (o.why_it_matters) console.log(`   ${o.why_it_matters}`)
+    if (o.suggested_next_step) console.log(`   ${c.dim("Next:")} ${o.suggested_next_step}`)
+  })
+}
+
+function renderProductBrief(brief) {
+  console.log(`\n${c.bold(`Product Brief: ${brief.title}`)}`)
+  if (brief.problem) console.log(`\n${c.bold("Problem:")} ${brief.problem}`)
+  if (brief.target_user) console.log(`${c.bold("Target user:")} ${brief.target_user}`)
+  if (brief.recommended_solution) {
+    console.log(`\n${c.bold("Recommended solution:")}`)
+    console.log(`  ${brief.recommended_solution}`)
+  }
+  if (brief.smallest_useful_version) {
+    console.log(`\n${c.bold("Smallest useful version:")}`)
+    console.log(`  ${brief.smallest_useful_version}`)
+  }
+  if (brief.non_goals?.length) {
+    console.log(`\n${c.bold("Non-goals:")}`)
+    brief.non_goals.forEach(g => console.log(`  ${c.dim("✗")} ${g}`))
+  }
+  if (brief.risks?.length) {
+    console.log(`\n${c.bold("Risks:")}`)
+    brief.risks.forEach(r => console.log(`  ${c.red("-")} ${r}`))
+  }
+  if (brief.open_questions?.length) {
+    console.log(`\n${c.bold("Open questions:")}`)
+    brief.open_questions.forEach(q => console.log(`  ${c.dim("?")} ${q}`))
+  }
+  if (brief.suggested_quorum_checks?.length) {
+    console.log(`\n${c.bold("Quorum checks:")}`)
+    brief.suggested_quorum_checks.forEach(ch => console.log(`  ${c.cyan("$")} ${ch}`))
+  }
+}
+
+// ── Last-run artifact cache (used by --from-last) ─────────────────────────────
+
+let _lastArtifact = null
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+export async function run(argv) {
+  const [subcommand, ...rest] = argv
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    help()
+    return
+  }
+
+  const flags = {}
+  const positional = []
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]
+    if (a.startsWith("--")) {
+      const key = a.slice(2)
+      const val = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : true
+      flags[key] = val
+    } else {
+      positional.push(a)
+    }
+  }
+
+  const area      = flags["area"]
+  const goal      = flags["goal"]     || positional.join(" ") || undefined
+  const horizon   = flags["horizon"]  || undefined
+  const appetite  = flags["appetite"] || undefined
+  const limitN    = flags["limit"]    ? parseInt(flags["limit"], 10) : undefined
+  const jsonMode  = Boolean(flags["json"])
+  const entryId   = flags["entry-id"] || flags["entryId"] || undefined
+  const result    = flags["result"]   || undefined
+
+  // ── Load Compass module ────────────────────────────────────────────────────
+
+  const rootDir      = process.cwd()
+  const chronicleDir = findChronicleDir(rootDir)
+
+  if (!chronicleDir) {
+    console.error(c.red("Error: Chronicle not found. Run 'quorum init' first."))
+    process.exit(1)
+  }
+
+  // Lazy import to keep CLI startup fast
+  const { createCompass }  = await import("../../modules/compass/create.js")
+  const { defaultSources } = await import("../../modules/compass/sources/index.js")
+  const { createOracleClient } = await import("../../modules/oracle/index.js")
+  const { createLanceDBStore } = await import("../../modules/oracle/adapters/lance-db.js")
+  const { xenovaEmbed } = await import("../../modules/oracle/adapters/xenova-embedder.js")
+
+  const vectorStore = await createLanceDBStore(chronicleDir)
+  const oracle = createOracleClient({ embedder: xenovaEmbed, vectorStore, chronicleDir })
+
+  // Only load LLM for subcommands that need it
+  const NO_LLM_CMDS = new Set(["map", "opportunities"])
+  const llm = NO_LLM_CMDS.has(subcommand) ? undefined : detectProvider()
+
+  const compass = createCompass({
+    oracle,
+    llm,
+    rootDir,
+    chronicleDir,
+    sources: defaultSources(),
+  })
+
+  // ── Route subcommand ───────────────────────────────────────────────────────
+
+  try {
+    switch (subcommand) {
+      case "brief": {
+        const data = await compass.brief({ area })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderBrief(data)
+        break
+      }
+
+      case "map": {
+        const data = await compass.mapBehaviors({ area })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderBehaviorMap(data)
+        break
+      }
+
+      case "behavior": {
+        const question = goal || positional.join(" ")
+        if (!question) {
+          console.error(c.red('Error: provide a question, e.g. quorum compass behavior "what does quorum do for onboarding?"'))
+          process.exit(1)
+        }
+        const data = await compass.behavior({ question, area })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        console.log(`\n${c.bold("Behaviour answer:")} ${data.product_implication}`)
+        if (data.what_exists?.length) {
+          console.log(`\n${c.bold("What exists:")}`)
+          data.what_exists.forEach(e => console.log(`  ${c.green("✓")} ${e}`))
+        }
+        if (data.what_appears_missing?.length) {
+          console.log(`\n${c.bold("Appears missing:")}`)
+          data.what_appears_missing.forEach(m => console.log(`  ${c.yellow("?")} ${m}`))
+        }
+        break
+      }
+
+      case "opportunities": {
+        const data = await compass.opportunities({ area, goal, limit: limitN })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderOpportunities(data)
+        break
+      }
+
+      case "pathways": {
+        if (!goal) {
+          console.error(c.red('Error: --goal is required. Example: quorum compass pathways --goal "onboard new agents faster"'))
+          process.exit(1)
+        }
+        const data = await compass.pathways({ goal, horizon, appetite, area, limit: limitN })
+        _lastArtifact = { kind: "product_pathway", items: data }
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderPathways(data)
+        console.log(c.dim("\nTip: run 'quorum compass propose --from-last' to stage a Chronicle entry."))
+        break
+      }
+
+      case "bets": {
+        const data = await compass.bigBets({ horizon, goal, appetite })
+        _lastArtifact = { kind: "product_bet", items: data }
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderBets(data)
+        console.log(c.dim("\nTip: run 'quorum compass propose --from-last' to stage a Chronicle entry."))
+        break
+      }
+
+      case "score": {
+        const idea = goal || positional.join(" ")
+        if (!idea) {
+          console.error(c.red('Error: provide an idea. Example: quorum compass score "add Slack integration"'))
+          process.exit(1)
+        }
+        const data = await compass.scoreIdea({ idea })
+        _lastArtifact = { kind: "product_idea_score", items: [data] }
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderScore(data)
+        break
+      }
+
+      case "spec": {
+        const title = goal || positional.join(" ")
+        if (!title) {
+          console.error(c.red('Error: provide a title. Example: quorum compass spec "Smart retry backoff"'))
+          process.exit(1)
+        }
+        const data = await compass.productBrief({ title })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        renderProductBrief(data)
+        break
+      }
+
+      case "propose": {
+        if (flags["from-last"]) {
+          if (!_lastArtifact?.items?.length) {
+            console.error(c.red("Error: no Compass artifact in memory. Run pathways/bets/score first in the same session."))
+            process.exit(1)
+          }
+          const item = _lastArtifact.items[0]
+          const result = await compass.propose({ artifact_kind: _lastArtifact.kind, payload: item })
+          console.log(c.green(`\n✓ ${result.message}`))
+          break
+        }
+        console.error(c.red('Error: provide --from-last. Example: quorum compass propose --from-last'))
+        process.exit(1)
+        break
+      }
+
+      case "outcome": {
+        if (!entryId) {
+          console.error(c.red("Error: --entry-id is required. Example: quorum compass outcome --entry-id abc123 --result validated"))
+          process.exit(1)
+        }
+        if (!result) {
+          console.error(c.red("Error: --result is required. Values: validated, partially-validated, invalidated, unclear, superseded"))
+          process.exit(1)
+        }
+        const note = flags["note"] || undefined
+        const data = await compass.outcome({ entry_id: entryId, result, note })
+        if (jsonMode) { console.log(JSON.stringify(data, null, 2)); break }
+        console.log(c.green(`\n✓ ${data.message}`))
+        break
+      }
+
+      default: {
+        console.error(c.red(`Unknown subcommand: ${subcommand}`))
+        help()
+        process.exit(1)
+      }
+    }
+  } catch (err) {
+    if (err.message?.includes("LLM provider is required") || err.message?.includes("No LLM provider")) {
+      console.error(c.red(`\nError: ${err.message}`))
+      console.error(c.dim("Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use this subcommand."))
+    } else {
+      console.error(c.red(`\nCompass error: ${err.message ?? err}`))
+      if (process.env.DEBUG) console.error(err.stack)
+    }
+    process.exit(1)
+  }
+}

package/bin/commands/init.js

@@ -33,13 +33,19 @@ async function guardAlreadyInitialized(target) {
 async function writeQuorumDocs(target) {
   log.section("Writing Quorum docs")
   await fs.mkdir(path.join(target, "quorum"), { recursive: true })
-  for (const file of ["CLAUDE.md", "AGENTS.md"]) {
-    const src  = path.join(QUORUM_ROOT, "modules", file)
-    const dest = path.join(target, "quorum", file)
-    if (await exists(src)) {
-      await fs.copyFile(src, dest)
-      log.created(`quorum/${file}`)
-    }
+  // Host-facing CLAUDE.md — CLI-first operational guide, not module internals
+  const claudeSrc = path.join(QUORUM_ROOT, "bin", "templates", "CLAUDE.md")
+  const claudeDest = path.join(target, "quorum", "CLAUDE.md")
+  if (await exists(claudeSrc)) {
+    await fs.copyFile(claudeSrc, claudeDest)
+    log.created("quorum/CLAUDE.md")
+  }
+  // AGENTS.md — module file ownership map
+  const agentsSrc = path.join(QUORUM_ROOT, "modules", "AGENTS.md")
+  const agentsDest = path.join(target, "quorum", "AGENTS.md")
+  if (await exists(agentsSrc)) {
+    await fs.copyFile(agentsSrc, agentsDest)
+    log.created("quorum/AGENTS.md")
   }
   await fs.copyFile(
     path.join(QUORUM_ROOT, "SETUP.md"),