@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-101-component-types.md

@@ -0,0 +1,99 @@
+---
+id: N-para-101-component-types
+title: Component Types & Hierarchy
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - component-type-describes
+  - types-are-open
+  - parent-field-establishes
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## Why Component Types?
+
+Components (`#`) are the most common symbol in any Paradigm project. A large project might have hundreds of components — services, views, utilities, routers, filters, models, and more. Without further classification, an AI agent triaging 'where is access control handled?' has to read every component to understand what kind of thing it is.
+
+Component types solve this by adding an optional `type` field that describes a component's **structural role** — what the code IS, not what domain it belongs to.
+
+## The `type` Field
+
+Add `type` to any component in a `.purpose` file:
+
+```yaml
+components:
+  PaymentService:
+    description: Coordinates payment processing
+    type: service
+  PaymentForm:
+    description: Credit card input form
+    type: view
+  format-currency:
+    description: Formats numbers as currency strings
+    type: utility
+```
+
+Types are **open strings** — each project defines its own vocabulary in the `component_types` glossary in `.paradigm/config.yaml`. There is no fixed enum. Common types include: `view`, `service`, `model`, `tool`, `utility`, `engine`, `loader`, `provider`, `manager`, `router`, `filter`, `handler`, `config`.
+
+## The `parent` Field
+
+Components can declare a parent to establish hierarchy:
+
+```yaml
+components:
+  InputOrchestrator:
+    description: Coordinates all input sources
+    type: manager
+  GazeRouter:
+    description: Maps gaze coordinates to dispatch targets
+    type: router
+    parent: "#InputOrchestrator"
+  KalmanFilter2D:
+    description: Smooths noisy gaze signal
+    type: filter
+    parent: "#GazeRouter"
+```
+
+Parent is declared on the **child**, not maintained as a roster on the parent. This keeps `.purpose` files decentralized.
+
+## Type vs Tag
+
+This is a common source of confusion:
+
+- **`type`** = structural role (what the code IS). One per component. Examples: `service`, `view`, `router`
+- **`tags`** = behavioral or domain classification. Many per component. Examples: `[feature]`, `[security]`, `[integration]`
+
+A component can be `type: service` with `tags: [feature, security]`. Type tells you the architecture; tags tell you the domain.
+
+## Config Glossary
+
+Projects define their vocabulary in `.paradigm/config.yaml`:
+
+```yaml
+component_types:
+  service: "Business logic coordinator — orchestrates tools, loaders, writers"
+  view: "UI rendering unit — SwiftUI view, React component"
+  utility: "Shared helper function or module — no side effects, pure logic"
+  router: "Maps input signals to targets based on rules"
+```
+
+The glossary is **descriptive only** — it helps agents understand types but does not enforce them.
+
+## MCP Integration
+
+Component types integrate with MCP tools:
+
+- `paradigm_search` with `componentType: "service"` finds all services
+- `paradigm_status` shows a component type breakdown
+- `paradigm_purpose_add_component` accepts `type` and `parent` parameters
+- `paradigm_reindex` aggregates type counts into `$meta.componentTypes`

package/dist/university-content/notes/N-para-101-first-steps.md

