@a-company/paradigm 5.37.11 → 6.0.2

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

@@ -0,0 +1,104 @@
+---
+id: N-para-501-session-intelligence
+title: Session Intelligence
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - four-checkpoint-phases
+  - breadcrumbs-auto-track-every
+  - paradigmsessionrecover-restores-last
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## The Session Problem
+
+AI agent sessions are ephemeral. When a session ends — whether by completion, crash, context exhaustion, or human interruption — everything the agent knew vanishes. The next session starts blank, with no memory of what was explored, decided, or partially implemented. Session Intelligence solves this with checkpoints, breadcrumbs, and a global brain that persists knowledge across sessions and even across projects.
+
+## Session Checkpoints
+
+Checkpoints are deliberate snapshots saved at phase transitions. There are four phases:
+
+| Phase | When to Checkpoint | What to Capture |
+|---|---|---|
+| `planning` | After reading requirements, before coding | Plan, approach, key decisions |
+| `implementing` | After starting code changes | Modified files, symbols touched, decisions made |
+| `validating` | After implementation, before tests | All modified files, test plan |
+| `complete` | Task finished | Summary, final file list |
+
+Create a checkpoint with `paradigm_session_checkpoint`:
+
+```
+paradigm_session_checkpoint({
+  phase: "implementing",
+  context: "Adding JWT auth middleware — RS256 signing, httpOnly refresh tokens",
+  modifiedFiles: ["src/middleware/auth.ts", "src/handlers/refresh.ts"],
+  symbolsTouched: ["#auth-middleware", "^authenticated"],
+  decisions: ["RS256 over HS256 for public key verification"]
+})
+```
+
+Only `phase` and `context` are required — everything else is optional. The context field should be a concise 1-3 sentence summary of your current state of mind. Think of it as answering "if I were teleported into this session right now, what would I need to know?"
+
+Checkpoints are stored in `.paradigm/session-checkpoint.json` and auto-expire after 7 days.
+
+## Breadcrumb Tracking
+
+While checkpoints are deliberate, breadcrumbs are automatic. Every MCP tool call generates a breadcrumb recording the timestamp, tool name, symbol being modified (if applicable), and a human-readable summary. Breadcrumbs are stored in `.paradigm/session-breadcrumbs.json` with a maximum of 50 entries (auto-rotating — oldest dropped when full).
+
+Breadcrumbs capture the narrative of a session: "searched for payment symbols → checked ripple on #payment-service → read auth middleware → modified #auth-handler → created ^refund-eligible gate." This trail lets the next session understand not just what was done but the reasoning path.
+
+## Session Recovery
+
+Recovery is the payoff. Call `paradigm_session_recover` (or let it happen automatically — recovery data is surfaced on your first Paradigm tool call in a new session) to get:
+
+- **breadcrumbs** — The last session's tool call trail
+- **lastCheckpoint** — The most recent checkpoint with phase, context, and details
+- **symbolsModified** — All symbols that were changed
+- **recentActivity** — A human-readable summary of what happened
+
+This is crash recovery for AI agents. If a session dies at 87% context with half-finished auth middleware, the next session immediately knows: phase was `implementing`, auth middleware was being added, RS256 was chosen, these files were modified, and tests still need to be written.
+
+## The Global Brain
+
+Session Intelligence extends beyond individual projects through the Global Brain at `~/.paradigm/`. This user-level directory stores:
+
+- **Global wisdom** — Antipatterns and decisions that apply everywhere (e.g., "never use HS256 for JWT signing in production")
+- **Global habits** — Behavioral overrides that apply to all projects
+- **Cross-project practice events** — Compliance data aggregated across projects
+
+The distinction between project scope and global scope is important:
+
+| Scope | Location | Applies To | Example |
+|---|---|---|---|
+| Project | `.paradigm/` | This project only | "Use Redis for caching in this app" |
+| Global | `~/.paradigm/` | All projects | "Always check fragility before modifying critical symbols" |
+
+## Wisdom Promotion
+
+When a project-local wisdom entry proves universally valuable, promote it to global scope with `paradigm_wisdom_promote`. This copies the entry from `.paradigm/wisdom/` to `~/.paradigm/wisdom/`, making it available in every project.
+
+For example, if a team discovers that "always wrap Express v5 async middleware in try-catch" prevents errors across multiple projects, promoting this wisdom means every future project session gets this advice automatically when touching Express middleware.
+
+## Handoff Persistence
+
+When context usage exceeds 80-85%, `paradigm_session_health` recommends a handoff. `paradigm_handoff_prepare` creates a structured handoff document with: summary of work done, modified files, symbols touched, next steps, and open questions. This document is stored alongside session data so the receiving session can `paradigm_session_recover` and pick up exactly where the previous session left off.
+
+The handoff is not just a note — it is a contract between sessions. The outgoing session declares what was done and what remains. The incoming session validates against the actual file state and continues.
+
+## Best Practices
+
+- Checkpoint at every phase transition — the cost is ~100 tokens, the value is crash recovery
+- Write `context` as if briefing a stranger with no prior knowledge
+- Promote wisdom that survives 3+ projects to global scope
+- Use handoffs proactively at 80% context, not reactively at 95%
+- Let breadcrumbs accumulate naturally — don't try to manage them manually

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

