@a-company/paradigm 6.0.2 → 6.0.4

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

@@ -0,0 +1,55 @@
+---
+id: N-para-451-welcome
+title: Welcome to PARA 451 — Agents Foundations
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - welcome
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - LP-para-101
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Why this course exists
+
+Paradigm's most differentiated feature is its **agent team**. Other AI tooling gives you one model and a chat box. Paradigm gives you a roster of named, persistent identities — each with its own role, its own notebook of learned patterns, and its own moment to step in. Architect designs. Builder implements. Reviewer reviews. Cid runs the briefing. Loid runs the learning loop. Scholar and Sheila pair on research. The team is the product.
+
+Until now, the only place to learn about agents in University was a handful of entries inside PARA 401: Orchestration — an advanced course beginners rarely reach. Worse, those entries pre-date the v6.0.3 partners primitive and the three-layer identity model, so they describe an older version of the team. PARA 451 is the canonical, beginner-accessible introduction; the older PARA 401 agent entries are flagged as v6.1 retirement candidates and will be retired once 451 is broadly adopted.
+
+## What you will learn
+
+By the end of this course you will be able to answer:
+
+- **What is an agent in Paradigm, and how is it different from "the model"?** An agent is a persistent identity with a profile, a notebook, and a role — not a single prompt or a single Claude call.
+- **What is an archetype, and how is it different from a nickname or an id?** The three-layer identity model (id / nickname / archetype) is what makes the same agent recognisable across every project, while still letting you call it whatever you want on yours.
+- **Who is on the team, and when do you call each one?** A single roster reference page covers all twenty-one currently-active agents — what each one is for, when it gets invoked, and which agents it pairs with.
+- **What does it mean for two agents to be "partners"?** The partners primitive (shipped at v6.0.3) is how the framework expresses that some agents work meaningfully better as a unit. Scholar + Sheila is the canonical example.
+- **How does orchestration actually run?** Faceted orchestration in Claude Code (true multi-agent, isolated Task contexts) versus sequential roleplay in Cursor and IDEs without Task tool support.
+
+## Prerequisite
+
+You should have completed **PARA 101: Foundations** — the five symbols, `.purpose` files, the basic shape of the `.paradigm/` directory. You do **not** need PARA 201, 301, or 401. The agent system is conceptually approachable, and learning the team early pays off in every project from then on.
+
+## Course shape
+
+PARA 451 is a single ordered learning path: notes interleaved with quizzes, ending in a mastery review. The full course is ~18 entries (about 35 minutes if you skim, 75-90 minutes if you take the quizzes seriously). This first batch of entries covers the foundation: identity, model tiers, and the roster. Subsequent batches add roster management, orchestration modes, the partners primitive deep-dive, and auto-rostering.
+
+## What this course does **not** cover
+
+Phase A — the entries in this course — is intentionally stable. We do not teach Rune's authority modes, the soft-block primitive, the notebook tier-1/tier-2 split, or the cross-project compounding runtime. Those topics are evolving as the v6.1 enforcement model lands, and they live in **PARA 551: Agents in Practice** (the follow-up course). The mastery review at the end of 451 will point you there when you are ready.
+
+> **Coming in v6.1:** PARA 551 launches alongside the v6.1 enforcement-model release. It treats PARA 451 as a hard prerequisite. See `agent-owned-enforcement-plan.md`.
+
+## Where to go from here
+
+Continue to **N-para-451-what-is-an-agent** to start with the conceptual foundation, then move on to **N-para-451-identity-layers**. If you only have ten minutes and you want the team-at-a-glance, jump to **N-para-451-roster-reference** — it is the most-referenced page in the course, and you will come back to it often.

package/dist/university-content/notes/N-para-451-what-is-an-agent.md

