@a-company/paradigm 5.38.0 → 6.0.4

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

@@ -0,0 +1,119 @@
+---
+id: N-para-501-symphony-networking
+title: 'Symphony Networking: Cross-Machine Relay'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - hub-and-spoke-topology-one
+  - websocket-relay-watches
+  - pairing-6-digit-code
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Beyond Single-Machine Messaging
+
+Symphony 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?
+
+Symphony 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.
+
+## Hub-and-Spoke Topology
+
+One 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.
+
+```
+Machine A (Hub)                     Machine B (Spoke)
+┌─────────────────────┐           ┌─────────────────────┐
+│ ~/.paradigm/score/  │           │ ~/.paradigm/score/  │
+│   agents/projA/core │           │   agents/projB/core │
+│     inbox.jsonl     │◄────ws───►│     inbox.jsonl     │
+│     outbox.jsonl    │  :3939    │     outbox.jsonl    │
+└─────────────────────┘           └─────────────────────┘
+```
+
+The 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()`.
+
+## Pairing & Authentication
+
+Security is critical when connecting machines over a network. Symphony uses a pairing code + HMAC challenge-response protocol:
+
+1. The hub generates a 32-byte random secret and derives a **6-digit pairing code**
+2. The code is displayed on the hub's terminal
+3. The spoke connects and receives a `hello` frame with a random challenge nonce
+4. The user enters the code on the spoke terminal (or embeds it in the connection string)
+5. The spoke computes `HMAC-SHA256(challenge, SHA256(code))` and sends an `auth` frame
+6. The hub verifies the code and HMAC proof, then sends `auth_ok` with its agent list
+
+Pairing 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.
+
+## Two Connection Modes
+
+### LAN Pairing (same WiFi)
+
+```sh
+# Machine A (hub)
+paradigm symphony serve
+# Shows: Pairing Code: 847 291
+
+# Machine B (spoke)
+paradigm symphony join --remote 192.168.1.42:3939
+# Prompted for code
+```
+
+### Internet Direct Connect
+
+```sh
+# Machine A
+paradigm symphony serve --public
+# Shows connection string
+
+# Machine B
+paradigm symphony join --remote 73.162.44.103:3939#847291
+# Code embedded — no prompt
+```
+
+Internet mode requires port 3939 to be reachable (port forward, VPN, or SSH tunnel).
+
+## Trust Management
+
+Peers are managed via CLI commands:
+
+- `paradigm symphony peers` — List trusted peers with agent counts and last-seen times
+- `paradigm symphony peers revoke <id>` — Immediately disconnect and block reconnection
+- `paradigm symphony peers forget --force` — Clear all peer trust records
+
+Existing `trust.yaml` hard-deny patterns (`.env*`, `*.key`, `*.pem`) apply to remote file requests — the trust boundary extends across the network.
+
+## Relay Internals
+
+The `SymphonyRelay` class handles both server and client modes:
+
+- **Outbox watcher**: Polls every 2s, compares outbox line counts against stored positions, forwards new messages
+- **Deduplication**: Bounded `Set<string>` of message IDs (max 10,000) prevents duplicate delivery
+- **Keepalive**: Ping/pong every 30s with 10s pong timeout. Dead connections are auto-terminated
+- **Auto-reconnect**: Client mode uses exponential backoff (1s → 2s → 4s → ... → 30s max)
+- **Rate limiting**: 3 failed auth attempts from the same IP triggers a 60s cooldown
+
+## Remote Agent Visibility
+
+Remote agents appear throughout the Symphony CLI and MCP tools:
+
+- `paradigm symphony list` shows remote agents with a `(remote: peer-name)` tag
+- `paradigm symphony status` includes peer count and remote agent totals
+- `paradigm_symphony_status` MCP tool returns a `peers` array in its response
+- Platform UI `GET /api/symphony/peers` endpoint returns connected peer data
+
+Local MCP tools (`peek`, `poll`, `send`) work unchanged — they just read/write local files. The relay handles the network transport transparently.
+
+## Backward Compatibility
+
+If `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.

package/dist/university-content/notes/N-para-501-task-management.md

