@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/quizzes/Q-para-101-welcome.yaml

@@ -0,0 +1,56 @@
+id: Q-para-101-welcome
+title: 'PARA 101: Foundations — Welcome to Paradigm'
+description: 'Quiz for lesson: Welcome to Paradigm'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+questions:
+  - id: q1
+    question: What is Paradigm best described as?
+    choices:
+      A: A JavaScript component library for building UIs
+      B: A code generation tool that scaffolds project boilerplate
+      C: A meta-framework that organizes how AI agents understand your codebase
+      D: A testing framework with built-in assertion helpers
+      E: A deployment pipeline tool for CI/CD
+    correct: C
+    explanation: Paradigm is a meta-framework — it does not ship runtime code or components. Its purpose is to give AI agents structured context (symbols, purpose files, specifications) so they can navigate and modify codebases efficiently.
+  - id: q2
+    question: Which of the following is NOT one of Paradigm's three pillars?
+    choices:
+      A: Symbols
+      B: Purpose Files
+      C: Specifications
+      D: Runtime Middleware
+      E: All of the above are pillars
+    correct: D
+    explanation: Paradigm's three pillars are Symbols (the vocabulary), Purpose Files (the directory maps), and Specifications (the project rulebook). Runtime Middleware is not a Paradigm concept — Paradigm is metadata, not runtime code.
+  - id: q3
+    question: What problem does Paradigm primarily solve for AI agents?
+    choices:
+      A: Slow compilation times in large TypeScript projects
+      B: Excessive token usage and missed context when navigating undocumented codebases
+      C: Lack of type safety in JavaScript applications
+      D: Difficulty deploying applications to cloud providers
+      E: Missing test coverage in legacy codebases
+    correct: B
+    explanation: AI agents waste tokens exploring directories, guessing relationships, and re-reading files when a codebase has no structured context. Paradigm provides that structure so agents can find what they need in ~100 tokens instead of 2,000+.
+  - id: q4
+    question: 'You open a .purpose file and see symbols prefixed with #, $, ^, !, and ~. A new team member asks what the ~ symbol means. What do you tell them?'
+    choices:
+      A: ~ marks a component — a documented code unit
+      B: ~ marks a flow — a multi-step process
+      C: ~ marks a gate — a security checkpoint
+      D: ~ marks a signal — an event notification
+      E: ~ marks an aspect — a cross-cutting rule, constraint, or configuration anchored to specific code
+    correct: E
+    explanation: 'The five symbols are: # (Component), $ (Flow), ^ (Gate), ! (Signal), and ~ (Aspect). Aspects represent cross-cutting concerns — rules, constraints, and configuration values that are anchored to specific lines of code. They are the only symbol type that requires code anchors.'

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

