@a-company/paradigm 5.38.0 → 6.0.4

package/dist/university-content/notes/N-para-401-orchestration-workflow.md

@@ -0,0 +1,101 @@
+---
+id: N-para-401-orchestration-workflow
+title: Orchestration Workflow
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - five-step-workflow-describe
+  - paradigmorchestrateinline-plan-then
+  - parallel-stage-launching
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Orchestration Workflow
+
+This lesson walks through the complete end-to-end orchestration workflow, from task description to final result. Understanding this workflow is essential for effectively coordinating multi-agent tasks in Paradigm.
+
+### Step 1: Describe the Task
+
+Start with a clear, specific task description. Good task descriptions include what you want to build, which areas are involved, and any constraints:
+
+- Good: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate"
+- Bad: "Fix payments"
+
+The quality of the task description directly affects the quality of the orchestration plan.
+
+### Step 2: Plan with paradigm_orchestrate_inline
+
+Call `paradigm_orchestrate_inline` with `mode="plan"` to get the orchestrator's analysis:
+
+```
+paradigm_orchestrate_inline({
+  task: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate",
+  mode: "plan"
+})
+```
+
+The plan returns: suggested agents, estimated token cost, and a stage breakdown with dependency information. Review this carefully. If you disagree with the agent selection, you can override it with the `agents` parameter.
+
+### Step 3: Execute to Get Prompts
+
+Once satisfied with the plan, call with `mode="execute"`:
+
+```
+paradigm_orchestrate_inline({
+  task: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate",
+  mode: "execute"
+})
+```
+
+This returns full prompts for each agent, complete with relevant file paths, symbol context, and stage-specific instructions.
+
+### Step 4: Launch Agents
+
+Launch agents according to the stage plan. Stages marked `canRunParallel: true` can be launched simultaneously:
+
+```
+// Stages 1 and 2 can run in parallel:
+Task: [architect prompt from execute output]
+Task: [security prompt from execute output]
+
+// Stage 3 depends on 1 and 2, must wait:
+Task: [builder prompt with handoff context from architect and security]
+
+// Stage 4 depends on 3:
+Task: [tester prompt with handoff context from builder]
+```
+
+### Step 5: Collect and Integrate Results
+
+Each agent returns results in its configured relay format. Review each output, verify it makes sense, and integrate the changes. The orchestrator does not auto-merge -- you are the final integrator.
+
+### CLI Alternative
+
+For command-line orchestration, the `paradigm team orchestrate` command handles the full workflow:
+
+```bash
+# Multi-agent (default)
+paradigm team orchestrate "Add Apple Pay to checkout"
+
+# Single agent mode -- one agent does everything
+paradigm team orchestrate "Add Apple Pay to checkout" --solo
+
+# A/B test -- compare solo vs multi-agent
+paradigm team orchestrate "Add Apple Pay to checkout" --compare
+```
+
+The `--solo` flag is useful when a task does not genuinely need multiple agents. The `--compare` flag runs both solo and faceted modes and lets you compare the results, which is valuable for learning when orchestration adds value versus overhead.
+
+### When NOT to Orchestrate
+
+Orchestration has overhead. For simple tasks (single file change, no security implications, clear implementation), a single builder agent is faster and cheaper. Use orchestration when the task involves 3+ files, has security implications, requires design decisions, or spans multiple feature areas.

package/dist/university-content/notes/N-para-401-pm-governance.md