@@ -0,0 +1,100 @@
+---
+id: N-para-501-task-management
+title: Task Management
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - tasks-are-persistent
+  - auto-generated-ids-t-date-sequence
+  - three-priority-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Why Tasks Exist
+
+AI agent sessions are stateless. You can discuss a plan, identify five things that need doing, and then the session ends. The next session starts blank — those five items are gone. Sticky notes on a monitor do not help when your developer is a language model.
+
+Paradigm's Task Management system provides a persistent scratch pad that survives context windows. Tasks are lightweight, date-partitioned YAML entries that capture what needs doing, how urgent it is, and what project knowledge relates to it. They are not a full project management system — they are the missing short-term memory between sessions.
+
+The key difference from lore: lore records what happened (past tense). Tasks record what should happen (future tense). Together they form a complete timeline — memory of the past and intention for the future.
+
+## Anatomy of a Task
+
+Every task follows a consistent structure:
+
+```yaml
+id: T-2026-02-26-001
+blurb: "Add rate limiting to the /api/payments endpoint"
+priority: high
+status: open
+tags: [security, payments]
+related_lore: [L-2026-02-25-003]
+created: "2026-02-26T10:15:00Z"
+updated: "2026-02-26T10:15:00Z"
+```
+
+The `id` field is auto-generated: `T-{date}-{sequence}`, following the same date-partitioned pattern as lore entries. The `blurb` is the only required field — a concise description of what needs to be done. Everything else is optional but useful.
+
+Three priority levels exist: `high` (do this soon), `medium` (do this eventually), and `low` (nice to have). Tasks without an explicit priority default to `medium`.
+
+Three statuses track lifecycle: `open` (needs doing), `done` (completed), and `shelved` (parked for later — not abandoned, just deferred).
+
+## Storage: Date-Partitioned YAML
+
+Tasks live in `.paradigm/tasks/entries/` organized by creation date:
+
+```
+.paradigm/tasks/
+  entries/
+    2026-02-25/
+      T-2026-02-25-001.yaml
+      T-2026-02-25-002.yaml
+    2026-02-26/
+      T-2026-02-26-001.yaml
+```
+
+Date partitioning keeps directories small. Each task is a standalone YAML file, making them easy to read, edit, and version-control. The date in the path matches the date in the task ID.
+
+## The Five MCP Tools
+
+**`paradigm_task_create`** — Create a new task. The `blurb` field is required — a short description of what needs to be done. Optional fields include `priority` (high/medium/low), `tags` (for categorization and filtering), and `related_lore` (linking to lore entries that provide context). The task is written to the correct date directory with an auto-incremented ID and starts with status `open`.
+
+**`paradigm_task_list`** — List tasks with filters. Filter by `status` (open/done/shelved/all), `priority` (high/medium/low), or `tag`. Results are sorted by priority (high first) then by date (newest first). Without filters, it returns all open tasks.
+
+**`paradigm_task_update`** — Update any field on an existing task by ID. You can change the blurb, priority, status, tags, or related_lore. Only specified fields are modified — everything else is preserved.
+
+**`paradigm_task_done`** — Shorthand to mark a task as complete. Pass the task ID and the status changes to `done` with an updated timestamp. This is equivalent to `paradigm_task_update` with `status: done` but more ergonomic for the common case.
+
+**`paradigm_task_shelve`** — Shorthand to shelve a task for later. Pass the task ID and the status changes to `shelved`. Shelved tasks are not deleted — they remain searchable and can be reopened by updating their status back to `open`.
+
+## Session Recovery Integration
+
+The top 5 open tasks are automatically surfaced during session recovery. When a new session starts and the agent calls any Paradigm MCP tool, the recovery data includes the highest-priority open tasks alongside the usual breadcrumbs and checkpoint data.
+
+This means every session begins with awareness of outstanding work. The agent does not need to ask "what should I work on?" — the task list is already there, sorted by priority. This is the scratch-pad-that-survives pattern: write tasks in one session, see them in the next.
+
+## When to Create Tasks
+
+Create tasks when:
+- You identify work that cannot be completed in the current session
+- A code review surfaces follow-up items
+- You discover a bug or improvement while working on something else
+- The user mentions something that should be tracked but is not the current focus
+- A handoff needs to communicate specific next steps
+
+Do not use tasks for:
+- Tracking completed work (that is what lore is for)
+- Long-term roadmap items (use your project management tool)
+- Architectural decisions (use lore entries with type `decision`)
+
+Tasks are ephemeral intentions — they should be created quickly, completed or shelved promptly, and never allowed to accumulate into a backlog of hundreds. If your task list grows beyond 20-30 open items, it is time to triage: shelve the low-priority items and focus on what matters.

