@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-101-project-structure.md

@@ -0,0 +1,143 @@
+---
+id: N-para-101-project-structure
+title: Project Structure
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - paradigm-holds-project-wide
+  - configyaml-defines-discipline
+  - navigatoryaml-is-generated
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The .paradigm/ Directory
+
+Every Paradigm project has a `.paradigm/` directory at its root. This is the central nervous system of the framework — it holds project-wide configuration, specifications, documentation, and metadata that apply across the entire codebase. While `.purpose` files describe individual directories, the `.paradigm/` directory describes the project as a whole.
+
+## Core Files
+
+### config.yaml — Project Configuration
+
+The most important file. It defines the project's discipline (web, backend, fullstack, etc.), naming conventions, and agent preferences:
+
+```yaml
+name: my-project
+discipline: fullstack
+version: "2.0"
+
+conventions:
+  naming: kebab-case
+  components: PascalCase
+  files: kebab-case
+
+agent-provider: claude-code
+```
+
+The `discipline` field tells Paradigm how to map directory patterns to symbol types. A `web` discipline treats `routes/` as components; a `backend` discipline treats `services/` as components. This affects the navigator, logger suggestions, and gate recommendations.
+
+### tags.yaml — Tag Bank
+
+Defines all valid tags in three sections: `core` (universal), `project` (team-specific), and `suggested` (AI-proposed). Covered in detail in the Tags lesson.
+
+### agents.yaml — Agent Roles
+
+Configures the AI agents that work on your project — their roles, model assignments, context includes/excludes, and token budgets:
+
+```yaml
+agents:
+  architect:
+    defaultModel: opus
+    context:
+      include: [".paradigm/**", "portal.yaml", "**/.purpose"]
+  builder:
+    defaultModel: haiku
+    context:
+      include: ["src/**", "**/.purpose"]
+      exclude: ["**/*.test.*"]
+  security:
+    defaultModel: opus
+    context:
+      include: ["portal.yaml", "**/auth/**", "**/middleware/**"]
+```
+
+### navigator.yaml — Generated Codebase Map
+
+A machine-generated file that maps symbols to file paths, directories to categories, and provides a structural overview of the codebase. AI agents read this to quickly locate code without directory traversal. Generated by `paradigm scan`.
+
+## Subdirectories
+
+### specs/ — Detailed Specifications
+
+Long-form documents that describe system behaviors, protocols, and standards. These are too detailed for `.purpose` files but essential for AI agents implementing features:
+
+```
+.paradigm/specs/
+  logger.md          ← Full logger specification
+  disciplines.md     ← Symbol mapping by domain
+  portal-protocol.md ← Authorization workflow
+```
+
+### docs/ — Commands and Patterns
+
+Quick-reference documentation for CLI commands, coding patterns, and troubleshooting:
+
+```
+.paradigm/docs/
+  commands.md                ← CLI command reference
+  patterns.md                ← Coding patterns and conventions
+  ai-maintenance-protocol.md ← When/how to update Paradigm files
+```
+
+### wisdom/ — Team Knowledge
+
+Captures the team's learned preferences, architectural decisions, and antipatterns:
+
+```
+.paradigm/wisdom/
+  preferences.yaml    ← Coding style preferences
+  decisions.yaml      ← Architectural Decision Records (ADRs)
+  antipatterns.yaml   ← What NOT to do, and why
+```
+
+AI agents check wisdom before implementing changes by calling `paradigm_wisdom_context`.
+
+### history/ — Implementation Timeline
+
+Tracks what was implemented, when, and by whom. Used for fragility analysis and rollback tracking.
+
+## The Big Picture
+
+Here is the complete project layout showing both `.paradigm/` and `.purpose` files:
+
+```
+my-project/
+  .paradigm/
+    config.yaml       ← Project-wide settings
+    tags.yaml         ← Tag definitions
+    agents.yaml       ← Agent configurations
+    navigator.yaml    ← Generated codebase map
+    specs/            ← Detailed specifications
+    docs/             ← Commands and patterns
+    wisdom/           ← Team knowledge
+    history/          ← Implementation timeline
+  portal.yaml         ← Security gates and routes (project root)
+  src/
+    payments/
+      .purpose        ← Directory-level documentation
+      payment-service.ts
+    auth/
+      .purpose
+      middleware.ts
+```
+
+Notice that `portal.yaml` lives at the project root, not inside `.paradigm/`. This is intentional — it is a security-critical file that should be visible and easy to audit.

