@a-company/paradigm 5.38.0 → 6.0.4

package/dist/university-content/quizzes/Q-para-201-component-patterns.yaml

@@ -0,0 +1,56 @@
+id: Q-para-201-component-patterns
+title: 'PARA 201: Architecture — Component Patterns'
+description: 'Quiz for lesson: Component Patterns'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: A Redis caching layer is used by the user service, the product service, and the search service. How should it be tagged?
+    choices:
+      A: 'tags: [feature, redis] — because users interact with cached data'
+      B: 'tags: [integration, redis] — because Redis is a third-party service'
+      C: 'tags: [state, cache, redis] — because it manages data storage'
+      D: 'tags: [infrastructure, redis] — because it is a foundational service'
+      E: Both C and D are acceptable, depending on whether caching is the primary purpose or a supporting capability
+    correct: E
+    explanation: 'If the component''s primary purpose is data caching (storing and retrieving cached data), tags: [state, cache, redis] is appropriate. If it is more of a foundational service that provides caching as infrastructure, tags: [infrastructure, cache, redis] fits. Both are valid interpretations.'
+  - id: q2
+    question: You have a 500-line module that handles payment processing AND sends email receipts. What should you do?
+    choices:
+      A: Keep it as one component — splitting would be premature optimization
+      B: 'Split into #payment-processor and #receipt-emailer — they have distinct responsibilities'
+      C: Create a $payment-receipt-flow instead of splitting
+      D: Add more tags to cover both responsibilities in one component
+      E: Move the email logic into the logger
+    correct: B
+    explanation: Payment processing and email sending are distinct responsibilities that could change independently (e.g., switching email providers without touching payment logic). The module is also large (500 lines). Splitting into two focused components follows the 'split when responsibilities are distinct' guideline.
+  - id: q3
+    question: Why should you check paradigm_history_fragility before modifying infrastructure components?
+    choices:
+      A: Because infrastructure components have more lines of code
+      B: Because many other components depend on them, making changes high-risk
+      C: Because infrastructure components are never tested
+      D: Because the fragility check automatically creates a backup
+      E: Because infrastructure tags prevent direct modification
+    correct: B
+    explanation: 'Infrastructure components (logger, config-loader, database-pool) are foundational — many other components depend on them. A breaking change to #database-pool could cascade across the entire application. Fragility analysis warns you about this risk before you make changes.'
+  - id: q4
+    question: What is wrong with splitting a payment module into `#payment-step-1` and `#payment-step-2`?
+    choices:
+      A: Components cannot have numbers in their names
+      B: There should be three components minimum
+      C: The names are non-descriptive and the split is artificial — neither component has an independent responsibility
+      D: Steps should be defined as a flow, not as components
+      E: The hyphen before the number violates kebab-case
+    correct: C
+    explanation: 'If you cannot describe a component without referencing ''the other half,'' the split is artificial. #payment-step-1 and #payment-step-2 are not independent responsibilities — they are an arbitrary division of a single unit. Keep them as one component with a clear description.'

package/dist/university-content/quizzes/Q-para-201-cross-cutting-concerns.yaml

