@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-201-disciplines.md

@@ -0,0 +1,187 @@
+---
+id: N-para-201-disciplines
+title: Disciplines
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - disciplines-define-how
+  - 14-disciplines-web
+  - auto-detection-at-init
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## How Symbols Map Across Domains
+
+A Paradigm `discipline` defines how directory patterns and code structures map to symbol types in a specific development domain. A web frontend project organizes code differently from a backend API, which differs from a CLI tool. Disciplines capture these differences so that tooling — the navigator, the logging conventions, gate recommendations, and auto-scan — works correctly regardless of your tech stack.
+
+## Auto-Detection
+
+When you run `paradigm shift` or `paradigm init`, Paradigm automatically detects the discipline from your project structure. It examines `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, and other project markers to infer the best match. The detected discipline is written to `.paradigm/config.yaml`:
+
+```yaml
+discipline: fullstack    # auto-detected from Next.js in package.json
+```
+
+Detection heuristics include: monorepo markers (workspaces), framework deps (Next.js → fullstack, React alone → web, Express alone → api), Python ML deps (PyTorch → ml), Rust crate deps (clap → cli, axum → api, bevy → game), and more. You can always override the detected value.
+
+## The 14 Disciplines
+
+Paradigm supports 14 disciplines, each with tailored symbol mappings, purpose-required paths, and scan patterns:
+
+| Discipline | When to Use | Key Directories |
+|------------|-------------|------------------|
+| `web` | Frontend-only (React, Vue, Svelte) | `components/`, `pages/`, `hooks/`, `stores/` |
+| `backend` | General backend (fallback) | `services/`, `routes/`, `models/` |
+| `fullstack` | SSR or combined frontend+backend (Next.js, Django) | `components/`, `pages/`, `api/`, `services/` |
+| `api` | API-only (Express, FastAPI, Gin) | `routes/`, `endpoints/`, `controllers/` |
+| `cli` | CLI tools (Node bin, Click, clap) | `commands/`, `cmd/` |
+| `ml` | Machine learning (PyTorch, TF, scikit-learn) | `models/`, `experiments/`, `pipelines/` |
+| `mobile` | Mobile apps (React Native, Flutter) | `screens/`, `widgets/`, `navigation/` |
+| `game` | Game dev (Bevy, Godot, Unity) | `gameplay/`, `entities/`, `systems/` |
+| `embedded` | Embedded/IoT (embedded-hal, PlatformIO) | `drivers/`, `hal/`, `protocols/` |
+| `devops` | Infrastructure (Terraform, Ansible) | `modules/`, `pipelines/`, `scripts/` |
+| `data` | Data engineering (dbt, Airflow, Spark) | `models/`, `dags/`, `transforms/` |
+| `library` | Reusable packages (npm, PyPI, crates) | `src/`, `lib/` |
+| `monorepo` | Multi-package repos (workspaces, Nx) | `packages/`, `apps/`, `libs/` |
+| `custom` | User-defined mappings | Whatever you configure |
+
+## Web Discipline
+
+In a web project, the primary units are routes, components, and pages:
+
+| Directory | Symbol | Rationale |
+|-----------|--------|-----------|
+| `routes/`, `pages/`, `views/` | `#` component | User-facing entry points |
+| `components/` | `#` component | Reusable UI elements |
+| `hooks/` | `#` component | Shared logic (hooks are code units, not signals) |
+| `stores/`, `state/` | `#` component (tag: `[state]`) | Client-side state |
+| `middleware/` | `^` gate | Route guards and auth checks |
+| `api/` | `#` component | API client wrappers |
+
+An important distinction: **hooks are components, not signals**. A frontend hook like `useAuth` encapsulates logic — it is `#useAuth`, a component. The `!` signal prefix is reserved for events that trigger decoupled side effects.
+
+## Backend / API Discipline
+
+In a backend or API project, the primary units are services, controllers, and models:
+
+| Directory | Symbol | Rationale |
+|-----------|--------|-----------|
+| `services/` | `#` component | Business logic |
+| `controllers/`, `handlers/` | `#` component | Request handlers |
+| `models/`, `entities/` | `#` component (tag: `[state]`) | Data models |
+| `middleware/`, `guards/` | `^` gate | Auth and validation |
+| `events/`, `listeners/` | `!` signal | Event emitters and handlers |
+| `jobs/`, `workers/` | `#` component | Background processing |
+| `integrations/`, `clients/` | `#` component (tag: `[integration]`) | External service wrappers |
+
+The `api` discipline is like `backend` but focused on HTTP endpoints (adds `endpoints/`, `controllers/`, `webhooks/`).
+
+## Fullstack Discipline
+
+The fullstack discipline combines both mappings. Paradigm determines which mapping to use based on the directory path:
+
+```
+src/
+  client/     → Web discipline mappings apply
+  server/     → Backend discipline mappings apply
+  shared/     → Common mappings (# for all code units)
+```
+
+Auto-detected for SSR frameworks like Next.js, Nuxt, SvelteKit, or when both React and Express are present.
+
+## Domain-Specific Disciplines
+
+**ML**: Scans `models/`, `experiments/`, `notebooks/`. Pipelines map to `$` flows. Training events map to `!` signals.
+
+**Data**: Scans `dbt/`, `dags/`, `transforms/`. ETL pipelines are `$` flows. Data quality checks are `!` signals.
+
+**Game**: Scans `gameplay/`, `entities/`, `systems/`. Game loops are `$` flows. Game events are `!` signals.
+
+**Embedded**: Scans `drivers/`, `hal/`, `protocols/`. State machines are `$` flows. Interrupts are `!` signals.
+
+## Why Disciplines Matter
+
+Disciplines affect four things:
+
+1. **Symbol mappings** — Each discipline populates the `logging.symbol-mapping` section in config.yaml with directory-to-symbol mappings appropriate for your domain.
+2. **Navigator generation** — `paradigm scan` uses the discipline to categorize directories and suggest symbol types for undocumented code.
+3. **Gate recommendations** — `paradigm_gates_for_route` uses the discipline to understand which routes exist and what patterns apply.
+4. **Auto-scan patterns** — `paradigm scan --auto` adds discipline-specific file patterns (e.g., ML scans `.ipynb` notebooks, game scans `.gd` scripts).
+
+With auto-detection, most projects get the right discipline without any manual configuration.
+
+## Custom Mappings
+
+If your project does not fit a standard discipline, you can override mappings in `config.yaml`:
+
+```yaml
+discipline: backend
+custom-mappings:
+  "workers/": "#"       # Override default if needed
+  "policies/": "^"      # Treat policies as gates
+  "sagas/": "$"         # Treat sagas as flows
+```
+
+Custom mappings extend (not replace) the discipline defaults. Or set `discipline: custom` and define everything yourself.
+
+## Stack Presets
+
+Disciplines tell Paradigm *what kind* of project you have (web, backend, mobile). Stack presets go one level deeper — they tell Paradigm *which framework* you are using. A stack preset layers framework-specific configuration on top of the discipline.
+
+Paradigm ships 16 stack presets:
+
+| Preset | Discipline | What It Adds |
+|--------|------------|-------------|
+| `nextjs` | fullstack | `app/` routes, server actions, RSC patterns |
+| `remix` | fullstack | loader/action patterns, nested routes |
+| `sveltekit` | fullstack | `+page.svelte`, `+server.ts` patterns |
+| `nuxt` | fullstack | `composables/`, auto-imports |
+| `react-spa` | web | CRA/Vite SPA patterns, `hooks/`, `contexts/` |
+| `vue-spa` | web | Composition API, Pinia stores |
+| `express` | api | `app.get/post`, middleware chains |
+| `fastapi` | api | `@app.get`, Pydantic models, dependency injection |
+| `django` | fullstack | `views.py`, `models.py`, `urls.py` |
+| `flask` | api | `@app.route`, blueprints |
+| `gin-go` | api | `r.GET`, handler groups |
+| `axum-rs` | api | Axum extractors, tower middleware |
+| `swift-ios` | mobile | SwiftUI views, `@Observable`, navigation |
+| `kotlin-android` | mobile | Jetpack Compose, ViewModels, Hilt |
+| `react-native` | mobile | Expo/bare RN, navigation, native modules |
+| `flutter` | mobile | Widgets, BLoC/Riverpod, platform channels |
+
+Stack presets are auto-detected during `paradigm init` from your dependencies and project files. You can also specify one explicitly:
+
+```bash
+paradigm init --stack nextjs
+```
+
+The detected stack is written to config.yaml:
+
+```yaml
+discipline: fullstack
+stack: nextjs
+```
+
+Stack presets add three things on top of the discipline:
+1. **Refined symbol mappings** — Framework-specific directories (e.g., `app/api/` for Next.js route handlers)
+2. **Purpose-required paths** — Directories that should have `.purpose` files for the framework to work well with Paradigm
+3. **Scan hints** — Framework-specific patterns for component detection, route patterns, auth patterns, and state management
+
+To see all available presets:
+
+```bash
+paradigm presets
+paradigm presets --discipline mobile   # Filter by discipline
+```
+
+Stack presets solve the cold-start problem: when you run `paradigm init` on an existing Next.js project, the preset knows to look for `app/` routes, server components, and API handlers — producing meaningful `.purpose` scaffolding instead of generic stubs.

