@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-301-wisdom-system.md

@@ -0,0 +1,89 @@
+---
+id: N-para-301-wisdom-system
+title: Team Wisdom
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-301
+  - two-wisdom-types
+  - paradigmwisdomcontext
+  - paradigmwisdomrecord
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Team Wisdom
+
+Every development team accumulates knowledge over time: patterns that work, mistakes that keep recurring. Paradigm's wisdom system captures this institutional knowledge in a structured, queryable format so it is available to both human developers and AI agents.
+
+There are two types of wisdom in Paradigm — preferences and antipatterns. Architectural decisions used to live here too, but in v6.0 they moved to a dedicated decision store; see "Where Decisions Went" below.
+
+**Preferences** define "how we do things." These are team conventions, coding standards, and stylistic choices that go beyond what a linter can enforce. For example: "We always use optimistic UI updates for payment flows" or "Error messages must include the operation that failed, not just the error code."
+
+**Antipatterns** record "what NOT to do" along with "what to do instead." Each antipattern has an ID, a description of the bad practice, a reason explaining why it is problematic, and an alternative showing the correct approach. For example: "Do not call the payment API directly from React components -- use the #payment-service abstraction layer instead."
+
+```yaml
+# Example antipattern
+api-001:
+  description: Calling external APIs directly from UI components
+  reason: Tight coupling, no error handling, no retry logic
+  alternative: Route all API calls through service components (#*-service)
+  symbols: ["#checkout-form", "#payment-service"]
+```
+
+## Where Decisions Went
+
+Through v5, "decisions" were a third type of wisdom recorded via `paradigm_wisdom_record({ type: 'decision', ... })`. v6.0 split decisions out into their own store:
+
+- **Tool:** `paradigm_decision_record` (CLI: `paradigm decision record`)
+- **Storage:** `.paradigm/decisions/TD-*.yaml` — topic-addressable, not date-partitioned
+- **Companion:** Each recorded decision auto-writes a lore `insight` entry so the project timeline still shows the moment the decision was made
+- **Search:** `paradigm_decision_search` (filter by status, participant, symbol, tag, date range)
+
+Calling `paradigm_wisdom_record({ type: 'decision' })` is no longer supported — `paradigm_wisdom_record` now accepts only `preference` and `antipattern`. The decision store carries the full ADR shape (proposed/supported/dissented participants, alternatives_considered, status lifecycle).
+
+```
+// Capture a v6.0 architectural decision (not via wisdom_record):
+paradigm_decision_record({
+  title: "Use Redis over in-memory cache for sessions",
+  decision: "Adopt Redis as the session backing store",
+  rationale: "Survives restarts, supports horizontal scale, observable via existing tooling",
+  participants: [
+    { id: "human/matt", role: "human", stance: "proposed" },
+    { id: "a-paradigm/architect", role: "agent", stance: "supported" },
+    { id: "a-paradigm/security", role: "agent", stance: "dissented" }
+  ],
+  alternatives_considered: [
+    { option: "in-memory Map", rejected_because: "lost on restart, not horizontally scalable" }
+  ],
+  symbols_affected: ["#session-store"],
+  status: "active"
+})
+```
+
+To retrieve wisdom before making changes, call `paradigm_wisdom_context` with the symbols you plan to modify. This returns all relevant preferences and antipatterns for those symbols. For decisions affecting those symbols, call `paradigm_decision_search({ symbol: '#x' })`. To capture new wisdom, use `paradigm_wisdom_record` to add antipatterns. For decisions, use `paradigm_decision_record`. The expertise tracking system also identifies who on the team knows the most about specific symbols, accessible via `paradigm_wisdom_expert`.
+
+```
+// Before modifying checkout:
+paradigm_wisdom_context({ symbols: ["#checkout-form", "$checkout-flow"] })
+
+// After discovering a recurring mistake:
+paradigm_wisdom_record({
+  type: "antipattern",
+  id: "checkout-003",
+  symbols: ["#checkout-form"],
+  description: "Using setTimeout for payment polling",
+  reason: "Unreliable, races with redirects, misses webhook events",
+  alternative: "Use the !payment-completed signal with a listener"
+})
+```
+
+The wisdom system is most valuable when it becomes a habit. After every debugging session, ask: "Is there an antipattern here we should record?" After every architectural discussion, ask: "Should this be a decision record?" — and if so, use `paradigm_decision_record`, not the wisdom system. The cost of capturing wisdom is minutes; the cost of not capturing it is repeating the same mistakes across sessions and team members.

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

