@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-201-symbol-naming.md

@@ -0,0 +1,149 @@
+---
+id: N-para-201-symbol-naming
+title: Symbol Naming Conventions
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - all-symbol-ids
+  - components-noun-role-payment-service
+  - gates-resource-role-or
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Consistency Is the Goal
+
+Naming conventions exist so that anyone — human or AI — can predict what a symbol is called without looking it up. If your payment service is sometimes `#PaymentService`, sometimes `#payment-service`, and sometimes `#paymentSvc`, agents waste tokens searching and developers waste time guessing. Paradigm defines clear naming rules for each symbol type.
+
+## The Base Rule: kebab-case for IDs
+
+All symbol IDs in `.purpose` files use **kebab-case**:
+
+```yaml
+# Correct
+#payment-service:
+#user-profile:
+#cart-item-list:
+
+# Incorrect
+#PaymentService:      # PascalCase is for display, not IDs
+#payment_service:     # No underscores
+#paymentService:      # No camelCase
+```
+
+This applies to all five symbol types: `#component-name`, `$flow-name`, `^gate-name`, `!signal-name`, `~aspect-name`.
+
+## Component Naming (`#`)
+
+Components follow the base kebab-case rule, with one exception: **class-like components** can use PascalCase in display names and code references while keeping kebab-case in the `.purpose` ID:
+
+```yaml
+components:
+  #payment-service:                    # kebab-case ID
+    description: PaymentService class   # PascalCase in description is fine
+    file: PaymentService.ts             # PascalCase file names are fine
+```
+
+Naming patterns for components:
+- **Services**: `#noun-service` — `#payment-service`, `#email-service`, `#auth-service`
+- **Handlers**: `#noun-handler` — `#login-handler`, `#webhook-handler`
+- **Stores/State**: `#noun-store` — `#user-store`, `#cart-store`
+- **Utilities**: `#noun-utils` or `#verb-helper` — `#date-utils`, `#format-helper`
+
+## Flow Naming (`$`)
+
+Flows describe processes, so they use **noun-flow** or **verb-noun-flow** patterns:
+
+```yaml
+# Good
+$checkout-flow
+$user-onboarding
+$password-reset-flow
+$daily-report-generation
+
+# Bad
+$doCheckout          # Avoid imperative verb-only names
+$flow1               # Non-descriptive
+$theProcessOfCheckingOut  # Too verbose
+```
+
+The `-flow` suffix is optional but recommended for clarity. `$checkout-flow` is more immediately recognizable as a flow than `$checkout` (which could be confused with a component).
+
+## Gate Naming (`^`)
+
+Gates use a **resource-role** or **condition** pattern:
+
+```yaml
+# Resource-role pattern
+^authenticated              # Base auth
+^project-admin              # Admin of a project
+^project-member             # Member of a project
+^comment-author             # Author of a comment
+^team-owner                 # Owner of a team
+
+# Condition pattern
+^email-verified             # Email has been verified
+^payment-method-exists      # User has a payment method
+^subscription-active        # Subscription is not expired
+```
+
+Avoid vague names like `^check1` or `^gate-a`. The name should describe what the gate verifies.
+
+## Signal Naming (`!`)
+
+Signals represent events that have already happened, so they use **past-tense** naming:
+
+```yaml
+# Good — past tense describes what happened
+!payment-completed
+!user-created
+!login-failed
+!order-shipped
+!cache-invalidated
+
+# Bad — present tense or imperative
+!process-payment         # Sounds like a command, not an event
+!creating-user           # Progressive tense is ambiguous
+!login                   # Too vague — login succeeded or failed?
+```
+
+Past tense makes the intent clear: the signal fires *after* something happened. `!payment-completed` means the payment is done; listeners can react to the completed event.
+
+## Aspect Naming (`~`)
+
+Aspects describe rules or qualities, using **adjective** or **past-participle** patterns:
+
+```yaml
+# Good
+~audit-required
+~rate-limited
+~cached
+~encrypted-at-rest
+~idempotent
+
+# Bad
+~doAudit              # Imperative — sounds like an action
+~auditStuff           # Vague and informal
+~Aspect1              # Non-descriptive
+```
+
+Aspect names should read naturally in a sentence: "This service is ~rate-limited" or "This endpoint is ~audit-required."
+
+## Summary Table
+
+| Symbol | Pattern | Examples |
+|--------|---------|----------|
+| `#` | `noun-role` | `#payment-service`, `#login-handler` |
+| `$` | `noun-flow` | `$checkout-flow`, `$onboarding` |
+| `^` | `resource-role` or `condition` | `^project-admin`, `^email-verified` |
+| `!` | `past-tense-event` | `!payment-completed`, `!login-failed` |
+| `~` | `adjective` / `past-participle` | `~rate-limited`, `~audit-required` |

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