@@ -0,0 +1,56 @@
+id: Q-para-201-cross-cutting-concerns
+title: 'PARA 201: Architecture — Cross-Cutting Concerns'
+description: 'Quiz for lesson: Cross-Cutting Concerns'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: All API handlers must validate input against a defined schema. Should this be modeled as a gate, signal, or aspect?
+    choices:
+      A: ^ gate — it checks a condition before processing
+      B: '! signal — it fires when validation fails'
+      C: ~ aspect — it is a structural pattern applied across all handlers
+      D: $ flow — it is a step in the request processing flow
+      E: '# component — it is a validation utility'
+    correct: C
+    explanation: Input validation across all handlers is a cross-cutting concern — the same pattern (validate against a schema) applies to every handler. This is an aspect (~validated), not a gate (gates check conditions like authorization, not input format) or a signal (validation is a structural requirement, not an event).
+  - id: q2
+    question: 'An aspect `~cached` has `applies-to: ["#*-query"]`. You create `#user-query` without applying caching. What is the recommended action?'
+    choices:
+      A: Nothing — aspects are just documentation
+      B: Delete the ~cached aspect since it does not apply universally
+      C: 'Apply the caching pattern to #user-query, since it matches the applies-to pattern'
+      D: 'Rename #user-query to #user-fetch to avoid matching the pattern'
+      E: 'Add an exception for #user-query in the aspect definition'
+    correct: C
+    explanation: 'When a new component matches an aspect''s applies-to pattern, the aspect should be applied. If ~cached applies to all #*-query components, then #user-query should use the caching pattern. If there is a genuine reason to exempt it, document that exception rather than working around the naming.'
+  - id: q3
+    question: Why is a rate limiter classified as an aspect (~rate-limited) rather than a gate (^rate-limited)?
+    choices:
+      A: Because rate limiters are implemented in middleware
+      B: Because rate limiters do not return 403 status codes
+      C: Because rate limiting is a structural pattern applied across many endpoints, not a per-resource authorization check
+      D: Because rate limiters do not require authentication
+      E: Because the ~ prefix is alphabetically closer to 'rate'
+    correct: C
+    explanation: Gates check specific conditions per request — 'is this user allowed to access this resource?' or 'is this feature enabled?' Rate limiting is a different concern — it applies the same pattern (request counting and throttling) across many endpoints as a structural rule. This cross-cutting nature makes it an aspect.
+  - id: q4
+    question: After a large refactor that moved files, what is the correct procedure for maintaining aspects?
+    choices:
+      A: Delete all aspects and recreate them from scratch
+      B: Run paradigm_aspect_check to find broken anchors, then update the anchor paths in .purpose files
+      C: Aspects automatically update their anchors when files move
+      D: Ignore broken anchors — they will fix themselves on the next paradigm scan
+      E: Convert all aspects to gates since gates do not have anchors
+    correct: B
+    explanation: After refactoring, run paradigm_aspect_check to identify which anchors now point to moved or renamed files. Then update the anchors in the .purpose files to reflect the new file paths and line numbers. This maintenance is the trade-off for having verifiable enforcement code.

package/dist/university-content/quizzes/Q-para-201-disciplines.yaml

@@ -0,0 +1,66 @@
+id: Q-para-201-disciplines
+title: 'PARA 201: Architecture — Disciplines'
+description: 'Quiz for lesson: Disciplines'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: In a web discipline project, what symbol type should a frontend hook like `useAuth` be classified as?
+    choices:
+      A: '! signal — hooks fire events'
+      B: ^ gate — hooks check conditions
+      C: '# component — hooks are code units that encapsulate logic'
+      D: $ flow — hooks define sequences
+      E: ~ aspect — hooks are cross-cutting concerns
+    correct: C
+    explanation: 'Hooks are code units, not events. A frontend hook like useAuth encapsulates authentication logic — it is #useAuth, a component. The ! signal prefix is reserved for events that trigger decoupled side effects, which is not what hooks do.'
+  - id: q2
+    question: A project has `src/client/` for frontend and `src/server/` for backend code. Which discipline should be used?
+    choices:
+      A: web — because the client directory is listed first
+      B: backend — because server code is more important
+      C: fullstack — it combines both web and backend mappings based on directory path
+      D: library — because the code is shared between client and server
+      E: cli — because the server might have CLI commands
+    correct: C
+    explanation: 'The fullstack discipline combines web and backend mappings. It uses the directory path to determine which mapping applies: src/client/ uses web discipline rules, src/server/ uses backend rules.'
+  - id: q3
+    question: What three things does the discipline setting affect in Paradigm tooling?
+    choices:
+      A: Build output, test runner, deployment target
+      B: Navigator generation, logging conventions, gate recommendations
+      C: File naming, import paths, type definitions
+      D: Package manager, bundler, linter configuration
+      E: Database schema, API schema, UI schema
+    correct: B
+    explanation: 'The discipline affects: (1) navigator generation — how paradigm scan categorizes directories, (2) logging conventions — which log methods are conventional for each directory, and (3) gate recommendations — what paradigm_gates_for_route suggests.'
+  - id: q4
+    question: Your backend project has a `policies/` directory for authorization policies. You want Paradigm to treat them as gates. How do you configure this?
+    choices:
+      A: Rename the directory to middleware/
+      B: Change the discipline to 'web' since it handles auth differently
+      C: 'Add a custom-mappings entry in config.yaml: "policies/": "^"'
+      D: Create a .purpose file with only gate definitions
+      E: It is not possible — gates can only live in middleware/
+    correct: C
+    explanation: 'Custom mappings in config.yaml extend the discipline defaults. Adding "policies/": "^" tells Paradigm to treat files in the policies/ directory as gates, without changing the overall discipline or renaming directories.'
+  - id: q5
+    question: 'A Next.js project runs `paradigm init`. The output shows `discipline: fullstack` and `stack: nextjs`. What does the stack preset add that the discipline alone does not provide?'
+    choices:
+      A: A completely different set of symbol mappings that replaces the discipline
+      B: Framework-specific scan hints, refined symbol mappings for Next.js patterns like app/ routes, and purpose-required paths
+      C: Automatic code generation for Next.js boilerplate
+      D: A Next.js-specific version of portal.yaml with pre-defined gates
+      E: Nothing — stack presets and disciplines are the same thing
+    correct: B
+    explanation: Stack presets layer framework-specific configuration on top of disciplines. For Next.js, the preset adds knowledge about app/ directory routing, server components, API route handlers, and other Next.js-specific patterns. It refines the generic fullstack discipline with framework-aware scan hints and purpose-required paths. Presets extend disciplines — they do not replace them.