@@ -0,0 +1,71 @@
+---
+id: N-para-401-pm-governance
+title: PM Governance
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - pre-flight-checks-symbols
+  - post-flight-checks-registration
+  - errorwarningsuggestion-severity-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## PM Governance
+
+The PM (Project Manager) layer is Paradigm's enforcement mechanism that ensures orchestrated tasks follow project discipline. Without governance, agents might implement features without updating `.purpose` files, add endpoints without portal.yaml gates, or ignore team wisdom. The PM layer adds automated pre-flight and post-flight checks that catch these oversights.
+
+### Pre-Flight Checks
+
+Before any implementation begins, the PM runs pre-flight checks to set up the task correctly:
+
+1. **Symbol identification** -- What symbols will this task create or modify? The PM uses `paradigm_search` and `paradigm_navigate` to identify all affected symbols.
+2. **Ripple analysis** -- For each affected symbol, run `paradigm_ripple` to map the blast radius. Flag any fragile dependents.
+3. **Portal requirements** -- If the task adds endpoints, run `paradigm_gates_for_route` to determine required gates. Flag if portal.yaml is missing or needs updates.
+4. **Wisdom check** -- Pull relevant wisdom with `paradigm_wisdom_context` to surface antipatterns and decisions that agents should know about.
+5. **Orchestration recommendation** -- Based on task complexity, recommend whether to use single-agent or multi-agent orchestration.
+
+```
+// Pre-flight output example:
+{
+  affectedSymbols: ["#payment-service", "$checkout-flow"],
+  rippleImpact: { direct: 3, indirect: 7, fragile: ["#notification-handler"] },
+  portalRequired: true,
+  requiredGates: ["^authenticated", "^payment-authorized"],
+  relevantWisdom: ["antipattern: api-001 (direct API calls from UI)"],
+  recommendation: "multi-agent: architect + security + builder"
+}
+```
+
+### Post-Flight Checks
+
+After implementation completes, the PM verifies compliance:
+
+1. **Purpose registration** -- Are all new components registered in `.purpose` files? Did renamed symbols get updated across all references?
+2. **Portal compliance** -- Are all new endpoints listed in portal.yaml with appropriate gates? Are there unprotected routes that should be protected?
+3. **Aspect anchors** -- If aspects were modified, do their anchors still point to valid code?
+4. **Wisdom capture** -- Were any decisions made during implementation that should be recorded? Did any antipatterns surface?
+5. **History recording** -- Was the implementation logged with `paradigm_history_record`?
+
+The PM reports issues in categories: **errors** (must fix before proceeding), **warnings** (should fix), and **suggestions** (good practice). A clean post-flight means full compliance.
+
+### Enabling PM Governance
+
+In the CLI, add the `--pm` flag to orchestrate commands:
+
+```bash
+paradigm team orchestrate "Add refund endpoint" --pm
+```
+
+This wraps the orchestration with pre-flight checks before the first agent runs and post-flight checks after the last agent completes. The PM does not modify code itself -- it reviews and reports, leaving fixes to you or the agents.
+
+PM governance is especially valuable for teams onboarding new developers or working with AI agents that do not yet have deep project familiarity. It is the safety net that ensures Paradigm metadata stays consistent with the code, regardless of who (or what) is writing that code.

package/dist/university-content/notes/N-para-401-provider-cascade.md