package/dist/university-content/notes/N-para-101-purpose-files.md

@@ -0,0 +1,121 @@
+---
+id: N-para-101-purpose-files
+title: Purpose Files
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - purpose-files-are
+  - they-declare-components
+  - ai-agents-read
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The Map AI Agents Read First
+
+A `.purpose` file is a YAML document that lives in a directory alongside your source code. It declares what that directory contains — its components, flows, gates, signals, and aspects. When an AI agent enters a directory, the first thing it should do is read the `.purpose` file. This single file gives the agent enough context to understand the directory without scanning every source file.
+
+Think of `.purpose` files as the table of contents for a chapter in a book. You would not read every page to find out what topics are covered — you check the table of contents. Similarly, AI agents should not `grep` through every `.ts` or `.py` file to figure out what a directory does.
+
+## Structure of a Purpose File
+
+A `.purpose` file has a top-level metadata section and then named sections for each symbol type:
+
+```yaml
+name: Payment Module
+description: Handles all payment processing and billing logic
+version: "1.0.0"
+context:
+  - Uses Stripe as the payment provider
+  - All amounts are in cents (integer)
+  - Webhooks are verified with Stripe signatures
+
+components:
+  #payment-service:
+    description: Core payment processing logic
+    file: payment-service.ts
+    tags: [integration, stripe, critical]
+    signals: ["!payment-completed", "!payment-failed"]
+    gates: ["^authenticated"]
+
+  #billing-calculator:
+    description: Computes totals, taxes, and discounts
+    file: billing.ts
+    tags: [feature]
+
+flows:
+  $checkout-flow:
+    description: End-to-end purchase sequence
+    steps:
+      - component: "#cart-service"
+        action: validate-items
+      - component: "#billing-calculator"
+        action: compute-total
+      - component: "#payment-service"
+        action: charge
+
+signals:
+  !payment-completed:
+    description: Emitted after successful charge
+    emitters: ["#payment-service"]
+    category: business
+
+gates:
+  ^payment-authorized:
+    description: User has a valid payment method on file
+    check: user.paymentMethods.length > 0
+```
+
+## Key Rules for Purpose Files
+
+**One per directory.** Each directory that contains meaningful code should have at most one `.purpose` file. Not every directory needs one — only directories that contain components worth documenting.
+
+**Symbols must use the correct prefix.** Components use `#`, flows use `$`, gates use `^`, signals use `!`, aspects use `~`. The prefix is part of the identifier.
+
+**Descriptions are required.** Every component, flow, gate, signal, and aspect must have a `description` field. Without it, the symbol is opaque to AI agents.
+
+**References link symbols together.** A component can reference the gates it requires (`gates: ["^authenticated"]`), the signals it emits (`signals: ["!payment-completed"]`), and the flows it participates in (`flows: ["$checkout-flow"]`). These cross-references let tools like `paradigm_ripple` calculate impact.
+
+**The `context` field is for AI.** The top-level `context` array contains free-text notes aimed at AI agents: conventions, gotchas, assumptions. This is where you write "all amounts are in cents" or "this module is deprecated, use v2 instead."
+
+## Where Purpose Files Live
+
+Purpose files are placed in source directories — wherever your code lives:
+
+```
+src/
+  payments/
+    .purpose          ← describes the payments module
+    payment-service.ts
+    billing.ts
+  auth/
+    .purpose          ← describes the auth module
+    login.ts
+    middleware.ts
+```
+
+They are NOT placed in the `.paradigm/` directory. The `.paradigm/` directory holds project-wide configuration; `.purpose` files hold directory-level documentation.
+
+## Creating Purpose Files with MCP Tools
+
+You can create and update purpose files using the Paradigm MCP tools:
+
+```
+paradigm_purpose_init     → Create/update file-level metadata
+paradigm_purpose_add_component → Add a #component
+paradigm_purpose_add_flow     → Add a $flow
+paradigm_purpose_add_gate     → Add a ^gate
+paradigm_purpose_add_signal   → Add a !signal
+paradigm_purpose_add_aspect   → Add a ~aspect (with required anchors)
+```
+
+These tools handle YAML formatting and symbol quoting automatically. For example, YAML treats `!` as a tag indicator, so signal IDs need special quoting — the tools handle this for you.

