@a-company/paradigm 5.37.11 → 6.0.2

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

@@ -0,0 +1,50 @@
+---
+id: N-para-301-fragility-tracking
+title: Fragility & Stability
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigmhistoryfragility
+  - stability-scores
+  - fragile-symbol-indicators
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Fragility & Stability
+
+Not all parts of a codebase are equally stable. Some symbols have been rock-solid for months, while others seem to break every time someone touches them. Paradigm's fragility tracking system quantifies this by analyzing the history log to produce **stability scores** for each symbol.
+
+The tool `paradigm_history_fragility` accepts an array of symbols and returns a stability assessment for each one. The score considers several factors: how frequently the symbol has been changed, how many rollbacks it has experienced, the ratio of fixes to features, and the recency of changes. A symbol that was implemented once six months ago and never touched again has high stability. A symbol that has been refactored three times in two weeks with one rollback is flagged as fragile.
+
+```
+paradigm_history_fragility({
+  symbols: ["#checkout-form", "#payment-service", "$onboarding"]
+})
+
+// Returns stability scores and warnings:
+// #checkout-form: stable (score: 0.92)
+// #payment-service: fragile (score: 0.34) -- 3 rollbacks in 30 days
+// $onboarding: moderate (score: 0.61) -- frequent refactors
+```
+
+Fragility information changes how you approach a task. When you are about to modify a fragile symbol, you should:
+
+1. **Read the full history** with `paradigm_history_context` to understand *why* it has been unstable
+2. **Check team wisdom** with `paradigm_wisdom_context` to see if there are known antipatterns or decisions about that area
+3. **Write more comprehensive tests** before making changes
+4. **Make smaller, incremental changes** rather than large refactors
+5. **Validate thoroughly** with `paradigm_history_validate` after implementation
+
+Refactor-heavy areas deserve special attention. If a symbol has a high count of `refactor` type events, it may indicate unclear requirements, poor initial design, or a component that is trying to do too much. The fragility system surfaces these patterns so you can address the root cause rather than adding another band-aid refactor.
+
+Stability scores are also useful for planning. When estimating effort for a feature that touches multiple symbols, fragile symbols should be weighted higher in your estimate. They are more likely to require debugging, testing, and potentially rolling back. The fragility check is a form of risk assessment that should happen before every non-trivial change.

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

@@ -0,0 +1,42 @@
+---
+id: N-para-301-history-system
+title: The History System
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - append-only-implementation-log
+  - paradigmhistoryrecord
+  - paradigmhistorycontext
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## The History System
+
+Paradigm maintains an append-only log of every implementation change in your project. This is not a replacement for git history -- it is a higher-level, symbol-aware record that tracks *what changed at the Paradigm level*, not just which lines of code were modified. Every time you implement a feature, fix a bug, or refactor a component, Paradigm can record that event against the symbols it affected.
+
+The primary tool for recording history is `paradigm_history_record`. When you call it, you specify three required fields: the **type** of change (`implement`, `refactor`, or `rollback`), the **symbols** affected (e.g., `["#payment-service", "$checkout-flow"]`), and a **description** of what was done. You can also specify an **intent** to further classify the change: `feature` for new capabilities, `fix` for bug repairs, `refactor` for structural improvements, `experimental` for exploratory changes, and `confirmed` for validated implementations.
+
+```
+paradigm_history_record({
+  type: "implement",
+  symbols: ["#payment-service", "!payment-completed"],
+  description: "Add Stripe webhook handler for payment confirmation",
+  intent: "feature",
+  commit: "a1b2c3d",
+  files: ["src/services/payment.ts", "src/handlers/webhook.ts"]
+})
+```
+
+To retrieve history for symbols before making changes, use `paradigm_history_context`. Pass in an array of symbols and you get back the recent implementation events, who worked on them, and how stable they have been. This is critical context -- before modifying `#payment-service`, you want to know if it was just refactored last week, if it has been the target of multiple rollbacks, or if it has been stable for months.
+
+The history log is append-only by design. Nothing is ever deleted or overwritten. This means you always have a complete timeline of how a symbol evolved. Rollback events do not erase the original implementation -- they add a new entry that says "this was rolled back and why." This immutability is what makes the history system trustworthy for fragility analysis and team wisdom.

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

@@ -0,0 +1,55 @@
+---
+id: N-para-301-navigation-system
+title: Codebase Navigation
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigmnavigate-with-three
+  - navigatoryaml-structure-map
+  - paradigmsearch-with-fuzzy
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Codebase Navigation
+
+Large codebases are expensive to explore token-by-token. Reading files costs roughly 500-2000 tokens each, and broad exploration can quickly eat through an AI agent's context window. Paradigm's navigation system solves this by providing efficient, symbol-aware lookup that costs only 100-200 tokens per query.
+
+The primary tool is `paradigm_navigate`, which supports three intents:
+
+**"find"** performs a direct symbol lookup. Give it a symbol like `#checkout-form` or a file path, and it returns the exact location in the codebase. This is the fastest way to go from a symbol name to its source file.
+
+```
+paradigm_navigate({ intent: "find", target: "#payment-service" })
+// Returns: src/services/payment.ts (defined in src/services/.purpose)
+```
+
+**"explore"** lets you browse a functional area of the codebase. Instead of looking for a specific symbol, you describe an area like "authentication" or "payments" and get back all the symbols, files, and structure in that domain.
+
+```
+paradigm_navigate({ intent: "explore", target: "authentication" })
+// Returns: gates, components, flows related to auth
+```
+
+**"context"** is task-based discovery. Describe what you want to accomplish, and the navigator returns the relevant files, symbols, and patterns you will need. This is the most powerful intent -- it answers "what do I need to know to complete this task?"
+
+```
+paradigm_navigate({ intent: "context", task: "add Apple Pay to checkout" })
+// Returns: #payment-service, $checkout-flow, #checkout-form,
+//          existing payment method patterns, relevant gates
+```
+
+Behind the scenes, navigation is powered by `navigator.yaml`, a generated structure map of your entire project. This file is created and updated by `paradigm scan` and contains the directory tree, symbol locations, and file classifications. You do not edit `navigator.yaml` directly -- it is regenerated from `.purpose` files.
+
+For fuzzy text search across symbol names, descriptions, and tags, use `paradigm_search`. This supports typo-tolerant matching, so searching for "paymnt" will still find `#payment-service`. You can filter by symbol type (component, flow, gate, signal, aspect) and control result limits.
+
+The general rule is: **MCP queries for discovery, file reads for implementation.** Use navigate and search to find what you need (~100-200 tokens), then read only the specific files required (~500-2000 tokens). Never broadly explore a codebase by reading directories when navigation tools are available.

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