package/dist/university-content/notes/N-para-201-flows-deep-dive.md

@@ -0,0 +1,119 @@
+---
+id: N-para-201-flows-deep-dive
+title: Flows in Depth
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - create-flows-when
+  - steps-are-component
+  - define-flows-in
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## When to Create a Flow
+
+Not every process needs a `$flow`. The rule of thumb is: **create a flow when logic spans three or more components in a specific order**. A two-component interaction (service A calls service B) is simple enough to document in the component's `.purpose` entry. But once a third component enters the picture — and the order matters — a flow captures the choreography that no single component can describe.
+
+Consider these scenarios:
+- User clicks "Buy" → cart validates → payment charges → order creates → email sends. That is four components in sequence. This needs a `$checkout-flow`.
+- A cron job triggers → data fetches → report generates → file uploads → Slack notifies. Five components. This needs a `$daily-report-flow`.
+- A controller calls a service which returns data. Two components, no sequence ambiguity. This does NOT need a flow.
+
+## Flow Step Structure
+
+Each step in a flow is a `component + action` pair. The component references a `#component` defined in a `.purpose` file, and the action describes what that component does in this step:
+
+```yaml
+flows:
+  $onboarding:
+    description: New user setup from registration to first project
+    steps:
+      - component: "#auth-handler"
+        action: create-account
+        description: Validates email, hashes password, creates user record
+      - component: "#email-service"
+        action: send-welcome
+        description: Sends welcome email with verification link
+      - component: "#project-service"
+        action: create-default-project
+        description: Creates a starter project for the new user
+      - component: "#notification-service"
+        action: notify-team
+        description: Alerts the team Slack channel about the new signup
+    signals: ["!user-created", "!welcome-email-sent"]
+    gates: []
+```
+
+The `description` on each step is optional but valuable — it tells AI agents what happens at each point without reading the source code.
+
+## Documenting Flows in .purpose Files
+
+Flows are defined in the `flows` section of a `.purpose` file, usually in the directory of the *initiating* component. If the checkout flow starts in the cart module, define `$checkout-flow` in `src/cart/.purpose`. The flow references components from other directories — that is expected and correct.
+
+You can also reference flows from component definitions:
+
+```yaml
+components:
+  #cart-service:
+    description: Shopping cart management
+    flows: ["$checkout-flow", "$cart-abandonment-flow"]
+```
+
+This bidirectional referencing lets `paradigm_ripple` calculate the full impact when you modify a component — it knows which flows pass through it.
+
+## Flow Validation
+
+Paradigm provides `paradigm_flow_check` to check that your flow definitions are consistent:
+
+```
+paradigm_flow_check({ flowId: "$checkout-flow", checkImplementation: true })
+```
+
+With `checkImplementation: true`, the validator goes beyond schema checks — it verifies that the referenced components exist in `.purpose` files, that the actions are implemented in the codebase, and that any signals listed are actually emitted. This catches drift between documentation and code.
+
+You can also validate all flows at once by omitting the `flowId` parameter. This is useful as a pre-commit check or CI step.
+
+## Circular Dependency Detection
+
+When flows reference each other via `relatedFlows` or step-level `$flow` symbols, they form a dependency graph. Paradigm automatically detects circular dependencies in this graph using depth-first search.
+
+A circular dependency looks like this:
+
+```yaml
+$checkout-flow:
+  relatedFlows: [$payment-flow]
+$payment-flow:
+  relatedFlows: [$checkout-flow]  # Creates a cycle!
+```
+
+When you run `paradigm_flow_check({})` (validate all flows), the output includes a `circularDependencies` section:
+
+```
+⚠ Circular Dependencies (1)
+
+  $checkout-flow → $payment-flow → $checkout-flow
+
+  Resolution: Break the cycle by extracting shared logic into a
+  separate flow, or remove one direction of the dependency.
+```
+
+To resolve circular dependencies:
+1. **Extract shared logic** into a new flow that both original flows reference
+2. **Remove one direction** if only one flow truly depends on the other
+3. **Replace with signals** — use `!signal` communication instead of direct flow references
+
+Circular dependencies are not just a documentation problem — they indicate architectural coupling that can lead to cascading failures and maintenance difficulty.
+
+## Flows Are Documentation, Not Orchestration
+
+A critical distinction: flows describe *what happens*, not *how to make it happen*. They are not workflow engines or saga orchestrators. Your code still calls services, handles errors, and manages state however it needs to. The flow definition is metadata that helps humans and AI agents understand the sequence — it does not replace your implementation.