@@ -0,0 +1,134 @@
+---
+id: N-para-101-first-steps
+title: Your First Steps
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - paradigm-shift-creates
+  - start-with-one
+  - create-portalyaml-if
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## Getting Started with Paradigm
+
+Before diving into theory, let's get your hands dirty. This lesson walks through the concrete steps to set up Paradigm in a real project. You will encounter terms like *symbols*, *purpose files*, and *gates* — each gets its own deep-dive lesson later in this course. For now, focus on the workflow: initialize, document, scan, go.
+
+## Step 1: Initialize the Project
+
+Run `paradigm shift` in your project root. This creates the `.paradigm/` directory with a starter `config.yaml`:
+
+```bash
+paradigm shift
+```
+
+`paradigm shift` runs non-interactively by default — it auto-detects your discipline from project markers (`package.json`, `Cargo.toml`, `go.mod`, etc.), selects an appropriate agent roster, configures model tiers, installs hooks, and generates AI instruction files (CLAUDE.md, AGENTS.md). One command, full setup.
+
+You can customize later with flags like `--verify` (health check) or `--workspace <name>` (multi-project workspace).
+
+After init, you will have:
+```
+.paradigm/
+  config.yaml    # Includes detected discipline and stack
+  tags.yaml
+  agents.yaml
+```
+
+## Step 2: Create Your First Purpose File
+
+Pick a source directory that contains meaningful code — perhaps your main feature module or your API routes. Create a `.purpose` file:
+
+```yaml
+name: User Authentication
+description: Handles user login, registration, and session management
+context:
+  - Uses bcrypt for password hashing
+  - Sessions stored in Redis with 24h TTL
+  - Rate limited to 5 login attempts per minute
+
+components:
+  #auth-handler:
+    description: POST /auth/login and POST /auth/register endpoints
+    file: auth.ts
+    tags: [feature, auth]
+    signals: ["!login-success", "!login-failed"]
+    gates: ["^authenticated"]
+
+  #session-manager:
+    description: Creates and validates user sessions in Redis
+    file: session.ts
+    tags: [state, auth]
+```
+
+Start small. You do not need to document every file on day one. Begin with the most important module and expand over time.
+
+## Step 3: Set Up portal.yaml (If Needed)
+
+If your application has any protected endpoints, create `portal.yaml` at the project root:
+
+```yaml
+version: "1.0"
+
+gates:
+  ^authenticated:
+    description: User must have a valid session
+    check: req.session.userId != null
+    type: auth
+    effects: []
+
+routes:
+  "POST /auth/login": []
+  "POST /auth/register": []
+  "GET /api/profile": [^authenticated]
+  "PUT /api/profile": [^authenticated]
+```
+
+Note that public routes like login and register have empty gate arrays `[]` — they are listed to document that they are intentionally unprotected.
+
+## Step 4: Run Your First Scan
+
+Generate the navigator map so AI agents can find symbols quickly:
+
+```bash
+paradigm scan
+```
+
+This reads all `.purpose` files and `portal.yaml`, builds a symbol index, and writes `navigator.yaml`.
+
+## Step 5: The Orientation Protocol
+
+When starting a new AI session (or when an AI agent first encounters your project), the agent should follow this protocol:
+
+1. **Call `paradigm_status`** — Gets a project overview: symbol counts, health, available features.
+2. **Read `config.yaml`** — Understands the discipline, conventions, and preferences.
+3. **Check `portal.yaml`** — Knows about security gates if they exist.
+4. **Use `paradigm_navigate`** — Finds the relevant code area for the current task.
+
+This four-step orientation takes ~500 tokens total and gives the agent everything it needs to work effectively.
+
+## Step 6: Iterate
+
+Paradigm grows with your project. As you add features:
+- Create `.purpose` files for new directories
+- Add gates to `portal.yaml` for new protected routes
+- Record team decisions in `.paradigm/wisdom/decisions.yaml`
+- Log antipatterns in `.paradigm/wisdom/antipatterns.yaml`
+- Run `paradigm scan` periodically to rebuild the navigator
+
+## Common Pitfalls
+
+- **Do not document everything on day one.** Start with the most critical module and expand.
+- **Do not skip portal.yaml.** If you have any gates or preconditions, you need it.
+- **Do not forget to re-scan.** After adding new `.purpose` files, run `paradigm scan` to update the navigator.
+- **Do not put .purpose files in .paradigm/.** They live alongside source code.
+- **Do not use raw console.log.** Use the Paradigm logger from the start to build good habits.

package/dist/university-content/notes/N-para-101-five-symbols.md