@@ -0,0 +1,75 @@
+---
+id: N-para-401-provider-cascade
+title: Provider Cascade
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - six-providers-claude
+  - cascade-tries-providers
+  - three-configuration-methods
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Provider Cascade
+
+Orchestrated agents need somewhere to run. Paradigm supports multiple **execution providers** -- the systems that actually run the agent prompts and return results. Since not every environment has the same providers available (some teams use the Anthropic API directly, others use Claude Code, others use Cursor), Paradigm implements a **cascade** that tries providers in priority order until one works.
+
+The default cascade order is:
+
+### Anthropic / Claude Ecosystem
+
+1. **`claude`** -- Direct Anthropic API. Requires `ANTHROPIC_API_KEY` environment variable. The most flexible option with full control over model selection and parameters.
+
+2. **`claude-code-teams`** -- Claude Code Agent Teams (experimental). Supports parallel agent execution natively. Only available with Claude Code Teams subscription.
+
+3. **`claude-code`** -- Claude Code Task tool. Uses the Task tool within a Claude Code session. Requires a Max subscription. Runs agents as sub-tasks within the current session.
+
+5. **`claude-cli`** -- Spawns separate `claude` CLI processes. Each agent runs as an independent CLI invocation. Available when the Claude CLI is installed.
+
+### Cursor Ecosystem
+
+4. **`cursor-cli`** -- Cursor's agent CLI. Auto-detected when running inside the Cursor IDE. Spawns agents through Cursor's built-in agent system.
+
+### Universal
+
+6. **`manual`** -- File-based handoffs. Always available as a fallback. Writes agent prompts to files that a human (or another tool) can execute. This is the universal fallback that works in every environment.
+
+### Configuration
+
+You can set the preferred provider in three ways (listed in priority order):
+
+```bash
+# Environment variable (highest priority)
+export PARADIGM_AGENT_PROVIDER=claude-code
+
+# Config file (.paradigm/config.yaml)
+agent-provider: claude-code
+
+# CLI command
+paradigm team providers --set claude-code
+```
+
+Setting a preferred provider does not disable the cascade -- it just changes the starting point. If your preferred provider is unavailable (e.g., API key expired), the cascade continues to the next available option.
+
+To see which providers are currently available in your environment, run:
+
+```bash
+paradigm team providers
+# Shows: claude (available), claude-code (available), cursor-cli (not detected), ...
+```
+
+### Model Discovery
+
+Different providers expose different models. `paradigm team models` shows the current model assignments per agent role and which provider serves them. If you add a new API key or install a new tool, run `paradigm team models --refresh` to re-discover available models.
+
+The cascade design means Paradigm orchestration works everywhere -- from a fully-equipped development machine with API keys and IDE integrations, down to a bare terminal where only manual file-based handoffs are possible. The fallback is always there.

package/dist/university-content/notes/N-para-401-quick-check.md

@@ -0,0 +1,95 @@
+---
+id: N-para-401-quick-check
+title: 'Quick-Check: Ask Before You Build'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - quick-check-is-a
+  - two-agents-jinx
+  - two-outcomes-greenlight
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## The Lightweight Pre-Check
+
+Not every task needs full orchestration with architect, security, builder, tester, and reviewer stages. Sometimes you just want to know: *is this task ready to build, or does it need more planning?*
+
+That is what **quick-check mode** does. It runs a lightweight risk assessment (~3–4k tokens) and returns one of two verdicts:
+
+- **GREENLIGHT** — proceed to implementation. The task is well-scoped, low-risk, and does not need multi-agent planning.
+- **ESCALATE** — this needs full orchestration. The task has unaddressed risks, ambiguous requirements, or cross-cutting concerns.
+
+### How It Works
+
+Quick-check uses two agents:
+
+**Jinx (advocate)** stress-tests your assumptions:
+- "What if the user loses their second factor?"
+- "What happens when the payment provider is down?"
+- "Did you consider rate limiting on this endpoint?"
+
+**Reviewer** checks feasibility:
+- Does this touch auth, security, or shared state?
+- How many files will this change?
+- Are there dependencies that need updating?
+
+Their combined assessment produces the verdict. If either agent raises concerns that cannot be resolved in a quick check, the verdict is ESCALATE.
+
+### Usage
+
+```
+paradigm_orchestrate_inline({
+  task: "Add a 'last seen' timestamp to user profiles",
+  mode: "quick"
+})
+```
+
+Compare with full orchestration:
+```
+paradigm_orchestrate_inline({
+  task: "Add two-factor authentication to the login flow",
+  mode: "plan"
+})
+```
+
+### When to Use Quick-Check vs Full Orchestration
+
+| Signal | Quick-Check | Full Orchestration |
+|--------|-------------|-------------------|
+| Single file change | Yes | Overkill |
+| UI-only change (styling, layout) | Yes | Overkill |
+| Touches auth or security | Depends on scope | Usually yes |
+| 3+ files affected | Depends on complexity | Yes |
+| New API endpoint | Depends on gates needed | Usually yes |
+| Infrastructure change | No | Yes |
+| Unknown scope ("make it faster") | No | Yes |
+
+**Rule of thumb:** If you can describe the complete change in one sentence and it touches ≤2 files, quick-check is appropriate. If you find yourself saying "and also..." or "but we need to consider...", go straight to full orchestration.
+
+### Quick-Check and Enforcement
+
+Quick-check satisfies the `orchestration-required` enforcement check. On balanced or strict enforcement, the stop hook requires that complex tasks go through orchestration before building. A GREENLIGHT from quick-check counts — you do not need to run full orchestration after a greenlight.
+
+However, if you get an ESCALATE verdict and proceed to build anyway, the stop hook will flag that you bypassed the recommendation. The verdict is recorded and traceable.
+
+### Example Walkthrough
+
+**Task:** "Add a 'forgot password' link to the login page"
+
+**Jinx:** "Where does the reset email get sent from? Is there rate limiting on reset requests? What happens if the email is not in the system — do you reveal that?"
+
+**Reviewer:** "This touches auth (password reset flow), requires a new API endpoint (/reset-password), involves email sending infrastructure, and needs rate limiting. Estimated: 4+ files."
+
+**Verdict: ESCALATE** — the task looks simple but involves auth, a new endpoint, email, and rate limiting. Full orchestration with security and architect (multi-file design) is recommended.
+
+Compare: "Change the login button color from blue to green" → **GREENLIGHT** (single CSS change, no logic, no auth).