package/dist/university-content/notes/N-para-201-gates-deep-dive.md

@@ -0,0 +1,165 @@
+---
+id: N-para-201-gates-deep-dive
+title: Gates in Depth
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - gate-types-include
+  - check-expressions-are
+  - gates-chain-via
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Gate Types
+
+Gates are general-purpose condition checkers. While authorization is a common use case, gates can check any defined condition — feature flags, environment requirements, data prerequisites, system health, and more. Here are the common gate types:
+
+**Auth gates** verify identity — is the user who they claim to be?
+```yaml
+^authenticated:
+  description: User must have a valid session
+  check: req.session.userId != null
+  type: auth
+```
+
+**Role gates** verify permission level — does the user hold the right role?
+```yaml
+^project-admin:
+  description: User must be an admin of the project
+  check: project.admins.includes(req.user.id)
+  type: role
+  requires: [^authenticated]
+```
+
+**Ownership gates** verify resource ownership — does the user own this specific item?
+```yaml
+^comment-author:
+  description: User must be the author of this comment
+  check: comment.authorId === req.user.id
+  type: ownership
+  requires: [^authenticated]
+```
+
+**State-precondition gates** verify system state — is the system in the right condition?
+```yaml
+^payment-method-exists:
+  description: User must have a payment method on file
+  check: user.paymentMethods.length > 0
+  type: state-precondition
+  requires: [^authenticated]
+```
+
+**Environment gates** verify deployment context — is the system running in the right environment?
+```yaml
+^production-only:
+  description: Action is restricted to production environment
+  check: process.env.NODE_ENV === 'production'
+  type: environment
+```
+
+**Capability gates** verify that a feature or capability is available:
+```yaml
+^feature-enabled:
+  description: The feature flag must be active for this user
+  check: features.isEnabled('new-checkout', req.user)
+  type: capability
+```
+
+**Data-readiness gates** verify that required data exists before proceeding:
+```yaml
+^profile-complete:
+  description: User must have completed their profile before accessing this feature
+  check: user.profile.isComplete === true
+  type: data-readiness
+```
+
+The `type` field is metadata for humans and tools — Paradigm does not enforce different behavior based on type. But categorizing gates helps AI agents suggest appropriate checks. Auth, role, and ownership are common in web applications, while state-precondition, environment, capability, and data-readiness gates are equally important across all disciplines.
+
+## Check Expressions
+
+The `check` field contains a **pseudo-code expression** that describes the gate's condition logic. It is not executable code — it is precise documentation:
+
+```yaml
+# Good: clear and implementable
+check: project.members.some(m => m.userId === req.user.id && m.role === 'admin')
+
+# Bad: too vague
+check: user is admin
+
+# Bad: too implementation-specific
+check: await db.query('SELECT * FROM project_members WHERE...')
+```
+
+The check should be specific enough that a developer can implement it from reading the expression, but abstract enough that it does not depend on a particular ORM or database.
+
+## Gate Chains
+
+Gates chain through the `requires` field. When a route specifies `[^authenticated, ^project-admin]`, the gates are checked in order:
+
+1. `^authenticated` runs first. If it fails, the request is rejected (in HTTP, this is a 401 Unauthorized; other disciplines handle failure differently).
+2. `^project-admin` runs next (which itself requires `^authenticated`, already passed). If it fails, the request is denied (in HTTP, a 403 Forbidden).
+
+Chains prevent redundant checks. You never need to re-check authentication inside a role gate — the `requires` field guarantees it already passed.
+
+Deep chains are possible but should be kept shallow for clarity:
+```yaml
+^super-admin:
+  requires: [^authenticated, ^org-admin]  # ^org-admin itself requires ^authenticated
+```
+
+## The Effects Field
+
+Gates can trigger side effects when they pass, defined in the `effects` field:
+
+```yaml
+^first-purchase:
+  description: User is making their first purchase
+  check: user.purchaseCount === 0
+  type: state-precondition
+  requires: [^authenticated]
+  effects:
+    - id: first-purchase-badge
+      oneTime: true
+    - id: welcome-discount
+      oneTime: true
+```
+
+The `oneTime: true` flag ensures the effect triggers only once per user. Effects are useful for gamification, onboarding rewards, and analytics events. If a gate has no side effects, use `effects: []`.
+
+## Implementing Gates
+
+While `portal.yaml` defines *what* gates exist and *where* they apply, your application code must *implement* them. In web applications, the typical pattern is middleware (other disciplines use different enforcement mechanisms):
+
+```typescript
+// Express middleware implementing ^authenticated
+function authenticated(req, res, next) {
+  if (!req.session?.userId) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+  next();
+}
+
+// Express middleware implementing ^project-admin
+function projectAdmin(req, res, next) {
+  const project = await Project.findById(req.params.id);
+  if (!project.admins.includes(req.user.id)) {
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+  next();
+}
+
+// Route applying the gate chain from portal.yaml
+router.put('/api/projects/:id', authenticated, projectAdmin, updateProject);
+```
+
+The key discipline: the `portal.yaml` definition and the implementation must match. If `portal.yaml` says an operation requires `^project-admin`, the code must actually enforce that check.