@@ -0,0 +1,128 @@
+---
+id: N-para-101-five-symbols
+title: The Five Symbols
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - '-component-'
+  - '-flow-'
+  - '-gate-'
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The Heart of Paradigm
+
+Everything in Paradigm revolves around five symbols. Each symbol is a single-character prefix that classifies a code unit by its *role* in the system. When you see `#PaymentService`, you immediately know it is a component. When you see `^authenticated`, you know it is a security gate. The symbols are not decorative — they are a shared vocabulary that lets humans, AI agents, and tooling speak the same language about your codebase.
+
+## `#` Component — The Universal Building Block
+
+The `#` symbol marks **any documented code unit**. Services, handlers, React components, utility modules, database models, configuration loaders — if it is a meaningful piece of code that you want AI to know about, it is a `#component`.
+
+```yaml
+# In a .purpose file
+components:
+  #PaymentService:
+    description: Handles payment processing via Stripe
+    file: payment-service.ts
+    tags: [integration, stripe, critical]
+
+  #login-handler:
+    description: POST /auth/login endpoint handler
+    file: login.ts
+    gates: [^authenticated]
+```
+
+Component is intentionally broad. You never have to debate whether something is a "feature" or a "service" — it is a component. Finer distinctions are handled by the tag system: `#checkout` with `tags: [feature]`, `#stripe-service` with `tags: [integration, stripe]`.
+
+## `$` Flow — Multi-Step Processes
+
+The `$` symbol marks **ordered sequences of steps that span multiple components**. Use a flow when logic touches three or more components in a specific order.
+
+```yaml
+flows:
+  $checkout-flow:
+    description: Complete purchase from cart to confirmation
+    steps:
+      - component: "#cart-service"
+        action: validate-cart
+      - component: "#payment-service"
+        action: charge-card
+      - component: "#order-service"
+        action: create-order
+      - component: "#notification-service"
+        action: send-confirmation
+    signals: ["!order-placed", "!payment-completed"]
+```
+
+Flows are documentation, not orchestration code. They tell AI agents *the sequence of operations* so the agent can understand what happens end-to-end without reading every file.
+
+## `^` Gate — Condition Checkpoints
+
+The `^` symbol marks **conditions that must be satisfied before an action can proceed**. Gates are the gatekeepers of Paradigm — they check a defined state and either allow or block.
+
+```yaml
+gates:
+  ^authenticated:
+    description: User must be logged in
+    check: req.user != null
+  ^project-admin:
+    description: User must be an admin of the project
+    check: project.admins.includes(req.user.id)
+    requires: [^authenticated]
+```
+
+Gates can chain — `^project-admin` requires `^authenticated` first. They map to routes in `portal.yaml`, which we will cover later.
+
+## `!` Signal — Events for Side Effects
+
+The `!` symbol marks **events that trigger decoupled side effects**. When a payment completes, the payment service does not directly call the notification service — it emits `!payment-completed`, and any listener can react.
+
+```yaml
+signals:
+  !payment-completed:
+    description: Fired after successful payment processing
+    emitters: ["#payment-service"]
+    category: business
+  !login-failed:
+    description: Fired on failed authentication attempt
+    emitters: ["#auth-handler"]
+    category: security
+```
+
+Signals promote loose coupling. The emitter does not need to know who listens.
+
+## `~` Aspect — Cross-Cutting Rules
+
+The `~` symbol marks **rules that apply across multiple components and MUST point to enforcement code**. This is the only symbol that *requires* code anchors.
+
+```yaml
+aspects:
+  ~audit-required:
+    description: All financial operations must be logged to audit trail
+    anchors:
+      - src/middleware/audit.ts:15-35
+      - src/decorators/auditable.ts:1-20
+    applies-to: ["#*Service"]
+    tags: [compliance, security]
+```
+
+The `anchors` field is mandatory. An aspect without anchors is invalid — it would be a rule with no enforcement. The anchor format is `file:line`, `file:start-end`, or `file:line1,line2,line3`.
+
+## Choosing the Right Symbol
+
+Ask yourself:
+- Is it a piece of code I want documented? → `#` Component
+- Does it describe a multi-step sequence? → `$` Flow
+- Does it guard access to a resource? → `^` Gate
+- Does it represent an event with side effects? → `!` Signal
+- Does it enforce a rule across many components? → `~` Aspect

