@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-601-knowledge-streams.md

@@ -0,0 +1,144 @@
+---
+id: N-para-601-knowledge-streams
+title: Knowledge Streams
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - three-knowledge-streams
+  - work-log-paradigmwork-logdate
+  - learning-journal-paradigmagentsidjournal
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## The Lore Split
+
+Paradigm's original lore system stored everything — sessions, decisions, incidents, milestones — in a single stream of date-partitioned YAML entries. This worked well for small projects, but as projects grew, the single stream created problems. A standup bot pulling "what got done this week" had to filter through architectural decisions and incident postmortems. An agent looking for "what did I learn about JWT handling" had to parse session summaries. A new team member searching for "why did we choose Redis" had to wade through hundreds of entries.
+
+v5.0 splits lore into three knowledge streams, each with a distinct audience, lifecycle, and storage location.
+
+## Stream 1: Work Log — "What Got Done"
+
+The work log is the team-facing record of completed work. It answers the question every standup asks: what did you do, what is left, what is blocking you?
+
+**Storage:** `.paradigm/work-log/{date}/` — project-scoped, date-partitioned YAML files, one entry per work unit.
+
+**Audience:** The team. Standup bots, sprint boards, and project managers consume work log entries.
+
+**Lifecycle:** Ephemeral. Work log entries are relevant for days to weeks. After a sprint ends, they are historical context rather than active reference.
+
+**Entry structure (`WorkLogEntry`):**
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Unique ID (e.g., `WL-security-001`) |
+| `agent` | yes | Agent that performed the work |
+| `timestamp` | yes | ISO 8601 timestamp |
+| `summary` | yes | What was done |
+| `outcome` | yes | pass, fail, partial, or blocked |
+| `task_ref` | no | Ticket or issue reference (e.g., `ENG-142`) |
+| `files_modified` | no | List of modified files |
+| `symbols_touched` | no | Paradigm symbols touched |
+| `next_steps` | no | What remains to be done |
+| `blockers` | no | What is blocking progress |
+| `duration_minutes` | no | How long the work took |
+| `commit` | no | Git commit hash |
+
+**MCP Tools:**
+- `paradigm_work_log_record` — Record a work log entry. Requires `agent`, `summary`, and `outcome`. Supports optional `task_ref`, `files_modified`, `symbols_touched`, `next_steps`, `blockers`, `duration_minutes`, and `commit`.
+- `paradigm_work_log_search` — Search work log entries by `agent`, `outcome`, `task_ref`, `symbol`, `dateFrom`, `dateTo`. Pass `summary: true` to get an aggregate summary instead of individual entries.
+
+## Stream 2: Learning Journal — "What I Learned"
+
+The learning journal is the agent-private record of insights, corrections, and patterns discovered during work. It answers the question: what should I remember for next time?
+
+**Storage:** `~/.paradigm/agents/{id}/journal/` — user-scoped, agent-specific. The journal travels with the agent across projects because learning is not project-specific.
+
+**Audience:** The agent itself (and optionally other agents if the insight is marked `transferable`).
+
+**Lifecycle:** Durable. A pattern discovered today about JWT ordering is relevant months from now. Journal entries persist until explicitly archived.
+
+**Entry structure (`JournalEntry`):**
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Unique ID (e.g., `LJ-2026-03-20-001`) |
+| `agent` | yes | Agent who learned this |
+| `timestamp` | yes | ISO 8601 timestamp |
+| `trigger` | yes | What prompted the learning (7 trigger types) |
+| `insight` | yes | The insight itself |
+| `project` | yes | Project where this happened |
+| `transferable` | yes | Whether this applies to other projects |
+| `confidence_before` | no | Agent's confidence before (0.0-1.0) |
+| `confidence_after` | no | Adjusted confidence after (0.0-1.0) |
+| `pattern` | no | Extracted `LearningPattern` (id, applies_when, correct_approach) |
+| `linked_work_log` | no | Work log entry that prompted this learning |
+| `tags` | no | Tags for categorization |
+
+Seven journal triggers capture distinct learning moments: `correction_received` (human corrected the approach), `confidence_miss` (agent was confident but wrong), `pattern_discovered` (new reusable pattern found), `debate_loss` (another agent's approach was chosen), `failure_analysis` (something broke and was analyzed), `human_feedback` (direct human assessment), and `self_reflection` (agent proactively recorded an insight).
+
+**MCP Tools:**
+- `paradigm_journal_record` — Record a journal entry. Requires `agent`, `trigger`, `insight`, `project`, and `transferable`. Supports optional `confidence_before`, `confidence_after`, `pattern`, `linked_work_log`, and `tags`.
+- `paradigm_journal_search` — Search journal entries by `agent`, `trigger`, `project`, `transferable`, `tag`, `dateFrom`, `dateTo`. Pass `stats: true` (with `agent`) to get aggregate statistics.
+
+## Stream 3: Team Decisions — "What We Decided"
+
+Team decisions are the institutional record of choices made, rationale given, and alternatives rejected. They answer the question: why did we do it this way?
+
+**Storage:** `.paradigm/decisions/` — project-scoped, not date-partitioned (decisions are referenced by topic, not by when they were made).
+
+**Audience:** The entire team — current and future. New team members benefit most from decision records.
+
+**Lifecycle:** Institutional. Decisions persist until explicitly superseded or deprecated. A decision made in month one remains authoritative until a newer decision replaces it.
+
+**Entry structure (`TeamDecision`):**
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Unique ID (e.g., `TD-2026-03-20-001`) |
+| `title` | yes | Decision title |
+| `timestamp` | yes | ISO 8601 timestamp |
+| `participants` | yes | Who participated (id, role, stance) |
+| `decision` | yes | The decision itself |
+| `rationale` | yes | Why this was chosen |
+| `alternatives_considered` | no | What else was considered and why it was rejected |
+| `symbols_affected` | no | Paradigm symbols affected |
+| `status` | yes | active, proposed, superseded, deprecated, rejected |
+| `tags` | no | Tags for categorization |
+
+Participant stances capture the human dynamics: `proposed`, `supported`, `dissented`, `abstained`, `neutral`. Recording dissent is especially important — when a decision is revisited later, knowing who dissented and why saves time.
+
+**MCP Tools:**
+- `paradigm_decision_record` — Record a decision. Requires `title`, `decision`, `rationale`, and `participants`. Supports optional `alternatives_considered`, `symbols_affected`, `status`, and `tags`.
+- `paradigm_decision_search` — Search decisions by `status`, `participant`, `symbol`, `tag`, `dateFrom`, `dateTo`. Pass `summary: true` for an aggregate view.
+
+## Auto-Classification and the Companion-Lore Pattern
+
+When recording via `paradigm_lore_record`, the `stream` parameter routes the entry to the correct knowledge stream. Setting `stream: 'auto'` triggers auto-classification based on the entry type. The `LORE_TYPE_TO_STREAM` mapping (defined in `packages/paradigm-mcp/src/types/knowledge-streams.ts`) defines how lore types map to streams:
+
+- `agent-session` splits into work-log (what was done) and journal (what was learned)
+- `incident` splits across work-log (what happened), journal (what we learned), and decisions (prevention strategy)
+- `review` splits into work-log and journal
+- `human-note` routes to the decisions stream (institutional context)
+- `retro` and `insight` route to journal and decisions (learnings worth preserving)
+- `milestone` routes to the decisions stream
+
+Note that the `decision` lore *type* was removed in v6.0 — see PARA 501 — but the `decision` *stream* persists. The stream is fed by `paradigm_decision_record`, not by typed lore entries. The `LORE_TYPE_TO_STREAM` table still contains a residual `'decision': ['decision']` mapping for backward-compat with v1/v2 entries that get migrated to type `insight` on read; new writes never reach that branch.
+
+### The Companion-Lore Pattern (v6.0)
+
+When you call `paradigm_decision_record`, two things happen:
+
+1. The canonical decision is written to `.paradigm/decisions/TD-*.yaml` (decisions stream).
+2. A companion lore entry of type `insight` is auto-written to the lore timeline (journal stream), with a back-reference (`references.decision_id`) to the TD- ID.
+
+This split lets the decision stay topic-addressable (search by symbol, status, participant) while the timeline still shows the moment it was made. Project newcomers can follow the timeline forward and see the major calls; researchers can query the decisions stream directly. The companion write is best-effort — a failure to write the companion lore never blocks the decision record.

package/dist/university-content/notes/N-para-601-learning-loop.md

@@ -0,0 +1,68 @@
+---
+id: N-para-601-learning-loop
+title: The Learning Loop
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - six-phase-learning-loop
+  - observation-without-adaptation
+  - v50-closes-the
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## Why Observation Without Adaptation Is Waste
+
+Most development tools observe extensively but adapt almost never. Your linter sees thousands of issues. Your CI runs hundreds of tests. Your APM collects millions of metrics. All of this observation generates data — but data without a feedback loop is just noise with a storage bill.
+
+Consider what happens in a typical AI-assisted session today. An agent modifies 8 files, creates a new service, adds routes to portal.yaml, and records a lore entry. The session ends. A week later, a different agent picks up related work and makes the same architectural mistake the first agent corrected mid-session. Why? Because the correction was never captured in a form that feeds back into future sessions. The observation happened (the lore entry recorded what was done), but the adaptation never occurred (the learning was not injected into the next agent's context).
+
+This is the gap that Paradigm v5.0 closes.
+
+## The DO-RECORD-ASSESS-LEARN-ADAPT-DO Cycle
+
+The ambient coordination system implements a six-phase loop:
+
+**DO** — An agent performs work: modifying files, calling tools, making decisions. Every action produces events in the event stream.
+
+**RECORD** — The work is captured in three knowledge streams, each with a different audience and lifecycle. The work log records what got done (for the team). The learning journal records what the agent learned (for itself). Team decisions record what was decided and why (for the institution).
+
+**ASSESS** — Events flow through attention filters. Each agent scores every event against its attention patterns — symbol matches, path matches, concept matches, signal matches. Events that exceed an agent's threshold trigger the next phase.
+
+**LEARN** — Agents self-nominate contributions based on relevant events. A security agent notices a new route without a gate. A reviewer spots a pattern they have seen fail before. A tester sees a new component without test coverage. These nominations capture agent-specific insights triggered by project activity.
+
+**ADAPT** — Learnings feed back into context. Journal insights from past sessions appear in the next session's prompt enrichment. Recent team decisions are surfaced to agents working on related symbols. Pending nominations are included in the active agent's context. The `paradigm_context_compose` tool assembles all of this into a coherent context section.
+
+**DO** — The cycle repeats, but now the agent starts with richer context. It knows what was tried before, what the team decided, what the security agent flagged, and what patterns to avoid. Each iteration produces better outcomes because the loop is closed.
+
+## What v5.0 Adds to Close the Loop
+
+Before v5.0, Paradigm had the DO and RECORD phases (lore entries, .purpose files, portal.yaml). It had partial ASSESS capability through ripple analysis. But the LEARN and ADAPT phases were manual — a human had to read lore entries and tell the next agent what to watch out for.
+
+v5.0 adds four capabilities that close the loop automatically:
+
+1. **Knowledge Streams** — Lore is split into three streams with distinct storage, lifecycles, and audiences, enabling targeted adaptation.
+2. **Event Stream** — Every tool call and file edit produces a structured event that flows through attention filters, enabling real-time assessment.
+3. **Attention Scoring & Nominations** — Agents evaluate events against their attention patterns and self-nominate contributions, enabling machine-driven learning.
+4. **Context Composition** — Journal insights, team decisions, and pending nominations are composed into the next session's context, enabling automatic adaptation.
+
+## Context Engineering: Slim CLAUDE.md + On-Demand Guidance
+
+The learning loop requires efficient context management. A 900-line CLAUDE.md that loads every time wastes tokens on content that may not be relevant to the current task. v5.0 implements a context engineering approach:
+
+**Slim CLAUDE.md** — The base CLAUDE.md was reduced from ~856 lines to ~150 lines. It contains only the orientation information needed for every session: project overview, symbol system, conventions, commit format, and pointers to on-demand resources.
+
+**On-Demand Guidance** — Twelve guidance resources are available via `paradigm://guidance/{topic}`. Topics include logging, portal protocol, MCP workflow, flows, orchestration, workspaces, university, calibration, checkpoints, navigation, component types, and troubleshooting. An agent loads only the guidance it needs for the current task.
+
+**Agent Contributions** — Active agents inject their own context sections via `AgentContext.contributions`. A security agent might contribute a section listing recently added gates. A reviewer might contribute a section listing code smells found in the current PR. These contributions compose dynamically based on which agents are active.
+
+The result is a context window that contains high-signal, task-relevant content rather than a static wall of instructions. The learning loop feeds relevant history into this context, making each session incrementally smarter than the last.

package/dist/university-content/notes/N-para-601-maestro-team-collab.md

@@ -0,0 +1,136 @@
+---
+id: N-para-601-maestro-team-collab
+title: 'Maestro: Visible Team Orchestration'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - maestro-is-a
+  - attributed-responses-nickname
+  - agent-profiles-carry
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## From Synthesized Summaries to Attributed Conversations
+
+Traditional multi-agent orchestration has a visibility problem. An orchestrator spawns three agents, waits for their responses, synthesizes a summary, and presents it to the human. The human sees one voice — the orchestrator's — and loses all nuance from individual agent perspectives. If the architect disagreed with the security agent, you would never know. If the builder had a novel approach, it gets flattened into a consensus view.
+
+The Maestro model inverts this pattern. Every agent speaks for itself.
+
+## The Maestro Model
+
+Maestro is not a separate system — it is a behavior pattern for the active Claude Code session. When you ask a complex question that benefits from multiple perspectives, Maestro:
+
+1. **Evaluates expertise** — Which agents have the highest confidence scores on the relevant symbols?
+2. **Loads ambient context** — Recent team decisions, journal insights, pending nominations are injected into each agent's prompt via `buildProfileEnrichment()`.
+3. **Spawns subagents** — Each agent receives its full profile: personality, expertise history, transferable patterns, notebook entries, and the ambient context.
+4. **Presents attributed responses** — Each agent's response appears with a `[role]` or `[nickname (role)]` prefix. You see exactly who said what.
+5. **Records to Symphony** — Each contribution is written as a Symphony message, creating a persistent team thread visible in Conductor and the Platform dashboard.
+6. **Learns from feedback** — At session end, `paradigm_ambient_learn` adjusts each agent's attention threshold based on acceptance/dismissal rates.
+
+## Agent Profiles and Nicknames
+
+Each agent has an `.agent` YAML file in `~/.paradigm/agents/` with:
+
+- **personality** — style (deliberate/rapid/exploratory/methodical), risk tolerance, verbosity
+- **expertise** — per-symbol confidence scores, exponential moving average from lore
+- **attention** — threshold, symbol/path/concept/signal subscriptions
+- **collaboration** — default stance toward other agents, debate behavior
+- **nomination** — urgency patterns, communication style
+- **nickname** — optional display name (e.g., "George" for the architect)
+- **benched** — if true, Maestro skips this agent entirely
+
+The `nickname` field makes agents feel like team members. Terminal output shows `[George (architect)]` instead of the generic `[architect]`.
+
+## Bench and Activate
+
+Not every agent should speak on every task. The bench system lets you silence noisy agents:
+
+- `paradigm agent bench security` — security agent stops nominating and is excluded from orchestration
+- `paradigm agent activate security` — restore to active status
+- `paradigm agent roster` — see who is active vs benched with stats
+
+Benched agents are skipped in both `paradigm_orchestrate_inline` and the nomination engine's `processEvent`. Their profiles remain intact — bench is a pause, not a delete.
+
+## Symphony Team Threads
+
+Every orchestration creates a thread prefixed `thr-orch-`. Maestro writes each agent contribution as a Symphony message from the agent's identity (`{project}/{role}`). This creates:
+
+- **Persistent record** — The team conversation survives session restarts
+- **Conductor visibility** — The TeamThreadView shows messages with colored role prefixes
+- **Platform dashboard** — The Team section displays the same thread in a browser
+- **Recovery context** — Next session's handoff includes which agents contributed and what they said
+
+## The Neverland Test
+
+Named after the validation criteria in the spec, the Neverland test tracks whether agent learning actually works across sessions:
+
+- **Sessions 1-3**: Agents accumulate — touching symbols, recording lore, discovering patterns
+- **Sessions 4-5**: Maestro routes based on learned confidence scores
+- **Sessions 6-10**: Accepted suggestions lower threshold (agent speaks more). Dismissed suggestions raise it (agent speaks less).
+
+Measurable targets:
+- By session 10, Maestro routes to the right agent >80% of the time
+- Agent acceptance rate improves from ~50% (cold start) to >70%
+
+Track progress with `paradigm_ambient_health` — returns per-agent stats and overall health status (cold-start → accumulating → calibrating → mature).
+
+## Postflight Learning Loop
+
+The postflight skill closes the feedback loop after every task:
+
+1. **Step 8b** runs `paradigm_ambient_learn` for each contributing agent — adjusts attention thresholds based on accept/dismiss rates
+2. Runs `paradigm_ambient_promote` — auto-promotes high-confidence journal patterns to the agent's notebook
+3. Records contributions via Symphony if not already done during execution
+
+This ensures every session makes agents incrementally smarter. The handoff skill captures agent performance summaries so the next session inherits this knowledge.
+
+## The Teacher Model
+
+The learning loop has a quality problem: the nomination engine only sees file paths, never content. Briefs like "review for consistency" get dismissed, which raises the agent's threshold, which silences the agent. The system learns to be *silent* instead of *better*.
+
+The Teacher Model fixes this. Maestro (the active session) acts as a teacher who observes the full session and writes targeted feedback.
+
+### Session Work Log
+
+During each session, a running JSONL log at `.paradigm/events/session-log.jsonl` captures:
+- **Agent contributions**: what each agent was asked to do (from orchestration)
+- **User verdicts**: accepted / dismissed / revised, with the reason why
+
+This is the data Maestro reads at postflight to write meaningful learning feedback.
+
+### Postflight Learning Pass
+
+At session end, Step 8b reads the session work log and writes journal entries per agent:
+
+- **Accepted** → `human_feedback` trigger, confidence 0.85, extract the pattern that was confirmed correct
+- **Dismissed** → `correction_received` trigger, confidence 0.4, explain what was wrong and what to do differently
+- **Revised** → `correction_received` trigger, confidence 0.65, include the delta between proposal and actual
+
+These journal entries include `pattern.applies_when` and `pattern.correct_approach` fields — the exact knowledge that gets promoted to notebooks.
+
+### Training New Behaviors
+
+The journal → notebook → `buildProfileEnrichment` pipeline is also how you teach agents new skills. If you say "documentor, also update CHANGELOG from now on," Maestro writes a journal entry. It promotes to a notebook entry. Next session, that knowledge is in the agent's context. No configuration needed.
+
+## The Documentor Agent
+
+The 6th core agent. Its sole job: maintain Paradigm metadata files after other agents finish their work.
+
+- Always runs as the **final orchestration stage**
+- Reviews what changed (git diff, session work log)
+- Updates .purpose files, portal.yaml, symbol registrations
+- Uses ONLY `paradigm_purpose_*`, `paradigm_portal_*`, and `paradigm_reindex` MCP tools
+- Never modifies source code
+- Relieves all other agents of Paradigm compliance
+
+This separation of concerns means architect, builder, security, and reviewer can focus purely on their domain. The documentor handles the bookkeeping.

package/dist/university-content/notes/N-para-601-nominations-debates.md

@@ -0,0 +1,115 @@
+---
+id: N-para-601-nominations-debates
+title: Nominations & Debates
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - nominations-are-structured
+  - four-urgency-levels
+  - five-nomination-types
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## Agents Self-Nominate Contributions
+
+In the ambient model, agents do not push messages at each other. Instead, when an event exceeds an agent's attention threshold, the agent creates a **nomination** — a structured contribution that may or may not be surfaced to the human. Nominations are the bridge between passive observation and active participation.
+
+The key insight is that not every observation deserves immediate attention. A nomination captures the agent's contribution in a structured format, and surfacing rules determine when and how to present it. This prevents the "every agent shouts at once" problem that plagues naive multi-agent systems.
+
+## Nomination Anatomy
+
+A nomination has 13 fields:
+
+```typescript
+interface Nomination {
+  id: string;                    // Unique ID
+  agent: string;                 // Nominating agent
+  relevance: number;             // Attention score (0.0-1.0)
+  urgency: NominationUrgencyLevel;  // critical, high, medium, low
+  type: NominationType;          // warning, suggestion, question, offer, observation
+  brief: string;                 // 1-line summary
+  detail?: string;               // Full contribution (shown on engage)
+  action_offered?: string;       // Action the agent offers to take
+  evidence?: NominationEvidence[];  // Supporting evidence
+  triggered_by: string[];        // Event ID(s) that triggered this
+  timestamp: string;             // ISO 8601
+  surfaced: boolean;             // Whether shown to human
+  engaged?: boolean;             // Whether human interacted
+  response?: string;             // accepted, dismissed, deferred
+}
+```
+
+The `brief` field is critical — it is the first (and possibly only) thing the human sees. A good brief is actionable and specific: "New POST /api/payments route lacks ^payment-authorized gate" rather than "Security concern detected."
+
+The `detail` field expands on the brief with full reasoning, code references, and recommendations. It is shown only if the human engages with the nomination, saving context window space when the human dismisses or defers.
+
+## Urgency Levels
+
+Four urgency levels determine how aggressively a nomination is surfaced:
+
+| Level | Meaning | Surfacing Rule |
+|---|---|---|
+| `critical` | Immediate action required — security vulnerability, data loss risk | Always surfaced immediately, interrupts if necessary |
+| `high` | Should be addressed before session ends — missing gate, broken flow | Surfaced in the current batch, highlighted |
+| `medium` | Worth knowing but not blocking — code smell, missing test | Surfaced if the human has not dismissed similar nominations recently |
+| `low` | FYI — style suggestion, minor optimization opportunity | Batched and shown only if the human asks or at session end |
+
+The surfacing rules are configurable via `SurfacingConfig`. A user who finds security nominations too frequent can set the security agent's `min_urgency` to `high`, silencing `medium` and `low` nominations from that agent.
+
+## Nomination Types
+
+Five types classify the nature of the contribution:
+
+- **warning** — Something is wrong or risky (e.g., "Route without gate", "Aspect anchor drift detected")
+- **suggestion** — An improvement opportunity (e.g., "Consider extracting this into a shared utility")
+- **question** — The agent needs clarification (e.g., "Should this endpoint be public or require authentication?")
+- **offer** — The agent volunteers to do something (e.g., "I can write the test suite for this component")
+- **observation** — A neutral factual note (e.g., "This is the third time this pattern has been refactored")
+
+The `action_offered` field is used with `offer` type nominations. When the human accepts an offer, the agent can proceed to take the offered action.
+
+## Evidence
+
+Nominations can include evidence to support their claims. Each `NominationEvidence` item can reference a file, a symbol, a pattern from the agent's notebook, specific line numbers, or a textual description.
+
+Evidence transforms a nomination from opinion to argument. "This route needs a gate" is a suggestion. "This route needs a gate — see portal.yaml line 42 where all /api/payments routes require ^payment-authorized, and `#payment-service` has a documented aspect ~pci-compliance-required" is a compelling argument backed by project facts.
+
+## Storage
+
+Nominations and debates are stored as JSONL files alongside the event stream:
+
+- `.paradigm/events/nominations.jsonl` — All nominations, append-only
+- `.paradigm/events/debates.jsonl` — Detected debates (conflicting/complementary nomination groups)
+
+## Debate Detection
+
+When multiple agents nominate on the same event or overlapping symbols, a **debate** may form. Paradigm detects debates by checking for overlapping `triggered_by` event IDs or overlapping symbols across nominations within a time window.
+
+A `Debate` has two types:
+- **conflicting** — The nominations disagree (e.g., architect says "use SQL" while builder says "use NoSQL")
+- **complementary** — The nominations agree but add different perspectives (e.g., security says "add gate" and tester says "add test for gate")
+
+Debates are surfaced as a group rather than individual nominations, so the human sees the full picture. A debate includes:
+- `topic` — What the debate is about (derived from overlapping symbols/events)
+- `nominations` — IDs of the participating nominations
+- `overlap_symbols` — Symbols that triggered grouping
+- `overlap_events` — Events that triggered grouping
+- `resolution` — How it was resolved (chosen nomination, reason, resolved by human or consensus)
+
+## MCP Tools
+
+**`paradigm_ambient_nominations`** — View pending nominations. Supports filtering by agent, urgency, type, and whether nominations have been surfaced. Returns nominations sorted by urgency (critical first) then by relevance score.
+
+**`paradigm_ambient_engage`** — Engage with a nomination. Pass the nomination ID and a response (`accepted`, `dismissed`, `deferred`). If accepted, the nomination's `detail` and `evidence` are returned for the agent to act on. If dismissed, the nomination is marked as seen but not acted upon. If deferred, it is re-queued for later surfacing.
+
+The engage tool creates a feedback signal — over time, the pattern of accepted vs dismissed nominations helps calibrate attention thresholds. An agent whose nominations are consistently dismissed may need a higher threshold.

package/dist/university-content/notes/N-para-701-agent-notebooks.md

@@ -0,0 +1,131 @@
+---
+id: N-para-701-agent-notebooks
+title: 'Lesson 3: Agent Notebooks'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - notebook-entries-contain
+  - notebookentry-schema-id
+  - global-notebooks-paradigmnotebooks
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## What Notebooks Are
+
+Agent notebooks are curated snippet libraries distilled from experience. Where expertise scores track *how well* an agent knows a symbol, and transferable patterns track *general principles* the agent has learned, notebooks contain *specific, reusable knowledge* — code patterns, configuration snippets, troubleshooting procedures, and domain-specific techniques.
+
+A notebook entry for the security agent might contain a specific JWT validation middleware pattern for Express v5. A notebook entry for Mika (designer) might contain a font pairing recommendation with rationale. A notebook entry for Atlas (devops) might contain a zero-downtime migration pattern for Supabase.
+
+Notebooks bridge the gap between abstract principles ("always validate JWTs") and concrete implementation ("here is the exact middleware code that handles edge cases in Express v5").
+
+## The NotebookEntry Schema
+
+Every notebook entry follows the `NotebookEntry` interface:
+
+```typescript
+interface NotebookEntry {
+  id: string;              // e.g., "nb-auth-pattern-001"
+  context: string;         // When to apply this snippet
+  snippet: string;         // The reusable code/knowledge
+  provenance: {            // Where this came from
+    source: 'lore' | 'manual' | 'transfer';
+    loreEntryId?: string;  // If promoted from lore
+    originProject?: string;
+    createdBy?: string;
+  };
+  appliedCount: number;    // Times applied in orchestration
+  confidence: number;      // 0.0-1.0
+  concepts: string[];      // Concept tags for retrieval
+  tags: string[];          // Classification tags
+  created: string;         // ISO date
+  updated: string;         // ISO date
+}
+```
+
+The `context` field describes *when* to apply the snippet — not what the snippet is, but the situation that calls for it. For example: "When setting up JWT validation middleware in an Express v5 application with async route handlers." This context is what the retrieval system matches against.
+
+The `snippet` field contains the actual knowledge — code, configuration, a procedure, or a detailed explanation. It should be directly usable, not abstract guidance.
+
+The `provenance` field tracks where the entry came from: `lore` (promoted from a lore entry), `manual` (written directly by a human or agent), or `transfer` (copied from another agent's notebook). This matters for trust: a lore-promoted entry with a link to the original session has higher credibility than a manually created one.
+
+The `appliedCount` tracks how often this entry has been used in orchestration. Entries are sorted by `appliedCount` descending — frequently-applied entries surface first.
+
+## Storage: Global vs Project
+
+Notebooks live in two locations:
+
+**Global notebooks** at `~/.paradigm/notebooks/{agent-id}/` travel with the agent across all projects. An entry about JWT validation patterns is useful regardless of which project the security agent joins. Global notebooks are stored in the user's home directory (ring 2), so they persist even if a project is deleted.
+
+**Project notebooks** at `.paradigm/notebooks/{agent-id}/` contain knowledge specific to one project. An entry about the specific authentication architecture of project X should not bleed into project Y. Project notebooks are committed to the repository so they are shared with the team.
+
+When loading entries, the system reads global first, then project. If the same entry ID exists in both locations, the **project version wins** (override pattern). This allows a project to customize an agent's global knowledge for its specific needs.
+
+Each entry is stored as an individual YAML file named `nb-{concept}.yaml` (or more precisely, `{entry-id}.yaml`). The `nb-` prefix and `.yaml` extension are enforced by the `NOTEBOOK_PREFIX` and `NOTEBOOK_EXT` constants in the notebook loader.
+
+## Bootstrapping: Canonical Sources vs Learning Loop
+
+Notebook entries come from two pipelines:
+
+**Canonical bootstrapping** — When an agent is first created, Loid (forge) or a human seeds its notebook with foundational entries. The security agent might be bootstrapped with entries for OWASP Top 10 patterns, JWT best practices, and RLS policy templates. This gives the agent useful knowledge on day one without needing to learn from experience.
+
+**Learning loop promotion** — Over time, journal entries and lore entries that prove valuable are promoted into notebook entries. The `promoteFromLore()` function takes a lore entry ID, extracts the symbols and content, and creates a notebook entry with `provenance.source: 'lore'` and a link to the original entry. Sensei (trainer) drives this promotion — reviewing agent performance, identifying high-value learnings, and curating them into notebook entries.
+
+The learning loop pipeline is more valuable over time because it captures *project-specific* and *team-specific* patterns that canonical sources cannot predict. A canonical JWT entry is generic. A learning-loop entry that captures "In this project, JWT refresh tokens use the sliding window pattern with 15-minute windows because the mobile app has intermittent connectivity" is specific and actionable.
+
+## How buildProfileEnrichment() Uses Notebooks
+
+During orchestration, `buildProfileEnrichment()` accepts an optional array of notebook entries. The orchestrator matches entries by concept against the task's relevant symbols and injects the **top 5 entries by concept match** into the agent's prompt:
+
+```typescript
+function buildProfileEnrichment(
+  profile: AgentProfile,
+  relevantSymbols: string[],
+  notebookEntries?: Array<{ context: string; snippet: string; concepts: string[] }>,
+  // ...
+): string {
+  // ...
+  if (notebookEntries && notebookEntries.length > 0) {
+    parts.push('## Relevant Notebook Entries');
+    for (const nb of notebookEntries.slice(0, 5)) {
+      parts.push(`### ${nb.context}`);
+      parts.push(`Concepts: ${nb.concepts.join(', ')}`);
+      parts.push('```');
+      const snippet = nb.snippet.length > 300
+        ? nb.snippet.slice(0, 300) + '...' : nb.snippet;
+      parts.push(snippet);
+      parts.push('```');
+    }
+  }
+}
+```
+
+Notice the `slice(0, 5)` — only the top 5 entries are injected. This is a deliberate budget constraint. Notebook entries consume prompt tokens. Injecting 50 entries would blow the context budget. The top 5 are selected by relevance (concept match) and sorted by `appliedCount` (most-used first).
+
+Snippets longer than 300 characters are truncated with `...`. This prevents a single large entry from consuming the entire notebook budget. If an entry's full snippet is needed, the agent can use `paradigm_notebook_search` to retrieve it.
+
+## 10 High-Signal Entries > 100 Low-Signal Ones
+
+The quality bar for notebook entries matters enormously. Consider the token economics: each entry consumes ~100-300 tokens in the prompt. Five entries consume ~500-1,500 tokens. If those entries are high-signal (directly relevant, battle-tested, frequently applied), they provide immense value — the agent starts the task with proven patterns instead of reinventing them.
+
+If those entries are low-signal (vague, generic, rarely applied), they waste 500-1,500 tokens on noise that might actually mislead the agent. Worse, low-quality entries can actively degrade performance by injecting irrelevant patterns that the LLM tries to apply inappropriately.
+
+The `appliedCount` sorting is the primary quality signal. An entry that has been applied 15 times across 8 sessions is empirically useful. An entry that was created once and never applied is speculative. The `confidence` score provides a secondary signal, especially for new entries that have not yet accumulated an applied count.
+
+Sensei's role as curator is critical: reviewing entries, pruning low-value ones, merging duplicates, and updating stale patterns. A well-maintained notebook with 10 entries is vastly more valuable than an unmaintained one with 100.
+
+## MCP Tools for Notebooks
+
+- `paradigm_notebook_add` — Add a new entry. Requires `agentId`, `context`, `snippet`, `concepts`, and `scope` (global or project).
+- `paradigm_notebook_search` — Search entries by query string across context, snippet, and concepts.
+- `paradigm_notebook_list` — List all entries for an agent, optionally filtered by concepts or tags.
+- `paradigm_notebook_promote` — Promote a lore entry into a notebook entry via `promoteFromLore()`.