@@ -0,0 +1,120 @@
+---
+id: N-para-501-symphony-a-mail
+title: 'Symphony: Multi-Agent Messaging with The Score'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - the-score-is
+  - agent-identity-is
+  - mailbox-protocol-uses
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Agents Need to Talk
+
+Until now, every Paradigm agent has worked in isolation. A Claude Code session modifying the backend has no awareness of what the session working on the frontend is doing. Two developers on the same team, each with their own AI assistant, have no way for those assistants to coordinate — even when they are working on the same project at the same time.
+
+Symphony changes this. It is Paradigm's multi-agent, multi-human collaborative intelligence layer. And its foundation is The Score: a lightweight, file-based messaging protocol that gives every Claude Code session its own mailbox.
+
+## The Metaphor: Email for AI Agents
+
+The Score works exactly like email. Each agent has an identity, an inbox, and an outbox. Messages are delivered as JSONL files on the filesystem. Agents poll for new messages on a timer. There is no persistent server, no WebSocket connection, and no cloud dependency. If two agents are running on the same machine, they can message each other through nothing more than file reads and writes.
+
+This simplicity is deliberate. The Score is the CLI-only foundation of Symphony — it works with zero dependencies beyond the Paradigm CLI. No Conductor, no Sentinel, no network configuration. The only requirement is that agents are running on the same machine (or connected via a lightweight TCP relay for cross-machine scenarios).
+
+## Agent Identity and Discovery
+
+Every Claude Code session that participates in The Score has a stable identity. The identity is derived from the project directory and the agent's role — for example, `a-paradigm/backend` or `a-kamiki/frontend`. This deterministic naming means the same project opened in the same context always gets the same identity, even across session restarts.
+
+When you run `paradigm symphony join`, the CLI discovers all Claude Code sessions on the current machine and connects them into a mail network. Each session gets a mailbox directory at `~/.paradigm/score/agents/{agent-id}/` containing four files:
+
+- **`inbox.jsonl`** — Messages waiting for this agent, one per line, append-only
+- **`outbox.jsonl`** — Replies from this agent, append-only
+- **`ack.json`** — The ID of the last acknowledged message (for garbage collection)
+- **`identity.json`** — Agent ID, project, role, PID, and session start time
+
+The JSONL format — one JSON object per line — makes appending atomic and parsing trivial. No file locking, no corruption risk from concurrent writes, no binary format to decode.
+
+## Messaging and Threading
+
+Messages in The Score carry structured metadata beyond plain text. Every message has an **intent** that classifies its purpose:
+
+| Intent | Meaning |
+|---|---|
+| `question` | Asking for information from other agents |
+| `context` | Providing background or context |
+| `proposal` | Proposing an action or fix |
+| `action` | Announcing an action the agent took |
+| `decision` | Recording a decision |
+| `alert` | Forwarding a Sentinel alert |
+| `approval` / `rejection` | Responding to a proposal |
+| `handoff` | Transferring responsibility to another agent |
+| `fileRequest` | Requesting a file from another agent |
+| `fileDelivery` | Delivering a requested file |
+
+Intents serve two purposes. First, they give the receiving agent structured context about what kind of response is expected — a question needs an answer, a proposal needs approval or rejection, a decision needs acknowledgment. Second, they feed into Lore: when a message has `intent: decision`, Symphony can automatically record it as a lore entry.
+
+Messages belong to **threads**. A thread starts when the first message on a topic is sent (with no `parentId`). Subsequent replies reference the thread root, building a conversation tree. Thread state is tracked in `~/.paradigm/score/threads/{thread-id}.json`, which records the topic, participants, message count, and last activity timestamp.
+
+## The File Pipeline
+
+Agents often need to share files — a type definition, an API contract, a configuration file. The Score's file pipeline enables this with a critical security constraint: **every file transfer requires explicit human approval**.
+
+The flow works like this: Agent A sends a `fileRequest` message specifying the file path, a reason, and the target agent. The request appears in the owning human's terminal (via `paradigm symphony requests`). The human reviews and either approves, denies, or approves with redaction (stripping sensitive lines). Only after human approval does the file content get written to the requester's inbox.
+
+Trust configuration lives in `~/.paradigm/score/trust.yaml`. You can define auto-approve patterns for trusted users (`docs/**`, `*.md`) and never-approve patterns for sensitive files (`.env*`, `*.key`, `*.pem`, `**/secrets/**`). The never-approve list is enforced absolutely — even clicking approve on a `.env` file will be denied by the system. File requests expire after one hour without action, and all transfers are logged.
+
+## /loop: The Agent Heartbeat
+
+The glue that makes The Score work is `/loop`. Each Claude Code session runs `/loop 10s paradigm_symphony_poll`, which polls the inbox every 10 seconds for new messages. The `paradigm_symphony_poll` MCP tool reads `inbox.jsonl`, formats messages as structured prompts the agent can reason about, and suggests actions.
+
+Without `/loop`, messages would accumulate in the inbox with nobody reading them. The loop is the heartbeat — it keeps agents responsive. When an agent processes a message and replies via `paradigm_symphony_send`, the reply goes to `outbox.jsonl`. A mail router (or Conductor, in later phases) picks up outbox messages and delivers them to the appropriate inbox files.
+
+The convenience command `paradigm symphony join` combines registration and loop setup in one step — it registers the session's identity and starts the polling loop automatically.
+
+## Thread Resolution and Lore Integration
+
+Conversation threads are not meant to live forever. When a thread reaches a conclusion, any participant (human or agent) can resolve it with `paradigm symphony resolve <thread-id>`. Resolution triggers an automatic lore entry that captures the full conversation: topic, participants, decisions made, actions taken, and symbols discussed.
+
+This is the bridge between ephemeral conversation and permanent project memory. A 15-minute exchange between three agents about a serialization bug becomes a searchable lore entry tagged with the relevant symbols and arc. The next developer encountering a similar issue can find the conversation, the decision, and the fix — all linked together.
+
+## CLI Commands
+
+The `paradigm symphony` command group provides the complete human interface:
+
+- `paradigm symphony whoami` — Show this agent's identity and linked peers
+- `paradigm symphony list` — List all known agents with status (awake/asleep) and location
+- `paradigm symphony join` — Discover and connect Claude Code sessions on this machine
+- `paradigm symphony join --remote <ip>` — Connect to a remote machine's mail server
+- `paradigm symphony send "message"` — Broadcast to all linked agents
+- `paradigm symphony send --to <agent> "message"` — Direct message to a specific agent
+- `paradigm symphony send --thread <id> "message"` — Reply to an existing thread
+- `paradigm symphony read` — Show unread messages
+- `paradigm symphony threads` — List active threads
+- `paradigm symphony resolve <id>` — Resolve a thread, creating a lore entry
+- `paradigm symphony status` — Network overview (agents, threads, unread count)
+
+For the file pipeline: `paradigm symphony request`, `paradigm symphony requests`, `paradigm symphony approve`, and `paradigm symphony deny`.
+
+## MCP Tools for Agent Participation
+
+Six MCP tools power agent-side Symphony participation:
+
+- **`paradigm_symphony_poll`** — The heartbeat. Reads inbox, returns formatted messages and thread summaries. Called by `/loop`.
+- **`paradigm_symphony_send`** — Send a message with intent, text, optional symbols, diff, or decision. Writes to outbox.
+- **`paradigm_symphony_status`** — Overview of the local network: agents, threads, Sentinel endpoint.
+- **`paradigm_symphony_thread`** — Get full context of a conversation thread with messages, participants, and extracted decisions.
+- **`paradigm_symphony_request_file`** — Request a file from another agent. Returns immediately with `pending` status; delivery arrives via future poll.
+- **`paradigm_symphony_approve_file`** — Approve or deny a pending file request after human confirmation.
+
+These tools compose naturally with existing Paradigm workflows. An agent can poll for messages, discover a question about `#payment-serializer`, call `paradigm_ripple` to check impact, and respond with full context — all within a single `/loop` cycle.

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.