package/dist/university-content/notes/N-para-101-paradigm-logger.md

@@ -0,0 +1,89 @@
+---
+id: N-para-101-paradigm-logger
+title: The Paradigm Logger
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - structured-logging-ties
+  - log-entries-should
+  - four-log-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## Structured Logging with Symbols
+
+Raw `console.log` calls are the bane of production debugging. They have no structure, no categorization, and no connection to the system architecture. Paradigm replaces them with a **structured logger** that ties every log line to a symbol. When you see a log entry from `#payment-service`, you know exactly which component produced it. When you see a warning from `^authenticated`, you know a gate check failed.
+
+The Paradigm logger uses a two-step chaining API: first you specify the symbol type and name, then you call a log level method.
+
+## The Logger API
+
+There are five logger methods, one for each symbol type:
+
+```typescript
+// Components — any code unit
+log.component('#payment-service').info('Payment processed', { amount: 4999 });
+log.component('#user-store').debug('Cache hit', { userId: 'u_123' });
+
+// Gates — authorization checks
+log.gate('^authenticated').warn('Access denied — no session', { path: '/api/admin' });
+log.gate('^project-admin').info('Gate passed', { userId: 'u_456' });
+
+// Signals — events
+log.signal('!payment-completed').info('Payment signal emitted', { orderId: 'ord_789' });
+log.signal('!login-failed').warn('Failed login attempt', { email: 'user@example.com' });
+
+// Flows — multi-step processes
+log.flow('$checkout-flow').debug('Step 2/4: billing calculated', { total: 5999 });
+log.flow('$onboarding').info('Flow completed', { userId: 'u_123' });
+
+// Aspects — cross-cutting concerns
+log.aspect('~audit-required').debug('Audit entry recorded', { operation: 'delete-user' });
+log.aspect('~rate-limited').warn('Rate limit approaching', { remaining: 5 });
+```
+
+## Log Levels
+
+Each symbol method returns an object with four log level methods:
+
+| Level | Use When |
+|-------|----------|
+| `debug` | Development-only details, verbose tracing |
+| `info` | Normal operations — a process completed, a step succeeded |
+| `warn` | Something unexpected but recoverable — a gate denial, a rate limit approaching |
+| `error` | Something failed — a payment declined, a database connection lost |
+
+Choose the level based on operational severity, not on how important the code is. A critical payment service logging a successful charge uses `.info()`, not `.error()`.
+
+## Symbol-to-Directory Mapping
+
+Paradigm defines a convention for which logger method to use based on which directory the code lives in:
+
+| Directory Pattern | Logger Method |
+|-------------------|---------------|
+| `features/`, `routes/`, `api/`, `services/`, `lib/`, `components/` | `log.component()` |
+| `middleware/`, `auth/`, `guards/`, `policies/` | `log.gate()` |
+| `events/`, `handlers/`, `listeners/`, `hooks/` | `log.signal()` |
+| `flows/`, `sagas/`, `workflows/`, `pipelines/` | `log.flow()` |
+| `aspects/`, `rules/` | `log.aspect()` |
+
+This is a convention, not enforcement. If a service in `lib/` emits a signal, it can call `log.signal()`. But when in doubt, follow the directory mapping.
+
+## Why Not console.log?
+
+Structured logging with symbols gives you:
+
+1. **Filterability** — In production, you can filter logs by symbol type (`gate`), symbol name (`^authenticated`), or log level (`warn`). Raw console.log gives you none of this.
+2. **Traceability** — Every log line connects back to the Paradigm symbol map. You can trace a log entry to its `.purpose` definition, see what flows involve it, and check what gates protect it.
+3. **Consistency** — AI agents generating code will use the correct logger if the convention exists. Without it, each agent invents its own logging pattern.
+4. **Incident correlation** — Paradigm Sentinel (the incident tracking system) matches log patterns to symbols, enabling automatic triage based on which components are failing.