@@ -0,0 +1,53 @@
+---
+id: N-para-301-context-management
+title: Context Management
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigmsessionhealth-for-monitoring
+  - paradigmhandoffprepare-for-session
+  - paradigmsessionrecover-for-continuity
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Context Management
+
+AI agents operate within a finite context window. Every file read, every tool call response, and every message in the conversation consumes tokens from that budget. When the context fills up, the agent loses the ability to recall earlier information, make coherent plans, or maintain awareness of all the changes it has made. Paradigm provides tools to monitor, manage, and gracefully handle context limits.
+
+**`paradigm_session_health`** monitors current context usage. Call it periodically during long sessions (every 10-15 tool calls is a good cadence) to get a recommendation. The response tells you whether to "continue" (plenty of room), "be-cautious" (usage is climbing), or "handoff-soon" (>85% consumed). You can optionally pass your estimated total tokens and context window size for more accurate assessment.
+
+```
+paradigm_session_health({
+  contextWindowSize: 200000,
+  estimatedTotalTokens: 150000
+})
+// Recommendation: "handoff-soon" -- context at ~75%, prepare handoff
+```
+
+When a handoff is needed, **`paradigm_handoff_prepare`** creates a structured summary of the current session. It captures what was done, which symbols were touched, which files were modified, what still needs to happen, and any open questions. This summary becomes the starting point for the next session.
+
+```
+paradigm_handoff_prepare({
+  summary: "Implemented Apple Pay in checkout flow",
+  symbolsTouched: ["#payment-service", "$checkout-flow", "#apple-pay-button"],
+  modifiedFiles: ["src/services/payment.ts", "src/components/checkout/ApplePayButton.tsx"],
+  nextSteps: ["Add unit tests for Apple Pay handler", "Update portal.yaml with new gates"],
+  openQuestions: ["Should we support Apple Pay in the mobile app too?"]
+})
+```
+
+On the receiving end, **`paradigm_session_recover`** loads breadcrumbs from the previous session. A new agent session calls this at startup to understand what was done before, pick up where the last session left off, and avoid redoing work.
+
+For cost awareness, **`paradigm_session_stats`** shows the current session's MCP interactions, estimated token usage, and cost breakdown. This is useful for understanding which operations are expensive and optimizing your workflow.
+
+The context management workflow forms a cycle: **monitor** usage with context_check, **prepare** handoff when limits approach, **recover** in new sessions with session_recover, and **track** costs with session_stats. Mastering this cycle means you can handle tasks that are larger than any single context window by splitting them across multiple sessions without losing progress.

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