@@ -0,0 +1,73 @@
+---
+id: N-para-451-what-is-an-agent
+title: What Is an Agent in Paradigm?
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - identity
+  - profile
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-welcome
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## An agent is not a model invocation
+
+The single most common confusion newcomers bring to Paradigm is the assumption that "an agent" is just "a Claude API call with a system prompt". It is not. A model invocation is **transient** — it begins, returns a response, and forgets everything. An **agent** is **persistent**: it has a name, a profile on disk, a notebook of patterns it has learned, and a role it fills across every session and (often) across every project on your machine.
+
+Concretely, an agent in Paradigm is the union of four things:
+
+| Part | What it is | Where it lives |
+|------|------------|----------------|
+| **Profile** | The agent's identity, role, voice, expertise, and partner declarations. | `~/.paradigm/agents/<id>.agent` |
+| **Notebook** | What the agent has learned — patterns, gotchas, expertise entries promoted from journal observations. | `.paradigm/notebooks/<id>/` (project) or global notebook stores |
+| **Roster entry** | Whether this agent is active on a given project, and at what tier. | `.paradigm/roster.yaml` |
+| **Runtime invocation** | The Claude model call that happens when the agent is asked to do something — driven by the profile, fed the notebook, scoped by the roster. | At runtime, via `paradigm_orchestrate_inline` or the Claude Code Task tool |
+
+Strip any one of these away and you do not have an agent any more — you have something less. A profile with no notebook is a fresh hire. A notebook with no profile is orphaned data. A roster entry pointing at a missing profile is a dangling reference. The agent is the *whole* construct.
+
+## Why the framework has many of them
+
+Paradigm could have given you one big general-purpose Claude with a long system prompt and called it a day. It deliberately does not. Two reasons:
+
+1. **Specialised attention beats generalist attention.** When Architect is invoked, its profile narrows the model's attention to system design — multi-file planning, spec coherence, blast-radius reasoning. When Builder is invoked, its profile narrows attention to "follow the spec exactly, push back if unclear, ship the code". The same Claude model in both invocations produces measurably different output because the framing is different. A multi-agent team is a way of giving the model **multiple framings** in the same project, each at the right time.
+
+2. **Persistent expertise compounds per role.** Architect's notebook accrues *design* patterns. Reviewer's notebook accrues *review* heuristics. Loid's notebook accrues *learning-loop* observations. If everything were one agent, the patterns would muddle. Splitting roles means each agent's notebook stays sharp in its lane, and the cross-project learning that Paradigm bets on (Swift patterns compounding everywhere Swift is detected, for example) actually makes sense.
+
+The team metaphor is not decoration. It is the simplest accurate description of what is happening: a small group of specialised, persistent identities, each running on Claude, coordinating through the framework.
+
+## Two scopes: globally installed, project-rostered
+
+Every agent has two scopes you should keep straight from day one:
+
+- **Globally installed** — the profile sits at `~/.paradigm/agents/<id>.agent` and exists once on your machine. You can install agents from GitHub or (in future) the nevr.land registry; the profile travels with you.
+- **Project-rostered** — each project decides which agents from your global pool are active, via `.paradigm/roster.yaml`. Benching an agent on Project A leaves it untouched on Project B. The same global Architect can be active on six projects simultaneously and benched on a seventh.
+
+This split is intentional. You curate your team once, globally. You shape your team per project, locally. The roster-management entry later in the course (**N-para-451-roster-management**) walks through the CLI and the `/paradigm:agents` skill that drive both halves.
+
+## How agents are invoked at runtime
+
+When the framework needs an agent to do something, two paths are common:
+
+1. **Via the Task tool (Claude Code).** Each agent runs in an isolated Task subagent context, with the `paradigm:` prefix on its name (e.g. `paradigm:architect`, `paradigm:builder`). Each agent has its own conversation, its own memory, its own tool access — true multi-agent execution. This is **faceted orchestration**, the default in Claude Code.
+2. **Via sequential roleplay.** In Cursor and other IDEs without Task tool support, the framework runs each agent as an inline persona switch in the same context — you see the agent's voice and reasoning, but they share memory rather than each holding their own. This is **sequential mode**, covered in **N-para-451-orchestration-modes**.
+
+Either way, the agent's profile is loaded, its notebook is consulted, and its output is attributed back to its identity (so you can see in the orchestration log "Architect designed", "Builder implemented", "Reviewer flagged"). The mode shapes *how* the work runs; the identity is the same either way.
+
+## Try this
+
+Run `paradigm agent list`. The output is your project's roster — every agent currently active, with its id and nickname. Pick one (Architect is a good first target) and run `paradigm agent get architect`. You will see the profile fields: id, nickname, role, tier, partners, and a description of what the agent does. That on-disk record — not a conversation, not a single prompt — is the agent.
+
+## Up next
+
+Now that the agent concept is clear, **N-para-451-identity-layers** zooms into the three layers every agent has (id, nickname, archetype) and why each layer earns its keep. After that, **N-para-451-tiers** covers the orthogonal question of which Claude model an agent runs on by default.

package/dist/university-content/paths/LP-para-451.yaml

@@ -0,0 +1,69 @@
+id: LP-para-451
+title: 'PARA 451: Agents Foundations'
+description: >-
+  Meet the team. Learn what each agent does and when to call them. PARA 451 is the
+  beginner-accessible introduction to Paradigm's most differentiated feature — its
+  agent system. The course covers the three-layer identity model (id / nickname /
+  archetype), the archetype-vs-instance distinction, the model-tier taxonomy, the
+  canonical 21-agent roster, roster management, the `paradigm shift` auto-rosterer,
+  the orchestration modes (faceted vs sequential roleplay), the partners
+  primitive, an agent-routing decision tree, and a capstone on why the team
+  pattern wins. Approximately 18 entries when complete (~35 minutes skim,
+  75-90 minutes full mastery). This course is the canonical introduction to
+  agents; the older agent entries inside PARA 401 are flagged as v6.1 retirement
+  candidates. Subsequent course PARA 551 (Agents in Practice) covers the v6.1
+  enforcement model, authority modes, soft-blocks, and notebook tier-1/tier-2
+  split.
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - path
+ordered: true
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+prerequisites:
+  - LP-para-101
+# Batches 1-3 (14 of ~18 planned entries) are implemented below. The remaining
+# planned entries (per .paradigm/research/agents-course-phase-a-design.md §2)
+# are the per-topic mini-quizzes (Q-para-451-identity-layers,
+# Q-para-451-archetypes-vs-instances, Q-para-451-tiers,
+# Q-para-451-roster-management, Q-para-451-orchestration-modes,
+# Q-para-451-partners) and the N-para-451-mastery-review note. Per the
+# batch-2/3 user locks, mini-quizzes are deferred to a polish pass after
+# launch — bigger when-to-invoke is the highest-leverage routing test, and the
+# capstone N-para-451-the-team-pattern serves as the conceptual close until
+# mastery-review lands.
+steps:
+  - content: N-para-451-welcome
+    required: true
+  - content: N-para-451-what-is-an-agent
+    required: true
+  - content: N-para-451-identity-layers
+    required: true
+  - content: N-para-451-archetypes-vs-instances
+    required: true
+  - content: N-para-451-tiers
+    required: true
+  - content: N-para-451-roster-reference
+    required: true
+  - content: N-para-451-roster-management
+    required: true
+  - content: N-para-451-paradigm-shift
+    required: true
+  - content: N-para-451-orchestration-modes
+    required: true
+  - content: N-para-451-partners-primitive
+    required: true
+  - content: N-para-451-agent-routing
+    required: true
+  - content: N-para-451-the-team-pattern
+    required: true
+  - content: Q-para-451-when-to-invoke
+    required: true
+  - content: Q-para-451-foundations
+    required: true

