@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-501-hook-enforcement.md

@@ -0,0 +1,100 @@
+---
+id: N-para-501-hook-enforcement
+title: Hook Enforcement & Automation
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - stop-hook-blocks
+  - post-write-hook-tracks
+  - pre-commit-hook-auto-rebuilds
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## The Compliance Gap
+
+Paradigm'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.
+
+Hooks 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.
+
+## The Stop Hook
+
+The stop hook is the primary enforcer. It runs before an agent session completes and can **block** the session from finishing if compliance checks fail.
+
+**Trigger**: Before agent session end (Claude Code: Stop hook, Cursor: pre-finish)
+
+**Seven checks, in order:**
+
+1. **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.
+
+2. **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.
+
+3. **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.
+
+4. **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.
+
+5. **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.
+
+6. **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.
+
+7. **Lore entry for significant sessions** — If 3+ source files were modified and no lore entry was recorded in `.paradigm/lore/entries/`, the hook blocks.
+
+**When blocked**, the hook outputs a clear list of violations with remediation steps. Fix the violations, then complete the session.
+
+## The Post-Write Hook
+
+The post-write hook runs after every file edit (Edit or Write tool calls). It is **advisory only** — it never blocks.
+
+**Trigger**: After Edit or Write tool completes
+
+**Actions:**
+1. Extracts the edited file path
+2. Skips non-source files (.purpose, portal.yaml, .md, .lock, .json, .yaml, .gitignore, .env files) and paradigm directories (.paradigm/, .claude/, .cursor/)
+3. Appends source file paths to `.paradigm/.pending-review` (deduplicated)
+4. Checks if a .purpose file covers the edited directory
+5. If no .purpose exists: reminds "No .purpose file covers {dir}/ — Create one"
+6. Every 3 source files edited: general reminder to update .purpose files
+
+The `.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.
+
+## The Pre-Commit Hook
+
+The pre-commit hook runs before `git commit` and handles index maintenance. It **never blocks**.
+
+**Trigger**: Before Bash commands containing `git commit`
+
+**Actions:**
+1. Runs `paradigm index --quiet` to rebuild scan-index.json, navigator.yaml, and flow-index.json
+2. Stages the rebuilt files so they are included in the commit
+3. Exits 0 (always succeeds)
+
+This 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.
+
+## Hook Installation
+
+Hooks 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.
+
+For 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).
+
+## Remediation Workflow
+
+When the stop hook blocks you:
+
+1. **Read the violation list** — Each violation names the specific check that failed
+2. **Update .purpose files** — For modified directories without coverage, create or update the nearest .purpose file
+3. **Update portal.yaml** — If routes were added, add the route and gate definitions
+4. **Fix stale anchors** — If aspect anchors point to deleted/moved files, update the anchor paths
+5. **Record lore** — If 3+ files were modified, call `paradigm_lore_record` with the session summary
+6. **Run `paradigm_reindex`** — Rebuild the index to reflect your updates
+7. **Complete the session** — The stop hook runs again and should pass
+
+The 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.

package/dist/university-content/notes/N-para-501-lore-system.md

@@ -0,0 +1,155 @@
+---
+id: N-para-501-lore-system
+title: The Lore System
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-501
+  - lore-entries-record
+  - seven-entry-types
+  - date-partitioned-yaml-storage
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Why Projects Forget
+
+Every 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.
+
+Paradigm's Lore system is a structured project timeline. It records sessions, milestones, incidents, retros, reviews, and insights as date-partitioned YAML entries that both humans and AI agents can search, filter, and learn from.
+
+> **v6.0 change:** the `decision` lore type was removed. Architectural decisions now have their own dedicated store — see "Decisions Have Their Own Store" below.
+
+## Anatomy of a Lore Entry
+
+Every lore entry follows a consistent structure:
+
+```yaml
+id: L-2026-02-21-ascend-143025-001
+type: agent-session
+timestamp: "2026-02-21T14:30:25Z"
+duration_minutes: 45
+author: ascend
+agent:
+  provider: anthropic
+  model: claude-opus-4-6
+title: "Add JWT authentication to user routes"
+summary: "Implemented RS256 JWT auth middleware, added ^authenticated and ^project-admin gates to portal.yaml, created refresh token rotation."
+symbols_touched: ["#auth-middleware", "^authenticated", "^project-admin"]
+symbols_created: ["#refresh-token-handler"]
+files_modified: ["src/middleware/auth.ts", "portal.yaml"]
+files_created: ["src/handlers/refresh-token.ts"]
+lines_added: 247
+lines_removed: 12
+commit: "a1b2c3d"
+decisions:
+  - id: jwt-signing
+    decision: "Use RS256 over HS256"
+    rationale: "Allows public key verification without sharing the signing secret"
+learnings:
+  - "Express v5 requires explicit async error wrapping for middleware"
+verification:
+  status: pass
+  details: { "unit-tests": pass, "integration": pass }
+tags: [security, auth]
+```
+
+The `id` field is auto-generated as `L-{date}-{author}-{hhmmss}-{seq}` — date partitions the storage, author and timestamp disambiguate within a day, and the sequence handles burst writes. Note that `author` is the human user (a string), and AI assistance is recorded separately in the optional `agent` object. The `decisions` field on an agent-session entry remains valid — it captures decisions made *during* a work session. Standalone architectural decisions go through `paradigm_decision_record` (see below).
+
+## Entry Types
+
+Lore recognizes seven entry types, each capturing a different kind of project event:
+
+| Type | When to Use |
+|---|---|
+| `agent-session` | An AI agent completed a work session (most common) |
+| `human-note` | A human records context, rationale, or tribal knowledge |
+| `review` | A code review, PR review, or post-mortem |
+| `incident` | A production incident or significant failure |
+| `milestone` | A release, launch, migration completion, or major achievement |
+| `retro` | A retrospective on a sprint, project, or incident response |
+| `insight` | A learned pattern or observation worth preserving |
+
+The type drives how the entry appears in timeline views and which filters surface it.
+
+## Decisions Have Their Own Store
+
+In v6.0 the `decision` lore type was removed. Decisions are first-class enough to deserve their own store, separate from the time-partitioned narrative of lore. Decisions live in `.paradigm/decisions/` as `TD-*` entries, recorded via `paradigm_decision_record`. When you record a decision, Paradigm auto-writes a companion lore `insight` entry pointing at it (with `references.decision_id`) — so the timeline still surfaces the moment the decision was made, while the canonical decision record stays addressable by topic rather than by date.
+
+If you have a v1/v2 project with old `type: decision` lore entries, the storage layer migrates them to type `insight` on read and tags them `v6-migrated:from-decision` for forensic recovery. New entries with `type: 'decision'` are rejected at the storage layer with an error pointing you at the decision-record path. The rejection envelope (`code: 'lore_type_decision_removed'`, `successor_tool: 'paradigm_decision_record'`) is structured so calling agents can auto-retry without human intervention.
+
+Search hierarchy:
+- Use `paradigm_lore_search` for narrative ("what happened on 2026-02-21?").
+- Use `paradigm_decision_search` for canonical choices ("what did we decide about caching?").
+
+## Storage: Date-Partitioned YAML
+
+Lore entries live in `.paradigm/lore/entries/` organized by date. Filenames mirror the entry id (`L-{date}-{author}-{hhmmss}-{seq}.yaml`), so you can identify the author and burst order from the filename alone:
+
+```
+.paradigm/lore/
+  timeline.yaml          # Index metadata
+  entries/
+    2026-02-19/
+      L-2026-02-19-ascend-091203-001.yaml
+      L-2026-02-19-matt-143812-001.yaml
+    2026-02-20/
+      L-2026-02-20-ascend-101545-001.yaml
+    2026-02-21/
+      L-2026-02-21-ascend-143025-001.yaml
+```
+
+The `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.
+
+## CLI Tools
+
+The CLI provides full lore management:
+
+- `paradigm lore list` — List entries with filters (author, type, symbol, date range, tags)
+- `paradigm lore show <id>` — Full detail view of a single entry
+- `paradigm lore record` — Record a new entry with expanded fields (files-modified, files-created, commit, learnings, duration)
+- `paradigm lore edit <id>` — Edit entry fields (title, summary, type, symbols, tags, learnings)
+- `paradigm lore delete <id>` — Delete an entry (with --yes to skip confirmation)
+- `paradigm lore timeline` — Timeline view grouped by date with hot symbols
+- `paradigm lore review <id>` — Add review scores to an entry
+- `paradigm lore` — Launch the web timeline UI
+
+## MCP Tools
+
+The Lore system exposes the following MCP tools:
+
+**`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). Calling with `type: 'decision'` returns a structured rejection envelope pointing at `paradigm_decision_record`.
+
+**`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.
+
+**`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.
+
+**`paradigm_lore_get`** — Fetch a single entry by ID. Returns the full entry with all fields, including decisions, learnings, and review data.
+
+**`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.
+
+**`paradigm_lore_delete`** — Delete an entry by ID. Requires `confirm: true` to prevent accidental deletion.
+
+**`paradigm_lore_assess`** — Score an entry's quality and completeness (1-5 each), with optional notes. The assessment is stored alongside the entry and feeds the calibration and review filters.
+
+**`paradigm_lore_calibration`** — Surface calibration drift: entries where the recorded confidence diverges from later-observed reality. Use this to find sessions where an agent over- or under-estimated its certainty.
+
+## Lore Reviews
+
+Entries 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.
+
+## When to Record
+
+The 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.
+
+Beyond the threshold, always record lore for: production incidents, milestone completions, retros, and any session where you learned something the next developer should know. For standalone architectural decisions, use `paradigm_decision_record` instead — the decision store handles them, and a companion lore `insight` is auto-written for timeline coverage.
+
+> **Going deeper:** PARA 601 covers knowledge streams (work-log, journal, decisions) and how `paradigm_decision_record` writes to the decisions stream while emitting a companion lore `insight` for timeline coverage. PARA 301 covers the new dedicated decision store in detail (`N-para-301-decisions`).

