@a-company/paradigm 3.44.0 → 5.3.3

package/dist/{sync-ZM4Q3R4U.js → sync-VEHUH4OA.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   syncCommand
-} from "./chunk-RP6TZYGE.js";
-import "./chunk-KB4XJWE3.js";
+} from "./chunk-2IO7JAG2.js";
+import "./chunk-6N3JTACN.js";
 import "./chunk-YO6DVTL7.js";
 import "./chunk-4NCFWYGG.js";
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 export {
   syncCommand
 };

package/dist/{sync-llms-JIPP3XX4.js → sync-llms-YHCFIE6X.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   loadParadigmFiles
-} from "./chunk-KB4XJWE3.js";
+} from "./chunk-6N3JTACN.js";
 import "./chunk-YO6DVTL7.js";
 import {
   log
 } from "./chunk-4NCFWYGG.js";
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/sync-llms.ts
 import * as fs from "fs";

package/dist/{task-loader-7M2FCBX6.js → task-loader-LDYWQSLM.js}

@@ -8,6 +8,7 @@ import {
   shelveTask,
   updateTask
 } from "./chunk-CSD7IHSN.js";
+import "./chunk-7N7GSU6K.js";
 export {
   completeTask,
   createTask,

package/dist/{team-HGLJXWQG.js → team-7HG7XK5C.js}

@@ -8,19 +8,19 @@ import {
   teamModelsCommand,
   teamResetCommand,
   teamStatusCommand
-} from "./chunk-HIKKOCXY.js";
-import "./chunk-QWA26UNO.js";
-import "./chunk-J4E6K5MG.js";
+} from "./chunk-EI32ZBE6.js";
+import "./chunk-WQITYKHM.js";
+import "./chunk-LSRABQIY.js";
 import "./chunk-PBHIFAL4.js";
-import "./chunk-FS3WTUHY.js";
+import "./chunk-TXESEO7Y.js";
 import "./chunk-6QC3YGB6.js";
 import "./chunk-PMXRGPRQ.js";
