@a-company/paradigm 5.28.0 → 5.34.0

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

@@ -0,0 +1,166 @@
+{
+  "id": "para-001",
+  "title": "PARA 001: Quick Start",
+  "description": "Get productive with Paradigm in 15 minutes. Initialize a project, meet your agent team, and build your first feature with orchestration. Hands-on from the first minute — theory comes later.",
+  "lessons": [
+    {
+      "id": "shift-setup",
+      "title": "Your First paradigm shift",
+      "content": "## Hands On in 60 Seconds\n\nOpen a terminal in any project directory and run:\n\n```bash\nparadigm shift\n```\n\nThat is it. One command, and your project is Paradigm-aware.\n\n### What Just Happened?\n\nLook at your directory. Several new files and a new folder appeared:\n\n```\n.paradigm/            ← Configuration, roster, tags, indexes\n  config.yaml         ← Project settings (name, discipline, enforcement)\n  roster.yaml         ← Your agent team\n  agents.yaml         ← Model tier assignments\n  tags.yaml           ← Tag taxonomy\nCLAUDE.md             ← Instructions for Claude Code\nAGENTS.md             ← Instructions for any AI agent\n.purpose              ← Root-level purpose file (describes your project)\n```\n\nEach file has a specific job:\n\n- **`.paradigm/config.yaml`** is the brain — it stores your project name, discipline (web, backend, mobile, etc.), enforcement level, and feature flags. Paradigm auto-detected your discipline from project markers like `package.json`, `Cargo.toml`, or `go.mod`.\n\n- **`CLAUDE.md`** and **`AGENTS.md`** are instruction files that AI tools read automatically. They are generated from your Paradigm configuration — you do not edit them by hand. When you change config, re-running `paradigm shift` regenerates them.\n\n- **`.purpose`** is the most important file type in Paradigm. It describes what code in a directory does using a structured format with **symbols** — you will learn all five symbol types in PARA 101. For now, just know that `.purpose` files are how AI agents understand your codebase.\n\n- **`roster.yaml`** lists which agents are on your team. More on this in the next lesson.\n\n### Hooks Are Installed\n\n`paradigm shift` also installed Git hooks and Claude Code hooks. These run automatically when you commit or finish a task, checking that your Paradigm metadata stays in sync with your code.\n\nBy default, hooks use **minimal enforcement** — they warn but never block. You will not lose work or get stuck. As you get comfortable, you can upgrade to balanced or strict enforcement (covered in PARA 301).\n\n### Try It: Explore What Was Created\n\nRun these commands to see what Paradigm set up:\n\n```bash\ncat .paradigm/config.yaml      # Your project configuration\ncat .paradigm/roster.yaml       # Your agent team\ncat .purpose                    # Root purpose file\n```\n\nNotice how `config.yaml` already knows your project type, and `roster.yaml` has agents selected for that type. This is the auto-detection at work — no manual configuration needed.",
+      "keyConcepts": [
+        "paradigm shift is the one-command setup — run it in any project directory",
+        ".paradigm/ directory holds configuration, roster, tags, and indexes",
+        "CLAUDE.md and AGENTS.md are auto-generated AI instruction files",
+        ".purpose files describe code directories using structured symbols",
+        "Hooks use minimal enforcement by default — warn but never block"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You just ran paradigm shift in a Node.js project. Which of the following was NOT created or configured automatically?",
+          "choices": {
+            "A": ".paradigm/config.yaml with discipline auto-detected from package.json",
+            "B": "CLAUDE.md with AI instructions derived from your configuration",
+            "C": "A comprehensive test suite for your existing code",
+            "D": "Git hooks for automated compliance checking",
+            "E": ".paradigm/roster.yaml with agents suited for a Node.js project"
+          },
+          "correct": "C",
+          "explanation": "paradigm shift sets up Paradigm metadata and tooling — it does not generate tests, modify your source code, or create application logic. It creates configuration, instruction files, hooks, and an agent roster. Testing is handled by the Vigil agent during orchestration, not during initialization."
+        },
+        {
+          "id": "q2",
+          "question": "After running paradigm shift, you edit .paradigm/config.yaml to change your enforcement level. Now CLAUDE.md is out of date. How do you update it?",
+          "choices": {
+            "A": "Edit CLAUDE.md manually to match your changes",
+            "B": "Run paradigm shift again — it regenerates CLAUDE.md from your updated config",
+            "C": "Delete CLAUDE.md and it will regenerate on the next commit",
+            "D": "Run paradigm sync to rebuild only the instruction files",
+            "E": "Both B and D would work — shift re-runs all steps including sync, while sync targets just the instruction files"
+          },
+          "correct": "E",
+          "explanation": "CLAUDE.md is a derived file — always generated from config, never hand-edited. Both paradigm shift (full re-run) and paradigm sync (targeted) will regenerate it. Use sync when you only changed config; use shift when you want the full pipeline (migrate, scan, hooks, etc.)."
+        },
+        {
+          "id": "q3",
+          "question": "A teammate says \"I ran paradigm shift but it broke my project — hooks are blocking my commits.\" This should not happen with default settings. What likely went wrong?",
+          "choices": {
+            "A": "paradigm shift always uses strict enforcement",
+            "B": "The project already had a config.yaml with enforcement level set to strict or balanced from a previous setup",
+            "C": "Hooks always block on the first run to teach discipline",
+            "D": "The teammate's Git version is incompatible with Paradigm hooks",
+            "E": "paradigm shift requires admin privileges to install hooks"
+          },
+          "correct": "B",
+          "explanation": "New projects default to minimal enforcement, which warns but never blocks. But paradigm shift is idempotent — if the project already had a .paradigm/config.yaml with a higher enforcement level, shift preserves that setting. The teammate's project was likely previously configured with balanced or strict enforcement. Check config.yaml and adjust enforcement.level if needed."
+        }
+      ]
+    },
+    {
+      "id": "meet-the-team",
+      "title": "Meet Your Agent Team",
+      "content": "## Your AI Team\n\nOpen `.paradigm/roster.yaml`. You will see a list of agents — your project's AI team. Each agent has a specific role, and the orchestrator assigns them to tasks based on what the task needs.\n\n### The 8 Core Agents\n\nEvery project gets these eight. They are the backbone of Paradigm's orchestration:\n\n| Agent | Role | What They Do |\n|-------|------|-------------|\n| **Architect** | Design | Plans multi-file changes, defines structure |\n| **Builder** | Implementation | Writes the code |\n| **Reviewer** | Quality | Two-stage review: spec compliance → code quality |\n| **Sage** | Advocacy | Represents the user's perspective, UX implications |\n| **Jinx** | Advocacy | Stress-tests assumptions, finds edge cases |\n| **Sentinel** | Security | Threat analysis, auth review, vulnerability scanning |\n| **Vigil** | Testing | Writes tests, checks coverage, validates edge cases |\n| **Doc** | Documentation | Maintains .purpose files and portal.yaml |\n| **Rune** | Compliance | Plans symbols before building, validates after |\n\n### Model Tiers\n\nNot every agent needs the most powerful (and expensive) model. Paradigm assigns agents to tiers:\n\n- **Tier 1 (opus)** — Architect, Sentinel. Complex reasoning, design decisions, threat analysis.\n- **Tier 2 (sonnet)** — Reviewer, Sage, Jinx, Doc, Rune. Balanced depth and speed.\n- **Tier 3 (haiku)** — Builder, Vigil. Fast, cost-effective for implementation and testing.\n\nThis is not a quality ranking — it is a complexity match. Building code is well-defined work that a fast model handles efficiently. Designing architecture requires deeper reasoning that benefits from a more capable model.\n\n### Specialized and Ecosystem Agents\n\nBeyond the 8 core agents, Paradigm has **54+ agents** total:\n\n- **Specialized agents** (~20) cover domains like mobile, database, DevOps, accessibility, performance, and internationalization. They are added to your roster when your project type matches.\n\n- **Ecosystem agents** (~26+) are language/platform-specific: Swift, TypeScript, Rust, Python ML, iOS, Android, etc. They accumulate knowledge through notebooks that transfer across projects.\n\nYou do not need to manage these manually. `paradigm shift` detected your project type and selected the right mix. You can view and customize your roster with:\n\n```bash\nparadigm agent list          # See your full roster\nparadigm agent activate <id> # Add an agent\nparadigm agent bench <id>    # Remove an agent\n```\n\n### The Maestro Model\n\nYou are **Maestro** — the orchestrator. When you give a task to Paradigm, you are not talking to one AI. You are conducting a team:\n\n1. **Rune** plans the symbols the task needs\n2. **Architect** designs the approach (for complex tasks)\n3. **Sentinel** reviews security implications (when auth or data is involved)\n4. **Builder** writes the code\n5. **Reviewer** checks spec compliance and code quality\n6. **Doc** updates .purpose files and Paradigm metadata\n7. **Rune** validates the symbols match the implementation\n\nNot every task uses every agent. A simple CSS fix might only need Builder. A new API endpoint might need Architect → Sentinel → Builder → Reviewer → Doc → Rune. The orchestrator decides based on the task.\n\n> **Going deeper:** PARA 401 covers orchestration mechanics (facets, handoffs, trigger patterns). PARA 701 covers the full agent roster, profiles, notebooks, and learning loops.",
+      "keyConcepts": [
+        "8 core agents are in every project: Architect, Builder, Reviewer, Sage, Jinx, Sentinel, Vigil, Doc, Rune",
+        "54+ total agents across three tiers: core, specialized, ecosystem",
+        "Model tiers match agent complexity: opus for design, sonnet for analysis, haiku for execution",
+        "paradigm shift auto-selects agents based on project type",
+        "You are Maestro — the human orchestrator conducting the agent team"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "Your project is a React frontend with no backend. Which of these agents would paradigm shift likely NOT include in your roster?",
+          "choices": {
+            "A": "Builder — every project needs code implementation",
+            "B": "A database specialist — there is no database in a frontend-only project",
+            "C": "Reviewer — code review is universal",
+            "D": "Rune — symbol compliance applies to all projects",
+            "E": "Sentinel — even frontend apps have security concerns (XSS, CSRF)"
+          },
+          "correct": "B",
+          "explanation": "Specialized agents like a database specialist are only rostered when the project type matches. A React frontend with no backend has no database layer, so database agents would not be selected. The 8 core agents (including Sentinel — frontend security matters) appear in every roster. Specialized and ecosystem agents are added based on detection."
+        },
+        {
+          "id": "q2",
+          "question": "The Architect uses opus (tier-1) while the Builder uses haiku (tier-3). A junior developer asks: \"Does that mean the builder writes worse code?\" How do you explain?",
+          "choices": {
+            "A": "Yes — tier-3 is lower quality, but it is faster and cheaper",
+            "B": "No — tiers match complexity, not quality. Architecture requires open-ended reasoning (opus). Building is well-defined implementation work where speed matters more (haiku).",
+            "C": "The tiers are just labels with no real difference",
+            "D": "The builder should be upgraded to opus for important features",
+            "E": "All agents should use the same model for consistency"
+          },
+          "correct": "B",
+          "explanation": "Model tier assignment is about matching the nature of the work, not ranking quality. Architectural design is open-ended — \"how should we structure this?\" benefits from deeper reasoning. Implementation is well-defined — \"write this function that does X\" benefits from speed. A fast model writing clearly specified code often produces better results than an overthinking model."
+        },
+        {
+          "id": "q3",
+          "question": "You want to add a DevOps specialist agent to your web project's roster. What command would you use?",
+          "choices": {
+            "A": "Edit roster.yaml by hand and add the agent definition",
+            "B": "paradigm agent activate devops — it adds the agent to your project roster",
+            "C": "paradigm shift --add-agent devops",
+            "D": "Re-run paradigm shift and hope it detects the need",
+            "E": "DevOps agents cannot be added to web projects"
+          },
+          "correct": "B",
+          "explanation": "paradigm agent activate <id> adds an agent to your project roster. This is the proper way to customize your team — the CLI updates roster.yaml, agents.yaml, and any related configuration atomically. While you could edit roster.yaml by hand, using the CLI ensures all related files stay in sync."
+        }
+      ]
+    },
+    {
+      "id": "build-something",
+      "title": "Build With the Team",
+      "content": "## Your First Orchestrated Task\n\nYou have a project set up and a team rostered. Now let's build something and see the full loop in action.\n\n### The Workflow\n\nEvery task in Paradigm follows this pattern:\n\n```\n1. Quick-check or plan   →  Is this task ready to build?\n2. Orchestrate           →  Assign the right agents\n3. Build                 →  Agents do the work\n4. Review                →  Spec compliance + code quality\n5. Commit                →  With symbol references in the message\n```\n\n### Step 1: Start with a Quick-Check\n\nBefore writing any code, ask the orchestrator if your task is ready:\n\n```\nparadigm_orchestrate_inline({\n  task: \"Add a health check endpoint at GET /health\",\n  mode: \"quick\"\n})\n```\n\nQuick-check runs two agents — **Jinx** stress-tests your assumptions (\"What should /health return? Just 200 OK, or system status?\") and a **reviewer** checks feasibility (\"Single file change, no auth needed\"). You get back either:\n\n- **GREENLIGHT** — go ahead and build\n- **ESCALATE** — needs full planning first\n\nA simple health endpoint would likely get GREENLIGHT.\n\n### Step 2: Build\n\nWith a greenlight, proceed to implementation. If you are using Claude Code with Paradigm, the agent team handles this automatically during orchestration. For a simple task:\n\n- **Builder** writes the endpoint\n- **Rune** ensures the component is documented in `.purpose`\n- **Reviewer** checks that the implementation matches Paradigm metadata\n\n### Step 3: Review the Output\n\nThe reviewer runs two stages:\n\n1. **Spec Compliance** — Is `#health-check` registered in a `.purpose` file? If a gate is needed, is it in `portal.yaml`? (A public health endpoint typically needs no gate.)\n2. **Code Quality** — Is the implementation clean, secure, and tested?\n\nIf Stage 1 fails, the reviewer stops and sends the task back. No point reviewing code quality of undocumented code.\n\n### Step 4: Commit\n\nParadigm uses structured commit messages with symbol references:\n\n```\nfeat(#health-check): add GET /health endpoint\n\n- Add #health-check component returning system status\n- No gate required — public endpoint\n\nSymbols: #health-check\n```\n\nThe `Symbols:` trailer is parsed by the post-commit hook for automatic history capture. This means every change is traceable to the symbols it affected.\n\n### What If You Skip Orchestration?\n\nYou can always write code directly without orchestrating. On minimal enforcement (the default), nothing blocks you. But you lose:\n\n- **Pre-build risk assessment** — Jinx might have caught an edge case you missed\n- **Automatic symbol planning** — Rune would have ensured `.purpose` coverage before you started\n- **Structured review** — the reviewer's two-stage protocol catches spec drift early\n- **Traceability** — the orchestration record links task → agents → decisions → code\n\nAs enforcement increases (balanced, strict), skipping orchestration triggers warnings or blocks. The system is designed to let you learn the value of orchestration before it becomes mandatory.\n\n### The Full Loop\n\nHere is the complete picture of what happens when you build a feature with Paradigm:\n\n```\nYou (Maestro)\n  │\n  ├─ \"Add a health check endpoint\"\n  │\n  ├─ Quick-check → GREENLIGHT\n  │\n  ├─ Rune → Symbol plan: #health-check component\n  │\n  ├─ Builder → src/routes/health.ts\n  │\n  ├─ Reviewer → Stage 1 pass, Stage 2 pass (3 findings: 0 blocking)\n  │\n  ├─ Doc → Updates .purpose with #health-check\n  │\n  ├─ Rune → Compliance report: 1 component, 1 aspect ✓\n  │\n  └─ Commit → feat(#health-check): add GET /health endpoint\n```\n\nThis loop — plan, build, review, document, validate — is the heartbeat of Paradigm development. Every feature, bug fix, and refactor follows the same pattern. The agents change, the complexity varies, but the loop is always the same.\n\n> **What's next:** PARA 101 covers the five symbols (#, $, ^, !, ~) and purpose files in depth. PARA 301 covers enforcement levels and operations. PARA 401 covers the orchestration mechanics behind what you just experienced.",
+      "keyConcepts": [
+        "Every task follows: quick-check → orchestrate → build → review → commit",
+        "Quick-check returns GREENLIGHT (proceed) or ESCALATE (needs full planning)",
+        "Reviewer runs two stages: spec compliance first, code quality only if spec passes",
+        "Commit messages use Symbols: trailer for automatic history tracking",
+        "Skipping orchestration is allowed on minimal enforcement but loses traceability and risk assessment"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You built a new API endpoint without running quick-check or orchestration. The code works fine. On minimal enforcement, what happens when you commit?",
+          "choices": {
+            "A": "The commit is blocked — orchestration is always required",
+            "B": "The commit succeeds but the stop hook warns that no orchestration record exists for the changed files",
+            "C": "Nothing — minimal enforcement has no checks",
+            "D": "The commit is reverted automatically",
+            "E": "Git rejects the commit because the pre-commit hook fails"
+          },
+          "correct": "B",
+          "explanation": "On minimal enforcement, orchestration-required is set to off, so the stop hook does not block. However, the purpose-coverage check (which is set to warn on minimal) may warn if you did not create a .purpose file for the new endpoint. The commit succeeds either way — minimal enforcement never blocks. But you have no orchestration record, no Rune compliance report, and no structured review."
+        },
+        {
+          "id": "q2",
+          "question": "During the build step, Rune creates a symbol plan with #health-check as a component. After the builder writes the code, Rune's compliance report says \"1 component, 0 aspects — blocking.\" Why is this a problem?",
+          "choices": {
+            "A": "Aspects are required for documentation completeness but have no real purpose",
+            "B": "Every component needs at least one aspect (rule, constraint, or configuration) — the 1:1 ratio means you must define what rules govern the health endpoint",
+            "C": "Rune made an error — health endpoints do not need aspects",
+            "D": "The builder should have created the aspect automatically",
+            "E": "This only matters on strict enforcement"
+          },
+          "correct": "B",
+          "explanation": "Rune enforces a 1:1 component-to-aspect ratio. Even a health endpoint has rules: response format, which checks it runs, timeout behavior, whether it includes dependency status. Defining an aspect like ~health-check-format forces you to document what the endpoint actually guarantees. This is not busywork — it is how Paradigm ensures every component has a documented contract."
+        },
+        {
+          "id": "q3",
+          "question": "The commit message for your feature reads: feat(#health-check): add GET /health endpoint. The Symbols: trailer says Symbols: #health-check. What does the post-commit hook do with this information?",
+          "choices": {
+            "A": "Nothing — the Symbols trailer is just for human readability",
+            "B": "It parses the Symbols trailer and records the commit in Paradigm's history system, linking the change to #health-check for traceability",
+            "C": "It validates that #health-check exists in a .purpose file",
+            "D": "It sends a notification to the agent team",
+            "E": "It automatically creates a changelog entry"
+          },
+          "correct": "B",
+          "explanation": "The post-commit hook parses the Symbols: trailer and records the commit in Paradigm's history system. This creates a traceable link: commit → symbols affected. Later, when someone asks \"what changed about #health-check?\" or runs paradigm_history_context, the answer includes this commit. The pre-commit hook handles index rebuilding; the post-commit hook handles history capture."
+        }
+      ]
+    }
+  ]
+}

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

