@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-401-agent-interop.md

@@ -0,0 +1,87 @@
+---
+id: N-para-401-agent-interop
+title: Agent Interoperability
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - agentsmd-is-a
+  - llmstxt-is-a
+  - agentsmd-contains-instructions
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## AGENTS.md and llms.txt
+
+Paradigm generates two standard files that make projects accessible to any AI agent, regardless of which IDE or platform is used.
+
+### AGENTS.md — Universal Agent Instructions
+
+AGENTS.md is a cross-IDE standard backed by Google, OpenAI, Cursor, and others. It is a pure Markdown file at the repo root containing everything an AI agent needs to be productive:
+
+- **Symbol system** — the five operational symbols and conventions
+- **MCP tools reference** — when to use each tool and what it returns
+- **Workflow protocol** — before/after task checklists
+- **Commit conventions** — format with Symbols: trailer
+- **Session recovery** — how to pick up where a previous agent left off
+- **Habits compliance** — behavioral expectations at each workflow stage
+- **Lore recording** — when and how to record project history
+- **Session checkpoints** — crash recovery protocol
+
+Regenerate with: `paradigm sync agents`
+
+Paradigm enriches AGENTS.md with sections that most projects don't include — habits, lore recording, checkpoint protocol, and llms.txt reference. This gives agents a richer behavioral contract than bare instructions.
+
+### llms.txt — LLM-Readable Project Summary
+
+The llms.txt standard provides a plain-text project summary optimized for LLM consumption. Unlike AGENTS.md (which contains instructions), llms.txt contains facts:
+
+- Project name and overview
+- Symbol table (prefixes, names, descriptions)
+- Key files from navigator.yaml
+- Defined flows and their triggers
+- Gates and protected routes
+- Conventions
+
+Regenerate with: `paradigm sync-llms`
+
+llms.txt is useful for RAG pipelines, chat interfaces, and any context where a quick project overview is needed without the full instruction set.
+
+### When to Use Which
+
+| File | Purpose | Audience | Content |
+|------|---------|----------|---------|
+| AGENTS.md | Agent instructions | AI agents working on the repo | How to behave, tools to use, conventions to follow |
+| llms.txt | Project summary | Any LLM consuming project info | What the project is, what exists, how it is structured |
+| CLAUDE.md | Claude-specific instructions | Claude Code / Claude API | Superset of AGENTS.md with Claude-specific features |
+
+All three can coexist. `paradigm sync --all` regenerates AGENTS.md alongside other IDE files. `paradigm sync-llms` handles llms.txt separately because it is not IDE-specific.
+
+## Enhanced MCP Tool Descriptions
+
+Every MCP tool description now includes three pieces of information that help agents make better decisions:
+
+1. **What it does** — the core functionality
+2. **What it returns** — the shape of the response data
+3. **Token cost** — approximate cost in tokens (~100 to ~400)
+
+This information is embedded directly in the tool description string, so agents can evaluate tool choice before calling. For example, an agent deciding between `paradigm_search` (~150 tokens) and reading 5 files (~2500 tokens) can make an informed cost/benefit decision.
+
+## The Fresh Context Principle
+
+When agents are spawned in isolation (via `paradigm_orchestrate_inline` or IDE task tools), they start with a blank context window. They must orient themselves before working. Paradigm's interop files solve this:
+
+1. **Agent reads AGENTS.md** — learns the symbol system, tools, and workflow
+2. **Agent calls `paradigm_session_recover`** — gets previous session breadcrumbs
+3. **Agent calls `paradigm_navigate` with context intent** — finds relevant code
+
+This three-step orientation costs ~500 tokens total and gives the agent full context. Without these files, the agent would need to read dozens of source files to achieve the same understanding.

package/dist/university-content/notes/N-para-401-agent-roles.md