package/dist/university-content/notes/N-para-101-portal-yaml.md

@@ -0,0 +1,112 @@
+---
+id: N-para-101-portal-yaml
+title: Portal.yaml
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - portalyaml-defines-gates
+  - lives-at-project
+  - gates-check-any
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The Gate Registry
+
+`portal.yaml` is Paradigm's gate specification. It defines the gates (`^`) for your project — conditions that must be checked before actions proceed. Gates can check anything: authentication, feature flags, data prerequisites, system health, rate limits, or any other condition your project needs to verify.
+
+This file lives at the **project root** — not inside `.paradigm/`. It is intentionally prominent because gate definitions should be easy to find, easy to audit, and impossible to overlook.
+
+## Structure
+
+A `portal.yaml` has two main sections: `gates` and `routes`.
+
+```yaml
+version: "1.0"
+
+gates:
+  ^authenticated:
+    description: User must be logged in
+    check: req.user != null
+    type: auth
+    effects: []
+
+  ^project-member:
+    description: User must be a member of the project
+    check: project.members.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+
+  ^project-admin:
+    description: User must be an admin of the project
+    check: project.admins.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+
+  ^comment-author:
+    description: User must be the author of the comment
+    check: comment.authorId === req.user.id
+    type: ownership
+    requires: [^authenticated]
+    effects: []
+
+routes:
+  "GET /api/projects": [^authenticated]
+  "GET /api/projects/:id": [^authenticated, ^project-member]
+  "PUT /api/projects/:id": [^authenticated, ^project-admin]
+  "DELETE /api/projects/:id": [^authenticated, ^project-admin]
+  "POST /api/projects/:id/comments": [^authenticated, ^project-member]
+  "DELETE /api/comments/:id": [^authenticated, ^comment-author]
+```
+
+## Gate Anatomy
+
+Each gate definition includes:
+
+- **description** — What the gate checks, in plain English.
+- **check** — A pseudo-code expression describing the authorization logic. This is documentation, not executable code — but it should be precise enough that a developer or AI agent can implement it.
+- **type** — The category of check: `auth`, `role`, `ownership`, `feature-flag`, `data-readiness`, `environment`, or any custom type that fits your domain.
+- **requires** — Other gates that must pass first. `^project-admin` requires `^authenticated`, meaning you must be logged in before the admin check runs.
+- **effects** — Side effects triggered when the gate passes. For example, passing `^first-login` might award an onboarding badge. Use `[]` if there are no effects.
+
+## Gate Chains
+
+Gates can chain via the `requires` field. The route `"PUT /api/projects/:id": [^authenticated, ^project-admin]` ensures that:
+1. First, `^authenticated` verifies the user is logged in.
+2. Then, `^project-admin` checks that the user is an admin of the specific project.
+
+If any gate in the chain fails, the action is blocked. How the failure manifests depends on your discipline: an API returns `403 Forbidden`, a mobile app might disable a button, a CLI exits with an error code.
+
+## When portal.yaml Is Required
+
+Create `portal.yaml` whenever your project has conditions that must be checked before actions proceed:
+- Authentication or session validation
+- Role or permission checks
+- Feature flags or environment checks
+- Data prerequisites (cart not empty, profile complete)
+- Rate limits or system health checks
+- Any precondition that should be documented and auditable
+
+If your project has no gates — no conditions that need to be verified before any action — then `portal.yaml` is not needed.
+
+## The Gate-First Workflow
+
+When adding functionality that requires preconditions, follow this workflow:
+
+1. **Ask Paradigm** — Call `paradigm_gates_for_route` with the route and method (for web APIs), or identify the conditions that must be checked.
+2. **Add to portal.yaml** — Define the gates and map them to the actions they protect.
+3. **Implement** — Write the code that enforces each gate check.
+4. **Test** — Verify that failing a gate blocks the action appropriately for your discipline.
+
+This workflow ensures that conditions are defined *before* implementation, not bolted on after.