@a-company/paradigm 5.38.0 → 6.0.4

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.

package/dist/university-content/notes/N-para-501-session-intelligence.md

@@ -0,0 +1,104 @@
+---
+id: N-para-501-session-intelligence
+title: Session Intelligence
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - four-checkpoint-phases
+  - breadcrumbs-auto-track-every
+  - paradigmsessionrecover-restores-last
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## The Session Problem
+
+AI 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.
+
+## Session Checkpoints
+
+Checkpoints are deliberate snapshots saved at phase transitions. There are four phases:
+
+| Phase | When to Checkpoint | What to Capture |
+|---|---|---|
+| `planning` | After reading requirements, before coding | Plan, approach, key decisions |
+| `implementing` | After starting code changes | Modified files, symbols touched, decisions made |
+| `validating` | After implementation, before tests | All modified files, test plan |
+| `complete` | Task finished | Summary, final file list |
+
+Create a checkpoint with `paradigm_session_checkpoint`:
+
+```
+paradigm_session_checkpoint({
+  phase: "implementing",
+  context: "Adding JWT auth middleware — RS256 signing, httpOnly refresh tokens",
+  modifiedFiles: ["src/middleware/auth.ts", "src/handlers/refresh.ts"],
+  symbolsTouched: ["#auth-middleware", "^authenticated"],
+  decisions: ["RS256 over HS256 for public key verification"]
+})
+```
+
+Only `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?"
+
+Checkpoints are stored in `.paradigm/session-checkpoint.json` and auto-expire after 7 days.
+
+## Breadcrumb Tracking
+
+While 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).
+
+Breadcrumbs 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.
+
+## Session Recovery
+
+Recovery 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:
+
+- **breadcrumbs** — The last session's tool call trail
+- **lastCheckpoint** — The most recent checkpoint with phase, context, and details
+- **symbolsModified** — All symbols that were changed
+- **recentActivity** — A human-readable summary of what happened
+
+This 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.
+
+## The Global Brain
+
+Session Intelligence extends beyond individual projects through the Global Brain at `~/.paradigm/`. This user-level directory stores:
+
+- **Global wisdom** — Antipatterns and decisions that apply everywhere (e.g., "never use HS256 for JWT signing in production")
+- **Global habits** — Behavioral overrides that apply to all projects
+- **Cross-project practice events** — Compliance data aggregated across projects
+
+The distinction between project scope and global scope is important:
+
+| Scope | Location | Applies To | Example |
+|---|---|---|---|
+| Project | `.paradigm/` | This project only | "Use Redis for caching in this app" |
+| Global | `~/.paradigm/` | All projects | "Always check fragility before modifying critical symbols" |
+
+## Wisdom Promotion
+
+When 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.
+
+For 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.
+
+## Handoff Persistence
+
+When 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.
+
+The 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.
+
+## Best Practices
+
+- Checkpoint at every phase transition — the cost is ~100 tokens, the value is crash recovery
+- Write `context` as if briefing a stranger with no prior knowledge
+- Promote wisdom that survives 3+ projects to global scope
+- Use handoffs proactively at 80% context, not reactively at 95%
+- Let breadcrumbs accumulate naturally — don't try to manage them manually

package/dist/university-content/notes/N-para-501-symphony-a-mail.md

@@ -0,0 +1,120 @@
+---
+id: N-para-501-symphony-a-mail
+title: 'Symphony: Multi-Agent Messaging with The Score'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - the-score-is
+  - agent-identity-is
+  - mailbox-protocol-uses
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Agents Need to Talk
+
+Until 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.
+
+Symphony 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.
+
+## The Metaphor: Email for AI Agents
+
+The 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.
+
+This 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).
+
+## Agent Identity and Discovery
+
+Every 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.
+
+When 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:
+
+- **`inbox.jsonl`** — Messages waiting for this agent, one per line, append-only
+- **`outbox.jsonl`** — Replies from this agent, append-only
+- **`ack.json`** — The ID of the last acknowledged message (for garbage collection)
+- **`identity.json`** — Agent ID, project, role, PID, and session start time
+
+The 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.
+
+## Messaging and Threading
+
+Messages in The Score carry structured metadata beyond plain text. Every message has an **intent** that classifies its purpose:
+
+| Intent | Meaning |
+|---|---|
+| `question` | Asking for information from other agents |
+| `context` | Providing background or context |
+| `proposal` | Proposing an action or fix |
+| `action` | Announcing an action the agent took |
+| `decision` | Recording a decision |
+| `alert` | Forwarding a Sentinel alert |
+| `approval` / `rejection` | Responding to a proposal |
+| `handoff` | Transferring responsibility to another agent |
+| `fileRequest` | Requesting a file from another agent |
+| `fileDelivery` | Delivering a requested file |
+
+Intents 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.
+
+Messages 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.
+
+## The File Pipeline
+
+Agents 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**.
+
+The 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.
+
+Trust 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.
+
+## /loop: The Agent Heartbeat
+
+The 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.
+
+Without `/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.
+
+The 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.
+
+## Thread Resolution and Lore Integration
+
+Conversation 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.
+
+This 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.
+
+## CLI Commands
+
+The `paradigm symphony` command group provides the complete human interface:
+
+- `paradigm symphony whoami` — Show this agent's identity and linked peers
+- `paradigm symphony list` — List all known agents with status (awake/asleep) and location
+- `paradigm symphony join` — Discover and connect Claude Code sessions on this machine
+- `paradigm symphony join --remote <ip>` — Connect to a remote machine's mail server
+- `paradigm symphony send "message"` — Broadcast to all linked agents
+- `paradigm symphony send --to <agent> "message"` — Direct message to a specific agent
+- `paradigm symphony send --thread <id> "message"` — Reply to an existing thread
+- `paradigm symphony read` — Show unread messages
+- `paradigm symphony threads` — List active threads
+- `paradigm symphony resolve <id>` — Resolve a thread, creating a lore entry
+- `paradigm symphony status` — Network overview (agents, threads, unread count)
+
+For the file pipeline: `paradigm symphony request`, `paradigm symphony requests`, `paradigm symphony approve`, and `paradigm symphony deny`.
+
+## MCP Tools for Agent Participation
+
+Six MCP tools power agent-side Symphony participation:
+
+- **`paradigm_symphony_poll`** — The heartbeat. Reads inbox, returns formatted messages and thread summaries. Called by `/loop`.
+- **`paradigm_symphony_send`** — Send a message with intent, text, optional symbols, diff, or decision. Writes to outbox.
+- **`paradigm_symphony_status`** — Overview of the local network: agents, threads, Sentinel endpoint.
+- **`paradigm_symphony_thread`** — Get full context of a conversation thread with messages, participants, and extracted decisions.
+- **`paradigm_symphony_request_file`** — Request a file from another agent. Returns immediately with `pending` status; delivery arrives via future poll.
+- **`paradigm_symphony_approve_file`** — Approve or deny a pending file request after human confirmation.
+
+These 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.