@a-company/paradigm 5.38.0 → 6.0.4

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

@@ -0,0 +1,56 @@
+id: Q-para-101-first-steps
+title: 'PARA 101: Foundations — Your First Steps'
+description: 'Quiz for lesson: Your First Steps'
+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 the correct order for the AI agent orientation protocol?
+    choices:
+      A: Read source code, write tests, check coverage, deploy
+      B: Call paradigm_status, read config.yaml, check portal.yaml, use paradigm_navigate
+      C: Run paradigm scan, edit navigator.yaml, read .purpose files, commit changes
+      D: Read package.json, install dependencies, run build, check logs
+      E: Create .purpose files, define gates, emit signals, validate flows
+    correct: B
+    explanation: 'The orientation protocol is: (1) paradigm_status for project overview, (2) read config.yaml for conventions, (3) check portal.yaml for security gates, (4) paradigm_navigate to find the relevant code area. This takes ~500 tokens and gives the agent full context.'
+  - id: q2
+    question: After creating new .purpose files, what command should you run?
+    choices:
+      A: paradigm shift
+      B: paradigm validate
+      C: paradigm scan
+      D: paradigm deploy
+      E: paradigm build
+    correct: C
+    explanation: paradigm scan reads all .purpose files and portal.yaml, builds the symbol index, and regenerates navigator.yaml. Without rescanning, AI agents will not find the newly defined symbols through navigation tools.
+  - id: q3
+    question: In portal.yaml, what does an empty gate array on a route mean?
+    choices:
+      A: The route is disabled and will return 404
+      B: The route requires all gates to pass
+      C: The route is intentionally unprotected — documented as public
+      D: The route has not been configured yet and will return 500
+      E: The route inherits gates from its parent path
+    correct: C
+    explanation: An empty gate array [] means the route is intentionally public. Listing it in portal.yaml with no gates documents the decision that this route should be accessible without authentication — it is not an oversight.
+  - id: q4
+    question: Which of these is a common pitfall when starting with Paradigm?
+    choices:
+      A: Creating too many .purpose files on day one instead of starting small
+      B: Using the Paradigm logger instead of console.log
+      C: Running paradigm scan after adding new purpose files
+      D: Putting portal.yaml at the project root
+      E: Using tags to classify components
+    correct: A
+    explanation: A common pitfall is trying to document everything on day one. The recommended approach is to start with the most critical module, create one .purpose file, and expand incrementally as the project grows.

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

@@ -0,0 +1,66 @@
+id: Q-para-101-five-symbols
+title: 'PARA 101: Foundations — The Five Symbols'
+description: 'Quiz for lesson: The Five Symbols'
+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: A middleware function that checks whether the current user has admin privileges should be classified as which symbol?
+    choices:
+      A: '# Component'
+      B: $ Flow
+      C: ^ Gate
+      D: '! Signal'
+      E: ~ Aspect
+    correct: C
+    explanation: A middleware function that checks a condition and either allows or blocks access is a gate (^). Gates verify that a required condition is met before proceeding — in this case, admin privileges.
+  - id: q2
+    question: After a refactor, you run paradigm doctor and it reports "3 broken anchors detected." Which symbol type was affected?
+    choices:
+      A: '# Component — components have code anchors that broke during refactoring'
+      B: $ Flow — flow steps reference line numbers that shifted
+      C: ^ Gate — gate definitions include file paths that changed
+      D: '! Signal — signal emitters moved to different files'
+      E: ~ Aspect — aspects are the only symbol with code anchors, and the refactor moved the anchored lines
+    correct: E
+    explanation: Aspects (~) are the only symbol type that requires code anchors — specific file:line references pointing to where the rule is enforced. When code is refactored and lines move, those anchors break. paradigm doctor detects this via SHA-256 hash comparison, and paradigm_aspect_drift can show exactly which anchors drifted.
+  - id: q3
+    question: A payment processing module contains a Stripe API wrapper, a billing calculator, and an in-memory cart. How should these be classified?
+    choices:
+      A: 'Each gets a different symbol type: $ for Stripe, # for calculator, ! for cart'
+      B: 'They are all # components, differentiated by tags like [integration, stripe], [feature], and [state]'
+      C: 'They should all be a single # component since they are in the same module'
+      D: The Stripe wrapper is a ~ aspect since it is a cross-cutting concern
+      E: They should be modeled as steps in a $ flow
+    correct: B
+    explanation: 'All three are documented code units, so they are all # components. The differences are captured by tags: #stripe-service with tags: [integration, stripe], #billing-calculator with tags: [feature], #cart-store with tags: [state]. Tags add nuance without requiring different symbol types.'
+  - id: q4
+    question: When should you create a $flow?
+    choices:
+      A: For every function that takes more than 10 lines of code
+      B: Only for authentication sequences
+      C: When logic spans three or more components in a specific order
+      D: Whenever you emit a signal
+      E: For all API endpoints regardless of complexity
+    correct: C
+    explanation: Flows document multi-step processes that involve three or more components in a defined sequence. A single-component operation or a two-component call does not warrant a flow — it adds documentation overhead without providing navigational value.
+  - id: q5
+    question: Your payment module emits !payment-completed after charging a card. Later, the marketing team adds a "send receipt email" listener, and the analytics team adds a "record conversion" listener. Neither team modified the payment module. How is this possible?
+    choices:
+      A: The payment module was refactored to call both services directly
+      B: Signals promote loose coupling — the emitter fires the event without knowing who listens, so new listeners can be added independently
+      C: The listeners were added to the payment module's .purpose file
+      D: Both teams used the same $flow as the payment module
+      E: The ^payment gate routes events to registered handlers
+    correct: B
+    explanation: 'This is the core value of signals: loose coupling. The payment module emits !payment-completed and has zero knowledge of who listens. The marketing team and analytics team independently subscribe to the signal. No code in the payment module was modified. This is why Paradigm separates signals (!) from flows ($) — flows define explicit steps, while signals enable independent, decoupled reactions.'

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