package/dist/university-content/quizzes/Q-para-201-flows-deep-dive.yaml

@@ -0,0 +1,66 @@
+id: Q-para-201-flows-deep-dive
+title: 'PARA 201: Architecture — Flows in Depth'
+description: 'Quiz for lesson: Flows in Depth'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: A controller calls a service, which queries a database and returns a result. Should this be a $flow?
+    choices:
+      A: Yes — any multi-step process should be a flow
+      B: Yes — database queries always require flow documentation
+      C: No — this is a two-component interaction with no sequence ambiguity
+      D: No — flows can only be used for user-facing features
+      E: It depends on whether the service emits a signal
+    correct: C
+    explanation: A flow is warranted when logic spans three or more components in a specific order. A controller calling a service (with its database query) is a straightforward two-component interaction that can be documented on the component itself.
+  - id: q2
+    question: Where should a $checkout-flow be defined if the checkout process starts in the cart module?
+    choices:
+      A: In .paradigm/flows/checkout.yaml
+      B: In portal.yaml under a flows section
+      C: In src/cart/.purpose, since the cart module initiates the flow
+      D: In every .purpose file of every component involved in the flow
+      E: In a standalone checkout-flow.purpose file at the project root
+    correct: C
+    explanation: Flows are defined in the .purpose file of the initiating component's directory. Since the checkout flow starts in the cart module, it belongs in src/cart/.purpose. The flow will reference components from other directories.
+  - id: q3
+    question: 'What does `paradigm_flow_check` with `checkImplementation: true` verify?'
+    choices:
+      A: That the flow executes correctly at runtime
+      B: That referenced components exist in .purpose files, actions are implemented, and signals are emitted
+      C: That the flow has fewer than 10 steps
+      D: That all flows use the same naming convention
+      E: That the flow is referenced in portal.yaml
+    correct: B
+    explanation: 'With checkImplementation: true, the validator performs deep checks: it verifies that referenced #components exist in .purpose files, that the named actions are implemented in the actual codebase, and that listed signals are actually emitted. This catches documentation-code drift.'
+  - id: q4
+    question: What is the fundamental nature of a Paradigm flow?
+    choices:
+      A: A workflow engine that orchestrates service calls at runtime
+      B: A saga implementation with rollback support
+      C: Documentation metadata describing what happens in a sequence, not how to execute it
+      D: A state machine that transitions between components
+      E: An event bus configuration defining message routing
+    correct: C
+    explanation: Flows are documentation, not orchestration. They describe the sequence of operations for humans and AI agents to understand. Your code still handles the actual service calls, error handling, and state management however you choose to implement it.
+  - id: q5
+    question: '`$checkout-flow` lists `relatedFlows: [$payment-flow]` and `$payment-flow` lists `relatedFlows: [$checkout-flow]`. What does `paradigm_flow_check` report?'
+    choices:
+      A: No issues — bidirectional references are valid
+      B: 'A circular dependency: $checkout-flow → $payment-flow → $checkout-flow'
+      C: A missing step error — related flows must appear as steps
+      D: A naming violation — flows cannot reference each other
+      E: A warning about duplicate flow definitions
+    correct: B
+    explanation: When flows reference each other in a cycle via relatedFlows, Paradigm detects it as a circular dependency using depth-first search. The resolution is to extract shared logic into a third flow, remove one direction of the dependency, or replace direct flow references with signal-based communication.