package/dist/university-content/notes/N-para-201-portal-protocol.md

@@ -0,0 +1,133 @@
+---
+id: N-para-201-portal-protocol
+title: The Portal Protocol
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - specification-before-implementation
+  - four-steps-ask
+  - paradigmgatesforroute-suggests-gates
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Specification Before Implementation
+
+The Portal Protocol is Paradigm's prescribed workflow for adding guarded operations. Its core principle is **specification before implementation** — you define what conditions must be met before you write the handler code. This inverts the common (and dangerous) pattern of building functionality first and bolting on checks later.
+
+The idea is universal: define what gates an operation needs before you implement the operation itself. In a web API, this means defining route gates before writing handlers. In a mobile app, it might mean specifying which screens require which conditions before building the UI. In a CLI tool, it means declaring what preconditions a command requires before writing the command logic.
+
+## The Four Steps
+
+### Step 1: Ask Paradigm
+
+Before writing any handler, call `paradigm_gates_for_route` with the route and method:
+
+```
+paradigm_gates_for_route({ route: "/api/projects/:id/members", method: "POST" })
+```
+
+This tool analyzes your existing `portal.yaml` and suggests gates based on patterns:
+- The route is under `/api/` → probably needs `^authenticated`
+- It modifies a project resource → probably needs `^project-admin` or `^project-member`
+- It is a POST (mutation) → higher gate requirements than a GET
+
+The suggestions are not binding, but they catch common oversights. You might realize you need a gate you had not considered.
+
+### Step 2: Add to portal.yaml
+
+Add the route with its required gates:
+
+```yaml
+routes:
+  # Existing routes...
+  "POST /api/projects/:id/members": [^authenticated, ^project-admin]
+```
+
+If you need a new gate that does not exist yet, define it in the `gates` section:
+
+```yaml
+gates:
+  ^project-admin:
+    description: User must be an admin of the project
+    check: project.admins.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+```
+
+### Step 3: Implement the Gate Checks
+
+Write the middleware or handler code that enforces each gate. The implementation must match the `check` expression in portal.yaml. How a failed gate manifests depends on your discipline:
+
+- **Web APIs** return HTTP status codes (401 for failed identity checks, 403 for failed authorization)
+- **Mobile apps** might disable UI elements or show an upgrade prompt
+- **CLI tools** might exit with a specific error code and message
+- **Desktop apps** might gray out menu items or show a dialog
+
+Here is an example for a web API:
+
+```typescript
+async function projectAdmin(req, res, next) {
+  const project = await Project.findById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: 'Project not found' });
+  }
+  if (!project.admins.includes(req.user.id)) {
+    log.gate('^project-admin').warn('Access denied', {
+      userId: req.user.id,
+      projectId: req.params.id
+    });
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+  req.project = project;  // Attach for downstream use
+  next();
+}
+```
+
+Notice the Paradigm logger usage: `log.gate('^project-admin').warn(...)` for a denied gate.
+
+### Step 4: Test Gate Failures
+
+Verify that failing a gate produces the correct behavior. In a web API, this means testing rejection status codes:
+
+```typescript
+it('rejects non-admin attempting to add member', async () => {
+  const res = await request(app)
+    .post('/api/projects/proj_123/members')
+    .set('Authorization', `Bearer ${memberToken}`)  // member, not admin
+    .send({ email: 'newuser@example.com' });
+
+  expect(res.status).toBe(403);
+});
+```
+
+Test both the pass path (authorized user succeeds) and the fail path (unauthorized user is rejected). The concept of pass/fail is universal across all disciplines — only the specific failure response varies.
+
+## Common Gate Patterns
+
+Over time, projects develop recurring gate patterns:
+
+| Pattern | Gate Name | Check |
+|---------|-----------|-------|
+| Any logged-in user | `^authenticated` | `req.user != null` |
+| Resource membership | `^{resource}-member` | `resource.members.includes(req.user.id)` |
+| Resource admin | `^{resource}-admin` | `resource.admins.includes(req.user.id)` |
+| Resource creator | `^{resource}-creator` | `resource.createdBy === req.user.id` |
+| Item author | `^{item}-author` | `item.authorId === req.user.id` |
+| Feature flag | `^feature-{name}` | `features.isEnabled(name, req.user)` |
+
+These patterns are reusable across projects. When you call `paradigm_gates_for_route`, the tool draws from these patterns to make suggestions.
+
+## The Cost of Skipping the Protocol
+
+The Portal Protocol makes conditions a first thought rather than an afterthought. By defining gates in portal.yaml before writing handlers, you create an auditable specification that is separate from (and checkable against) the implementation. Whether you are protecting API endpoints, gating CLI commands, or controlling feature access in a mobile app, the principle is the same: specify first, implement second.