-import "./chunk-MW5DMGBB.js";
 import "./chunk-5JGJACDU.js";
 import "./chunk-ZGUAAVMA.js";
 import "./chunk-EDOAWN7J.js";
 import "./chunk-IRKUEJVW.js";
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-YMDLDELF.js";
+import "./chunk-PDX44BCA.js";
 export {
   teamAcceptCommand,
   teamCheckCommand,

package/dist/{test-WTR5Q33E.js → test-566CP5KC.js}

@@ -2,7 +2,7 @@
 import {
   parseGateConfig
 } from "./chunk-IRKUEJVW.js";
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/portal/test.ts
 import * as path3 from "path";

package/dist/{thread-3WM7KKID.js → thread-N754I4D5.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/thread.ts
 import * as fs from "fs";

package/dist/{timeline-ANC7LVDL.js → timeline-M3CICQFE.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   loadLoreEntries
-} from "./chunk-QIOCFXDQ.js";
-import "./chunk-ZXMDA7VB.js";
+} from "./chunk-EKGMAM62.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/lore/timeline.ts
 import chalk from "chalk";

package/dist/{triage-IZ4MDYNB.js → triage-HHYGT3HY.js}

@@ -10,7 +10,7 @@ import {
 import {
   SentinelStorage
 } from "./chunk-FKJUBQU3.js";
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/triage/index.ts
 import chalk2 from "chalk";

package/dist/{tutorial-GC6QL4US.js → tutorial-KD22SUNO.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import "./chunk-ZXMDA7VB.js";
+import "./chunk-PDX44BCA.js";
 
 // src/commands/tutorial/index.ts
 import * as path from "path";

package/dist/university-content/courses/.purpose

@@ -244,6 +244,17 @@ components:
     tags: [course-content, para-401]
     references: ["#orchestration", "#mcp-tools", "#paradigm-sync"]
 
+  para-401-agent-identity:
+    description: "Agent Identity & Expertise — .agent files, personality, expertise auto-population, symbol-to-agent routing, orchestration enrichment"
+    file: para-401.json
+    tags: [course-content, para-401]
+    references: ["#agent-loader", "#agent-tools", "#orchestration"]
+
+  para-401-notebooks-permissions:
+    description: "University lesson: Agent Notebooks & Permission Scoping — notebooks, permissions, integrity hashing"
+    type: lesson
+    tags: [university, notebooks, agent-identity, permissions]
+
   # PARA 501: Advanced Systems (10 lessons)
 
   para-501-lore-system:
@@ -311,3 +322,58 @@ components:
     file: para-501.json
     tags: [course-content, para-501]
     references: ["#PlatformServer", "#PlatformWebSocket", "#AgentPresenceManager", "#UserStateTracker", "#AgentCommandRoute", "#PlatformTools", "#AgentStore", "#AgentToast", "#AgentCallout"]
+
+  para-501-review-compliance:
+    description: "University lesson: Automated Review Pipeline — paradigm review, compliance-checker, dynamic tool loading, response format"
+    type: lesson
+    tags: [university, review, compliance, tool-loading]
+
+  # PARA 601: Ambient Coordination (8 lessons)
+
+  para-601-event-stream:
+    description: "Event Stream — append-only JSONL activity log, event types, automatic emission from MCP tools and hooks"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#event-stream"]
+
+  para-601-attention-scoring:
+    description: "Attention Scoring — four-dimension relevance scoring (symbol, path, concept, signal), max-based scoring, configurable thresholds"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#agent-loader", "#event-stream"]
+
+  para-601-nominations:
+    description: "Nominations — self-nominated agent contributions, brief/urgency/type/evidence, surfacing and engagement workflow"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#nomination-engine", "#agent-loader"]
+
+  para-601-knowledge-streams:
+    description: "Knowledge Streams — Work Log, Learning Journal, Team Decisions; different audiences, lifecycles, and storage"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#event-stream"]
+
+  para-601-trust-rings:
+    description: "Trust Rings — four concentric data sovereignty levels, project-locked default, enforcement boundaries"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#data-policy"]
+
+  para-601-data-policy:
+    description: "Data Policy — YAML-configured rules, observation control, stream filtering, per-agent overrides, DEFAULT_DATA_POLICY"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#data-policy"]
+
+  para-601-context-composition:
+    description: "Context Composition — paradigm_context_compose, profile enrichment, decisions, journal insights, nominations into session context"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#agent-loader", "#nomination-engine"]
+
+  para-601-ambient-review:
+    description: "Ambient Review — comprehensive review of PARA 601 ambient coordination concepts"
+    file: para-601.json
+    tags: [course-content, para-601]
+    references: ["#event-stream", "#nomination-engine", "#data-policy", "#agent-loader"]

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

@@ -689,6 +689,152 @@
           "explanation": "Token cost estimates enable agents to evaluate tool selection before calling. An agent deciding between paradigm_search (~150 tokens) and reading 5 files (~2500 tokens) can make an informed cost/benefit decision. The goal is efficiency, not restriction."
         }
       ]
+    },
+    {
+      "id": "agent-identity",
+      "title": "Agent Identity & Expertise Profiles",
+      "content": "## Agent Identity & Expertise Profiles\n\nEvery Claude session starts blank. The project remembers — via lore, protocols, aspects — but the agent doesn't. An architect that has successfully designed auth systems 14 times has no memory of that expertise. The orchestrator cannot route tasks to the most qualified agent because qualification is not tracked.\n\nAgent identity files (`.agent`) solve this with persistent YAML profiles that track expertise, personality, and cross-project patterns. They **overlay** the existing `agents.yaml` system and are fully backward compatible — when no `.agent` files exist, everything works exactly as before.\n\n### Storage & Merge Priority\n\nProfiles live in two locations:\n\n- **Global** (`~/.paradigm/agents/architect.agent`) — travels across projects\n- **Project** (`.paradigm/agents/builder.agent`) — project-level overrides\n\nMerge priority: **project `.agent` > global `.agent` > `agents.yaml`**. This means a project can override a global agent's default model or focus areas without modifying the shared identity.\n\n### Profile Structure\n\nEach `.agent` file contains:\n\n- **`id`** — Agent identifier (e.g., \"architect\")\n- **`personality`** — Style (deliberate/rapid/exploratory/methodical), risk tolerance (conservative/balanced/aggressive), and verbosity (minimal/concise/detailed)\n- **`expertise`** — Per-symbol entries with confidence (0.0-1.0), session count, and last touch date\n- **`transferable`** — Cross-project patterns with success rates and linked protocols/lore\n- **`contexts`** — Per-project adaptations: focus areas, preferred model, session count\n\n### Expertise Auto-Population\n\nWhen lore is recorded with `paradigm_lore_record`, the relevant agent's expertise scores update automatically via exponential moving average:\n\n```\nFor each symbol in symbols_touched:\n  if existing entry:\n    sessions++\n    confidence = 0.7 * old_confidence + 0.3 * lore_confidence\n  else:\n    create entry with confidence = lore_confidence (or 0.5 default)\n```\n\nAssessment verdicts from `paradigm_lore_assess` also feed into expertise. A verdict of `correct` nudges confidence up, `incorrect` nudges it down.\n\n### Querying Expertise\n\n`paradigm_agent_expertise` takes a symbol and returns agents ranked by confidence:\n\n```\nparadigm_agent_expertise({ symbol: \"#payment-service\" })\n// Returns: [{ agentId: \"architect\", confidence: 0.92, sessions: 14 }, ...]\n```\n\nThis enables **symbol-to-agent routing** — the orchestrator can prefer the agent most experienced with the symbols a task touches.\n\n### Orchestration Enrichment\n\nWhen `paradigm_orchestrate_inline` builds agent prompts, agents with `.agent` profiles receive a preamble:\n\n```markdown\n## Agent Identity: architect\n**Style:** deliberate | **Risk:** conservative | **Verbosity:** concise\n\n## Your Expertise on Relevant Symbols\n- #auth-middleware: confidence 0.92 (14 sessions)\n- $checkout-flow: confidence 0.88 (8 sessions)\n\n## Transferable Patterns\n- portal-gate-pattern: 95% success (learned in a-paradigm, applied in 2 projects)\n```\n\nThis goes BEFORE the role-specific prompt, giving the agent self-awareness about its strengths.\n\n### CLI Commands\n\n- `paradigm agent list` — Show all profiles with top expertise\n- `paradigm agent show <id>` — Full profile with expertise table\n- `paradigm agent create <id> --global` — Create new identity file\n- `paradigm agent sync <id>` — Bootstrap expertise from existing project lore\n\nAgent identities are a foundation for future capabilities: curated notebooks, model cascading, and knowledge graduation across projects.",
+      "keyConcepts": [
+        ".agent files are persistent YAML profiles that overlay agents.yaml — backward compatible",
+        "Two storage scopes: global (~/.paradigm/agents/) and project (.paradigm/agents/), project wins on merge",
+        "Expertise auto-updates via exponential moving average (70/30) from lore recording",
+        "paradigm_agent_expertise enables symbol-to-agent routing for orchestration",
+        "Orchestration enrichment prepends personality and expertise context to agent prompts"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You run `paradigm agent create architect --global`. Where is the file stored?",
+          "choices": {
+            "A": "In the project's .paradigm/agents/architect.agent",
+            "B": "In ~/.paradigm/agents/architect.agent",
+            "C": "In .paradigm/agents.yaml as a new entry",
+            "D": "In ~/.paradigm/score/agents/architect.agent",
+            "E": "In the project's .paradigm/config.yaml under agents section"
+          },
+          "correct": "B",
+          "explanation": "The --global flag stores the .agent file in ~/.paradigm/agents/, the global scope that travels across projects. Without --global, it would go in the project's .paradigm/agents/ directory."
+        },
+        {
+          "id": "q2",
+          "question": "Both ~/.paradigm/agents/builder.agent and .paradigm/agents/builder.agent exist with different defaultModel. Which one wins?",
+          "choices": {
+            "A": "The global one (~/.paradigm/agents/) always takes priority",
+            "B": "The one with the newer 'updated' timestamp wins",
+            "C": "Project-level .paradigm/agents/builder.agent takes priority",
+            "D": "agents.yaml overrides both .agent files",
+            "E": "An error is raised for the conflict"
+          },
+          "correct": "C",
+          "explanation": "Merge priority is: project .agent > global .agent > agents.yaml. Project-level overrides exist specifically so a project can customize model preferences or focus areas without changing the global identity."
+        },
+        {
+          "id": "q3",
+          "question": "An agent records lore with confidence: 0.8 touching #auth-middleware. The agent's existing expertise on that symbol is confidence: 0.9, sessions: 10. What's the new confidence?",
+          "choices": {
+            "A": "0.85 (simple average)",
+            "B": "0.87 (exponential moving average: 0.7 * 0.9 + 0.3 * 0.8)",
+            "C": "0.80 (new value replaces old)",
+            "D": "0.90 (existing value preserved)",
+            "E": "0.88 (weighted by session count)"
+          },
+          "correct": "B",
+          "explanation": "Expertise uses exponential moving average with alpha=0.3: new = 0.7 * old + 0.3 * new_observation. So 0.7 * 0.9 + 0.3 * 0.8 = 0.63 + 0.24 = 0.87. This balances stability (70% old) with responsiveness to new data (30% new)."
+        },
+        {
+          "id": "q4",
+          "question": "You want to find which agent is best qualified to modify #payment-service. Which MCP tool do you call?",
+          "choices": {
+            "A": "paradigm_agent_list and manually compare expertise arrays",
+            "B": "paradigm_agent_get with the symbol name",
+            "C": "paradigm_agent_expertise with symbol: \"#payment-service\"",
+            "D": "paradigm_search with query: \"payment-service agents\"",
+            "E": "paradigm_orchestrate_inline with the task description"
+          },
+          "correct": "C",
+          "explanation": "paradigm_agent_expertise takes a symbol and returns all agents with expertise on that symbol, ranked by confidence score. This is the purpose-built tool for symbol-to-agent routing, costing only ~100 tokens."
+        },
+        {
+          "id": "q5",
+          "question": "A project has agents.yaml with 5 agents but no .agent files. What happens during orchestration?",
+          "choices": {
+            "A": "An error: .agent files are required for orchestration",
+            "B": "agents.yaml is ignored and default agents are used",
+            "C": "Empty .agent files are auto-created for each agent",
+            "D": "Everything works exactly as before — .agent files are a pure overlay",
+            "E": "Orchestration runs but warns about missing profiles"
+          },
+          "correct": "D",
+          "explanation": ".agent files are a pure overlay. No files = no enrichment, same behavior as pre-3.47.0. The system is fully backward compatible — agents.yaml continues to work unchanged, and .agent profiles only add capabilities when present."
+        }
+      ]
+    },
+    {
+      "id": "notebooks-permissions",
+      "title": "Agent Notebooks & Permission Scoping",
+      "content": "## Agent Notebooks\n\nAgent notebooks are curated snippet libraries distilled from lore entries. They provide reusable knowledge that agents can apply across sessions and projects.\n\n### NotebookEntry Format\n\nEach entry contains:\n- **context**: When to apply this snippet (retrieval key)\n- **snippet**: The reusable code/knowledge\n- **provenance**: Where it came from (lore, manual, transfer)\n- **concepts[]**: Concept tags for retrieval (e.g., [\"auth\", \"middleware\"])\n- **appliedCount**: How many times used in orchestration\n- **confidence**: 0.0-1.0 reliability score\n\n### Storage\n\n- Global: `~/.paradigm/notebooks/{agent-id}/` — travels across projects\n- Project: `.paradigm/notebooks/{agent-id}/` — project-specific\n\n### MCP Tools\n\n- `paradigm_notebook_search` — find entries by concept, tag, or keyword\n- `paradigm_notebook_add` — create a new curated entry\n- `paradigm_notebook_promote` — extract from lore entry with provenance linking\n\n### Orchestration Integration\n\n`buildProfileEnrichment()` appends a \"Relevant Notebook Entries\" section with context + snippet for matching entries. This enriches the orchestration prompt with reusable patterns.\n\n## Agent Permissions\n\nPermission scoping controls what agents can access:\n\n### Permission Fields\n\n- **paths.read/write**: Glob patterns for file access\n- **paths.deny**: Always-deny patterns (overrides read/write)\n- **tools.allow/deny**: Tool name patterns\n- **dangerous_actions**: Actions requiring explicit approval\n\n### Integrity Hashing\n\nSHA-256 hash of `{id, role, permissions}` stored as `integrityHash`. `verifyIntegrity()` detects tampering — agents must never modify their own config.\n\n### In Orchestration\n\nPermissions appear as constraints in orchestration prompts, informing agents of their boundaries.",
+      "quiz": [
+        {
+          "id": "Q-401-NP-001",
+          "question": "Where are global notebook entries stored for the architect agent?",
+          "options": [
+            "~/.paradigm/notebooks/architect/",
+            ".paradigm/notebooks/architect/",
+            "~/.paradigm/agents/architect/notebooks/",
+            ".paradigm/agents/architect.notebooks"
+          ],
+          "correct": 0,
+          "explanation": "Global notebook entries are stored at ~/.paradigm/notebooks/{agent-id}/ and travel across projects."
+        },
+        {
+          "id": "Q-401-NP-002",
+          "question": "An agent has permissions.paths.deny: [\".paradigm/agents/*\"]. What happens if it tries to write to .paradigm/agents/builder.agent?",
+          "options": [
+            "The write succeeds if there's also a write pattern matching it",
+            "The write is flagged as denied — deny patterns always override allow patterns",
+            "The write succeeds but triggers an advisory",
+            "The agent profile is deleted"
+          ],
+          "correct": 1,
+          "explanation": "Deny patterns always override allow patterns. checkPathPermission() checks deny first."
+        },
+        {
+          "id": "Q-401-NP-003",
+          "question": "You want to extract a reusable pattern from lore entry L-2026-03-10-001 into the architect's notebook. Which MCP tool?",
+          "options": [
+            "paradigm_notebook_add with loreEntryId parameter",
+            "paradigm_lore_promote with agentId parameter",
+            "paradigm_notebook_promote with agentId + loreEntryId",
+            "paradigm_agent_notebook with action: 'promote'"
+          ],
+          "correct": 2,
+          "explanation": "paradigm_notebook_promote takes agentId + loreEntryId and creates a distilled notebook entry with provenance link."
+        },
+        {
+          "id": "Q-401-NP-004",
+          "question": "An architect agent has 3 notebook entries matching #auth-middleware. How does orchestration use them?",
+          "options": [
+            "They replace the agent's expertise section in the prompt",
+            "buildProfileEnrichment() appends a 'Relevant Notebook Entries' section with context + snippet",
+            "They are sent as separate tool calls before the main prompt",
+            "They override the agent's personality settings"
+          ],
+          "correct": 1,
+          "explanation": "buildProfileEnrichment() appends notebook entries (up to 5) with context + truncated snippet to the orchestration prompt."
+        },
+        {
+          "id": "Q-401-NP-005",
+          "question": "A .agent file's integrityHash doesn't match the computed hash. What does this indicate?",
+          "options": [
+            "The file was created before v4.0 and needs migration",
+            "The file was modified without going through saveAgentProfile() — possible tampering",
+            "The agent's expertise has been updated since the hash was computed",
+            "The hash algorithm has changed between versions"
+          ],
+          "correct": 1,
+          "explanation": "verifyIntegrity() returns false when the stored hash doesn't match. The hash covers id+role+permissions, so changes to those fields without saveAgentProfile() indicate tampering."
+        }
+      ]
     }
   ]
 }

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

@@ -955,6 +955,157 @@
           "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": "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."
+        }
+      ]
     }
   ]
 }