@@ -0,0 +1,56 @@
+id: Q-para-101-paradigm-logger
+title: 'PARA 101: Foundations — The Paradigm Logger'
+description: 'Quiz for lesson: The Paradigm Logger'
+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 the correct way to log a successful payment in `#payment-service`?
+    choices:
+      A: 'console.log(''Payment processed'', { amount: 4999 })'
+      B: log.info('#payment-service', 'Payment processed')
+      C: 'log.component(''#payment-service'').info(''Payment processed'', { amount: 4999 })'
+      D: log.signal('!payment-completed').info('Payment processed')
+      E: log.gate('#payment-service').info('Payment processed')
+    correct: C
+    explanation: 'Paradigm''s logging philosophy is that every log entry should be tagged with the symbol it relates to. For a component like #payment-service, the log should identify it as a component-level entry at the info level.'
+  - id: q2
+    question: Code in the `middleware/` directory should typically use which logger method?
+    choices:
+      A: log.component()
+      B: log.flow()
+      C: log.signal()
+      D: log.gate()
+      E: log.aspect()
+    correct: D
+    explanation: By Paradigm's directory-to-symbol convention, middleware/ maps to gates (^). Code in middleware directories typically performs condition checks, which are gate operations — so logs from these files should be tagged as gate-related.
+  - id: q3
+    question: An authentication gate denies access to an unauthenticated user. What log level should be used?
+    choices:
+      A: debug — it is a routine check
+      B: info — the gate worked correctly
+      C: warn — access was denied, which is unexpected but not a failure
+      D: error — someone tried to access a protected resource
+      E: No logging — gate denials should be silent
+    correct: C
+    explanation: A gate denial is unexpected from the user's perspective (they tried to access something they should not) but it is recoverable and the system handled it correctly. This makes it a warn — not an error (the system did not fail) and not info (something unusual happened).
+  - id: q4
+    question: Which of these is a valid reason to use the Paradigm logger instead of console.log?
+    choices:
+      A: console.log is slower in production environments
+      B: The Paradigm logger automatically fixes bugs in the logged code
+      C: Structured symbol-tagged logs enable filtering, tracing, and incident correlation
+      D: console.log does not work in TypeScript projects
+      E: The Paradigm logger compresses log output to save disk space
+    correct: C
+    explanation: The primary advantage of the Paradigm logger is structure. Every log line is tagged with a symbol type and name, enabling you to filter by component, trace entries back to .purpose definitions, and correlate incidents with specific symbols.

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

@@ -0,0 +1,56 @@
+id: Q-para-101-portal-yaml
+title: 'PARA 101: Foundations — Portal.yaml'
+description: 'Quiz for lesson: Portal.yaml'
+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: You are adding a new action that requires preconditions — only authenticated team admins should be able to invite users. What is the correct gate workflow?
+    choices:
+      A: Write the handler code first, then add authorization if there is time
+      B: Identify the required gates, add them to portal.yaml, implement the checks, test that failing a gate blocks the action
+      C: Add a console.log that prints the user's role for manual verification
+      D: Create a new .purpose file with a ^gate definition — portal.yaml is optional
+      E: Add the route to navigator.yaml so AI agents know about it
+    correct: B
+    explanation: 'The Paradigm gate-first workflow is: (1) identify the required gates (paradigm_gates_for_route can suggest them for web routes), (2) define the gates in portal.yaml, (3) implement the gate checks in code, (4) test that failing a gate blocks the action. Conditions are defined before implementation.'
+  - id: q2
+    question: What does the `requires` field on a gate definition do?
+    choices:
+      A: Lists npm packages the gate depends on
+      B: Specifies other gates that must pass before this gate is checked
+      C: Defines the HTTP status code returned on failure
+      D: Lists the source files that implement the gate
+      E: Specifies environment variables needed for the check
+    correct: B
+    explanation: The requires field creates a gate chain. For example, ^project-admin requires [^authenticated] — the authentication check must pass before the admin role check is evaluated.
+  - id: q3
+    question: When is portal.yaml NOT needed?
+    choices:
+      A: When the project has condition checks that must pass before actions proceed
+      B: When the project has role-based access control
+      C: When the application has no gates — no conditions need to be checked before any action
+      D: When the project only has GET endpoints
+      E: When the project uses a third-party auth service
+    correct: C
+    explanation: portal.yaml is needed whenever your application has gates — conditions that must be checked before actions proceed. If no action in the system requires a precondition check (authentication, feature flags, data readiness, etc.), then portal.yaml is not needed.
+  - id: q4
+    question: What is the `effects` field on a gate definition?
+    choices:
+      A: The HTTP response body returned when the gate passes
+      B: Side effects triggered when the gate is successfully passed
+      C: The list of routes protected by this gate
+      D: The reward given to the developer who implemented the gate
+      E: A list of test cases for the gate
+    correct: B
+    explanation: 'Effects are side effects that trigger when a gate passes. For example, passing ^first-login might award an onboarding badge. If there are no side effects, use an empty array: effects: [].'

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.