@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-301-operations-review.md

@@ -0,0 +1,55 @@
+---
+id: N-para-301-operations-review
+title: Operational Excellence
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - the-operational-loop
+  - combining-tools-for
+  - metadata-maintenance-as
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Operational Excellence
+
+This lesson brings together everything from PARA 301 into a cohesive daily workflow. Operational excellence in Paradigm is not about memorizing individual tools -- it is about building habits that keep your project healthy, your metadata accurate, and your development sessions productive.
+
+### The Operational Loop
+
+Every development session follows a predictable pattern:
+
+**1. Orient** -- Start by calling `paradigm_status` to see the project overview: how many symbols are defined, recent changes, any outstanding issues. If this is a continuation session, call `paradigm_session_recover` to load context from the previous session.
+
+**2. Discover** -- Before touching code, check for existing protocols: call `paradigm_protocol_search` with your task description. If a match exists, follow its steps and skip exploration. Otherwise, call `paradigm_wisdom_context` with the symbols you plan to modify to learn team conventions and avoid known pitfalls. Use `paradigm_navigate` with the "context" intent to find all relevant files for your task.
+
+**3. Assess Risk** -- Run `paradigm_ripple` on every symbol you plan to modify to understand the blast radius. Check `paradigm_history_fragility` on anything flagged as a dependency. If the task is complex (3+ files, security + implementation), call `paradigm_orchestrate_inline` with mode="plan" to get the right agent team.
+
+**4. Implement** -- Write code, updating `.purpose` files as you go. If you add routes, update `portal.yaml`. If you add signals, register them. Do not defer metadata updates to "later" -- later never comes.
+
+**5. Validate** -- Run `paradigm doctor` or `paradigm_purpose_validate` to catch any drift. Use `paradigm_flow_check` if you modified flows. Record the implementation with `paradigm_history_record`.
+
+**6. Capture Knowledge** -- Did you discover an antipattern? Record it with `paradigm_wisdom_record`. Did you make an architectural decision? Record it with `paradigm_decision_record` (which auto-writes a companion lore `insight` for timeline coverage). Did the implementation follow a repeatable pattern? Record a protocol with `paradigm_protocol_record`. Did the implementation reveal a fragile area? Note it for the team.
+
+**7. Monitor Context** -- Check `paradigm_session_health` periodically. If approaching limits, prepare a handoff.
+
+### Common Pitfalls
+
+- **Skipping wisdom checks**: Leads to repeating mistakes the team already knows about
+- **Skipping ripple analysis**: Leads to breaking downstream dependencies
+- **Deferring metadata updates**: Leads to stale `.purpose` files and misleading navigation
+- **Ignoring fragility warnings**: Leads to cascading failures in unstable areas
+- **Not recording history**: Loses the trail that fragility analysis depends on
+
+### The Measure of Excellence
+
+A well-operated Paradigm project has: accurate `.purpose` files that match the code, a `portal.yaml` that reflects all protected routes, wisdom entries that prevent repeated mistakes, history records that enable fragility analysis, and context handoffs that allow seamless multi-session work. When all of these are in place, every AI agent session starts with full context and every change is informed by the project's complete institutional knowledge.

package/dist/university-content/notes/N-para-301-paradigm-shift.md