package/dist/university-content/notes/N-para-101-tags-and-classification.md

@@ -0,0 +1,93 @@
+---
+id: N-para-101-tags-and-classification
+title: Tags & Classification
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - tags-classify-components
+  - tags-are-defined
+  - three-sections-core
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## Beyond Symbols: The Tag Bank
+
+Paradigm's five symbols classify code by *role* — component, flow, gate, signal, aspect. But within each role, you often need finer distinctions. Is this component a user-facing feature or a third-party integration? Is it critical infrastructure or an experimental idea? Paradigm handles this with a unified **tag system**.
+
+Tags are plain strings in brackets that you attach to any symbol. They live in the `tags` array on a symbol definition:
+
+```yaml
+components:
+  #checkout:
+    description: Shopping cart checkout experience
+    tags: [feature, critical, payments]
+
+  #stripe-service:
+    description: Stripe API client wrapper
+    tags: [integration, stripe, payments]
+
+  #cart-store:
+    description: In-memory shopping cart state
+    tags: [state, ephemeral]
+```
+
+## The Tag Bank File
+
+Tags are not arbitrary strings — they are defined in `.paradigm/tags.yaml`, which serves as the project's tag bank. The tag bank has three sections:
+
+```yaml
+core:          # Universal tags, defined by Paradigm itself
+  feature:     { description: "User-facing functionality" }
+  integration: { description: "Third-party service connection" }
+  state:       { description: "Data store or state container" }
+  critical:    { description: "Failure causes major user impact" }
+  deprecated:  { description: "Scheduled for removal" }
+  idea:        { description: "Experimental, not yet approved" }
+
+project:       # Team-defined tags specific to this project
+  payments:    { description: "Related to payment processing" }
+  onboarding:  { description: "Part of the new-user experience" }
+
+suggested:     # AI-proposed tags awaiting human approval
+  webhook-handler: { description: "Processes incoming webhooks" }
+```
+
+The **core** section contains tags that apply to any project. The **project** section contains tags your team has defined for this specific codebase. The **suggested** section is where AI agents can propose new tags using the `paradigm_tags_suggest` tool — a human reviews and promotes them to the project section.
+
+## How Tags Work in Practice
+
+Here is how tags differentiate components that serve different roles:
+
+| Role | How to Tag |
+|-----------|---------------|
+| User-facing feature | `#checkout` with `tags: [feature]` |
+| Third-party service | `#stripe-service` with `tags: [integration, stripe]` |
+| Data store | `#cart-store` with `tags: [state]` |
+| Experimental prototype | `#new-widget` with `tags: [idea]` |
+| Scheduled for removal | `#legacy-handler` with `tags: [deprecated]` |
+
+This means fewer concepts to remember and no ambiguity. A Stripe payment service is `#stripe-service` with `tags: [integration, stripe]` — clear, searchable, and consistent.
+
+## Using Tags Effectively
+
+Tags are most powerful when they are **consistent and searchable**. Follow these guidelines:
+
+- **Use existing tags before inventing new ones.** Check `paradigm_tags({ action: "list" })` to see what is available.
+- **Keep tags lowercase and kebab-case.** `webhook-handler`, not `WebhookHandler` or `WEBHOOK_HANDLER`.
+- **Use 2-4 tags per symbol.** One tag is too vague; ten tags is noise.
+- **Tag for discoverability.** Ask: "What would I search for to find this component?" Those search terms are your tags.
+- **Let AI propose tags.** If you notice a pattern (e.g., five components all handle webhooks), use `paradigm_tags_suggest` to propose a `webhook-handler` tag.
+
+## Querying by Tags
+
+The Paradigm MCP tools support tag-based discovery. When you call `paradigm_search` with a tag name, it returns all symbols bearing that tag. This makes it easy to ask questions like "show me everything tagged `critical`" or "find all `integration` components."