package/dist/university-content/notes/N-para-601-agent-renaissance.md

@@ -0,0 +1,121 @@
+---
+id: N-para-601-agent-renaissance
+title: Agent Manifest Renaissance
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - six-new-dimensions
+  - intrinsic-learning-optional
+  - five-collaboration-stances
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## Six New Dimensions
+
+Before v5.0, an agent profile (`AgentProfile`) had six core fields: `id`, `role`, `description`, `personality`, `expertise`, and `transferable` patterns. These covered identity and knowledge but said nothing about how agents observe, learn, contribute context, report work, collaborate, or decide when to speak up.
+
+v5.0 adds six new dimensions to the agent manifest, transforming it from a static identity card into a living behavioral specification:
+
+1. **Attention** (`AgentAttention`) — What this agent notices in the event stream
+2. **Learning** (`AgentLearning`) — How this agent improves over time
+3. **Context** (`AgentContext`) — What this agent contributes to shared context
+4. **Reporting** (`AgentReporting`) — How this agent logs work and learnings
+5. **Collaboration** (`AgentCollaboration`) — How this agent interacts with others
+6. **Nomination** (`AgentNomination`) — When this agent speaks up in ambient mode
+
+All six are optional on the `AgentProfile` interface for backward compatibility. Agents without these fields use sensible defaults or are treated as non-ambient (they do not participate in the observation-nomination loop).
+
+## Attention (AgentAttention)
+
+Covered in detail in the Attention & Scoring lesson. The attention dimension defines what the agent watches for: symbol patterns, file paths, semantic concepts, and signal types. The threshold determines sensitivity.
+
+Default configs exist for five standard roles via `DEFAULT_ATTENTION`. For example, the security agent defaults to watching all gate symbols (`^*`), auth-related components and paths, security concepts, and gate/route signals with a low threshold of 0.4.
+
+## Learning (AgentLearning)
+
+The learning dimension has two layers:
+
+**Intrinsic Learning** (`IntrinsicLearning`) — The agent's own drive to improve. This is optional for downloaded agents (they may or may not want to learn from user feedback). Four sub-sections:
+
+- **feedback** — When to ask for assessment: after work, after recommendations, from which agents, from humans. A security agent might configure `from_agents: ['architect', 'reviewer']` to weight peer feedback.
+- **adaptation** — How to adjust: `confidence_ema_alpha` (default 0.3) controls how quickly confidence scores move. `notebook_auto_promote` auto-promotes high-value journal entries. `pattern_extraction` extracts reusable patterns from learnings.
+- **reflection** — When to self-reflect: on failure, on correction, on debate loss. Each trigger records a journal entry with the relevant trigger type.
+- **calibration** — Accuracy targets: `target_accuracy` (default 0.85) is the goal. `overconfidence_alert` (default 0.15) triggers when estimated confidence exceeds actual accuracy by more than 15 points.
+
+**Platform Learning** (`PlatformLearning`) — Mandated for all marketplace agents. `feedback_required: true` is always set. Collects `work_outcome`, `helpfulness`, and `would_use_again` metrics. Feedback flows upstream anonymized. Aggregation is configurable per-offering, per-session, or per-project.
+
+## Context (AgentContext)
+
+The context dimension defines what the agent contributes to the composed context and what it requires to be loaded.
+
+**Contributions** — An array of `ContextContribution` items. Each specifies a `section` name (e.g., "Security Warnings"), inline `content` or a `content_ref` MCP resource URI, and a `priority` (high, medium, low). High-priority contributions are always included in composed context. Medium-priority contributions are included if token budget allows. Low-priority contributions are loaded on demand.
+
+**Requirements** — An array of `ContextRequirement` items specifying files or sections the agent needs loaded before it can work effectively. A security agent might require `portal.yaml` and the "gates" section of CLAUDE.md.
+
+## Reporting (AgentReporting)
+
+The reporting dimension controls how the agent captures its work and learnings in the knowledge streams.
+
+**Work Log Config** (`WorkLogConfig`):
+- `auto_record` — Automatically create work log entries when work completes
+- `structure` — Which structured fields to include: `task_ref`, `files_modified`, `symbols_touched`, `next_steps`, `blockers`
+- `destination` — Always `'work-log'`
+
+**Learning Journal Config** (`LearningJournalConfig`):
+- `auto_record` — Automatically record learning moments
+- `triggers` — Which events trigger journal entries: `correction_received`, `confidence_miss`, `pattern_discovered`
+- `destination` — Always `'journal'` (agent-private)
+
+## Collaboration (AgentCollaboration)
+
+The collaboration dimension defines how the agent interacts with others in multi-agent contexts.
+
+**Default Stance** (`CollaborationStance`) — One of five stances:
+- `lead` — Drives decisions, sets direction (architect default)
+- `advisory` — Offers guidance but does not drive (reviewer, security defaults)
+- `supportive` — Follows direction, executes (builder default)
+- `observer` — Watches but rarely acts
+- `peer` — Equal footing with no hierarchy
+
+**Per-Agent Relationships** — The `with` record allows overriding stance per agent. A builder might be `supportive` by default but `peer` with another builder.
+
+**Debate Config** — Controls debate behavior: `will_challenge` (will push back), `evidence_required` (must cite specific code/patterns), `escalate_to_human` (ask human if debate does not resolve).
+
+Default configs exist via `DEFAULT_COLLABORATION`. The architect defaults to `lead` stance with evidence-based challenging and human escalation. The builder defaults to `supportive` with `can_contradict: false` toward the architect.
+
+## Nomination (AgentNomination)
+
+The nomination dimension defines behavioral rules for self-nomination beyond the threshold check.
+
+**speak_when** — Conditions for speaking up:
+- `relevance_above` — Score threshold (default 0.6, mirrors attention threshold)
+- `urgency` — Always speak for specific urgency types: `security_risk`, `breaking_change`, `gate_missing`, `test_failure`, `performance_risk`
+- `asked_directly` — Always respond to direct questions (default: true)
+
+**quiet_when** — Conditions for staying silent:
+- `relevance_below` — Hard floor below which the agent never speaks
+- `another_agent_handling` — Stay quiet if another agent is already addressing this
+- `human_explicitly_excluded` — Respect human's explicit exclusion
+
+**contribution_style** — How the agent communicates:
+- `brief_first` — Start with a short summary, elaborate if asked
+- `cite_sources` — Reference specific code and patterns
+- `offer_action` — Offer concrete actions rather than just observations
+
+## buildProfileEnrichment
+
+The `buildProfileEnrichment` function composes all six dimensions into a prompt enrichment string for orchestration. It takes the agent profile, relevant symbols, optional notebook entries, and optional ambient context (recent decisions, journal insights, pending nominations).
+
+The output is structured markdown with sections for: Agent Identity, Expertise on Relevant Symbols, Transferable Patterns, Relevant Notebook Entries, Attention patterns, Collaboration stance, Nomination preferences, Recent Team Decisions, Transferable Insights, and Pending Nominations.
+
+This enrichment is injected into the agent's prompt during orchestration, giving it full awareness of its identity, capabilities, behavioral rules, and ambient context — all derived from the `.agent` file and the knowledge streams.