package/dist/university-content/quizzes/Q-para-201-gates-deep-dive.yaml

@@ -0,0 +1,66 @@
+id: Q-para-201-gates-deep-dive
+title: 'PARA 201: Architecture — Gates in Depth'
+description: 'Quiz for lesson: Gates in Depth'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: A gate checks whether a user's subscription is active before allowing access to premium content. What type should this gate be?
+    choices:
+      A: auth — it verifies the user's identity
+      B: role — it checks the user's permission level
+      C: ownership — it verifies resource ownership
+      D: state-precondition — it verifies the system is in the right condition
+      E: integration — it checks a third-party service
+    correct: D
+    explanation: This gate verifies system state — whether the subscription is active — rather than identity (auth), permission level (role), or resource ownership. State-precondition gates check conditions about the current state of data.
+  - id: q2
+    question: 'What is wrong with this gate check expression: `check: user is admin`?'
+    choices:
+      A: Nothing — it is clear and concise
+      B: It should use JavaScript syntax, not English
+      C: It is too vague — a developer cannot implement it without more information
+      D: It is missing the req. prefix
+      E: Gate checks must be written in YAML, not pseudo-code
+    correct: C
+    explanation: 'Check expressions should be precise enough to implement from reading the expression. ''user is admin'' does not specify how admin status is determined — is it a boolean field? A role in an array? A separate table? A better expression: project.admins.includes(req.user.id).'
+  - id: q3
+    question: 'A route requires `[^authenticated, ^org-admin, ^billing-enabled]`. The `^org-admin` gate has `requires: [^authenticated]`. What happens at runtime?'
+    choices:
+      A: ^authenticated runs twice — once from the route, once from ^org-admin's requires
+      B: ^authenticated runs once, ^org-admin runs once, ^billing-enabled runs once — in that order
+      C: An error is thrown because ^authenticated is listed both in the route and in requires
+      D: All three gates run in parallel for performance
+      E: Only ^billing-enabled runs because the other two are implicit from requires
+    correct: B
+    explanation: 'Gate chains prevent redundant checks. ^authenticated is required by ^org-admin, but since the route lists ^authenticated first, it runs once and subsequent gates know it already passed. The three gates execute in order: authenticated, org-admin, billing-enabled.'
+  - id: q4
+    question: When should the `effects` field be an empty array `[]`?
+    choices:
+      A: Never — every gate must have at least one prize
+      B: When the gate has no side effects to trigger on pass
+      C: When the gate is of type 'auth'
+      D: When the gate is used on GET routes only
+      E: When the gate has been deprecated
+    correct: B
+    explanation: 'Use effects: [] when the gate has no side effects. Most gates simply allow or deny access without triggering additional actions. Effects are for special cases like gamification badges, onboarding rewards, or analytics events.'
+  - id: q5
+    question: 'portal.yaml says `"DELETE /api/posts/:id": [^authenticated, ^post-author]`, but the route handler only checks authentication, not authorship. What is the consequence?'
+    choices:
+      A: No consequence — portal.yaml is just documentation
+      B: The route will return 403 automatically based on portal.yaml
+      C: Any authenticated user can delete any post — a security vulnerability caused by the implementation not matching the specification
+      D: The paradigm scan command will fix the discrepancy automatically
+      E: The delete will fail silently
+    correct: C
+    explanation: portal.yaml defines what SHOULD happen, but your code must implement it. If the middleware only checks authentication without verifying post authorship, any logged-in user can delete any post. This is a security vulnerability caused by specification-implementation drift.

package/dist/university-content/quizzes/Q-para-201-portal-protocol.yaml

