@a-company/paradigm 5.37.11 → 6.0.2

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.

package/dist/university-content/notes/N-para-601-data-sovereignty.md

@@ -0,0 +1,140 @@
+---
+id: N-para-601-data-sovereignty
+title: Data Sovereignty
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - four-trust-rings
+  - all-data-is
+  - data-policyyaml-configures-observation
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## The Local Brain Principle
+
+All data produced during agent work is project-locked by default. This is not a policy choice that requires opt-in — it is the architectural default. No data leaves the project unless the user explicitly configures it to do so. This principle is called the "local brain" — every project has its own self-contained intelligence that never leaks.
+
+The reason is trust. When an agent records a learning journal entry about your payment processing logic, that entry should not appear in another user's project. When a work log captures which files were modified, those file paths should not flow to an analytics dashboard without consent. Data sovereignty means the user controls every boundary their data crosses.
+
+## Trust Rings
+
+Data classification uses four concentric trust rings, each expanding the boundary of who can see the data:
+
+**Ring 1: Project-Locked** — Data never leaves the project directory. Work log entries, event stream, nominations, and team decisions are project-locked by default. Storage lives in `.paradigm/` within the project.
+
+**Ring 2: User-Scoped** — Data travels across the user's own projects but not beyond. Learning journal entries are user-scoped — an agent's insights from project A are available when working on project B, but only for the same user. Storage lives in `~/.paradigm/`.
+
+**Ring 3: Creator-Upstream** — Anonymized, aggregate data flows to agent creators (for agents installed from a marketplace). Only high-level metrics like task type, outcome, and helpfulness rating — never code, file paths, symbol names, or conversation content. This ring requires explicit opt-in.
+
+**Ring 4: Network-Public** — Fully anonymized, aggregated statistics shared publicly. Only `aggregated_task_success_rates` and `anonymized_pattern_frequency`. Requires explicit opt-in. Nothing in this ring can identify a project, user, or agent.
+
+The rings are ordered: data at ring 1 can never reach ring 3 without passing through ring 2 first. Each ring expansion requires a policy declaration.
+
+## data-policy.yaml Format
+
+The data policy is configured in `.paradigm/data-policy.yaml`:
+
+```yaml
+version: "1.0"
+default_ring: project-locked
+
+observation:
+  allow:
+    - "src/**"
+    - ".paradigm/**"
+    - "portal.yaml"
+  deny:
+    - ".env*"
+    - "**/*.key"
+    - "**/*.pem"
+    - "**/secrets/**"
+
+streams:
+  work_log:
+    ring: project-locked
+    allow_content: [file_paths, symbol_names, outcome]
+    deny_content: [code_snippets, file_contents, diff_content]
+  learning_journal:
+    ring: user-scoped
+    allow_content: [pattern_descriptions, confidence_adjustments, approach_descriptions]
+    deny_content: [code_snippets, file_contents, symbol_names_with_context]
+    redaction:
+      - pattern: "\\b[A-Z_]{2,}_KEY\\b"
+      - pattern: "password|secret|token"
+  team_decisions:
+    ring: project-locked
+    allow_content: [rationale, alternatives, symbol_references]
+    deny_content: [implementation_details]
+
+upstream:
+  ring: creator-upstream
+  allowed: [task_type, outcome, helpfulness, duration_bucket, error_category]
+  denied: [code_of_any_kind, file_paths, symbol_names, conversation_content, user_identity]
+
+network:
+  ring: network-public
+  opt_in: false
+  if_opted_in: [aggregated_task_success_rates, anonymized_pattern_frequency]
+```
+
+## Observation Rules
+
+Observation rules control which files agents can observe. The `allow` list defines glob patterns for permitted paths. The `deny` list defines patterns that are always blocked — deny overrides allow.
+
+The default denies `.env*`, `*.key`, `*.pem`, and `**/secrets/**`. These patterns catch common secret file locations. The deny list is **additive** when merging user policy over defaults — you can add deny patterns but never remove the built-in ones.
+
+## Stream Content Rules
+
+Each knowledge stream has its own content rules defining what categories of content are allowed or denied:
+
+**14 content categories:** `file_paths`, `symbol_names`, `symbol_names_with_context`, `outcome`, `pattern_descriptions`, `confidence_adjustments`, `approach_descriptions`, `rationale`, `alternatives`, `symbol_references`, `code_snippets`, `file_contents`, `diff_content`, `implementation_details`, `architectural_decisions`.
+
+The work log allows `file_paths` and `symbol_names` (needed for standup context) but denies `code_snippets` (no raw code in work logs). The learning journal allows `pattern_descriptions` (abstract learnings) but denies `symbol_names_with_context` (no project-specific details in the cross-project journal).
+
+**Redaction patterns** use regex to scrub sensitive content before it is stored. The default learning journal redaction catches environment variable names (`\b[A-Z_]{2,}_KEY\b`) and common secret terms (`password|secret|token`). Matches are replaced with `[REDACTED]`.
+
+## Per-Agent Overrides
+
+The `agent_overrides` section allows per-agent policy customization:
+
+```yaml
+agent_overrides:
+  security:
+    observation:
+      allow: ["src/**", ".paradigm/**", "portal.yaml", ".env.example"]
+    learning_journal:
+      deny_content: [code_snippets, file_contents, diff_content, implementation_details]
+    upstream:
+      opt_in: false
+```
+
+This gives the security agent slightly broader observation (it can read `.env.example` to verify it matches the template) while restricting its journal content and disabling upstream feedback.
+
+## Enforcement Boundaries
+
+The data policy is enforced at eight boundaries:
+
+1. **event-emission** — Before an event enters the stream, check if the path is observable
+2. **attention-filtering** — Agents only score events for paths they are allowed to observe
+3. **work-log-recording** — Content is filtered and redacted before writing to the work log
+4. **journal-recording** — Content is filtered and redacted before writing to the journal
+5. **cross-project-transfer** — Journal entries marked `transferable` are checked against ring 2 rules
+6. **upstream-feedback** — Data flowing to agent creators is checked against ring 3 rules
+7. **network-aggregation** — Data flowing to the network is checked against ring 4 rules
+8. **notebook-promotion** — Journal entries promoted to notebook are checked against content rules
+
+Every enforcement action is auditable. The `AuditEntry` interface captures who, when, what boundary, what data category, and what action was taken (allowed, filtered, redacted, or blocked).
+
+## The Merge Rule
+
+When a user provides a `data-policy.yaml`, it is merged over the `DEFAULT_DATA_POLICY` with a critical rule: **deny lists are additive, never replacing**. If the default denies `.env*` and the user's policy does not mention `.env*`, the deny still applies. The user can add more deny patterns but cannot remove built-in protections. Allow lists, by contrast, can be fully replaced.