@@ -0,0 +1,107 @@
+---
+id: N-para-401-agent-roles
+title: Agent Roles & Facets
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - three-tier-hierarchy
+  - compliance-symbol-bookkeeper
+  - 11-component-to-aspect-ratio
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## The Agent Roster: Core Team + Specialists
+
+Paradigm ships with 50+ agent definitions (the exact count evolves; see PARA 701). You do not use all of them — `paradigm shift` auto-selects a project roster based on your detected project type. But understanding the hierarchy helps you work with the orchestrator effectively.
+
+### Three-Tier Hierarchy
+
+**Core agents** are available in every project. The minimum core team is seven roles (architect, builder, reviewer, security, tester, documentor, ftux), with three more (advocate, compliance, debugger) activating based on project profile. These are the backbone of orchestration:
+
+| Role | Model Tier | Purpose |
+|------|-----------|---------|
+| **architect** | Tier-1 (opus) | System design, multi-file planning |
+| **builder** | Tier-3 (haiku) | Implementation, code generation |
+| **reviewer** | Tier-2 (sonnet) | Two-stage code review (spec → quality) |
+| **security** | Tier-1 (opus) | Threat analysis, auth review, OWASP |
+| **tester** | Tier-3 (haiku) | Test writing, coverage, edge cases |
+| **documentor** | Tier-2 (sonnet) | .purpose files, portal.yaml — Paradigm metadata only |
+| **ftux** (Nora) | Tier-1 (opus) | First-time-user simulation, friction reports |
+| **advocate** (historically Jinx) | Tier-2 (sonnet) | Stress-tests assumptions, finds edge cases |
+| **compliance** (historically Rune) | Tier-2 (sonnet) | Symbol planning, 1:1 aspect enforcement |
+| **debugger** | Tier-2 (sonnet) | Incident triage, root-cause analysis |
+
+**Specialized agents (~20)** cover domains like mobile, database, DevOps, accessibility, and performance. They are rostered when your project type matches their expertise.
+
+**Ecosystem agents (~26+)** are language/platform-specific — Swift, TypeScript, Rust, Python ML, iOS, Android, etc. They accumulate per-ecosystem knowledge through notebooks that transfer across projects.
+
+> **Deep dive:** PARA 701 covers the full roster, agent profiles, notebooks, per-project customization, and the learning feedback loop.
+
+### Compliance: The Symbol Bookkeeper
+
+Compliance (historically nicknamed Rune) is one of Paradigm's core-tier agents, added specifically to prevent a common failure mode: building features without proper symbol coverage.
+
+**Before implementation**, compliance creates a **Symbol Plan**:
+- Enumerates all `#components`, `$flows`, `!signals`, `~aspects` the task needs
+- Creates symbol stubs via MCP tools (`paradigm_purpose_add_component`, etc.)
+- Enforces a **1:1 component-to-aspect ratio** — every component must have at least one aspect
+
+**After implementation**, compliance produces a **Compliance Report**:
+- Validates that planned symbols were actually created
+- Checks that aspect anchors point to valid code
+- Verifies flows exist for logic spanning 3+ components
+- Reports findings as blocking (must fix) or passing
+
+Compliance never modifies source code — only Paradigm metadata files (.purpose, portal.yaml). Think of it as the "symbol bookkeeper" who ensures the spec matches the code.
+
+### Facet Configuration
+
+Each agent role is a **facet** with four dimensions defined in `.paradigm/agents.yaml`:
+
+- **`defaultModel`** — Which AI model to use (opus for complex reasoning, sonnet for balanced, haiku for fast execution)
+- **`context.include / context.exclude`** — Which files the agent sees (scoped to reduce token waste)
+- **`limits.maxTokens`** — Budget per invocation (architects get more, builders get less)
+- **`protocol.relay`** — How results are reported: `structured` (JSON), `markdown` (narrative), or `handoff` (file for next agent)
+
+```yaml
+# Example from agents.yaml
+architect:
+  defaultModel: opus
+  context:
+    include: ["**/.purpose", "portal.yaml", ".paradigm/specs/**"]
+    exclude: ["**/*.test.*", "node_modules/**"]
+  limits:
+    maxTokens: 30000
+  protocol:
+    relay: structured
+```
+
+### Handoff Context
+
+Agents run in sequence, each receiving the previous agent's output via `handoffContext`:
+
+```
+compliance (symbol plan) → architect (design) → security (review) → builder (implement) → reviewer (check) → compliance (report) → documentor (.purpose files)
+```
+
+The `paradigm_agent_prompt` tool accepts `previousAgent` and `handoffContext` parameters to thread this chain.
+
+### Reviewer Protocol
+
+The reviewer follows a strict **two-stage protocol**:
+
+**Stage 1 (Spec Compliance)** — checks .purpose registrations, portal.yaml gates, flow steps, signal emissions, aspect enforcement. If Stage 1 fails, the reviewer **stops immediately** and hands back to the builder.
+
+**Stage 2 (Code Quality)** — only runs if Stage 1 passes. Covers OWASP security, conventions, test coverage, performance, error handling.
+
+Every review must produce a **minimum of 3 categorized findings**: blocking (must fix), improvement (should fix), or note (informational). A rubber-stamp "looks good" with zero findings is never acceptable.