@@ -0,0 +1,93 @@
+---
+id: N-para-301-paradigm-shift
+title: The paradigm shift Command
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigm-shift-is
+  - six-steps-init
+  - non-interactive-by-default
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## One Command, Full Setup
+
+`paradigm shift` is the universal onboarding command. It transforms any project directory into a Paradigm-aware workspace in a single run. Whether you are starting a new project or adopting Paradigm in an existing codebase, this is where you begin.
+
+```bash
+paradigm shift
+```
+
+## What It Does (6 Steps)
+
+The command runs six steps in sequence:
+
+### Step 1: Initialize
+Creates the `.paradigm/` directory with `config.yaml`, `tags.yaml`, and starter files. If the directory already exists, it updates configuration without overwriting your customizations.
+
+### Step 2: Auto-Migrate
+Detects if your project uses an older Paradigm version and applies breaking-change migrations automatically. This keeps projects up to date without manual migration effort.
+
+### Step 3: Scan & Index
+Discovers all symbols in your codebase by reading `.purpose` files and `portal.yaml`. Builds the navigator index for fast symbol lookup. Skip this step with `--quick` for faster initialization.
+
+### Step 4: Sync IDEs
+Generates instruction files for your AI tools:
+- `CLAUDE.md` — Claude Code instructions
+- `AGENTS.md` — Universal agent instructions
+- `.cursor/rules/` — Cursor IDE rules
+
+These files are regenerated from your Paradigm configuration every time you run shift or sync.
+
+### Step 5: Install Hooks
+Sets up Git hooks (pre-commit, post-commit) and Claude Code/Cursor hooks for automated enforcement. The hooks run compliance checks based on your enforcement level.
+
+### Step 6: Roster & Model Tiers
+Suggests an agent roster based on your detected project type (web, backend, mobile, etc.) and configures model tiers (tier-1/tier-2/tier-3) based on your environment.
+
+## Key Flags
+
+| Flag | Effect |
+|------|--------|
+| `--quick` | Skip symbol scanning (fast init) |
+| `--verify` | Run `paradigm doctor` health checks at the end |
+| `--workspace <name>` | Create or join a multi-project workspace |
+| `--force` | Reinitialize (overwrite existing config) |
+
+## When to Re-Run
+
+Run `paradigm shift` again when:
+- You upgrade Paradigm to a new version (auto-migrates)
+- You want to refresh IDE instruction files after config changes
+- You add the project to a workspace
+- After major restructuring that changes project type
+
+The command is idempotent — running it multiple times is safe. It updates what changed and leaves the rest alone.
+
+## What Comes Out
+
+After `paradigm shift`, your project has:
+
+```
+.paradigm/
+  config.yaml       # Project configuration
+  tags.yaml         # Tag taxonomy
+  roster.yaml       # Agent team roster
+  agents.yaml       # Agent tier assignments
+CLAUDE.md            # Claude Code instructions
+AGENTS.md            # Universal agent instructions
+.purpose             # Root purpose file (if new project)
+portal.yaml          # Auth topology (if gates detected)
+```
+
+Plus Git hooks and IDE-specific instruction files, all derived from your Paradigm configuration.

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