@@ -0,0 +1,56 @@
+id: Q-para-201-portal-protocol
+title: 'PARA 201: Architecture — The Portal Protocol'
+description: 'Quiz for lesson: The Portal Protocol'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: You need to add `DELETE /api/teams/:id`. What is the FIRST step in the Portal Protocol?
+    choices:
+      A: Write the delete handler and add authentication middleware
+      B: Add the route to portal.yaml with [^authenticated]
+      C: Call paradigm_gates_for_route to get gate suggestions
+      D: Write a test for the 403 response
+      E: Create a ^team-admin gate in middleware
+    correct: C
+    explanation: The Portal Protocol starts with asking Paradigm. Call paradigm_gates_for_route with the route and method to get suggestions based on existing patterns. This ensures you consider all necessary gates before implementation.
+  - id: q2
+    question: 'Your portal.yaml specifies `"PUT /api/posts/:id": [^authenticated, ^post-author]`. Your middleware only checks ^authenticated. What is the security impact?'
+    choices:
+      A: None — portal.yaml automatically enforces all listed gates
+      B: Any authenticated user can edit any post, because the ^post-author check is missing from the implementation
+      C: The route will return 500 because of the missing gate
+      D: Paradigm will block the request at the framework level
+      E: The post-author gate runs automatically via the requires field
+    correct: B
+    explanation: portal.yaml is a specification, not enforcement. If the middleware does not implement the ^post-author check, any authenticated user can edit any post. This is a security vulnerability caused by the implementation not matching the specification.
+  - id: q3
+    question: In a web API, which HTTP status code should a failed authentication gate return, versus a failed authorization gate?
+    choices:
+      A: Both return 403 Forbidden
+      B: Authentication returns 401 Unauthorized; authorization returns 403 Forbidden
+      C: Authentication returns 403 Forbidden; authorization returns 401 Unauthorized
+      D: Both return 401 Unauthorized
+      E: Authentication returns 400 Bad Request; authorization returns 403 Forbidden
+    correct: B
+    explanation: In the HTTP discipline, the standard distinguishes between authentication (who are you?) and authorization (are you allowed?). A failed auth gate (^authenticated) returns 401 Unauthorized. A failed role/ownership gate (^project-admin) returns 403 Forbidden. Note that this is the web API implementation — other disciplines express gate failure differently (a mobile app might show a login screen or disable a button; a CLI might exit with an error code).
+  - id: q4
+    question: Why does the Portal Protocol require defining gates BEFORE writing handler code?
+    choices:
+      A: Because Paradigm cannot parse handler code that already exists
+      B: Because it creates an auditable specification separate from implementation, preventing conditions as an afterthought
+      C: Because TypeScript requires gate types to be defined before use
+      D: Because AI agents refuse to write code without portal.yaml
+      E: Because gate middleware must be loaded before route handlers in the server stack
+    correct: B
+    explanation: The Portal Protocol's core principle is specification before implementation. By specifying gates in portal.yaml first, you create an auditable specification that is separate from (and checkable against) the implementation. This prevents the common pattern of building features first and bolting on checks later.

package/dist/university-content/quizzes/Q-para-201-signal-patterns.yaml

@@ -0,0 +1,56 @@
+id: Q-para-201-signal-patterns
+title: 'PARA 201: Architecture — Signal Patterns'
+description: 'Quiz for lesson: Signal Patterns'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: The order service needs to send a confirmation email after an order is placed. What is the correct architecture?
+    choices:
+      A: The order service directly calls the email service's sendEmail method
+      B: The order service emits !order-placed; the email service listens to that signal
+      C: The email service polls the order service every 5 seconds for new orders
+      D: A $send-email-flow orchestrates the interaction
+      E: The order service includes email logic internally
+    correct: B
+    explanation: Signal-based communication decouples the order service from the email service. The order service emits !order-placed and does not know who listens. The email service independently listens for that signal. This means you can add more listeners (analytics, loyalty points) without touching the order service.
+  - id: q2
+    question: Where are signal listeners documented in Paradigm?
+    choices:
+      A: On the signal definition in the 'listeners' field
+      B: On the listening component in a 'listens' field
+      C: In portal.yaml under a 'listeners' section
+      D: In .paradigm/config.yaml
+      E: They are not documented — only emitters are tracked
+    correct: B
+    explanation: Listeners are documented on the component that listens, using a 'listens' field. This asymmetry is intentional — the emitter declares what it emits (on the signal), and each listener independently declares what it consumes (on the component). This maintains true decoupling.
+  - id: q3
+    question: A failed login attempt from an unknown IP should emit what category of signal?
+    choices:
+      A: business — it affects the user's experience
+      B: system — it is an infrastructure event
+      C: security — it is an authentication event relevant to audit trails
+      D: error — it indicates a system failure
+      E: It should not emit a signal — failed logins are expected
+    correct: C
+    explanation: Failed login attempts are security events. They are critical for audit trails, intrusion detection, and monitoring suspicious activity. The signal (!login-failed) should include data like email, reason, and IP address to support security analysis.
+  - id: q4
+    question: A system currently has !order-placed consumed by 3 listeners. A developer needs to add a Slack notification when orders are placed. What must change?
+    choices:
+      A: The !order-placed signal definition must be updated to list the Slack notifier as an emitter
+      B: The $order-flow must add a Slack notification step
+      C: 'Only the new #slack-notifier component needs a ''listens: ["!order-placed"]'' declaration — nothing else changes'
+      D: 'The #order-service must be modified to call the Slack API'
+      E: portal.yaml must add a ^slack-authorized gate
+    correct: C
+    explanation: This is the power of signal-based decoupling. Adding a new listener requires only defining the new component with its 'listens' field. The signal definition, the emitting component, and all existing listeners remain untouched.

