@a-company/paradigm 3.1.5 → 3.5.0

package/dist/university-content/courses/para-201.json

@@ -6,13 +6,15 @@
     {
       "id": "flows-deep-dive",
       "title": "Flows in Depth",
-      "content": "## When to Create a Flow\n\nNot every process needs a `$flow`. The rule of thumb is: **create a flow when logic spans three or more components in a specific order**. A two-component interaction (service A calls service B) is simple enough to document in the component's `.purpose` entry. But once a third component enters the picture — and the order matters — a flow captures the choreography that no single component can describe.\n\nConsider these scenarios:\n- User clicks \"Buy\" → cart validates → payment charges → order creates → email sends. That is four components in sequence. This needs a `$checkout-flow`.\n- A cron job triggers → data fetches → report generates → file uploads → Slack notifies. Five components. This needs a `$daily-report-flow`.\n- A controller calls a service which returns data. Two components, no sequence ambiguity. This does NOT need a flow.\n\n## Flow Step Structure\n\nEach step in a flow is a `component + action` pair. The component references a `#component` defined in a `.purpose` file, and the action describes what that component does in this step:\n\n```yaml\nflows:\n  $onboarding:\n    description: New user setup from registration to first project\n    steps:\n      - component: \"#auth-handler\"\n        action: create-account\n        description: Validates email, hashes password, creates user record\n      - component: \"#email-service\"\n        action: send-welcome\n        description: Sends welcome email with verification link\n      - component: \"#project-service\"\n        action: create-default-project\n        description: Creates a starter project for the new user\n      - component: \"#notification-service\"\n        action: notify-team\n        description: Alerts the team Slack channel about the new signup\n    signals: [\"!user-created\", \"!welcome-email-sent\"]\n    gates: []\n```\n\nThe `description` on each step is optional but valuable — it tells AI agents what happens at each point without reading the source code.\n\n## Documenting Flows in .purpose Files\n\nFlows are defined in the `flows` section of a `.purpose` file, usually in the directory of the *initiating* component. If the checkout flow starts in the cart module, define `$checkout-flow` in `src/cart/.purpose`. The flow references components from other directories — that is expected and correct.\n\nYou can also reference flows from component definitions:\n\n```yaml\ncomponents:\n  #cart-service:\n    description: Shopping cart management\n    flows: [\"$checkout-flow\", \"$cart-abandonment-flow\"]\n```\n\nThis bidirectional referencing lets `paradigm_ripple` calculate the full impact when you modify a component — it knows which flows pass through it.\n\n## Flow Validation\n\nParadigm provides `paradigm_flow_validate` to check that your flow definitions are consistent:\n\n```\nparadigm_flow_validate({ flowId: \"$checkout-flow\", checkImplementation: true })\n```\n\nWith `checkImplementation: true`, the validator goes beyond schema checks — it verifies that the referenced components exist in `.purpose` files, that the actions are implemented in the codebase, and that any signals listed are actually emitted. This catches drift between documentation and code.\n\nYou can also validate all flows at once by omitting the `flowId` parameter. This is useful as a pre-commit check or CI step.\n\n## Flows Are Documentation, Not Orchestration\n\nA critical distinction: flows describe *what happens*, not *how to make it happen*. They are not workflow engines or saga orchestrators. Your code still calls services, handles errors, and manages state however it needs to. The flow definition is metadata that helps humans and AI agents understand the sequence — it does not replace your implementation.",
+      "content": "## When to Create a Flow\n\nNot every process needs a `$flow`. The rule of thumb is: **create a flow when logic spans three or more components in a specific order**. A two-component interaction (service A calls service B) is simple enough to document in the component's `.purpose` entry. But once a third component enters the picture — and the order matters — a flow captures the choreography that no single component can describe.\n\nConsider these scenarios:\n- User clicks \"Buy\" → cart validates → payment charges → order creates → email sends. That is four components in sequence. This needs a `$checkout-flow`.\n- A cron job triggers → data fetches → report generates → file uploads → Slack notifies. Five components. This needs a `$daily-report-flow`.\n- A controller calls a service which returns data. Two components, no sequence ambiguity. This does NOT need a flow.\n\n## Flow Step Structure\n\nEach step in a flow is a `component + action` pair. The component references a `#component` defined in a `.purpose` file, and the action describes what that component does in this step:\n\n```yaml\nflows:\n  $onboarding:\n    description: New user setup from registration to first project\n    steps:\n      - component: \"#auth-handler\"\n        action: create-account\n        description: Validates email, hashes password, creates user record\n      - component: \"#email-service\"\n        action: send-welcome\n        description: Sends welcome email with verification link\n      - component: \"#project-service\"\n        action: create-default-project\n        description: Creates a starter project for the new user\n      - component: \"#notification-service\"\n        action: notify-team\n        description: Alerts the team Slack channel about the new signup\n    signals: [\"!user-created\", \"!welcome-email-sent\"]\n    gates: []\n```\n\nThe `description` on each step is optional but valuable — it tells AI agents what happens at each point without reading the source code.\n\n## Documenting Flows in .purpose Files\n\nFlows are defined in the `flows` section of a `.purpose` file, usually in the directory of the *initiating* component. If the checkout flow starts in the cart module, define `$checkout-flow` in `src/cart/.purpose`. The flow references components from other directories — that is expected and correct.\n\nYou can also reference flows from component definitions:\n\n```yaml\ncomponents:\n  #cart-service:\n    description: Shopping cart management\n    flows: [\"$checkout-flow\", \"$cart-abandonment-flow\"]\n```\n\nThis bidirectional referencing lets `paradigm_ripple` calculate the full impact when you modify a component — it knows which flows pass through it.\n\n## Flow Validation\n\nParadigm provides `paradigm_flow_validate` to check that your flow definitions are consistent:\n\n```\nparadigm_flow_validate({ flowId: \"$checkout-flow\", checkImplementation: true })\n```\n\nWith `checkImplementation: true`, the validator goes beyond schema checks — it verifies that the referenced components exist in `.purpose` files, that the actions are implemented in the codebase, and that any signals listed are actually emitted. This catches drift between documentation and code.\n\nYou can also validate all flows at once by omitting the `flowId` parameter. This is useful as a pre-commit check or CI step.\n\n## Circular Dependency Detection\n\nWhen flows reference each other via `relatedFlows` or step-level `$flow` symbols, they form a dependency graph. Paradigm automatically detects circular dependencies in this graph using depth-first search.\n\nA circular dependency looks like this:\n\n```yaml\n$checkout-flow:\n  relatedFlows: [$payment-flow]\n$payment-flow:\n  relatedFlows: [$checkout-flow]  # Creates a cycle!\n```\n\nWhen you run `paradigm_flow_validate({})` (validate all flows), the output includes a `circularDependencies` section:\n\n```\n⚠ Circular Dependencies (1)\n\n  $checkout-flow → $payment-flow → $checkout-flow\n\n  Resolution: Break the cycle by extracting shared logic into a\n  separate flow, or remove one direction of the dependency.\n```\n\nTo resolve circular dependencies:\n1. **Extract shared logic** into a new flow that both original flows reference\n2. **Remove one direction** if only one flow truly depends on the other\n3. **Replace with signals** — use `!signal` communication instead of direct flow references\n\nCircular dependencies are not just a documentation problem — they indicate architectural coupling that can lead to cascading failures and maintenance difficulty.\n\n## Flows Are Documentation, Not Orchestration\n\nA critical distinction: flows describe *what happens*, not *how to make it happen*. They are not workflow engines or saga orchestrators. Your code still calls services, handles errors, and manages state however it needs to. The flow definition is metadata that helps humans and AI agents understand the sequence — it does not replace your implementation.",
       "keyConcepts": [
         "Create flows when 3+ components are involved in sequence",
         "Steps are component + action pairs",
         "Define flows in the .purpose file of the initiating component",
         "paradigm_flow_validate checks consistency with codebase",
-        "Flows are documentation, not orchestration code"
+        "Circular dependency detection catches cycles in flow relatedFlows references",
+        "Flows are documentation, not orchestration code",
+        "'paradigm flow diagram $flowId' generates Mermaid flowcharts — gates as diamonds, actions as rectangles, signals as rounded boxes"
       ],
       "quiz": [
         {
@@ -66,6 +68,19 @@
           },
           "correct": "C",
           "explanation": "Flows are documentation, not orchestration. They describe the sequence of operations for humans and AI agents to understand. Your code still handles the actual service calls, error handling, and state management however you choose to implement it."
+        },
+        {
+          "id": "q5",
+          "question": "`$checkout-flow` lists `relatedFlows: [$payment-flow]` and `$payment-flow` lists `relatedFlows: [$checkout-flow]`. What does `paradigm_flow_validate` report?",
+          "choices": {
+            "A": "No issues — bidirectional references are valid",
+            "B": "A circular dependency: $checkout-flow → $payment-flow → $checkout-flow",
+            "C": "A missing step error — related flows must appear as steps",
+            "D": "A naming violation — flows cannot reference each other",
+            "E": "A warning about duplicate flow definitions"
+          },
+          "correct": "B",
+          "explanation": "When flows reference each other in a cycle via relatedFlows, Paradigm detects it as a circular dependency using depth-first search. The resolution is to extract shared logic into a third flow, remove one direction of the dependency, or replace direct flow references with signal-based communication."
         }
       ]
     },