@@ -56,16 +56,82 @@
         },
         {
           "id": "q4",
-          "question": "How many operational symbols does Paradigm define?",
+          "question": "You open a .purpose file and see symbols prefixed with #, $, ^, !, and ~. A new team member asks what the ~ symbol means. What do you tell them?",
           "choices": {
-            "A": "3",
-            "B": "4",
-            "C": "5",
-            "D": "7",
-            "E": "10"
+            "A": "~ marks a component — a documented code unit",
+            "B": "~ marks a flow — a multi-step process",
+            "C": "~ marks a gate — a security checkpoint",
+            "D": "~ marks a signal — an event notification",
+            "E": "~ marks an aspect — a cross-cutting rule, constraint, or configuration anchored to specific code"
+          },
+          "correct": "E",
+          "explanation": "The five symbols are: # (Component), $ (Flow), ^ (Gate), ! (Signal), and ~ (Aspect). Aspects represent cross-cutting concerns — rules, constraints, and configuration values that are anchored to specific lines of code. They are the only symbol type that requires code anchors."
+        }
+      ]
+    },
+    {
+      "id": "first-steps",
+      "title": "Your First Steps",
+      "content": "## Getting Started with Paradigm\n\nBefore diving into theory, let's get your hands dirty. This lesson walks through the concrete steps to set up Paradigm in a real project. You will encounter terms like *symbols*, *purpose files*, and *gates* — each gets its own deep-dive lesson later in this course. For now, focus on the workflow: initialize, document, scan, go.\n\n## Step 1: Initialize the Project\n\nRun `paradigm shift` in your project root. This creates the `.paradigm/` directory with a starter `config.yaml`:\n\n```bash\nparadigm shift\n```\n\n`paradigm shift` runs non-interactively by default — it auto-detects your discipline from project markers (`package.json`, `Cargo.toml`, `go.mod`, etc.), selects an appropriate agent roster, configures model tiers, installs hooks, and generates AI instruction files (CLAUDE.md, AGENTS.md). One command, full setup.\n\nYou can customize later with flags like `--verify` (health check) or `--workspace <name>` (multi-project workspace).\n\nAfter init, you will have:\n```\n.paradigm/\n  config.yaml    # Includes detected discipline and stack\n  tags.yaml\n  agents.yaml\n```\n\n## Step 2: Create Your First Purpose File\n\nPick a source directory that contains meaningful code — perhaps your main feature module or your API routes. Create a `.purpose` file:\n\n```yaml\nname: User Authentication\ndescription: Handles user login, registration, and session management\ncontext:\n  - Uses bcrypt for password hashing\n  - Sessions stored in Redis with 24h TTL\n  - Rate limited to 5 login attempts per minute\n\ncomponents:\n  #auth-handler:\n    description: POST /auth/login and POST /auth/register endpoints\n    file: auth.ts\n    tags: [feature, auth]\n    signals: [\"!login-success\", \"!login-failed\"]\n    gates: [\"^authenticated\"]\n\n  #session-manager:\n    description: Creates and validates user sessions in Redis\n    file: session.ts\n    tags: [state, auth]\n```\n\nStart small. You do not need to document every file on day one. Begin with the most important module and expand over time.\n\n## Step 3: Set Up portal.yaml (If Needed)\n\nIf your application has any protected endpoints, create `portal.yaml` at the project root:\n\n```yaml\nversion: \"1.0\"\n\ngates:\n  ^authenticated:\n    description: User must have a valid session\n    check: req.session.userId != null\n    type: auth\n    effects: []\n\nroutes:\n  \"POST /auth/login\": []\n  \"POST /auth/register\": []\n  \"GET /api/profile\": [^authenticated]\n  \"PUT /api/profile\": [^authenticated]\n```\n\nNote that public routes like login and register have empty gate arrays `[]` — they are listed to document that they are intentionally unprotected.\n\n## Step 4: Run Your First Scan\n\nGenerate the navigator map so AI agents can find symbols quickly:\n\n```bash\nparadigm scan\n```\n\nThis reads all `.purpose` files and `portal.yaml`, builds a symbol index, and writes `navigator.yaml`.\n\n## Step 5: The Orientation Protocol\n\nWhen starting a new AI session (or when an AI agent first encounters your project), the agent should follow this protocol:\n\n1. **Call `paradigm_status`** — Gets a project overview: symbol counts, health, available features.\n2. **Read `config.yaml`** — Understands the discipline, conventions, and preferences.\n3. **Check `portal.yaml`** — Knows about security gates if they exist.\n4. **Use `paradigm_navigate`** — Finds the relevant code area for the current task.\n\nThis four-step orientation takes ~500 tokens total and gives the agent everything it needs to work effectively.\n\n## Step 6: Iterate\n\nParadigm grows with your project. As you add features:\n- Create `.purpose` files for new directories\n- Add gates to `portal.yaml` for new protected routes\n- Record team decisions in `.paradigm/wisdom/decisions.yaml`\n- Log antipatterns in `.paradigm/wisdom/antipatterns.yaml`\n- Run `paradigm scan` periodically to rebuild the navigator\n\n## Common Pitfalls\n\n- **Do not document everything on day one.** Start with the most critical module and expand.\n- **Do not skip portal.yaml.** If you have any gates or preconditions, you need it.\n- **Do not forget to re-scan.** After adding new `.purpose` files, run `paradigm scan` to update the navigator.\n- **Do not put .purpose files in .paradigm/.** They live alongside source code.\n- **Do not use raw console.log.** Use the Paradigm logger from the start to build good habits.",
+      "keyConcepts": [
+        "paradigm shift creates the .paradigm/ directory",
+        "Start with one .purpose file in your most important module",
+        "Create portal.yaml if your project has gates (conditions to check)",
+        "paradigm scan generates navigator.yaml",
+        "The orientation protocol: status, config, portal, navigate"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "What is the correct order for the AI agent orientation protocol?",
+          "choices": {
+            "A": "Read source code, write tests, check coverage, deploy",
+            "B": "Call paradigm_status, read config.yaml, check portal.yaml, use paradigm_navigate",
+            "C": "Run paradigm scan, edit navigator.yaml, read .purpose files, commit changes",
+            "D": "Read package.json, install dependencies, run build, check logs",
+            "E": "Create .purpose files, define gates, emit signals, validate flows"
+          },
+          "correct": "B",
+          "explanation": "The orientation protocol is: (1) paradigm_status for project overview, (2) read config.yaml for conventions, (3) check portal.yaml for security gates, (4) paradigm_navigate to find the relevant code area. This takes ~500 tokens and gives the agent full context."
+        },
+        {
+          "id": "q2",
+          "question": "After creating new .purpose files, what command should you run?",
+          "choices": {
+            "A": "paradigm shift",
+            "B": "paradigm validate",
+            "C": "paradigm scan",
+            "D": "paradigm deploy",
+            "E": "paradigm build"
           },
           "correct": "C",
-          "explanation": "Paradigm defines exactly five operational symbols: # (Component), $ (Flow), ^ (Gate), ! (Signal), and ~ (Aspect). Classification beyond these five is handled by the tag system."
+          "explanation": "paradigm scan reads all .purpose files and portal.yaml, builds the symbol index, and regenerates navigator.yaml. Without rescanning, AI agents will not find the newly defined symbols through navigation tools."
+        },
+        {
+          "id": "q3",
+          "question": "In portal.yaml, what does an empty gate array on a route mean?",
+          "choices": {
+            "A": "The route is disabled and will return 404",
+            "B": "The route requires all gates to pass",
+            "C": "The route is intentionally unprotected — documented as public",
+            "D": "The route has not been configured yet and will return 500",
+            "E": "The route inherits gates from its parent path"
+          },
+          "correct": "C",
+          "explanation": "An empty gate array [] means the route is intentionally public. Listing it in portal.yaml with no gates documents the decision that this route should be accessible without authentication — it is not an oversight."
+        },
+        {
+          "id": "q4",
+          "question": "Which of these is a common pitfall when starting with Paradigm?",
+          "choices": {
+            "A": "Creating too many .purpose files on day one instead of starting small",
+            "B": "Using the Paradigm logger instead of console.log",
+            "C": "Running paradigm scan after adding new purpose files",
+            "D": "Putting portal.yaml at the project root",
+            "E": "Using tags to classify components"
+          },
+          "correct": "A",
+          "explanation": "A common pitfall is trying to document everything on day one. The recommended approach is to start with the most critical module, create one .purpose file, and expand incrementally as the project grows."
         }
       ]
     },
