@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/quizzes/Q-para-001-build-something.yaml

@@ -0,0 +1,46 @@
+id: Q-para-001-build-something
+title: 'PARA 001: Quick Start — Build With the Team'
+description: 'Quiz for lesson: Build With the Team'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-001
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+questions:
+  - id: q1
+    question: You built a new API endpoint without running quick-check or orchestration. The code works fine. On minimal enforcement, what happens when you commit?
+    choices:
+      A: The commit is blocked — orchestration is always required
+      B: The commit succeeds but the stop hook warns that no orchestration record exists for the changed files
+      C: Nothing — minimal enforcement has no checks
+      D: The commit is reverted automatically
+      E: Git rejects the commit because the pre-commit hook fails
+    correct: B
+    explanation: On minimal enforcement, orchestration-required is set to off, so the stop hook does not block. However, the purpose-coverage check (which is set to warn on minimal) may warn if you did not create a .purpose file for the new endpoint. The commit succeeds either way — minimal enforcement never blocks. But you have no orchestration record, no Rune compliance report, and no structured review.
+  - id: q2
+    question: 'During the build step, Rune creates a symbol plan with #health-check as a component. After the builder writes the code, Rune''s compliance report says "1 component, 0 aspects — blocking." Why is this a problem?'
+    choices:
+      A: Aspects are required for documentation completeness but have no real purpose
+      B: Every component needs at least one aspect (rule, constraint, or configuration) — the 1:1 ratio means you must define what rules govern the health endpoint
+      C: Rune made an error — health endpoints do not need aspects
+      D: The builder should have created the aspect automatically
+      E: This only matters on strict enforcement
+    correct: B
+    explanation: 'Rune enforces a 1:1 component-to-aspect ratio. Even a health endpoint has rules: response format, which checks it runs, timeout behavior, whether it includes dependency status. Defining an aspect like ~health-check-format forces you to document what the endpoint actually guarantees. This is not busywork — it is how Paradigm ensures every component has a documented contract.'
+  - id: q3
+    question: 'The commit message for your feature reads: feat(#health-check): add GET /health endpoint. The Symbols: trailer says Symbols: #health-check. What does the post-commit hook do with this information?'
+    choices:
+      A: Nothing — the Symbols trailer is just for human readability
+      B: 'It parses the Symbols trailer and records the commit in Paradigm''s history system, linking the change to #health-check for traceability'
+      C: 'It validates that #health-check exists in a .purpose file'
+      D: It sends a notification to the agent team
+      E: It automatically creates a changelog entry
+    correct: B
+    explanation: 'The post-commit hook parses the Symbols: trailer and records the commit in Paradigm''s history system. This creates a traceable link: commit → symbols affected. Later, when someone asks "what changed about #health-check?" or runs paradigm_history_context, the answer includes this commit. The pre-commit hook handles index rebuilding; the post-commit hook handles history capture.'

package/dist/university-content/quizzes/Q-para-001-meet-the-team.yaml

@@ -0,0 +1,46 @@
+id: Q-para-001-meet-the-team
+title: 'PARA 001: Quick Start — Meet Your Agent Team'
+description: 'Quiz for lesson: Meet Your Agent Team'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-001
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+questions:
+  - id: q1
+    question: Your project is a React frontend with no backend. Which of these agents would paradigm shift likely NOT include in your roster?
+    choices:
+      A: Builder — every project needs code implementation
+      B: A database specialist — there is no database in a frontend-only project
+      C: Reviewer — code review is universal
+      D: compliance — symbol coverage applies to all projects
+      E: security — even frontend apps have security concerns (XSS, CSRF)
+    correct: B
+    explanation: Specialized agents like a database specialist are only rostered when the project type matches. A React frontend with no backend has no database layer, so database agents would not be selected. The core team (including the security role — frontend security matters too) appears in every roster. Specialized and ecosystem agents are added based on detection.
+  - id: q2
+    question: 'The Architect uses opus (tier-1) while the Builder uses haiku (tier-3). A junior developer asks: "Does that mean the builder writes worse code?" How do you explain?'
+    choices:
+      A: Yes — tier-3 is lower quality, but it is faster and cheaper
+      B: No — tiers match complexity, not quality. Architecture requires open-ended reasoning (opus). Building is well-defined implementation work where speed matters more (haiku).
+      C: The tiers are just labels with no real difference
+      D: The builder should be upgraded to opus for important features
+      E: All agents should use the same model for consistency
+    correct: B
+    explanation: Model tier assignment is about matching the nature of the work, not ranking quality. Architectural design is open-ended — "how should we structure this?" benefits from deeper reasoning. Implementation is well-defined — "write this function that does X" benefits from speed. A fast model writing clearly specified code often produces better results than an overthinking model.
+  - id: q3
+    question: You want to add a DevOps specialist agent to your web project's roster. What command would you use?
+    choices:
+      A: Edit roster.yaml by hand and add the agent definition
+      B: paradigm agent activate devops — it adds the agent to your project roster
+      C: paradigm shift --add-agent devops
+      D: Re-run paradigm shift and hope it detects the need
+      E: DevOps agents cannot be added to web projects
+    correct: B
+    explanation: paradigm agent activate <id> adds an agent to your project roster. This is the proper way to customize your team — the CLI updates roster.yaml, agents.yaml, and any related configuration atomically. While you could edit roster.yaml by hand, using the CLI ensures all related files stay in sync.