package/dist/university-content/quizzes/Q-para-201-symbol-naming.yaml

@@ -0,0 +1,66 @@
+id: Q-para-201-symbol-naming
+title: 'PARA 201: Architecture — Symbol Naming Conventions'
+description: 'Quiz for lesson: Symbol Naming Conventions'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+questions:
+  - id: q1
+    question: Which of these signal names follows Paradigm naming conventions?
+    choices:
+      A: '!processPayment'
+      B: '!payment-completed'
+      C: '!PaymentSignal'
+      D: '!creating-user'
+      E: '!payment_done'
+    correct: B
+    explanation: 'Signals use kebab-case and past-tense naming: !payment-completed. Option A uses camelCase and imperative mood. C uses PascalCase. D uses progressive tense. E uses underscores instead of hyphens.'
+  - id: q2
+    question: 'A flow that handles user registration from form submission to welcome email should be named:'
+    choices:
+      A: $doRegistration
+      B: $registerUser
+      C: $user-registration-flow
+      D: $REGISTRATION
+      E: $flow_register
+    correct: C
+    explanation: Flows use kebab-case with a noun-flow pattern. $user-registration-flow is descriptive and follows the convention. Imperative names (doRegistration, registerUser), ALL CAPS, and underscores all violate the naming rules.
+  - id: q3
+    question: What is wrong with the gate name `^check1`?
+    choices:
+      A: Nothing — it is valid kebab-case
+      B: Gates must start with a verb
+      C: The number 1 is not allowed in symbol names
+      D: It is non-descriptive — the name should describe what the gate verifies
+      E: Gates must end with '-gate'
+    correct: D
+    explanation: 'Gate names should describe what they verify: ^project-admin, ^email-verified, ^subscription-active. The name ^check1 tells you nothing about what condition is being checked. A developer or AI agent cannot infer the gate''s purpose from its name.'
+  - id: q4
+    question: A component wraps the Stripe API for payment processing. Its class is `StripePaymentClient`. What should its .purpose ID be?
+    choices:
+      A: '#StripePaymentClient'
+      B: '#stripe-payment-client'
+      C: '#stripe_payment_client'
+      D: '#stripePaymentClient'
+      E: '#STRIPE-CLIENT'
+    correct: B
+    explanation: 'All symbol IDs in .purpose files use kebab-case: #stripe-payment-client. The PascalCase class name (StripePaymentClient) is fine in code and descriptions, but the ID must be kebab-case.'
+  - id: q5
+    question: 'Which aspect name reads most naturally in the sentence: ''All financial services are ___''?'
+    choices:
+      A: ~doAudit
+      B: ~auditStuff
+      C: ~audit-required
+      D: ~auditService
+      E: ~the-audit-aspect
+    correct: C
+    explanation: 'Aspect names should read as adjectives or past-participles: ''All financial services are ~audit-required.'' Options A and B are informal/imperative, D sounds like a component name, and E is unnecessarily verbose.'

package/dist/university-content/quizzes/Q-para-301-context-management.yaml