package/dist/university-content/quizzes/Q-para-451-foundations.yaml

@@ -0,0 +1,154 @@
+id: Q-para-451-foundations
+title: 'PARA 451: Agents Foundations — Foundations Quiz'
+description: >-
+  First quiz of PARA 451. Covers what an agent is, the three identity layers
+  (id / nickname / archetype), model tiers, the faceted vs sequential
+  orchestration modes, when to invoke the always-on backbone agents, and the
+  `paradigm shift` auto-rosterer. Six questions.
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - foundations
+  - quiz
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+prerequisites:
+  - N-para-451-roster-management
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+questions:
+  - id: q1
+    question: >-
+      You rename `forge` to "Lola" on your project, while leaving the agent's
+      machine-stable handle and role pattern untouched. Which of the three
+      identity layers did you change?
+    choices:
+      A: id
+      B: nickname
+      C: archetype
+      D: tier
+      E: All three — they always change together
+    correct: B
+    explanation: >-
+      The nickname is the user-customisable display layer. Renaming `forge` to
+      "Lola" changes only the nickname; the id (`forge`) stays stable so CLI,
+      MCP, and registry references keep resolving, and the archetype
+      (`intelligence-officer`) stays fixed because that is what the agent *is*,
+      not what it is *called*. Tier is an orthogonal axis (which model the
+      agent runs on) and is not part of the identity model.
+  - id: q2
+    question: >-
+      A teammate says "let's bump documentor up to opus on this project for
+      the next week." Which Paradigm concept are they actually changing?
+    choices:
+      A: The documentor's archetype
+      B: The documentor's notebook tier
+      C: The documentor's model tier (its default Claude model)
+      D: The documentor's roster status
+      E: The documentor's partners declaration
+    correct: C
+    explanation: >-
+      Model tier maps an agent to a default Claude model — tier-1 (opus),
+      tier-2 (sonnet), tier-3 (haiku). Bumping `documentor` from its tier-2
+      default up to opus is a model-tier override, configured per-project in
+      `.paradigm/config.yaml` under `model-resolution`. This is **not** the
+      v6.1 notebook-tier concept (scope/ownership of learned patterns), which
+      is a separate axis with the same unfortunate name — PARA 451 keeps the
+      two strictly separate.
+  - id: q3
+    question: >-
+      You are working in Cursor on a small task. You notice that when the
+      orchestrator switches from `architect` to `builder`, builder seems to
+      "remember" things architect just discussed. In Claude Code with the
+      default settings, this would not happen. What is the difference?
+    choices:
+      A: Cursor uses faceted mode and Claude Code uses sequential mode
+      B: >-
+        Cursor uses sequential mode (single shared context, agents take turns
+        in the same conversation), while Claude Code defaults to faceted mode
+        (each agent runs in an isolated Task subagent with its own memory)
+      C: Cursor disables agent profiles entirely
+      D: Claude Code shares notebooks across agents while Cursor does not
+      E: The two IDEs use entirely different agent rosters
+    correct: B
+    explanation: >-
+      Faceted mode (the Claude Code default) launches each agent as an
+      isolated Task subagent — separate context, separate memory, separate
+      tool access. Sequential mode (Cursor and other IDEs without Task tool
+      support) runs each agent as a persona switch in the same conversation,
+      so they share memory. Both modes use the same agent profiles and the
+      same identity layers; the difference is the runtime plumbing. The mode
+      is configured by `orchestration.default_mode` in `agents.yaml`.
+  - id: q4
+    question: >-
+      You are about to start a feature that will touch eight files across
+      three packages and you do not yet have a written plan. Which agent
+      should pick this up first?
+    choices:
+      A: builder — start implementing and figure it out as you go
+      B: reviewer — review what you already have before planning
+      C: architect — design the multi-file change and produce a spec
+      D: tester — write tests first and let the design fall out
+      E: documentor — update `.purpose` files first
+    correct: C
+    explanation: >-
+      `architect` is the design agent — system design, specs, multi-file
+      planning. Anything that spans three or more files in a non-trivial way
+      is architect's territory. `builder` follows the spec architect produces;
+      invoking builder first on an unscoped change is exactly the trap
+      architect exists to prevent. `reviewer` runs after implementation, not
+      before. `documentor` runs as the final orchestration stage on
+      `.purpose` files and `portal.yaml`, not as the entry point for
+      multi-file design work.
+  - id: q5
+    question: >-
+      `builder` has just finished implementing a feature and the diff is in
+      front of you. The change touches the README. Which agents should run
+      next, and in what order?
+    choices:
+      A: documentor first, then reviewer
+      B: reviewer first, then documentor (the final orchestration stage)
+      C: ftux first, then reviewer, then documentor
+      D: reviewer first, then ftux (because the README is a user-visible
+        surface), then documentor as the final stage
+      E: Only documentor — reviewer is unnecessary on small features
+    correct: D
+    explanation: >-
+      The canonical post-implementation sequence: `reviewer` does the
+      two-stage review (spec compliance, then code quality) and hands back
+      without fixing. `ftux` (Nora) runs after Builder when the task touches
+      a user-visible surface — README qualifies, and ftux reads ONLY
+      user-facing surfaces to simulate first-time-user friction. `documentor`
+      is **always the final orchestration stage** — it updates `.purpose`
+      files, `portal.yaml`, and lore, never source. Reviewer-only or
+      documentor-only sequences skip the friction signal that Nora exists to
+      capture.
+  - id: q6
+    question: >-
+      You have just cloned a fresh Swift project and the repo has no
+      `.paradigm/roster.yaml` yet. Which command bootstraps an initial roster
+      that includes both the always-on backbone *and* the matching ecosystem
+      agent?
+    choices:
+      A: paradigm agent list
+      B: paradigm agent activate swift
+      C: paradigm shift
+      D: paradigm agent get architect
+      E: paradigm agent bench --all
+    correct: C
+    explanation: >-
+      `paradigm shift` is the auto-rosterer. It detects the project's
+      language and platform (Swift in this case), selects the always-on
+      backbone (architect, builder, reviewer, security, tester, documentor,
+      cid), and adds matching ecosystem agents (`swift` for a Swift project).
+      `paradigm agent list` only displays the current roster; `paradigm agent
+      activate swift` would only add the ecosystem agent and would not seed
+      the backbone; the other options do unrelated things. `paradigm shift`
+      is the single command that gets a fresh project from "no roster" to "a
+      sensible default roster".