@@ -0,0 +1,66 @@
+id: Q-para-201-architecture-review
+title: 'PARA 201: Architecture — Putting It All Together'
+description: 'Quiz for lesson: Putting It All Together'
+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 team invitation feature uses a token to accept invitations. The token was created by an admin. Should the accept action require the ^team-admin gate?
+    choices:
+      A: Yes — only admins should be able to modify team membership
+      B: No — the invitation token itself serves as proof of authorization, so any authenticated user with a valid token should be able to accept
+      C: Yes — ^team-admin is always required for team-related operations
+      D: No — acceptance actions should be completely public with no gates at all
+      E: It depends on whether the token has expired
+    correct: B
+    explanation: The invitation token itself is the authorization. The admin already approved the invitation by creating it. Any authenticated user who possesses the valid token (received via email) should be able to accept. Requiring ^team-admin would make the feature useless — the invitee is not yet a team member, let alone an admin. The token acts as a delegated authorization from the admin.
+  - id: q2
+    question: The walkthrough creates four components. Put them in the correct order of the $team-invitation-flow steps.
+    choices:
+      A: '#invitation-email → #invitation-token → #invitation-store → #invitation-service'
+      B: '#invitation-service → #invitation-token → #invitation-store → #invitation-email'
+      C: '#invitation-store → #invitation-service → #invitation-email → #invitation-token'
+      D: '#invitation-token → #invitation-email → #invitation-service → #invitation-store'
+      E: '#invitation-service → #invitation-email → #invitation-token → #invitation-store'
+    correct: B
+    explanation: 'The flow is: (1) #invitation-service validates and creates, (2) #invitation-token generates the secure token, (3) #invitation-store persists the invitation, (4) #invitation-email sends the email. The service orchestrates, the token is needed before storage, and the email is sent last.'
+  - id: q3
+    question: The feature building pattern ends with 'validate → implement'. Why does implementation come last?
+    choices:
+      A: Because Paradigm generates the implementation code automatically
+      B: Because implementation is the least important step
+      C: Because documenting architecture first ensures security is defined before code, AI agents can navigate immediately, and the team has a clear map
+      D: Because .purpose files must be committed before any source files
+      E: Because the validator rejects implementations that do not match definitions
+    correct: C
+    explanation: 'Front-loading documentation has three benefits: (1) security gates are defined in portal.yaml before handler code exists, preventing auth as an afterthought, (2) AI agents can navigate the feature structure immediately, and (3) the team has a validated architectural map before writing any implementation.'
+  - id: q4
+    question: 'After defining all components for the invitation feature, you run paradigm_ripple on #invitation-service. What is this checking?'
+    choices:
+      A: Whether the invitation service's code compiles
+      B: Whether the service name follows naming conventions
+      C: 'What existing code and symbols would be affected by changes to #invitation-service'
+      D: Whether the service has enough test coverage
+      E: Whether the service's dependencies are installed
+    correct: C
+    explanation: 'paradigm_ripple analyzes the dependency graph to show what would be impacted if #invitation-service changes. This reveals connections to flows, signals, gates, and other components — helping you understand the blast radius before implementation.'
+  - id: q5
+    question: 'You notice that ~audit-required applies-to ["#*Service"] and your new #invitation-service matches this pattern. What should you do?'
+    choices:
+      A: 'Rename #invitation-service to #invitation-handler to avoid the aspect'
+      B: Delete the ~audit-required aspect since it is too broad
+      C: 'Ensure the audit middleware is applied to #invitation-service and add aspects: ["~audit-required"] to its definition'
+      D: Nothing — aspects are enforced automatically by Paradigm
+      E: Create a new aspect ~invitation-audit specific to this service
+    correct: C
+    explanation: 'When a new component matches an existing aspect''s applies-to pattern, you should apply that aspect. This means ensuring the enforcement code (audit middleware) is used by the new service and documenting the relationship by adding aspects: ["~audit-required"] to the component''s .purpose definition.'

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

@@ -0,0 +1,46 @@
+id: Q-para-201-aspect-graph
+title: 'PARA 201: Architecture — The Aspect Graph'
+description: 'Quiz for lesson: The Aspect Graph'
+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: Your team's rate limiter was recently changed from 100 req/min to 500 req/min, but no one updated the aspect definition. Which tool would catch this?
+    choices:
+      A: paradigm_aspect_search — it would find the stale value in search results
+      B: paradigm_aspect_drift — it compares code hashes at anchor line ranges and detects the change
+      C: paradigm_aspect_heatmap — it shows the aspect is no longer being accessed
+      D: paradigm_aspect_graph — it reveals the broken edge to the rate limiter component
+      E: paradigm_reindex — it automatically updates the aspect value during reindexing
+    correct: B
+    explanation: paradigm_aspect_drift compares SHA-256 hashes of code at anchored line ranges against the hashes from the last scan. When the rate limiter code changed, the hash changed, flagging the anchor as drifted. The other tools don't detect code changes — reindex rebuilds the graph from YAML, which still has the old value.
+  - id: q2
+    question: Which aspect category best fits "JWT access tokens expire after 24 hours"?
+    choices:
+      A: rule — it defines a behavioral pattern that code must follow
+      B: decision — it captures an architectural choice
+      C: constraint — it is a hard limit that cannot be violated
+      D: configuration — it is a value that may differ across environments
+      E: invariant — it is a condition that must always hold true
+    correct: D
+    explanation: A JWT expiry duration is a configuration value — it could reasonably differ between environments (shorter in dev, longer in production). A constraint is a hard limitation (like "maximum 100 items per page"). A rule is a behavioral pattern. Configuration captures what specific value was set and where.
+  - id: q3
+    question: 'An aspect has edges: [{symbol: "^authenticated", relation: "enforced-by"}]. What does this tell you?'
+    choices:
+      A: The aspect enforces the ^authenticated gate
+      B: The ^authenticated gate depends on the aspect existing
+      C: The ^authenticated gate is the mechanism that ensures the aspect holds true
+      D: The aspect and the gate are in conflict
+      E: The aspect will be removed if the gate is deleted
+    correct: C
+    explanation: The enforced-by relation means the target symbol is what ensures the aspect's rule holds. Here, the ^authenticated gate is the checkpoint that enforces whatever the aspect defines. Aspects declare what must be true; gates enforce those truths. The edge makes this relationship explicit and queryable.