package/dist/university-content/notes/N-para-601-attention-scoring.md

@@ -0,0 +1,129 @@
+---
+id: N-para-601-attention-scoring
+title: Attention & Scoring
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - agentattention-has-four
+  - four-scoring-dimensions
+  - score-is-max-based
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## AgentAttention Patterns
+
+Every agent in the ambient system has an attention configuration — a set of patterns that define what the agent notices. Think of it as a personalized filter: events that match the agent's attention patterns are potentially relevant; events that do not match are noise.
+
+The `AgentAttention` interface has five fields:
+
+```typescript
+interface AgentAttention {
+  symbols?: string[];       // Symbol patterns (e.g., ["^*", "#*-middleware"])
+  paths?: string[];         // File path patterns (e.g., ["auth/**", "middleware/**"])
+  concepts?: string[];      // Semantic triggers (e.g., ["JWT", "RBAC", "injection"])
+  signals?: AttentionSignal[]; // Event type triggers (e.g., [{ type: "gate-added" }])
+  threshold?: number;       // Confidence threshold (default 0.6)
+}
+```
+
+**Symbols** use glob patterns to match against the `symbols` array on events. A security agent watching `["^*", "#*-auth", "#*-middleware"]` will match any gate symbol and any component whose name ends in `-auth` or `-middleware`.
+
+**Paths** use glob patterns to match against the `path` field on events. A builder watching `["src/**", "lib/**", "packages/**"]` matches any source file change.
+
+**Concepts** are semantic keywords matched against the event's `context`, `keywords`, and `type` fields (all lowercased). A tester watching `["test", "coverage", "assertion"]` will match events mentioning those terms.
+
+**Signals** match against the event's `type` field. A security agent with `signals: [{ type: 'gate-added' }, { type: 'route-created' }]` will match whenever a new gate or route appears in the stream.
+
+## Four Scoring Dimensions
+
+When an event enters the stream, each agent scores it against their attention patterns across four dimensions:
+
+**symbolMatch (0.0-1.0):** For each pattern in the agent's `symbols` array, check if any symbol in the event matches (using glob). If any match is found, `symbolMatch = 1.0`. If no agent symbols are defined or no event symbols exist, `symbolMatch = 0.0`.
+
+**pathMatch (0.0-1.0):** For each pattern in the agent's `paths` array, check if the event's `path` matches. If any match is found, `pathMatch = 1.0`. Binary: either a path matches or it does not.
+
+**conceptMatch (0.0-1.0):** The event's `context`, `keywords`, and `type` are joined into a lowercased text. Each concept in the agent's `concepts` array is checked for inclusion. The score is `matched / total_concepts`. If the agent watches 5 concepts and 3 appear in the event text, `conceptMatch = 0.6`.
+
+**signalMatch (0.0-1.0):** For each signal in the agent's `signals` array, check if the event's `type` matches. If any match, `signalMatch = 1.0`. Binary.
+
+## Max-Based Score
+
+The overall score is the **maximum** of the four dimensions:
+
+```typescript
+const score = Math.max(symbolMatch, pathMatch, conceptMatch, signalMatch);
+```
+
+This is a deliberate design choice. Using max (rather than average or weighted sum) means a single strong match is enough to trigger attention. A security agent does not need to match on all four dimensions — if the event mentions a gate symbol (`symbolMatch = 1.0`), that alone is sufficient even if the file path, concepts, and signals do not match.
+
+The alternative (averaging) would dilute strong signals: a perfect symbol match (1.0) with no other matches would average to 0.25, likely falling below the threshold. Max scoring ensures that domain-specific expertise in any single dimension is respected.
+
+## Threshold-Based Self-Nomination
+
+After scoring, the agent checks its threshold:
+
+```typescript
+const threshold = attention.threshold ?? 0.6;
+const shouldNominate = score >= threshold;
+```
+
+If the score meets or exceeds the threshold, the agent should self-nominate a contribution. If not, the agent stays quiet, and the `quietReason` field records why: `'below-threshold'`.
+
+The default threshold is 0.6, but different agent roles have different defaults based on their domain:
+
+| Role | Default Threshold | Rationale |
+|---|---|---|
+| architect | 0.5 | Broad awareness — should notice most structural changes |
+| builder | 0.7 | Focused — only speaks when directly relevant to implementation |
+| reviewer | 0.6 | Balanced — watches code quality and patterns |
+| tester | 0.5 | Broad — testing intersects all areas |
+| security | 0.4 | Most sensitive — should speak up early and often |
+
+A lower threshold means the agent speaks up more often (more false positives, fewer missed issues). A higher threshold means the agent speaks up less often (fewer false positives, more missed issues). Security uses 0.4 because the cost of missing a security issue far outweighs the cost of a false alarm.
+
+## scoreEventForAgent
+
+The `scoreEventForAgent` function ties everything together:
+
+```typescript
+function scoreEventForAgent(
+  event: StreamEvent,
+  agentId: string,
+  attention: AgentAttention
+): AttentionScore
+```
+
+It returns an `AttentionScore` with five fields:
+- `agentId` — Which agent evaluated this event
+- `score` — Overall relevance (0.0-1.0)
+- `breakdown` — The four dimension scores (`symbolMatch`, `pathMatch`, `conceptMatch`, `signalMatch`)
+- `shouldNominate` — Whether the score exceeds the agent's threshold
+- `quietReason` — Why the agent stayed quiet (if it did)
+
+The breakdown is valuable for debugging attention patterns. If an agent is not speaking up when expected, the breakdown shows which dimension scored low. If `symbolMatch = 0.0` but the event clearly involves the agent's domain, the agent's symbol patterns may need expanding.
+
+## DEFAULT_ATTENTION for Standard Roles
+
+Paradigm provides default attention configurations for five standard roles:
+
+**Architect** — Watches all flows (`$*`) and components (`#*`), concepts like `architecture`, `design`, `pattern`, `refactor`. Threshold 0.5.
+
+**Builder** — Watches source paths (`src/**`, `lib/**`, `packages/**`). Threshold 0.7.
+
+**Reviewer** — Watches concepts like `code quality`, `bug`, `smell`, `convention`. Threshold 0.6.
+
+**Tester** — Watches test paths (`**/*.test.*`, `**/*.spec.*`), concepts like `test`, `coverage`, `assertion`, and `error-encountered` signals. Threshold 0.5.
+
+**Security** — Watches gate symbols (`^*`), auth components (`#*-auth`, `#*-middleware`), auth paths (`auth/**`, `middleware/**`, `guards/**`), concepts like `permission`, `JWT`, `session`, `RBAC`, `XSS`, `injection`, and signals `gate-added` and `route-created`. Threshold 0.4.
+
+These defaults are overridable in the agent's `.agent` file via the `attention` field. A security agent working on a project with no web routes might raise its threshold to 0.6 and remove the path patterns.