package/dist/university-content/notes/N-para-101-welcome.md

@@ -0,0 +1,51 @@
+---
+id: N-para-101-welcome
+title: Welcome to Paradigm
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - meta-framework-for-ai-assisted
+  - structured-context-over
+  - five-operational-symbols
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## What Is Paradigm?
+
+Paradigm is a **meta-framework for structured AI-assisted development**. It is not a code framework like React or Express — it does not ship components, generate boilerplate, or impose a runtime. Instead, Paradigm organizes *how AI agents understand your code*. It provides a shared vocabulary of symbols, a directory-level documentation format, and a set of specifications that let any AI assistant — whether Claude, Cursor, or another tool — navigate even large codebases with precision and minimal token waste.
+
+The core insight behind Paradigm is simple: AI agents are powerful, but they struggle when dropped into an undocumented codebase. They spend thousands of tokens exploring directories, guessing at relationships, and re-reading files they have already seen. Paradigm solves this by giving the codebase *structured context* — lightweight metadata files that describe what lives where, how pieces relate, and what rules apply.
+
+## The Three Pillars
+
+Paradigm rests on three pillars:
+
+1. **Symbols** — A set of five prefixed identifiers (`#`, `$`, `^`, `!`, `~`) that classify every meaningful unit in your project. A payment service is `#PaymentService`. An authorization check is `^authenticated`. A business event is `!order-placed`. Symbols are the vocabulary AI agents use to talk about your code.
+
+2. **Purpose Files** — YAML files named `.purpose` that live in directories alongside your source code. They declare which components, flows, gates, signals, and aspects exist in that directory. They are the map AI agents read before they touch any code.
+
+3. **Specifications** — Files in the `.paradigm/` directory that define project-wide configuration, tag taxonomies, agent roles, navigation maps, and team wisdom. They are the rulebook that keeps every agent aligned with your team's conventions.
+
+## Why It Matters
+
+Without structured context, an AI agent working on a checkout feature might:
+- Spend 2,000+ tokens reading irrelevant files looking for the payment service
+- Miss an authorization gate that protects the endpoint
+- Accidentally duplicate a signal that another component already emits
+- Use `console.log` instead of the team's structured logger
+
+With Paradigm, that same agent calls `paradigm_navigate` to find `#PaymentService` in ~100 tokens, checks `paradigm_ripple` to see what depends on it, reads the `.purpose` file to understand the directory, and follows the team's logging convention. The result is faster, safer, and more consistent code changes.
+
+## What You Will Learn
+
+In this course you will learn the five symbols and when to use each one, how to write and read `.purpose` files, how to classify symbols with tags, how to use the Paradigm logger, how the `.paradigm/` directory is organized, how `portal.yaml` secures your routes, and how to set up a new project from scratch.

package/dist/university-content/notes/N-para-201-architecture-review.md