package/dist/university-content/notes/N-para-451-agent-routing.md

@@ -0,0 +1,117 @@
+---
+id: N-para-451-agent-routing
+title: Agent Routing — A Decision Tree for "Which Agent Should I Invoke?"
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - routing
+  - decision-tree
+  - reference
+  - when-to-invoke
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites:
+  - N-para-451-roster-reference
+  - N-para-451-roster-management
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## How to use this entry
+
+This is a **reference card**, not a narrative. Bookmark it. The earlier entries in PARA 451 taught you the team — what an agent is, the three identity layers, the model tiers, the canonical roster, partners, orchestration modes, and roster management. This entry compresses all of that into a single quick-reference: *given a situation in front of me, which agent should I invoke first?*
+
+You will not need this on day one — most invocation is automatic via `paradigm_orchestrate_inline`, agent.yaml keyword routing, and partner declarations. You will reach for it on day thirty, when something does not auto-route the way you expected and you want to know who you should explicitly call.
+
+## The decision tree
+
+Read top-to-bottom. Stop at the first branch that matches.
+
+### Are you starting a new session?
+
+- **Yes** → Invoke **Cid** (`cid`) first. Cid runs the pre-task brief, maps blast radius, and surfaces relevant lore. The first turn of every session belongs to Cid.
+
+### Are you about to design something that spans 3+ files or introduces a new pattern?
+
+- **Yes** → Invoke **Architect** (`architect`). System design, specs, multi-file planning. No code. Architect produces the spec; Builder follows it.
+- **Adding a protected route, auth surface, or anything OWASP-touching at the same time?** → Invoke **Aegis** (`security`) in parallel. Aegis flags; it does not fix. Both can run before Builder.
+
+### Do you have a spec and need code written?
+
+- **Yes** → Invoke **Builder** (`builder`). Builder follows the spec exactly and pushes back if it is unclear. If no spec exists, route through Architect first.
+- **Is the work also explicit visual / UI / design-system work?** → Invoke **Mika** (`designer`) instead of (or in parallel with) Builder for the visual surface. Builder still owns wiring; Mika owns the surface.
+- **Is the work an API surface, SDK, or integration guide?** → Pair **Builder** with **Helix** (`dx`). Helix shapes the developer-facing surface; Builder ships the implementation.
+
+### Has Builder just finished and you need to verify?
+
+- **Code review pass first** → Invoke **Reviewer** (`reviewer`). Two stages: spec compliance, then code quality. Reviewer hands back; never fixes.
+- **Then, did the change touch a user-visible surface (README, --help, error messages, docs, install flow)?** → Invoke **Nora** (`ftux`). Nora simulates a first-time user and reads ONLY user-facing surfaces. Confusion **is** data. Skip Nora when the change is purely internal.
+- **Then, always, as the final orchestration stage** → Invoke **Scribe** (`documentor`). Scribe updates `.purpose` files, `portal.yaml`, and lore. Never source. Documentor is **always last**.
+
+### Is something broken or behaving strangely?
+
+- **You need to understand why** → Invoke **Trace** (`debugger`). Hypothesis-driven, binary-search root-cause hunter.
+- **You need to design tests that would have caught this** → Invoke **Shield** (`qa`) for test *strategy*, then **Probe** (`tester`) to write the tests. Shield designs the pyramid; Probe ships individual tests.
+
+### Is the question "what could break?" or "is this risky?"
+
+- **Yes** → Invoke **Jinx** (`advocate`). Devil's advocate. Stress-tests assumptions; finds edge cases you have not considered. Best invoked *before* irreversible decisions, not after.
+
+### Is the work pedagogical or research-shaped?
+
+- **Authoring or revising University content (notes, paths, quizzes, PLSAT modules)?** → Invoke **Sheila** (`educator`) and **Scholar** (`scholar`) as a pair. Reciprocal partnership: Scholar produces source material; Sheila shapes it into learning experiences. This is the canonical use of the partners primitive — and the pattern that authored this very course.
+- **Pure research / curation / citation discipline (no pedagogical shaping yet)?** → Invoke **Scholar** alone.
+- **Pure pedagogical sequencing (you already have the source material)?** → Invoke **Sheila** alone.
+- **Business research, competitive analysis, market sizing?** → Invoke **Scout** (`researcher`) instead. Different archetype: Scout does *market* research, Scholar does *technical* research.
+
+### Are you adding, redesigning, or training an agent?
+
+- **Yes** → Invoke **Loid** (`forge`). Intelligence officer. Designs agents, processes session debriefs, runs the journal → notebook → wisdom learning loop. Always include Loid when designing agents, team changes, or training systems — she owns the learning loop.
+
+### Is the work performance-shaped?
+
+- **Yes** → Invoke **Bolt** (`performance`). Core Web Vitals, bundles, query optimisation. "Why is this slow?" is Bolt's question.
+
+### Cutting a release?
+
+- **Yes** → Invoke **Ship** (`release`). Versioning, changelog, deployment coordination.
+
+### Working in a Swift / Apple-platform codebase?
+
+- **Yes** → **Swift** (`swift`) is auto-rostered by `paradigm shift` on Swift detection. For any Swift code, Conductor work, or SwiftUI patterns, route through Swift. Notebooks compound globally — every Swift project on your machine sharpens the same agent.
+
+### Does symbol coverage matter on this change?
+
+- **Yes** → Invoke **Rune** (`compliance`). Pre-implementation plan; post-implementation report. Never source. Rune's role sharpens at v6.1 (authority modes, soft-blocks); for now, treat it as a planner / reporter.
+
+### Closing the session?
+
+- **Yes** → Invoke **Cid** (`cid`) again for the post-task debrief, then **Loid** (`forge`) to process the debrief and promote learnings. Cid frames the session; Loid stores what should compound.
+
+## The compressed mental model
+
+If the decision tree is too much, hold three rules in your head:
+
+1. **Cid bookends every session.** Pre-task brief at the start, post-task debrief at the end.
+2. **Architect → Builder → Reviewer → (Nora if user-facing) → Scribe** is the canonical implementation pipeline. Every other agent slots in *around* this spine.
+3. **Specialists slot in by signal, not by schedule.** Aegis on auth; Mika on UI; Trace on bugs; Jinx on risk; Scholar+Sheila on learning content; Loid on agent work; Swift on Swift; Bolt on perf; Ship on releases. Match the signal to the agent and most routing decisions answer themselves.
+
+## When the framework routes for you
+
+Most of the time you will not be reading this entry — you will be writing prompts, and `paradigm_orchestrate_inline` will pick the right agent automatically. Three layers of routing run before you have to think about it:
+
+- **`paradigm_orchestrate_inline`** picks agents based on task keywords, file paths, and orchestration mode.
+- **Keyword triggers in `agents.yaml`** route common phrases ("review", "audit", "implement", "design") to the right agent.
+- **Partner declarations** mean invoking one half of a pair (Scholar) often triggers the other (Sheila) for joint work.
+
+You read this entry when automatic routing missed, or when you want to bypass it for a deliberate reason — a second opinion, a forced specialty pass, a debugging dive that needs a specific archetype.
+
+## Up next
+
+The next entry — **N-para-451-the-team-pattern** — closes the conceptual arc of PARA 451 by zooming all the way back out: *why* does Paradigm have many agents instead of one mega-agent? What does the team pattern actually buy you? After that, the **Q-para-451-when-to-invoke** quiz tests the routing decisions you just learned.