@@ -0,0 +1,99 @@
+---
+id: N-para-301-decisions
+title: The Decision Store
+type: note
+author: paradigm
+created: '2026-04-18'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-301
+  - decision-store
+  - paradigmdecisionrecord
+  - companion-lore-pattern
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: authored
+source: v6.0-content-fix
+---
+
+## Why Decisions Got Their Own Store
+
+Through Paradigm v5.x, architectural decisions lived in two places at once: as a `decision` lore type (date-partitioned, narrative-shaped) and as a `decision` wisdom entry (symbol-keyed, ADR-shaped). Both stores carried roughly the same content, neither was canonical, and the inconsistency caused predictable problems — agents recorded the same choice in both places, search returned conflicting versions, and "what did we decide about X?" was answered by reading two stores and reconciling.
+
+In v6.0 the decision (D3 in the locked v6 synthesis) was to give decisions a single dedicated home. Lore stays the time-partitioned narrative timeline. Wisdom stays the symbol-keyed playbook (preferences and antipatterns). Decisions move to `.paradigm/decisions/` as `TD-*` entries with the full ADR shape — and the `decision` lore type is hard-removed.
+
+## The New Tools
+
+The decision store is reached through two MCP tools (CLI: `paradigm decision record` / `paradigm decision search`):
+
+- **`paradigm_decision_record`** — Records a new decision. Required: `title`, `decision`, `rationale`, `participants`. Optional: `alternatives_considered`, `symbols_affected`, `status`, `tags`, `context`, `consequences`, `superseded_by`, `supersedes`. Returns the canonical `TD-*` id and the companion lore id.
+- **`paradigm_decision_search`** — Filters the store by `status`, `participant`, `symbol`, `tag`, `dateFrom`, `dateTo`. Pass `summary: true` for an aggregate view.
+
+A recorded decision looks like:
+
+```yaml
+id: TD-2026-04-18-001
+title: "Adopt RS256 over HS256 for JWT signing"
+timestamp: "2026-04-18T15:30:00Z"
+participants:
+  - { id: "human/matt", role: human, stance: proposed }
+  - { id: "a-paradigm/security", role: agent, stance: supported }
+  - { id: "a-paradigm/architect", role: agent, stance: supported }
+  - { id: "a-paradigm/builder", role: agent, stance: dissented }
+decision: "Sign all JWTs with RS256 (RSA)"
+rationale: "Public-key verification lets downstream services validate without sharing the signing secret. Builder dissented over rotation overhead — accepted as a known cost."
+alternatives_considered:
+  - option: "HS256 (shared secret)"
+    rejected_because: "Every verifier needs the secret; rotation is invasive across services."
+symbols_affected: ["#auth-middleware", "^authenticated"]
+status: active
+tags: [security, auth]
+```
+
+## The Companion-Lore Pattern
+
+Every successful `paradigm_decision_record` call writes two artifacts:
+
+1. The canonical decision in `.paradigm/decisions/TD-*.yaml`.
+2. A companion lore entry of `type: 'insight'` in `.paradigm/lore/entries/{date}/L-*.yaml`, with `references.decision_id` pointing back at the TD- id, and the `companion-lore` + `decision-reference` tags applied.
+
+This split solves the problem the v5.x dual-store approach created. The decision is *topic-addressable* — search by symbol, status, or participant and you get one canonical answer. The companion lore is *time-addressable* — scrolling the project timeline forward, the moment the decision was made still surfaces with a one-line summary and a back-reference to the full record.
+
+The companion write is best-effort. If it fails (filesystem error, permission issue), the decision still records — the timeline coverage is a nice-to-have, not a correctness requirement. The decision record is the source of truth.
+
+## How It Differs from `paradigm_wisdom_record({type:'decision'})`
+
+The v5.x path is soft-deprecated and increasingly hard-removed:
+
+| Concern | `wisdom_record({type:'decision'})` (v5) | `paradigm_decision_record` (v6) |
+|---|---|---|
+| Storage | `.paradigm/wisdom/decisions.yaml` (single file) | `.paradigm/decisions/TD-*.yaml` (one file per decision) |
+| ID shape | `dec-001`, freeform | `TD-{date}-{seq}`, structured |
+| Participants | Optional, freeform string | Structured array with stance enum |
+| Alternatives | Optional, prose | Structured array with `rejected_because` |
+| Status lifecycle | None | `active` / `proposed` / `superseded` / `deprecated` / `rejected` |
+| Bidirectional supersede | One-way (`superseded_by`) | Two-way (`superseded_by` + `supersedes`) |
+| Companion timeline coverage | Manual | Automatic |
+| v6.0 acceptance | `paradigm_wisdom_record` rejects `type:'decision'` | First-class |
+
+If you call `paradigm_wisdom_record({type:'decision'})` against a v6 install, you get a structured rejection envelope (`code: 'wisdom_decision_removed'`) pointing you at `paradigm_decision_record`. Same shape as the lore-record rejection envelope, so a calling agent can auto-retry without human intervention.
+
+## Migrating v1/v2 Lore Decisions
+
+Projects that recorded `type: decision` lore entries through v5 are not stranded. On read, the storage layer remaps `type: decision` to `type: insight` and applies the `v6-migrated:from-decision` tag for forensic recovery. Search for the old type still works via the tag (`paradigm_lore_search({ tag: 'v6-migrated:from-decision' })`).
+
+If you want the old entries promoted to canonical decisions in the new store, do it deliberately — read each migrated entry, decide whether it still represents an active decision, and call `paradigm_decision_record` with the structured shape. There is no automatic backfill because the v1/v2 entries lack the structured participant/alternative data the new shape requires.
+
+## When to Use Which Tool
+
+- **Standalone architectural decision** (no implementation code): `paradigm_decision_record`. The companion lore covers the timeline.
+- **Decision made *during* a work session** (alongside implementation): record an `agent-session` lore entry and put the decision in the entry's `decisions` field. If the choice deserves canonical status (search by symbol, supersede tracking, status lifecycle), *also* call `paradigm_decision_record` — the two are not mutually exclusive.
+- **Team convention or coding standard**: `paradigm_wisdom_record({type:'preference', ...})`.
+- **"Don't do X, do Y instead"**: `paradigm_wisdom_record({type:'antipattern', ...})`.
+- **Tracking what changed and when**: `paradigm_history_record` (implementation events).
+
+> **Going deeper:** PARA 501 covers the lore system in detail (including the v6 entry types and the decisions-have-their-own-store callout). PARA 601 covers the three knowledge streams (work-log, journal, decisions) and how the companion-lore pattern fits into the broader stream architecture.