package/dist/university-content/notes/N-para-501-platform-agent-ui.md

@@ -0,0 +1,108 @@
+---
+id: N-para-501-platform-agent-ui
+title: Platform & Agent-Driven UI
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - paradigm-serve-unifies
+  - agent-driven-ui-5
+  - pipeline-mcp-
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## The Unified Platform
+
+`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.
+
+The 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.
+
+### Architecture
+
+```
+localhost:3850 (Express + WebSocket)
+├── /api/lore/*        ← LoreRouter
+├── /api/symbols/*     ← SymbolsRouter
+├── /api/graphs/*      ← GraphsRouter
+├── /api/platform/*    ← PlatformRouter (health, sections, agent-command)
+├── /ws                ← WebSocket (agent commands + user activity)
+└── /                  ← Platform UI SPA
+```
+
+## Agent-Driven UI
+
+The 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.
+
+### The Pipeline: MCP → HTTP → WebSocket → Browser
+
+```
+Agent (Claude Code)       Platform Server          Browser
+      │                          │                    │
+      │ paradigm_platform_*      │                    │
+      │ POST /api/platform/cmd   │                    │
+      │ ─────────────────────────►│                    │
+      │   ◄── { ok: true } ──────│                    │
+      │                          │  ws: agent:*       │
+      │                          │──────────────────►│
+      │                          │                    │ UI updates
+```
+
+Why 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.
+
+### The Five Tools
+
+| Tool | Purpose |
+|------|---------|
+| `paradigm_platform_navigate` | Switch sections, select symbols, open lore entries |
+| `paradigm_platform_highlight` | Pulsing glow on symbols with color + label, auto-expires |
+| `paradigm_platform_annotate` | Toasts (notifications), callouts (on graph nodes), badges |
+| `paradigm_platform_observe` | Read user's current section, selected symbol, theme, mute state |
+| `paradigm_platform_clear` | Remove all agent highlights and annotations |
+
+### Conflict Resolution: User Always Wins
+
+The agent must never hijack the user's attention:
+
+- **User idle (>5s):** Agent navigation executes immediately
+- **User active (<5s):** A prompt appears: "Agent wants to show you #X — [Go there] [Dismiss]"
+- **User muted:** All agent effects are silently discarded; `observe` returns `{ muted: true }`
+
+### Agent Presence
+
+The `#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.
+
+Stale agents are auto-pruned after 2 minutes of inactivity.
+
+### User State Tracking
+
+The `#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.
+
+Browser clients report activity via WebSocket messages: `user:navigate`, `user:select`, `user:theme`, `user:mute`.
+
+### Visual Treatment
+
+| Element | Human | Agent |
+|---------|-------|-------|
+| Selection ring | Solid 2px blue | Dashed 2px agent-color |
+| Highlight | N/A | Pulsing glow animation |
+| Toast | N/A | Left border + robot icon |
+| Navigation | Instant | 300ms ease + toast notification |
+
+### Browser Architecture
+
+The agent UI layer sits alongside existing stores:
+
+- `agentStore.ts` — Zustand store managing presence, highlights, annotations, toasts, mute, pending navigation
+- `useAgentEffects` — Hook connecting WebSocket `agent:*` messages to store actions, with auto-reconnect
+- `useActivityReporter` — Hook reporting section/theme changes back to server
+- `AgentToast` — Severity-colored toast component
+- `AgentCallout` — Floating callout overlay + navigation conflict prompt

package/dist/university-content/notes/N-para-501-review-compliance.md

@@ -0,0 +1,72 @@
+---
+id: N-para-501-review-compliance
+title: Automated Review Pipeline & Compliance Checking
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## paradigm review
+
+The automated review pipeline uses a two-stage protocol:
+
+### Stage 1: Spec Compliance (always runs)
+
+- **Purpose coverage**: All touched symbols registered in .purpose files
+- **Portal gate compliance**: Routes declared in portal.yaml with gates
+- **Aspect anchors**: Anchor files still exist, no drift
+- **Broken references**: Parent symbols exist
+- **Route coverage**: New routes have portal.yaml entries
+
+### Stage 2: Code Quality (--deep only)
+
+- **Security**: eval() detection, hardcoded secrets
+- **Convention**: console.log usage (use Paradigm logger)
+- **Test coverage**: Gaps in test files
+
+### ReviewFinding Format
+
+Each finding has:
+- **type**: blocking (must fix), improvement (should fix), note (informational)
+- **category**: purpose-coverage, portal-compliance, aspect-anchors, security, convention
+- **message**: Human-readable description
+- **suggestion**: How to fix it
+
+### Usage
+
+```bash
+paradigm review              # Staged changes
+paradigm review --pr 123     # PR via gh CLI
+paradigm review --ci         # Exit 1 on blocking
+paradigm review --deep       # Include code quality
+paradigm review --json       # JSON output
+```
+
+## Dynamic Tool Loading
+
+Tools are organized in three tiers:
+- **Core** (~15 tools): Always loaded (search, ripple, status, navigate, etc.)
+- **Feature**: Auto-detected from filesystem (lore → .paradigm/lore/, etc.)
+- **Advanced**: On-demand via `paradigm_tool_activate`
+
+## Response Format
+
+`response_format: 'concise'` on high-traffic tools strips secondary data:
+- paradigm_search: returns only { symbol, type }
+- paradigm_ripple: returns only { symbol, impact, summary }
+- paradigm_status: returns only { project, counts, total }
+
+## compliance-checker.ts
+
+Shared logic extracted from pm.ts postflight. Both `paradigm_pm_postflight` and `paradigm review` use the same compliance checks.

package/dist/university-content/notes/N-para-501-sentinel-deep-dive.md

@@ -0,0 +1,173 @@
+---
+id: N-para-501-sentinel-deep-dive
+title: Sentinel Deep Dive
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - symbolic-incident-records
+  - flow-position-tracking
+  - automatic-incident-grouping
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Beyond Stack Traces
+
+Traditional 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."
+
+## Symbolic Incident Records
+
+When Sentinel records an incident, it captures both technical and symbolic context:
+
+```yaml
+id: INC-042
+timestamp: "2026-02-21T02:15:00Z"
+status: open
+error:
+  message: "Cannot read property 'id' of null"
+  stack: "at PaymentProcessor.processRefund (payment-processor.ts:142)"
+  type: TypeError
+symbols:
+  component: "#payment-processor"
+  flow: "$refund-flow"
+  gate: "^authenticated"
+flowPosition:
+  flowId: "$refund-flow"
+  expected: ["^authenticated", "^refund-eligible", "#process-refund", "!refund-completed"]
+  actual: ["^authenticated", "^refund-eligible", "#process-refund"]
+  missing: ["!refund-completed"]
+  failedAt: "#process-refund"
+environment: production
+```
+
+The `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.
+
+## Incident Grouping
+
+Sentinel 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.
+
+An `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`.
+
+## Failure Patterns
+
+Patterns are the institutional knowledge of your error handling. Each pattern defines matching criteria and a resolution strategy:
+
+```yaml
+id: payment-null-ref-001
+name: "Null reference in payment processing"
+pattern:
+  symbols:
+    component: "#payment-processor"
+  errorType: [TypeError]
+  errorContains: ["Cannot read property", "null"]
+resolution:
+  description: "Add null check before accessing refund object properties"
+  strategy: fix-code
+  priority: high
+  symbolsToModify: ["#payment-processor"]
+  filesLikelyInvolved: ["src/services/payment-processor.ts"]
+confidence:
+  score: 85
+  timesMatched: 12
+  timesResolved: 10
+  timesRecurred: 2
+```
+
+Six 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`.
+
+Patterns 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.
+
+## The Triage Workflow
+
+Sentinel follows a defined lifecycle for incidents:
+
+1. **Record** — `paradigm_sentinel_record` creates the incident with error details, symbolic context, and optional flow position. The incident starts as `open`.
+
+2. **Triage** — `paradigm_sentinel_triage` lists incidents filtered by status, symbol, environment, or error text. The matcher automatically suggests patterns that fit each incident.
+
+3. **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.
+
+4. **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.
+
+5. **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.
+
+The sequence is: **record → triage → show → resolve → add pattern**. This cycle builds institutional knowledge with every incident.
+
+## Stats and Health Metrics
+
+`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).
+
+The `symbolHealth` view shows per-symbol incident history — use it to identify which components need hardening or refactoring.
+
+## Logger Transports
+
+Sentinel 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.
+
+```typescript
+interface LogTransport {
+  name: string;
+  send(entry: LogEntry): void | Promise<void>;
+}
+```
+
+The 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.
+
+## The SentinelTransport Bridge
+
+Connecting the Paradigm logger to Sentinel is a one-liner:
+
+```typescript
+import { enableSentinel } from '@a-company/sentinel';
+
+enableSentinel({ endpoint: 'http://localhost:3001' });
+```
+
+This 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.
+
+The 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.
+
+## Metrics API
+
+Sentinel's server exposes a metrics API for recording and querying application metrics:
+
+**POST /api/metrics** — Record a metric data point. Supports three metric types:
+- `counter` — Monotonically increasing values (e.g., request count, error count)
+- `gauge` — Point-in-time values that can go up or down (e.g., active connections, queue depth)
+- `histogram` — Distribution of values over time (e.g., response latency, payload size)
+
+```json
+{
+  "name": "api.requests.total",
+  "type": "counter",
+  "value": 1,
+  "labels": { "method": "POST", "route": "/api/payments" },
+  "timestamp": "2026-02-21T14:30:00Z"
+}
+```
+
+**GET /api/metrics** — Query metrics with optional filters by name, type, labels, and time range. Returns aggregated data suitable for dashboards and alerting.
+
+## Traces API
+
+Sentinel supports distributed tracing through span trees:
+
+**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`.
+
+**GET /api/traces** — Query traces by operation name, service, time range, or minimum duration. Returns full span trees with timing breakdowns.
+
+## Service Registry
+
+Sentinel maintains a live registry of services reporting data:
+
+**POST /api/services** — Register or update a service. Each service entry includes name, version, environment, health status, and last-seen timestamp.
+
+**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.