@@ -0,0 +1,113 @@
+---
+id: N-para-301-protocols
+title: Protocols — Repeatable Patterns
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - protocols-as-repeatable
+  - paradigmprotocolsearch--find
+  - paradigmprotocolrecord--capture
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Protocols — Repeatable Patterns
+
+AI agents routinely spend tens of thousands of tokens exploring codebases to reverse-engineer implementation patterns before they can start working. In a well-structured project, the answer to "how do I add a new view?" is the same every time: create a component file, create a store, register a route, add CSS. But this knowledge lives nowhere explicit, so every agent re-discovers it from scratch.
+
+Protocols solve this problem. They are procedural, step-by-step instructions with exact file references, learned from actual completed work. When an agent receives a task like "add a Settings page," it first calls `paradigm_protocol_search` with the task description. If a matching protocol exists, the agent gets back ordered steps, an exemplar file to study, and freshness information -- all within a few hundred tokens instead of exploring for thousands.
+
+### Storage and Format
+
+Protocols are stored as `.protocol` files (YAML syntax, semantic extension) in `.paradigm/protocols/`. Each protocol has an ID, a name, a description, trigger phrases for fuzzy matching, tags for classification, an exemplar file (the canonical example to follow), and an ordered list of steps.
+
+```
+.paradigm/protocols/
+  index.yaml            # Auto-generated by reindex
+  add-view.protocol     # One file per protocol
+  add-api-route.protocol
+```
+
+### Step Types
+
+Protocol steps use four action types:
+
+- **create** -- Create a new file. Specifies `target` (the file to create, with placeholders) and `template_from` (an existing file to follow as a model).
+- **modify** -- Edit an existing file. Specifies `target`, `reference` (where in the file to make changes), and `notes` explaining what to add.
+- **run** -- Execute a command. Specifies `command` and `notes`.
+- **verify** -- Confirm something works. Specifies `notes` with what to check.
+
+Steps support placeholders: `{Name}` for PascalCase and `{name}` for kebab-case. When following the protocol, the agent substitutes the actual name.
+
+### Searching for Protocols
+
+The primary entry point is `paradigm_protocol_search`. Pass a natural language task description and it returns matching protocols ranked by relevance.
+
+```
+paradigm_protocol_search({ task: "add a new settings page" })
+```
+
+The search uses weighted fuzzy matching: trigger phrases (weight 3), tags (weight 2), name and description (weight 1), and step notes (weight 0.5). The protocol set per project is small (5-30 entries), so a full scan is efficient.
+
+To get full details for a specific protocol, use `paradigm_protocol_get`:
+
+```
+paradigm_protocol_get({ id: "P-add-view" })
+```
+
+### Recording Protocols
+
+Protocols are captured *after* completing work, not before. Two paths lead to a new protocol:
+
+1. **Agent-initiated** -- After implementing a repeatable task, the agent calls `paradigm_protocol_record` with the steps it followed:
+
+```
+paradigm_protocol_record({
+  name: "Add a new view",
+  description: "Create a new page with store, route, and CSS",
+  trigger: ["add view", "new page", "create view"],
+  tags: ["ui", "frontend"],
+  exemplar: "ui/src/views/LogsView.tsx",
+  steps: [
+    { action: "create", target: "ui/src/views/{Name}View.tsx", template_from: "ui/src/views/LogsView.tsx" },
+    { action: "modify", target: "ui/src/App.tsx", reference: "Route elements", notes: "Add Route" },
+    { action: "verify", notes: "Run build, check route loads" }
+  ],
+  recorded_from: "L-2026-03-01-001"
+})
+```
+
+2. **Lore-prompted** -- When `paradigm_lore_record` is called, the response includes a `protocol_suggestion` if the session created new files following existing patterns. This nudges agents to capture repeatable work without manual intervention.
+
+### Freshness and Maintenance
+
+Protocols go stale as code evolves. Three mechanisms keep them fresh:
+
+- **Reindex validation** -- During `paradigm_reindex`, all protocol references are checked. Missing files mark the protocol as `broken`. An exemplar modified since `last_verified` marks it `stale`. All references valid means `current`.
+- **On-use refresh** -- After successfully following a protocol, the agent calls `paradigm_protocol_update` with `refresh: true` to bump `last_verified` and fix outdated references.
+- **Status visibility** -- `paradigm_status` includes protocol health (X current, Y stale, Z broken). Stale protocols surface naturally during normal workflow.
+
+You can also explicitly validate protocols:
+
+```
+paradigm_protocol_validate({ id: "P-add-view" })
+```
+
+### The Workflow
+
+The protocol workflow integrates into the Paradigm operational loop:
+
+1. **Before implementing**: Call `paradigm_protocol_search` with your task description. If a match exists, follow the steps -- skip codebase exploration.
+2. **During implementation**: Use the protocol's exemplar as a reference. Follow each step in order.
+3. **After completion**: If no protocol existed and the work was repeatable, record one. If a protocol existed and you followed it successfully, call `paradigm_protocol_update` to refresh its timestamp.
+
+This creates a virtuous cycle: each agent session that follows a protocol validates it, and each session that does repeatable work without a protocol can create one for future agents.

package/dist/university-content/notes/N-para-301-ripple-analysis.md