package/dist/university-content/notes/N-para-301-doctor-and-validation.md

@@ -0,0 +1,70 @@
+---
+id: N-para-301-doctor-and-validation
+title: Doctor & Validation
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - paradigm-doctor-cli
+  - paradigmpurposevalidate-mcp-tool
+  - paradigmflowcheck
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## Doctor & Validation
+
+As a Paradigm project evolves, its metadata can drift out of sync with the actual code. A component gets renamed but its `.purpose` file still references the old name. A gate is added to `portal.yaml` but never implemented. An aspect loses its code anchor when someone refactors the file it pointed to. Paradigm's validation tools catch these inconsistencies before they cause confusion.
+
+The `paradigm doctor` CLI command runs a comprehensive health check across your entire project. It validates several categories of issues:
+
+- **Purpose file integrity**: Are all `.purpose` files valid YAML? Do all symbol references use correct prefixes?
+- **Portal.yaml consistency**: Do routes reference gates that are actually defined? Are there gates defined but never used?
+- **Aspect anchor verification**: Do all `~aspect` symbols have anchors? Do those anchors point to files and lines that still exist?
+- **Orphaned symbol detection**: Are there symbols defined in `.purpose` files that are never referenced anywhere else?
+- **Cross-reference validation**: When `#checkout-form` says it uses `$checkout-flow`, does that flow actually exist?
+
+```bash
+$ paradigm doctor
+
+Checking .purpose files...
+  src/features/checkout/.purpose - OK
+  src/features/auth/.purpose - WARNING: #legacy-login referenced but not defined
+  src/services/.purpose - OK
+
+Checking portal.yaml...
+  ^authenticated - OK (used in 12 routes)
+  ^project-admin - WARNING: defined but used in 0 routes
+
+Checking aspects...
+  ~audit-required - ERROR: anchor src/middleware/audit.ts:15-35 not found
+  ~rate-limited - OK
+
+Results: 2 warnings, 1 error
+```
+
+For more targeted validation, the MCP tool `paradigm_purpose_validate` lets you check a specific `.purpose` file or validate all files. You can also include portal.yaml validation with the `includePortal` parameter. This is useful after making changes to a specific area -- run validation on just the files you touched rather than the entire project.
+
+The `paradigm_flow_check` tool specifically validates flow definitions. It checks that gates referenced in flow steps exist in `portal.yaml`, that actions described in steps have corresponding implementations in the codebase (when `checkImplementation` is true), and that signals emitted during the flow are properly defined.
+
+A good rhythm is to run `paradigm doctor` after major changes (adding features, refactoring, renaming symbols) and before committing. Many teams integrate it into their pre-commit hooks or CI pipelines. Think of it as a linter for your Paradigm metadata -- catching problems early is always cheaper than debugging them later.
+
+### Clarification Markers
+
+When a requirement is ambiguous or incomplete in a `.purpose` file, use the `[NEEDS CLARIFICATION: ...]` marker format instead of guessing. For example:
+
+```yaml
+components:
+  payment-processor:
+    description: "Processes payments via Stripe [NEEDS CLARIFICATION: should this support PayPal fallback?]"
+```
+
+Clarification markers are reported as **warnings** (not errors) by both `paradigm doctor` and `paradigm_purpose_validate`. They do not block validation or break builds, but they surface during health checks to remind the team that a design question remains open. The exact format `[NEEDS CLARIFICATION: <question>]` is required -- the tooling scans for this specific prefix in all description fields across `.purpose` files. Resolve all markers before shipping by replacing them with the clarified text.

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