@@ -0,0 +1,56 @@
+id: Q-para-301-context-management
+title: 'PARA 301: Operations — Context Management'
+description: 'Quiz for lesson: Context Management'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-301
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-301.json
+questions:
+  - id: q1
+    question: How often should you call paradigm_session_health during a long session?
+    choices:
+      A: Only at the start of the session
+      B: Every 10-15 tool calls
+      C: Only when the AI starts forgetting things
+      D: Once per hour
+      E: Only before handoff
+    correct: B
+    explanation: The recommended cadence for context checks is every 10-15 tool calls. This proactive monitoring lets you prepare for handoff before context is exhausted, rather than discovering the limit when it is too late.
+  - id: q2
+    question: paradigm_session_health returns 'handoff-soon'. What should you do?
+    choices:
+      A: Ignore it and keep working
+      B: Immediately stop all work
+      C: Finish the current task, then call paradigm_handoff_prepare with summary and next steps
+      D: Delete old messages to free up context
+      E: Switch to a model with a larger context window
+    correct: C
+    explanation: When handoff is recommended, prioritize completing the current task (if close to done), then prepare a handoff summary. paradigm_handoff_prepare captures what was done, files modified, next steps, and open questions so the next session can continue seamlessly.
+  - id: q3
+    question: What is the first thing a new AI agent session should do to continue work from a previous session?
+    choices:
+      A: Read every file that was modified
+      B: Call paradigm_session_recover to load breadcrumbs from the previous session
+      C: Start the task from scratch
+      D: Call paradigm_doctor to validate the project
+      E: Run paradigm scan to rebuild the index
+    correct: B
+    explanation: paradigm_session_recover loads the breadcrumbs and handoff summary from the previous session. This tells the new agent what was done, what files were modified, what remains, and any open questions -- enabling seamless continuity.
+  - id: q4
+    question: At what context usage threshold does Paradigm recommend preparing a handoff?
+    choices:
+      A: 50%
+      B: 65%
+      C: 75%
+      D: 85%
+      E: 95%
+    correct: D
+    explanation: When context usage exceeds 85%, Paradigm recommends preparing a handoff. This leaves enough room to complete the current task and create a proper handoff summary without running out of context.

package/dist/university-content/quizzes/Q-para-301-decisions.yaml