package/dist/university-content/notes/N-para-401-commit-conventions.md

@@ -0,0 +1,82 @@
+---
+id: N-para-401-commit-conventions
+title: Commit Conventions
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - commit-format-typesymbol
+  - symbols-trailer-for
+  - post-commit-hook-automatic
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Commit Conventions
+
+Paradigm extends conventional commit format with symbol references, creating a machine-readable history that powers automatic history capture. Every commit message follows a specific structure that both humans and the Paradigm toolchain can parse.
+
+### Commit Message Format
+
+The format has three parts: subject line, body, and trailers.
+
+```
+type(#primary-symbol): short description
+
+- Detail with #component references
+- Gate changes: ^gate-name
+- Signals emitted: !signal-name
+- Flow updates: $flow-name
+
+Symbols: #symbol-a, #symbol-b, !signal-c, $flow-d
+```
+
+**Subject line**: `type(#primary-symbol): description` -- The type follows conventional commit types (`feat`, `fix`, `refactor`, `docs`, `test`, `chore`). The primary symbol in parentheses indicates the main component affected. The description is a concise summary under 70 characters.
+
+**Body**: References all affected symbols using their prefixes (`#`, `$`, `^`, `!`, `~`). Describe what changed, what gates were added or modified, what signals are emitted, and what flows were updated.
+
+**Symbols trailer**: A machine-readable line starting with `Symbols:` followed by a comma-separated list of every symbol affected. This trailer is **parsed by the post-commit hook** to automatically create `paradigm_history_record` entries.
+
+### Full Example
+
+```
+feat(#payment-form): add Apple Pay support
+
+- Add #apple-pay-button component for payment method selection
+- Update $checkout-flow with new Apple Pay payment step
+- Emit !payment-method-added signal when user selects Apple Pay
+- Gate: ^authenticated required for payment submission
+- Aspect: ~pci-compliant applied to payment data handling
+
+Symbols: #payment-form, #apple-pay-button, $checkout-flow, !payment-method-added, ^authenticated, ~pci-compliant
+```
+
+### Why the Symbols Trailer Matters
+
+The `Symbols:` trailer is not just documentation -- it is the bridge between git and Paradigm's history system. The post-commit hook reads this line, parses the symbols, and automatically calls `paradigm_history_record` with the commit hash, affected symbols, and the commit message as the description. This means every commit with a Symbols trailer is automatically captured in the Paradigm history log without any manual recording.
+
+Without the trailer, the commit is just a git commit. With the trailer, it becomes a tracked event in Paradigm's history system, feeding into fragility analysis, expertise tracking, and team wisdom.
+
+### Type Mapping
+
+The commit type maps to the history record fields:
+
+| Commit Type | History Type | History Intent |
+|---|---|---|
+| `feat` | implement | feature |
+| `fix` | implement | fix |
+| `refactor` | refactor | refactor |
+| `revert` | rollback | (automatic) |
+| `test` | implement | confirmed |
+| `docs` | (not recorded) | -- |
+| `chore` | (not recorded) | -- |
+
+By following these conventions, your git history becomes a structured input to Paradigm's operational tools. Every `feat` commit feeds fragility scores. Every `fix` commit increases the fix-to-feature ratio. Every `revert` becomes a rollback event. The commit message is the entry point for the entire history-wisdom-fragility pipeline.

package/dist/university-content/notes/N-para-401-mastery-review.md