@@ -96,16 +162,16 @@
         },
         {
           "id": "q2",
-          "question": "Which symbol REQUIRES code anchors in its definition?",
+          "question": "After a refactor, you run paradigm doctor and it reports \"3 broken anchors detected.\" Which symbol type was affected?",
           "choices": {
-            "A": "# Component",
-            "B": "$ Flow",
-            "C": "^ Gate",
-            "D": "! Signal",
-            "E": "~ Aspect"
+            "A": "# Component — components have code anchors that broke during refactoring",
+            "B": "$ Flow — flow steps reference line numbers that shifted",
+            "C": "^ Gate — gate definitions include file paths that changed",
+            "D": "! Signal — signal emitters moved to different files",
+            "E": "~ Aspect — aspects are the only symbol with code anchors, and the refactor moved the anchored lines"
           },
           "correct": "E",
-          "explanation": "Aspects (~) are the only symbol that requires code anchors. An aspect represents a cross-cutting rule, and without anchors pointing to the enforcement code, the rule is just a wish — not a verified constraint."
+          "explanation": "Aspects (~) are the only symbol type that requires code anchors — specific file:line references pointing to where the rule is enforced. When code is refactored and lines move, those anchors break. paradigm doctor detects this via SHA-256 hash comparison, and paradigm_aspect_drift can show exactly which anchors drifted."
         },
         {
           "id": "q3",
@@ -135,16 +201,16 @@
         },
         {
           "id": "q5",
-          "question": "A system emits `!payment-completed` after a successful charge. Which statement is true about signals?",
+          "question": "Your payment module emits !payment-completed after charging a card. Later, the marketing team adds a \"send receipt email\" listener, and the analytics team adds a \"record conversion\" listener. Neither team modified the payment module. How is this possible?",
           "choices": {
-            "A": "The signal must directly invoke the notification service",
-            "B": "Signals can only be emitted by gate components",
-            "C": "The emitter does not need to know who listens to the signal",
-            "D": "Signals replace flows — you use one or the other, never both",
-            "E": "Signals must be defined in portal.yaml"
+            "A": "The payment module was refactored to call both services directly",
+            "B": "Signals promote loose coupling — the emitter fires the event without knowing who listens, so new listeners can be added independently",
+            "C": "The listeners were added to the payment module's .purpose file",
+            "D": "Both teams used the same $flow as the payment module",
+            "E": "The ^payment gate routes events to registered handlers"
           },
-          "correct": "C",
-          "explanation": "Signals promote loose coupling. The emitting component fires the event, and any number of listeners can react independently. The emitter has no knowledge of — and no dependency on — the listeners."
+          "correct": "B",
+          "explanation": "This is the core value of signals: loose coupling. The payment module emits !payment-completed and has zero knowledge of who listens. The marketing team and analytics team independently subscribe to the signal. No code in the payment module was modified. This is why Paradigm separates signals (!) from flows ($) — flows define explicit steps, while signals enable independent, decoupled reactions."
         }
       ]
     },