@@ -0,0 +1,175 @@
+---
+id: N-para-201-architecture-review
+title: Putting It All Together
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - feature-building-follows
+  - implementation-comes-last
+  - check-existing-aspects
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Building a Complete Feature
+
+You have learned flows, gates, aspects, disciplines, naming conventions, component patterns, signal patterns, and cross-cutting concerns. Now let us walk through building a complete feature from scratch, using every tool in the Paradigm toolkit. The feature: **a team invitation system** where team admins can invite new members via email.
+
+## Step 1: Identify Components
+
+Start by listing the code units you will need:
+
+```yaml
+#invitation-service:
+  description: Creates and manages team invitations
+  tags: [feature, teams]
+
+#invitation-email:
+  description: Sends invitation emails via SendGrid
+  tags: [integration, sendgrid, email]
+
+#invitation-token:
+  description: Generates and validates secure invitation tokens
+  tags: [infrastructure, security]
+
+#invitation-store:
+  description: Persists invitations with status tracking
+  tags: [state, teams]
+```
+
+Four components — one feature, one integration, one infrastructure, one state. Each has a clear responsibility and appropriate tags.
+
+## Step 2: Define the Flow
+
+The invitation process spans all four components in sequence:
+
+```yaml
+$team-invitation-flow:
+  description: Admin invites a user, email is sent, user accepts and joins team
+  steps:
+    - component: "#invitation-service"
+      action: create-invitation
+      description: Validates admin permissions and creates invitation record
+    - component: "#invitation-token"
+      action: generate-token
+      description: Creates a cryptographically secure token with 7-day expiry
+    - component: "#invitation-store"
+      action: persist-invitation
+      description: Saves invitation with pending status
+    - component: "#invitation-email"
+      action: send-invite
+      description: Sends email with accept link containing the token
+  signals: ["!invitation-sent", "!invitation-accepted"]
+  gates: ["^authenticated", "^team-admin"]
+```
+
+## Step 3: Add Gates
+
+Two gates are needed. First, check `portal.yaml` for existing gates. `^authenticated` likely exists. `^team-admin` may need to be created:
+
+```yaml
+# In portal.yaml
+gates:
+  ^team-admin:
+    description: User must be an admin of the specified team
+    check: team.admins.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+
+routes:
+  "POST /api/teams/:id/invitations": [^authenticated, ^team-admin]
+  "POST /api/invitations/:token/accept": [^authenticated]
+  "GET /api/teams/:id/invitations": [^authenticated, ^team-admin]
+  "DELETE /api/invitations/:id": [^authenticated, ^team-admin]
+```
+
+Notice that accepting an invitation only requires `^authenticated` — any logged-in user with a valid token can accept. But creating, listing, and deleting invitations requires `^team-admin`.
+
+## Step 4: Define Signals
+
+```yaml
+!invitation-sent:
+  description: An invitation email was successfully sent to a prospective team member
+  emitters: ["#invitation-service"]
+  category: business
+  data:
+    invitationId: string
+    teamId: string
+    email: string
+
+!invitation-accepted:
+  description: A user accepted a team invitation and joined the team
+  emitters: ["#invitation-service"]
+  category: business
+  data:
+    invitationId: string
+    teamId: string
+    userId: string
+```
+
+These business signals enable decoupled side effects — an analytics tracker can listen for `!invitation-accepted` to track conversion rates, and a notification service can alert existing team members.
+
+## Step 5: Apply Aspects
+
+Check which aspects apply to the new components:
+
+- `~audit-required` applies to `#*Service` → `#invitation-service` is covered. Ensure the audit middleware is applied.
+- `~rate-limited` applies to `#*-handler` → Not directly applicable here (no handler component), but the API route should go through the rate limiter.
+- `~validated` applies to `#*-handler` → The invitation endpoint should validate input (email format, team existence).
+
+## Step 6: Write the .purpose File
+
+Assemble everything into `src/invitations/.purpose`:
+
+```yaml
+name: Team Invitations
+description: Team admin invitation system with email delivery and token-based acceptance
+context:
+  - Invitation tokens expire after 7 days
+  - Maximum 50 pending invitations per team
+  - Uses SendGrid for email delivery
+
+components:
+  #invitation-service:
+    description: Creates and manages team invitations
+    file: invitation-service.ts
+    tags: [feature, teams]
+    flows: ["$team-invitation-flow"]
+    signals: ["!invitation-sent", "!invitation-accepted"]
+    gates: ["^authenticated", "^team-admin"]
+    aspects: ["~audit-required"]
+  # ... (remaining components)
+
+flows:
+  $team-invitation-flow:
+    # ... (as defined above)
+
+signals:
+  !invitation-sent:
+    # ... (as defined above)
+  !invitation-accepted:
+    # ... (as defined above)
+```
+
+## Step 7: Validate
+
+Before writing any implementation code, validate the Paradigm definitions:
+
+1. `paradigm_purpose_validate` — Checks the .purpose file for schema errors.
+2. `paradigm_flow_check` — Verifies the flow references valid components.
+3. `paradigm_aspect_check` — Confirms aspect anchors are valid for applied aspects.
+4. `paradigm_ripple` — Shows what existing code is affected by the new components.
+
+## The Pattern
+
+Every feature follows this pattern: **identify components** → **define flows** → **add gates** → **define signals** → **apply aspects** → **write .purpose** → **validate** → **implement**. The implementation comes last — after the architecture is documented and validated. This front-loaded documentation pays dividends: AI agents can navigate the new feature immediately, security is defined before code, and the team has a clear map of what will be built.

