@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-701-symphony-visibility.md

@@ -0,0 +1,142 @@
+---
+id: N-para-701-symphony-visibility
+title: 'Lesson 8: Live Visibility via Symphony'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - orchestrator-auto-emits-thr-orch-id
+  - noterelay-polls-paradigmscorethreads
+  - symphonythreadwatcher-filters-orchestration
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## The Visibility Gap
+
+Orchestration runs inside an MCP tool call. The human sees: "Calling paradigm_orchestrate_inline..." followed by a wall of text when it completes. There is no live visibility into what is happening during orchestration — which agents are active, what they are producing, whether they agree or disagree, how far along the plan is.
+
+Symphony closes this gap by providing a real-time communication channel between the orchestrator, agents, and the Conductor UI. The orchestrator emits progress into Symphony threads. The Conductor watches these threads and renders live updates.
+
+## How Orchestration Emits to Symphony
+
+When `paradigm_orchestrate_inline` runs in execute mode, it auto-emits a Symphony thread with a `thr-orch-` prefix:
+
+```typescript
+const orchestrationThread = `thr-orch-${orchestrationId}`;
+```
+
+The orchestrator creates this thread via the Symphony loader and posts an initial note from the "maestro" identity:
+
+```typescript
+const maestroId = `${projectName}/maestro`;
+symphony.createNote(orchestrationThread, {
+  from: maestroId,
+  content: `Orchestration started: ${taskDescription}`,
+  type: 'agent',
+  project: projectName,
+  role: 'orchestrator',
+});
+```
+
+As each agent completes its work, the orchestrator posts their contributions to the thread. If security finds a gate coverage issue, that appears as a note from the security agent. If the builder completes implementation, that appears as a note from the builder. The thread becomes a chronological record of the orchestration.
+
+The `thr-orch-` prefix is critical — it is the identifier that allows the Conductor to distinguish orchestration threads from regular Symphony threads (like team chat or general discussion).
+
+## NoteRelay: The Polling Bridge
+
+Symphony threads are stored as JSON files in `~/.paradigm/score/threads/`. The Conductor is a native macOS application that cannot directly watch the filesystem for MCP-created files (different process, different sandbox). NoteRelay bridges this gap.
+
+NoteRelay is a Conductor service that polls the Symphony thread directory on a 5-second interval:
+
+```
+~/.paradigm/score/threads/*.json → NoteRelay (5s poll) → Conductor state
+```
+
+Every 5 seconds, NoteRelay scans for new or modified thread files. When it finds changes, it parses the JSON, extracts the notes, and updates the Conductor's in-memory state. This creates a near-real-time bridge between the MCP server (which writes threads) and the Conductor UI (which displays them).
+
+The 5-second poll interval is a deliberate balance. A 1-second poll would provide faster updates but consume more CPU on the macOS overlay app. A 30-second poll would be too slow for live orchestration visibility. Five seconds means the Conductor is at most 5 seconds behind the actual orchestration state.
+
+## SymphonyThreadWatcher: Filtering Orchestration Threads
+
+NoteRelay delivers all Symphony threads to the Conductor. But the Team view in Conductor only wants orchestration threads — not general discussion or personal notes. SymphonyThreadWatcher handles this filtering.
+
+SymphonyThreadWatcher polls at a 3-second interval (faster than NoteRelay's 5-second scan) and filters threads by the `thr-orch-` prefix:
+
+```
+All Symphony threads → SymphonyThreadWatcher (3s poll) → 
+Filter: thr-orch-* → TeamThreadView
+```
+
+The watcher also tracks thread state: is the orchestration in progress, completed, or failed? It determines this by checking the latest note in the thread — a "completed" or "failed" status note indicates the orchestration has finished.
+
+## TeamThreadView: Rendering in Conductor
+
+TeamThreadView is the SwiftUI view that renders orchestration threads in the Conductor overlay. Each note in the thread is displayed with:
+
+1. **Colored role badge** — Each agent role has a distinct color. The architect gets one color, the security agent another, the builder another. This makes it immediately visible who said what without reading names.
+
+2. **Intent indicator** — The orchestration plan specifies an intent for each agent (e.g., "review gate coverage", "implement webhook handler"). The intent appears next to the agent's badge, providing context for why the agent was included.
+
+3. **Agent nickname** — If the agent has a nickname (Mika, Atlas, Jinx), it is displayed alongside the role. This makes attributed responses feel like team communication rather than tool output.
+
+4. **Note content** — The actual contribution from the agent. This could be a review finding, a code suggestion, a security flag, or a completion confirmation.
+
+The visual layout mimics a team chat interface: chronological notes from identified agents, each with their role badge and intent. The human can watch the orchestration unfold in real time rather than waiting for a monolithic output.
+
+## Agent-Side Emission
+
+Agents are instructed (via their orchestration prompts) to emit progress and completion notes to Symphony during execution. The orchestrator includes this instruction:
+
+```markdown
+## Symphony Communication
+During your work, emit progress notes to the active Symphony thread.
+Use these note types:
+- progress: "Reviewing file X of Y..."
+- finding: "Found gate coverage gap on POST /api/payments"
+- completion: "Review complete. 2 findings, 0 blockers."
+```
+
+Not all agents emit notes equally. The architect tends to emit planning updates. The security agent emits findings. The builder emits completion summaries. The documentor emits what it updated. This diversity creates a natural team-communication feel in the thread.
+
+## The Full Pipeline
+
+Putting it all together, the live visibility pipeline is:
+
+```
+pardigm_orchestrate_inline execute
+  ↓
+Orchestrator creates thr-orch-{id} thread
+  ↓
+Each agent contributes → notes posted to thread
+  ↓
+Thread file written to ~/.paradigm/score/threads/
+  ↓
+NoteRelay polls (5s) → detects new/changed thread
+  ↓
+SymphonyThreadWatcher filters (3s) → thr-orch-* threads
+  ↓
+TeamThreadView renders with colored badges and intents
+  ↓
+Human sees live orchestration progress in Conductor overlay
+```
+
+The latency from agent contribution to visual display is at most ~8 seconds (5s NoteRelay + 3s ThreadWatcher in the worst case). In practice, it is usually 3-5 seconds because the polls are offset.
+
+## Why This Architecture
+
+The polling-based architecture was chosen over alternatives for pragmatic reasons:
+
+- **Filesystem watching** (FSEvents on macOS) is brittle across sandboxed processes and does not work reliably when the MCP server writes files from a different process tree.
+- **WebSocket/TCP connection** between MCP server and Conductor would require connection management, reconnection logic, and port conflicts. Polling a directory is simpler.
+- **Shared memory** would require both processes to link against the same framework, creating tight coupling.
+
+Polling JSON files from a well-known directory is the simplest architecture that provides near-real-time visibility without process-coupling complexity. The tradeoff is a 3-8 second display latency, which is acceptable for human observation of orchestration progress.

package/dist/university-content/paths/LP-para-001.yaml

@@ -0,0 +1,29 @@
+id: LP-para-001
+title: 'PARA 001: Quick Start'
+description: Get productive with Paradigm in 15 minutes. Initialize a project, meet your agent team, and build your first feature with orchestration. Hands-on from the first minute — theory comes later.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-001
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+steps:
+  - content: N-para-001-shift-setup
+    required: true
+  - content: Q-para-001-shift-setup
+    required: true
+    passRequired: true
+  - content: N-para-001-meet-the-team
+    required: true
+  - content: Q-para-001-meet-the-team
+    required: true
+    passRequired: true
+  - content: N-para-001-build-something
+    required: true
+  - content: Q-para-001-build-something
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-101.yaml

@@ -0,0 +1,59 @@
+id: LP-para-101
+title: 'PARA 101: Foundations'
+description: Master the fundamentals of Paradigm — the meta-framework that gives AI agents structured context to navigate and understand your codebase. Learn the five symbols, purpose files, tags, logging, project structure, and gates.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+steps:
+  - content: N-para-101-welcome
+    required: true
+  - content: Q-para-101-welcome
+    required: true
+    passRequired: true
+  - content: N-para-101-first-steps
+    required: true
+  - content: Q-para-101-first-steps
+    required: true
+    passRequired: true
+  - content: N-para-101-five-symbols
+    required: true
+  - content: Q-para-101-five-symbols
+    required: true
+    passRequired: true
+  - content: N-para-101-purpose-files
+    required: true
+  - content: Q-para-101-purpose-files
+    required: true
+    passRequired: true
+  - content: N-para-101-tags-and-classification
+    required: true
+  - content: Q-para-101-tags-and-classification
+    required: true
+    passRequired: true
+  - content: N-para-101-paradigm-logger
+    required: true
+  - content: Q-para-101-paradigm-logger
+    required: true
+    passRequired: true
+  - content: N-para-101-project-structure
+    required: true
+  - content: Q-para-101-project-structure
+    required: true
+    passRequired: true
+  - content: N-para-101-portal-yaml
+    required: true
+  - content: Q-para-101-portal-yaml
+    required: true
+    passRequired: true
+  - content: N-para-101-component-types
+    required: true
+  - content: Q-para-101-component-types
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-201.yaml

@@ -0,0 +1,69 @@
+id: LP-para-201
+title: 'PARA 201: Architecture'
+description: Deepen your Paradigm expertise with advanced patterns for flows, gates, aspects, disciplines, naming conventions, and architectural design. Learn to build complete features end-to-end using the full symbol system.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+steps:
+  - content: N-para-201-flows-deep-dive
+    required: true
+  - content: Q-para-201-flows-deep-dive
+    required: true
+    passRequired: true
+  - content: N-para-201-gates-deep-dive
+    required: true
+  - content: Q-para-201-gates-deep-dive
+    required: true
+    passRequired: true
+  - content: N-para-201-aspects-and-anchors
+    required: true
+  - content: Q-para-201-aspects-and-anchors
+    required: true
+    passRequired: true
+  - content: N-para-201-aspect-graph
+    required: true
+  - content: Q-para-201-aspect-graph
+    required: true
+    passRequired: true
+  - content: N-para-201-portal-protocol
+    required: true
+  - content: Q-para-201-portal-protocol
+    required: true
+    passRequired: true
+  - content: N-para-201-disciplines
+    required: true
+  - content: Q-para-201-disciplines
+    required: true
+    passRequired: true
+  - content: N-para-201-symbol-naming
+    required: true
+  - content: Q-para-201-symbol-naming
+    required: true
+    passRequired: true
+  - content: N-para-201-component-patterns
+    required: true
+  - content: Q-para-201-component-patterns
+    required: true
+    passRequired: true
+  - content: N-para-201-signal-patterns
+    required: true
+  - content: Q-para-201-signal-patterns
+    required: true
+    passRequired: true
+  - content: N-para-201-cross-cutting-concerns
+    required: true
+  - content: Q-para-201-cross-cutting-concerns
+    required: true
+    passRequired: true
+  - content: N-para-201-architecture-review
+    required: true
+  - content: Q-para-201-architecture-review
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-301.yaml

@@ -0,0 +1,84 @@
+id: LP-para-301
+title: 'PARA 301: Operations'
+description: Master the operational tools and workflows that keep a Paradigm project healthy. From history tracking and fragility analysis to sentinel observability and context management, this course covers the day-to-day operations that separate well-maintained projects from chaotic ones.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+steps:
+  - content: N-para-301-history-system
+    required: true
+  - content: Q-para-301-history-system
+    required: true
+    passRequired: true
+  - content: N-para-301-fragility-tracking
+    required: true
+  - content: Q-para-301-fragility-tracking
+    required: true
+    passRequired: true
+  - content: N-para-301-wisdom-system
+    required: true
+  - content: Q-para-301-wisdom-system
+    required: true
+    passRequired: true
+  - content: N-para-301-decisions
+    required: true
+  - content: Q-para-301-decisions
+    required: true
+    passRequired: true
+  - content: N-para-301-ripple-analysis
+    required: true
+  - content: Q-para-301-ripple-analysis
+    required: true
+    passRequired: true
+  - content: N-para-301-doctor-and-validation
+    required: true
+  - content: Q-para-301-doctor-and-validation
+    required: true
+    passRequired: true
+  - content: N-para-301-enforcement-levels
+    required: true
+  - content: Q-para-301-enforcement-levels
+    required: true
+    passRequired: true
+  - content: N-para-301-paradigm-shift
+    required: true
+  - content: Q-para-301-paradigm-shift
+    required: true
+    passRequired: true
+  - content: N-para-301-navigation-system
+    required: true
+  - content: Q-para-301-navigation-system
+    required: true
+    passRequired: true
+  - content: N-para-301-sentinel-observability
+    required: true
+  - content: Q-para-301-sentinel-observability
+    required: true
+    passRequired: true
+  - content: N-para-301-sync-and-maintenance
+    required: true
+  - content: Q-para-301-sync-and-maintenance
+    required: true
+    passRequired: true
+  - content: N-para-301-context-management
+    required: true
+  - content: Q-para-301-context-management
+    required: true
+    passRequired: true
+  - content: N-para-301-protocols
+    required: true
+  - content: Q-para-301-protocols
+    required: true
+    passRequired: true
+  - content: N-para-301-operations-review
+    required: true
+  - content: Q-para-301-operations-review
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-401.yaml

@@ -0,0 +1,74 @@
+id: LP-para-401
+title: 'PARA 401: Orchestration'
+description: Advanced course on multi-agent orchestration, MCP tool mastery, and framework-level coordination. Learn to decompose complex tasks across specialized agents, configure provider cascades, enforce governance with the PM layer, and achieve full Paradigm framework mastery.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+steps:
+  - content: N-para-401-mcp-tools-overview
+    required: true
+  - content: Q-para-401-mcp-tools-overview
+    required: true
+    passRequired: true
+  - content: N-para-401-multi-agent-coordination
+    required: true
+  - content: Q-para-401-multi-agent-coordination
+    required: true
+    passRequired: true
+  - content: N-para-401-agent-roles
+    required: true
+  - content: Q-para-401-agent-roles
+    required: true
+    passRequired: true
+  - content: N-para-401-provider-cascade
+    required: true
+  - content: Q-para-401-provider-cascade
+    required: true
+    passRequired: true
+  - content: N-para-401-orchestration-workflow
+    required: true
+  - content: Q-para-401-orchestration-workflow
+    required: true
+    passRequired: true
+  - content: N-para-401-quick-check
+    required: true
+  - content: Q-para-401-quick-check
+    required: true
+    passRequired: true
+  - content: N-para-401-pm-governance
+    required: true
+  - content: Q-para-401-pm-governance
+    required: true
+    passRequired: true
+  - content: N-para-401-commit-conventions
+    required: true
+  - content: Q-para-401-commit-conventions
+    required: true
+    passRequired: true
+  - content: N-para-401-mastery-review
+    required: true
+  - content: Q-para-401-mastery-review
+    required: true
+    passRequired: true
+  - content: N-para-401-agent-interop
+    required: true
+  - content: Q-para-401-agent-interop
+    required: true
+    passRequired: true
+  - content: N-para-401-agent-identity
+    required: true
+  - content: Q-para-401-agent-identity
+    required: true
+    passRequired: true
+  - content: N-para-401-notebooks-permissions
+    required: true
+  - content: Q-para-401-notebooks-permissions
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-501.yaml

@@ -0,0 +1,89 @@
+id: LP-para-501
+title: 'PARA 501: Advanced Systems'
+description: Master Paradigm's advanced operational systems — Lore for project memory, Sentinel for incident intelligence, Habits for behavioral discipline, Session Intelligence for crash recovery, and Hook Enforcement for automated compliance. Ties everything together into the complete Paradigm workflow.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+steps:
+  - content: N-para-501-lore-system
+    required: true
+  - content: Q-para-501-lore-system
+    required: true
+    passRequired: true
+  - content: N-para-501-sentinel-deep-dive
+    required: true
+  - content: Q-para-501-sentinel-deep-dive
+    required: true
+    passRequired: true
+  - content: N-para-501-aspect-graph-internals
+    required: true
+  - content: Q-para-501-aspect-graph-internals
+    required: true
+    passRequired: true
+  - content: N-para-501-habits-practice
+    required: true
+  - content: Q-para-501-habits-practice
+    required: true
+    passRequired: true
+  - content: N-para-501-session-intelligence
+    required: true
+  - content: Q-para-501-session-intelligence
+    required: true
+    passRequired: true
+  - content: N-para-501-hook-enforcement
+    required: true
+  - content: Q-para-501-hook-enforcement
+    required: true
+    passRequired: true
+  - content: N-para-501-advanced-workflows
+    required: true
+  - content: Q-para-501-advanced-workflows
+    required: true
+    passRequired: true
+  - content: N-para-501-aspect-graph-advanced
+    required: true
+  - content: Q-para-501-aspect-graph-advanced
+    required: true
+    passRequired: true
+  - content: N-para-501-task-management
+    required: true
+  - content: Q-para-501-task-management
+    required: true
+    passRequired: true
+  - content: N-para-501-assessment-loops
+    required: true
+  - content: Q-para-501-assessment-loops
+    required: true
+    passRequired: true
+  - content: N-para-501-symphony-a-mail
+    required: true
+  - content: Q-para-501-symphony-a-mail
+    required: true
+    passRequired: true
+  - content: N-para-501-platform-agent-ui
+    required: true
+  - content: Q-para-501-platform-agent-ui
+    required: true
+    passRequired: true
+  - content: N-para-501-conductor-workspace
+    required: true
+  - content: Q-para-501-conductor-workspace
+    required: true
+    passRequired: true
+  - content: N-para-501-symphony-networking
+    required: true
+  - content: Q-para-501-symphony-networking
+    required: true
+    passRequired: true
+  - content: N-para-501-review-compliance
+    required: true
+  - content: Q-para-501-review-compliance
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-601.yaml

@@ -0,0 +1,59 @@
+id: LP-para-601
+title: 'PARA 601: Paradigm Ambient'
+description: Master Paradigm's ambient coordination system — knowledge streams, event stream, attention scoring, nominations, data sovereignty, agent manifest renaissance, and context composition. The full loop from observation to adaptation.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+steps:
+  - content: N-para-601-learning-loop
+    required: true
+  - content: Q-para-601-learning-loop
+    required: true
+    passRequired: true
+  - content: N-para-601-knowledge-streams
+    required: true
+  - content: Q-para-601-knowledge-streams
+    required: true
+    passRequired: true
+  - content: N-para-601-event-stream
+    required: true
+  - content: Q-para-601-event-stream
+    required: true
+    passRequired: true
+  - content: N-para-601-attention-scoring
+    required: true
+  - content: Q-para-601-attention-scoring
+    required: true
+    passRequired: true
+  - content: N-para-601-nominations-debates
+    required: true
+  - content: Q-para-601-nominations-debates
+    required: true
+    passRequired: true
+  - content: N-para-601-data-sovereignty
+    required: true
+  - content: Q-para-601-data-sovereignty
+    required: true
+    passRequired: true
+  - content: N-para-601-agent-renaissance
+    required: true
+  - content: Q-para-601-agent-renaissance
+    required: true
+    passRequired: true
+  - content: N-para-601-context-composition
+    required: true
+  - content: Q-para-601-context-composition
+    required: true
+    passRequired: true
+  - content: N-para-601-maestro-team-collab
+    required: true
+  - content: Q-para-601-maestro-team-collab
+    required: true
+    passRequired: true

package/dist/university-content/paths/LP-para-701.yaml

@@ -0,0 +1,64 @@
+id: LP-para-701
+title: 'PARA 701: Agent Mastery'
+description: Master the Paradigm agent system — from the 54-agent roster to orchestration enforcement, learning loops, and the nevr.land marketplace.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+ordered: true
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+steps:
+  - content: N-para-701-agent-roster
+    required: true
+  - content: Q-para-701-agent-roster
+    required: true
+    passRequired: true
+  - content: N-para-701-agent-profiles
+    required: true
+  - content: Q-para-701-agent-profiles
+    required: true
+    passRequired: true
+  - content: N-para-701-agent-notebooks
+    required: true
+  - content: Q-para-701-agent-notebooks
+    required: true
+    passRequired: true
+  - content: N-para-701-agent-state
+    required: true
+  - content: Q-para-701-agent-state
+    required: true
+    passRequired: true
+  - content: N-para-701-per-project-rosters
+    required: true
+  - content: Q-para-701-per-project-rosters
+    required: true
+    passRequired: true
+  - content: N-para-701-model-tier-resolution
+    required: true
+  - content: Q-para-701-model-tier-resolution
+    required: true
+    passRequired: true
+  - content: N-para-701-orchestration-enforcement
+    required: true
+  - content: Q-para-701-orchestration-enforcement
+    required: true
+    passRequired: true
+  - content: N-para-701-symphony-visibility
+    required: true
+  - content: Q-para-701-symphony-visibility
+    required: true
+    passRequired: true
+  - content: N-para-701-learning-feedback-loop
+    required: true
+  - content: Q-para-701-learning-feedback-loop
+    required: true
+    passRequired: true
+  - content: N-para-701-agent-pods-nevrland
+    required: true
+  - content: Q-para-701-agent-pods-nevrland
+    required: true
+    passRequired: true