@a-company/paradigm 5.37.11 → 6.0.2

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.

package/dist/university-content/notes/N-para-101-project-structure.md

@@ -0,0 +1,143 @@
+---
+id: N-para-101-project-structure
+title: Project Structure
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - paradigm-holds-project-wide
+  - configyaml-defines-discipline
+  - navigatoryaml-is-generated
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The .paradigm/ Directory
+
+Every Paradigm project has a `.paradigm/` directory at its root. This is the central nervous system of the framework — it holds project-wide configuration, specifications, documentation, and metadata that apply across the entire codebase. While `.purpose` files describe individual directories, the `.paradigm/` directory describes the project as a whole.
+
+## Core Files
+
+### config.yaml — Project Configuration
+
+The most important file. It defines the project's discipline (web, backend, fullstack, etc.), naming conventions, and agent preferences:
+
+```yaml
+name: my-project
+discipline: fullstack
+version: "2.0"
+
+conventions:
+  naming: kebab-case
+  components: PascalCase
+  files: kebab-case
+
+agent-provider: claude-code
+```
+
+The `discipline` field tells Paradigm how to map directory patterns to symbol types. A `web` discipline treats `routes/` as components; a `backend` discipline treats `services/` as components. This affects the navigator, logger suggestions, and gate recommendations.
+
+### tags.yaml — Tag Bank
+
+Defines all valid tags in three sections: `core` (universal), `project` (team-specific), and `suggested` (AI-proposed). Covered in detail in the Tags lesson.
+
+### agents.yaml — Agent Roles
+
+Configures the AI agents that work on your project — their roles, model assignments, context includes/excludes, and token budgets:
+
+```yaml
+agents:
+  architect:
+    defaultModel: opus
+    context:
+      include: [".paradigm/**", "portal.yaml", "**/.purpose"]
+  builder:
+    defaultModel: haiku
+    context:
+      include: ["src/**", "**/.purpose"]
+      exclude: ["**/*.test.*"]
+  security:
+    defaultModel: opus
+    context:
+      include: ["portal.yaml", "**/auth/**", "**/middleware/**"]
+```
+
+### navigator.yaml — Generated Codebase Map
+
+A machine-generated file that maps symbols to file paths, directories to categories, and provides a structural overview of the codebase. AI agents read this to quickly locate code without directory traversal. Generated by `paradigm scan`.
+
+## Subdirectories
+
+### specs/ — Detailed Specifications
+
+Long-form documents that describe system behaviors, protocols, and standards. These are too detailed for `.purpose` files but essential for AI agents implementing features:
+
+```
+.paradigm/specs/
+  logger.md          ← Full logger specification
+  disciplines.md     ← Symbol mapping by domain
+  portal-protocol.md ← Authorization workflow
+```
+
+### docs/ — Commands and Patterns
+
+Quick-reference documentation for CLI commands, coding patterns, and troubleshooting:
+
+```
+.paradigm/docs/
+  commands.md                ← CLI command reference
+  patterns.md                ← Coding patterns and conventions
+  ai-maintenance-protocol.md ← When/how to update Paradigm files
+```
+
+### wisdom/ — Team Knowledge
+
+Captures the team's learned preferences, architectural decisions, and antipatterns:
+
+```
+.paradigm/wisdom/
+  preferences.yaml    ← Coding style preferences
+  decisions.yaml      ← Architectural Decision Records (ADRs)
+  antipatterns.yaml   ← What NOT to do, and why
+```
+
+AI agents check wisdom before implementing changes by calling `paradigm_wisdom_context`.
+
+### history/ — Implementation Timeline
+
+Tracks what was implemented, when, and by whom. Used for fragility analysis and rollback tracking.
+
+## The Big Picture
+
+Here is the complete project layout showing both `.paradigm/` and `.purpose` files:
+
+```
+my-project/
+  .paradigm/
+    config.yaml       ← Project-wide settings
+    tags.yaml         ← Tag definitions
+    agents.yaml       ← Agent configurations
+    navigator.yaml    ← Generated codebase map
+    specs/            ← Detailed specifications
+    docs/             ← Commands and patterns
+    wisdom/           ← Team knowledge
+    history/          ← Implementation timeline
+  portal.yaml         ← Security gates and routes (project root)
+  src/
+    payments/
+      .purpose        ← Directory-level documentation
+      payment-service.ts
+    auth/
+      .purpose
+      middleware.ts
+```
+
+Notice that `portal.yaml` lives at the project root, not inside `.paradigm/`. This is intentional — it is a security-critical file that should be visible and easy to audit.

package/dist/university-content/notes/N-para-101-purpose-files.md