package/dist/university-content/notes/N-para-601-event-stream.md

@@ -0,0 +1,126 @@
+---
+id: N-para-601-event-stream
+title: The Event Stream
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - streamevent-has-12
+  - 12-event-types
+  - 6-event-sources
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## How Events Are Produced
+
+Every meaningful action in a Paradigm session produces an event. When an agent modifies a file, the post-write hook emits a `file-modified` event. When an MCP tool is called, a `symbol-queried` or `gate-checked` event fires depending on the tool. When compliance issues are detected, a `compliance-violation` event captures the details. These events flow into a shared stream that all agents can observe.
+
+The event stream is the nervous system of ambient coordination. Without it, agents are blind to each other's actions. With it, a security agent can notice that a new route was created without a gate, a tester can see that a new component was added without test coverage, and a reviewer can observe that a complex flow was modified without documentation updates.
+
+## StreamEvent Anatomy
+
+Every event follows the `StreamEvent` interface with 12 fields:
+
+```typescript
+interface StreamEvent {
+  id: string;          // Unique ID (e.g., "ev-1710937200000-4821")
+  type: EventType;     // Classification (12 types)
+  source: EventSource; // Origin (6 sources)
+  timestamp: string;   // ISO 8601
+  path?: string;       // File path (if applicable)
+  symbols?: string[];  // Paradigm symbols referenced
+  keywords?: string[]; // Semantic keywords extracted
+  context?: string;    // Brief context snippet
+  agent?: string;      // Agent that produced this event
+  tool?: string;       // MCP tool name (if from tool call)
+  severity?: string;   // info, warning, error, critical
+  data?: Record<string, unknown>; // Structured metadata
+}
+```
+
+**Event IDs** are generated from the current timestamp plus a random 4-digit suffix: `ev-{timestamp}-{rand}`. This ensures uniqueness without coordination.
+
+**Event Sources** identify where the event originated:
+- `post-write-hook` — File was written, hook detected the change
+- `mcp-tool-call` — An MCP tool was invoked
+- `stop-hook` — Session end triggered an event
+- `conversation` — Event derived from conversation context
+- `agent-action` — Agent explicitly emitted an event
+- `error` — An error occurred during processing
+
+**Event Types** classify what happened. Twelve types cover the full range of project activity:
+
+| Type | When It Fires |
+|---|---|
+| `file-modified` | A source file was changed |
+| `symbol-queried` | A symbol was looked up via search/navigate/ripple |
+| `gate-checked` | A gate (^) was evaluated or referenced |
+| `compliance-violation` | A habit, hook, or policy check failed |
+| `concept-mentioned` | A semantic concept appeared in context |
+| `work-completed` | A unit of work finished (pass/fail/partial) |
+| `decision-made` | A team decision was recorded |
+| `error-encountered` | An error was caught during processing |
+| `route-created` | A new API route was added |
+| `gate-added` | A new gate was added to portal.yaml |
+| `flow-modified` | A flow definition was changed |
+| `test-result` | A test suite reported results |
+
+## JSONL Storage
+
+Events are stored as append-only JSONL (one JSON object per line) at `.paradigm/events/stream.jsonl`. The append-only format is chosen for performance — writing one line is cheaper than reading, modifying, and rewriting a file.
+
+The stream is bounded by `DEFAULT_MAX_EVENTS` (1000). When the file exceeds ~500KB (a rough proxy for 1000 events), the `pruneIfNeeded` function reads the file, keeps only the most recent 1000 lines, and rewrites it. This ensures the stream does not grow unbounded while preserving recent history.
+
+Events are also held in a memory buffer (`memoryStream`) for fast access during the current session. The memory buffer is independently bounded to 1000 events. Even if file I/O fails, the memory stream continues to function — file write failure is non-fatal.
+
+## emitEvent
+
+The `emitEvent` function is the single entry point for producing events:
+
+```typescript
+emitEvent(rootDir, {
+  type: 'file-modified',
+  source: 'post-write-hook',
+  path: 'src/auth/middleware.ts',
+  symbols: ['#auth-middleware', '^authenticated'],
+  keywords: ['authentication', 'JWT'],
+  context: 'Modified JWT validation logic',
+});
+```
+
+The function auto-generates the `id` and `timestamp`, appends to both the memory buffer and the JSONL file, and prunes if the file is oversized. It returns the complete `StreamEvent` with all fields populated.
+
+## queryEvents
+
+The `queryEvents` function reads events from disk (falling back to the memory buffer on read failure) and supports five filters:
+
+- `type` — Filter by event type (e.g., `'file-modified'`)
+- `source` — Filter by event source (e.g., `'mcp-tool-call'`)
+- `symbol` — Filter by a specific symbol in the event's `symbols` array
+- `agent` — Filter by the agent that produced the event
+- `since` — Only events after this ISO timestamp
+- `limit` — Maximum number of events to return
+
+Results are sorted by timestamp descending (most recent first). This ordering is intentional — in ambient coordination, recent events are almost always more relevant than older ones.
+
+## Event Stream Configuration
+
+The `EventStreamConfig` interface allows fine-grained control:
+
+- `enabled` — Master switch for ambient coordination (default: true in v5.0 projects)
+- `max_events` — Maximum events retained (default: 1000)
+- `event_ttl_seconds` — Time-to-live for events (default: 3600 = 1 hour)
+- `emit` — Whitelist of event types to produce (if set, only these types fire)
+- `suppress` — Blacklist of event types to silence (overrides emit)
+- `storage` — `'memory'` (in-process only) or `'file'` (JSONL persistence)
+
+For projects that do not need ambient coordination, setting `enabled: false` turns off event emission entirely. For projects that need it but want to reduce noise, the `suppress` list can silence high-frequency event types like `symbol-queried` while preserving important ones like `compliance-violation` and `gate-added`.