@@ -0,0 +1,71 @@
+---
+id: N-para-401-mastery-review
+title: Framework Mastery
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - four-phases-initialization
+  - beginner---practitioner
+  - the-self-reinforcing-flywheel
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Framework Mastery
+
+This final lesson synthesizes everything from PARA 101 through PARA 401 into a complete picture of what it means to master the Paradigm framework. Mastery is not about memorizing tool names -- it is about internalizing the workflows, knowing which tool to reach for in each situation, and understanding how the pieces fit together to create a self-documenting, self-healing development system.
+
+### The Complete Paradigm Workflow
+
+**Phase 1: Project Initialization**
+
+Every Paradigm project starts with `paradigm shift`, which creates the `.paradigm/` directory, `config.yaml`, and initial structure. From there, you define symbols in `.purpose` files, set up `portal.yaml` for gates and condition checks, and configure agent facets in `agents.yaml`. The foundation must be solid -- everything else builds on accurate `.purpose` files and a complete `portal.yaml`.
+
+**Phase 2: Symbol-Driven Development**
+
+With the foundation in place, development is symbol-driven. Every code unit has a `#component` identity. Multi-step processes are documented as `$flows`. Condition checkpoints are `^gates`. Events are `!signals`. Cross-cutting rules are `~aspects` with code anchors. Tags from the tag bank classify symbols by function: `[feature]`, `[integration]`, `[state]`, `[critical]`.
+
+The power of symbols is that they create a semantic layer above the code. When an AI agent calls `paradigm_navigate` with intent "context" and task "add retry logic to payments," it does not just get file paths -- it gets the full symbolic context: which components are involved, which flows will be affected, which gates protect the endpoints, and which wisdom entries are relevant.
+
+**Phase 3: Operational Excellence**
+
+Day-to-day development follows the operational loop from PARA 301: orient, discover, assess risk, implement, validate, capture knowledge, monitor context. Each step uses specific tools:
+
+| Step | Tools |
+|---|---|
+| Orient | `paradigm_status`, `paradigm_session_recover` |
+| Discover | `paradigm_wisdom_context`, `paradigm_navigate` |
+| Assess | `paradigm_ripple`, `paradigm_history_fragility` |
+| Implement | File edits + `.purpose` updates + `portal.yaml` updates |
+| Validate | `paradigm doctor`, `paradigm_purpose_validate`, `paradigm_flow_check` |
+| Capture | `paradigm_wisdom_record`, `paradigm_decision_record`, `paradigm_history_record` |
+| Monitor | `paradigm_session_health`, `paradigm_session_stats` |
+
+**Phase 4: Orchestrated Complexity**
+
+Complex tasks are decomposed across specialized agents using `paradigm_orchestrate_inline`. The architect designs, security audits, the builder implements, and the tester validates. The PM layer enforces discipline with pre-flight and post-flight checks. Commits follow the Paradigm convention with `Symbols:` trailers that feed the history system automatically.
+
+### What Distinguishes Mastery
+
+A **beginner** uses Paradigm tools when reminded. They forget to update `.purpose` files, skip ripple analysis, and do not capture wisdom.
+
+A **practitioner** follows the operational loop consistently. They update metadata as they code, run doctor before committing, and record wisdom after debugging sessions.
+
+A **master** has internalized the framework to the point where it is invisible. They instinctively reach for `paradigm_ripple` before any modification. They write commit messages with `Symbols:` trailers without thinking. They call `paradigm_orchestrate_inline` when a task smells complex. They capture wisdom reflexively. Their `.purpose` files are always accurate because they update them in the same motion as writing code.
+
+The difference is not knowledge -- it is habit. Every tool in Paradigm exists to answer a specific question: "What depends on this?" (`paradigm_ripple`), "What do I need to know?" (`paradigm_wisdom_context`), "Is this area stable?" (`paradigm_history_fragility`), "What should I work on?" (`paradigm_navigate`). A master does not think about which tool to use -- the question triggers the tool automatically.
+
+### The Self-Reinforcing System
+
+Paradigm is designed as a flywheel. Accurate `.purpose` files make navigation reliable. Reliable navigation makes agents more efficient. Efficient agents produce better results. Better results with Symbols trailers feed the history system. Rich history enables fragility analysis. Fragility analysis informs risk assessment. Risk assessment guides implementation. Implementations update `.purpose` files. The cycle reinforces itself.
+
+Every time you skip a step -- neglecting a `.purpose` update, omitting a `Symbols:` trailer, not recording wisdom -- you degrade the flywheel. Every time you complete the loop, you strengthen it. Framework mastery is the commitment to keep the flywheel spinning.

package/dist/university-content/notes/N-para-401-mcp-tools-overview.md