package/dist/university-content/quizzes/Q-para-451-when-to-invoke.yaml

@@ -0,0 +1,182 @@
+id: Q-para-451-when-to-invoke
+title: 'PARA 451: Agents Foundations — When to Invoke Quiz'
+description: >-
+  Highest-leverage routing quiz of PARA 451. Five scenario questions covering
+  builder-vs-documentor differentiation, reviewer activation timing, scholar
+  deep-dive triggering, ftux first-time UX simulation, and designer for visual
+  work. Tests the decision-tree material from N-para-451-agent-routing.
+  Architect-routing scenario is intentionally omitted (already covered in
+  Q-para-451-foundations q4).
+type: quiz
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - routing
+  - when-to-invoke
+  - quiz
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+prerequisites:
+  - N-para-451-agent-routing
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+questions:
+  - id: q1
+    question: >-
+      Builder has just shipped a feature. The diff modifies source files and
+      adds three new exported functions, but does not touch any `.purpose`
+      files, `portal.yaml`, or lore. Two agents are clearly relevant: one to
+      verify the implementation, and one to keep framework metadata in sync.
+      Which agent owns which job, and in what order do they run?
+    choices:
+      A: documentor reviews the code, then builder updates .purpose files
+      B: >-
+        reviewer reviews the code (spec compliance, then code quality), then
+        documentor updates `.purpose` files, `portal.yaml`, and lore as the
+        final orchestration stage. documentor never touches source.
+      C: >-
+        documentor reviews the code AND updates .purpose files in one pass —
+        reviewer is unnecessary for small changes
+      D: >-
+        reviewer reviews the code AND updates .purpose files in one pass —
+        documentor is for user-facing docs only
+      E: >-
+        builder updates `.purpose` files itself; neither reviewer nor
+        documentor needs to run
+    correct: B
+    explanation: >-
+      reviewer and documentor own non-overlapping jobs. reviewer runs the
+      two-stage review (spec compliance, then code quality) and hands back
+      without fixing — its job is verifying the code. documentor is **always
+      the final orchestration stage** and updates `.purpose` files,
+      `portal.yaml`, and lore — never source. The two agents differentiate
+      cleanly: reviewer touches code (read-only), documentor touches
+      framework metadata (write). Conflating them is the most common routing
+      mistake; that is why this quiz tests the difference explicitly.
+  - id: q2
+    question: >-
+      You are halfway through implementing a feature in builder when you
+      realise the spec is ambiguous about an edge case. What is the right
+      escalation move?
+    choices:
+      A: >-
+        Push through with a best-guess interpretation; reviewer will catch it
+        later
+      B: Bench builder and switch to architect to redesign the whole feature
+      C: >-
+        Have builder push back on the ambiguity (this is one of builder's
+        documented behaviours) and route the clarifying question to architect
+        — the agent that produced the spec — before continuing
+      D: >-
+        Ask documentor to clarify the spec, since documentor owns
+        framework-text consistency
+      E: Invoke jinx (advocate) to pick the safer interpretation
+    correct: C
+    explanation: >-
+      builder's profile explicitly says "follows specs exactly. Pushes back
+      when unclear." Pushing back on ambiguity is the documented behaviour,
+      not a failure mode. The clarifying question routes to architect because
+      architect owns the spec — that is exactly what architect was invoked
+      for. reviewer runs after implementation, not as a clarification surface
+      mid-implementation. documentor never touches spec content. jinx is for
+      stress-testing assumptions before high-risk decisions, not for
+      arbitrating ambiguous spec text.
+  - id: q3
+    question: >-
+      You are about to add a new technical research entry to the project's
+      learning materials — citations, file references, careful sourcing — and
+      then shape it into a sequenced quiz. Which agent (or pair) picks this
+      up?
+    choices:
+      A: educator alone — pedagogical sequencing covers all of it
+      B: scholar alone — research includes the shaping step
+      C: researcher alone — all research is researcher's job
+      D: >-
+        scholar and educator as a reciprocal pair — scholar produces the
+        source material with citation discipline; educator shapes it
+        pedagogically into the quiz. This is the canonical use of the
+        partners primitive.
+      E: documentor — University content is framework-text, so documentor owns it
+    correct: D
+    explanation: >-
+      scholar and educator (Sheila) are the canonical partners pair in
+      Paradigm. scholar produces source material with citation discipline;
+      educator shapes it into pedagogical form (sequenced quizzes, paths,
+      PLSAT modules). Routing to one alone leaves half the work undone.
+      researcher is the **business / market** research agent, not technical
+      research — different archetype entirely. documentor handles framework
+      metadata (`.purpose`, `portal.yaml`, lore), not University content.
+      This routing is the same partnership that authored PARA 451 itself.
+  - id: q4
+    question: >-
+      Builder has just shipped a CLI command improvement. The change updates
+      the `--help` output, the printed error messages, and the README's
+      install section. After reviewer signs off but before documentor runs,
+      which additional agent should be in the pipeline, and what is the rule
+      for when to include it?
+    choices:
+      A: >-
+        scholar — to research how other CLIs handle the same command shape
+      B: >-
+        ftux — Nora simulates a first-time user and reads ONLY user-facing
+        surfaces (README, --help, docs, error messages). Include ftux after
+        builder when the task touches a user-visible surface; skip when the
+        change is purely internal.
+      C: >-
+        designer — Mika reviews any text change for visual hierarchy
+      D: >-
+        ftux always runs after every builder pass, regardless of whether the
+        change is user-facing
+      E: >-
+        jinx — to stress-test the new error messages for failure modes
+    correct: B
+    explanation: >-
+      ftux (Nora) is the framework's first-time-user-experience guard. Its
+      simulation integrity rule is strict — it reads ONLY user-facing surfaces
+      (README, --help, docs, changelogs, error strings). It never reads
+      source code; confusion observed in user-facing surfaces **is** data.
+      The trigger condition is "the task touches a user-visible surface" —
+      a CLI `--help` change, a README update, or new error messages all
+      qualify. Internal-only refactors do not. ftux running after every
+      builder pass would be wasted invocation; ftux skipping a CLI surface
+      change would miss the friction it exists to catch.
+  - id: q5
+    question: >-
+      You are about to redesign the visual layout of a settings panel — UI
+      hierarchy, spacing, motion, accessibility. Which agent owns this work,
+      and what is the relationship to builder?
+    choices:
+      A: >-
+        builder owns it — visual work is just code, and builder writes the
+        code
+      B: >-
+        designer (Mika) owns the visual surface; builder owns the wiring.
+        Invoke designer for the visual decisions, builder for the
+        implementation, often in parallel for visual / UI / design-system
+        work.
+      C: >-
+        forge owns it — visual changes are agent work
+      D: >-
+        documentor owns it, since visual changes are user-facing
+      E: >-
+        Only mika can ever touch UI code; builder must be benched on UI
+        projects entirely
+    correct: B
+    explanation: >-
+      designer (Mika) is the design engineer — UI/UX, design systems, motion,
+      accessibility. designer owns the **surface** (the visual decisions, the
+      hierarchy, the spacing, the motion); builder owns the **wiring** (the
+      implementation that makes the surface real). On UI work the two run
+      together — often in parallel — with designer producing the surface
+      decisions and builder shipping the implementation. forge is the
+      intelligence-officer archetype (Loid) and has nothing to do with
+      visual work. documentor only touches framework metadata. Benching
+      builder on UI projects entirely would be incorrect — builder is
+      always part of the implementation pipeline; designer is the
+      *additional* agent that owns the visual decisions builder implements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-company/paradigm",
-  "version": "6.0.2",
+  "version": "6.0.4",
   "description": "Unified CLI for Paradigm developer tools",
   "type": "module",
   "main": "./dist/index.js",

