@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/courses/para-501.json

@@ -1,1166 +0,0 @@
-{
-  "id": "para-501",
-  "title": "PARA 501: Advanced Systems",
-  "description": "Master Paradigm's advanced operational systems — Lore for project memory, Sentinel for incident intelligence, Habits for behavioral discipline, Session Intelligence for crash recovery, and Hook Enforcement for automated compliance. Ties everything together into the complete Paradigm workflow.",
-  "lessons": [
-    {
-      "id": "lore-system",
-      "title": "The Lore System",
-      "content": "## Why Projects Forget\n\nEvery software project accumulates institutional knowledge — why a migration was attempted then rolled back, which approach was chosen for caching and why, what the team learned when the billing system went down at 2 AM. Without a system for capturing this knowledge, it lives only in the heads of the people who were there. When they leave, context-switch, or simply forget, the project loses its memory.\n\nParadigm's Lore system is a structured project timeline. It records sessions, decisions, milestones, incidents, and reviews as date-partitioned YAML entries that both humans and AI agents can search, filter, and learn from.\n\n## Anatomy of a Lore Entry\n\nEvery lore entry follows a consistent structure:\n\n```yaml\nid: L-2026-02-21-001\ntype: agent-session\ntimestamp: \"2026-02-21T14:30:00Z\"\nduration_minutes: 45\nauthor:\n  type: agent\n  id: claude-opus-4\n  model: claude-opus-4-6\ntitle: \"Add JWT authentication to user routes\"\nsummary: \"Implemented RS256 JWT auth middleware, added ^authenticated and ^project-admin gates to portal.yaml, created refresh token rotation.\"\nsymbols_touched: [\"#auth-middleware\", \"^authenticated\", \"^project-admin\"]\nsymbols_created: [\"#refresh-token-handler\"]\nfiles_modified: [\"src/middleware/auth.ts\", \"portal.yaml\"]\nfiles_created: [\"src/handlers/refresh-token.ts\"]\nlines_added: 247\nlines_removed: 12\ncommit: \"a1b2c3d\"\ndecisions:\n  - id: jwt-signing\n    decision: \"Use RS256 over HS256\"\n    rationale: \"Allows public key verification without sharing the signing secret\"\nlearnings:\n  - \"Express v5 requires explicit async error wrapping for middleware\"\nverification:\n  status: pass\n  details: { \"unit-tests\": pass, \"integration\": pass }\ntags: [security, auth]\n```\n\nThe `id` field is auto-generated: `L-{date}-{sequence}`, where the sequence resets daily. This creates a natural chronological index.\n\n## Entry Types\n\nLore recognizes six entry types, each capturing a different kind of project event:\n\n| Type | When to Use |\n|---|---|\n| `agent-session` | An AI agent completed a work session (most common) |\n| `human-note` | A human records context, rationale, or tribal knowledge |\n| `decision` | An architectural or design decision with rationale |\n| `review` | A code review, PR review, or post-mortem |\n| `incident` | A production incident or significant failure |\n| `milestone` | A release, launch, migration completion, or major achievement |\n\nThe type drives how the entry appears in timeline views and which filters surface it.\n\n## Storage: Date-Partitioned YAML\n\nLore entries live in `.paradigm/lore/entries/` organized by date:\n\n```\n.paradigm/lore/\n  timeline.yaml          # Index metadata\n  entries/\n    2026-02-19/\n      L-2026-02-19-001.yaml\n      L-2026-02-19-002.yaml\n    2026-02-20/\n      L-2026-02-20-001.yaml\n    2026-02-21/\n      L-2026-02-21-001.yaml\n```\n\nThe `timeline.yaml` index tracks total entry count, last updated timestamp, and known authors. Date partitioning keeps directories small and makes time-range queries efficient — to find entries from last week, you only read 7 directories.\n\n## CLI Tools\n\nThe CLI provides full lore management:\n\n- `paradigm lore list` — List entries with filters (author, type, symbol, date range, tags)\n- `paradigm lore show <id>` — Full detail view of a single entry\n- `paradigm lore record` — Record a new entry with expanded fields (files-modified, files-created, commit, learnings, duration)\n- `paradigm lore edit <id>` — Edit entry fields (title, summary, type, symbols, tags, learnings)\n- `paradigm lore delete <id>` — Delete an entry (with --yes to skip confirmation)\n- `paradigm lore timeline` — Timeline view grouped by date with hot symbols\n- `paradigm lore review <id>` — Add review scores to an entry\n- `paradigm lore` — Launch the web timeline UI\n\n## MCP Tools\n\nSix MCP tools power the Lore system:\n\n**`paradigm_lore_record`** — Create a new entry. Requires `type`, `title`, `summary`, and `symbols_touched`. Optional fields include files, decisions, learnings, and verification status. The entry is written to the correct date directory with an auto-incremented ID. When `validateSymbols: true` is passed, the tool checks each symbol in `symbols_touched` against registered symbols in `.purpose` files, `flows.yaml`, and `portal.yaml`. Unregistered symbols produce advisory warnings (the entry is always recorded regardless).\n\n**`paradigm_lore_search`** — Query entries with filters: by symbol, author, type, date range, tags, review status, and minimum completeness score. Returns matching entries sorted by recency.\n\n**`paradigm_lore_timeline`** — Get a high-level view: recent entries, active authors, hot symbols (most-referenced in recent entries), and timeline metadata. Use this for orientation — it tells you what has been happening in the project.\n\n**`paradigm_lore_get`** — Fetch a single entry by ID. Returns the full entry with all fields, including decisions, learnings, and review data.\n\n**`paradigm_lore_update`** — Update an existing entry. Pass the entry ID and the fields to change (title, summary, type, symbols, tags, learnings). Only specified fields are modified.\n\n**`paradigm_lore_delete`** — Delete an entry by ID. Requires `confirm: true` to prevent accidental deletion.\n\n## Lore Reviews\n\nEntries can be reviewed by humans after the fact. A review adds a `completeness` score (1-5), a `quality` score (1-5), and optional notes. This creates a feedback loop: agents learn which sessions produced high-quality entries and can adjust their recording behavior. You can filter entries by `hasReview` and `minCompleteness` to surface only verified project history.\n\n## When to Record\n\nThe general rule: **record lore when a session modifies 3 or more source files**. This threshold captures significant work sessions while ignoring trivial edits. The stop hook enforces this — if you modified 3+ files without recording a lore entry, it will block your session from completing.\n\nBeyond the threshold, always record lore for: architectural decisions (even if only 1 file changed), production incidents, milestone completions, and any session where you learned something the next developer should know.",
-      "keyConcepts": [
-        "Lore entries record sessions, decisions, milestones, incidents, and reviews",
-        "Six entry types: agent-session, human-note, decision, review, incident, milestone",
-        "Date-partitioned YAML storage in .paradigm/lore/entries/{YYYY-MM-DD}/",
-        "Auto-generated IDs: L-{date}-{sequence}",
-        "Six MCP tools: paradigm_lore_record, paradigm_lore_search, paradigm_lore_timeline, paradigm_lore_get, paradigm_lore_update, paradigm_lore_delete",
-        "Review scores (completeness 1-5, quality 1-5) enable feedback loops",
-        "Recording trigger: 3+ modified source files = significant session",
-        "Optional symbol validation checks symbols_touched against registered .purpose, flows, and portal symbols",
-        "timeline.yaml index tracks entry counts, authors, and last-updated"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You just finished a 40-minute session where you added caching to the API, modifying 5 files and creating 2 new ones. You also decided to use Redis over in-memory caching. Which lore entry type is most appropriate?",
-          "choices": {
-            "A": "`decision` — because you made an architectural choice about Redis",
-            "B": "`agent-session` — because this captures the full work session including the decision",
-            "C": "`milestone` — because adding caching is a significant achievement",
-            "D": "`review` — because you reviewed caching options before choosing",
-            "E": "`human-note` — because you want to record the Redis rationale"
-          },
-          "correct": "B",
-          "explanation": "An `agent-session` entry captures the full work session — files modified, symbols touched, decisions made, and learnings. The Redis decision belongs in the entry's `decisions` array. Use `decision` type only when you're recording a standalone architectural decision without associated implementation work."
-        },
-        {
-          "id": "q2",
-          "question": "Where does a lore entry created on February 21, 2026 (the third entry that day) get stored?",
-          "choices": {
-            "A": "`.paradigm/lore/L-2026-02-21-003.yaml`",
-            "B": "`.paradigm/lore/entries/2026-02-21/L-2026-02-21-003.yaml`",
-            "C": "`.paradigm/lore/entries/L-2026-02-21-003.yaml`",
-            "D": "`.paradigm/lore/2026/02/21/003.yaml`",
-            "E": "`.paradigm/history/lore/2026-02-21-003.yaml`"
-          },
-          "correct": "B",
-          "explanation": "Lore uses date-partitioned storage: `.paradigm/lore/entries/{YYYY-MM-DD}/L-{date}-{NNN}.yaml`. The date directory groups entries by day, and the sequence number (003) auto-increments within each day."
-        },
-        {
-          "id": "q3",
-          "question": "You want to find all lore entries related to the payment system from the last month. Which MCP tool and approach is correct?",
-          "choices": {
-            "A": "`paradigm_lore_timeline` with a symbol filter",
-            "B": "`paradigm_lore_search` with `symbol: '#payment-service'` and `dateFrom` set to 30 days ago",
-            "C": "`paradigm_search` with `query: 'payment'` and `type: 'lore'`",
-            "D": "Read all files in `.paradigm/lore/entries/` and grep for 'payment'",
-            "E": "`paradigm_lore_record` with a search query parameter"
-          },
-          "correct": "B",
-          "explanation": "`paradigm_lore_search` accepts filters including `symbol` (to match entries that touched a specific symbol) and `dateFrom`/`dateTo` for time ranges. `paradigm_lore_timeline` gives a high-level overview but doesn't support detailed filtering. `paradigm_search` searches the symbol index, not lore entries."
-        },
-        {
-          "id": "q4",
-          "question": "An agent modified 2 source files and did not record a lore entry. What happens at session end?",
-          "choices": {
-            "A": "The stop hook blocks the session — all modifications require lore entries",
-            "B": "Nothing — the 2-file threshold is below the recording trigger",
-            "C": "A warning is issued but the session completes normally",
-            "D": "The system auto-generates a lore entry from the git diff",
-            "E": "The post-write hook retroactively creates a minimal entry"
-          },
-          "correct": "B",
-          "explanation": "The lore recording threshold is 3+ modified source files. With only 2 files modified, the session is not considered significant enough to require a lore entry. The stop hook only enforces lore recording when 3 or more source files were modified."
-        },
-        {
-          "id": "q5",
-          "question": "A team lead reviews a lore entry and gives it completeness: 3, quality: 5. What does this tell you?",
-          "choices": {
-            "A": "The entry is high quality but missing some information about what was done",
-            "B": "The entry is poorly written but covers everything",
-            "C": "The review scores are contradictory and invalid",
-            "D": "The entry should be deleted and re-recorded",
-            "E": "Both scores must be the same for a valid review"
-          },
-          "correct": "A",
-          "explanation": "Completeness and quality are independent scores. A completeness of 3 means the entry is missing some details (perhaps decisions weren't documented or files weren't fully listed). A quality of 5 means what IS there is excellent — well-written, accurate, and useful. The review suggests the entry should be enriched with more detail while preserving its good writing."
-        }
-      ]
-    },
-    {
-      "id": "sentinel-deep-dive",
-      "title": "Sentinel Deep Dive",
-      "content": "## Beyond Stack Traces\n\nTraditional error tracking gives you a stack trace and a count. Paradigm Sentinel gives you *symbolic context* — which component failed, where in a flow it failed, what gate was being evaluated, and which known pattern matches the failure. This transforms incident response from \"read the stack trace and hope\" to \"match against institutional knowledge and follow a resolution strategy.\"\n\n## Symbolic Incident Records\n\nWhen Sentinel records an incident, it captures both technical and symbolic context:\n\n```yaml\nid: INC-042\ntimestamp: \"2026-02-21T02:15:00Z\"\nstatus: open\nerror:\n  message: \"Cannot read property 'id' of null\"\n  stack: \"at PaymentProcessor.processRefund (payment-processor.ts:142)\"\n  type: TypeError\nsymbols:\n  component: \"#payment-processor\"\n  flow: \"$refund-flow\"\n  gate: \"^authenticated\"\nflowPosition:\n  flowId: \"$refund-flow\"\n  expected: [\"^authenticated\", \"^refund-eligible\", \"#process-refund\", \"!refund-completed\"]\n  actual: [\"^authenticated\", \"^refund-eligible\", \"#process-refund\"]\n  missing: [\"!refund-completed\"]\n  failedAt: \"#process-refund\"\nenvironment: production\n```\n\nThe `flowPosition` field is critical — it tells you exactly where in the defined flow the failure occurred. The refund flow expected 4 steps; only 3 completed. The failure happened at `#process-refund`, and the `!refund-completed` signal never fired. This immediately narrows the investigation to the refund processing logic.\n\n## Incident Grouping\n\nSentinel automatically groups related incidents using symbolic similarity. When two incidents share the same component, flow, and error pattern, they form a group. The grouping algorithm uses a similarity threshold of 0.6 — incidents must share at least 60% of their symbolic context to cluster.\n\nAn `IncidentGroup` tracks the common symbols, error patterns, occurrence count, first/last seen timestamps, and which environments are affected. If a group matches a known failure pattern, Sentinel attaches it as a `suggestedPattern`.\n\n## Failure Patterns\n\nPatterns are the institutional knowledge of your error handling. Each pattern defines matching criteria and a resolution strategy:\n\n```yaml\nid: payment-null-ref-001\nname: \"Null reference in payment processing\"\npattern:\n  symbols:\n    component: \"#payment-processor\"\n  errorType: [TypeError]\n  errorContains: [\"Cannot read property\", \"null\"]\nresolution:\n  description: \"Add null check before accessing refund object properties\"\n  strategy: fix-code\n  priority: high\n  symbolsToModify: [\"#payment-processor\"]\n  filesLikelyInvolved: [\"src/services/payment-processor.ts\"]\nconfidence:\n  score: 85\n  timesMatched: 12\n  timesResolved: 10\n  timesRecurred: 2\n```\n\nSix resolution strategies exist: `retry` (transient failure), `fallback` (use alternative path), `fix-data` (data issue), `fix-code` (bug), `ignore` (known harmless), and `escalate` (needs human decision). Pattern priority ranges from `low` through `medium` and `high` to `critical`.\n\nPatterns come from four sources: `manual` (team-created), `suggested` (Sentinel auto-generated from groups), `imported` (from another project), and `community` (shared patterns). Paradigm ships 26 seed patterns covering common failures like incomplete flows, gate bypasses, state race conditions, and unhandled signals.\n\n## The Triage Workflow\n\nSentinel follows a defined lifecycle for incidents:\n\n1. **Record** — `paradigm_sentinel_record` creates the incident with error details, symbolic context, and optional flow position. The incident starts as `open`.\n\n2. **Triage** — `paradigm_sentinel_triage` lists incidents filtered by status, symbol, environment, or error text. The matcher automatically suggests patterns that fit each incident.\n\n3. **Investigate** — `paradigm_sentinel_show` with `includeTimeline: true` shows the full flow timeline — every gate passed, signal emitted, and state change leading up to the failure. With `includeSimilar: true`, it surfaces related incidents that may share a root cause.\n\n4. **Resolve** — `paradigm_sentinel_resolve` closes the incident with a resolution: which pattern applied (if any), the fix commit hash, PR URL, and notes. Resolved incidents feed back into pattern confidence scores.\n\n5. **Pattern** — `paradigm_sentinel_add_pattern` creates new patterns from resolved incidents. When you fix a novel failure, capture the fix as a pattern so the next occurrence resolves faster.\n\nThe sequence is: **record → triage → show → resolve → add pattern**. This cycle builds institutional knowledge with every incident.\n\n## Stats and Health Metrics\n\n`paradigm_sentinel_stats` provides operational intelligence for a given time period: total incidents, open vs resolved counts, incidents by environment and day, pattern effectiveness (which patterns resolve most incidents vs which recur), symbol hotspots (components with the highest incident rates), and resolution metrics (average time to resolve, pattern vs manual resolution rates).\n\nThe `symbolHealth` view shows per-symbol incident history — use it to identify which components need hardening or refactoring.\n\n## Logger Transports\n\nSentinel integrates with the Paradigm logger through a transport layer. The `LogTransport` interface defines a simple contract: a transport receives structured log entries and delivers them somewhere — a file, a remote API, a database, or Sentinel's ingestion endpoint.\n\n```typescript\ninterface LogTransport {\n  name: string;\n  send(entry: LogEntry): void | Promise<void>;\n}\n```\n\nThe logger supports multiple transports simultaneously via `addTransport(transport)` and `removeTransport(name)`. By default, logs go to the console. Adding a `SentinelTransport` sends them to Sentinel's server as well, without changing any of your existing logging calls.\n\n## The SentinelTransport Bridge\n\nConnecting the Paradigm logger to Sentinel is a one-liner:\n\n```typescript\nimport { enableSentinel } from '@a-company/sentinel';\n\nenableSentinel({ endpoint: 'http://localhost:3001' });\n```\n\nThis call creates a `SentinelTransport` instance and registers it with the logger via `addTransport`. From that point forward, every `log.component(...)`, `log.gate(...)`, and `log.signal(...)` call is forwarded to Sentinel as a structured log entry. Error-level logs are automatically promoted to incident candidates.\n\nThe beauty of this design is zero code changes to your application. Your existing logger calls remain unchanged — the transport layer silently bridges them to Sentinel's observability pipeline.\n\n## Metrics API\n\nSentinel's server exposes a metrics API for recording and querying application metrics:\n\n**POST /api/metrics** — Record a metric data point. Supports three metric types:\n- `counter` — Monotonically increasing values (e.g., request count, error count)\n- `gauge` — Point-in-time values that can go up or down (e.g., active connections, queue depth)\n- `histogram` — Distribution of values over time (e.g., response latency, payload size)\n\n```json\n{\n  \"name\": \"api.requests.total\",\n  \"type\": \"counter\",\n  \"value\": 1,\n  \"labels\": { \"method\": \"POST\", \"route\": \"/api/payments\" },\n  \"timestamp\": \"2026-02-21T14:30:00Z\"\n}\n```\n\n**GET /api/metrics** — Query metrics with optional filters by name, type, labels, and time range. Returns aggregated data suitable for dashboards and alerting.\n\n## Traces API\n\nSentinel supports distributed tracing through span trees:\n\n**POST /api/traces** — Record a trace span. Each span has a `traceId`, `spanId`, optional `parentSpanId`, `operationName`, `startTime`, `endTime`, and `tags`. Spans with the same `traceId` form a tree — the root span has no parent, and child spans reference their parent via `parentSpanId`.\n\n**GET /api/traces** — Query traces by operation name, service, time range, or minimum duration. Returns full span trees with timing breakdowns.\n\n## Service Registry\n\nSentinel maintains a live registry of services reporting data:\n\n**POST /api/services** — Register or update a service. Each service entry includes name, version, environment, health status, and last-seen timestamp.\n\n**GET /api/services** — List all registered services with their current health status and metadata. This provides a real-time view of what is running and where.",
-      "keyConcepts": [
-        "Symbolic incident records capture component, flow, gate, and signal context",
-        "Flow position tracking shows exactly where in a flow a failure occurred",
-        "Automatic incident grouping with 0.6 similarity threshold",
-        "Failure patterns define matching criteria and resolution strategies",
-        "Six resolution strategies: retry, fallback, fix-data, fix-code, ignore, escalate",
-        "Triage lifecycle: record → triage → show → resolve → add pattern",
-        "26 seed patterns ship with Paradigm covering common failure modes",
-        "Stats surface symbol hotspots, pattern effectiveness, and resolution rates",
-        "LogTransport interface enables pluggable log delivery via addTransport/removeTransport",
-        "enableSentinel() one-liner bridges the Paradigm logger to Sentinel with zero code changes",
-        "Metrics API supports counter, gauge, and histogram metric types",
-        "Traces API records distributed span trees with parent-child relationships",
-        "Service registry provides live health status for all reporting services"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "An incident record shows `flowPosition.actual` has 3 entries and `flowPosition.expected` has 5. The `failedAt` field points to the third step. What does this tell you?",
-          "choices": {
-            "A": "Three out of five flow steps completed successfully before the failure",
-            "B": "The flow is missing 2 step definitions and needs to be updated",
-            "C": "The third step failed, preventing the last 2 steps (including their signals) from executing",
-            "D": "Only the last 2 steps need to be investigated",
-            "E": "The flow validation is broken and should be re-run"
-          },
-          "correct": "C",
-          "explanation": "The `actual` array shows what actually executed, `expected` shows what should have. Three steps executed, meaning the first two succeeded and the third (`failedAt`) is where the failure occurred. The remaining 2 expected steps (in `missing`) never ran because execution stopped at the failure point."
-        },
-        {
-          "id": "q2",
-          "question": "A failure pattern has confidence scores: timesMatched=20, timesResolved=15, timesRecurred=5. What does a recurrence rate of 25% suggest?",
-          "choices": {
-            "A": "The pattern is highly effective and should be trusted",
-            "B": "The resolution strategy may not fully address the root cause — the fix works sometimes but the issue returns",
-            "C": "The pattern's matching criteria are too broad and catching unrelated incidents",
-            "D": "25% is normal and healthy for any pattern",
-            "E": "The pattern should be deleted and replaced"
-          },
-          "correct": "B",
-          "explanation": "timesRecurred (5) out of timesResolved (15) gives a 33% recurrence rate after resolution. This suggests the resolution strategy addresses symptoms but not the root cause. The pattern still has value (it resolves 67% permanently), but the resolution description should be updated with a more thorough fix, or a second pattern created for the recurring variant."
-        },
-        {
-          "id": "q3",
-          "question": "You receive a 2 AM production alert. What is the correct Sentinel-powered response sequence?",
-          "choices": {
-            "A": "`paradigm_sentinel_triage` → `paradigm_sentinel_record` → fix → `paradigm_sentinel_resolve`",
-            "B": "`paradigm_sentinel_record` → `paradigm_sentinel_patterns` → `paradigm_wisdom_context` → fix → `paradigm_sentinel_resolve`",
-            "C": "`paradigm_status` → read all files → find bug → `paradigm_sentinel_record`",
-            "D": "`paradigm_sentinel_stats` → identify hotspot → fix → `paradigm_sentinel_resolve`",
-            "E": "`paradigm_sentinel_record` → `paradigm_orchestrate_inline` → deploy agents → wait"
-          },
-          "correct": "B",
-          "explanation": "First, record the incident with `paradigm_sentinel_record` to start the clock and capture the error. Then check `paradigm_sentinel_patterns` for known fixes — this could save hours if the failure matches an existing pattern. Then check `paradigm_wisdom_context` for antipatterns on the failing component. Fix with full context, then resolve. Recording first is critical — you can't triage what you haven't recorded."
-        },
-        {
-          "id": "q4",
-          "question": "Sentinel ships with 26 seed patterns. Which pattern source would a team-created pattern from a post-mortem use?",
-          "choices": {
-            "A": "`community`",
-            "B": "`imported`",
-            "C": "`manual`",
-            "D": "`suggested`",
-            "E": "`seed`"
-          },
-          "correct": "C",
-          "explanation": "Patterns have four sources: `manual` (team-created), `suggested` (auto-generated by Sentinel from incident groups), `imported` (from another project), and `community` (shared open-source patterns). A pattern created by the team during a post-mortem is `manual`. The seed patterns that ship with Paradigm use `manual` source as well."
-        },
-        {
-          "id": "q5",
-          "question": "Two incidents share the same component (#auth-service) and error type (TypeError) but different flows. Sentinel's similarity threshold is 0.6. Will they be grouped?",
-          "choices": {
-            "A": "Yes — sharing a component and error type exceeds the 0.6 threshold",
-            "B": "No — different flows always prevent grouping",
-            "C": "It depends on what other symbolic context they share — 0.6 means 60% overlap required",
-            "D": "Only if they occurred within the same hour",
-            "E": "Only if a human manually groups them"
-          },
-          "correct": "C",
-          "explanation": "The 0.6 similarity threshold means 60% of symbolic context must overlap. Sharing a component and error type provides some overlap, but different flows reduce it. Whether they cross 0.6 depends on other shared context — same gate, same environment, similar error message. Grouping is automatic but similarity-driven, not based on any single field."
-        },
-        {
-          "id": "q6",
-          "question": "How do you connect the Paradigm logger to Sentinel's observability pipeline?",
-          "choices": {
-            "A": "Replace all `log.component()` calls with `sentinel.log()` calls throughout your codebase",
-            "B": "Call `enableSentinel({ endpoint: '...' })` once — it registers a SentinelTransport via addTransport with zero changes to existing logging code",
-            "C": "Configure a `sentinel` key in `.paradigm/config.yaml` and restart the application",
-            "D": "Import SentinelTransport in every file that uses the logger",
-            "E": "Set the `SENTINEL_ENDPOINT` environment variable — the logger auto-detects it"
-          },
-          "correct": "B",
-          "explanation": "The SentinelTransport bridge is designed for zero-code-change adoption. Calling `enableSentinel()` once creates a SentinelTransport and registers it with the logger via `addTransport`. From that point, all existing `log.component()`, `log.gate()`, and `log.signal()` calls are automatically forwarded to Sentinel. No changes to individual logging calls are needed."
-        },
-        {
-          "id": "q7",
-          "question": "You want to track API response latency in Sentinel. Which metric type should you use?",
-          "choices": {
-            "A": "`counter` — increment it by the latency value on each request",
-            "B": "`gauge` — set it to the current response time",
-            "C": "`histogram` — record each response time to build a distribution over time",
-            "D": "`timer` — Sentinel has a dedicated timer metric type for latency",
-            "E": "`counter` with a `latency` label containing the value"
-          },
-          "correct": "C",
-          "explanation": "Histogram is the correct metric type for distributions like response latency. A histogram records individual values and lets you compute percentiles (p50, p95, p99), averages, and distributions over time. A counter only tracks cumulative totals, a gauge only captures point-in-time snapshots, and there is no dedicated timer type — histograms serve that purpose."
-        }
-      ]
-    },
-    {
-      "id": "aspect-graph-internals",
-      "title": "Aspect Graph Internals",
-      "content": "## SQLite Schema\n\nThe aspect graph database at `.paradigm/aspect-graph.db` uses six core tables that model the full aspect ecosystem:\n\n**`aspects`** — The primary table storing aspect metadata. Columns include `id` (the aspect symbol, e.g., `token-expiry-24h`), `description`, `value`, `category` (rule/decision/constraint/configuration/invariant), `severity` (low/medium/high/critical), and `content_hash` (SHA-256 of the combined anchor code for drift detection). Each row represents one aspect from a `.purpose` file.\n\n**`anchors`** — Stores code anchor locations. Columns: `aspect_id` (foreign key to aspects), `file_path`, `start_line`, `end_line`, and `content_hash` (SHA-256 of the code at those lines). An aspect can have multiple anchors across different files.\n\n**`edges`** — The graph edges connecting aspects to other symbols. Columns: `source` (the aspect), `target` (any symbol), `relation` (enforced-by, depends-on, contradicts, supersedes, related-to), `weight` (numeric confidence, default 1.0 for explicit edges), and `origin` (explicit, inferred, or learned). This table is what makes the aspect system a graph rather than a flat list.\n\n**`lore_links`** — Connects aspects to lore entries. Columns: `aspect_id` and `lore_id`. These links are materialized from the `lore` field in aspect YAML definitions, and additional links are inferred when two aspects share lore references.\n\n**`search_weights`** — The learning system's memory. Columns: `query` (the search string), `aspect_id` (the result), and `weight` (accumulated confidence). This table powers Tier 1 of the three-tier search — when a query matches a stored mapping with sufficient weight, the result is returned immediately without FTS5 or fuzzy matching.\n\n**`heatmap`** — Tracks aspect access patterns. Columns: `aspect_id`, `access_type` (search, ripple, navigate, direct), `count`, and `last_accessed`. This data drives the `paradigm_aspect_heatmap` tool, revealing which aspects are most frequently referenced and how they are typically discovered.\n\n## Recursive Ripple\n\nThe aspect graph enables recursive ripple analysis — when you call `paradigm_ripple` on a symbol that has aspect edges, the ripple follows those edges to discover indirect impacts. The algorithm uses weighted breadth-first search (BFS) with three configurable parameters:\n\n- **maxDepth** — How many hops to traverse. Default is 5, maximum is 10. Each hop follows one edge in the graph. At depth 1, you see direct connections. At depth 5, you see connections five edges away.\n- **minWeight** — The minimum cumulative weight to continue traversal. Default is 0.1. As the BFS traverses edges, it multiplies the current weight by each edge's weight (multiplicative decay). When the cumulative weight drops below minWeight, that branch is pruned.\n- **Queue limit** — Maximum BFS queue size: 1000 nodes. This prevents runaway traversals in densely connected graphs. If the queue exceeds 1000 entries, the oldest entries are dropped.\n\nThe multiplicative decay is the key mechanism. An explicit edge with weight 1.0 passes full confidence to the next hop. An inferred edge with weight 0.5 halves the confidence. After two inferred edges, the weight is 0.25 — and after four, it drops to 0.0625, below the default minWeight threshold. This naturally limits traversal depth through low-confidence paths while allowing full traversal through high-confidence ones.\n\n## Heatmap Tracking\n\nEvery time an aspect is accessed through any MCP tool, the heatmap table records the access. Four access types are tracked:\n\n- **search** — The aspect was found via `paradigm_aspect_search`\n- **ripple** — The aspect was encountered during `paradigm_ripple` traversal\n- **navigate** — The aspect was discovered via `paradigm_navigate`\n- **direct** — The aspect was accessed by ID via `paradigm_aspect_get`\n\nThe heatmap serves two purposes. First, it powers the `paradigm_aspect_heatmap` tool, which ranks aspects by access frequency and reveals usage patterns. Second, it provides data for project health analysis — aspects that are never accessed may be stale or poorly named, while aspects accessed frequently across multiple types are clearly central to the project.\n\n## Materialization Pipeline\n\nThe aspect graph is rebuilt during `paradigm_reindex` through a five-step pipeline:\n\n1. **openAspectGraph** — Opens (or creates) the SQLite database at `.paradigm/aspect-graph.db`. If the database exists, all tables are cleared for a fresh rebuild. This ensures the graph always reflects the current state of YAML files.\n\n2. **materializeAspects** — Reads all `.purpose` files, extracts aspect definitions, and writes them to the `aspects`, `anchors`, and `edges` tables. For each anchor, the pipeline reads the actual source code at the specified line range and computes a SHA-256 content hash. Explicit edges from the YAML `edges` field are written with origin `explicit` and weight 1.0. Inferred edges from `applies-to` references are written with origin `inferred` and weight 0.5.\n\n3. **materializeLoreLinks** — Reads the `lore` field from each aspect and creates entries in the `lore_links` table connecting aspects to their referenced lore entries.\n\n4. **inferLoreEdges** — Scans the `lore_links` table for aspects that share lore references. When two aspects both reference the same lore entry, a learned edge is created between them with origin `learned` and a weight proportional to the number of shared references. This discovers implicit relationships that were not explicitly declared.\n\n5. **closeAspectGraph** — Commits all changes, runs ANALYZE for query optimization, and closes the database connection.\n\nBecause the entire graph is rebuilt from YAML on every reindex, there is no migration or versioning concern. If the schema changes in a future Paradigm version, the next reindex simply creates the new schema.\n\n## Category Inference\n\nWhen an aspect definition omits the `category` field, the materialization pipeline attempts to infer it from the description using keyword matching:\n\n- Descriptions containing \"must\", \"always\", \"never\", \"required\" suggest `rule`\n- Descriptions containing \"decided\", \"chosen\", \"selected\", \"opted\" suggest `decision`\n- Descriptions containing \"limit\", \"maximum\", \"minimum\", \"cannot exceed\" suggest `constraint`\n- Descriptions containing \"configured\", \"set to\", \"defaults to\", \"environment\" suggest `configuration`\n- Descriptions containing \"always true\", \"never negative\", \"invariant\", \"guarantee\" suggest `invariant`\n\nSimilarly, severity can be inferred from tags: aspects tagged `[critical]` or `[security]` default to `high` severity, aspects tagged `[compliance]` default to `critical`, and untagged aspects default to `medium`.\n\nInference is a fallback — explicit `category` and `severity` fields in YAML always take precedence.\n\n## Weight Decay in Search Learning\n\nThe search learning system uses a reinforcement model. When `paradigm_aspect_confirm` is called with a query and aspect ID:\n\n1. The selected result's weight for that query gets **+1.0** added to its current weight in the `search_weights` table. If no entry exists, one is created with weight 1.0.\n2. All other aspects that were previously returned for the same query get their weights multiplied by **0.95** (a 5% decay). This applies only to aspects that have existing `search_weights` entries for this query — it does not penalize aspects that were never returned for this query.\n\nThis mechanism is self-correcting. If result A is consistently confirmed for a query, its weight grows (1.0, 2.0, 3.0, ...) while alternatives decay (1.0, 0.95, 0.9025, ...). After enough confirmations, the learned mapping becomes dominant and Tier 1 returns it instantly. But if the user later confirms a different result B for the same query, B starts climbing while A begins decaying — the system adapts to changing preferences without requiring manual intervention.",
-      "keyConcepts": [
-        "Six SQLite tables: aspects, anchors, edges, lore_links, search_weights, heatmap",
-        "Recursive ripple uses weighted BFS with multiplicative decay across edges",
-        "Default maxDepth is 5 (max 10), default minWeight is 0.1, queue limit is 1000",
-        "Four heatmap access types: search, ripple, navigate, direct",
-        "Five-step materialization pipeline: open, materialize aspects, materialize lore links, infer lore edges, close",
-        "Category inference uses description keywords when category is not explicitly set",
-        "Search weight decay: +1.0 to confirmed result, *0.95 to all others for the same query",
-        "Inferred edges from applies-to have weight 0.5 and origin 'inferred'"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "What is the default maxDepth for recursive ripple in the aspect graph?",
-          "choices": {
-            "A": "3 — to keep traversals fast and focused",
-            "B": "5 — balancing depth of discovery with performance",
-            "C": "10 — the maximum allowed value",
-            "D": "Unlimited — ripple traverses until minWeight is reached",
-            "E": "1 — only direct connections are followed by default"
-          },
-          "correct": "B",
-          "explanation": "The default maxDepth for recursive ripple is 5, with a maximum configurable value of 10. This default balances discovery depth with performance — at 5 hops, you see a meaningful neighborhood without traversing the entire graph. The minWeight threshold (default 0.1) provides additional pruning by cutting off low-confidence paths before they reach maxDepth."
-        },
-        {
-          "id": "q2",
-          "question": "What happens to search weights when a result is confirmed via paradigm_aspect_confirm?",
-          "choices": {
-            "A": "The confirmed result gets +0.5 weight and all others are deleted",
-            "B": "The confirmed result gets +1.0 weight and all other results for the same query decay by *0.95",
-            "C": "All results for the query get +1.0 weight to reinforce the entire set",
-            "D": "The confirmed result is permanently pinned and decay is disabled",
-            "E": "The confirmed result replaces all other entries for that query"
-          },
-          "correct": "B",
-          "explanation": "The search learning system adds +1.0 to the confirmed result's weight for that query and multiplies all other existing results for the same query by 0.95 (a 5% decay). This self-correcting mechanism lets the best result rise to the top over time while alternatives gradually fade. The decay only applies to aspects that have existing search_weights entries for the query — it does not penalize unrelated aspects."
-        },
-        {
-          "id": "q3",
-          "question": "Which SQLite table stores aspect access frequency for the heatmap tool?",
-          "choices": {
-            "A": "aspects — in an access_count column",
-            "B": "edges — access frequency is tracked per edge",
-            "C": "search_weights — all access types feed into search weights",
-            "D": "heatmap — with columns for aspect_id, access_type, count, and last_accessed",
-            "E": "anchors — access is tracked per anchor location"
-          },
-          "correct": "D",
-          "explanation": "The `heatmap` table stores aspect access frequency with columns for `aspect_id`, `access_type` (search, ripple, navigate, direct), `count`, and `last_accessed`. This dedicated table allows the `paradigm_aspect_heatmap` tool to rank aspects by usage frequency and break down how each aspect is typically discovered — whether through search, ripple analysis, navigation, or direct access."
-        },
-        {
-          "id": "q4",
-          "question": "What is the queue limit for recursive ripple BFS traversal?",
-          "choices": {
-            "A": "100 nodes — to keep memory usage minimal",
-            "B": "500 nodes — a balance between coverage and performance",
-            "C": "1000 nodes — preventing runaway traversals in dense graphs",
-            "D": "Unlimited — the queue grows until maxDepth is reached",
-            "E": "10000 nodes — large enough for enterprise-scale graphs"
-          },
-          "correct": "C",
-          "explanation": "The BFS queue limit is 1000 nodes. This prevents runaway traversals in densely connected aspect graphs where the number of reachable nodes could grow exponentially with depth. When the queue exceeds 1000 entries, the oldest entries are dropped, ensuring the algorithm completes in bounded time and memory regardless of graph density."
-        },
-        {
-          "id": "q5",
-          "question": "How are aspect edges inferred from existing data during materialization?",
-          "choices": {
-            "A": "By analyzing import statements in source code files",
-            "B": "From applies-to references with weight 0.5 and origin 'inferred', and from shared lore references with origin 'learned'",
-            "C": "By running static analysis on anchor code blocks",
-            "D": "From git commit history showing which aspects changed together",
-            "E": "Only explicit edges are created — no inference occurs"
-          },
-          "correct": "B",
-          "explanation": "The materialization pipeline creates inferred edges in two ways. First, `materializeAspects` generates edges from `applies-to` references with weight 0.5 and origin 'inferred' — when an aspect applies to a component, a relationship edge is created. Second, `inferLoreEdges` scans for aspects sharing lore references and creates edges with origin 'learned' and weight proportional to the overlap. These supplement explicit YAML edges to build a richer graph."
-        }
-      ]
-    },
-    {
-      "id": "habits-practice",
-      "title": "Habits & Practice",
-      "content": "## Instinct vs Habit\n\nWhen you first learn to drive, you consciously think about every action — check mirrors, signal, check blind spot, change lanes. After thousands of miles, these become habits: automatic behaviors you execute without conscious effort. The Habits system brings this concept to AI-assisted development.\n\nWithout habits, an agent must be told every time: \"check ripple before modifying,\" \"validate flows after changing gates,\" \"record lore for significant sessions.\" With habits, these checks become automatic behavioral triggers — the system evaluates them at defined points and reports compliance. Over time, agents internalize the patterns, and the habit checks become confirmation rather than correction.\n\n## Habit Definitions\n\nEach habit is a structured rule with six fields:\n\n```yaml\nid: ripple-before-modify\nname: Check Ripple Before Modifying\ndescription: Always call paradigm_ripple before modifying any symbol\ncategory: discovery\ntrigger: preflight\nseverity: advisory\ncheck:\n  type: tool-called\n  params:\n    tools: [paradigm_ripple]\nenabled: true\n```\n\n**Categories** classify what kind of discipline the habit enforces. There are six:\n- `discovery` — Exploring before acting (ripple, navigate, search)\n- `verification` — Validating after implementing (postflight, reindex)\n- `testing` — Ensuring test coverage for new code\n- `documentation` — Keeping .purpose files and lore entries current\n- `collaboration` — Checking team wisdom and expert knowledge\n- `security` — Validating gates and portal.yaml compliance\n\n**Triggers** define when the habit is evaluated. There are four:\n- `preflight` — Before starting implementation\n- `postflight` — After completing implementation\n- `on-commit` — Before committing changes\n- `on-stop` — Before the session ends (stop hook)\n\n**Severity** determines what happens when a habit is violated:\n- `advisory` — Log a note, don't block anything\n- `warn` — Show a warning to the agent/user\n- `block` — Prevent session completion until resolved (enforced by stop hook)\n\n## Check Types\n\nHabits verify compliance through twelve check types:\n\n| Check Type | What It Verifies |\n|---|---|\n| `tool-called` | Specified MCP tools were invoked during the session |\n| `file-exists` | Files matching glob patterns exist (e.g., test files) |\n| `file-modified` | Files matching patterns were modified during session |\n| `lore-recorded` | A lore entry was created (for 3+ file sessions) |\n| `symbols-registered` | New code is registered in .purpose files |\n| `gates-declared` | Routes have corresponding gates in portal.yaml |\n| `tests-exist` | Test files exist for modified components |\n| `git-clean` | Git working tree is clean — all changes committed |\n| `commit-message-format` | Commit messages match regex patterns (default: conventional commit prefix + Symbols: trailer) |\n| `flow-coverage` | Changes spanning 3+ components have a documented $flow |\n| `context-checked` | Session context/recovery tools (paradigm_session_health, paradigm_session_recover) were called |\n| `aspect-anchored` | Touched aspects (~) have valid code anchors verified via paradigm_aspect_check |\n\n## The 14 Seed Habits\n\nParadigm ships with 14 built-in habits that establish baseline discipline:\n\n1. **explore-before-implement** (preflight/advisory/discovery) — Called paradigm_ripple, paradigm_navigate, paradigm_search, or paradigm_related before coding\n2. **ripple-before-modify** (preflight/advisory/discovery) — Called paradigm_ripple specifically before modifying symbols\n3. **check-fragility** (preflight/advisory/discovery) — Called paradigm_history_fragility before touching symbols\n4. **wisdom-before-implement** (preflight/advisory/collaboration) — Checked paradigm_wisdom_context or paradigm_wisdom_expert\n5. **verify-before-done** (on-stop/warn/verification) — Called paradigm_pm_postflight before finishing\n6. **postflight-compliance** (on-stop/advisory/verification) — Ran postflight and reindex\n7. **test-new-components** (postflight/advisory/testing) — Test files exist for new components\n8. **purpose-coverage** (postflight/warn/documentation) — .purpose files cover modified directories\n9. **record-lore-for-significant** (on-stop/warn/documentation) — Lore recorded for 3+ file sessions\n10. **gates-for-routes** (postflight/warn/security) — Routes have portal.yaml gate coverage\n11. **commit-message-symbols** (on-commit/advisory/documentation) — Commit messages follow type(#symbol): format with Symbols: trailer\n12. **flow-coverage-for-multi-component** (postflight/advisory/documentation) — Changes spanning 3+ components have a documented $flow\n13. **context-session-awareness** (preflight/advisory/discovery) — Session recovery or context check tools were called for continuity\n14. **aspect-anchors-valid** (postflight/advisory/verification) — Aspects touched during the session have valid code anchors\n\n## Habit Loading and Overrides\n\nHabits load from three sources, merged in order (later wins):\n\n1. **Seed habits** — The 10 built-in habits (always present)\n2. **Global habits** — `~/.paradigm/habits.yaml` (optional, applies to all projects)\n3. **Project habits** — `.paradigm/habits.yaml` (optional, project-specific)\n\nOverrides let you adjust severity or disable habits without redefining them:\n\n```yaml\n# .paradigm/habits.yaml\noverrides:\n  ripple-before-modify:\n    severity: block    # Upgrade from advisory to blocking\n  test-new-components:\n    enabled: false     # Disable for this project\ncustom:\n  - id: check-migrations\n    name: Verify DB Migrations\n    category: verification\n    trigger: on-commit\n    severity: warn\n    check:\n      type: file-exists\n      params:\n        patterns: [\"migrations/*.sql\"]\n```\n\n## Practice Profiles\n\nEvery habit evaluation is recorded as a practice event with a result: `followed`, `skipped`, or `partial`. These events accumulate into practice profiles that show compliance rates over time.\n\n`paradigm_habits_status` returns a practice profile with: overall compliance rate, strongest and weakest categories, per-category breakdowns, trend analysis (improving/declining/stable), and incident correlations — habits whose skipped evaluations correlate with higher incident rates.\n\nThe incident correlation is powerful: if skipping `ripple-before-modify` correlates with a 3x higher incident rate for the modified symbols, that is concrete evidence for upgrading the habit's severity.\n\n## MCP Tools\n\n**`paradigm_habits_check`** — Evaluate habits for a trigger point. Pass the trigger (`preflight`, `postflight`, `on-stop`), optionally with `filesModified` and `symbolsTouched` for context. Returns evaluations with follow/skip/partial results and whether any blocking violations exist.\n\n**`paradigm_habits_status`** — Get the practice profile for an engineer over a time period (7d, 30d, 90d, or all). Shows compliance rates, category breakdowns, trends, and incident correlations.\n\n**`paradigm_practice_context`** — Before modifying symbols, get habit-aware warnings. Pass the symbols you are about to touch, and it returns relevant habits, recent compliance rates, and suggestions based on your weak areas.\n\n## CLI Commands\n\nThe CLI provides full habit management:\n\n- `paradigm habits list` — List all habits with trigger, severity, and enabled status\n- `paradigm habits add` — Add a custom habit with check type, patterns, and tools\n- `paradigm habits edit <id>` — Edit habit fields (for seed habits: severity and enabled only)\n- `paradigm habits remove <id>` — Remove a custom habit\n- `paradigm habits enable/disable <id>` — Toggle a habit on or off\n- `paradigm habits check --trigger <trigger>` — Evaluate compliance for a specific trigger\n- `paradigm habits status` — Practice profile with compliance rates and trends\n- `paradigm habits init` — Initialize a habits.yaml file for the project\n\n## Platform Targeting\n\nHabits support a `platforms` field to restrict evaluation to specific platforms. For example, a habit with `platforms: ['claude', 'cursor']` will only be evaluated when running in those environments. A habit with `platforms: ['cli']` will only fire during CLI-driven workflows. When `platforms` is omitted, the habit applies everywhere.",
-      "keyConcepts": [
-        "Six categories: discovery, verification, testing, documentation, collaboration, security",
-        "Four triggers: preflight, postflight, on-commit, on-stop",
-        "Three severity levels: advisory (note), warn (visible), block (prevents completion)",
-        "14 seed habits establish baseline discipline across all categories",
-        "Three-layer loading: seed → global (~/.paradigm/) → project (.paradigm/)",
-        "Practice profiles track compliance rates and trend direction",
-        "Incident correlations link skipped habits to higher incident rates",
-        "Twelve check types: tool-called, file-exists, file-modified, lore-recorded, symbols-registered, gates-declared, tests-exist, git-clean, commit-message-format, flow-coverage, context-checked, aspect-anchored"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "A project wants the `ripple-before-modify` habit to block session completion instead of just advising. How should they configure this?",
-          "choices": {
-            "A": "Delete the seed habit and create a new one with `severity: block`",
-            "B": "Add an override in `.paradigm/habits.yaml` setting `severity: block` for `ripple-before-modify`",
-            "C": "Edit the seed-habits.json file directly in node_modules",
-            "D": "Create a global override in `~/.paradigm/habits.yaml` — project-level overrides cannot change severity",
-            "E": "Set `PARADIGM_HABIT_SEVERITY=block` environment variable"
-          },
-          "correct": "B",
-          "explanation": "Project-level overrides in `.paradigm/habits.yaml` can change any field of a seed habit, including severity. The three-layer merge means project settings override global settings, which override seed defaults. You never edit seed habits directly."
-        },
-        {
-          "id": "q2",
-          "question": "An agent's practice profile shows: discovery compliance 95%, verification 40%, testing 30%. The agent frequently skips `verify-before-done` and `test-new-components`. What does this pattern reveal?",
-          "choices": {
-            "A": "The agent is good at exploring but poor at following through — it rushes to finish without validating",
-            "B": "The discovery habits are too easy and should be made harder",
-            "C": "The agent needs more seed habits in the testing category",
-            "D": "This is a healthy pattern — discovery is the most important category",
-            "E": "The verification and testing habits should be disabled since the agent skips them"
-          },
-          "correct": "A",
-          "explanation": "High discovery compliance with low verification and testing shows an agent that does good pre-work but doesn't follow through with validation. This is the 'explore well, ship hastily' antipattern. The fix is to upgrade verification and testing habits to `warn` or `block` severity, not to disable them."
-        },
-        {
-          "id": "q3",
-          "question": "The `record-lore-for-significant` habit fires on which trigger and at what threshold?",
-          "choices": {
-            "A": "`preflight` — checks if lore was recorded in the previous session",
-            "B": "`on-stop` — checks if lore was recorded when 3+ source files were modified",
-            "C": "`postflight` — always checks for lore regardless of file count",
-            "D": "`on-commit` — requires lore for every commit",
-            "E": "`on-stop` — checks if lore was recorded when any files were modified"
-          },
-          "correct": "B",
-          "explanation": "The `record-lore-for-significant` habit triggers `on-stop` (before session end) and uses the `lore-recorded` check type, which fires when 3 or more source files were modified. This threshold captures significant sessions while ignoring trivial edits."
-        },
-        {
-          "id": "q4",
-          "question": "Practice profiles show that skipping `wisdom-before-implement` correlates with a 3x incident rate. What action should the team take?",
-          "choices": {
-            "A": "Disable the habit since it is not preventing incidents anyway",
-            "B": "Upgrade its severity from `advisory` to `warn` or `block` based on the evidence",
-            "C": "Add more discovery habits to compensate",
-            "D": "The correlation is coincidental — ignore it",
-            "E": "Move the habit from `preflight` to `on-stop` trigger"
-          },
-          "correct": "B",
-          "explanation": "Incident correlations provide concrete evidence for severity decisions. A 3x incident rate when skipping wisdom checks is strong evidence that the check prevents real problems. Upgrading to `warn` makes it visible; upgrading to `block` enforces it. This is the feedback loop in action — practice data drives policy changes."
-        }
-      ]
-    },
-    {
-      "id": "session-intelligence",
-      "title": "Session Intelligence",
-      "content": "## The Session Problem\n\nAI agent sessions are ephemeral. When a session ends — whether by completion, crash, context exhaustion, or human interruption — everything the agent knew vanishes. The next session starts blank, with no memory of what was explored, decided, or partially implemented. Session Intelligence solves this with checkpoints, breadcrumbs, and a global brain that persists knowledge across sessions and even across projects.\n\n## Session Checkpoints\n\nCheckpoints are deliberate snapshots saved at phase transitions. There are four phases:\n\n| Phase | When to Checkpoint | What to Capture |\n|---|---|---|\n| `planning` | After reading requirements, before coding | Plan, approach, key decisions |\n| `implementing` | After starting code changes | Modified files, symbols touched, decisions made |\n| `validating` | After implementation, before tests | All modified files, test plan |\n| `complete` | Task finished | Summary, final file list |\n\nCreate a checkpoint with `paradigm_session_checkpoint`:\n\n```\nparadigm_session_checkpoint({\n  phase: \"implementing\",\n  context: \"Adding JWT auth middleware — RS256 signing, httpOnly refresh tokens\",\n  modifiedFiles: [\"src/middleware/auth.ts\", \"src/handlers/refresh.ts\"],\n  symbolsTouched: [\"#auth-middleware\", \"^authenticated\"],\n  decisions: [\"RS256 over HS256 for public key verification\"]\n})\n```\n\nOnly `phase` and `context` are required — everything else is optional. The context field should be a concise 1-3 sentence summary of your current state of mind. Think of it as answering \"if I were teleported into this session right now, what would I need to know?\"\n\nCheckpoints are stored in `.paradigm/session-checkpoint.json` and auto-expire after 7 days.\n\n## Breadcrumb Tracking\n\nWhile checkpoints are deliberate, breadcrumbs are automatic. Every MCP tool call generates a breadcrumb recording the timestamp, tool name, symbol being modified (if applicable), and a human-readable summary. Breadcrumbs are stored in `.paradigm/session-breadcrumbs.json` with a maximum of 50 entries (auto-rotating — oldest dropped when full).\n\nBreadcrumbs capture the narrative of a session: \"searched for payment symbols → checked ripple on #payment-service → read auth middleware → modified #auth-handler → created ^refund-eligible gate.\" This trail lets the next session understand not just what was done but the reasoning path.\n\n## Session Recovery\n\nRecovery is the payoff. Call `paradigm_session_recover` (or let it happen automatically — recovery data is surfaced on your first Paradigm tool call in a new session) to get:\n\n- **breadcrumbs** — The last session's tool call trail\n- **lastCheckpoint** — The most recent checkpoint with phase, context, and details\n- **symbolsModified** — All symbols that were changed\n- **recentActivity** — A human-readable summary of what happened\n\nThis is crash recovery for AI agents. If a session dies at 87% context with half-finished auth middleware, the next session immediately knows: phase was `implementing`, auth middleware was being added, RS256 was chosen, these files were modified, and tests still need to be written.\n\n## The Global Brain\n\nSession Intelligence extends beyond individual projects through the Global Brain at `~/.paradigm/`. This user-level directory stores:\n\n- **Global wisdom** — Antipatterns and decisions that apply everywhere (e.g., \"never use HS256 for JWT signing in production\")\n- **Global habits** — Behavioral overrides that apply to all projects\n- **Cross-project practice events** — Compliance data aggregated across projects\n\nThe distinction between project scope and global scope is important:\n\n| Scope | Location | Applies To | Example |\n|---|---|---|---|\n| Project | `.paradigm/` | This project only | \"Use Redis for caching in this app\" |\n| Global | `~/.paradigm/` | All projects | \"Always check fragility before modifying critical symbols\" |\n\n## Wisdom Promotion\n\nWhen a project-local wisdom entry proves universally valuable, promote it to global scope with `paradigm_wisdom_promote`. This copies the entry from `.paradigm/wisdom/` to `~/.paradigm/wisdom/`, making it available in every project.\n\nFor example, if a team discovers that \"always wrap Express v5 async middleware in try-catch\" prevents errors across multiple projects, promoting this wisdom means every future project session gets this advice automatically when touching Express middleware.\n\n## Handoff Persistence\n\nWhen context usage exceeds 80-85%, `paradigm_session_health` recommends a handoff. `paradigm_handoff_prepare` creates a structured handoff document with: summary of work done, modified files, symbols touched, next steps, and open questions. This document is stored alongside session data so the receiving session can `paradigm_session_recover` and pick up exactly where the previous session left off.\n\nThe handoff is not just a note — it is a contract between sessions. The outgoing session declares what was done and what remains. The incoming session validates against the actual file state and continues.\n\n## Best Practices\n\n- Checkpoint at every phase transition — the cost is ~100 tokens, the value is crash recovery\n- Write `context` as if briefing a stranger with no prior knowledge\n- Promote wisdom that survives 3+ projects to global scope\n- Use handoffs proactively at 80% context, not reactively at 95%\n- Let breadcrumbs accumulate naturally — don't try to manage them manually",
-      "keyConcepts": [
-        "Four checkpoint phases: planning, implementing, validating, complete",
-        "Breadcrumbs auto-track every MCP tool call (max 50, auto-rotating)",
-        "paradigm_session_recover restores last checkpoint and breadcrumb trail",
-        "Auto-recovery surfaces data on first tool call of a new session",
-        "Global Brain at ~/.paradigm/ stores cross-project wisdom and habits",
-        "paradigm_wisdom_promote moves project wisdom to global scope",
-        "Checkpoints stored in .paradigm/session-checkpoint.json, expire after 7 days",
-        "Handoff at 80% context creates structured continuation contract"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You have finished implementing a feature and are about to write tests. Which checkpoint phase should you save?",
-          "choices": {
-            "A": "`implementing` — you just finished implementing",
-            "B": "`validating` — you are transitioning from implementation to validation",
-            "C": "`complete` — the feature code is done",
-            "D": "`testing` — you are about to test",
-            "E": "`planning` — you need to plan the tests first"
-          },
-          "correct": "B",
-          "explanation": "Checkpoint at the phase you are entering, not the one you are leaving. The `validating` phase captures the state after implementation is complete but before tests/review. If the session crashes now, recovery knows implementation is done and testing is the next step. `complete` is only for when everything (including tests) is finished."
-        },
-        {
-          "id": "q2",
-          "question": "What is the maximum number of breadcrumbs stored, and what happens when the limit is reached?",
-          "choices": {
-            "A": "100 breadcrumbs, then the file is archived and a new one starts",
-            "B": "50 breadcrumbs, then the oldest are dropped as new ones are added",
-            "C": "Unlimited — breadcrumbs grow until the session ends",
-            "D": "50 breadcrumbs, then tracking stops until the next session",
-            "E": "25 breadcrumbs per phase, resetting at each checkpoint"
-          },
-          "correct": "B",
-          "explanation": "Breadcrumbs have a hard cap of 50 entries with auto-rotation — when the 51st breadcrumb is recorded, the oldest one is dropped. This keeps the file small and focused on recent activity while still providing enough trail for meaningful recovery."
-        },
-        {
-          "id": "q3",
-          "question": "A team discovers that 'always validate JWT expiry before refresh' prevents bugs across 4 different projects. What should they do?",
-          "choices": {
-            "A": "Add the wisdom to each project's `.paradigm/wisdom/` individually",
-            "B": "Use `paradigm_wisdom_promote` to move it to `~/.paradigm/wisdom/` for global scope",
-            "C": "Create a new seed habit for JWT validation",
-            "D": "Add it to the CLAUDE.md file in each project",
-            "E": "Record it as a lore entry in the most recent project"
-          },
-          "correct": "B",
-          "explanation": "When wisdom proves valuable across multiple projects, `paradigm_wisdom_promote` copies it from project scope (`.paradigm/wisdom/`) to global scope (`~/.paradigm/wisdom/`). This makes it available automatically in every future session across all projects. Adding it individually (A) or to CLAUDE.md (D) works but doesn't leverage the Global Brain."
-        },
-        {
-          "id": "q4",
-          "question": "Your session is at 82% context usage. What should you do?",
-          "choices": {
-            "A": "Continue working — 82% is still plenty of room",
-            "B": "Immediately stop and call `paradigm_handoff_prepare` with summary and next steps",
-            "C": "Call `paradigm_session_health` to confirm, then proactively prepare a handoff while finishing current work",
-            "D": "Delete old messages to free up context space",
-            "E": "Save a checkpoint and keep working until 95%"
-          },
-          "correct": "C",
-          "explanation": "At 80-85%, the recommendation is proactive handoff preparation. Call `paradigm_session_health` to confirm the recommendation, then prepare the handoff with `paradigm_handoff_prepare` while completing your current task. Waiting until 95% (E) risks running out of context mid-task. The sweet spot is preparing the handoff while you still have room to finish current work cleanly."
-        },
-        {
-          "id": "q5",
-          "question": "A new session starts and the agent calls `paradigm_status`. What happens with session recovery?",
-          "choices": {
-            "A": "The agent must explicitly call `paradigm_session_recover` — recovery is never automatic",
-            "B": "Recovery data is automatically surfaced on the first Paradigm tool call",
-            "C": "Recovery only works if the previous session saved a checkpoint",
-            "D": "The agent must read `.paradigm/session-checkpoint.json` manually",
-            "E": "Recovery data is shown only if the previous session crashed"
-          },
-          "correct": "B",
-          "explanation": "Auto-recovery is triggered on the first Paradigm MCP tool call in a new session — whether that is `paradigm_status`, `paradigm_navigate`, or any other tool. The system surfaces the last checkpoint and recent breadcrumbs without the agent needing to explicitly request recovery. This ensures continuity even if the agent doesn't know to ask."
-        }
-      ]
-    },
-    {
-      "id": "hook-enforcement",
-      "title": "Hook Enforcement & Automation",
-      "content": "## The Compliance Gap\n\nParadigm's value depends on discipline. Purpose files must be updated when code changes. Portal.yaml must reflect route additions. Lore must be recorded for significant sessions. Aspect anchors must point to real code. Without enforcement, these requirements become suggestions that erode over time.\n\nHooks close this gap. They are automated checks that run at specific points in the development workflow, catching violations before they become technical debt. Paradigm uses three hooks, each with a distinct role and severity.\n\n## The Stop Hook\n\nThe stop hook is the primary enforcer. It runs before an agent session completes and can **block** the session from finishing if compliance checks fail.\n\n**Trigger**: Before agent session end (Claude Code: Stop hook, Cursor: pre-finish)\n\n**Seven checks, in order:**\n\n1. **Source files modified without .purpose updates** — If 2+ source files were modified but zero paradigm metadata files (.purpose, portal.yaml, etc.) were updated, the hook blocks. This catches the \"implement and forget\" pattern.\n\n2. **Modified directories missing .purpose coverage** — The hook walks up the directory tree from each modified source file looking for a covering .purpose file. If no .purpose exists anywhere in the ancestor chain (including the project root), it blocks.\n\n3. **Route patterns without portal.yaml** — The hook scans modified files for route declaration patterns (Express `.get()`, `.post()`, decorators like `@Get()`, Rust macros like `#[actix_web::get]`). If routes are detected and portal.yaml was neither present nor modified, it blocks.\n\n4. **Stale aspect anchors** — The hook parses .purpose files for `anchors:` sections and validates that each referenced file still exists. If an anchor points to a deleted file, it blocks.\n\n5. **Pending .purpose freshness** — The post-write hook tracks files edited without .purpose updates in `.paradigm/.pending-review`. The stop hook checks this list: if source files are pending and their covering .purpose was not also modified during the session, it blocks.\n\n6. **Aspect coverage advisory** — If the project uses `~aspects`, the hook advises (non-blocking) to verify that anchor line numbers are still accurate after code changes.\n\n7. **Lore entry for significant sessions** — If 3+ source files were modified and no lore entry was recorded in `.paradigm/lore/entries/`, the hook blocks.\n\n**When blocked**, the hook outputs a clear list of violations with remediation steps. Fix the violations, then complete the session.\n\n## The Post-Write Hook\n\nThe post-write hook runs after every file edit (Edit or Write tool calls). It is **advisory only** — it never blocks.\n\n**Trigger**: After Edit or Write tool completes\n\n**Actions:**\n1. Extracts the edited file path\n2. Skips non-source files (.purpose, portal.yaml, .md, .lock, .json, .yaml, .gitignore, .env files) and paradigm directories (.paradigm/, .claude/, .cursor/)\n3. Appends source file paths to `.paradigm/.pending-review` (deduplicated)\n4. Checks if a .purpose file covers the edited directory\n5. If no .purpose exists: reminds \"No .purpose file covers {dir}/ — Create one\"\n6. Every 3 source files edited: general reminder to update .purpose files\n\nThe `.pending-review` file is the bridge between the post-write hook and the stop hook. Post-write accumulates the list; stop hook validates against it.\n\n## The Pre-Commit Hook\n\nThe pre-commit hook runs before `git commit` and handles index maintenance. It **never blocks**.\n\n**Trigger**: Before Bash commands containing `git commit`\n\n**Actions:**\n1. Runs `paradigm index --quiet` to rebuild scan-index.json, navigator.yaml, and flow-index.json\n2. Stages the rebuilt files so they are included in the commit\n3. Exits 0 (always succeeds)\n\nThis ensures that every commit has a fresh symbol index. Without this hook, the index would drift from the actual codebase between manual `paradigm scan` runs.\n\n## Hook Installation\n\nHooks are installed automatically by `paradigm shift` (full setup) or manually with `paradigm hooks install`. The installer detects the IDE (Claude Code or Cursor) and writes the appropriate hook format.\n\nFor Claude Code, hooks are configured in `.claude/settings.json` using the hooks API — stop hooks, PreToolUse matchers (for Bash commands matching `git commit`), and PostToolUse matchers (for Edit/Write tool calls).\n\n## Remediation Workflow\n\nWhen the stop hook blocks you:\n\n1. **Read the violation list** — Each violation names the specific check that failed\n2. **Update .purpose files** — For modified directories without coverage, create or update the nearest .purpose file\n3. **Update portal.yaml** — If routes were added, add the route and gate definitions\n4. **Fix stale anchors** — If aspect anchors point to deleted/moved files, update the anchor paths\n5. **Record lore** — If 3+ files were modified, call `paradigm_lore_record` with the session summary\n6. **Run `paradigm_reindex`** — Rebuild the index to reflect your updates\n7. **Complete the session** — The stop hook runs again and should pass\n\nThe key insight is that the stop hook is not punitive — it is protective. Every check it enforces prevents a real problem: stale documentation, unprotected routes, orphaned anchors, or lost institutional knowledge.",
-      "keyConcepts": [
-        "Stop hook blocks session completion on compliance failures (7 checks)",
-        "Post-write hook tracks edited files in .paradigm/.pending-review (advisory only)",
-        "Pre-commit hook auto-rebuilds index before git commit (never blocks)",
-        ".pending-review bridges post-write tracking to stop hook validation",
-        "2+ source files + 0 paradigm updates = stop hook violation",
-        "3+ source files without lore entry = stop hook violation",
-        "Routes detected without portal.yaml = stop hook violation",
-        "paradigm hooks install or paradigm shift for automatic installation"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You modified 4 source files and updated one .purpose file but did not record a lore entry. The stop hook runs. What happens?",
-          "choices": {
-            "A": "It passes — the .purpose update satisfies all requirements",
-            "B": "It blocks on two violations: .purpose freshness for the other 3 files, and missing lore entry for a 4-file session",
-            "C": "It blocks only on the missing lore entry — 4 files exceeds the 3-file threshold",
-            "D": "It passes — .purpose coverage is sufficient, lore is optional",
-            "E": "It blocks only on .purpose freshness — the other 3 files need coverage"
-          },
-          "correct": "C",
-          "explanation": "The stop hook checks multiple conditions independently. The '.purpose freshness' check passes because you did update a .purpose file (the '2+ source files with 0 paradigm updates' check fails only when zero paradigm files were touched). However, 4 modified source files exceeds the 3-file lore recording threshold, so the missing lore entry causes a block. Whether the other files need .purpose coverage depends on whether they have covering .purpose files in ancestor directories."
-        },
-        {
-          "id": "q2",
-          "question": "The post-write hook just fired after you edited `src/services/payment.ts`. Which of these files would it skip tracking?",
-          "choices": {
-            "A": "`src/services/payment.ts` — it tracks this file",
-            "B": "`.paradigm/config.yaml` — it skips paradigm directory files",
-            "C": "`src/middleware/auth.ts` — it would track this too",
-            "D": "`package.json` — it skips .json files",
-            "E": "Both B and D are skipped"
-          },
-          "correct": "E",
-          "explanation": "The post-write hook skips non-source files (.json, .yaml, .md, .lock, .env, .gitignore) and paradigm directories (.paradigm/, .claude/, .cursor/). Both `.paradigm/config.yaml` (paradigm directory) and `package.json` (.json extension) are skipped. Only actual source code files like .ts, .js, .rs, .py are tracked in .pending-review."
-        },
-        {
-          "id": "q3",
-          "question": "What does the pre-commit hook do, and can it block a commit?",
-          "choices": {
-            "A": "Runs all habit checks and blocks if any severity=block habits are violated",
-            "B": "Validates portal.yaml and blocks if gates are undefined",
-            "C": "Rebuilds the symbol index and stages the updated files — never blocks",
-            "D": "Checks .purpose freshness and blocks if files are stale",
-            "E": "Records a lore entry for the commit — never blocks"
-          },
-          "correct": "C",
-          "explanation": "The pre-commit hook has a single job: rebuild the symbol index (`paradigm index --quiet`) and stage the rebuilt files (scan-index.json, navigator.yaml, flow-index.json) so they are included in the commit. It always exits 0 — it never blocks. This ensures every commit has a fresh index without manual intervention."
-        },
-        {
-          "id": "q4",
-          "question": "The stop hook detects that `src/routes/api.ts` contains Express `.post()` calls but `portal.yaml` does not exist. What happens?",
-          "choices": {
-            "A": "Advisory warning — portal.yaml is recommended but not required",
-            "B": "The hook blocks — route patterns detected without portal.yaml is a violation",
-            "C": "The hook skips this check — portal.yaml is only required for projects that already have one",
-            "D": "The hook creates a minimal portal.yaml automatically",
-            "E": "The hook blocks only if the route handles user data"
-          },
-          "correct": "B",
-          "explanation": "The stop hook scans modified files for route declaration patterns (`.get()`, `.post()`, etc.). If route patterns are found and portal.yaml was neither present in the project nor modified during the session, the hook blocks. This enforces the rule that all protected routes must be declared in portal.yaml."
-        },
-        {
-          "id": "q5",
-          "question": "You are blocked by the stop hook. The violations list shows: 'stale aspect anchor: src/old/audit.ts no longer exists'. How do you fix this?",
-          "choices": {
-            "A": "Delete the aspect from the .purpose file — aspects with stale anchors are invalid",
-            "B": "Create an empty file at `src/old/audit.ts` to satisfy the anchor check",
-            "C": "Update the anchor path in the .purpose file to point to the new location of the audit code",
-            "D": "Run `paradigm_aspect_check` — it auto-fixes stale anchors",
-            "E": "Ignore it — stale anchors are advisory only"
-          },
-          "correct": "C",
-          "explanation": "Aspects require valid code anchors. If the file was moved or renamed, update the anchor path in the .purpose file to point to the new location. If the code was deleted entirely, you may need to remove the aspect or create new enforcement code. Creating an empty file (B) is a hack that defeats the purpose. `paradigm_aspect_check` validates but doesn't auto-fix."
-        }
-      ]
-    },
-    {
-      "id": "advanced-workflows",
-      "title": "The Complete Workflow",
-      "content": "## Putting It All Together\n\nYou have learned the five advanced systems individually. Now let's see how they work together in a complete development workflow. Every system has a role, and the handoffs between them create a feedback loop that gets smarter with every session.\n\n## The Full Cycle\n\nHere is the complete Paradigm workflow for a non-trivial task:\n\n### Phase 1: Preflight\n\n```\n1. paradigm_session_recover       → Load previous session context\n2. paradigm_pm_preflight           → Get compliance plan for the task\n3. paradigm_habits_check(preflight) → Verify discovery habits are followed\n4. paradigm_ripple                 → Check impact of planned changes\n5. paradigm_wisdom_context         → Get team knowledge for affected symbols\n6. paradigm_practice_context       → Get habit-aware warnings for symbols\n7. paradigm_session_checkpoint(planning) → Save plan before coding\n```\n\nNotice the layering: session recovery provides continuity, preflight ensures preparation, habits check enforces discovery discipline, ripple and wisdom provide context, practice context adds behavioral awareness, and the checkpoint enables crash recovery.\n\n### Phase 2: Implementation\n\n```\n8. Write code                      → Implement the feature\n   → Post-write hook fires         → Tracks edited files in .pending-review\n   → Post-write advisory           → Reminds about .purpose coverage\n9. Update .purpose files           → Document new/changed symbols\n10. Update portal.yaml             → Add routes and gates (if applicable)\n11. paradigm_session_checkpoint(implementing) → Save progress\n```\n\nThe post-write hook acts as a running tally. Every source file edit is tracked, and periodic reminders keep documentation top of mind. Updating .purpose and portal.yaml during implementation (not after) prevents the stop hook from blocking at the end.\n\n### Phase 3: Validation\n\n```\n12. paradigm_flow_check          → Verify flows are complete\n13. paradigm_aspect_check           → Verify aspect anchors are valid\n14. paradigm_pm_postflight          → Run post-implementation governance\n15. paradigm_habits_check(postflight) → Verify documentation/testing habits\n16. paradigm_session_checkpoint(validating) → Save pre-test state\n```\n\nValidation catches issues before they become stop hook violations. Flow validation ensures multi-step processes are complete. Aspect checks confirm anchors point to real code. Postflight governance catches missing .purpose files and undefined gates.\n\n### Phase 4: Recording\n\n```\n17. paradigm_lore_record            → Record the session's work\n18. paradigm_history_record         → Log implementation to symbol history\n19. paradigm_reindex                → Rebuild the symbol index\n20. paradigm_session_checkpoint(complete) → Mark task complete\n```\n\nRecording preserves institutional knowledge. The lore entry captures what was done and why. History record logs implementation details to individual symbol timelines. Reindexing ensures the symbol index reflects all changes.\n\n### Phase 5: Commit\n\n```\n21. git commit                      → Commit changes\n    → Pre-commit hook fires         → Auto-rebuilds index, stages updated files\n    → Stop hook fires               → Validates all compliance checks\n22. If stop hook blocks             → Fix violations, re-attempt\n23. If stop hook passes             → Session complete\n```\n\nThe commit phase is where enforcement happens. The pre-commit hook ensures the index is fresh. The stop hook validates everything: .purpose coverage, portal.yaml compliance, aspect anchors, lore recording, and pending review freshness.\n\n## How Systems Reinforce Each Other\n\nThe power of the complete workflow is in the feedback loops:\n\n**Sentinel catches what Habits miss.** If an agent skips the `ripple-before-modify` habit and introduces a breaking change, Sentinel records the incident. The practice profile then shows that skipping ripple correlates with incidents — evidence to upgrade the habit severity.\n\n**Lore preserves what Sessions forget.** Session breadcrumbs and checkpoints are ephemeral — they expire after 7 days. Lore entries are permanent. The checkpoint gets you through a crash; the lore entry gets the team through the next 6 months.\n\n**Wisdom surfaces what Lore accumulates.** Lore entries record individual sessions. Wisdom distills patterns across sessions: \"every time we modify #payment-service, check for null references on the refund object.\" Wisdom is lore, refined.\n\n**Hooks enforce what Habits recommend.** Habits at `advisory` severity are suggestions. The stop hook at `block` severity is enforcement. The workflow starts with advice (habits check) and ends with enforcement (stop hook). This graduated approach teaches good behavior before punishing bad behavior.\n\n## Capstone Scenario\n\nImagine you are adding a refund endpoint to a payment system. Here is how the complete workflow plays out:\n\n1. **Session recover** reveals the previous session added the payment processor but did not add refunds\n2. **Preflight** shows you need to check `#payment-service`, `$checkout-flow`, and `^authenticated`\n3. **Habits check** confirms you called ripple and wisdom — discovery habits followed\n4. **Ripple** shows `#payment-service` has 4 downstream dependents\n5. **Wisdom** warns: \"always null-check refund objects — see incident INC-042\"\n6. You implement the refund endpoint with proper null checks\n7. **Post-write hook** tracks 5 edited files in `.pending-review`\n8. You update .purpose with `#refund-handler` and portal.yaml with `^refund-eligible` gate\n9. **Postflight** confirms all gates are declared and flows are valid\n10. **Lore record** captures the session with the decision to require `^refund-eligible`\n11. **Commit** triggers pre-commit (index rebuild) and stop hook (all checks pass)\n12. Three weeks later, a similar null reference hits — **Sentinel** matches pattern `payment-null-ref-001` and resolves it in 5 minutes using the recorded fix\n\nThis is Paradigm at full power: every system contributing, every session building on the last, every incident making the next resolution faster.",
-      "keyConcepts": [
-        "Five-phase workflow: preflight → implement → validate → record → commit",
-        "Session recovery provides continuity between sessions",
-        "Post-write hook tracks files during implementation for stop hook validation",
-        "Recording phase preserves lore, history, and fresh index before commit",
-        "Stop hook is the final enforcement gate before session completion",
-        "Sentinel catches what Habits miss — incidents drive severity upgrades",
-        "Lore preserves what Sessions forget — permanent vs ephemeral knowledge",
-        "Graduated enforcement: habits advise, hooks enforce"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "In the complete workflow, why does `paradigm_habits_check(preflight)` run BEFORE `paradigm_ripple` and `paradigm_wisdom_context`?",
-          "choices": {
-            "A": "To block the session if discovery habits were violated in the previous session",
-            "B": "To verify that the agent intends to call discovery tools — the habit check reminds and tracks, while the actual tools provide the context",
-            "C": "Because habits must always run first regardless of workflow position",
-            "D": "To generate the list of symbols that ripple and wisdom should check",
-            "E": "The order does not matter — they can run in any sequence"
-          },
-          "correct": "B",
-          "explanation": "The preflight habits check evaluates whether discovery habits (ripple, navigate, wisdom) are being followed. It runs early to remind and track compliance. The actual MCP tools (ripple, wisdom_context) run after to provide the substantive context. The habit check is about behavioral discipline; the tools are about information gathering."
-        },
-        {
-          "id": "q2",
-          "question": "An agent implements a feature, updates .purpose files, but forgets to record lore before committing. The session modified 5 source files. What sequence of events occurs?",
-          "choices": {
-            "A": "Pre-commit hook blocks the commit until lore is recorded",
-            "B": "Stop hook blocks, citing missing lore entry → agent records lore → re-attempts commit → stop hook passes",
-            "C": "Commit succeeds but the next session receives a warning about missing lore",
-            "D": "The post-write hook retroactively creates a lore entry from tracked files",
-            "E": "The commit succeeds — lore is enforced by habits, not hooks"
-          },
-          "correct": "B",
-          "explanation": "The stop hook checks for lore entries when 3+ source files were modified. With 5 files and no lore entry, it blocks. The agent must then call `paradigm_lore_record` with the session summary, and re-attempt the commit. The pre-commit hook only rebuilds the index — it doesn't check compliance. Lore enforcement lives in the stop hook."
-        },
-        {
-          "id": "q3",
-          "question": "How does Sentinel benefit from the Habits system?",
-          "choices": {
-            "A": "Sentinel directly calls habit checks during incident recording",
-            "B": "Practice profiles show correlations between skipped habits and incident rates, providing evidence for severity upgrades",
-            "C": "Habits automatically resolve Sentinel incidents when compliance is high",
-            "D": "Sentinel and Habits are independent systems with no interaction",
-            "E": "Habits disable Sentinel checks when compliance is above 90%"
-          },
-          "correct": "B",
-          "explanation": "The feedback loop between Habits and Sentinel works through practice profiles. When an agent frequently skips `ripple-before-modify` and the symbols it touches have higher incident rates, the practice profile surfaces this correlation. This provides data-driven evidence to upgrade the habit's severity from advisory to warn or block — closing the loop between behavior and outcomes."
-        },
-        {
-          "id": "q4",
-          "question": "What is the relationship between Lore entries and Session checkpoints?",
-          "choices": {
-            "A": "They are the same thing — checkpoints are stored as lore entries",
-            "B": "Checkpoints are ephemeral (7-day expiry) for crash recovery; lore entries are permanent for institutional memory",
-            "C": "Lore entries are auto-generated from checkpoints at session end",
-            "D": "Checkpoints replace lore entries in Paradigm v2",
-            "E": "Lore entries expire after 30 days; checkpoints are permanent"
-          },
-          "correct": "B",
-          "explanation": "Checkpoints and lore serve different purposes with different lifespans. Checkpoints are ephemeral snapshots for crash recovery — they expire after 7 days because their value is immediate continuity. Lore entries are permanent project history — they capture decisions, learnings, and context that remain valuable months or years later. You need both: checkpoints for resilience, lore for memory."
-        },
-        {
-          "id": "q5",
-          "question": "A team's practice profile shows high compliance across all categories, yet incidents keep occurring in `#payment-service`. What system should they investigate?",
-          "choices": {
-            "A": "Habits — add more habits targeting the payment service",
-            "B": "Hooks — the stop hook might not be running for payment-related changes",
-            "C": "Sentinel — check `paradigm_sentinel_patterns` and `paradigm_sentinel_stats` for the symbol to identify recurring failure patterns and resolution gaps",
-            "D": "Lore — the payment service lore entries might be inaccurate",
-            "E": "Session Intelligence — breadcrumbs might be losing payment context"
-          },
-          "correct": "C",
-          "explanation": "High habit compliance means the behavioral discipline is fine — agents are doing the right things. If incidents persist despite good practices, the issue is likely in the code or architecture, not the process. Sentinel's pattern analysis (`paradigm_sentinel_patterns`) can reveal if the same failure keeps recurring despite resolutions, and `paradigm_sentinel_stats` can show the symbol's incident rate and resolution effectiveness. The answer lives in the incident data, not the compliance data."
-        }
-      ]
-    },
-    {
-      "id": "aspect-graph-advanced",
-      "title": "The Aspect Graph at Scale",
-      "content": "## Beyond the Basics\n\nPARA 201 introduced the Aspect Graph's internals — the SQLite schema, materialization pipeline, and recursive ripple. This lesson takes you deeper: building custom detectors, advanced graph queries, drift detection in CI/CD, search learning optimization, and governing aspects at enterprise scale.\n\n## Building Custom Aspect Detection Patterns\n\nParadigm ships with 8 built-in detectors that `paradigm_aspect_suggest_scan` uses to find undocumented aspects in source code:\n\n1. **Magic numbers** — Numeric literals that aren't 0 or 1 (e.g., `timeout: 30000`, `maxRetries: 3`)\n2. **Hardcoded strings** — String literals used in conditionals or assignments that smell like configuration (e.g., `'production'`, `'us-east-1'`)\n3. **Rate limits** — Patterns like `rateLimit(100)`, `throttle(1000)`, or variable names containing `limit`, `throttle`, `quota`\n4. **Time values** — Durations, timeouts, TTLs, and expiry values (e.g., `86400`, `24 * 60 * 60`)\n5. **Environment checks** — `process.env`, `std::env`, `os.environ` patterns that branch on environment variables\n6. **Feature flags** — Conditional logic gated on feature names (e.g., `isEnabled('new-checkout')`, `featureFlags.get()`)\n7. **Regex patterns** — Regular expressions used for validation (e.g., email patterns, URL matchers)\n8. **Assertion guards** — Invariant checks using `assert`, `invariant()`, `expect()` that enforce guarantees\n\nTo extend the detection system, you define custom detectors in `.paradigm/aspect-detectors.yaml`:\n\n```yaml\ndetectors:\n  - id: compliance-annotation\n    name: Compliance Annotations\n    description: Detects SOC2/GDPR compliance annotations in code\n    patterns:\n      - regex: \"@(SOC2|GDPR|PCI|HIPAA)\"\n        languages: [typescript, javascript, java]\n      - regex: \"#\\[compliance\\(\"\n        languages: [rust]\n    suggestedCategory: rule\n    suggestedSeverity: critical\n    suggestedTags: [compliance, security]\n\n  - id: retry-policy\n    name: Retry Policies\n    description: Detects retry/backoff configurations\n    patterns:\n      - regex: \"(retryPolicy|backoff|maxAttempts|retryCount)\"\n        languages: [typescript, javascript, python]\n    suggestedCategory: configuration\n    suggestedSeverity: medium\n```\n\nCustom detectors are loaded alongside the built-in 8 during `paradigm_aspect_suggest_scan`. They follow the same interface: match source code patterns, suggest a category and severity, and let the user decide whether to formalize the finding as a `~aspect`.\n\n## Graph Querying Strategies\n\nThe aspect graph supports three primary querying patterns, each suited to different use cases:\n\n### BFS Traversal (Neighborhood Analysis)\n\n`paradigm_aspect_graph` uses breadth-first search to explore the neighborhood of a symbol. The `hops` parameter controls how far to traverse:\n\n- **1 hop** — Direct connections only. Use this when you need to know what a single aspect directly relates to. Fast, focused, minimal noise.\n- **2 hops** — Friends-of-friends. Reveals indirect relationships: \"this aspect relates to that aspect, which relates to that component.\" The sweet spot for most queries.\n- **3+ hops** — Extended neighborhood. Useful for understanding how distant parts of the codebase connect through aspects. Gets noisy in dense graphs.\n\nThe multiplicative weight decay means that each hop reduces confidence. An explicit edge (weight 1.0) followed by an inferred edge (weight 0.5) produces a path weight of 0.5. Two inferred edges produce 0.25. The `minWeight` threshold (default 0.1) prunes low-confidence paths automatically.\n\n### Heatmap-Driven Exploration\n\n`paradigm_aspect_heatmap` ranks aspects by access frequency. This is not about what aspects ARE important — it is about what aspects are USED most. The distinction matters:\n\n- An aspect accessed 50 times via search but never via ripple might have a discoverability problem — people search for it because it is hard to find through the graph.\n- An aspect accessed primarily via ripple has good graph connectivity — it naturally surfaces during impact analysis.\n- An aspect with zero access across all types may be stale, poorly named, or irrelevant.\n\nHeatmap data is the starting point for governance reviews. Aspects that nobody accesses should be evaluated for removal or renaming.\n\n### Edge-Filtered Queries\n\nWhen calling `paradigm_aspect_graph`, you can filter by edge relation to narrow results:\n\n- `enforced-by` — Find all aspects that enforce a given component. Useful when changing a component to know what rules apply.\n- `depends-on` — Find dependency chains. If `~token-expiry-24h` depends-on `~jwt-signing-rs256`, changing JWT signing affects token expiry.\n- `contradicts` — Find conflicting aspects. Two aspects that contradict each other signal an architectural tension that needs resolution.\n- `supersedes` — Find deprecated-but-still-referenced aspects. The superseding aspect should be the authoritative one.\n- `related-to` — The weakest relation. Useful for discovery but not for impact analysis.\n\n## Drift Detection in CI/CD\n\nAspect drift occurs when the code at an anchor location changes without updating the aspect definition. The `paradigm_aspect_drift` tool detects this using SHA-256 content hashes.\n\nDuring materialization, the pipeline computes a SHA-256 hash of the code at each anchor's line range and stores it in the `anchors.content_hash` column. When `paradigm_aspect_drift` runs later, it re-reads the code at those line ranges, computes a new hash, and compares. A mismatch means the code changed — the anchor is drifted.\n\nFor CI/CD integration, add drift detection as a pipeline step:\n\n```yaml\n# .github/workflows/paradigm.yml\nsteps:\n  - name: Check aspect drift\n    run: |\n      paradigm scan --quiet\n      paradigm doctor --strict --json | jq '.aspects.drifted'\n      if [ $(paradigm doctor --json | jq '.aspects.drifted | length') -gt 0 ]; then\n        echo \"::error::Aspect anchors have drifted\"\n        exit 1\n      fi\n```\n\nThe `--strict` flag treats drifted anchors as errors rather than warnings. In a mature project, you want drift detection to block merges — it ensures that aspect documentation stays synchronized with code changes.\n\nDrift detection is also available per-aspect via the MCP tool:\n\n```\nparadigm_aspect_drift({ aspectId: 'token-expiry-24h' })\n```\n\nThis returns: the aspect ID, each anchor with its stored hash vs current hash, whether each anchor has drifted, and the specific lines that changed. Use this during code review to verify that refactors updated their aspect anchors.\n\n## Search Learning Loop Optimization\n\nThe three-tier search system improves over time through the confirm-and-decay mechanism. Here is how to optimize it:\n\n### Tier Priority\n\n1. **Tier 1: Learned mappings** — Query-to-aspect weights in the `search_weights` table. If a query matches a stored mapping with weight >= 1.0, the result is returned immediately. This is instant because it is a simple key-value lookup.\n2. **Tier 2: FTS5 full-text search** — SQLite's FTS5 engine searches aspect descriptions, values, and categories. Returns results ranked by BM25 relevance. Accurate but slower than Tier 1.\n3. **Tier 3: Fuzzy matching** — Levenshtein distance-based matching with a configurable threshold. Catches typos and partial matches. Slowest but most forgiving.\n\n### Warming the Learning System\n\nA new project's search starts cold — no learned mappings exist. Every search falls through to Tier 2 or 3. To warm the system:\n\n1. Run common queries for your project's domain (e.g., search for 'expiry', 'rate limit', 'auth')\n2. Confirm the best result with `paradigm_aspect_confirm` for each query\n3. After 3-5 confirmations per query, the learned weight exceeds the Tier 1 threshold\n\nThe decay mechanism (confirmed +1.0, others *0.95) means that a single confirmation is enough to create a Tier 1 entry. But multiple confirmations build a stronger mapping that resists displacement.\n\n### Diagnosing Search Issues\n\nWhen search returns unexpected results:\n\n- Check `search_weights` table entries for the query — are stale mappings dominating?\n- Verify aspect descriptions contain the keywords you are searching for (FTS5 searches descriptions)\n- Check for typos in the query that might prevent Tier 2 matches but trigger Tier 3 fuzzy results\n- Use `paradigm_aspect_heatmap` to see if the expected aspect is ever accessed — a zero-access aspect might have a discovery problem\n\n## Aspect Governance at Scale\n\nWhen a project exceeds 100 aspects, governance becomes critical. Without it, aspects accumulate as stale documentation, anchor drift goes undetected, and the graph becomes noisy rather than useful.\n\n### The Governance Review Cycle\n\nRun quarterly aspect reviews using this process:\n\n1. **Heatmap analysis** — `paradigm_aspect_heatmap({ limit: 0 })` returns ALL aspects ranked by access. The bottom 20% are candidates for removal or consolidation.\n2. **Drift audit** — `paradigm doctor --strict` catches all drifted anchors. Drifted aspects either need anchor updates or should be marked stale.\n3. **Category distribution** — Check that aspect categories are balanced. A project with 80 rules and 2 decisions might be over-documenting constraints while missing strategic choices.\n4. **Edge health** — Check for orphaned aspects (no edges to any other symbol). An aspect with zero edges is either standalone (legitimate but rare) or poorly connected.\n5. **Search weight review** — Check the `search_weights` table for queries with multiple high-weight mappings, which indicate ambiguous terminology.\n\n### Naming Conventions at Scale\n\nWith 100+ aspects, naming collisions and ambiguity become real problems. Establish conventions:\n\n- **Category prefix** — Prefix aspects with their category: `~rule-no-console-log`, `~decision-use-redis`, `~constraint-max-upload-10mb`\n- **Domain grouping** — Group related aspects by domain: `~auth-token-expiry`, `~auth-session-timeout`, `~auth-refresh-rotation`\n- **Version suffix** — When aspects evolve: `~rate-limit-v2` supersedes `~rate-limit-v1` with an explicit `supersedes` edge\n\n### Delegation and Ownership\n\nFor large teams, assign aspect ownership:\n\n```yaml\n~payment-idempotency:\n  description: Payment operations must be idempotent\n  owner: payments-team\n  reviewers: [platform-team, security-team]\n```\n\nThe `owner` field indicates who maintains the aspect, and `reviewers` lists teams that should be consulted when the aspect changes. This is purely metadata — Paradigm does not enforce it — but it guides humans and AI agents when modifications are needed.",
-      "keyConcepts": [
-        "8 built-in detectors: magic numbers, hardcoded strings, rate limits, time values, env checks, feature flags, regex patterns, assertion guards",
-        "Custom detectors defined in .paradigm/aspect-detectors.yaml extend the suggest-scan system",
-        "BFS traversal with multiplicative weight decay prunes low-confidence paths automatically",
-        "Heatmap-driven exploration reveals usage patterns vs importance assumptions",
-        "Five edge relations for filtered queries: enforced-by, depends-on, contradicts, supersedes, related-to",
-        "Drift detection uses SHA-256 content hashes comparing stored vs current code at anchor line ranges",
-        "CI/CD integration via paradigm doctor --strict --json blocks merges on drifted anchors",
-        "Three-tier search: learned mappings (instant) -> FTS5 (accurate) -> fuzzy (forgiving)",
-        "Warm the learning system with 3-5 confirmations per common query",
-        "Governance review cycle: heatmap analysis, drift audit, category distribution, edge health, search weight review"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "How many built-in detectors does paradigm_aspect_suggest_scan use, and which of these is NOT one of them?",
-          "choices": {
-            "A": "8 built-in detectors; 'database schema' is not one of them",
-            "B": "6 built-in detectors; 'magic numbers' is not one of them",
-            "C": "8 built-in detectors; 'rate limits' IS one of them (trick question)",
-            "D": "10 built-in detectors; 'feature flags' is not one of them",
-            "E": "5 built-in detectors; 'environment checks' is not one of them"
-          },
-          "correct": "A",
-          "explanation": "paradigm_aspect_suggest_scan uses 8 built-in detectors: magic numbers, hardcoded strings, rate limits, time values, environment checks, feature flags, regex patterns, and assertion guards. 'Database schema' is not among them. Custom detectors can be added via .paradigm/aspect-detectors.yaml to extend the detection system."
-        },
-        {
-          "id": "q2",
-          "question": "You want to find all rules that enforce constraints on #payment-service through the aspect graph. Which query approach is most effective?",
-          "choices": {
-            "A": "paradigm_aspect_search({ query: 'payment rules' }) to find them by text",
-            "B": "paradigm_aspect_graph({ symbol: '#payment-service', hops: 1 }) filtered by 'enforced-by' edge relation",
-            "C": "paradigm_aspect_heatmap({ limit: 100 }) and manually scan for payment-related aspects",
-            "D": "paradigm_aspect_drift({ aspectId: '#payment-service' }) to find stale rules",
-            "E": "paradigm_ripple({ symbol: '#payment-service' }) without any graph filtering"
-          },
-          "correct": "B",
-          "explanation": "An edge-filtered graph query at 1 hop with the 'enforced-by' relation is the most direct approach. It returns exactly the aspects that enforce rules on the target component. Search (A) finds by text, not by graph relationship. Heatmap (C) ranks by usage, not by target. Drift (D) checks anchor freshness, not relationships."
-        },
-        {
-          "id": "q3",
-          "question": "Your CI pipeline should fail when aspect anchors have drifted. Which command configuration achieves this?",
-          "choices": {
-            "A": "paradigm doctor with no flags — drift is always a blocking error",
-            "B": "paradigm doctor --strict — treats drifted anchors as errors that cause a non-zero exit code",
-            "C": "paradigm scan --fix — automatically fixes drifted anchors",
-            "D": "paradigm_aspect_drift with no arguments — checks all aspects and exits non-zero on drift",
-            "E": "paradigm lint --strict — lint checks include drift detection"
-          },
-          "correct": "B",
-          "explanation": "paradigm doctor --strict treats warnings (including drifted anchors) as errors, producing a non-zero exit code that fails the CI step. Without --strict, drifted anchors are warnings that do not block. paradigm scan rebuilds the index but does not check drift. paradigm lint checks .purpose file structure, not anchor content hashes."
-        },
-        {
-          "id": "q4",
-          "question": "A new project's aspect search always falls to Tier 3 (fuzzy matching). How do you warm the learning system so common queries use Tier 1?",
-          "choices": {
-            "A": "Manually edit the search_weights SQLite table to insert mappings",
-            "B": "Run paradigm_reindex with a --warm-search flag",
-            "C": "Run common queries with paradigm_aspect_search, then confirm the best results with paradigm_aspect_confirm for each query",
-            "D": "Wait for 100+ searches to accumulate — Tier 1 learns automatically without confirmation",
-            "E": "Set limits.searchLearningRate to a higher value in config.yaml"
-          },
-          "correct": "C",
-          "explanation": "The learning system requires explicit confirmation via paradigm_aspect_confirm. When you search for a term and confirm the best result, the confirmed aspect gets +1.0 weight for that query. After 3-5 confirmations, the weight exceeds the Tier 1 threshold and future queries return instantly. There is no automatic learning without confirmation — the system relies on user feedback to improve."
-        },
-        {
-          "id": "q5",
-          "question": "During a quarterly governance review, the heatmap shows that 30 aspects out of 120 have zero access across all types (search, ripple, navigate, direct). What does this indicate and what should you do?",
-          "choices": {
-            "A": "These aspects are well-documented and need no changes — zero access means no issues",
-            "B": "Delete all 30 immediately — unused aspects are always stale",
-            "C": "These aspects may be stale, poorly named, or irrelevant — evaluate each for removal, renaming, or consolidation as part of the governance review",
-            "D": "Increase their severity to 'critical' to force agents to access them",
-            "E": "Move them to a separate 'archive' section in the .purpose files"
-          },
-          "correct": "C",
-          "explanation": "Zero-access aspects are candidates for review, not automatic deletion. Some may be legitimate but poorly named (rename to improve discoverability). Some may be truly stale with drifted anchors (remove or update). Some may have been superseded by newer aspects (consolidate with supersedes edges). The governance review evaluates each case individually."
-        }
-      ]
-    },
-    {
-      "id": "task-management",
-      "title": "Task Management",
-      "content": "## Why Tasks Exist\n\nAI agent sessions are stateless. You can discuss a plan, identify five things that need doing, and then the session ends. The next session starts blank — those five items are gone. Sticky notes on a monitor do not help when your developer is a language model.\n\nParadigm's Task Management system provides a persistent scratch pad that survives context windows. Tasks are lightweight, date-partitioned YAML entries that capture what needs doing, how urgent it is, and what project knowledge relates to it. They are not a full project management system — they are the missing short-term memory between sessions.\n\nThe key difference from lore: lore records what happened (past tense). Tasks record what should happen (future tense). Together they form a complete timeline — memory of the past and intention for the future.\n\n## Anatomy of a Task\n\nEvery task follows a consistent structure:\n\n```yaml\nid: T-2026-02-26-001\nblurb: \"Add rate limiting to the /api/payments endpoint\"\npriority: high\nstatus: open\ntags: [security, payments]\nrelated_lore: [L-2026-02-25-003]\ncreated: \"2026-02-26T10:15:00Z\"\nupdated: \"2026-02-26T10:15:00Z\"\n```\n\nThe `id` field is auto-generated: `T-{date}-{sequence}`, following the same date-partitioned pattern as lore entries. The `blurb` is the only required field — a concise description of what needs to be done. Everything else is optional but useful.\n\nThree priority levels exist: `high` (do this soon), `medium` (do this eventually), and `low` (nice to have). Tasks without an explicit priority default to `medium`.\n\nThree statuses track lifecycle: `open` (needs doing), `done` (completed), and `shelved` (parked for later — not abandoned, just deferred).\n\n## Storage: Date-Partitioned YAML\n\nTasks live in `.paradigm/tasks/entries/` organized by creation date:\n\n```\n.paradigm/tasks/\n  entries/\n    2026-02-25/\n      T-2026-02-25-001.yaml\n      T-2026-02-25-002.yaml\n    2026-02-26/\n      T-2026-02-26-001.yaml\n```\n\nDate partitioning keeps directories small. Each task is a standalone YAML file, making them easy to read, edit, and version-control. The date in the path matches the date in the task ID.\n\n## The Five MCP Tools\n\n**`paradigm_task_create`** — Create a new task. The `blurb` field is required — a short description of what needs to be done. Optional fields include `priority` (high/medium/low), `tags` (for categorization and filtering), and `related_lore` (linking to lore entries that provide context). The task is written to the correct date directory with an auto-incremented ID and starts with status `open`.\n\n**`paradigm_task_list`** — List tasks with filters. Filter by `status` (open/done/shelved/all), `priority` (high/medium/low), or `tag`. Results are sorted by priority (high first) then by date (newest first). Without filters, it returns all open tasks.\n\n**`paradigm_task_update`** — Update any field on an existing task by ID. You can change the blurb, priority, status, tags, or related_lore. Only specified fields are modified — everything else is preserved.\n\n**`paradigm_task_done`** — Shorthand to mark a task as complete. Pass the task ID and the status changes to `done` with an updated timestamp. This is equivalent to `paradigm_task_update` with `status: done` but more ergonomic for the common case.\n\n**`paradigm_task_shelve`** — Shorthand to shelve a task for later. Pass the task ID and the status changes to `shelved`. Shelved tasks are not deleted — they remain searchable and can be reopened by updating their status back to `open`.\n\n## Session Recovery Integration\n\nThe top 5 open tasks are automatically surfaced during session recovery. When a new session starts and the agent calls any Paradigm MCP tool, the recovery data includes the highest-priority open tasks alongside the usual breadcrumbs and checkpoint data.\n\nThis means every session begins with awareness of outstanding work. The agent does not need to ask \"what should I work on?\" — the task list is already there, sorted by priority. This is the scratch-pad-that-survives pattern: write tasks in one session, see them in the next.\n\n## When to Create Tasks\n\nCreate tasks when:\n- You identify work that cannot be completed in the current session\n- A code review surfaces follow-up items\n- You discover a bug or improvement while working on something else\n- The user mentions something that should be tracked but is not the current focus\n- A handoff needs to communicate specific next steps\n\nDo not use tasks for:\n- Tracking completed work (that is what lore is for)\n- Long-term roadmap items (use your project management tool)\n- Architectural decisions (use lore entries with type `decision`)\n\nTasks are ephemeral intentions — they should be created quickly, completed or shelved promptly, and never allowed to accumulate into a backlog of hundreds. If your task list grows beyond 20-30 open items, it is time to triage: shelve the low-priority items and focus on what matters.",
-      "keyConcepts": [
-        "Tasks are persistent scratch-pad items that survive context windows",
-        "Auto-generated IDs: T-{date}-{sequence}, date-partitioned in .paradigm/tasks/entries/{YYYY-MM-DD}/",
-        "Three priority levels: high, medium (default), low",
-        "Three statuses: open, done, shelved",
-        "Five MCP tools: paradigm_task_create, paradigm_task_list, paradigm_task_update, paradigm_task_done, paradigm_task_shelve",
-        "Top 5 open tasks surfaced automatically on session recovery",
-        "Tasks record future intention; lore records past action"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You are midway through adding authentication when you notice the payment service has a null-check bug. You cannot fix it now. What is the correct action?",
-          "choices": {
-            "A": "Record a lore entry describing the bug for future reference",
-            "B": "Call `paradigm_task_create` with a blurb describing the null-check bug, priority high, and tags [bug, payments]",
-            "C": "Add a TODO comment in the payment service code and move on",
-            "D": "Call `paradigm_sentinel_record` to log it as an incident",
-            "E": "Mention it in the session's handoff summary and hope the next session picks it up"
-          },
-          "correct": "B",
-          "explanation": "This is exactly what tasks are for — capturing work you cannot complete in the current session. A task with priority `high` ensures it surfaces at the top of the next session's recovery data. A lore entry (A) records what happened, not what needs to happen. A TODO comment (C) is invisible to Paradigm. Sentinel (D) is for production incidents. A handoff mention (E) is fragile — tasks are persistent."
-        },
-        {
-          "id": "q2",
-          "question": "A new session starts. The agent calls `paradigm_status`. Among the recovery data, it sees 3 high-priority tasks and 12 medium-priority tasks. How were these surfaced?",
-          "choices": {
-            "A": "The agent must explicitly call `paradigm_task_list` to see tasks — they are not in recovery data",
-            "B": "All 15 tasks appear in the recovery data automatically",
-            "C": "The top 5 open tasks (sorted by priority then date) are automatically included in recovery data on the first Paradigm tool call",
-            "D": "Only high-priority tasks are surfaced during recovery",
-            "E": "Tasks are only surfaced if the previous session created a handoff"
-          },
-          "correct": "C",
-          "explanation": "Session recovery automatically includes the top 5 open tasks, sorted by priority (high first) then by date (newest first). So the agent would see the 3 high-priority tasks plus 2 of the most recent medium-priority tasks. The remaining 10 medium-priority tasks are available via `paradigm_task_list` but are not in the initial recovery data."
-        },
-        {
-          "id": "q3",
-          "question": "Your task list has grown to 35 open items. What should you do?",
-          "choices": {
-            "A": "Delete the oldest tasks to keep the list manageable",
-            "B": "Increase the session recovery limit from 5 to 35 so all tasks are visible",
-            "C": "Triage: shelve low-priority items with `paradigm_task_shelve` and focus on what matters — tasks should not accumulate into a large backlog",
-            "D": "Convert all tasks to lore entries since the list is too long for task management",
-            "E": "Tasks have no practical limit — 35 is fine, just filter by priority when working"
-          },
-          "correct": "C",
-          "explanation": "Tasks are meant to be a lightweight scratch pad, not a project management backlog. When the list grows beyond 20-30 items, it is time to triage. Use `paradigm_task_shelve` to park items that are not immediately relevant. Shelved tasks are not deleted — they remain searchable and can be reopened. This keeps the active list focused and the session recovery data meaningful."
-        }
-      ]
-    },
-    {
-      "id": "assessment-loops",
-      "title": "Lore as Unified Project Memory",
-      "content": "## Lore: The Single Source of Project Memory\n\nParadigm uses lore as its unified project memory system. Every piece of project knowledge — session records, retrospectives, insights, decisions, milestones — lives in lore entries, differentiated by `type` and classified by tags.\n\nThe model is simple: **one system, tags drive classification.**\n\n| Entry Type | When to Use |\n|---|---|\n| `agent-session` | Automated record of an AI-assisted work session |\n| `human-note` | Manual note from a human developer |\n| `decision` | Strategic or architectural decision with rationale |\n| `review` | Quality review of a previous entry |\n| `incident` | Production issue or bug report |\n| `milestone` | Significant project achievement |\n| `retro` | Retrospective — looking back at completed work |\n| `insight` | A realization or pattern discovered across sessions |\n\nLore entries are stored as YAML files in `.paradigm/lore/entries/{date}/` with the `.lore` extension. Each entry has a unique ID: `L-{date}-{author}-{HHMMSS}-{NNN}`.\n\n## Tags Drive Classification\n\nTags are the primary classification mechanism in lore. Any string can be a tag, but certain prefixes carry special meaning:\n\n| Tag Prefix | Meaning | Example |\n|---|---|---|\n| `arc:` | Groups entries into a thematic arc | `arc:auth-hardening`, `arc:v2-migration` |\n| `assessment:` | Marks the reflection type | `assessment:retro`, `assessment:insight` |\n| `arc-closed` | Arc is no longer active | Added when an arc is complete |\n| `arc-status:` | Arc status metadata | `arc-status:complete`, `arc-status:archived` |\n\nArcs are simply tag prefixes — no separate storage or management needed. To create an arc, just start tagging lore entries with `arc:my-arc-name`. To close an arc, add `arc-closed` and `arc-status:complete` tags to its entries.\n\n## The Body Field\n\nFor entries that need more than a 2-3 sentence summary, lore entries support a `body` field for long-form content. This is where retrospective narratives, detailed decision rationale, and multi-paragraph reflections live:\n\n```yaml\nid: L-2026-03-02-ascend-164500-001\ntype: retro\ntitle: \"JWT refresh token rotation — what we learned\"\nsummary: Completed refresh token rotation with httpOnly cookie storage.\nbody: |\n  After three sessions implementing refresh token rotation,\n  the key insight is that storing refresh tokens in httpOnly\n  cookies eliminates an entire class of XSS vulnerabilities.\nsymbols_touched: [\"#refresh-token-handler\", \"^authenticated\"]\nlinked_lore: [L-2026-02-10-003, L-2026-02-12-001]\nlinked_commits: [a1b2c3d, e4f5g6h]\ntags: [arc:auth-hardening, assessment:retro, security, auth, jwt]\n```\n\n## Cross-Referencing\n\nLore entries can link to other project artifacts:\n\n- **`linked_lore`** — References to other lore entry IDs, creating a web of related records\n- **`linked_tasks`** — References to paradigm task IDs\n- **`linked_commits`** — Git commit SHAs related to this entry\n\nThese links create traceability. A retrospective entry can point to the three session records that produced it and the five commits that implemented it.\n\n## Working with Lore\n\n**Recording:** Use `paradigm_lore_record` with `type`, `title`, `summary`, and `symbols_touched`. Add `body` for long-form content, `tags` with `arc:*` prefixes for arc grouping, and `linked_lore`/`linked_commits` for cross-references.\n\n**Searching:** Use `paradigm_lore_search` with filters:\n- `tag: \"arc:auth-hardening\"` — Find all entries in an arc\n- `type: \"retro\"` — Find all retrospectives\n- `hasBody: true` — Find entries with detailed content\n- `symbol: \"#payment-service\"` — Find entries touching a symbol\n\n## The Reflection Loop\n\nLore supports a natural reflection cycle:\n\n1. **Session records** — Automatically captured during work sessions (type: `agent-session`)\n2. **Reflection entries** — Manually recorded at natural pause points (type: `retro`, `insight`, `decision`, `milestone`)\n3. **Arc grouping** — Related reflections tagged with `arc:*` for thematic organization\n4. **Cross-referencing** — Reflection entries link back to the sessions that produced them\n\nWhen a task is marked complete via `paradigm_task_done`, the system suggests recording a lore entry as a natural reflection point.\n\n## When to Record Reflective Entries\n\n- **After completing a multi-session feature** — What did we learn? (`retro` with `arc:feature-name`)\n- **When a pattern emerges** — \"Every time we touch auth, we find token edge cases\" (`insight`)\n- **When making a strategic choice** — \"Switching from REST to GraphQL\" (`decision`)\n- **When reaching a milestone** — \"v2.0 shipped to production\" (`milestone`)\n\nThe general rule: if the knowledge would be valuable in 3 months, record it as a reflective lore entry with appropriate tags.\n\n## Migration from Assessments\n\nProjects that used the older separate assessment system can migrate with `paradigm lore migrate-assessments`. This converts assessment entries to lore entries with `arc:{arc_id}` and `assessment:{type}` tags, preserving all data.",
-      "keyConcepts": [
-        "Lore is the unified project memory — one system, tags drive classification",
-        "Eight entry types: agent-session, human-note, decision, review, incident, milestone, retro, insight",
-        "Arc tags (arc:*) group related entries by theme — no separate arc management needed",
-        "The body field supports long-form content for detailed reflections",
-        "Cross-referencing via linked_lore, linked_tasks, and linked_commits creates traceability",
-        "paradigm_lore_search with tag filter finds entries across arcs",
-        "Task completion nudges lore recording as a natural reflection point"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You have completed a three-session effort to add rate limiting. You want to record a retrospective grouped with other rate-limiting work. What is the correct approach?",
-          "choices": {
-            "A": "Call `paradigm_lore_record` with `type: \"retro\"`, a body with your reflection, and `tags: [\"arc:rate-limiting\"]`",
-            "B": "Call `paradigm_assessment_record` with `arc_id: \"arc-rate-limiting\"` and `type: \"retro\"`",
-            "C": "Call `paradigm_lore_record` with `type: \"milestone\"` — completing features is always a milestone",
-            "D": "Create a separate `.paradigm/assessments/` directory and write the entry manually",
-            "E": "Call `paradigm_lore_record` with `type: \"agent-session\"` — all lore is session-level"
-          },
-          "correct": "A",
-          "explanation": "Reflective entries are recorded via `paradigm_lore_record` with the appropriate type and arc tag. A retro with `tags: [\"arc:rate-limiting\"]` groups it with other entries in that arc. The body field holds the detailed reflection. The assessment tools (B) are deprecated wrappers. Milestones (C) mark significant project events, not feature completions. Agent-session (E) is for automated session records, not deliberate reflections."
-        },
-        {
-          "id": "q2",
-          "question": "A lore entry has `linked_lore: [L-2026-02-10-003, L-2026-02-12-001]` and `linked_commits: [a1b2c3d]`. What does this cross-referencing enable?",
-          "choices": {
-            "A": "It automatically updates the linked entries with backlinks",
-            "B": "It creates traceability — readers can drill from the synthesized insight down to the specific sessions and code changes",
-            "C": "It prevents the referenced lore entries from being deleted",
-            "D": "It triggers Sentinel to check those commits for incidents",
-            "E": "It merges the linked entries into a single combined entry"
-          },
-          "correct": "B",
-          "explanation": "Cross-references create a traceability chain. A reader encountering an insight entry can follow `linked_lore` to see the full session context, and `linked_commits` to see the exact code changes. This is the core value of linking — each entry adds interpretation to what it references, with links to drill down for evidence."
-        },
-        {
-          "id": "q3",
-          "question": "You want to find every retrospective in the `arc:auth-hardening` arc that mentions `#payment-service`. Which approach is correct?",
-          "choices": {
-            "A": "Call `paradigm_lore_search` with `tag: \"arc:auth-hardening\"`, `type: \"retro\"`, and `symbol: \"#payment-service\"`",
-            "B": "Call `paradigm_assessment_search` with `symbol: \"#payment-service\"` — it searches the old assessment system",
-            "C": "Call `paradigm_lore_search` with `tags: [\"arc:auth-hardening\", \"retro\"]`",
-            "D": "Call `paradigm_search` with `query: \"payment retro auth\"` — general search covers lore",
-            "E": "Read every file in `.paradigm/lore/entries/` and filter manually"
-          },
-          "correct": "A",
-          "explanation": "`paradigm_lore_search` supports combining filters: `tag` for arc prefix matching, `type` for entry type, and `symbol` for symbol references. These filters combine (AND logic), so you get only retro entries in the auth-hardening arc that touch the payment service. The assessment tools (B) are deprecated. Using `tags` array (C) uses OR logic, not AND. General search (D) searches the symbol index, not lore content."
-        }
-      ]
-    },
-    {
-      "id": "symphony-a-mail",
-      "title": "Symphony: Multi-Agent Messaging with The Score",
-      "content": "## Agents Need to Talk\n\nUntil now, every Paradigm agent has worked in isolation. A Claude Code session modifying the backend has no awareness of what the session working on the frontend is doing. Two developers on the same team, each with their own AI assistant, have no way for those assistants to coordinate — even when they are working on the same project at the same time.\n\nSymphony changes this. It is Paradigm's multi-agent, multi-human collaborative intelligence layer. And its foundation is The Score: a lightweight, file-based messaging protocol that gives every Claude Code session its own mailbox.\n\n## The Metaphor: Email for AI Agents\n\nThe Score works exactly like email. Each agent has an identity, an inbox, and an outbox. Messages are delivered as JSONL files on the filesystem. Agents poll for new messages on a timer. There is no persistent server, no WebSocket connection, and no cloud dependency. If two agents are running on the same machine, they can message each other through nothing more than file reads and writes.\n\nThis simplicity is deliberate. The Score is the CLI-only foundation of Symphony — it works with zero dependencies beyond the Paradigm CLI. No Conductor, no Sentinel, no network configuration. The only requirement is that agents are running on the same machine (or connected via a lightweight TCP relay for cross-machine scenarios).\n\n## Agent Identity and Discovery\n\nEvery Claude Code session that participates in The Score has a stable identity. The identity is derived from the project directory and the agent's role — for example, `a-paradigm/backend` or `a-kamiki/frontend`. This deterministic naming means the same project opened in the same context always gets the same identity, even across session restarts.\n\nWhen you run `paradigm symphony join`, the CLI discovers all Claude Code sessions on the current machine and connects them into a mail network. Each session gets a mailbox directory at `~/.paradigm/score/agents/{agent-id}/` containing four files:\n\n- **`inbox.jsonl`** — Messages waiting for this agent, one per line, append-only\n- **`outbox.jsonl`** — Replies from this agent, append-only\n- **`ack.json`** — The ID of the last acknowledged message (for garbage collection)\n- **`identity.json`** — Agent ID, project, role, PID, and session start time\n\nThe JSONL format — one JSON object per line — makes appending atomic and parsing trivial. No file locking, no corruption risk from concurrent writes, no binary format to decode.\n\n## Messaging and Threading\n\nMessages in The Score carry structured metadata beyond plain text. Every message has an **intent** that classifies its purpose:\n\n| Intent | Meaning |\n|---|---|\n| `question` | Asking for information from other agents |\n| `context` | Providing background or context |\n| `proposal` | Proposing an action or fix |\n| `action` | Announcing an action the agent took |\n| `decision` | Recording a decision |\n| `alert` | Forwarding a Sentinel alert |\n| `approval` / `rejection` | Responding to a proposal |\n| `handoff` | Transferring responsibility to another agent |\n| `fileRequest` | Requesting a file from another agent |\n| `fileDelivery` | Delivering a requested file |\n\nIntents serve two purposes. First, they give the receiving agent structured context about what kind of response is expected — a question needs an answer, a proposal needs approval or rejection, a decision needs acknowledgment. Second, they feed into Lore: when a message has `intent: decision`, Symphony can automatically record it as a lore entry.\n\nMessages belong to **threads**. A thread starts when the first message on a topic is sent (with no `parentId`). Subsequent replies reference the thread root, building a conversation tree. Thread state is tracked in `~/.paradigm/score/threads/{thread-id}.json`, which records the topic, participants, message count, and last activity timestamp.\n\n## The File Pipeline\n\nAgents often need to share files — a type definition, an API contract, a configuration file. The Score's file pipeline enables this with a critical security constraint: **every file transfer requires explicit human approval**.\n\nThe flow works like this: Agent A sends a `fileRequest` message specifying the file path, a reason, and the target agent. The request appears in the owning human's terminal (via `paradigm symphony requests`). The human reviews and either approves, denies, or approves with redaction (stripping sensitive lines). Only after human approval does the file content get written to the requester's inbox.\n\nTrust configuration lives in `~/.paradigm/score/trust.yaml`. You can define auto-approve patterns for trusted users (`docs/**`, `*.md`) and never-approve patterns for sensitive files (`.env*`, `*.key`, `*.pem`, `**/secrets/**`). The never-approve list is enforced absolutely — even clicking approve on a `.env` file will be denied by the system. File requests expire after one hour without action, and all transfers are logged.\n\n## /loop: The Agent Heartbeat\n\nThe glue that makes The Score work is `/loop`. Each Claude Code session runs `/loop 10s paradigm_symphony_poll`, which polls the inbox every 10 seconds for new messages. The `paradigm_symphony_poll` MCP tool reads `inbox.jsonl`, formats messages as structured prompts the agent can reason about, and suggests actions.\n\nWithout `/loop`, messages would accumulate in the inbox with nobody reading them. The loop is the heartbeat — it keeps agents responsive. When an agent processes a message and replies via `paradigm_symphony_send`, the reply goes to `outbox.jsonl`. A mail router (or Conductor, in later phases) picks up outbox messages and delivers them to the appropriate inbox files.\n\nThe convenience command `paradigm symphony join` combines registration and loop setup in one step — it registers the session's identity and starts the polling loop automatically.\n\n## Thread Resolution and Lore Integration\n\nConversation threads are not meant to live forever. When a thread reaches a conclusion, any participant (human or agent) can resolve it with `paradigm symphony resolve <thread-id>`. Resolution triggers an automatic lore entry that captures the full conversation: topic, participants, decisions made, actions taken, and symbols discussed.\n\nThis is the bridge between ephemeral conversation and permanent project memory. A 15-minute exchange between three agents about a serialization bug becomes a searchable lore entry tagged with the relevant symbols and arc. The next developer encountering a similar issue can find the conversation, the decision, and the fix — all linked together.\n\n## CLI Commands\n\nThe `paradigm symphony` command group provides the complete human interface:\n\n- `paradigm symphony whoami` — Show this agent's identity and linked peers\n- `paradigm symphony list` — List all known agents with status (awake/asleep) and location\n- `paradigm symphony join` — Discover and connect Claude Code sessions on this machine\n- `paradigm symphony join --remote <ip>` — Connect to a remote machine's mail server\n- `paradigm symphony send \"message\"` — Broadcast to all linked agents\n- `paradigm symphony send --to <agent> \"message\"` — Direct message to a specific agent\n- `paradigm symphony send --thread <id> \"message\"` — Reply to an existing thread\n- `paradigm symphony read` — Show unread messages\n- `paradigm symphony threads` — List active threads\n- `paradigm symphony resolve <id>` — Resolve a thread, creating a lore entry\n- `paradigm symphony status` — Network overview (agents, threads, unread count)\n\nFor the file pipeline: `paradigm symphony request`, `paradigm symphony requests`, `paradigm symphony approve`, and `paradigm symphony deny`.\n\n## MCP Tools for Agent Participation\n\nSix MCP tools power agent-side Symphony participation:\n\n- **`paradigm_symphony_poll`** — The heartbeat. Reads inbox, returns formatted messages and thread summaries. Called by `/loop`.\n- **`paradigm_symphony_send`** — Send a message with intent, text, optional symbols, diff, or decision. Writes to outbox.\n- **`paradigm_symphony_status`** — Overview of the local network: agents, threads, Sentinel endpoint.\n- **`paradigm_symphony_thread`** — Get full context of a conversation thread with messages, participants, and extracted decisions.\n- **`paradigm_symphony_request_file`** — Request a file from another agent. Returns immediately with `pending` status; delivery arrives via future poll.\n- **`paradigm_symphony_approve_file`** — Approve or deny a pending file request after human confirmation.\n\nThese tools compose naturally with existing Paradigm workflows. An agent can poll for messages, discover a question about `#payment-serializer`, call `paradigm_ripple` to check impact, and respond with full context — all within a single `/loop` cycle.",
-      "keyConcepts": [
-        "The Score is Symphony's CLI-only foundation — file-based messaging between agents with zero dependencies beyond the Paradigm CLI",
-        "Agent identity is derived from project directory + role (e.g., a-paradigm/backend), stable across session restarts",
-        "Mailbox protocol uses JSONL files: inbox.jsonl (incoming), outbox.jsonl (replies), ack.json (last acknowledged), identity.json (agent metadata)",
-        "Messages carry structured intents (question, proposal, decision, action, alert, etc.) that classify purpose and drive Lore integration",
-        "Threads group related messages into conversations, tracked in ~/.paradigm/score/threads/{thread-id}.json",
-        "The file pipeline requires explicit human approval for every file transfer, with configurable trust levels and a hard deny list for sensitive files",
-        "/loop is the agent heartbeat — each session runs /loop 10s paradigm_symphony_poll to stay responsive to incoming messages",
-        "Thread resolution via paradigm symphony resolve triggers automatic lore entry creation, bridging ephemeral conversation to permanent project memory",
-        "Six MCP tools: paradigm_symphony_poll, paradigm_symphony_send, paradigm_symphony_status, paradigm_symphony_thread, paradigm_symphony_request_file, paradigm_symphony_approve_file",
-        "paradigm symphony join discovers Claude Code sessions on the local machine; paradigm symphony join --remote <ip> extends to remote machines via TCP"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "You have three Claude Code sessions open on your machine: one working on the core library, one on the backend API, and one on the frontend. You want them to communicate. What is the correct setup sequence?",
-          "choices": {
-            "A": "Start a Sentinel hub, then connect each session to the WebSocket endpoint",
-            "B": "Install Conductor, which automatically links all sessions on the machine",
-            "C": "Run `paradigm symphony join` to discover and connect the sessions, then run `/loop 10s paradigm_symphony_poll` in each session",
-            "D": "Create a `.paradigm-workspace` file listing all three projects — workspace linking enables messaging",
-            "E": "Run `paradigm team orchestrate` which automatically sets up inter-agent communication"
-          },
-          "correct": "C",
-          "explanation": "The Score is the CLI-only foundation that requires no Conductor, no Sentinel, and no workspace setup. `paradigm symphony join` discovers Claude Code sessions on the machine and creates mailboxes. Then each session needs `/loop 10s paradigm_symphony_poll` to poll for incoming messages. Conductor (B) auto-links sessions but is not required — The Score works standalone."
-        },
-        {
-          "id": "q2",
-          "question": "An agent sends a message with `intent: 'decision'` and the text 'Use Redis for session storage instead of in-memory.' What happens beyond normal message delivery?",
-          "choices": {
-            "A": "The message is blocked — only humans can make decisions",
-            "B": "Symphony automatically records a lore entry of type `decision` with the message text, linking it to the conversation thread and referenced symbols",
-            "C": "The message is flagged for human review before delivery",
-            "D": "Nothing special — intent is informational only and has no side effects",
-            "E": "The decision is written to `.paradigm/config.yaml` as a project setting"
-          },
-          "correct": "B",
-          "explanation": "Messages with `intent: decision` trigger automatic Lore integration. Symphony records a lore entry with the decision text, links it to the conversation thread, and tags it with referenced symbols. This bridges ephemeral conversation to permanent project memory without manual recording."
-        },
-        {
-          "id": "q3",
-          "question": "Agent A (on your machine) requests `src/types.ts` from Agent B (on a teammate's machine). What must happen before Agent A receives the file?",
-          "choices": {
-            "A": "Agent B must call `paradigm_symphony_approve_file` — agents can approve their own file requests",
-            "B": "The file is sent automatically since both agents are linked in the same Symphony network",
-            "C": "The teammate (human) must explicitly approve the file transfer — every cross-agent file transfer requires human approval from the file owner's side",
-            "D": "Agent A must have the `^file-access` gate declared in portal.yaml",
-            "E": "The file is sent if it matches the auto-approve glob patterns, but there is no human gate"
-          },
-          "correct": "C",
-          "explanation": "The file pipeline's core security constraint is that every file transfer requires explicit human approval from the owner's side. When Agent A requests a file, the teammate sees a prompt (via Conductor or `paradigm symphony requests`) and must approve, deny, or approve with redaction. Even if auto-approve patterns exist in trust.yaml, the initial setup still requires human-configured trust levels."
-        },
-        {
-          "id": "q4",
-          "question": "An agent's `paradigm_symphony_poll` returns 3 new messages in a thread about a failing test. The agent reads them, investigates the code, and finds the bug. How should the agent communicate its findings?",
-          "choices": {
-            "A": "Call `paradigm_lore_record` with the findings — lore is the communication channel",
-            "B": "Call `paradigm_symphony_send` with `intent: 'context'` providing the investigation results, then `intent: 'proposal'` with the fix, writing to `outbox.jsonl` for delivery to the thread",
-            "C": "Write directly to the other agents' `inbox.jsonl` files for immediate delivery",
-            "D": "Call `paradigm_sentinel_record` to log the bug as an incident",
-            "E": "Call `paradigm symphony send` from the CLI — agents cannot use MCP tools to reply"
-          },
-          "correct": "B",
-          "explanation": "Agents communicate via `paradigm_symphony_send`, which writes structured messages to `outbox.jsonl`. Using multiple messages with appropriate intents (context for the investigation, proposal for the fix) gives other agents structured context. Writing directly to inbox files (C) bypasses the routing protocol. Lore (A) and Sentinel (D) are recording systems, not communication channels."
-        },
-        {
-          "id": "q5",
-          "question": "A thread about a serialization bug has been active for 20 minutes across 4 agents. The team agrees on a fix. What should happen next?",
-          "choices": {
-            "A": "Delete the thread files from `~/.paradigm/score/threads/` to clean up",
-            "B": "Let the thread expire naturally — threads auto-resolve after 1 hour of inactivity",
-            "C": "Run `paradigm symphony resolve <thread-id>` which marks the thread as resolved and automatically creates a lore entry capturing the full conversation, decisions, and actions",
-            "D": "Each agent independently records a lore entry about their contribution",
-            "E": "Run `paradigm_reindex` to incorporate the thread into the project index"
-          },
-          "correct": "C",
-          "explanation": "Thread resolution via `paradigm symphony resolve` is the bridge between ephemeral conversation and permanent project memory. It marks the thread as resolved and automatically creates a comprehensive lore entry with the topic, participants, decisions, actions, and referenced symbols. This single action preserves the entire collaborative context for future reference."
-        }
-      ]
-    },
-    {
-      "id": "platform-agent-ui",
-      "title": "Platform & Agent-Driven UI",
-      "content": "## The Unified Platform\n\n`paradigm serve` launches the Paradigm Platform — a unified development management interface on port 3850 that absorbs every Paradigm tool (Lore, Graph, Sentinel, University, Symphony) into one browser tab.\n\nThe Platform is built on Express + WebSocket on the server, React 18 + Zustand on the client. Sections are lazy-loaded. A shared design system provides consistent theming and symbol colors.\n\n### Architecture\n\n```\nlocalhost:3850 (Express + WebSocket)\n├── /api/lore/*        ← LoreRouter\n├── /api/symbols/*     ← SymbolsRouter\n├── /api/graphs/*      ← GraphsRouter\n├── /api/platform/*    ← PlatformRouter (health, sections, agent-command)\n├── /ws                ← WebSocket (agent commands + user activity)\n└── /                  ← Platform UI SPA\n```\n\n## Agent-Driven UI\n\nThe breakthrough: **the AI agent can drive the browser in real-time.** Five MCP tools let the agent navigate, highlight, annotate, observe, and clear — turning the Platform from a passive viewer into a shared workspace.\n\n### The Pipeline: MCP → HTTP → WebSocket → Browser\n\n```\nAgent (Claude Code)       Platform Server          Browser\n      │                          │                    │\n      │ paradigm_platform_*      │                    │\n      │ POST /api/platform/cmd   │                    │\n      │ ─────────────────────────►│                    │\n      │   ◄── { ok: true } ──────│                    │\n      │                          │  ws: agent:*       │\n      │                          │──────────────────►│\n      │                          │                    │ UI updates\n```\n\nWhy HTTP not file-based: the <500ms latency requirement rules out file-watching. Why not direct WebSocket from MCP: MCP tools are stdio-based with no event loop for persistent WS connections.\n\n### The Five Tools\n\n| Tool | Purpose |\n|------|---------|\n| `paradigm_platform_navigate` | Switch sections, select symbols, open lore entries |\n| `paradigm_platform_highlight` | Pulsing glow on symbols with color + label, auto-expires |\n| `paradigm_platform_annotate` | Toasts (notifications), callouts (on graph nodes), badges |\n| `paradigm_platform_observe` | Read user's current section, selected symbol, theme, mute state |\n| `paradigm_platform_clear` | Remove all agent highlights and annotations |\n\n### Conflict Resolution: User Always Wins\n\nThe agent must never hijack the user's attention:\n\n- **User idle (>5s):** Agent navigation executes immediately\n- **User active (<5s):** A prompt appears: \"Agent wants to show you #X — [Go there] [Dismiss]\"\n- **User muted:** All agent effects are silently discarded; `observe` returns `{ muted: true }`\n\n### Agent Presence\n\nThe `#AgentPresenceManager` tracks connected agents by their Symphony identity (`{project}/{role}`). Each agent gets a deterministic color from its ID hash. Presence dots appear in the Platform header with a mute toggle.\n\nStale agents are auto-pruned after 2 minutes of inactivity.\n\n### User State Tracking\n\nThe `#UserStateTracker` accumulates user activity — what section they're viewing, what symbol is selected, theme preference. This state is served to `paradigm_platform_observe` so the agent can reason about what the user is looking at.\n\nBrowser clients report activity via WebSocket messages: `user:navigate`, `user:select`, `user:theme`, `user:mute`.\n\n### Visual Treatment\n\n| Element | Human | Agent |\n|---------|-------|-------|\n| Selection ring | Solid 2px blue | Dashed 2px agent-color |\n| Highlight | N/A | Pulsing glow animation |\n| Toast | N/A | Left border + robot icon |\n| Navigation | Instant | 300ms ease + toast notification |\n\n### Browser Architecture\n\nThe agent UI layer sits alongside existing stores:\n\n- `agentStore.ts` — Zustand store managing presence, highlights, annotations, toasts, mute, pending navigation\n- `useAgentEffects` — Hook connecting WebSocket `agent:*` messages to store actions, with auto-reconnect\n- `useActivityReporter` — Hook reporting section/theme changes back to server\n- `AgentToast` — Severity-colored toast component\n- `AgentCallout` — Floating callout overlay + navigation conflict prompt",
-      "keyConcepts": [
-        "paradigm serve unifies all tools on port 3850 in one browser tab",
-        "Agent-Driven UI: 5 MCP tools (navigate, highlight, annotate, observe, clear) control the browser in real-time",
-        "Pipeline: MCP → HTTP POST → Platform server → WebSocket broadcast → browser Zustand store → visual effect",
-        "Conflict resolution: user idle → auto-navigate, user active → prompt, user muted → silently discard",
-        "Agent identity reuses Symphony pattern: {project}/{role} with deterministic color from hash",
-        "AgentPresenceManager tracks agents, auto-prunes after 2min idle",
-        "UserStateTracker accumulates section/symbol/theme for observe tool",
-        "Visual distinction: agent effects use dashed rings, pulsing glow, robot-icon toasts vs. human solid styles"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "An AI agent calls `paradigm_platform_navigate({ section: 'graph', symbol: '#payment-service' })` while the user is actively typing in the lore section. What happens in the browser?",
-          "choices": {
-            "A": "The browser immediately switches to the graph section and selects the node",
-            "B": "The command fails with an error because the user is in a different section",
-            "C": "A prompt appears: 'Agent wants to show you #payment-service — [Go there] [Dismiss]' — the user decides",
-            "D": "The agent's command is queued and executes when the user next switches sections",
-            "E": "The browser switches to graph but keeps the lore section visible in a split view"
-          },
-          "correct": "C",
-          "explanation": "When the user is active (last interaction <5s ago), the agent's navigation creates a pending navigation prompt instead of auto-navigating. The user sees 'Agent wants to show you #payment-service — [Go there] [Dismiss]' and chooses whether to follow. This is the conflict resolution model: user always wins."
-        },
-        {
-          "id": "q2",
-          "question": "What is the communication pipeline when an MCP tool like `paradigm_platform_highlight` sends a command to the browser?",
-          "choices": {
-            "A": "MCP tool → direct WebSocket connection to browser → UI update",
-            "B": "MCP tool → writes to file → browser polls file every 500ms → UI update",
-            "C": "MCP tool → HTTP POST to Platform server → server broadcasts via WebSocket → browser Zustand store → UI update",
-            "D": "MCP tool → writes to scan-index.json → browser watches index file → UI update",
-            "E": "MCP tool → sends message via Symphony mailbox → browser reads mailbox → UI update"
-          },
-          "correct": "C",
-          "explanation": "The pipeline is MCP → HTTP POST → WebSocket broadcast → browser. The MCP tool calls the platform-bridge helper which POSTs to /api/platform/agent-command. The server validates the command, updates server-side state (presence, highlights), and broadcasts a typed WebSocket message (e.g., agent:highlight) to all connected browsers. The browser's useAgentEffects hook receives the message and dispatches to the Zustand agentStore."
-        },
-        {
-          "id": "q3",
-          "question": "The user clicks the 'Mute' button in the Platform header. An agent then calls `paradigm_platform_annotate({ type: 'toast', message: 'Found a bug in #auth' })`. What happens?",
-          "choices": {
-            "A": "The toast appears but with reduced opacity",
-            "B": "The command returns `{ annotated: false, reason: 'Agent actions are muted by user' }` and no toast appears",
-            "C": "The toast is queued and shown when the user unmutes",
-            "D": "The command throws an error that the agent must handle",
-            "E": "The toast appears regardless — mute only affects navigation, not annotations"
-          },
-          "correct": "B",
-          "explanation": "When the user mutes agent actions, ALL agent effects are silently discarded — navigate, highlight, annotate, and clear commands all return a response with `reason: 'Agent actions are muted by user'`. The server checks UserStateTracker.isMuted() before broadcasting. The agent can detect this via `paradigm_platform_observe` which returns `{ muted: true }`."
-        },
-        {
-          "id": "q4",
-          "question": "How does the Platform determine an agent's display color in the header presence indicator?",
-          "choices": {
-            "A": "Each agent chooses its color when connecting via WebSocket",
-            "B": "Colors are assigned sequentially from a fixed palette (first agent = blue, second = green, etc.)",
-            "C": "The color is deterministically computed from a hash of the agent's Symphony identity string ({project}/{role})",
-            "D": "Colors are stored in .paradigm/config.yaml under platform.agentColors",
-            "E": "All agents share the same color — they're distinguished by name only"
-          },
-          "correct": "C",
-          "explanation": "Agent colors are deterministic: the AgentPresenceManager computes a hash of the agentId string (e.g., 'a-paradigm/core') and maps it to one of 8 predefined colors. This means the same agent always gets the same color across sessions, making it recognizable. The identity reuses Symphony's {project}/{role} pattern."
-        },
-        {
-          "id": "q5",
-          "question": "An agent wants to understand what the user is currently looking at before deciding what to highlight. Which approach is correct?",
-          "choices": {
-            "A": "Read the platformStore.ts file to check the activeSection variable",
-            "B": "Call `paradigm_platform_observe()` which returns the current section, selected symbol, theme, mute state, and connected agents",
-            "C": "Call `paradigm_status` which includes the Platform UI state in its output",
-            "D": "Check the browser's localStorage via a Bash command",
-            "E": "Call `paradigm_navigate({ intent: 'context' })` which includes Platform UI state"
-          },
-          "correct": "B",
-          "explanation": "paradigm_platform_observe is the dedicated tool for reading UI state. It sends an 'observe' command to the Platform server, which returns the UserStateTracker's accumulated state: current section, selected symbol, theme, mute status, connected agents, and optionally active highlights/annotations. This is real-time data from the server, not a file read."
-        }
-      ]
-    },
-    {
-      "id": "conductor-workspace",
-      "title": "Conductor: Visual Mission Control",
-      "content": "## What Is Conductor?\n\nConductor is a native macOS application that serves as the visual mission control for Paradigm. While the CLI and MCP tools handle the automation, Conductor gives you a real-time view of what your agent team is doing — and lets you interact with them visually.\n\nThink of it as the difference between managing a team over email versus walking into a mission control room. Both work, but the room gives you instant awareness.\n\n### Core Capabilities\n\n**Workspace Mode** — A full-screen tiling window manager for Claude Code sessions. Launch multiple terminals side by side, split horizontally or vertically, drag dividers to resize. Six layout presets (single, split-h, split-v, quad, triple, grid) let you quickly arrange your workspace.\n\n**Symphony Integration** — Conductor connects to Symphony, the inter-agent messaging system. When agents communicate during orchestration (handing off context, requesting approval, debating approaches), those messages appear in Conductor's thread view in real time. You can read the full conversation without switching to the CLI.\n\n**Task Protocol** — A structured protocol for human-agent coordination with 7 intents:\n- `task` — assign work to an agent\n- `task-ack` — agent acknowledges receipt\n- `progress` — agent reports progress\n- `approval-request` — agent asks for human approval\n- `approval-response` — human approves or rejects\n- `task-complete` — agent reports success\n- `task-failed` — agent reports failure\n\nThis protocol makes agent work visible and controllable. You see when agents are working, what they are asking, and whether they succeeded.\n\n**Agent Health Dashboard** — Per-agent metrics: success rates, average time-per-task, acceptance rates for contributions. Sparklines show trends over time. When an agent's performance drops, you see it immediately.\n\n**Live Sentinel** — Real-time event viewer with symbol filtering. When Sentinel detects an incident or pattern, it appears in Conductor's event feed with full detail and suggested resolution.\n\n### Architecture\n\nConductor is built with Swift and SwiftUI — a native macOS application, not an Electron wrapper. Key design decisions:\n\n- **Single-owner pattern** — AppDelegate owns the orchestrator, workspace, project store, and agent process manager. No shared mutable state.\n- **Local-only ML** — Gaze tracking, gesture recognition, and voice commands all run locally via CoreML. Zero cloud, zero cost, zero latency.\n- **SwiftTerm embedding** — Terminal sessions use SwiftTerm, a native Swift terminal emulator. Each session is a real PTY with full ANSI support.\n- **7 platform protocols** — Abstraction layer for future portability (the same protocol set would power a Windows or Linux version).\n\n### Getting Started\n\nBuild and install Conductor:\n\n```bash\ncd packages/conductor\n./build-conductor.sh --install\n```\n\nThis produces `Conductor.app` in `/Applications`. Launch it, and it connects to your Paradigm project automatically.\n\n### When to Use Conductor\n\n- **During orchestration** — watch agents work in real time, approve contributions, read debates\n- **Multi-session development** — tile 2-4 Claude Code sessions side by side, each working on different parts of the codebase\n- **Monitoring** — keep Conductor visible on a secondary display to catch Sentinel events and agent health changes\n- **Team collaboration** — when multiple developers use Symphony, Conductor shows cross-session threads and file approval requests\n\nConductor is optional — everything it shows is also available via CLI and MCP tools. But for teams that want visual awareness of their agent team, it is the command center.",
-      "keyConcepts": [
-        "Conductor is a native macOS SwiftUI application — not Electron",
-        "Workspace mode provides tiling terminal management with 6 layout presets",
-        "Symphony integration shows inter-agent messages in real time",
-        "Task protocol has 7 intents for structured human-agent coordination",
-        "Agent health dashboard tracks per-agent success rates and trends",
-        "All ML inference (gaze, gesture, voice) runs locally via CoreML",
-        "Optional but powerful — everything is also available via CLI"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "During orchestration, the security agent sends an approval-request via Symphony asking to modify portal.yaml. Where would you see and respond to this in Conductor?",
-          "choices": {
-            "A": "In the terminal session where the agent is running",
-            "B": "In the Symphony thread view — approval-request is a task protocol intent that appears as a message you can approve or reject",
-            "C": "In the agent health dashboard under the security agent's metrics",
-            "D": "In the Sentinel event feed as a security incident",
-            "E": "You cannot — approval requests only work via CLI"
-          },
-          "correct": "B",
-          "explanation": "Symphony messages, including task protocol intents like approval-request, appear in Conductor's thread view in real time. The task protocol is designed for human-agent coordination — you see the request, read the context, and respond with approval-response directly in the thread view. This is one of Conductor's key advantages over CLI-only workflows."
-        },
-        {
-          "id": "q2",
-          "question": "You want to work on the frontend and backend of a feature simultaneously with two Claude Code sessions. How would you set this up in Conductor?",
-          "choices": {
-            "A": "Launch two separate Conductor apps",
-            "B": "Use workspace mode with a split-h or split-v layout preset, launching one terminal session per pane",
-            "C": "Conductor only supports one session at a time",
-            "D": "Use the agent health dashboard to assign work to two agents",
-            "E": "Use Symphony to relay messages between two CLI sessions instead"
-          },
-          "correct": "B",
-          "explanation": "Conductor's workspace mode is a tiling window manager for Claude Code sessions. Choose a split layout preset (horizontal or vertical), and each pane gets its own terminal session. Both sessions connect to Symphony, so they can coordinate via inter-agent messaging while you watch both in a single window."
-        },
-        {
-          "id": "q3",
-          "question": "Conductor's ML features (gaze tracking, gesture recognition, voice commands) all run locally via CoreML. Why is this significant?",
-          "choices": {
-            "A": "CoreML is faster than cloud APIs for all tasks",
-            "B": "It means zero cloud cost, zero data leaving your machine, and zero network latency — critical for a developer tool that sees your code and screen",
-            "C": "Apple requires all macOS apps to use CoreML",
-            "D": "Cloud ML services do not support gaze tracking",
-            "E": "It is not significant — it is just an implementation detail"
-          },
-          "correct": "B",
-          "explanation": "For a developer tool that has access to your codebase, screen content, and camera feed, privacy is paramount. Local-only ML means your data never leaves your machine — no cloud processing, no storage, no costs. The zero-latency benefit is a bonus, but the privacy guarantee is the real reason this design choice matters."
-        }
-      ]
-    },
-    {
-      "id": "symphony-networking",
-      "title": "Symphony Networking: Cross-Machine Relay",
-      "content": "## Beyond Single-Machine Messaging\n\nSymphony Phase 0 (A-Mail) established file-based agent-to-agent messaging on a single machine — JSONL mailboxes at `~/.paradigm/score/`, polled via `/loop`. But what happens when two developers on the same WiFi, or at different locations, want their Claude instances to collaborate?\n\nSymphony Phase 1 adds cross-machine networking via a WebSocket relay. The key design principle: **the local mailbox model is unchanged**. Networking is a transparent sync layer that watches local outboxes and delivers remote messages to local inboxes.\n\n## Hub-and-Spoke Topology\n\nOne machine runs `paradigm symphony serve` (the **hub**), and others connect with `paradigm symphony join --remote` (the **spokes**). The hub relays messages between all connected machines.\n\n```\nMachine A (Hub)                     Machine B (Spoke)\n┌─────────────────────┐           ┌─────────────────────┐\n│ ~/.paradigm/score/  │           │ ~/.paradigm/score/  │\n│   agents/projA/core │           │   agents/projB/core │\n│     inbox.jsonl     │◄────ws───►│     inbox.jsonl     │\n│     outbox.jsonl    │  :3939    │     outbox.jsonl    │\n└─────────────────────┘           └─────────────────────┘\n```\n\nThe relay watches each local agent's outbox file (polling every 2 seconds via `fs.stat`). When new messages appear, they're pushed to all connected peers as WebSocket frames. Incoming messages from peers are written to the appropriate local inbox via `appendToInbox()`.\n\n## Pairing & Authentication\n\nSecurity is critical when connecting machines over a network. Symphony uses a pairing code + HMAC challenge-response protocol:\n\n1. The hub generates a 32-byte random secret and derives a **6-digit pairing code**\n2. The code is displayed on the hub's terminal\n3. The spoke connects and receives a `hello` frame with a random challenge nonce\n4. The user enters the code on the spoke terminal (or embeds it in the connection string)\n5. The spoke computes `HMAC-SHA256(challenge, SHA256(code))` and sends an `auth` frame\n6. The hub verifies the code and HMAC proof, then sends `auth_ok` with its agent list\n\nPairing codes rotate every 5 minutes. After 3 failed attempts from the same IP, a 60-second cooldown is enforced. Peer records are saved to `~/.paradigm/score/peers.json` (file mode 0600) for auto-reconnect.\n\n## Two Connection Modes\n\n### LAN Pairing (same WiFi)\n\n```sh\n# Machine A (hub)\nparadigm symphony serve\n# Shows: Pairing Code: 847 291\n\n# Machine B (spoke)\nparadigm symphony join --remote 192.168.1.42:3939\n# Prompted for code\n```\n\n### Internet Direct Connect\n\n```sh\n# Machine A\nparadigm symphony serve --public\n# Shows connection string\n\n# Machine B\nparadigm symphony join --remote 73.162.44.103:3939#847291\n# Code embedded — no prompt\n```\n\nInternet mode requires port 3939 to be reachable (port forward, VPN, or SSH tunnel).\n\n## Trust Management\n\nPeers are managed via CLI commands:\n\n- `paradigm symphony peers` — List trusted peers with agent counts and last-seen times\n- `paradigm symphony peers revoke <id>` — Immediately disconnect and block reconnection\n- `paradigm symphony peers forget --force` — Clear all peer trust records\n\nExisting `trust.yaml` hard-deny patterns (`.env*`, `*.key`, `*.pem`) apply to remote file requests — the trust boundary extends across the network.\n\n## Relay Internals\n\nThe `SymphonyRelay` class handles both server and client modes:\n\n- **Outbox watcher**: Polls every 2s, compares outbox line counts against stored positions, forwards new messages\n- **Deduplication**: Bounded `Set<string>` of message IDs (max 10,000) prevents duplicate delivery\n- **Keepalive**: Ping/pong every 30s with 10s pong timeout. Dead connections are auto-terminated\n- **Auto-reconnect**: Client mode uses exponential backoff (1s → 2s → 4s → ... → 30s max)\n- **Rate limiting**: 3 failed auth attempts from the same IP triggers a 60s cooldown\n\n## Remote Agent Visibility\n\nRemote agents appear throughout the Symphony CLI and MCP tools:\n\n- `paradigm symphony list` shows remote agents with a `(remote: peer-name)` tag\n- `paradigm symphony status` includes peer count and remote agent totals\n- `paradigm_symphony_status` MCP tool returns a `peers` array in its response\n- Platform UI `GET /api/symphony/peers` endpoint returns connected peer data\n\nLocal MCP tools (`peek`, `poll`, `send`) work unchanged — they just read/write local files. The relay handles the network transport transparently.\n\n## Backward Compatibility\n\nIf `paradigm symphony serve` is never run, Symphony operates exactly as Phase 0: local-only file-based messaging. Networking is purely additive — no existing workflows change.",
-      "keyConcepts": [
-        "Hub-and-spoke topology: one serve (hub), multiple join --remote (spokes)",
-        "WebSocket relay watches local outboxes and delivers remote messages to local inboxes",
-        "Pairing: 6-digit code + HMAC-SHA256 challenge-response authentication",
-        "Codes rotate every 5 minutes; 3 failed auth attempts trigger 60s cooldown",
-        "Two modes: LAN pairing (interactive code) and internet direct connect (embedded code in connection string)",
-        "Peer trust stored in ~/.paradigm/score/peers.json (mode 0600)",
-        "Trust management: peers list/revoke/forget commands",
-        "Outbox watcher polls every 2s; dedup via bounded Set<string> (max 10,000)",
-        "Auto-reconnect with exponential backoff (1s → 30s max)",
-        "Remote agents visible in list/status CLI and MCP tools with peer provenance"
-      ],
-      "quiz": [
-        {
-          "id": "net-q1",
-          "question": "Developer A runs `paradigm symphony serve` and sees pairing code 472831. Developer B runs `paradigm symphony join --remote 192.168.1.42:3939`. What happens next?",
-          "choices": {
-            "A": "Developer B's agents automatically appear in A's inbox",
-            "B": "Developer B is prompted to enter the 6-digit pairing code from A's terminal",
-            "C": "The connection fails because Developer B didn't specify the --public flag",
-            "D": "Developer B must also run `paradigm symphony serve` to create a peer-to-peer link",
-            "E": "Developer B receives A's full agent list immediately without authentication"
-          },
-          "correct": "B",
-          "explanation": "When connecting via --remote without an embedded code (no # in the address), the user is prompted to enter the 6-digit pairing code displayed on the hub. The code is used to compute an HMAC proof for authentication. Only after successful verification does the agent list exchange occur."
-        },
-        {
-          "id": "net-q2",
-          "question": "A spoke machine loses its network connection to the hub. What happens?",
-          "choices": {
-            "A": "All local messages are deleted and the agent must re-pair from scratch",
-            "B": "The spoke immediately attempts to reconnect using a fixed 5-second interval",
-            "C": "The spoke schedules reconnect with exponential backoff (1s → 2s → 4s → ... → 30s max)",
-            "D": "The spoke shuts down and the user must manually restart `paradigm symphony join`",
-            "E": "The hub removes the spoke's peer record from peers.json"
-          },
-          "correct": "C",
-          "explanation": "The client-mode relay uses exponential backoff for auto-reconnect: starting at 1 second and doubling each attempt up to a maximum of 30 seconds. On successful reconnect, the delay resets to 1 second. Local messages are unaffected — they remain in the JSONL files."
-        },
-        {
-          "id": "net-q3",
-          "question": "An attacker tries to brute-force the pairing code. After entering 3 wrong codes from IP 10.0.0.5, what happens on the next attempt?",
-          "choices": {
-            "A": "The pairing code is rotated and a new code must be obtained from the hub",
-            "B": "The hub blocks all incoming connections permanently until restarted",
-            "C": "The connection is accepted but messages are quarantined for review",
-            "D": "The hub sends `auth_fail` with 'Too many failed attempts' and enforces a 60-second cooldown for that IP",
-            "E": "The hub disconnects but allows immediate retry with the correct code"
-          },
-          "correct": "D",
-          "explanation": "After 3 failed auth attempts from the same IP address, the relay enforces a 60-second cooldown. During this period, any connection from that IP receives an immediate auth_fail with the message 'Too many failed attempts — try again later' and is disconnected."
-        },
-        {
-          "id": "net-q4",
-          "question": "How does the relay prevent duplicate message delivery when two peers forward the same message?",
-          "choices": {
-            "A": "Messages include a TTL counter that decrements on each hop",
-            "B": "A bounded Set of seen message IDs (max 10,000) skips already-processed messages",
-            "C": "Each peer maintains a sequence number and only accepts higher-numbered messages",
-            "D": "The hub assigns unique relay IDs to prevent duplicates",
-            "E": "Messages are only forwarded once per minute, allowing time for dedup"
-          },
-          "correct": "B",
-          "explanation": "The relay maintains a bounded Set<string> of message IDs it has already processed. When a message arrives, if its ID is in the set, the relay sends an ack but skips delivery. When the set exceeds 10,000 entries, the oldest half is evicted. This prevents both echo (receiving your own message back) and multi-path duplicates."
-        },
-        {
-          "id": "net-q5",
-          "question": "Developer B wants to connect to Developer A's machine over the internet. Developer A runs `paradigm symphony serve --public`. What is the correct command for Developer B?",
-          "choices": {
-            "A": "`paradigm symphony join --remote devA.example.com` and enter the code when prompted",
-            "B": "`paradigm symphony join --remote 73.162.44.103:3939#847291` with the embedded code",
-            "C": "`paradigm symphony serve --connect 73.162.44.103:3939`",
-            "D": "`paradigm symphony peers add 73.162.44.103:3939 --code 847291`",
-            "E": "`paradigm symphony join --public 73.162.44.103`"
-          },
-          "correct": "B",
-          "explanation": "Internet direct connect uses the connection string format: address:port#code. The --public flag on the hub displays this connection string. The spoke parses the embedded code from after the # character and uses it automatically — no interactive prompt needed. Port 3939 must be reachable from the internet (port forward, VPN, or SSH tunnel)."
-        }
-      ]
-    },
-    {
-      "id": "review-compliance",
-      "title": "Automated Review Pipeline & Compliance Checking",
-      "content": "## paradigm review\n\nThe automated review pipeline uses a two-stage protocol:\n\n### Stage 1: Spec Compliance (always runs)\n\n- **Purpose coverage**: All touched symbols registered in .purpose files\n- **Portal gate compliance**: Routes declared in portal.yaml with gates\n- **Aspect anchors**: Anchor files still exist, no drift\n- **Broken references**: Parent symbols exist\n- **Route coverage**: New routes have portal.yaml entries\n\n### Stage 2: Code Quality (--deep only)\n\n- **Security**: eval() detection, hardcoded secrets\n- **Convention**: console.log usage (use Paradigm logger)\n- **Test coverage**: Gaps in test files\n\n### ReviewFinding Format\n\nEach finding has:\n- **type**: blocking (must fix), improvement (should fix), note (informational)\n- **category**: purpose-coverage, portal-compliance, aspect-anchors, security, convention\n- **message**: Human-readable description\n- **suggestion**: How to fix it\n\n### Usage\n\n```bash\nparadigm review              # Staged changes\nparadigm review --pr 123     # PR via gh CLI\nparadigm review --ci         # Exit 1 on blocking\nparadigm review --deep       # Include code quality\nparadigm review --json       # JSON output\n```\n\n## Dynamic Tool Loading\n\nTools are organized in three tiers:\n- **Core** (~15 tools): Always loaded (search, ripple, status, navigate, etc.)\n- **Feature**: Auto-detected from filesystem (lore → .paradigm/lore/, etc.)\n- **Advanced**: On-demand via `paradigm_tool_activate`\n\n## Response Format\n\n`response_format: 'concise'` on high-traffic tools strips secondary data:\n- paradigm_search: returns only { symbol, type }\n- paradigm_ripple: returns only { symbol, impact, summary }\n- paradigm_status: returns only { project, counts, total }\n\n## compliance-checker.ts\n\nShared logic extracted from pm.ts postflight. Both `paradigm_pm_postflight` and `paradigm review` use the same compliance checks.",
-      "quiz": [
-        {
-          "id": "Q-501-RC-001",
-          "question": "paradigm review --ci finds 2 blocking and 3 improvement findings. What's the exit code?",
-          "options": [
-            "Exit code 0 — improvements are non-blocking",
-            "Exit code 1 — any blocking findings cause non-zero exit in CI mode",
-            "Exit code 2 — one per blocking finding",
-            "Exit code 5 — total findings count"
-          ],
-          "correct": 1,
-          "explanation": "In CI mode, any blocking findings cause exit code 1. Improvements and notes do not affect the exit code."
-        },
-        {
-          "id": "Q-501-RC-002",
-          "question": "A project has no features: section in config.yaml. How many MCP tools are loaded?",
-          "options": [
-            "Only core tools (~15)",
-            "Core + explicitly enabled features",
-            "All of them — auto-detection is generous, defaulting to current behavior",
-            "None — features must be explicitly configured"
-          ],
-          "correct": 2,
-          "explanation": "No features config + generous auto-detection = all tools loaded, matching pre-4.0 behavior for backward compat."
-        },
-        {
-          "id": "Q-501-RC-003",
-          "question": "You call paradigm_search with response_format: 'concise'. What fields are returned?",
-          "options": [
-            "Full results with descriptions, paths, and fuzzy matches",
-            "Only { symbol, type } per result — descriptions and secondary data stripped",
-            "Only symbol names as a flat array",
-            "Compressed binary format"
-          ],
-          "correct": 1,
-          "explanation": "Concise mode strips results to { symbol, type } per entry and removes fuzzyMatched, fuzzyNote, suggestions, workspace data."
-        },
-        {
-          "id": "Q-501-RC-004",
-          "question": "An agent needs the graph generation tool but it's in the advanced tier. What does it do?",
-          "options": [
-            "Request an admin to enable it in config.yaml",
-            "Call paradigm_tool_activate with feature: 'graph'",
-            "Modify the agent's permissions to include graph tools",
-            "Restart the session with --enable-graph flag"
-          ],
-          "correct": 1,
-          "explanation": "paradigm_tool_activate enables advanced-tier modules for the current session. The tools become available immediately."
-        },
-        {
-          "id": "Q-501-RC-005",
-          "question": "What's the relationship between paradigm review Stage 1 and paradigm_pm_postflight?",
-          "options": [
-            "They are completely independent with different checks",
-            "paradigm review calls paradigm_pm_postflight internally",
-            "They share the same compliance logic extracted into compliance-checker.ts",
-            "paradigm_pm_postflight is deprecated in favor of paradigm review"
-          ],
-          "correct": 2,
-          "explanation": "Both use compliance-checker.ts for shared compliance logic — purpose coverage, portal gates, aspect anchors, and broken refs."
-        }
-      ]
-    }
-  ]
-}