@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-001-meet-the-team.md

@@ -0,0 +1,85 @@
+---
+id: N-para-001-meet-the-team
+title: Meet Your Agent Team
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-001
+  - core-team
+  - roster
+  - model-tiers-match
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+---
+
+## Your AI Team
+
+Open `.paradigm/roster.yaml`. You will see a list of agents — your project's AI team. Each agent has a specific role, and the orchestrator assigns them to tasks based on what the task needs.
+
+### The Core Agent Team
+
+Every project gets a small team of role-named core agents. They are the backbone of Paradigm's orchestration:
+
+| Role | Model Tier | What They Do |
+|------|-----------|-------------|
+| **architect** | tier-1 (opus) | Plans multi-file changes, defines structure |
+| **builder** | tier-3 (haiku) | Writes the code |
+| **reviewer** | tier-2 (sonnet) | Two-stage review: spec compliance → code quality |
+| **security** | tier-1 (opus) | Threat analysis, auth review, vulnerability scanning |
+| **tester** | tier-3 (haiku) | Writes tests, checks coverage, validates edge cases |
+| **documentor** | tier-2 (sonnet) | Maintains .purpose files and portal.yaml |
+| **ftux** (Nora) | tier-1 (opus) | First-time-user simulation, friction reports |
+
+These seven roles ship in every project's roster. Additional core-tier specialists like **advocate** (devil's-advocate review, historically nicknamed Jinx), **compliance** (symbol coverage, historically nicknamed Rune), and **debugger** (incident triage) activate based on the project profile detected by `paradigm shift`.
+
+Roles are addressed by their canonical role name (e.g. `architect`). Some roles also have nicknames (the ftux agent is named **Nora**) — nicknames are cosmetic and may evolve; the role name is the stable contract.
+
+### Model Tiers
+
+Not every agent needs the most powerful (and expensive) model. Paradigm assigns agents to tiers:
+
+- **Tier 1 (opus)** — architect, security, ftux. Complex reasoning, design decisions, threat analysis, simulation.
+- **Tier 2 (sonnet)** — reviewer, documentor, advocate, compliance. Balanced depth and speed.
+- **Tier 3 (haiku)** — builder, tester. Fast, cost-effective for implementation and testing.
+
+This is not a quality ranking — it is a complexity match. Building code is well-defined work that a fast model handles efficiently. Designing architecture requires deeper reasoning that benefits from a more capable model.
+
+### Specialized and Ecosystem Agents
+
+Beyond the core team, Paradigm ships with **50+ agents** total (the exact count evolves; see PARA 701):
+
+- **Specialized agents** (~20) cover domains like mobile, database, DevOps, accessibility, performance, and internationalization. They are added to your roster when your project type matches.
+
+- **Ecosystem agents** (~26+) are language/platform-specific: Swift, TypeScript, Rust, Python ML, iOS, Android, etc. They accumulate knowledge through notebooks that transfer across projects.
+
+You do not need to manage these manually. `paradigm shift` detected your project type and selected the right mix. You can view and customize your roster with:
+
+```bash
+paradigm agent list          # See your full roster
+paradigm agent activate <id> # Add an agent
+paradigm agent bench <id>    # Remove an agent
+```
+
+### The Maestro Model
+
+You are **Maestro** — the orchestrator. When you give a task to Paradigm, you are not talking to one AI. You are conducting a team:
+
+1. **architect** designs the approach (for complex tasks)
+2. **security** reviews security implications (when auth or data is involved)
+3. **builder** writes the code
+4. **reviewer** checks spec compliance and code quality
+5. **ftux** (Nora) simulates a first-time user when the change touches a user-visible surface
+6. **documentor** updates .purpose files and Paradigm metadata
+7. **compliance** validates that planned symbols match the implementation
+
+Not every task uses every agent. A simple CSS fix might only need builder. A new API endpoint might need architect → security → builder → reviewer → documentor. The orchestrator decides based on the task.
+
+> **Going deeper:** PARA 401 covers orchestration mechanics (facets, handoffs, trigger patterns). PARA 701 covers the full agent roster, profiles, notebooks, and learning loops.

package/dist/university-content/notes/N-para-001-shift-setup.md

@@ -0,0 +1,74 @@
+---
+id: N-para-001-shift-setup
+title: Your First paradigm shift
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-001
+  - paradigm-shift-is
+  - paradigm-directory-holds
+  - claudemd-and-agentsmd
+symbols: []
+difficulty: beginner
+estimatedMinutes: 2
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-001.json
+---
+
+## Hands On in 60 Seconds
+
+Open a terminal in any project directory and run:
+
+```bash
+paradigm shift
+```
+
+That is it. One command, and your project is Paradigm-aware.
+
+### What Just Happened?
+
+Look at your directory. Several new files and a new folder appeared:
+
+```
+.paradigm/            ← Configuration, roster, tags, indexes
+  config.yaml         ← Project settings (name, discipline, enforcement)
+  roster.yaml         ← Your agent team
+  agents.yaml         ← Model tier assignments
+  tags.yaml           ← Tag taxonomy
+CLAUDE.md             ← Instructions for Claude Code
+AGENTS.md             ← Instructions for any AI agent
+.purpose              ← Root-level purpose file (describes your project)
+```
+
+Each file has a specific job:
+
+- **`.paradigm/config.yaml`** is the brain — it stores your project name, discipline (web, backend, mobile, etc.), enforcement level, and feature flags. Paradigm auto-detected your discipline from project markers like `package.json`, `Cargo.toml`, or `go.mod`.
+
+- **`CLAUDE.md`** and **`AGENTS.md`** are instruction files that AI tools read automatically. They are generated from your Paradigm configuration — you do not edit them by hand. When you change config, re-running `paradigm shift` regenerates them.
+
+- **`.purpose`** is the most important file type in Paradigm. It describes what code in a directory does using a structured format with **symbols** — you will learn all five symbol types in PARA 101. For now, just know that `.purpose` files are how AI agents understand your codebase.
+
+- **`roster.yaml`** lists which agents are on your team. More on this in the next lesson.
+
+### Hooks Are Installed
+
+`paradigm shift` also installed Git hooks and Claude Code hooks. These run automatically when you commit or finish a task, checking that your Paradigm metadata stays in sync with your code.
+
+By default, hooks use **minimal enforcement** — they warn but never block. You will not lose work or get stuck. As you get comfortable, you can upgrade to balanced or strict enforcement (covered in PARA 301).
+
+### Try It: Explore What Was Created
+
+Run these commands to see what Paradigm set up:
+
+```bash
+cat .paradigm/config.yaml      # Your project configuration
+cat .paradigm/roster.yaml       # Your agent team
+cat .purpose                    # Root purpose file
+```
+
+Notice how `config.yaml` already knows your project type, and `roster.yaml` has agents selected for that type. This is the auto-detection at work — no manual configuration needed.

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.