package/dist/agent-X6I2YWOB.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-import {a as a$1}from'./chunk-LKAT7IAK.js';import'./chunk-5TAVYPOV.js';import*as a from'fs';import*as y from'path';import*as R from'os';import o from'chalk';import*as m from'js-yaml';var h=y.join(R.homedir(),".paradigm","agents"),S=".paradigm/agents",$=".agent",k=".paradigm/roster.yaml";function j(e){let s=y.join(e,k);if(!a.existsSync(s))return null;try{return m.load(a.readFileSync(s,"utf8"))?.active??null}catch{return null}}function F(e,s){let c=y.join(e,k),n=y.dirname(c);a.existsSync(n)||a.mkdirSync(n,{recursive:true});let r={version:"1.0",active:s.sort()};a.writeFileSync(c,m.dump(r,{lineWidth:-1,noRefs:true}),"utf8");}function C(){if(!a.existsSync(h))return [];try{return a.readdirSync(h).filter(e=>e.endsWith($)).map(e=>e.replace($,""))}catch{return []}}var E={architect:{style:"deliberate",risk:"conservative",verbosity:"detailed"},builder:{style:"rapid",risk:"balanced",verbosity:"concise"},tester:{style:"methodical",risk:"conservative",verbosity:"concise"},reviewer:{style:"deliberate",risk:"conservative",verbosity:"detailed"},security:{style:"methodical",risk:"conservative",verbosity:"detailed"}};async function _(e={}){let s=process.cwd(),c=a$1.command("agent-list").start("Listing agent profiles",{cwd:s}),n=[];if(!e.project&&a.existsSync(h))try{let i=a.readdirSync(h).filter(d=>d.endsWith($));for(let d of i)try{let f=a.readFileSync(y.join(h,d),"utf-8"),t=m.load(f);t?.id&&n.push(t);}catch{}}catch{}let r=y.join(s,S);if(!e.global&&a.existsSync(r))try{let i=a.readdirSync(r).filter(d=>d.endsWith($));for(let d of i)try{let f=a.readFileSync(y.join(r,d),"utf-8"),t=m.load(f);if(t?.id){let l=n.findIndex(g=>g.id===t.id);l>=0?n[l]=t:n.push(t);}}catch{}}catch{}if(e.json){console.log(JSON.stringify({count:n.length,agents:n.map(O)},null,2)),c.success(`Found ${n.length} agents`);return}if(console.log(o.blue(`
-\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510`)),console.log(o.blue("\u2502")+o.white.bold("  paradigm agent list                              ")+o.blue("\u2502")),console.log(o.blue("\u2502")+o.gray("  Persistent agent identity profiles              ")+o.blue("\u2502")),console.log(o.blue(`\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-`)),n.length===0){console.log(o.yellow("  No .agent profiles found.")),console.log(o.gray(`  Create one: paradigm agent create <id> --global
-`)),c.success("No agents found");return}for(let i of n){let f=(i.expertise||[]).sort((t,l)=>l.confidence-t.confidence).slice(0,3).map(t=>`${t.symbol} (${(t.confidence*100).toFixed(0)}%)`).join(", ")||o.gray("none yet");console.log(`  ${o.white.bold(i.id)} \u2014 ${o.gray(i.role)}`),console.log(`    Style: ${i.personality?.style||"?"} | Risk: ${i.personality?.risk||"?"} | Verbosity: ${i.personality?.verbosity||"?"}`),console.log(`    Top expertise: ${f}`),console.log(`    Projects: ${Object.keys(i.contexts||{}).join(", ")||o.gray("none")}`),console.log("");}c.success(`Listed ${n.length} agents`);}async function D(e,s={}){let c=process.cwd(),n=a$1.command("agent-show").start(`Showing agent ${e}`,{cwd:c}),r=w(c,e);if(!r){s.json?console.log(JSON.stringify({error:`Agent "${e}" not found`})):(console.log(o.red(`
-  Agent "${e}" not found.`)),console.log(o.gray(`  Create: paradigm agent create ${e} --global
-`))),n.error(`Agent ${e} not found`);return}if(s.json){console.log(JSON.stringify(r,null,2)),n.success(`Showed agent ${e}`);return}if(console.log(o.blue(`
-\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510`)),console.log(o.blue("\u2502")+o.white.bold(`  Agent: ${e}`.padEnd(50))+o.blue("\u2502")),console.log(o.blue(`\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-`)),console.log(`  ${o.white.bold("Role:")} ${r.role}`),console.log(`  ${o.white.bold("Description:")} ${r.description}`),console.log(`  ${o.white.bold("Version:")} ${r.version}`),console.log(`  ${o.white.bold("Created:")} ${r.created}`),console.log(`  ${o.white.bold("Updated:")} ${r.updated}`),console.log(""),r.personality){let l=r.personality;console.log(`  ${o.white.bold("Personality")}`),console.log(`    Style: ${l.style}  |  Risk: ${l.risk}  |  Verbosity: ${l.verbosity}`),console.log("");}let i=(r.expertise||[]).sort((l,g)=>g.confidence-l.confidence);if(i.length>0){console.log(`  ${o.white.bold("Expertise")} (${i.length} symbols)`),console.log(`  ${"Symbol".padEnd(30)} ${"Confidence".padEnd(12)} ${"Sessions".padEnd(10)} Last Touch`),console.log(`  ${"-".repeat(70)}`);for(let l of i.slice(0,20)){let g=`${(l.confidence*100).toFixed(0)}%`.padEnd(12),p=String(l.sessions).padEnd(10),u=l.lastTouch?l.lastTouch.split("T")[0]:"\u2014";console.log(`  ${l.symbol.padEnd(30)} ${g} ${p} ${u}`);}i.length>20&&console.log(o.gray(`  ... and ${i.length-20} more`)),console.log("");}else console.log(o.gray("  No expertise recorded. Run `paradigm agent sync` to bootstrap from lore.\n"));let d=r.transferable||[];if(d.length>0){console.log(`  ${o.white.bold("Transferable Patterns")} (${d.length})`);for(let l of d)console.log(`    ${l.id}: ${(l.successRate*100).toFixed(0)}% success \u2014 ${l.description}`),console.log(o.gray(`      Learned in: ${l.learnedIn} | Applied in: ${l.appliedIn.join(", ")||"none"}`));console.log("");}let f=Object.entries(r.contexts||{});if(f.length>0){console.log(`  ${o.white.bold("Project Contexts")} (${f.length})`);for(let[l,g]of f)console.log(`    ${o.white(l)}: ${g.sessionsInProject||0} sessions, last active ${g.lastActive?.split("T")[0]||"\u2014"}`),g.defaultModel&&console.log(`      Model: ${g.defaultModel}`),g.focus?.length&&console.log(`      Focus: ${g.focus.join(", ")}`);console.log("");}let t=r.permissions;t&&(console.log(`  ${o.white.bold("Permissions")}`),t.paths?.read?.length&&console.log(`    Read: ${t.paths.read.join(", ")}`),t.paths?.write?.length&&console.log(`    Write: ${t.paths.write.join(", ")}`),t.paths?.deny?.length&&console.log(`    Deny: ${o.red(t.paths.deny.join(", "))}`),t.tools?.allow?.length&&console.log(`    Tools allow: ${t.tools.allow.join(", ")}`),t.tools?.deny?.length&&console.log(`    Tools deny: ${o.red(t.tools.deny.join(", "))}`),t.dangerous_actions?.length&&console.log(`    Requires approval: ${t.dangerous_actions.join(", ")}`),console.log("")),n.success(`Showed agent ${e}`);}async function L(e,s={}){let c=process.cwd(),n=s.global?"global":"project",r=a$1.command("agent-create").start(`Creating agent ${e} (${n})`,{cwd:c}),i=n==="global"?h:y.join(c,S);a.existsSync(i)||a.mkdirSync(i,{recursive:true});let d=y.join(i,`${e}${$}`);if(a.existsSync(d)){console.log(o.yellow(`
-  Agent "${e}" already exists at ${d}`)),console.log(o.gray("  Use `paradigm agent show` to view.\n")),r.error("Agent already exists");return}let f=new Date().toISOString(),t=E[e]||{style:"deliberate",risk:"balanced",verbosity:"concise"},l={id:e,role:s.role||`${e.charAt(0).toUpperCase()+e.slice(1)} agent`,description:s.description||`Persistent identity for the ${e} agent role`,version:"1.0.0",personality:t,expertise:[],transferable:[],contexts:{},created:f,updated:f};if(s.denyPaths){let p=s.denyPaths.split(",").map(u=>u.trim());l.permissions={paths:{deny:p}};}let g=m.dump(l,{lineWidth:120,noRefs:true,sortKeys:false});a.writeFileSync(d,g,"utf-8"),console.log(o.green(`
-  \u2713 Created agent "${e}" at ${d}`)),console.log(o.gray("  Run `paradigm agent sync` to bootstrap expertise from lore.\n")),r.success(`Created agent ${e}`);}async function W(e,s={}){let c=process.cwd(),n=a$1.command("agent-sync").start(`Syncing expertise for ${e}`,{cwd:c}),r=y.join(c,".paradigm","lore","entries");if(!a.existsSync(r)){console.log(o.yellow(`
-  No lore directory found. Nothing to sync from.
-`)),n.error("No lore found");return}let i=w(c,e);if(!i){if(s.dryRun){console.log(o.yellow(`
-  Agent "${e}" not found. Would create with --no-dry-run.
-`)),n.success("Dry run \u2014 would create");return}let p=(a.existsSync(y.join(h,`${e}${$}`))?"global":"project")==="global"?h:y.join(c,S);a.existsSync(p)||a.mkdirSync(p,{recursive:true});let u=new Date().toISOString(),x=E[e]||{style:"deliberate",risk:"balanced",verbosity:"concise"};i={id:e,role:`${e.charAt(0).toUpperCase()+e.slice(1)} agent`,description:`Persistent identity for the ${e} agent role`,version:"1.0.0",personality:x,expertise:[],transferable:[],contexts:{},created:u,updated:u};}let d=i.expertise||[],f=0,t=new Set,l=T(r);for(let g of l)if(!(!g.symbols_touched||g.symbols_touched.length===0)){f++;for(let p of g.symbols_touched){t.add(p);let u=d.find(x=>x.symbol===p);u?(u.sessions++,u.lastTouch=g.timestamp||u.lastTouch,g.confidence!=null&&(u.confidence=.7*u.confidence+.3*g.confidence)):d.push({symbol:p,confidence:g.confidence??.5,sessions:1,lastTouch:g.timestamp||new Date().toISOString()});}}if(i.expertise=d,s.json)console.log(JSON.stringify({agentId:e,entriesProcessed:f,symbolsUpdated:t.size,dryRun:!!s.dryRun,topExpertise:d.sort((g,p)=>p.confidence-g.confidence).slice(0,10)},null,2));else if(console.log(o.blue(`
-  Syncing expertise for "${e}" from ${f} lore entries...`)),console.log(`  ${o.green("\u2713")} ${t.size} symbols updated`),console.log(`  ${o.green("\u2713")} ${f} entries processed`),d.length>0){console.log(`
-  Top expertise:`);for(let g of d.sort((p,u)=>u.confidence-p.confidence).slice(0,5))console.log(`    ${g.symbol}: ${(g.confidence*100).toFixed(0)}% (${g.sessions} sessions)`);}if(s.dryRun)s.json||console.log(o.yellow(`
-  Dry run \u2014 no changes written.
-`));else {i.updated=new Date().toISOString();let g=y.join(c,S,`${e}${$}`),p=y.join(h,`${e}${$}`),u=a.existsSync(g)?"project":"global",x=u==="global"?h:y.join(c,S);a.existsSync(x)||a.mkdirSync(x,{recursive:true});let A=u==="global"?p:g;a.writeFileSync(A,m.dump(i,{lineWidth:120,noRefs:true,sortKeys:false}),"utf-8"),s.json||console.log(o.green(`
-  \u2713 Saved to ${A}
-`));}n.success(`Synced ${t.size} symbols from ${f} entries`);}async function M(e={}){let s=process.cwd(),c=a$1.command("agent-roster").start("Agent roster",{cwd:s}),n=[];if(a.existsSync(h))for(let t of a.readdirSync(h).filter(l=>l.endsWith($)))try{let l=m.load(a.readFileSync(y.join(h,t),"utf-8"));l?.id&&n.push(l);}catch{}let r=y.join(s,S);if(a.existsSync(r))for(let t of a.readdirSync(r).filter(l=>l.endsWith($)))try{let l=m.load(a.readFileSync(y.join(r,t),"utf-8"));if(l?.id){let g=n.findIndex(p=>p.id===l.id);g>=0?n[g]=l:n.push(l);}}catch{}let i=j(s),d=i?n.filter(t=>i.includes(t.id)):n,f=i?n.filter(t=>!i.includes(t.id)):[];if(e.json){console.log(JSON.stringify({active:d.map(t=>P(t,false)),benched:f.map(t=>P(t,true))},null,2)),c.success(`${d.length} active, ${f.length} benched`);return}if(console.log(o.blue(`
-\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510`)),console.log(o.blue("\u2502")+o.white.bold("  Agent Roster                                    ")+o.blue("\u2502")),console.log(o.blue(`\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-`)),d.length>0){console.log(o.green.bold("  Active"));for(let t of d)v(t);}if(f.length>0){console.log(o.gray.bold(`
-  Benched`));for(let t of f)v(t,true);}n.length===0?console.log(o.yellow(`  No agents found.
-`)):console.log(""),c.success(`${d.length} active, ${f.length} benched`);}function v(e,s=false){let c=(e.expertise||[]).sort((t,l)=>l.confidence-t.confidence),n=c[0]?`${c[0].symbol} (${(c[0].confidence*100).toFixed(0)}%)`:o.gray("\u2014"),r=s?o.gray:o.white,i=e.nickname?` (${e.nickname})`:"",d=e.attention?.threshold,f=d!=null?` | thr: ${d.toFixed(2)}`:"";console.log(`    ${r.bold(e.id)}${o.gray(i)} \u2014 ${o.gray(e.role)}`),console.log(`      Top: ${n} | ${c.length} symbols${f}`);}function P(e,s=false){let c=(e.expertise||[]).sort((n,r)=>r.confidence-n.confidence);return {id:e.id,role:e.role,nickname:e.nickname,benched:s,expertiseCount:c.length,topExpertise:c.slice(0,3).map(n=>({symbol:n.symbol,confidence:parseFloat(n.confidence.toFixed(2))})),threshold:e.attention?.threshold}}async function U(e){let s=process.cwd(),c=a$1.command("agent-bench").start(`Benching agent ${e}`,{cwd:s}),n=w(s,e);if(!n){console.log(o.red(`
-  Agent "${e}" not found.
-`)),c.error("Not found");return}let r=j(s);r?r=r.filter(i=>i!==n.id):r=C().filter(i=>i!==n.id),F(s,r),console.log(o.yellow(`
-  Agent "${n.id}" removed from this project's roster.`)),console.log(o.gray(`  Maestro will skip this agent during orchestration. Still available globally.
-`)),c.success(`Benched ${n.id} (roster: ${r.length} active)`);}async function J(e){let s=process.cwd(),c=a$1.command("agent-activate").start(`Activating agent ${e}`,{cwd:s}),n=w(s,e);if(!n){console.log(o.red(`
-  Agent "${e}" not found.
-`)),c.error("Not found");return}let r=j(s);if(r)r.includes(n.id)||r.push(n.id);else {let i=C();r=i.includes(n.id)?i:[...i,n.id];}F(s,r),console.log(o.green(`
-  \u25B6 Agent "${n.id}" added to this project's roster.`)),console.log(o.gray(`  Maestro will include this agent in orchestration. Roster is per-project.
-`)),c.success(`Activated ${n.id} (roster: ${r.length} active)`);}function w(e,s){let c=y.join(e,S,`${s}${$}`);if(a.existsSync(c))try{return m.load(a.readFileSync(c,"utf-8"))}catch{}let n=y.join(h,`${s}${$}`);if(a.existsSync(n))try{return m.load(a.readFileSync(n,"utf-8"))}catch{}return null}function O(e){return {id:e.id,role:e.role,personality:e.personality,expertiseCount:(e.expertise||[]).length,topExpertise:(e.expertise||[]).sort((s,c)=>c.confidence-s.confidence).slice(0,3).map(s=>({symbol:s.symbol,confidence:parseFloat(s.confidence.toFixed(2))})),projectContexts:Object.keys(e.contexts||{}),transferableCount:(e.transferable||[]).length}}function T(e){let s=[];try{let c=a.readdirSync(e,{withFileTypes:!0});for(let n of c){if(!n.isDirectory())continue;let r=y.join(e,n.name);try{let i=a.readdirSync(r).filter(d=>d.endsWith(".yaml")||d.endsWith(".yml"));for(let d of i)try{let f=a.readFileSync(y.join(r,d),"utf-8"),t=m.load(f);t?.symbols_touched&&Array.isArray(t.symbols_touched)&&s.push({symbols_touched:t.symbols_touched,confidence:typeof t.confidence=="number"?t.confidence:void 0,timestamp:t.timestamp||n.name});}catch{}}catch{}}}catch{}return s}export{J as agentActivateCommand,U as agentBenchCommand,L as agentCreateCommand,_ as agentListCommand,M as agentRosterCommand,D as agentShowCommand,W as agentSyncCommand};