package/dist/university-content/notes/N-para-601-context-composition.md

@@ -0,0 +1,146 @@
+---
+id: N-para-601-context-composition
+title: Context Composition
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - slim-claudemd-150
+  - paradigmcontextcompose-assembles-base
+  - agent-contributions-use
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## From Verbose to Slim
+
+Paradigm's CLAUDE.md historically contained everything an agent might need: logging rules, portal conventions, MCP workflow guidance, flow patterns, orchestration instructions, workspace configuration, and more. At its peak, the file was ~856 lines — loaded in full at the start of every session, consuming thousands of tokens regardless of whether the task involved logging, security, or lore.
+
+This approach has two problems. First, it wastes context window space. An agent working on test coverage does not need 200 lines of portal gate conventions. Second, it creates staleness — with all guidance in one file, updates to any topic require reading and understanding the entire file.
+
+v5.0 restructured this into a two-layer architecture: a slim CLAUDE.md (~150 lines) for universal orientation, plus 12 on-demand guidance resources for topic-specific depth.
+
+## The Slim CLAUDE.md
+
+The reduced CLAUDE.md contains only what every session needs:
+
+1. **Project Overview** — What this project is and which version of Paradigm it uses
+2. **Symbol System** — The 5 symbols (#, $, ^, !, ~) and their meanings
+3. **Conventions** — Naming, commit format, .purpose rules
+4. **Agent Onboarding** — What to call first (`paradigm_status`), what to check
+5. **Before Implementing** — Protocol search, ripple, gates check
+6. **Automatic Enforcement** — What the stop hook blocks
+7. **On-Demand Guidance** — Table of 12 guidance resources with their MCP URIs
+
+This provides enough context for any agent to orient itself and know where to find deeper guidance, without spending tokens on content irrelevant to the current task.
+
+## 12 Guidance Resources
+
+Guidance resources are served via MCP at `paradigm://guidance/{topic}`. Each resource generates its content on demand — it is not a static file but a function that produces the latest guidance.
+
+The 12 topics:
+
+| Topic | What It Covers |
+|---|---|
+| `logging` | Logger usage, symbol-to-method mapping by directory |
+| `portal` | Portal protocol, gate patterns, route declarations |
+| `mcp-workflow` | MCP tool orchestration, token budgets |
+| `flows` | Flow-first development, $flow documentation |
+| `orchestration` | Multi-agent orchestration, agent spawning |
+| `workspaces` | Multi-project symbol awareness |
+| `university` | Knowledge base, courses, PLSAT |
+| `calibration` | Confidence calibration, overconfidence alerts |
+| `checkpoints` | Session checkpoints, crash recovery |
+| `navigation` | Task recipes, navigation patterns |
+| `component-types` | Component hierarchy, type guidelines |
+| `troubleshooting` | Common issues, diagnostic steps |
+
+An agent working on portal.yaml calls `paradigm://guidance/portal` to get the full portal protocol. An agent setting up multi-project awareness calls `paradigm://guidance/workspaces`. This on-demand model means the agent pays the token cost only for the guidance it actually uses.
+
+## Agent Contributions Section
+
+Beyond the static guidance resources, composed context includes a dynamic **Agent Contributions** section built from active agents' `AgentContext.contributions`.
+
+For example, if a security agent is active and its profile includes:
+
+```yaml
+context:
+  contributions:
+    - section: "Security Warnings"
+      content: "New routes added in this session require ^authenticated gate minimum."
+      priority: high
+    - section: "Portal Conventions"
+      content_ref: "paradigm://guidance/portal"
+      priority: medium
+```
+
+...the composed context will include a "Security Warnings" section (always, because `priority: high`) and may include the full portal guidance (if token budget allows, because `priority: medium`).
+
+Contributions with `content_ref` instead of inline `content` are resolved lazily — the MCP resource is fetched only when the contribution is actually included in the composed context.
+
+## paradigm_context_compose
+
+The `paradigm_context_compose` tool assembles the full context for a session. It takes:
+
+- The active agent(s) and their profiles
+- The current task or focus area
+- Token budget constraints
+
+It produces a composed context string that includes:
+
+1. **Base CLAUDE.md content** — Universal orientation
+2. **Agent identity section** — From `buildProfileEnrichment`
+3. **High-priority contributions** — From all active agents' context contributions
+4. **Relevant guidance** — On-demand resources loaded based on the task
+5. **Ambient context** — Recent team decisions, transferable journal insights, pending nominations
+6. **Medium-priority contributions** — If token budget allows
+
+Low-priority contributions and unused guidance resources are omitted from the initial context but remain available via MCP resource URIs if the agent needs them mid-session.
+
+## The Full Loop: Journal to Context
+
+Here is where everything connects. Consider this sequence:
+
+1. **Session A**: Builder modifies `#payment-service`, makes a mistake with JWT token ordering, gets corrected by the human. The builder records a journal entry: `trigger: 'correction_received', insight: 'JWT refresh tokens must be validated before access tokens when both are present', transferable: true, pattern: { id: 'jwt-ordering', applies_when: 'validating multiple JWT types', correct_approach: 'Check refresh token first, then access token' }`.
+
+2. **Between sessions**: The journal entry is stored at `~/.paradigm/agents/builder/journal/`. The pattern is extracted as a transferable pattern.
+
+3. **Session B**: A different agent (or the same builder on a different project) starts work on an authentication module. `paradigm_context_compose` runs, loading the builder's profile. The `buildProfileEnrichment` function includes the transferable pattern and the journal insight in the "Transferable Insights" section of the composed context.
+
+4. **Result**: The agent in Session B sees the JWT ordering insight before writing any code, preventing the same mistake.
+
+This is the closed loop: DO (Session A work) -> RECORD (journal entry) -> ASSESS (attention scoring recognizes auth work in Session B) -> LEARN (pattern extracted) -> ADAPT (context composition includes the pattern) -> DO (Session B starts with the insight).
+
+## emitAndProcess
+
+The `emitAndProcess` function unifies event emission with nomination processing. When an event is emitted, it is simultaneously:
+
+1. Written to the event stream (JSONL file + memory buffer)
+2. Scored against all active agents' attention patterns
+3. For any agent exceeding its threshold, a nomination opportunity is created
+
+This single-call pattern ensures that no event is emitted without being evaluated for nominations. It prevents the race condition where an event is emitted but attention scoring happens too late to catch it.
+
+The function returns both the emitted event and any nominations that were generated, giving the caller full visibility into what happened.
+
+## Putting It All Together
+
+Ambient coordination is not a single feature — it is a system of interconnected capabilities:
+
+- **Knowledge streams** split lore into purpose-specific channels
+- **Events** capture every meaningful action in a structured format
+- **Attention** filters events to the right agents
+- **Nominations** let agents contribute without being asked
+- **Data sovereignty** ensures data stays where it belongs
+- **Agent renaissance** gives agents the behavioral vocabulary to participate
+- **Context composition** closes the loop by feeding learnings back into future sessions
+
+Each piece is independently useful, but together they create a system that gets smarter with every session — not because any single component is intelligent, but because the loop never breaks.