@@ -0,0 +1,121 @@
+---
+id: N-para-101-purpose-files
+title: Purpose Files
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - purpose-files-are
+  - they-declare-components
+  - ai-agents-read
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## The Map AI Agents Read First
+
+A `.purpose` file is a YAML document that lives in a directory alongside your source code. It declares what that directory contains — its components, flows, gates, signals, and aspects. When an AI agent enters a directory, the first thing it should do is read the `.purpose` file. This single file gives the agent enough context to understand the directory without scanning every source file.
+
+Think of `.purpose` files as the table of contents for a chapter in a book. You would not read every page to find out what topics are covered — you check the table of contents. Similarly, AI agents should not `grep` through every `.ts` or `.py` file to figure out what a directory does.
+
+## Structure of a Purpose File
+
+A `.purpose` file has a top-level metadata section and then named sections for each symbol type:
+
+```yaml
+name: Payment Module
+description: Handles all payment processing and billing logic
+version: "1.0.0"
+context:
+  - Uses Stripe as the payment provider
+  - All amounts are in cents (integer)
+  - Webhooks are verified with Stripe signatures
+
+components:
+  #payment-service:
+    description: Core payment processing logic
+    file: payment-service.ts
+    tags: [integration, stripe, critical]
+    signals: ["!payment-completed", "!payment-failed"]
+    gates: ["^authenticated"]
+
+  #billing-calculator:
+    description: Computes totals, taxes, and discounts
+    file: billing.ts
+    tags: [feature]
+
+flows:
+  $checkout-flow:
+    description: End-to-end purchase sequence
+    steps:
+      - component: "#cart-service"
+        action: validate-items
+      - component: "#billing-calculator"
+        action: compute-total
+      - component: "#payment-service"
+        action: charge
+
+signals:
+  !payment-completed:
+    description: Emitted after successful charge
+    emitters: ["#payment-service"]
+    category: business
+
+gates:
+  ^payment-authorized:
+    description: User has a valid payment method on file
+    check: user.paymentMethods.length > 0
+```
+
+## Key Rules for Purpose Files
+
+**One per directory.** Each directory that contains meaningful code should have at most one `.purpose` file. Not every directory needs one — only directories that contain components worth documenting.
+
+**Symbols must use the correct prefix.** Components use `#`, flows use `$`, gates use `^`, signals use `!`, aspects use `~`. The prefix is part of the identifier.
+
+**Descriptions are required.** Every component, flow, gate, signal, and aspect must have a `description` field. Without it, the symbol is opaque to AI agents.
+
+**References link symbols together.** A component can reference the gates it requires (`gates: ["^authenticated"]`), the signals it emits (`signals: ["!payment-completed"]`), and the flows it participates in (`flows: ["$checkout-flow"]`). These cross-references let tools like `paradigm_ripple` calculate impact.
+
+**The `context` field is for AI.** The top-level `context` array contains free-text notes aimed at AI agents: conventions, gotchas, assumptions. This is where you write "all amounts are in cents" or "this module is deprecated, use v2 instead."
+
+## Where Purpose Files Live
+
+Purpose files are placed in source directories — wherever your code lives:
+
+```
+src/
+  payments/
+    .purpose          ← describes the payments module
+    payment-service.ts
+    billing.ts
+  auth/
+    .purpose          ← describes the auth module
+    login.ts
+    middleware.ts
+```
+
+They are NOT placed in the `.paradigm/` directory. The `.paradigm/` directory holds project-wide configuration; `.purpose` files hold directory-level documentation.
+
+## Creating Purpose Files with MCP Tools
+
+You can create and update purpose files using the Paradigm MCP tools:
+
+```
+paradigm_purpose_init     → Create/update file-level metadata
+paradigm_purpose_add_component → Add a #component
+paradigm_purpose_add_flow     → Add a $flow
+paradigm_purpose_add_gate     → Add a ^gate
+paradigm_purpose_add_signal   → Add a !signal
+paradigm_purpose_add_aspect   → Add a ~aspect (with required anchors)
+```
+
+These tools handle YAML formatting and symbol quoting automatically. For example, YAML treats `!` as a tag indicator, so signal IDs need special quoting — the tools handle this for you.

package/dist/university-content/notes/N-para-101-tags-and-classification.md