@@ -492,72 +558,6 @@
         }
       ]
     },
-    {
-      "id": "first-steps",
-      "title": "Your First Steps",
-      "content": "## Getting Started with Paradigm\n\nYou have learned the concepts — now it is time to put them into practice. This lesson walks through the concrete steps to initialize Paradigm in a new project and set up the foundational files.\n\n## Step 1: Initialize the Project\n\nRun `paradigm shift` in your project root. This creates the `.paradigm/` directory with a starter `config.yaml`:\n\n```bash\nparadigm shift\n```\n\nThe init command will prompt you for:\n- **Project name** — Used in config.yaml and as a display name\n- **Discipline** — `web`, `backend`, `fullstack`, `mobile`, `cli`, etc. (auto-detected from your project)\n- **Agent provider** — Which AI tool you use (`claude-code`, `cursor-cli`, etc.)\n\nParadigm automatically detects your discipline from project markers (`package.json`, `Cargo.toml`, `go.mod`, etc.) and your **stack preset** from framework dependencies. For example, a project with Next.js in its dependencies will be detected as `discipline: fullstack` with `stack: nextjs`. The stack preset provides framework-specific scan patterns, purpose-required paths, and refined symbol mappings.\n\nYou can also specify a stack explicitly: `paradigm init --stack fastapi`.\n\nAfter init, you will have:\n```\n.paradigm/\n  config.yaml    # Includes detected discipline and stack\n  tags.yaml\n  agents.yaml\n```\n\n## Step 2: Create Your First Purpose File\n\nPick a source directory that contains meaningful code — perhaps your main feature module or your API routes. Create a `.purpose` file:\n\n```yaml\nname: User Authentication\ndescription: Handles user login, registration, and session management\ncontext:\n  - Uses bcrypt for password hashing\n  - Sessions stored in Redis with 24h TTL\n  - Rate limited to 5 login attempts per minute\n\ncomponents:\n  #auth-handler:\n    description: POST /auth/login and POST /auth/register endpoints\n    file: auth.ts\n    tags: [feature, auth]\n    signals: [\"!login-success\", \"!login-failed\"]\n    gates: [\"^authenticated\"]\n\n  #session-manager:\n    description: Creates and validates user sessions in Redis\n    file: session.ts\n    tags: [state, auth]\n```\n\nStart small. You do not need to document every file on day one. Begin with the most important module and expand over time.\n\n## Step 3: Set Up portal.yaml (If Needed)\n\nIf your application has any protected endpoints, create `portal.yaml` at the project root:\n\n```yaml\nversion: \"1.0\"\n\ngates:\n  ^authenticated:\n    description: User must have a valid session\n    check: req.session.userId != null\n    type: auth\n    effects: []\n\nroutes:\n  \"POST /auth/login\": []\n  \"POST /auth/register\": []\n  \"GET /api/profile\": [^authenticated]\n  \"PUT /api/profile\": [^authenticated]\n```\n\nNote that public routes like login and register have empty gate arrays `[]` — they are listed to document that they are intentionally unprotected.\n\n## Step 4: Run Your First Scan\n\nGenerate the navigator map so AI agents can find symbols quickly:\n\n```bash\nparadigm scan\n```\n\nThis reads all `.purpose` files and `portal.yaml`, builds a symbol index, and writes `navigator.yaml`.\n\n## Step 5: The Orientation Protocol\n\nWhen starting a new AI session (or when an AI agent first encounters your project), the agent should follow this protocol:\n\n1. **Call `paradigm_status`** — Gets a project overview: symbol counts, health, available features.\n2. **Read `config.yaml`** — Understands the discipline, conventions, and preferences.\n3. **Check `portal.yaml`** — Knows about security gates if they exist.\n4. **Use `paradigm_navigate`** — Finds the relevant code area for the current task.\n\nThis four-step orientation takes ~500 tokens total and gives the agent everything it needs to work effectively.\n\n## Step 6: Iterate\n\nParadigm grows with your project. As you add features:\n- Create `.purpose` files for new directories\n- Add gates to `portal.yaml` for new protected routes\n- Record team decisions in `.paradigm/wisdom/decisions.yaml`\n- Log antipatterns in `.paradigm/wisdom/antipatterns.yaml`\n- Run `paradigm scan` periodically to rebuild the navigator\n\n## Common Pitfalls\n\n- **Do not document everything on day one.** Start with the most critical module and expand.\n- **Do not skip portal.yaml.** If you have any gates or preconditions, you need it.\n- **Do not forget to re-scan.** After adding new `.purpose` files, run `paradigm scan` to update the navigator.\n- **Do not put .purpose files in .paradigm/.** They live alongside source code.\n- **Do not use raw console.log.** Use the Paradigm logger from the start to build good habits.",
-      "keyConcepts": [
-        "paradigm shift creates the .paradigm/ directory",
-        "Start with one .purpose file in your most important module",
-        "Create portal.yaml if your project has gates (conditions to check)",
-        "paradigm scan generates navigator.yaml",
-        "The orientation protocol: status, config, portal, navigate"
-      ],
-      "quiz": [
-        {
-          "id": "q1",
-          "question": "What is the correct order for the AI agent orientation protocol?",
-          "choices": {
-            "A": "Read source code, write tests, check coverage, deploy",
-            "B": "Call paradigm_status, read config.yaml, check portal.yaml, use paradigm_navigate",
-            "C": "Run paradigm scan, edit navigator.yaml, read .purpose files, commit changes",
-            "D": "Read package.json, install dependencies, run build, check logs",
-            "E": "Create .purpose files, define gates, emit signals, validate flows"
-          },
-          "correct": "B",
-          "explanation": "The orientation protocol is: (1) paradigm_status for project overview, (2) read config.yaml for conventions, (3) check portal.yaml for security gates, (4) paradigm_navigate to find the relevant code area. This takes ~500 tokens and gives the agent full context."
-        },
-        {
-          "id": "q2",
-          "question": "After creating new .purpose files, what command should you run?",
-          "choices": {
-            "A": "paradigm shift",
-            "B": "paradigm validate",
-            "C": "paradigm scan",
-            "D": "paradigm deploy",
-            "E": "paradigm build"
-          },
-          "correct": "C",
-          "explanation": "paradigm scan reads all .purpose files and portal.yaml, builds the symbol index, and regenerates navigator.yaml. Without rescanning, AI agents will not find the newly defined symbols through navigation tools."
-        },
-        {
-          "id": "q3",
-          "question": "In portal.yaml, what does an empty gate array on a route mean?",
-          "choices": {
-            "A": "The route is disabled and will return 404",
-            "B": "The route requires all gates to pass",
-            "C": "The route is intentionally unprotected — documented as public",
-            "D": "The route has not been configured yet and will return 500",
-            "E": "The route inherits gates from its parent path"
-          },
-          "correct": "C",
-          "explanation": "An empty gate array [] means the route is intentionally public. Listing it in portal.yaml with no gates documents the decision that this route should be accessible without authentication — it is not an oversight."
-        },
-        {
-          "id": "q4",
-          "question": "Which of these is a common pitfall when starting with Paradigm?",
-          "choices": {
-            "A": "Creating too many .purpose files on day one instead of starting small",
-            "B": "Using the Paradigm logger instead of console.log",
-            "C": "Running paradigm scan after adding new purpose files",
-            "D": "Putting portal.yaml at the project root",
-            "E": "Using tags to classify components"
-          },
-          "correct": "A",
-          "explanation": "A common pitfall is trying to document everything on day one. The recommended approach is to start with the most critical module, create one .purpose file, and expand incrementally as the project grows."
-        }
-      ]
-    },
     {
       "id": "component-types",
       "title": "Component Types & Hierarchy",

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

@@ -232,82 +232,54 @@
     {
       "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.",
+      "content": "## What Is the Aspect Graph?\n\nIn earlier lessons you learned that aspects (`~`) represent cross-cutting rules, constraints, and configuration values anchored to specific lines of code. The **aspect graph** connects those aspects to each other and to the rest of your symbol system — components, gates, flows, and signals — creating a queryable relationship map.\n\nThink of it this way: a single aspect like `~token-expiry-24h` is useful on its own. But when you can see that it is *enforced by* `^authenticated`, *related to* `~refresh-token-7d`, and linked to a lore entry explaining why the team chose 24 hours — that is the graph at work.\n\n## v3.5 Aspect Fields\n\nParadigm v3.5 extended aspects with structured fields that make them graph-ready:\n\n```yaml\naspects:\n  ~rate-limit-100:\n    description: API rate limited to 100 requests per minute\n    value: 100/min\n    category: constraint\n    severity: high\n    anchors:\n      - src/middleware/rate-limiter.ts:12-18\n    applies-to: [#api-gateway]\n    edges:\n      - symbol: ^authenticated\n        relation: enforced-by\n    tags: [security, performance]\n```\n\nKey fields:\n- **value** — The concrete value (a number, duration, threshold) making aspects searchable by content\n- **category** — One of five types: `rule` (behavioral), `decision` (architectural choice), `constraint` (hard limit), `configuration` (environment-specific), `invariant` (always-true condition)\n- **severity** — Impact of violation: `low`, `medium`, `high`, `critical`\n- **edges** — Explicit relationships to other symbols with typed relations: `enforced-by`, `depends-on`, `contradicts`, `supersedes`, `related-to`\n- **lore** — References to lore entries providing historical context\n\n## Working with the Graph\n\nSeven MCP tools let you interact with the aspect graph:\n\n| Tool | Purpose |\n|------|---------|\n| `paradigm_aspect_search` | Find aspects by keyword — uses a three-tier search (learned mappings, full-text, fuzzy) |\n| `paradigm_aspect_get` | Deep-dive: full definition, code snippets at anchors, edges, linked lore |\n| `paradigm_aspect_graph` | Explore the neighborhood around a symbol (N hops out) |\n| `paradigm_aspect_heatmap` | See which aspects are accessed most (search, ripple, navigate, direct) |\n| `paradigm_aspect_suggest_scan` | Scan a source file for undocumented aspects (magic numbers, hardcoded strings, rate limits, etc.) |\n| `paradigm_aspect_drift` | Check if code at anchored lines changed since last scan (SHA-256 hash comparison) |\n| `paradigm_aspect_confirm` | Confirm a search result to improve future search accuracy (learning loop) |\n\nThe graph is stored as a SQLite database at `.paradigm/aspect-graph.db` — a derived artifact rebuilt by `paradigm_reindex`. The YAML `.purpose` files remain the source of truth.\n\n## When to Use the Aspect Graph\n\n- **Before modifying enforcement code** — call `paradigm_aspect_drift` to check for stale anchors\n- **Exploring unfamiliar rules** — call `paradigm_aspect_search` then `paradigm_aspect_get` for full context\n- **Understanding impact** — call `paradigm_aspect_graph` to see what a change affects\n- **Finding undocumented rules** — call `paradigm_aspect_suggest_scan` on source files\n\n> **Deep dive:** PARA 501 covers the SQLite schema, three-tier search internals, the learning loop, edge origins (explicit vs inferred vs learned), and the materialization pipeline in detail.",
       "keyConcepts": [
-        "v3.5 adds value, category, severity, edges, and lore fields to aspect definitions",
+        "Aspect graph connects aspects to components, gates, flows, and signals",
         "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"
+        "Five edge relations: enforced-by, depends-on, contradicts, supersedes, related-to",
+        "Seven MCP tools for search, detail, graph, heatmap, suggest, drift, and confirm",
+        "SQLite graph at .paradigm/aspect-graph.db is a derived artifact — YAML is source of truth",
+        "Deep internals covered in PARA 501"
       ],
       "quiz": [
         {
           "id": "q1",
-          "question": "What is the correct order of tiers in aspect search?",
+          "question": "Your team's rate limiter was recently changed from 100 req/min to 500 req/min, but no one updated the aspect definition. Which tool would catch this?",
           "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"
+            "A": "paradigm_aspect_search — it would find the stale value in search results",
+            "B": "paradigm_aspect_drift — it compares code hashes at anchor line ranges and detects the change",
+            "C": "paradigm_aspect_heatmap — it shows the aspect is no longer being accessed",
+            "D": "paradigm_aspect_graph — it reveals the broken edge to the rate limiter component",
+            "E": "paradigm_reindex — it automatically updates the aspect value during reindexing"
           },
           "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."
+          "explanation": "paradigm_aspect_drift compares SHA-256 hashes of code at anchored line ranges against the hashes from the last scan. When the rate limiter code changed, the hash changed, flagging the anchor as drifted. The other tools don't detect code changes — reindex rebuilds the graph from YAML, which still has the old value."
         },
         {
-          "id": "q3",
-          "question": "Which aspect category is appropriate for 'JWT expiry is 24 hours'?",
+          "id": "q2",
+          "question": "Which aspect category best fits \"JWT access tokens expire after 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",
+            "A": "rule — it defines a behavioral pattern that code must follow",
+            "B": "decision — it captures an architectural choice",
+            "C": "constraint — it is a hard limit that cannot be violated",
+            "D": "configuration — it is a value that may differ 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."
+          "explanation": "A JWT expiry duration is a configuration value — it could reasonably differ between environments (shorter in dev, longer in production). A constraint is a hard limitation (like \"maximum 100 items per page\"). A rule is a behavioral pattern. Configuration captures what specific value was set and where."
         },
         {
-          "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?",
+          "id": "q3",
+          "question": "An aspect has edges: [{symbol: \"^authenticated\", relation: \"enforced-by\"}]. What does this tell you?",
           "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"
+            "B": "The ^authenticated gate depends on the aspect existing",
+            "C": "The ^authenticated gate is the mechanism that ensures the aspect holds true",
+            "D": "The aspect and the gate are in conflict",
+            "E": "The aspect will be removed if the gate is deleted"
           },
           "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."
+          "explanation": "The enforced-by relation means the target symbol is what ensures the aspect's rule holds. Here, the ^authenticated gate is the checkpoint that enforces whatever the aspect defines. Aspects declare what must be true; gates enforce those truths. The edge makes this relationship explicit and queryable."
         }
       ]
     },