@@ -0,0 +1,102 @@
+---
+id: N-para-401-mcp-tools-overview
+title: MCP Tools Overview
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - four-tool-categories
+  - token-economics-of
+  - paradigmsearch-paradigmnavigate-paradigmripple
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## MCP Tools Overview
+
+Model Context Protocol (MCP) tools are the primary interface between AI agents and the Paradigm framework. Rather than reading raw files to understand project structure, agents call MCP tools that return structured, token-efficient responses. Understanding the full tool inventory and when to use each tool is fundamental to effective Paradigm orchestration.
+
+Paradigm exposes ~30 tool modules, organized into four categories:
+
+### Discovery Tools
+These tools help agents understand the codebase without reading files directly.
+
+- **`paradigm_search`** (~150 tokens) -- Fuzzy search across symbol names, descriptions, and tags. Supports type filtering (component, flow, gate, signal, aspect).
+- **`paradigm_navigate`** (~200 tokens) -- Three intents: `find` (symbol lookup), `explore` (area browsing), `context` (task-based discovery).
+- **`paradigm_ripple`** (~300 tokens) -- Dependency analysis showing what depends on a symbol, 1-5 levels deep.
+- **`paradigm_related`** (~200 tokens) -- All symbols connected to a given symbol, both upstream and downstream.
+
+### Knowledge Tools
+These tools access the project's institutional memory.
+
+- **`paradigm_wisdom_context`** -- Retrieves preferences and antipatterns for specified symbols. (For decisions affecting those symbols, call `paradigm_decision_search` — see PARA 501.)
+- **`paradigm_wisdom_record`** -- Captures new preferences or antipatterns. (For architectural decisions, use `paradigm_decision_record` — see PARA 501.)
+- **`paradigm_wisdom_expert`** -- Identifies human experts for symbols or areas.
+- **`paradigm_decision_record`** -- Records an architectural decision with rationale, participants, and alternatives. Stored in `.paradigm/decisions/`, auto-emits a companion lore `insight` entry.
+- **`paradigm_decision_search`** -- Searches the decision store by status, participant, symbol, tag, or date range.
+- **`paradigm_history_context`** -- Retrieves implementation history for symbols.
+- **`paradigm_history_record`** -- Logs implementation events.
+- **`paradigm_history_fragility`** -- Checks stability scores.
+
+### Validation Tools
+These tools verify metadata integrity.
+
+- **`paradigm_purpose_validate`** -- Validates `.purpose` files and optionally `portal.yaml`.
+- **`paradigm_flow_check`** -- Validates flow definitions against the codebase.
+- **`paradigm_aspect_check`** -- Verifies that aspects have valid code anchors.
+
+### Management Tools
+These tools modify Paradigm metadata.
+
+- **`paradigm_purpose_add_component`**, **`paradigm_purpose_add_signal`**, **`paradigm_purpose_add_flow`**, etc. -- Add symbols to `.purpose` files.
+- **`paradigm_portal_add_gate`**, **`paradigm_portal_add_route`** -- Manage `portal.yaml` gates and routes.
+- **`paradigm_purpose_rename`** -- Rename symbols across all `.purpose` files.
+- **`paradigm_tags`**, **`paradigm_tags_suggest`** -- Manage the tag bank.
+
+### Token Economics
+
+Every tool call has a token cost. The general principle is that MCP queries are 5-20x cheaper than reading files:
+
+| Operation | Approximate Cost |
+|---|---|
+| `paradigm_status` | ~100 tokens |
+| `paradigm_search` | ~150 tokens |
+| `paradigm_navigate` | ~200 tokens |
+| `paradigm_ripple` | ~300 tokens |
+| Reading a small file | ~500 tokens |
+| Reading a large file | ~2000+ tokens |
+
+The rule of thumb: **use MCP tools for discovery and knowledge retrieval; use file reads only when you need exact source code for implementation.** An agent that reads 10 files to understand a feature (10,000+ tokens) versus one that calls `paradigm_navigate` with context intent (200 tokens) has a 50x cost difference for the same information.
+
+### Practice Tools
+
+These tools manage behavioral discipline and project memory.
+
+**Habits Tools:**
+- **`paradigm_habits_list`** -- List habit definitions with filters (category, trigger, severity, enabled status).
+- **`paradigm_habits_check`** -- Evaluate and record practice compliance. Triggers: `preflight`, `postflight`, `on-stop`, `on-commit`.
+- **`paradigm_habits_status`** -- Practice profile with compliance rates, category breakdowns, trends, and incident correlations.
+- **`paradigm_practice_context`** -- Proactive habit warnings before modifying symbols. Returns relevant habits and recent compliance rates.
+
+**Lore Tools:**
+- **`paradigm_lore_search`** -- Search lore entries by symbol, author, date range, tags, type, and review status.
+- **`paradigm_lore_record`** -- Record new entries (agent sessions, milestones, incidents, reviews, retros, insights, human-notes). Calling with `type: 'decision'` returns a structured rejection envelope pointing at `paradigm_decision_record` (v6.0 hard-removal).
+- **`paradigm_lore_get`** -- Fetch a single entry by ID with full detail.
+- **`paradigm_lore_update`** -- Update an existing entry's fields (title, summary, type, symbols, tags, learnings).
+- **`paradigm_lore_delete`** -- Delete an entry by ID. Requires `confirm: true` to prevent accidental deletion.
+- **`paradigm_lore_timeline`** -- Timeline overview with recent entries, hot symbols, and active authors.
+- **`paradigm_lore_assess`** -- Score an entry's quality and completeness (1-5 each), with optional notes; feeds the calibration and review filters.
+- **`paradigm_lore_calibration`** -- Surface entries where recorded confidence diverges from observed reality.
+
+**Knowledge Stream Tools (v5.x — Work Log, Journal, Decisions):**
+- **`paradigm_work_log_record`** / **`paradigm_work_log_search`** -- Project-scoped, ephemeral record of "what got done" — for standups and sprint summaries. Stored in `.paradigm/work-log/{date}/`.
+- **`paradigm_journal_record`** / **`paradigm_journal_search`** -- Agent-private, durable record of "what I learned." Stored in `~/.paradigm/agents/{id}/journal/`. Travels across projects.
+- **`paradigm_decision_record`** / **`paradigm_decision_search`** -- Project-scoped, institutional record of "what we decided." Stored in `.paradigm/decisions/`. Each record auto-writes a companion lore `insight` entry for timeline coverage.