package/dist/university-content/notes/N-para-451-archetypes-vs-instances.md

@@ -0,0 +1,82 @@
+---
+id: N-para-451-archetypes-vs-instances
+title: Archetypes vs Instances — Role Patterns and the Agents That Fill Them
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - archetype
+  - instance
+  - taxonomy
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-identity-layers
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## One archetype, many instances
+
+The previous entry established that **archetype** is one of the three identity layers — the role pattern an agent fills. This entry zooms into the distinction the framework leans on most heavily once you have more than one project: the difference between an **archetype** (a role-type, the shape of a job) and an **instance** (a specific agent on a specific roster, a particular hire who fills that shape).
+
+If you have written code, the analogy is almost on-the-nose: an archetype is a class; an instance is a value of that class. One class can have many values. One archetype can have many agents.
+
+## The two columns side by side
+
+| | Archetype | Instance |
+|---|-----------|----------|
+| **What it is** | A role-type. The *shape* of an agent's job. | A specific rostered agent. A *particular* agent fulfilling that shape. |
+| **Examples** | `compliance`, `architect`, `intelligence-officer`, `educator`, `captain` | Rune (id `compliance`), Architect (id `architect`), Loid (id `forge`), Sheila (id `educator`), Cid (id `cid`) |
+| **Granularity** | A class — same archetype across every Paradigm install. | A value — one specific agent per id, per installed profile. |
+| **Travels how** | Conceptually shared across the ecosystem. Two projects' "compliance archetype" agents are filling the same role even if their names differ. | Pointed at by id. Two projects can both roster `compliance` and they are **the same instance** at the profile level — same `~/.paradigm/agents/compliance.agent` file. |
+| **Mutable?** | Conceptually fixed. An archetype is *what an agent is*; you cannot rename a role-type and have the rest of the framework still reason about it. | The instance's id is fixed; its nickname is mutable per project; its roster status (active / benched) is mutable per project. |
+| **CLI surface today** | None first-class — declared informally in the agent's profile narrative. | Every CLI command that takes an `<id>` is operating on an instance. |
+
+## Worked example: the compliance archetype
+
+Take the **compliance archetype** — the role-type that handles symbol coverage and planning. On the canonical roster, the instance filling that role is **Rune** (id `compliance`).
+
+- The **archetype** says: "this role looks at symbol planning, runs pre-implementation plans, files post-implementation reports, and never writes source." That definition is stable across every Paradigm install — the role exists.
+- The **instance** is Rune. Rune is the agent currently filling that role on the canonical first-party roster. Rune's profile sits at `~/.paradigm/agents/compliance.agent`. Rune has a notebook. Rune is benched or active per project.
+
+Now imagine — purely hypothetically — that someone publishes a *second* compliance-archetype agent to nevr.land: same role-type (symbol planning, coverage), but with a different cognitive bias (perhaps stricter on tag coverage, perhaps looser on aspect drift). That second agent would have:
+
+- a **different id** (say, `compliance-strict`),
+- a **different nickname** (say, "Aegis-2" or whatever the publisher chose),
+- and the **same archetype** (`compliance`).
+
+The two agents would be **two instances of one archetype**. A project could roster either one (or, in principle, both, with the framework treating them as a pair filling the same role from different angles). The archetype tells you "this is a compliance-shaped agent" without committing to *which* compliance-shaped agent.
+
+## Why this matters for your day-to-day
+
+In practice, on a single project, you mostly think about instances — Rune, Loid, Cid, Sheila. You roster them, bench them, invoke them by id. The archetype distinction matters most in three situations:
+
+1. **Cross-project reasoning.** "Does my project have an intelligence officer?" is a question about archetype, not instance. The answer is yes whether your intelligence officer instance is Loid (id `forge`) on this project or, hypothetically, a different forge-archetype agent on a different project.
+
+2. **Talking about role-fit before commit.** When designing a new agent, you usually start by naming the *archetype* it should fill (`security-engineer`? `mobile-platform-specialist`?), then choose a specific instance to ship with that role-type. The archetype is the design abstraction; the instance is the deliverable.
+
+3. **The future registry (nevr.land).** Once agents travel through a public registry, learners will browse archetypes ("I need a debugger archetype agent") and pick from competing instances ("I'll install Trace-classic" or "I'll install Trace-strict"). The two-layer split is what makes that browsing coherent.
+
+## What this looks like at v6.0.3 vs later
+
+Today, the framework leans on archetype as a **concept** — the docs use it, agent profiles narrate it, the canonical roster groups by it. But there is no first-class `archetype` field on `AgentProfile` you can query from the CLI or filter on programmatically. You cannot run `paradigm agent list --archetype intelligence-officer` and get a clean answer; you have to read the profile narratives and infer.
+
+> **Coming in v6.1:** `archetype` becomes a first-class field on `AgentProfile`, queryable from the CLI and surfaced in registry listings. Existing agent profiles will gain an explicit `archetype:` declaration. Until then, archetype is a stable concept the framework reasons in but does not enforce in the schema. See `agent-owned-enforcement-plan.md`.
+
+## A common confusion to avoid
+
+It is tempting to read the canonical roster and conclude that every archetype has exactly one instance, because that is what the first-party roster ships today: one Architect, one Builder, one Loid, one Sheila. **That is a property of the current roster, not a property of the model.** The framework already supports multiple instances per archetype at the conceptual level, and the v6.1 first-class archetype field is what surfaces it. Treating the roster as a fixed one-to-one mapping will make the registry confusing later; treating it as "twenty-one instances filling sixteen-or-so distinct archetypes today" matches the design.
+
+## Try this
+
+Pick three agents from `paradigm agent list` and try to articulate each one's **archetype** (its role-type) versus its **instance identity** (its id and nickname). For Rune, the archetype is `compliance` and the instance id is `compliance`; the two happen to share the spelling. For Loid, the archetype is `intelligence-officer` and the instance id is `forge`; they diverge cleanly. For Mika, the archetype is `designer` and the instance id is `designer`. The point of the exercise is not to memorise which is which — it is to feel the layer separation in your hands before the v6.1 surface makes it explicit.
+
+## Up next
+
+The next entry — **N-para-451-tiers** — switches axes entirely. Identity layers (and the archetype / instance split) tell you *who* an agent is. Tiers tell you *which Claude model* the agent runs on. Two orthogonal taxonomies; both worth holding in your head.