@@ -0,0 +1,99 @@
+---
+id: N-para-401-agent-identity
+title: Agent Identity & Expertise Profiles
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - agent-files-are
+  - two-storage-scopes
+  - expertise-auto-updates-via
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Agent Identity & Expertise Profiles
+
+Every Claude session starts blank. The project remembers — via lore, protocols, aspects — but the agent doesn't. An architect that has successfully designed auth systems 14 times has no memory of that expertise. The orchestrator cannot route tasks to the most qualified agent because qualification is not tracked.
+
+Agent identity files (`.agent`) solve this with persistent YAML profiles that track expertise, personality, and cross-project patterns. They **overlay** the existing `agents.yaml` system and are fully backward compatible — when no `.agent` files exist, everything works exactly as before.
+
+### Storage & Merge Priority
+
+Profiles live in two locations:
+
+- **Global** (`~/.paradigm/agents/architect.agent`) — travels across projects
+- **Project** (`.paradigm/agents/builder.agent`) — project-level overrides
+
+Merge priority: **project `.agent` > global `.agent` > `agents.yaml`**. This means a project can override a global agent's default model or focus areas without modifying the shared identity.
+
+### Profile Structure
+
+Each `.agent` file contains:
+
+- **`id`** — Agent identifier (e.g., "architect")
+- **`personality`** — Style (deliberate/rapid/exploratory/methodical), risk tolerance (conservative/balanced/aggressive), and verbosity (minimal/concise/detailed)
+- **`expertise`** — Per-symbol entries with confidence (0.0-1.0), session count, and last touch date
+- **`transferable`** — Cross-project patterns with success rates and linked protocols/lore
+- **`contexts`** — Per-project adaptations: focus areas, preferred model, session count
+
+### Expertise Auto-Population
+
+When lore is recorded with `paradigm_lore_record`, the relevant agent's expertise scores update automatically via exponential moving average:
+
+```
+For each symbol in symbols_touched:
+  if existing entry:
+    sessions++
+    confidence = 0.7 * old_confidence + 0.3 * lore_confidence
+  else:
+    create entry with confidence = lore_confidence (or 0.5 default)
+```
+
+Assessment verdicts from `paradigm_lore_assess` also feed into expertise. A verdict of `correct` nudges confidence up, `incorrect` nudges it down.
+
+### Querying Expertise
+
+`paradigm_agent_expertise` takes a symbol and returns agents ranked by confidence:
+
+```
+paradigm_agent_expertise({ symbol: "#payment-service" })
+// Returns: [{ agentId: "architect", confidence: 0.92, sessions: 14 }, ...]
+```
+
+This enables **symbol-to-agent routing** — the orchestrator can prefer the agent most experienced with the symbols a task touches.
+
+### Orchestration Enrichment
+
+When `paradigm_orchestrate_inline` builds agent prompts, agents with `.agent` profiles receive a preamble:
+
+```markdown
+## Agent Identity: architect
+**Style:** deliberate | **Risk:** conservative | **Verbosity:** concise
+
+## Your Expertise on Relevant Symbols
+- #auth-middleware: confidence 0.92 (14 sessions)
+- $checkout-flow: confidence 0.88 (8 sessions)
+
+## Transferable Patterns
+- portal-gate-pattern: 95% success (learned in a-paradigm, applied in 2 projects)
+```
+
+This goes BEFORE the role-specific prompt, giving the agent self-awareness about its strengths.
+
+### CLI Commands
+
+- `paradigm agent list` — Show all profiles with top expertise
+- `paradigm agent show <id>` — Full profile with expertise table
+- `paradigm agent create <id> --global` — Create new identity file
+- `paradigm agent sync <id>` — Bootstrap expertise from existing project lore
+
+Agent identities are a foundation for future capabilities: curated notebooks, model cascading, and knowledge graduation across projects.

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.