package/dist/university-content/notes/N-para-201-aspect-graph.md

@@ -0,0 +1,79 @@
+---
+id: N-para-201-aspect-graph
+title: The Aspect Graph
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - aspect-graph-connects
+  - five-aspect-categories
+  - five-edge-relations
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## What Is the Aspect Graph?
+
+In 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.
+
+Think 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.
+
+## v3.5 Aspect Fields
+
+Paradigm v3.5 extended aspects with structured fields that make them graph-ready:
+
+```yaml
+aspects:
+  ~rate-limit-100:
+    description: API rate limited to 100 requests per minute
+    value: 100/min
+    category: constraint
+    severity: high
+    anchors:
+      - src/middleware/rate-limiter.ts:12-18
+    applies-to: [#api-gateway]
+    edges:
+      - symbol: ^authenticated
+        relation: enforced-by
+    tags: [security, performance]
+```
+
+Key fields:
+- **value** — The concrete value (a number, duration, threshold) making aspects searchable by content
+- **category** — One of five types: `rule` (behavioral), `decision` (architectural choice), `constraint` (hard limit), `configuration` (environment-specific), `invariant` (always-true condition)
+- **severity** — Impact of violation: `low`, `medium`, `high`, `critical`
+- **edges** — Explicit relationships to other symbols with typed relations: `enforced-by`, `depends-on`, `contradicts`, `supersedes`, `related-to`
+- **lore** — References to lore entries providing historical context
+
+## Working with the Graph
+
+Seven MCP tools let you interact with the aspect graph:
+
+| Tool | Purpose |
+|------|---------|
+| `paradigm_aspect_search` | Find aspects by keyword — uses a three-tier search (learned mappings, full-text, fuzzy) |
+| `paradigm_aspect_get` | Deep-dive: full definition, code snippets at anchors, edges, linked lore |
+| `paradigm_aspect_graph` | Explore the neighborhood around a symbol (N hops out) |
+| `paradigm_aspect_heatmap` | See which aspects are accessed most (search, ripple, navigate, direct) |
+| `paradigm_aspect_suggest_scan` | Scan a source file for undocumented aspects (magic numbers, hardcoded strings, rate limits, etc.) |
+| `paradigm_aspect_drift` | Check if code at anchored lines changed since last scan (SHA-256 hash comparison) |
+| `paradigm_aspect_confirm` | Confirm a search result to improve future search accuracy (learning loop) |
+
+The 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.
+
+## When to Use the Aspect Graph
+
+- **Before modifying enforcement code** — call `paradigm_aspect_drift` to check for stale anchors
+- **Exploring unfamiliar rules** — call `paradigm_aspect_search` then `paradigm_aspect_get` for full context
+- **Understanding impact** — call `paradigm_aspect_graph` to see what a change affects
+- **Finding undocumented rules** — call `paradigm_aspect_suggest_scan` on source files
+
+> **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.