@@ -0,0 +1,76 @@
+id: Q-para-301-decisions
+title: 'PARA 301: Operations — The Decision Store'
+description: 'Quiz for lesson: The Decision Store'
+author: paradigm
+created: '2026-04-18'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-301
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: authored
+source: v6.0-content-fix
+questions:
+  - id: q1
+    question: In Paradigm v6.0, where do architectural decisions live?
+    choices:
+      A: '`.paradigm/wisdom/decisions.yaml` — written via `paradigm_wisdom_record({ type: ''decision'', ... })`'
+      B: '`.paradigm/lore/entries/{date}/L-*.yaml` — written via `paradigm_lore_record({ type: ''decision'', ... })`'
+      C: '`.paradigm/decisions/TD-*.yaml` — written via `paradigm_decision_record`, with a companion lore `insight` auto-written for timeline coverage'
+      D: '`.paradigm/history/decisions.jsonl` — written via `paradigm_history_record({ type: ''decision'', ... })`'
+      E: They live in commit messages with the `decision:` trailer
+    correct: C
+    explanation: 'In v6.0 decisions moved to a dedicated topic-addressable store at `.paradigm/decisions/`. Each decision is one `TD-*.yaml` file recorded via `paradigm_decision_record`. A companion lore entry of `type: ''insight''` is auto-written so the timeline still surfaces when the decision was made. Both `paradigm_wisdom_record({type:''decision''})` (A) and `paradigm_lore_record({type:''decision''})` (B) reject with a structured envelope pointing at the new tool.'
+  - id: q2
+    question: You call `paradigm_decision_record` and it succeeds. What gets written to disk?
+    choices:
+      A: Only the `TD-*.yaml` decision file
+      B: The `TD-*.yaml` decision file AND a companion lore `insight` entry with `references.decision_id` back-pointing to the TD- id
+      C: Only the companion lore entry — decisions are stored as a special lore type
+      D: Three files — one in decisions, one in wisdom, one in lore (for backward compat)
+      E: Nothing on disk — decisions are kept in memory only
+    correct: B
+    explanation: 'Two artifacts are written. (1) The canonical decision goes to `.paradigm/decisions/TD-*.yaml` — topic-addressable, with full ADR shape. (2) A companion lore entry of `type: ''insight''` goes to `.paradigm/lore/entries/{date}/L-*.yaml` with `references.decision_id` pointing back at the TD- id and the `companion-lore` + `decision-reference` tags. The lore entry keeps the project timeline complete; the TD- entry stays the source of truth. The companion write is best-effort — a failure to write the lore entry never blocks the decision record.'
+  - id: q3
+    question: 'A teammate has a v5 project with old `type: decision` lore entries in `.paradigm/lore/entries/`. They upgrade to v6.0 and run `paradigm_lore_search`. What happens to those old entries?'
+    choices:
+      A: They disappear — decisions are no longer a valid lore type
+      B: 'They are auto-deleted on the first read after upgrade'
+      C: 'They are remapped to `type: insight` on read and tagged `v6-migrated:from-decision`, so they remain searchable via the tag'
+      D: 'They throw errors and block lore-search until the user manually edits each one'
+      E: 'They are auto-converted into `paradigm_decision_record` entries in `.paradigm/decisions/`'
+    correct: C
+    explanation: 'v1/v2 entries with `type: decision` are remapped to `type: insight` on read with the `v6-migrated:from-decision` tag applied for forensic recovery. The old entries remain searchable (`paradigm_lore_search({ tag: ''v6-migrated:from-decision'' })`). There is no automatic conversion to canonical TD- records (E) — the v1/v2 entries lack the structured participant/alternative data the new shape requires, so promotion to the new store is deliberate, one-by-one.'
+  - id: q4
+    question: 'In v6.0, you call `paradigm_lore_record({ type: ''decision'', title: ''Use Redis'', ... })`. What is the response?'
+    choices:
+      A: 'The entry is recorded successfully — `decision` is still a valid lore type'
+      B: 'A structured rejection envelope (code: ''lore_type_decision_removed'', successor_tool: ''paradigm_decision_record'') so a calling agent can auto-retry against the right tool without human intervention'
+      C: A silent no-op — the call returns success but nothing is written
+      D: The entry is written but flagged as deprecated and hidden from search
+      E: The CLI prompts the user interactively to choose a different type
+    correct: B
+    explanation: 'The storage layer (in `packages/paradigm/src/core/lore/storage.ts`) hard-rejects `type: ''decision''` with a structured rejection envelope. The envelope includes `code: ''lore_type_decision_removed''`, `successor_tool: ''paradigm_decision_record''`, `removed_in: ''6.0.0''`, and `doc: ''docs/private/plans/v6.0-decisions-locked.md''`. Same shape applies if you call `paradigm_wisdom_record({type:''decision''})`. The structured shape lets a calling agent (LLM or script) auto-retry against the right tool — no human in the loop required.'
+  - id: q5
+    question: 'You finish a 40-minute work session that modified 5 files and decided to switch from PostgreSQL to CockroachDB. How should you record this in v6.0?'
+    choices:
+      A: 'Just `paradigm_decision_record` — it covers the choice; no lore needed'
+      B: 'Just `paradigm_lore_record({ type: ''agent-session'' })` with the choice in the `decisions` field'
+      C: 'Both: an `agent-session` lore entry covers the work session; if the DB choice also deserves canonical status (search by symbol, status lifecycle), call `paradigm_decision_record` separately. They are not mutually exclusive.'
+      D: 'Use `paradigm_wisdom_record({ type: ''decision'' })` — wisdom captures team choices'
+      E: 'Use `paradigm_history_record` — DB switches are implementation events'
+    correct: C
+    explanation: 'Lore and decisions are not mutually exclusive. The `agent-session` entry captures the work session (5 files modified, what was learned) — and its `decisions` field can hold a brief reference to the DB switch. If the DB choice also deserves canonical status (you want to search "what did we decide about the user-service database?" later), call `paradigm_decision_record` separately. The TD- entry is the canonical source; the agent-session lore covers "what happened that day." D is invalid in v6 (`paradigm_wisdom_record` rejects `type: ''decision''`).'
+  - id: q6
+    question: What does `paradigm_decision_record` give you that `paradigm_wisdom_record({type:''decision''})` (v5 style) did not?
+    choices:
+      A: Nothing — it is just a rename
+      B: Structured participants with stance enum (proposed/supported/dissented/abstained), structured alternatives_considered with rejected_because, status lifecycle (active/superseded/deprecated/rejected), bidirectional supersede tracking, and an automatic companion lore insight for timeline coverage
+      C: Faster writes — TD- files are smaller than wisdom entries
+      D: Encryption — decisions are encrypted at rest, wisdom was not
+      E: Public-key signing — every decision is cryptographically signed
+    correct: B
+    explanation: 'The new tool brings ADR-shape structure that the wisdom path never had: structured participants with a stance enum, structured alternatives_considered with `rejected_because`, a status lifecycle, bidirectional supersede tracking (`superseded_by` + `supersedes`), and the companion-lore pattern for automatic timeline coverage. None of A/C/D/E are real differences — the win is structured-data discipline plus the companion timeline write.'