package/dist/university-content/notes/N-para-451-identity-layers.md

@@ -0,0 +1,76 @@
+---
+id: N-para-451-identity-layers
+title: The Three-Layer Identity Model
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - identity
+  - three-layer
+  - archetype
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-welcome
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Three layers, one agent
+
+Every Paradigm agent has three layers of identity. They are easy to confuse on first contact, but keeping them straight is the single most important thing you will learn in this course — every later concept (partners, rostering, the registry, cross-project notebooks) leans on this distinction.
+
+| Layer | What it is | Example | Mutable? |
+|-------|------------|---------|----------|
+| **id** | Machine-stable handle. Used in CLI, MCP, and registry calls. | `architect`, `forge`, `cid` | No — set when the agent is published; changing it breaks every reference. |
+| **nickname** | User-customisable display name. What you see in logs and orchestration output. | "Architect", "Loid", "Cid" | Yes — rename per project, per user, per taste. |
+| **archetype** | Role pattern. Describes what *kind* of agent this is. | `architect`, `intelligence-officer`, `captain` | Conceptually fixed — it is what the agent *is*, not what it is *called*. |
+
+## Walking through it
+
+### Example 1: the architect agent
+
+- **id:** `architect`
+- **nickname:** "Architect" (default; some users rename it to "Apex" or similar)
+- **archetype:** `architect`
+
+This is the canonical case where all three layers happen to share the same name. It is also the source of most confusion — learners assume the layers are the same thing because they look identical. They are not. The id is what `paradigm agent get architect` resolves against. The nickname is what shows up in your terminal. The archetype is what tells the framework "this agent fills the architect-shaped hole on every team."
+
+### Example 2: the intelligence officer
+
+- **id:** `forge`
+- **nickname:** "Loid"
+- **archetype:** `intelligence-officer`
+
+Here all three layers diverge. The CLI calls it `forge`. The team calls it Loid. The role pattern is "intelligence officer" — the agent that designs other agents, processes session debriefs, and runs the learning loop that promotes journal entries to notebook entries to wisdom. If a second agent ever shipped that filled the same role pattern (a different intelligence officer, perhaps with a different specialty bias), it would have a different `id` and a different `nickname` but the same `archetype: intelligence-officer`.
+
+## Why three layers, not one or two?
+
+Each layer earns its keep:
+
+- **id** has to be stable so that scripts, configs, MCP calls, and the cross-project notebook system never lose track of which agent is which. If `forge` could rename itself to `loid` tomorrow, every project's roster would silently break.
+- **nickname** has to be mutable so that you, the user, can call your team whatever you want. The framework is yours; if "Loid" feels wrong and you want "Sage" instead, that should be a one-line change with no breakage.
+- **archetype** has to be a separate layer because some questions are about *what role an agent fills*, not *which specific agent fills it*. "Does my project have an intelligence officer?" should be answerable without knowing whether yours is named Loid, Sage, or Forge.
+
+This is also what makes the planned **nevr.land** registry coherent. When agents travel — installed across the ecosystem, recommended to other projects, paired with each other — the unit of identity has to be richer than just a name.
+
+## Where each layer lives in the file system
+
+- **Profile (id-keyed):** `~/.paradigm/agents/<id>.agent` — for example, `~/.paradigm/agents/forge.agent`. The filename is the id.
+- **Nickname (project- or user-keyed):** `.paradigm/agents.yaml` under the agent's id, e.g. `forge: { nickname: "Loid" }`. Override per project.
+- **Archetype (conceptual today):** declared informally in the agent's profile and in framework documentation. There is no first-class `archetype` field in `AgentProfile` yet — that lands in v6.1.
+
+> **Coming in v6.1:** `archetype` becomes a first-class field in `AgentProfile`, queryable from the registry and the CLI. For now, archetype is a concept the framework leans on but does not yet enforce in the schema. Declarations made today will not need rewriting once the field ships. See `agent-owned-enforcement-plan.md`.
+
+## Try this
+
+Run `paradigm agent get forge`. The `id` field is `forge`. Look for the nickname (it will be "Loid" on most rosters). Now run `paradigm agent list` — the displayed name in the roster is the nickname, but the underlying record is keyed on the id. The archetype layer is the one you cannot see in the CLI yet; you have to read about it (here, in the agent's profile narrative, and in framework documentation) until v6.1 makes it queryable.
+
+## Up next
+
+Now that you can tell the three layers apart, the next entry — **N-para-451-archetypes-vs-instances** — zooms into the distinction between an *archetype* (the role pattern) and an *instance* (a specific agent on your roster), and shows what it means for two agents to share an archetype. After that, **N-para-451-tiers** covers the orthogonal question of which model an agent runs on.