package/dist/university-content/notes/N-para-401-multi-agent-coordination.md

@@ -0,0 +1,80 @@
+---
+id: N-para-401-multi-agent-coordination
+title: Multi-Agent Coordination
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - paradigmorchestrateinline-with-plan
+  - five-agent-roles
+  - model-assignment-opus
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Multi-Agent Coordination
+
+Some tasks are too complex or too multi-faceted for a single AI agent to handle efficiently. Adding a payment system requires architectural design, security review, code implementation, and testing -- each benefiting from a different perspective and expertise level. Paradigm's orchestration system decomposes complex tasks into stages handled by specialized agents.
+
+The entry point is `paradigm_orchestrate_inline` with `mode="plan"`. Describe your task, and the orchestrator analyzes it against trigger patterns to suggest the right agent team, estimate token costs, and produce an execution plan.
+
+```
+paradigm_orchestrate_inline({
+  task: "Add JWT authentication with role-based access control",
+  mode: "plan"
+})
+
+// Returns:
+// Suggested agents: architect, security, builder, tester
+// Estimated tokens: ~45,000
+// Stages:
+//   1. architect: Design auth architecture (cannot parallel)
+//   2. security: Review auth design for vulnerabilities (depends on 1)
+//   3. builder: Implement auth middleware and gates (depends on 1, 2)
+//   4. tester: Write auth test suite (depends on 3)
+```
+
+The five agent roles are:
+
+- **Architect** (opus model) -- Designs system architecture, evaluates tradeoffs, makes structural decisions. Used when a task requires design thinking before implementation.
+- **Builder** (haiku model) -- Implements code changes. Fast and cost-effective for straightforward implementation once the design is clear.
+- **Tester** (haiku model) -- Writes tests and validates implementations. Focused on coverage and edge cases.
+- **Reviewer** (sonnet model) -- Critiques implementations for quality, patterns, and potential issues. Balanced between speed and depth.
+- **Security** (opus model) -- Audits authentication, authorization, and data handling. Used whenever a task involves protected resources or user data.
+
+These model assignments are defaults configured in `.paradigm/agents.yaml`. When you first set up a project with `paradigm shift`, the interactive setup detects available providers and prompts you to select models for each agent role. You can reconfigure models at any time with `paradigm team models` -- this shows the current assignment table and lets you change which model each agent uses. Run `paradigm team models --refresh` to re-discover models from your environment (useful after adding new API keys or providers). The model-to-role mapping follows a simple principle: use the most capable model (opus) for tasks requiring deep reasoning, a balanced model (sonnet) for critique, and the fastest model (haiku) for straightforward execution.
+
+Once you have a plan, call `paradigm_orchestrate_inline` with `mode="execute"` to get full prompts for each agent. These prompts include the task context, relevant symbols, file locations, and stage-specific instructions. You then launch each agent using the Task tool or the CLI.
+
+```
+paradigm_orchestrate_inline({
+  task: "Add JWT authentication with role-based access control",
+  mode: "execute"
+})
+// Returns full prompts ready to pass to each agent
+```
+
+For individual agent prompts with custom context, use `paradigm_agent_prompt`. This is useful when you want to spawn a single agent for a focused task rather than running full orchestration.
+
+```
+paradigm_agent_prompt({
+  agent: "security",
+  task: "Audit the new payment webhook endpoint for CSRF and replay attacks"
+})
+```
+
+The key insight is that orchestration is not just about parallelism -- it is about applying the right model and perspective to each stage. An architect (opus) spending 10,000 tokens on design is more valuable than a builder (haiku) spending 50,000 tokens trying to figure out the design while implementing.
+
+### Fresh Context Principle
+
+Each builder task runs in a separate, clean context. Builders NEVER carry assumptions from previous tasks -- they re-read specs and handoff context for every invocation. Why? Stale assumptions from prior tasks cause subtle bugs. If a builder remembers that "the payment field was called `amount`" from a previous task, but the architect's current spec renamed it to `total`, the builder would write code against the wrong field name. A fresh context ensures each implementation is based only on the current spec, not on memory of what a previous task did.
+
+This principle applies even when the same builder agent handles multiple sequential tasks in an orchestration pipeline. Each task invocation should be treated as if the builder has never seen the codebase before -- the handoff context provides everything it needs.

