@a-company/paradigm 5.37.11 → 6.0.2

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

@@ -0,0 +1,66 @@
+id: Q-para-101-project-structure
+title: 'PARA 101: Foundations — Project Structure'
+description: 'Quiz for lesson: Project Structure'
+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: Where does portal.yaml live in a Paradigm project?
+    choices:
+      A: Inside .paradigm/specs/
+      B: Inside .paradigm/ at the top level
+      C: At the project root, alongside .paradigm/
+      D: Inside each source directory that has protected routes
+      E: It does not exist as a file — it is generated at runtime
+    correct: C
+    explanation: portal.yaml lives at the project root, not inside .paradigm/. This is intentional — as a security-critical file defining gates and protected routes, it should be visible and easy to audit.
+  - id: q2
+    question: What is navigator.yaml and how is it created?
+    choices:
+      A: A manually written guide to project conventions
+      B: A machine-generated codebase map created by 'paradigm scan'
+      C: A configuration file for IDE navigation shortcuts
+      D: A list of all npm dependencies and their versions
+      E: An auto-generated test coverage report
+    correct: B
+    explanation: navigator.yaml is generated by running 'paradigm scan'. It maps symbols to file paths and directories to categories, giving AI agents a fast way to locate code without traversing the file system.
+  - id: q3
+    question: An AI agent wants to check if there are known antipatterns before modifying the payment module. Where should it look?
+    choices:
+      A: src/payments/.purpose
+      B: .paradigm/wisdom/ (via paradigm_wisdom_context)
+      C: .paradigm/specs/payments.md
+      D: portal.yaml
+      E: package.json
+    correct: B
+    explanation: Team knowledge — including antipatterns, decisions, and preferences — lives in .paradigm/wisdom/. AI agents access it by calling paradigm_wisdom_context with the symbols they plan to modify.
+  - id: q4
+    question: What does the 'discipline' field in config.yaml control?
+    choices:
+      A: Which programming language the project uses
+      B: How directory patterns map to symbol types (web vs backend vs fullstack)
+      C: The maximum number of components allowed per directory
+      D: Whether the project uses TypeScript or JavaScript
+      E: The deployment target (cloud, on-premise, serverless)
+    correct: B
+    explanation: The discipline field tells Paradigm how to interpret directory patterns. A 'web' discipline maps routes/ to components, while a 'backend' discipline maps services/ to components. This affects the navigator, logger suggestions, and gate recommendations.
+  - id: q5
+    question: Which of these files should be written by hand, NOT generated by a tool?
+    choices:
+      A: navigator.yaml
+      B: config.yaml
+      C: history/ entries
+      D: All of the above are generated
+      E: None of the above — all are written by hand
+    correct: B
+    explanation: config.yaml is a project configuration file written by the team (or initialized by 'paradigm shift' and then customized). navigator.yaml is generated by 'paradigm scan', and history entries are recorded by tools and post-commit hooks.

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

@@ -0,0 +1,56 @@
+id: Q-para-101-purpose-files
+title: 'PARA 101: Foundations — Purpose Files'
+description: 'Quiz for lesson: Purpose Files'
+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: Where should a .purpose file be placed?
+    choices:
+      A: In the .paradigm/ directory at the project root
+      B: In the source directory it describes, alongside the code files
+      C: In a dedicated /docs directory
+      D: In the project root, one file for the entire project
+      E: In the node_modules directory for package documentation
+    correct: B
+    explanation: Purpose files live in the source directory they describe — right next to the code. The .paradigm/ directory holds project-wide configuration, not directory-level documentation.
+  - id: q2
+    question: What is the `context` field in a .purpose file used for?
+    choices:
+      A: Defining application context providers
+      B: Specifying environment variables required by the module
+      C: Free-text notes aimed at AI agents — conventions, gotchas, assumptions
+      D: Listing the test files associated with the directory
+      E: Declaring the programming language used in the directory
+    correct: C
+    explanation: The context field is an array of free-text strings written specifically for AI agents. It conveys things like 'all amounts are in cents', 'this module is deprecated', or 'uses Stripe signatures for webhook verification'.
+  - id: q3
+    question: How many .purpose files should a single directory contain?
+    choices:
+      A: Exactly one for every file in the directory
+      B: At most one per directory
+      C: One per component defined in the directory
+      D: At least three — one for components, one for flows, one for gates
+      E: None — purpose files are generated automatically
+    correct: B
+    explanation: Each directory should have at most one .purpose file. All symbols in that directory (components, flows, gates, signals, aspects) are defined within that single file.
+  - id: q4
+    question: Which field is REQUIRED on every symbol defined in a .purpose file?
+    choices:
+      A: file
+      B: tags
+      C: description
+      D: version
+      E: anchors
+    correct: C
+    explanation: Every symbol must have a description. Without it, AI agents cannot understand what the symbol represents. The file, tags, and version fields are useful but optional. Anchors are required only for aspects (~).

package/dist/university-content/quizzes/Q-para-101-tags-and-classification.yaml

@@ -0,0 +1,56 @@
+id: Q-para-101-tags-and-classification
+title: 'PARA 101: Foundations — Tags & Classification'
+description: 'Quiz for lesson: Tags & Classification'
+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: How should a Stripe API wrapper be documented in Paradigm?
+    choices:
+      A: $stripe-service as a flow with Stripe steps
+      B: '#stripe-service with tags: [integration, stripe]'
+      C: ^stripe-service as a gate that checks Stripe credentials
+      D: '!stripe-service as a signal emitted on payment'
+      E: ~stripe-service as an aspect that applies Stripe logic across components
+    correct: B
+    explanation: 'A Stripe API wrapper is a documented code unit, so it is a # component. The integration role is captured by tags: #stripe-service with tags: [integration, stripe]. Tags provide searchable classification without requiring different symbol types.'
+  - id: q2
+    question: Where are project-specific tags defined?
+    choices:
+      A: In each .purpose file's tags section
+      B: In portal.yaml alongside gate definitions
+      C: In .paradigm/tags.yaml under the 'project' section
+      D: In package.json under the 'paradigm' key
+      E: They are not defined anywhere — any string can be a tag
+    correct: C
+    explanation: 'Tags are defined in .paradigm/tags.yaml. The file has three sections: core (universal), project (team-specific), and suggested (AI-proposed). Project-specific tags go in the ''project'' section.'
+  - id: q3
+    question: An AI agent notices that seven components in the codebase handle webhook processing. What should it do?
+    choices:
+      A: Create a new ~webhook aspect with anchors
+      B: Rename all seven components to start with 'webhook-'
+      C: Use paradigm_tags_suggest to propose a 'webhook-handler' tag for human review
+      D: Add a $webhook-flow connecting all seven components
+      E: Ignore the pattern — tags should only be created by humans
+    correct: C
+    explanation: AI agents can propose new tags using paradigm_tags_suggest. The proposed tag goes into the 'suggested' section of tags.yaml, where a human reviews it and decides whether to promote it to the 'project' section.
+  - id: q4
+    question: How many tags should a typical symbol have?
+    choices:
+      A: Exactly one
+      B: Two to four
+      C: At least five for maximum discoverability
+      D: None — tags are optional and rarely used
+      E: As many as possible to cover all search terms
+    correct: B
+    explanation: The guideline is 2-4 tags per symbol. One tag is often too vague to be useful, while five or more creates noise and dilutes searchability. Tags should be chosen for discoverability — the terms you would search for to find the component.

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.