package/dist/university-content/quizzes/Q-para-201-aspects-and-anchors.yaml

@@ -0,0 +1,56 @@
+id: Q-para-201-aspects-and-anchors
+title: 'PARA 201: Architecture — Aspects & Code Anchors'
+description: 'Quiz for lesson: Aspects & Code Anchors'
+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: Why do aspects require anchors while other symbols do not?
+    choices:
+      A: Because aspects are more important than other symbols
+      B: Because without anchors, an aspect is an unenforced rule — a wish, not a constraint
+      C: Because YAML requires at least one nested field under aspects
+      D: Because AI agents cannot understand aspects without seeing the code
+      E: Because aspects are always defined in middleware files
+    correct: B
+    explanation: An aspect without anchors is just a statement of intent with no proof of enforcement. Anchors point to the actual code that enforces the rule, making the aspect verifiable by tools, reviewable by developers, and auditable by compliance.
+  - id: q2
+    question: The anchor `src/middleware/auth.ts:42-78` points to what?
+    choices:
+      A: Lines 42 and 78 only (two specific lines)
+      B: The 42nd through 78th characters on line 1
+      C: A range of lines from line 42 to line 78 inclusive
+      D: Column 42 through column 78 on every line in the file
+      E: The 42nd and 78th functions defined in the file
+    correct: C
+    explanation: The range format (file:start-end) points to a block of consecutive lines. src/middleware/auth.ts:42-78 covers lines 42 through 78 inclusive — typically a complete function or middleware definition.
+  - id: q3
+    question: 'You define `~cached` with `applies-to: ["#*-query"]`. You then create `#user-query` without applying the cache aspect. What should happen?'
+    choices:
+      A: Nothing — applies-to is just a suggestion
+      B: 'paradigm_aspect_check reports a coverage gap: #user-query matches the pattern but is not covered'
+      C: The build fails because the aspect is not applied
+      D: The component is automatically cached by Paradigm
+      E: '#user-query is renamed to #user-query-cached'
+    correct: B
+    explanation: 'The applies-to field is declarative — it says ''this aspect should cover all components matching this pattern.'' When paradigm_aspect_check runs, it identifies #user-query as matching #*-query but not having the caching aspect applied, reporting a coverage gap.'
+  - id: q4
+    question: After a major refactor, several source files were renamed and moved. What is the risk to aspects?
+    choices:
+      A: No risk — aspects are tied to symbol names, not file paths
+      B: Anchor references break because they point to file paths and line numbers that may no longer exist
+      C: The aspect definitions are automatically updated by git
+      D: Aspects are deleted when their files move
+      E: The refactor cannot proceed if aspects exist
+    correct: B
+    explanation: Anchors contain file paths and line numbers (e.g., src/middleware/audit.ts:15-35). When files are renamed, moved, or heavily edited, these references break. Running paradigm_aspect_check after refactoring catches this drift.

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.