@@ -0,0 +1,53 @@
+---
+id: N-para-301-ripple-analysis
+title: Ripple Analysis
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigmripple
+  - direct-and-indirect
+  - depth-parameter-1-5
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Ripple Analysis
+
+When you change a symbol, the effects can ripple outward through the codebase like a stone dropped in water. A modification to `#payment-service` might affect `$checkout-flow`, which depends on it. That flow might be used by `#checkout-form`, which is consumed by `#order-page`. Ripple analysis maps these dependency chains before you make changes, so you can understand the full blast radius of your modification.
+
+The tool `paradigm_ripple` takes a symbol and an optional depth parameter (1-5, default 2) and returns everything that depends on it, both directly and indirectly. This is not just a list of imports -- it is a semantic dependency graph built from Paradigm's symbol relationships: which components reference this symbol, which flows include it as a step, which gates protect endpoints that use it, and which signals it emits that other components listen to.
+
+```
+paradigm_ripple({
+  symbol: "#payment-service",
+  depth: 3
+})
+
+// Returns:
+// Direct dependents (depth 1):
+//   $checkout-flow - uses #payment-service in step 3
+//   #refund-handler - calls #payment-service.refund()
+//   !payment-completed - emitted by #payment-service
+//
+// Indirect dependents (depth 2):
+//   #checkout-form - triggers $checkout-flow
+//   #order-history - listens to !payment-completed
+//
+// Indirect dependents (depth 3):
+//   #account-dashboard - renders #order-history
+```
+
+Ripple analysis is **essential before any refactor**. The most common cause of unintended breakage is not understanding the full dependency tree. A developer renames a method on `#payment-service` thinking only `$checkout-flow` uses it, not realizing that `#refund-handler` also calls that method. Ripple analysis catches this.
+
+The depth parameter controls how far out to look. Depth 1 shows only direct dependents. Depth 2 (the default) shows dependents of dependents. For large refactors, depth 3 or higher may be warranted. Keep in mind that higher depth values return more results and cost more tokens, so start at the default and increase only if needed.
+
+A good practice is to run ripple analysis, review the affected symbols, then check the fragility of any flagged dependents before proceeding. If your modification would ripple into a fragile area, you may want to add extra safeguards or break the change into smaller increments. The combination of ripple analysis and fragility checking forms the core of Paradigm's change safety net.

package/dist/university-content/notes/N-para-301-sentinel-observability.md

@@ -0,0 +1,87 @@
+---
+id: N-para-301-sentinel-observability
+title: Sentinel & Observability
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - incidents-map-errors
+  - failure-pattern-matching
+  - paradigmsentineltriage-for-filtering
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Sentinel & Observability
+
+Paradigm Sentinel is the error tracking and observability system that maps runtime errors back to Paradigm symbols. When something breaks in production, Sentinel does not just show you a stack trace -- it tells you which `#component` failed, which `$flow` was interrupted, which `^gate` was involved, and whether there is a known failure pattern that matches.
+
+Incidents are the core unit of Sentinel. Each incident records the error message, stack trace, environment, affected symbols, and the flow position (where in a multi-step flow the failure occurred). Incidents can be created automatically by instrumented code or manually via `paradigm_sentinel_record`.
+
+```
+paradigm_sentinel_record({
+  error: {
+    message: "Stripe API returned 429: rate limited",
+    type: "RateLimitError",
+    code: "STRIPE_429"
+  },
+  symbols: {
+    component: "#payment-service",
+    flow: "$checkout-flow",
+    gate: "^authenticated"
+  },
+  environment: "production",
+  service: "api-server"
+})
+```
+
+**Pattern matching** is what makes Sentinel more than a log aggregator. You define failure patterns that describe known error signatures -- which error messages to look for, which symbols are typically involved, and what the resolution strategy is. When an incident is recorded, Sentinel matches it against known patterns and suggests resolutions.
+
+```
+paradigm_sentinel_add_pattern({
+  id: "stripe-rate-limit",
+  name: "Stripe Rate Limit",
+  pattern: {
+    errorContains: ["429", "rate limit"],
+    symbols: { component: "#payment-service" }
+  },
+  resolution: {
+    description: "Implement exponential backoff retry",
+    strategy: "retry",
+    priority: "high"
+  }
+})
+```
+
+The triage workflow uses `paradigm_sentinel_triage` to filter and view incidents. You can filter by status (open, investigating, resolved), by symbol, by environment, or by search text in error messages. Once an incident is understood and fixed, mark it resolved with `paradigm_sentinel_resolve`, optionally linking the fix commit and matched pattern.
+
+Sentinel also provides health metrics via `paradigm_sentinel_stats`. You can see incident counts over time periods (1d, 7d, 30d, 90d) and get health scores for specific symbols. A symbol with many recent incidents and low resolution rates has poor health -- another signal that pairs with fragility tracking to identify problem areas. The web UI, launched with `paradigm sentinel`, provides a visual dashboard for all of this.
+
+## Incident Grouping
+
+When incidents pile up, grouping helps identify systemic issues. Sentinel's incident grouper clusters similar incidents using three signals: **symbol context similarity** (which components, flows, and gates are involved), **error message similarity** (Levenshtein distance between messages), and **stack trace fingerprinting** (normalizing stack frames by stripping line numbers and paths to capture structural similarity). A time-decay factor ensures recent incidents weigh more heavily in similarity calculations -- incidents from two weeks ago contribute half as much as fresh ones. The grouper's similarity threshold is configurable to tune sensitivity for your project.
+
+## Resolution Strategy Inference
+
+When Sentinel suggests a failure pattern from grouped incidents, it infers the most likely resolution strategy from error message keywords:
+
+| Strategy | Triggered By | Action |
+|---|---|---|
+| `retry` | timeout, network, ECONNREFUSED | Retry with backoff |
+| `fallback` | unavailable, service down, 503 | Use alternative path |
+| `fix-data` | validation, invalid, required, 404 | Correct the data |
+| `fix-code` | General code errors | Change the code |
+| `rollback` | regression, revert, broke after deploy | Roll back deployment |
+| `config-change` | config, environment variable, missing key | Update configuration |
+| `scale-up` | out of memory, OOM, capacity | Add resources |
+| `investigate` | Mixed error types, unclear pattern | Needs human triage |
+| `ignore` | Known non-issues | Suppress notifications |
+| `escalate` | permission, 403, unauthorized | Needs authorization change |