@@ -0,0 +1,102 @@
+---
+id: N-para-301-enforcement-levels
+title: Enforcement Levels
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+  - three-enforcement-levels
+  - minimal-is-the
+  - 13-checks-control
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+---
+
+## The Three Enforcement Levels
+
+Paradigm enforcement is configurable. Not every project needs the same rigor — a weekend prototype has different needs than a healthcare platform. Enforcement levels control which compliance checks **block** (stop you), **warn** (notify but continue), or are **off** (silent).
+
+### Minimal — For Learning and Prototyping
+
+Minimal enforcement is the default for new projects created by `paradigm shift`. Only two checks are active, both as warnings:
+
+- `purpose-coverage` — warns if source directories lack `.purpose` files
+- `habits-blocking` — warns if defined habits are being violated
+
+Everything else is off. This means hooks never block you, so you can learn Paradigm without friction. You can always run checks manually with `paradigm doctor`.
+
+### Balanced — For Active Development
+
+When your team is comfortable with Paradigm, upgrade to balanced. This is where most teams operate:
+
+- **Blocks on:** `purpose-coverage` (must have purpose files), `habits-blocking` (must follow habits)
+- **Warns on:** `purpose-exists`, `portal-gates`, `aspect-anchors`, `purpose-freshness`, `lore-required`, `purpose-required-patterns`, `drift-detection`, `portal-compliance`, `orchestration-required`
+- **Off:** `aspect-advisory`, `graduation-tracking`
+
+Balanced catches problems early without being oppressive. The stop hook blocks on missing purpose files but lets you work freely otherwise.
+
+### Strict — For Regulated Domains
+
+Healthcare, finance, legal — domains where compliance is not optional. Strict blocks on nearly everything:
+
+- **Blocks on:** `purpose-coverage`, `purpose-exists`, `portal-gates`, `aspect-anchors`, `lore-required`, `habits-blocking`, `purpose-required-patterns`, `drift-detection`, `portal-compliance`, `orchestration-required`
+- **Warns on:** `purpose-freshness`, `aspect-advisory`, `graduation-tracking`
+
+With strict enforcement, you cannot commit without purpose files, portal gates, lore records, and passing drift checks. This ensures every change is documented and traceable.
+
+## Configuration
+
+Set the level in `.paradigm/config.yaml`:
+
+```yaml
+enforcement:
+  level: balanced   # minimal | balanced | strict
+```
+
+Override individual checks when a preset does not quite fit:
+
+```yaml
+enforcement:
+  level: balanced
+  checks:
+    orchestration-required: block   # Upgrade from warn to block
+    lore-required: off              # Downgrade — we don't need lore yet
+```
+
+Per-check overrides take precedence over the preset. This lets you start with a base level and tune specific checks to match your team's workflow.
+
+## The 13 Checks
+
+| Check | What It Validates |
+|-------|------------------|
+| `purpose-coverage` | Source directories have .purpose files |
+| `purpose-exists` | Referenced purpose files actually exist on disk |
+| `portal-gates` | Routes in portal.yaml have required gates defined |
+| `aspect-anchors` | Aspect anchors point to valid code locations |
+| `purpose-freshness` | Purpose files are not stale (content matches code) |
+| `aspect-advisory` | Components have at least one aspect (1:1 ratio) |
+| `lore-required` | Sessions modifying 3+ files record lore |
+| `habits-blocking` | Defined habits are being followed |
+| `purpose-required-patterns` | Required patterns (flows, gates) are present |
+| `drift-detection` | Aspect anchor code has not drifted |
+| `portal-compliance` | Portal.yaml matches actual route definitions |
+| `graduation-tracking` | Habits are graduating through automation tiers |
+| `orchestration-required` | Complex tasks use multi-agent orchestration |
+
+## Progression Strategy
+
+Most teams follow this path:
+
+1. **Start minimal** — learn Paradigm, build habits, no blocking
+2. **Move to balanced** after 1-2 weeks — catch issues early, still flexible
+3. **Upgrade to strict** for production-critical or regulated codebases
+
+You can change levels at any time. The switch is immediate — no migration needed.

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

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

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

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

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

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