package/dist/university-content/notes/N-para-401-notebooks-permissions.md

@@ -0,0 +1,66 @@
+---
+id: N-para-401-notebooks-permissions
+title: Agent Notebooks & Permission Scoping
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Agent Notebooks
+
+Agent notebooks are curated snippet libraries distilled from lore entries. They provide reusable knowledge that agents can apply across sessions and projects.
+
+### NotebookEntry Format
+
+Each entry contains:
+- **context**: When to apply this snippet (retrieval key)
+- **snippet**: The reusable code/knowledge
+- **provenance**: Where it came from (lore, manual, transfer)
+- **concepts[]**: Concept tags for retrieval (e.g., ["auth", "middleware"])
+- **appliedCount**: How many times used in orchestration
+- **confidence**: 0.0-1.0 reliability score
+
+### Storage
+
+- Global: `~/.paradigm/notebooks/{agent-id}/` — travels across projects
+- Project: `.paradigm/notebooks/{agent-id}/` — project-specific
+
+### MCP Tools
+
+- `paradigm_notebook_search` — find entries by concept, tag, or keyword
+- `paradigm_notebook_add` — create a new curated entry
+- `paradigm_notebook_promote` — extract from lore entry with provenance linking
+
+### Orchestration Integration
+
+`buildProfileEnrichment()` appends a "Relevant Notebook Entries" section with context + snippet for matching entries. This enriches the orchestration prompt with reusable patterns.
+
+## Agent Permissions
+
+Permission scoping controls what agents can access:
+
+### Permission Fields
+
+- **paths.read/write**: Glob patterns for file access
+- **paths.deny**: Always-deny patterns (overrides read/write)
+- **tools.allow/deny**: Tool name patterns
+- **dangerous_actions**: Actions requiring explicit approval
+
+### Integrity Hashing
+
+SHA-256 hash of `{id, role, permissions}` stored as `integrityHash`. `verifyIntegrity()` detects tampering — agents must never modify their own config.
+
+### In Orchestration
+
+Permissions appear as constraints in orchestration prompts, informing agents of their boundaries.