package/dist/university-content/notes/N-para-301-sync-and-maintenance.md

@@ -0,0 +1,57 @@
+---
+id: N-para-301-sync-and-maintenance
+title: Sync & Maintenance
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigm-sync-for
+  - paradigm-scan-for
+  - ai-maintenance-protocol
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Sync & Maintenance
+
+Paradigm metadata needs to stay synchronized with the actual code. As developers add features, rename files, and refactor modules, the `.purpose` files, `portal.yaml`, and `navigator.yaml` can drift out of date. Paradigm provides two key maintenance commands to keep everything aligned.
+
+**`paradigm sync`** synchronizes metadata with the codebase. It detects when source files have moved, when new files appear that should be registered, and when existing registrations point to files that no longer exist. Think of it as a reconciliation between what Paradigm knows about and what actually exists on disk.
+
+**`paradigm scan`** performs a full rebuild of the index and regenerates `navigator.yaml`. This is a heavier operation that re-reads every `.purpose` file, rebuilds the symbol graph, and produces a fresh structure map. Run scan when the index feels stale, when navigator.yaml is missing, or after bulk operations like branch merges that may have changed many files at once.
+
+```bash
+# Light sync -- detect drift and reconcile
+$ paradigm sync
+
+# Full rebuild -- regenerate everything from .purpose files
+$ paradigm scan
+```
+
+Beyond these commands, the **AI Maintenance Protocol** defines when and how to update Paradigm files during development:
+
+| Change Type | Required Paradigm Update |
+|---|---|
+| Add a feature | Create or update the nearest `.purpose` file with `#component` |
+| Add a protected route | Update `portal.yaml` with the new route and its `^gates` |
+| Add an event or signal | Add `!signal` to the emitting component's `.purpose` file |
+| Add a multi-step process | Document as `$flow` with ordered steps |
+| Rename or delete a symbol | Update all `.purpose` files that reference it |
+| Discover a pattern or antipattern | Capture with `paradigm_wisdom_record` |
+| Add a cross-cutting rule | Create `~aspect` with required code anchors |
+
+The maintenance protocol is not optional -- it is how the metadata stays valuable. Stale metadata is worse than no metadata because it actively misleads. When `.purpose` files accurately reflect the code, AI agents can navigate efficiently, ripple analysis produces correct results, and the doctor finds real issues instead of false positives.
+
+A practical rhythm for maintenance:
+1. **Before work**: `paradigm_wisdom_context` and `paradigm_ripple` on symbols you will touch
+2. **During work**: Update `.purpose` files as you go, not after
+3. **After work**: Run `paradigm doctor` to catch any drift, record wisdom if applicable
+4. **Periodically**: Run `paradigm scan` to rebuild the full index

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.