@@ -0,0 +1,93 @@
+---
+id: N-para-101-tags-and-classification
+title: Tags & Classification
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - tags-classify-components
+  - tags-are-defined
+  - three-sections-core
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## Beyond Symbols: The Tag Bank
+
+Paradigm's five symbols classify code by *role* — component, flow, gate, signal, aspect. But within each role, you often need finer distinctions. Is this component a user-facing feature or a third-party integration? Is it critical infrastructure or an experimental idea? Paradigm handles this with a unified **tag system**.
+
+Tags are plain strings in brackets that you attach to any symbol. They live in the `tags` array on a symbol definition:
+
+```yaml
+components:
+  #checkout:
+    description: Shopping cart checkout experience
+    tags: [feature, critical, payments]
+
+  #stripe-service:
+    description: Stripe API client wrapper
+    tags: [integration, stripe, payments]
+
+  #cart-store:
+    description: In-memory shopping cart state
+    tags: [state, ephemeral]
+```
+
+## The Tag Bank File
+
+Tags are not arbitrary strings — they are defined in `.paradigm/tags.yaml`, which serves as the project's tag bank. The tag bank has three sections:
+
+```yaml
+core:          # Universal tags, defined by Paradigm itself
+  feature:     { description: "User-facing functionality" }
+  integration: { description: "Third-party service connection" }
+  state:       { description: "Data store or state container" }
+  critical:    { description: "Failure causes major user impact" }
+  deprecated:  { description: "Scheduled for removal" }
+  idea:        { description: "Experimental, not yet approved" }
+
+project:       # Team-defined tags specific to this project
+  payments:    { description: "Related to payment processing" }
+  onboarding:  { description: "Part of the new-user experience" }
+
+suggested:     # AI-proposed tags awaiting human approval
+  webhook-handler: { description: "Processes incoming webhooks" }
+```
+
+The **core** section contains tags that apply to any project. The **project** section contains tags your team has defined for this specific codebase. The **suggested** section is where AI agents can propose new tags using the `paradigm_tags_suggest` tool — a human reviews and promotes them to the project section.
+
+## How Tags Work in Practice
+
+Here is how tags differentiate components that serve different roles:
+
+| Role | How to Tag |
+|-----------|---------------|
+| User-facing feature | `#checkout` with `tags: [feature]` |
+| Third-party service | `#stripe-service` with `tags: [integration, stripe]` |
+| Data store | `#cart-store` with `tags: [state]` |
+| Experimental prototype | `#new-widget` with `tags: [idea]` |
+| Scheduled for removal | `#legacy-handler` with `tags: [deprecated]` |
+
+This means fewer concepts to remember and no ambiguity. A Stripe payment service is `#stripe-service` with `tags: [integration, stripe]` — clear, searchable, and consistent.
+
+## Using Tags Effectively
+
+Tags are most powerful when they are **consistent and searchable**. Follow these guidelines:
+
+- **Use existing tags before inventing new ones.** Check `paradigm_tags({ action: "list" })` to see what is available.
+- **Keep tags lowercase and kebab-case.** `webhook-handler`, not `WebhookHandler` or `WEBHOOK_HANDLER`.
+- **Use 2-4 tags per symbol.** One tag is too vague; ten tags is noise.
+- **Tag for discoverability.** Ask: "What would I search for to find this component?" Those search terms are your tags.
+- **Let AI propose tags.** If you notice a pattern (e.g., five components all handle webhooks), use `paradigm_tags_suggest` to propose a `webhook-handler` tag.
+
+## Querying by Tags
+
+The Paradigm MCP tools support tag-based discovery. When you call `paradigm_search` with a tag name, it returns all symbols bearing that tag. This makes it easy to ask questions like "show me everything tagged `critical`" or "find all `integration` components."

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

@@ -0,0 +1,51 @@
+---
+id: N-para-101-welcome
+title: Welcome to Paradigm
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-101
+  - meta-framework-for-ai-assisted
+  - structured-context-over
+  - five-operational-symbols
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-101.json
+---
+
+## What Is Paradigm?
+
+Paradigm is a **meta-framework for structured AI-assisted development**. It is not a code framework like React or Express — it does not ship components, generate boilerplate, or impose a runtime. Instead, Paradigm organizes *how AI agents understand your code*. It provides a shared vocabulary of symbols, a directory-level documentation format, and a set of specifications that let any AI assistant — whether Claude, Cursor, or another tool — navigate even large codebases with precision and minimal token waste.
+
+The core insight behind Paradigm is simple: AI agents are powerful, but they struggle when dropped into an undocumented codebase. They spend thousands of tokens exploring directories, guessing at relationships, and re-reading files they have already seen. Paradigm solves this by giving the codebase *structured context* — lightweight metadata files that describe what lives where, how pieces relate, and what rules apply.
+
+## The Three Pillars
+
+Paradigm rests on three pillars:
+
+1. **Symbols** — A set of five prefixed identifiers (`#`, `$`, `^`, `!`, `~`) that classify every meaningful unit in your project. A payment service is `#PaymentService`. An authorization check is `^authenticated`. A business event is `!order-placed`. Symbols are the vocabulary AI agents use to talk about your code.
+
+2. **Purpose Files** — YAML files named `.purpose` that live in directories alongside your source code. They declare which components, flows, gates, signals, and aspects exist in that directory. They are the map AI agents read before they touch any code.
+
+3. **Specifications** — Files in the `.paradigm/` directory that define project-wide configuration, tag taxonomies, agent roles, navigation maps, and team wisdom. They are the rulebook that keeps every agent aligned with your team's conventions.
+
+## Why It Matters
+
+Without structured context, an AI agent working on a checkout feature might:
+- Spend 2,000+ tokens reading irrelevant files looking for the payment service
+- Miss an authorization gate that protects the endpoint
+- Accidentally duplicate a signal that another component already emits
+- Use `console.log` instead of the team's structured logger
+
+With Paradigm, that same agent calls `paradigm_navigate` to find `#PaymentService` in ~100 tokens, checks `paradigm_ripple` to see what depends on it, reads the `.purpose` file to understand the directory, and follows the team's logging convention. The result is faster, safer, and more consistent code changes.
+
+## What You Will Learn
+
+In this course you will learn the five symbols and when to use each one, how to write and read `.purpose` files, how to classify symbols with tags, how to use the Paradigm logger, how the `.paradigm/` directory is organized, how `portal.yaml` secures your routes, and how to set up a new project from scratch.