package/dist/university-content/quizzes/Q-para-001-shift-setup.yaml

@@ -0,0 +1,46 @@
+id: Q-para-001-shift-setup
+title: 'PARA 001: Quick Start — Your First paradigm shift'
+description: 'Quiz for lesson: Your First paradigm shift'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-001
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+questions:
+  - id: q1
+    question: You just ran paradigm shift in a Node.js project. Which of the following was NOT created or configured automatically?
+    choices:
+      A: .paradigm/config.yaml with discipline auto-detected from package.json
+      B: CLAUDE.md with AI instructions derived from your configuration
+      C: A comprehensive test suite for your existing code
+      D: Git hooks for automated compliance checking
+      E: .paradigm/roster.yaml with agents suited for a Node.js project
+    correct: C
+    explanation: paradigm shift sets up Paradigm metadata and tooling — it does not generate tests, modify your source code, or create application logic. It creates configuration, instruction files, hooks, and an agent roster. Testing is handled by the tester agent during orchestration, not during initialization.
+  - id: q2
+    question: After running paradigm shift, you edit .paradigm/config.yaml to change your enforcement level. Now CLAUDE.md is out of date. How do you update it?
+    choices:
+      A: Edit CLAUDE.md manually to match your changes
+      B: Run paradigm shift again — it regenerates CLAUDE.md from your updated config
+      C: Delete CLAUDE.md and it will regenerate on the next commit
+      D: Run paradigm sync to rebuild only the instruction files
+      E: Both B and D would work — shift re-runs all steps including sync, while sync targets just the instruction files
+    correct: E
+    explanation: CLAUDE.md is a derived file — always generated from config, never hand-edited. Both paradigm shift (full re-run) and paradigm sync (targeted) will regenerate it. Use sync when you only changed config; use shift when you want the full pipeline (migrate, scan, hooks, etc.).
+  - id: q3
+    question: A teammate says "I ran paradigm shift but it broke my project — hooks are blocking my commits." This should not happen with default settings. What likely went wrong?
+    choices:
+      A: paradigm shift always uses strict enforcement
+      B: The project already had a config.yaml with enforcement level set to strict or balanced from a previous setup
+      C: Hooks always block on the first run to teach discipline
+      D: The teammate's Git version is incompatible with Paradigm hooks
+      E: paradigm shift requires admin privileges to install hooks
+    correct: B
+    explanation: New projects default to minimal enforcement, which warns but never blocks. But paradigm shift is idempotent — if the project already had a .paradigm/config.yaml with a higher enforcement level, shift preserves that setting. The teammate's project was likely previously configured with balanced or strict enforcement. Check config.yaml and adjust enforcement.level if needed.

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

@@ -0,0 +1,46 @@
+id: Q-para-101-component-types
+title: 'PARA 101: Foundations — Component Types & Hierarchy'
+description: 'Quiz for lesson: Component Types & Hierarchy'
+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 does the `type` field on a component describe?
+    choices:
+      A: The programming language the component is written in
+      B: The structural role of the component (e.g., service, view, router)
+      C: The business domain the component belongs to
+      D: The test coverage level of the component
+      E: The deployment environment for the component
+    correct: B
+    explanation: The `type` field describes a component's structural role — what the code IS architecturally (service, view, router, filter, etc.). Business domain classification uses tags instead.
+  - id: q2
+    question: Where should the `parent` relationship be declared?
+    choices:
+      A: On the parent component, listing all children
+      B: In a separate relationships.yaml file
+      C: 'On the child component, referencing the parent with a # symbol'
+      D: In portal.yaml alongside gate definitions
+      E: In the config.yaml component_types glossary
+    correct: C
+    explanation: 'Parent is declared on the child component using a `parent: "#parent-name"` field. This keeps .purpose files decentralized — you don''t need to maintain rosters on parent components.'
+  - id: q3
+    question: A `PaymentService` handles payment processing and integrates with Stripe. How should it be documented?
+    choices:
+      A: '`type: integration` with no tags'
+      B: '`type: service` with `tags: [integration, feature]`'
+      C: '`tags: [service, integration]` with no type'
+      D: '`type: feature` with `tags: [service]`'
+      E: '`type: service-integration` combining both concepts'
+    correct: B
+    explanation: 'Type describes what the code IS (a service), while tags describe behavior and domain (it''s an integration and a feature). The correct approach is `type: service` with `tags: [integration, feature]`.'

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.