@@ -214,6 +229,88 @@
         }
       ]
     },
+    {
+      "id": "aspect-graph",
+      "title": "The Aspect Graph",
+      "content": "## v3.5 Aspect Definition Fields\n\nParadigm v3.5 extends the aspect definition with structured fields that transform aspects from simple tagged rules into first-class graph nodes. Every aspect can now carry a `value`, a `category`, a `severity`, typed `edges` to other symbols, and `lore` references linking the aspect to project history.\n\nHere is a complete v3.5 aspect definition:\n\n```yaml\naspects:\n  ~token-expiry-24h:\n    description: JWT access tokens expire after 24 hours\n    value: \"24h\"\n    category: configuration\n    severity: high\n    anchors:\n      - src/auth/jwt.ts:18-22\n    applies-to: [\"#auth-middleware\", \"#token-refresh-handler\"]\n    edges:\n      - symbol: \"^authenticated\"\n        relation: enforced-by\n      - symbol: \"~refresh-token-7d\"\n        relation: related-to\n      - symbol: \"~session-timeout-30m\"\n        relation: supersedes\n    lore:\n      - L-2026-01-15-002\n      - L-2026-02-10-001\n    tags: [security, auth, configuration]\n```\n\nThe **value** field captures the aspect's concrete value — a number, duration, threshold, or configuration string. This makes aspects searchable by their actual content, not just their description.\n\nThe **category** field classifies the aspect into one of five types:\n- `rule` — A behavioral rule that code must follow (e.g., \"all API responses must include a request ID\")\n- `decision` — An architectural decision captured as an aspect (e.g., \"use RS256 for JWT signing\")\n- `constraint` — A hard limitation that cannot be violated (e.g., \"maximum 100 items per page\")\n- `configuration` — A configurable value that may change across environments (e.g., \"JWT expiry is 24 hours\")\n- `invariant` — A condition that must always hold true (e.g., \"user balance is never negative\")\n\nThe **severity** field indicates the impact of violating or changing the aspect: `low`, `medium`, `high`, or `critical`. This drives prioritization in drift detection and heatmap analysis.\n\nThe **edges** array defines explicit relationships to other symbols. Each edge has a `symbol` (the target) and a `relation` (the relationship type). Five relation types are supported:\n- `enforced-by` — The aspect is enforced by the target (e.g., a gate, a middleware)\n- `depends-on` — The aspect depends on the target existing or functioning\n- `contradicts` — The aspect conflicts with the target (useful for flagging tensions)\n- `supersedes` — The aspect replaces or overrides the target\n- `related-to` — A general association without directional semantics\n\nThe **lore** array references lore entry IDs that provide historical context for the aspect — when it was introduced, why it was changed, what incidents led to its creation.\n\n## The SQLite Graph Engine\n\nAspect definitions live in YAML `.purpose` files — that is the source of truth. But querying a graph across dozens of YAML files is slow and awkward. Paradigm v3.5 introduces a SQLite graph database at `.paradigm/aspect-graph.db` that materializes the aspect graph for fast querying.\n\nThis database is a **derived build artifact**. It is rebuilt from scratch every time you run `paradigm_reindex`. You should never edit it directly — any changes would be overwritten on the next reindex. The YAML files remain the authoritative source; the SQLite database is a read-optimized cache.\n\nThe materialization pipeline runs in order: `openAspectGraph` creates or opens the database, `materializeAspects` writes all aspect and anchor data, `materializeLoreLinks` connects aspects to lore entries, `inferLoreEdges` creates implicit edges from shared lore references, and `closeAspectGraph` finalizes the database.\n\n## Edge Origins\n\nNot all edges are created equal. The graph tracks three edge origins:\n\n- **explicit** — Edges declared in the YAML `edges` field. These are intentional, human-authored relationships with full confidence.\n- **inferred** — Edges derived from `applies-to` references. When an aspect applies to a component, the system creates an inferred edge with weight 0.5 and relation `related-to`. These have lower confidence because they are computed, not declared.\n- **learned** — Edges discovered from lore overlap. When two aspects share lore references, the system infers a relationship. Learned edges have the lowest initial weight but can strengthen through confirmation.\n\nWhen querying the graph, you can filter by origin to see only the relationships you trust most, or include all origins for a complete picture.\n\n## Three-Tier Search\n\nThe aspect search system uses a three-tier strategy that improves over time:\n\n**Tier 1: Learned Mappings.** Before doing any text search, the system checks `search_weights` — a table of query-to-aspect mappings built from previous confirmed searches. If you searched for \"jwt expiry\" last week and confirmed `~token-expiry-24h` as the result, that mapping is stored. The next time anyone searches \"jwt expiry,\" the learned mapping returns the result instantly with high confidence.\n\n**Tier 2: FTS5 Full-Text Search.** If no learned mapping matches (or the confidence is below threshold), the system falls back to SQLite FTS5 full-text search across aspect descriptions, values, categories, and tags. FTS5 provides ranked results with relevance scoring.\n\n**Tier 3: Levenshtein Fuzzy Matching.** If FTS5 returns no results, the system tries fuzzy matching using Levenshtein distance. This catches typos and approximate queries — searching for \"tockn expry\" will still find `~token-expiry-24h` if the edit distance is small enough.\n\nThe tiers are tried in order. The first tier to return results wins. This means the system gets faster and more accurate over time as learned mappings accumulate.\n\n## The Learning Loop\n\nThe search learning loop works as follows:\n\n1. **Search** — You call `paradigm_aspect_search({ query: 'jwt expiry' })` and receive ranked results from whichever tier matched.\n2. **Select** — You pick the result you want and use it (e.g., `paradigm_aspect_get({ aspectId: 'token-expiry-24h' })`).\n3. **Confirm** — You call `paradigm_aspect_confirm({ query: 'jwt expiry', aspectId: 'token-expiry-24h' })` to tell the system your selection was correct.\n4. **Weights Updated** — The confirmed aspect gets +1.0 weight for that query. All other results that were returned for the same query get a decay multiplier of *0.95 applied to their weights. This self-correcting mechanism ensures that the best result rises to the top while alternatives gradually fade.\n5. **Future Searches Improve** — The next search for \"jwt expiry\" hits Tier 1 immediately, returning the learned mapping without needing FTS5 or fuzzy matching.\n\nOver time, the search system learns the vocabulary of your project — which terms map to which aspects — making discovery faster for every team member and agent.\n\n## The Seven MCP Tools\n\nParadigm v3.5 adds seven MCP tools for aspect graph interaction:\n\n**`paradigm_aspect_search`** — Search aspects using the three-tier system. Returns ranked results with scores and the tier that matched. Always call `paradigm_aspect_confirm` after selecting a result to feed the learning loop.\n\n**`paradigm_aspect_get`** — Get full details for an aspect: description, category, severity, value, anchor snippets (the actual code at anchor locations), graph edges, and linked lore entries. This is the deep-dive tool after search narrows the field.\n\n**`paradigm_aspect_graph`** — Get the subgraph neighborhood of a symbol. Pass a symbol and a hop count, and it returns all aspects and edges within that radius. Useful for understanding how aspects cluster around components.\n\n**`paradigm_aspect_heatmap`** — Get the most-accessed aspects ranked by usage frequency. The heatmap tracks four access types: `search` (found via search), `ripple` (encountered during ripple analysis), `navigate` (found via navigation), and `direct` (accessed by ID). This reveals which aspects are central to the project and which might be under-utilized.\n\n**`paradigm_aspect_suggest_scan`** — Scan a source file for undocumented aspects. The scanner detects magic numbers, hardcoded strings, rate limits, time values, environment variable checks, feature flags, and regex patterns. Each suggestion includes the line number, the detected value, and a proposed aspect definition. This is the discovery tool for finding rules that exist in code but are not yet documented.\n\n**`paradigm_aspect_drift`** — Check aspect anchors for content drift. The system computes SHA-256 hashes of the code at each anchor's line range and compares them against the hashes stored at the last scan. If the code has changed, the anchor is flagged as drifted. This catches silent changes to enforcement code that could invalidate an aspect's guarantees.\n\n**`paradigm_aspect_confirm`** — Confirm a search result to improve future search quality. This is the feedback mechanism for the learning loop — it updates `search_weights` with +1.0 for the selected result and applies *0.95 decay to alternatives.\n\n## Drift Detection\n\nDrift detection uses SHA-256 content hashing. When `paradigm_reindex` runs, it reads the code at each anchor's line range and stores a hash. When you later call `paradigm_aspect_drift`, it re-reads the current code and compares hashes. A mismatch means the code changed since the last index — the aspect may no longer be accurately anchored.\n\nDrift is not always a problem. If someone added a comment to the enforcement code, the hash changes but the aspect is still valid. But if someone refactored the rate limiter from 100 requests/minute to 500 requests/minute, the `~rate-limit-100` aspect is now stale. Drift detection catches both cases and lets you decide which need action.\n\n## Auto-Suggest Scanning\n\nThe `paradigm_aspect_suggest_scan` tool analyzes source files for patterns that should be documented as aspects but are not. It detects:\n\n- **Magic numbers** — Numeric literals that represent thresholds, limits, or configuration values\n- **Hardcoded strings** — String literals that represent URLs, paths, keys, or identifiers\n- **Rate limits** — Patterns like `rateLimit(100)` or `maxRequests: 50`\n- **Time values** — Durations like `24 * 60 * 60 * 1000` or `'30m'` or `setTimeout(fn, 5000)`\n- **Environment checks** — `process.env.NODE_ENV`, `std::env::var()`, or similar patterns\n- **Feature flags** — Patterns like `isEnabled('feature-name')` or `if (features.newCheckout)`\n- **Regex patterns** — Regular expressions that encode business rules or validation logic\n\nEach suggestion includes the file path, line number, detected value, a proposed aspect ID, and a draft category. You review the suggestions, accept the ones worth documenting, and discard the rest. This is how teams discover the implicit rules hiding in their codebase.",
+      "keyConcepts": [
+        "v3.5 adds value, category, severity, edges, and lore fields to aspect definitions",
+        "Five aspect categories: rule, decision, constraint, configuration, invariant",
+        "SQLite graph at .paradigm/aspect-graph.db is a derived artifact rebuilt by paradigm_reindex",
+        "Three edge origins: explicit (YAML), inferred (applies-to), learned (lore overlap)",
+        "Three-tier search: learned mappings, FTS5 full-text, Levenshtein fuzzy",
+        "Learning loop: search, select, confirm, weights update, future searches improve",
+        "Seven new MCP tools for search, detail, graph, heatmap, suggest, drift, and confirm",
+        "Drift detection uses SHA-256 hashing of code at anchor line ranges"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "What is the correct order of tiers in aspect search?",
+          "choices": {
+            "A": "FTS5 full-text search, then learned mappings, then Levenshtein fuzzy",
+            "B": "Levenshtein fuzzy, then FTS5 full-text search, then learned mappings",
+            "C": "Learned mappings, then FTS5 full-text search, then Levenshtein fuzzy",
+            "D": "Learned mappings, then Levenshtein fuzzy, then FTS5 full-text search",
+            "E": "All three tiers run in parallel and the highest-scoring result wins"
+          },
+          "correct": "C",
+          "explanation": "The three-tier search system tries tiers in order: Tier 1 (learned mappings from confirmed searches), Tier 2 (FTS5 full-text search across descriptions, values, categories, and tags), and Tier 3 (Levenshtein fuzzy matching for typo tolerance). The first tier to return results wins, which means learned mappings provide the fastest path when available."
+        },
+        {
+          "id": "q2",
+          "question": "A developer confirms a search result via paradigm_aspect_confirm. What happens to the search weights?",
+          "choices": {
+            "A": "All results for the query are removed and only the confirmed one remains",
+            "B": "The confirmed aspect gets +1.0 weight and all other results for the same query decay by *0.95",
+            "C": "The confirmed aspect gets +0.5 weight and nothing happens to other results",
+            "D": "All results for the query get +1.0 weight to reinforce the entire result set",
+            "E": "The confirmed aspect is pinned permanently and can never be overridden"
+          },
+          "correct": "B",
+          "explanation": "When a search result is confirmed, the selected aspect receives +1.0 weight for that query, reinforcing the mapping. All other results that were returned for the same query receive a *0.95 decay multiplier, gradually reducing their weight. This self-correcting mechanism ensures the best result rises to the top over time while alternatives fade without being immediately removed."
+        },
+        {
+          "id": "q3",
+          "question": "Which aspect category is appropriate for 'JWT expiry is 24 hours'?",
+          "choices": {
+            "A": "rule — it defines a behavioral rule that code must follow",
+            "B": "decision — it captures an architectural decision",
+            "C": "constraint — it is a hard limitation that cannot be violated",
+            "D": "configuration — it is a configurable value that may change across environments",
+            "E": "invariant — it is a condition that must always hold true"
+          },
+          "correct": "D",
+          "explanation": "A JWT expiry duration is a configuration value — it defines a specific setting (24 hours) that could reasonably differ between environments (development might use shorter expiry, production longer). Constraints are hard limitations that cannot be changed without breaking things. Rules are behavioral patterns. Decisions capture why something was chosen. Configuration captures what value was set."
+        },
+        {
+          "id": "q4",
+          "question": "What does paradigm_aspect_drift detect?",
+          "choices": {
+            "A": "When aspect definitions in YAML have syntax errors",
+            "B": "When aspects are referenced by symbols that no longer exist",
+            "C": "When the code at anchored line ranges has changed since the last scan, detected via SHA-256 hash comparison",
+            "D": "When aspects have been moved to a different .purpose file",
+            "E": "When aspect edges reference symbols that have been renamed"
+          },
+          "correct": "C",
+          "explanation": "Drift detection works by comparing SHA-256 hashes of the code at each anchor's line range. During paradigm_reindex, the system hashes the code at every anchor location. When paradigm_aspect_drift runs later, it re-reads the current code and compares hashes. A mismatch means the enforcement code changed — the aspect may need updating to reflect the current implementation."
+        },
+        {
+          "id": "q5",
+          "question": "An aspect has edges: [{symbol: '^authenticated', relation: 'enforced-by'}]. What does this mean?",
+          "choices": {
+            "A": "The aspect enforces the ^authenticated gate",
+            "B": "The ^authenticated gate depends on the aspect",
+            "C": "The aspect is enforced by the ^authenticated gate — the gate is the mechanism that ensures the aspect holds",
+            "D": "The aspect contradicts the ^authenticated gate",
+            "E": "The aspect and ^authenticated gate are the same thing expressed differently"
+          },
+          "correct": "C",
+          "explanation": "The 'enforced-by' relation means the target symbol is the mechanism that enforces the aspect. In this case, the ^authenticated gate is what ensures the aspect's rule holds true. This is a common pattern — aspects define what must be true, and gates define the checkpoints that enforce those truths. The edge makes this relationship explicit and queryable in the graph."
+        }
+      ]
+    },
     {
       "id": "portal-protocol",
       "title": "The Portal Protocol",
@@ -223,7 +320,9 @@
         "Four steps: ask Paradigm, add to portal.yaml, implement, test gate failures",
         "paradigm_gates_for_route suggests gates based on existing patterns",
         "Implementation must match the check expression in portal.yaml",
-        "Test both the pass path and the fail path"
+        "Test both the pass path and the fail path",
+        "paradigm portal test --gate introspects lock key expressions to auto-generate test fixtures",
+        "paradigm portal export outputs gate/route config as json, csv, or markdown"
       ],
       "quiz": [
         {

package/dist/university-content/courses/para-301.json

@@ -402,13 +402,15 @@
     {
       "id": "sentinel-observability",
       "title": "Sentinel & Observability",
-      "content": "## Sentinel & Observability\n\nParadigm 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.\n\nIncidents 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`.\n\n```\nparadigm_sentinel_record({\n  error: {\n    message: \"Stripe API returned 429: rate limited\",\n    type: \"RateLimitError\",\n    code: \"STRIPE_429\"\n  },\n  symbols: {\n    component: \"#payment-service\",\n    flow: \"$checkout-flow\",\n    gate: \"^authenticated\"\n  },\n  environment: \"production\",\n  service: \"api-server\"\n})\n```\n\n**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.\n\n```\nparadigm_sentinel_add_pattern({\n  id: \"stripe-rate-limit\",\n  name: \"Stripe Rate Limit\",\n  pattern: {\n    errorContains: [\"429\", \"rate limit\"],\n    symbols: { component: \"#payment-service\" }\n  },\n  resolution: {\n    description: \"Implement exponential backoff retry\",\n    strategy: \"retry\",\n    priority: \"high\"\n  }\n})\n```\n\nThe 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.\n\nSentinel 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.",
+      "content": "## Sentinel & Observability\n\nParadigm 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.\n\nIncidents 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`.\n\n```\nparadigm_sentinel_record({\n  error: {\n    message: \"Stripe API returned 429: rate limited\",\n    type: \"RateLimitError\",\n    code: \"STRIPE_429\"\n  },\n  symbols: {\n    component: \"#payment-service\",\n    flow: \"$checkout-flow\",\n    gate: \"^authenticated\"\n  },\n  environment: \"production\",\n  service: \"api-server\"\n})\n```\n\n**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.\n\n```\nparadigm_sentinel_add_pattern({\n  id: \"stripe-rate-limit\",\n  name: \"Stripe Rate Limit\",\n  pattern: {\n    errorContains: [\"429\", \"rate limit\"],\n    symbols: { component: \"#payment-service\" }\n  },\n  resolution: {\n    description: \"Implement exponential backoff retry\",\n    strategy: \"retry\",\n    priority: \"high\"\n  }\n})\n```\n\nThe 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.\n\nSentinel 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.\n\n## Incident Grouping\n\nWhen 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.\n\n## Resolution Strategy Inference\n\nWhen Sentinel suggests a failure pattern from grouped incidents, it infers the most likely resolution strategy from error message keywords:\n\n| Strategy | Triggered By | Action |\n|---|---|---|\n| `retry` | timeout, network, ECONNREFUSED | Retry with backoff |\n| `fallback` | unavailable, service down, 503 | Use alternative path |\n| `fix-data` | validation, invalid, required, 404 | Correct the data |\n| `fix-code` | General code errors | Change the code |\n| `rollback` | regression, revert, broke after deploy | Roll back deployment |\n| `config-change` | config, environment variable, missing key | Update configuration |\n| `scale-up` | out of memory, OOM, capacity | Add resources |\n| `investigate` | Mixed error types, unclear pattern | Needs human triage |\n| `ignore` | Known non-issues | Suppress notifications |\n| `escalate` | permission, 403, unauthorized | Needs authorization change |",
       "keyConcepts": [
         "Incidents map errors to symbols",
         "Failure pattern matching",
         "paradigm_sentinel_triage for filtering",
         "paradigm_sentinel_resolve for closing incidents",
-        "paradigm_sentinel_stats for health metrics"
+        "paradigm_sentinel_stats for health metrics",
+        "Incident grouping clusters similar incidents by symbol context, error similarity, and stack fingerprints",
+        "10 resolution strategies: retry, fallback, fix-data, fix-code, rollback, config-change, scale-up, investigate, ignore, escalate"
       ],
       "quiz": [
         {
@@ -426,16 +428,16 @@
         },
         {
           "id": "q2",
-          "question": "Which resolution strategies can be assigned to a Sentinel failure pattern?",
+          "question": "Which of the following is NOT a valid Sentinel resolution strategy?",
           "choices": {
-            "A": "Only 'fix-code' and 'ignore'",
-            "B": "retry, fallback, fix-data, fix-code, ignore, escalate",
-            "C": "low, medium, high, critical",
-            "D": "open, investigating, resolved",
-            "E": "implement, refactor, rollback"
+            "A": "rollback",
+            "B": "config-change",
+            "C": "auto-deploy",
+            "D": "investigate",
+            "E": "scale-up"
           },
-          "correct": "B",
-          "explanation": "Sentinel supports six resolution strategies: retry (try again), fallback (use alternative), fix-data (correct the data), fix-code (code change needed), ignore (known non-issue), and escalate (needs human attention). The other options are priority levels, incident statuses, and history change types respectively."
+          "correct": "C",
+          "explanation": "Sentinel supports 10 resolution strategies: retry, fallback, fix-data, fix-code, rollback, config-change, scale-up, investigate, ignore, and escalate. 'auto-deploy' is not a strategy — Sentinel suggests actions for humans to take, not automated deployments."
         },
         {
           "id": "q3",
@@ -461,7 +463,8 @@
         "paradigm scan for full index rebuild",
         "AI Maintenance Protocol",
         "Maintaining .purpose files alongside code changes",
-        "Practical maintenance rhythm"
+        "Practical maintenance rhythm",
+        "paradigm lint --auto-populate discovers undocumented source directories and drafts .purpose files"
       ],
       "quiz": [
         {

package/dist/university-content/courses/para-401.json

@@ -8,11 +8,12 @@
       "title": "MCP Tools Overview",
       "content": "## MCP Tools Overview\n\nModel 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.\n\nParadigm exposes approximately 15 tool modules, organized into four categories:\n\n### Discovery Tools\nThese tools help agents understand the codebase without reading files directly.\n\n- **`paradigm_search`** (~150 tokens) -- Fuzzy search across symbol names, descriptions, and tags. Supports type filtering (component, flow, gate, signal, aspect).\n- **`paradigm_navigate`** (~200 tokens) -- Three intents: `find` (symbol lookup), `explore` (area browsing), `context` (task-based discovery).\n- **`paradigm_ripple`** (~300 tokens) -- Dependency analysis showing what depends on a symbol, 1-5 levels deep.\n- **`paradigm_related`** (~200 tokens) -- All symbols connected to a given symbol, both upstream and downstream.\n\n### Knowledge Tools\nThese tools access the project's institutional memory.\n\n- **`paradigm_wisdom_context`** -- Retrieves preferences, antipatterns, and decisions for specified symbols.\n- **`paradigm_wisdom_record`** -- Captures new antipatterns or architectural decisions.\n- **`paradigm_wisdom_expert`** -- Identifies human experts for symbols or areas.\n- **`paradigm_history_context`** -- Retrieves implementation history for symbols.\n- **`paradigm_history_record`** -- Logs implementation events.\n- **`paradigm_history_fragility`** -- Checks stability scores.\n\n### Validation Tools\nThese tools verify metadata integrity.\n\n- **`paradigm_purpose_validate`** -- Validates `.purpose` files and optionally `portal.yaml`.\n- **`paradigm_flow_validate`** -- Validates flow definitions against the codebase.\n- **`paradigm_aspect_check`** -- Verifies that aspects have valid code anchors.\n\n### Management Tools\nThese tools modify Paradigm metadata.\n\n- **`paradigm_purpose_add_component`**, **`paradigm_purpose_add_signal`**, **`paradigm_purpose_add_flow`**, etc. -- Add symbols to `.purpose` files.\n- **`paradigm_portal_add_gate`**, **`paradigm_portal_add_route`** -- Manage `portal.yaml` gates and routes.\n- **`paradigm_purpose_rename`** -- Rename symbols across all `.purpose` files.\n- **`paradigm_tags`**, **`paradigm_tags_suggest`** -- Manage the tag bank.\n\n### Token Economics\n\nEvery tool call has a token cost. The general principle is that MCP queries are 5-20x cheaper than reading files:\n\n| Operation | Approximate Cost |\n|---|---|\n| `paradigm_status` | ~100 tokens |\n| `paradigm_search` | ~150 tokens |\n| `paradigm_navigate` | ~200 tokens |\n| `paradigm_ripple` | ~300 tokens |\n| Reading a small file | ~500 tokens |\n| Reading a large file | ~2000+ tokens |\n\nThe 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.\n\n### Practice Tools\n\nThese tools manage behavioral discipline and project memory.\n\n**Habits Tools:**\n- **`paradigm_habits_list`** -- List habit definitions with filters (category, trigger, severity, enabled status).\n- **`paradigm_habits_check`** -- Evaluate and record practice compliance. Triggers: `preflight`, `postflight`, `on-stop`, `on-commit`.\n- **`paradigm_habits_status`** -- Practice profile with compliance rates, category breakdowns, trends, and incident correlations.\n- **`paradigm_practice_context`** -- Proactive habit warnings before modifying symbols. Returns relevant habits and recent compliance rates.\n\n**Lore Tools:**\n- **`paradigm_lore_search`** -- Search lore entries by symbol, author, date range, tags, type, and review status.\n- **`paradigm_lore_record`** -- Record new entries (agent sessions, decisions, milestones, incidents, reviews).\n- **`paradigm_lore_get`** -- Fetch a single entry by ID with full detail.\n- **`paradigm_lore_update`** -- Update an existing entry's fields (title, summary, type, symbols, tags, learnings).\n- **`paradigm_lore_delete`** -- Delete an entry by ID. Requires `confirm: true` to prevent accidental deletion.\n- **`paradigm_lore_timeline`** -- Timeline overview with recent entries, hot symbols, and active authors.",
       "keyConcepts": [
-        "Four tool categories: discovery, knowledge, validation, management",
-        "Token economics of MCP vs file reads",
+        "Four tool categories: discovery, knowledge, validation, management — plus practice tools (habits + lore)",
+        "Token economics of MCP vs file reads — each tool description now includes approximate token cost",
         "paradigm_search, paradigm_navigate, paradigm_ripple as core discovery tools",
         "Management tools for .purpose and portal.yaml editing",
-        "5-20x token efficiency over file reads"
+        "5-20x token efficiency over file reads",
+        "Enhanced tool descriptions include return data shape, usage guidance, and token cost estimates"
       ],
       "quiz": [
         {
@@ -635,6 +636,59 @@
           "explanation": "The distinction is habit, not knowledge. Both masters and practitioners know the tools. The master has internalized the framework so deeply that reaching for paradigm_ripple before a modification is reflexive, not deliberate. The question ('what depends on this?') triggers the tool automatically."
         }
       ]
+    },
+    {
+      "id": "agent-interop",
+      "title": "Agent Interoperability",
+      "content": "## AGENTS.md and llms.txt\n\nParadigm generates two standard files that make projects accessible to any AI agent, regardless of which IDE or platform is used.\n\n### AGENTS.md — Universal Agent Instructions\n\nAGENTS.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:\n\n- **Symbol system** — the five operational symbols and conventions\n- **MCP tools reference** — when to use each tool and what it returns\n- **Workflow protocol** — before/after task checklists\n- **Commit conventions** — format with Symbols: trailer\n- **Session recovery** — how to pick up where a previous agent left off\n- **Habits compliance** — behavioral expectations at each workflow stage\n- **Lore recording** — when and how to record project history\n- **Session checkpoints** — crash recovery protocol\n\nRegenerate with: `paradigm sync agents`\n\nParadigm 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.\n\n### llms.txt — LLM-Readable Project Summary\n\nThe llms.txt standard provides a plain-text project summary optimized for LLM consumption. Unlike AGENTS.md (which contains instructions), llms.txt contains facts:\n\n- Project name and overview\n- Symbol table (prefixes, names, descriptions)\n- Key files from navigator.yaml\n- Defined flows and their triggers\n- Gates and protected routes\n- Conventions\n\nRegenerate with: `paradigm sync-llms`\n\nllms.txt is useful for RAG pipelines, chat interfaces, and any context where a quick project overview is needed without the full instruction set.\n\n### When to Use Which\n\n| File | Purpose | Audience | Content |\n|------|---------|----------|---------|\n| AGENTS.md | Agent instructions | AI agents working on the repo | How to behave, tools to use, conventions to follow |\n| llms.txt | Project summary | Any LLM consuming project info | What the project is, what exists, how it is structured |\n| CLAUDE.md | Claude-specific instructions | Claude Code / Claude API | Superset of AGENTS.md with Claude-specific features |\n\nAll 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.\n\n## Enhanced MCP Tool Descriptions\n\nEvery MCP tool description now includes three pieces of information that help agents make better decisions:\n\n1. **What it does** — the core functionality\n2. **What it returns** — the shape of the response data\n3. **Token cost** — approximate cost in tokens (~100 to ~400)\n\nThis 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.\n\n## The Fresh Context Principle\n\nWhen 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:\n\n1. **Agent reads AGENTS.md** — learns the symbol system, tools, and workflow\n2. **Agent calls `paradigm_session_recover`** — gets previous session breadcrumbs\n3. **Agent calls `paradigm_navigate` with context intent** — finds relevant code\n\nThis 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.",
+      "keyConcepts": [
+        "AGENTS.md is a universal AI agent instruction file generated by 'paradigm sync agents'",
+        "llms.txt is a plain-text project summary for LLM consumption, generated by 'paradigm sync-llms'",
+        "AGENTS.md contains instructions (how to behave), llms.txt contains facts (what exists)",
+        "Enhanced MCP tool descriptions include return data shape and token cost estimates",
+        "The Fresh Context Principle: orientation via AGENTS.md + session_recover + navigate costs ~500 tokens"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "A new AI agent is spawned in isolation to implement a feature. What is the most token-efficient orientation sequence?",
+          "choices": {
+            "A": "Read all .purpose files in the project",
+            "B": "Read AGENTS.md, call paradigm_session_recover, call paradigm_navigate with context intent",
+            "C": "Read package.json, then explore the src/ directory",
+            "D": "Call paradigm_search for every symbol type",
+            "E": "Read CLAUDE.md, then read every file in .paradigm/"
+          },
+          "correct": "B",
+          "explanation": "The Fresh Context Principle: AGENTS.md provides instructions and conventions, paradigm_session_recover provides previous session context, and paradigm_navigate with context intent provides task-relevant files. Total cost: ~500 tokens. Reading all .purpose files or exploring directories would cost thousands of tokens for the same information."
+        },
+        {
+          "id": "q2",
+          "question": "What is the key difference between AGENTS.md and llms.txt?",
+          "choices": {
+            "A": "AGENTS.md is for Claude, llms.txt is for other LLMs",
+            "B": "AGENTS.md contains instructions (how to behave), llms.txt contains facts (what exists)",
+            "C": "llms.txt replaces AGENTS.md in newer projects",
+            "D": "AGENTS.md is human-readable, llms.txt is machine-only",
+            "E": "They contain identical information in different formats"
+          },
+          "correct": "B",
+          "explanation": "AGENTS.md is prescriptive — it tells agents what tools to use, what conventions to follow, and what workflow to observe. llms.txt is descriptive — it tells agents what symbols exist, what flows are defined, and how the project is structured. Both serve distinct purposes and can coexist."
+        },
+        {
+          "id": "q3",
+          "question": "Why do enhanced MCP tool descriptions include token cost estimates?",
+          "choices": {
+            "A": "To bill agents for tool usage",
+            "B": "To enforce budget limits on agents",
+            "C": "So agents can make informed cost/benefit decisions when choosing between tools and file reads",
+            "D": "Token costs are required by the MCP specification",
+            "E": "To discourage agents from using expensive tools"
+          },
+          "correct": "C",
+          "explanation": "Token cost estimates enable agents to evaluate tool selection before calling. An agent deciding between paradigm_search (~150 tokens) and reading 5 files (~2500 tokens) can make an informed cost/benefit decision. The goal is efficiency, not restriction."
+        }
+      ]
     }
   ]
 }