@a-company/paradigm 6.0.5 → 6.2.0

package/dist/university-content/notes/N-para-701-arch-mcp-tools.md

@@ -0,0 +1,149 @@
+---
+id: N-para-701-arch-mcp-tools
+title: 'Lesson 13: The arch MCP Tools'
+type: note
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+  - arch-tools
+  - mcp-tools
+symbols: []
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-para-701-atlas-agent
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## Overview
+
+Paradigm exposes two MCP tools for architectural map queries. Both are read-only and operate on `.paradigm/arch.yaml`. They are available whenever the `arch.yaml` file exists — the tool registry auto-detects the file and activates the arch tool module.
+
+The two tools are:
+- `paradigm_arch_status` — tier summary + drift report
+- `paradigm_arch_diagram` — Mermaid diagram string
+
+There is also a CLI interface with the same functionality: `paradigm arch status` and `paradigm arch diagram`.
+
+## paradigm_arch_status
+
+**Purpose:** Get a complete summary of the architectural map, including tier details and drift report.
+
+**Token cost:** ~200 tokens
+
+**Input:** No required fields. The tool reads `arch.yaml` from the project root automatically.
+
+**Output when arch.yaml exists:**
+```json
+{
+  "exists": true,
+  "version": "1.0",
+  "tierCount": 3,
+  "tiers": [
+    {
+      "id": "frontend",
+      "label": "Frontend",
+      "responsibility": "User interface and client-side logic",
+      "framework": "React",
+      "componentCount": 8,
+      "components": ["#auth-form", "#dashboard-view", "..."]
+    }
+  ],
+  "links": [
+    { "from": "frontend", "to": "backend", "via": "REST API" }
+  ],
+  "drift": {
+    "unassigned": ["#analytics-service", "#export-worker"],
+    "missing_purpose": ["#legacy-gateway"],
+    "clean": false
+  }
+}
+```
+
+**Output when arch.yaml is missing:**
+```json
+{
+  "exists": false,
+  "message": "No arch.yaml found. Create .paradigm/arch.yaml to start mapping your architecture."
+}
+```
+
+**When to call it:**
+- At the start of an architectural review session
+- After a large feature build to check for tier drift
+- When a stakeholder asks for an architecture overview
+- As part of a Context Brief when the task involves cross-tier work
+
+## paradigm_arch_diagram
+
+**Purpose:** Render the architectural map as a Mermaid diagram string.
+
+**Token cost:** ~150 tokens
+
+**Input:** Optional `format` field (only `"mermaid"` is supported; default: `"mermaid"`).
+
+**Output when arch.yaml exists:**
+```json
+{
+  "format": "mermaid",
+  "diagram": "graph TD\n  frontend[\"Frontend\\n(User interface)\"]\n  backend[\"Backend\\n(Business logic)\"]\n  database[\"Database\\n(Persistence)\"]\n  frontend -->|\"REST API\"| backend\n  backend -->|\"Prisma ORM\"| database"
+}
+```
+
+**Output when arch.yaml is missing:**
+```json
+{
+  "error": "No arch.yaml found. Cannot render diagram."
+}
+```
+
+**When to call it:**
+- To generate a diagram for inclusion in a pull request description
+- When onboarding a new team member who needs a visual of the system
+- When preparing architecture documentation
+- After adding new tiers or links to verify the diagram renders correctly
+
+## Choosing the Right Tool
+
+| Goal | Tool to Use |
+|---|---|
+| "How many tiers do we have, and what are they?" | `paradigm_arch_status` |
+| "Which new components are not yet in a tier?" | `paradigm_arch_status` → check `drift.unassigned` |
+| "Which components in arch.yaml no longer exist?" | `paradigm_arch_status` → check `drift.missing_purpose` |
+| "Generate a diagram I can paste into Confluence" | `paradigm_arch_diagram` |
+| "Is the architecture clean (no drift)?" | `paradigm_arch_status` → check `drift.clean` |
+
+Call `paradigm_arch_status` first in any architectural session. Call `paradigm_arch_diagram` when you need a visual. There is no need to call both unless you want both the summary data and the diagram string.
+
+## The CLI Interface
+
+The same functionality is available from the terminal:
+
+```bash
+# Show tier summary (default subcommand)
+paradigm arch status
+paradigm arch          # same as above
+
+# Output as JSON for scripting
+paradigm arch status --json
+
+# Print Mermaid diagram to stdout
+paradigm arch diagram
+paradigm arch diagram | pbcopy   # macOS: copy to clipboard
+```
+
+The CLI is useful for quick checks, for integrating into CI scripts that report on architectural health, and for generating diagrams in automated documentation workflows.
+
+## Tool Detection
+
+Both tools are registered in the `feature` tier of the MCP tool registry. They activate automatically when `.paradigm/arch.yaml` exists in the project root. If the file does not exist, the tools are not listed in the tool registry and do not consume token budget in tool-list payloads.
+
+This means:
+- Projects without `arch.yaml` will never see arch tools in their tool list
+- Projects with `arch.yaml` always have both tools available without any configuration
+- Creating `arch.yaml` is the only setup required to activate Atlas's full toolset

package/dist/university-content/notes/N-para-701-arch-yaml-format.md

@@ -0,0 +1,123 @@
+---
+id: N-para-701-arch-yaml-format
+title: 'Lesson 11: The arch.yaml Format'
+type: note
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+  - arch-yaml
+  - architectural-map
+symbols: []
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-para-701-agent-roster
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## What Is arch.yaml?
+
+The file `.paradigm/arch.yaml` is an optional architectural layer map. When it exists, Paradigm knows the intended tier structure of a project — which components belong to which layer, what each layer is responsible for, and how layers connect to each other. It is the source of truth for macro-level architecture.
+
+The file is optional. Projects without it still work — symbol indexing, orchestration, and all other Paradigm features function normally. You create `arch.yaml` when you want to:
+
+- Document the intended architectural layers of a project (frontend, backend, database, infrastructure)
+- Detect drift between declared architecture and the live symbol index
+- Render architecture diagrams for onboarding or architectural review
+- Give Atlas (the cartographer agent) a map to audit against
+
+## The Schema
+
+```yaml
+version: '1.0'
+
+tiers:
+  - id: frontend
+    label: Frontend
+    responsibility: User interface and client-side logic
+    tech:
+      framework: React
+      libraries:
+        - zustand
+        - react-query
+    components:
+      - '#auth-form'
+      - '#dashboard-view'
+      - '#settings-panel'
+
+  - id: backend
+    label: Backend
+    responsibility: Business logic and API layer
+    tech:
+      framework: Express
+      libraries:
+        - zod
+        - prisma
+    components:
+      - '#auth-middleware'
+      - '#user-service'
+      - '#billing-service'
+
+  - id: database
+    label: Database
+    responsibility: Persistence and data access
+    tech:
+      framework: PostgreSQL
+      libraries:
+        - prisma
+    components:
+      - '#user-schema'
+      - '#billing-schema'
+
+links:
+  - from: frontend
+    to: backend
+    via: REST API
+  - from: backend
+    to: database
+    via: Prisma ORM
+```
+
+## Fields Reference
+
+**version** (required) — Schema version string. Use `'1.0'`.
+
+**tiers** (required) — Array of architectural tiers. Each tier has:
+
+- `id` (required) — Machine-readable identifier. Use kebab-case. Referenced by `links`.
+- `label` (required) — Human-readable name shown in diagrams and summaries.
+- `responsibility` (required) — One sentence describing what this tier owns.
+- `tech` (optional) — Technology stack for this tier. `framework` is the primary runtime; `libraries` is a list of key dependencies.
+- `components` (required) — List of Paradigm symbol IDs (prefixed with `#`) that belong to this tier.
+
+**links** (required, can be empty array `[]`) — Array of directed edges between tiers. Each link has:
+
+- `from` (required) — Tier ID of the caller or dependent.
+- `to` (required) — Tier ID of the callee or dependency.
+- `via` (optional) — Human-readable label for the connection (e.g., "REST API", "message queue", "gRPC"). Renders as an edge label in Mermaid diagrams.
+
+## When to Create arch.yaml
+
+Create `.paradigm/arch.yaml` when:
+
+1. **Onboarding new team members** — a written tier map removes ambiguity about which code belongs where
+2. **Planning a large refactor** — declaring the target architecture before refactoring makes drift detectable
+3. **Architectural review** — stakeholders can read the YAML or view the rendered Mermaid diagram
+4. **Drift detection** — once declared, Atlas can flag components that appear in the symbol index but are not assigned to any tier (unassigned), or components declared in a tier but not present in the index (missing_purpose)
+
+You do NOT need `arch.yaml` for orchestration, symbol tracking, gate checking, or any other Paradigm feature. It is purely additive metadata.
+
+## Drift Detection
+
+Atlas computes two drift categories by comparing `arch.yaml` to the live symbol index:
+
+**Unassigned** — Component symbols in the index that are not listed in any tier's `components` array. These components exist and are documented, but the architectural map has not categorized them. Common cause: new components added after the arch.yaml was last updated.
+
+**Missing Purpose** — Component IDs listed in a tier's `components` array that do not appear in the symbol index. These components were planned or once existed, but are no longer indexed. Common cause: renamed or deleted components whose arch.yaml entry was not updated.
+
+Neither drift category blocks the build. Atlas reports them as advisory findings so the team can update the map at their own pace.

package/dist/university-content/notes/N-para-701-atlas-agent.md

@@ -0,0 +1,83 @@
+---
+id: N-para-701-atlas-agent
+title: 'Lesson 12: Atlas — The Cartographer Agent'
+type: note
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+  - atlas
+  - cartographer
+symbols: []
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-para-701-arch-yaml-format
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## Who Is Atlas?
+
+Atlas is the Cartographer agent — archetype ID `cartographer`. He is agent #67 in the Paradigm roster, a tier-1 specialist whose single responsibility is architectural mapping. When a project has a `.paradigm/arch.yaml`, Atlas reads it, computes drift against the live symbol index, and renders diagrams. He does not implement code, does not write .purpose files, and does not block builds.
+
+Atlas is advisory-only. His job is to make architectural drift visible, not to enforce it. The team decides when and how to resolve drift.
+
+## Atlas's Personality
+
+Atlas is **methodical** and **conservative**. He does not take risks with interpretation — if arch.yaml is ambiguous, he reports what he found rather than guessing intent. His verbosity is **concise**: tier summaries, a drift count, and the Mermaid diagram string. He does not produce lengthy analysis.
+
+Model tier: **tier-1 (opus)**. Architectural reasoning requires deep understanding of symbol relationships and the ability to explain drift in context. Atlas earns his tier-1 slot by analyzing not just whether drift exists, but what it means for the project.
+
+## When Atlas Fires
+
+Atlas is triggered at two points in the orchestration lifecycle:
+
+**After the Builder stage** — When the Builder completes implementation, Atlas checks whether new components introduced by the build have been assigned to a tier. If the project has `arch.yaml`, Atlas runs automatically as part of the post-build review pipeline and surfaces unassigned components before the Documentor runs.
+
+**On-demand** — Any time the user or another agent calls `paradigm_arch_status` or `paradigm_arch_diagram`, Atlas fires. This is the most common path: an engineer asks for an architecture overview at the start of a planning session, or requests a diagram for a pull request description.
+
+Atlas does **not** fire on every tool call. His attention threshold is low (0.35) because architectural drift is cheap to report and expensive to accumulate silently. His attention patterns match `#*` symbols and the `.paradigm/arch.yaml` path.
+
+## Atlas vs. Documentor
+
+Both Atlas and the Documentor run after builders complete. They have different responsibilities:
+
+| Dimension | Atlas (Cartographer) | Documentor |
+|---|---|---|
+| What it reads | `.paradigm/arch.yaml`, symbol index | Source files, existing .purpose files |
+| What it writes | Nothing | `.purpose` files, `portal.yaml` |
+| What it reports | Architectural drift (tier-level) | Coverage gaps (symbol-level) |
+| Blocking? | Never | Never (advisory) |
+| Tier | 1 (opus) | 3 (haiku) |
+
+The Documentor works at symbol granularity — "this directory has no .purpose file" or "this component is missing its description." Atlas works at tier granularity — "these 8 components were added but have not been assigned to any architectural layer."
+
+They complement each other: the Documentor ensures every symbol is documented, Atlas ensures documented symbols are architecturally located.
+
+## What Atlas Never Does
+
+Atlas has strict constraints encoded in his agent profile:
+
+- **Never blocks a build** — drift is informational. A project can ship with unassigned components.
+- **Never writes source code** — he is read-only on `src/**`.
+- **Never modifies .purpose files** — that is the Documentor's job.
+- **Never modifies portal.yaml** — that is Aegis's domain.
+- **Never modifies arch.yaml directly** — he reads it and reports on it. A human or the architect agent updates the map.
+
+These constraints are deliberate. An advisory agent that occasionally blocks builds would undermine trust. Atlas stays in his lane so the team can rely on his reports without worrying about side effects.
+
+## Resolving Drift
+
+When Atlas reports drift, the team has three options:
+
+1. **Update arch.yaml** — add unassigned components to the correct tier, remove missing_purpose entries for deleted components. This is the most common resolution.
+
+2. **Ignore it** — Atlas does not block. If a component is intentionally unclassified (e.g., a utility shared across tiers), the team can leave it unassigned.
+
+3. **Create arch.yaml entries for new tiers** — if new components don't fit existing tiers, the architect may declare a new tier. Atlas will then show the new tier in future runs.
+
+Resolution is a human decision. Atlas surfaces the information; the architect makes the call.

package/dist/university-content/paths/.purpose

@@ -0,0 +1,12 @@
+# Auto-generated .purpose stub — created by Cid (captain debrief)
+# Delegate to Scribe (Documentor) for rich documentation
+name: paths
+description: "TODO: describe what this directory/module does"
+context:
+  - "Stub created by Cid during coverage audit — update with real context"
+# Key files touched:
+# - LP-para-701.yaml
+components:
+  paths:
+    description: "TODO: describe this component"
+    tags: []

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

@@ -62,3 +62,18 @@ steps:
   - content: Q-para-701-agent-pods-nevrland
     required: true
     passRequired: true
+  - content: N-para-701-arch-yaml-format
+    required: true
+  - content: Q-para-701-arch-yaml-format
+    required: true
+    passRequired: true
+  - content: N-para-701-atlas-agent
+    required: true
+  - content: Q-para-701-atlas-agent
+    required: true
+    passRequired: true
+  - content: N-para-701-arch-mcp-tools
+    required: true
+  - content: Q-para-701-arch-mcp-tools
+    required: true
+    passRequired: true

package/dist/university-content/quizzes/.purpose

@@ -0,0 +1,14 @@
+# Auto-generated .purpose stub — created by Cid (captain debrief)
+# Delegate to Scribe (Documentor) for rich documentation
+name: quizzes
+description: "TODO: describe what this directory/module does"
+context:
+  - "Stub created by Cid during coverage audit — update with real context"
+# Key files touched:
+# - Q-para-701-arch-yaml-format.yaml
+# - Q-para-701-atlas-agent.yaml
+# - Q-para-701-arch-mcp-tools.yaml
+components:
+  quizzes:
+    description: "TODO: describe this component"
+    tags: []

package/dist/university-content/quizzes/Q-para-701-arch-mcp-tools.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-arch-mcp-tools
+title: 'PARA 701: Agent Mastery — Lesson 13: The arch MCP Tools'
+description: 'Quiz for lesson: Lesson 13: The arch MCP Tools'
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: intermediate
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A developer wants to know which newly-added components are not yet assigned to any architectural tier. Which tool should they call, and which field in the response answers the question?
+    choices:
+      A: paradigm_arch_diagram — the diagram visually shows unassigned nodes
+      B: paradigm_arch_status — check drift.unassigned for component symbols that exist in the index but are not in any tier
+      C: paradigm_status — it includes drift information in the main status response
+      D: paradigm_arch_status — check drift.missing_purpose for components not in any tier
+      E: paradigm_search — search for components with type "unassigned"
+    correct: B
+    explanation: paradigm_arch_status returns a drift object with two arrays. drift.unassigned contains component symbols that are indexed (documented) but not listed in any tier's components array — these are the newly-added components with no tier assignment. drift.missing_purpose is the inverse: components declared in arch.yaml that do not appear in the index. paradigm_arch_diagram renders the declared tiers but does not show drift; paradigm_status does not include arch.yaml drift.
+  - id: q2
+    question: A project does not have a `.paradigm/arch.yaml` file. A developer calls `paradigm_arch_status`. What happens?
+    choices:
+      A: The tool throws an error and the MCP session crashes
+      B: The tool returns a JSON object with exists=false and a message explaining that arch.yaml was not found, with guidance on how to create it
+      C: The tool is not listed in the tool registry at all — it cannot be called on projects without arch.yaml
+      D: The tool returns an empty tier list with zero drift
+      E: The tool automatically creates a minimal arch.yaml and returns its contents
+    correct: B
+    explanation: "The tool handles the missing-file case gracefully: it returns {\"exists\": false, \"message\": \"No arch.yaml found. Create .paradigm/arch.yaml to start mapping your architecture.\"}. However, the tool detection note adds nuance: the arch module registers with a `detect` function that checks for arch.yaml. If the file doesn't exist, the tools are not included in the tool list. A developer who calls the tool directly (knowing its name) after the file was deleted would get the graceful JSON response. The session does not crash either way."
+  - id: q3
+    question: An engineer wants to generate a Mermaid diagram to paste into a pull request description. Which of the following is the correct approach?
+    choices:
+      A: Call paradigm_arch_status and extract the diagram field from the response
+      B: Call paradigm_arch_diagram — it returns a JSON object with a `diagram` field containing the Mermaid graph string, or use `paradigm arch diagram` from the CLI
+      C: Call paradigm_arch_status with format="mermaid" to get the diagram
+      D: Manually write the Mermaid diagram by reading arch.yaml — the tools do not generate diagrams
+      E: Call paradigm_arch_diagram with output="clipboard" to copy it automatically
+    correct: B
+    explanation: "paradigm_arch_diagram is the dedicated diagram tool. It returns {\"format\": \"mermaid\", \"diagram\": \"graph TD\\n  ...\"} where the diagram field is the Mermaid string ready for copy-paste. The CLI equivalent is `paradigm arch diagram` — on macOS, piping to `pbcopy` copies it to the clipboard. paradigm_arch_status does not include a diagram field; it focuses on tier metadata and drift. There is no `format` parameter on paradigm_arch_status."
+  - id: q4
+    question: A project has `.paradigm/arch.yaml`. An agent calls `paradigm_arch_status` and receives `drift.clean: false` with `drift.unassigned` containing 5 symbols and `drift.missing_purpose` containing 2 symbols. What is the correct interpretation?
+    choices:
+      A: The build is blocked — drift.clean must be true before deployment
+      B: 5 components are in the index but not assigned to any tier; 2 components are declared in arch.yaml tiers but do not appear in the index. Neither condition blocks anything — this is advisory information.
+      C: 5 components have no .purpose files; 2 components have missing portal.yaml gate declarations
+      D: The arch.yaml file has 5 syntax errors and 2 missing required fields
+      E: drift.clean: false means the previous build introduced breaking changes
+    correct: B
+    explanation: "drift.clean: false means at least one drift category is non-empty. drift.unassigned (5 items) means 5 component symbols exist in the symbol index but have no tier assignment in arch.yaml — likely new components added after arch.yaml was last updated. drift.missing_purpose (2 items) means 2 component IDs in arch.yaml tiers cannot be found in the index — likely renamed or deleted components. Neither is a blocker. Atlas reports this information so the team can decide whether to update arch.yaml."
+  - id: q5
+    question: Why are the arch tools registered in the `feature` tier of the MCP registry rather than the `core` tier?
+    choices:
+      A: Feature-tier tools cost fewer tokens to list than core-tier tools
+      B: Feature-tier tools are auto-detected — the arch module uses a `detect` function that checks for arch.yaml. If the file doesn't exist, the tools are not listed, saving token budget for projects that don't use architectural mapping
+      C: Feature-tier tools require manual activation via paradigm_tool_activate before they can be called
+      D: Core-tier tools are reserved for Anthropic-approved tools only
+      E: The arch tools are in the feature tier because they were added after the core tier was finalized
+    correct: B
+    explanation: The feature tier supports auto-detection via a `detect` function. For arch tools, detect checks whether `.paradigm/arch.yaml` exists. If it does, both arch tools are included in the tool list. If not, they are omitted entirely. This keeps the tool list lean for projects that have not declared an architectural map. Advanced-tier tools require manual `paradigm_tool_activate` to load; feature-tier tools are automatic based on detection. Core-tier tools are always loaded regardless of project state.

package/dist/university-content/quizzes/Q-para-701-arch-yaml-format.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-arch-yaml-format
+title: 'PARA 701: Agent Mastery — Lesson 11: The arch.yaml Format'
+description: 'Quiz for lesson: Lesson 11: The arch.yaml Format'
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: intermediate
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A team adds a new component `#notification-service` to the backend. Their `.paradigm/arch.yaml` was last updated six months ago and does not list this component in any tier. When Atlas runs, how will this component appear in the drift report?
+    choices:
+      A: As a "missing_purpose" entry — the component is listed in arch.yaml but not in the index
+      B: As an "unassigned" entry — the component exists in the symbol index but is not assigned to any tier
+      C: Atlas will not report it because arch.yaml does not need to be updated
+      D: Atlas will automatically add it to the backend tier
+      E: The drift report only includes gate symbols, not components
+    correct: B
+    explanation: "Unassigned drift means: component exists in the symbol index but is not listed in any tier's components array. The component was indexed (via .purpose coverage) but arch.yaml was not updated to include it. Missing_purpose is the inverse: declared in arch.yaml but not found in the index. Atlas never auto-assigns components — it reports drift as advisory findings for the team to resolve."
+  - id: q2
+    question: Which of the following arch.yaml configurations is valid?
+    choices:
+      A: A tier with no `id` field but a `label` field
+      B: A `links` array with an entry that has `from` and `to` pointing to tier IDs, and an optional `via` label
+      C: A `components` array containing `$checkout-flow` (a flow symbol)
+      D: Omitting the `links` key entirely from the file
+      E: Using camelCase for tier IDs (e.g., `id: frontEnd`)
+    correct: B
+    explanation: "Links require `from` and `to` (both referencing tier IDs) and accept an optional `via` label for edge labeling in Mermaid diagrams. Tier `id` is required — a label alone is not sufficient. The `components` array holds `#component` symbols only, not `$flows`. The `links` key is required (though it can be an empty array `[]`). Tier IDs should use kebab-case per Paradigm conventions."
+  - id: q3
+    question: A startup is three months into development. They have 40 components, 6 flows, and 12 gates indexed by Paradigm. Should they create `.paradigm/arch.yaml`?
+    choices:
+      A: Yes — arch.yaml is required for gate checking to work
+      B: Yes — without it, the symbol index will not build
+      C: No — arch.yaml is required only for projects with more than 100 components
+      D: It depends — arch.yaml is optional additive metadata. They should create it if they want tier-level architecture documentation, drift detection, or diagrams. It is not required for any core Paradigm feature.
+      E: No — arch.yaml is only for enterprise projects
+    correct: D
+    explanation: "arch.yaml is entirely optional. All core Paradigm features — orchestration, symbol indexing, gate checking, notebook learning, lore recording — work without it. The file is additive metadata that enables tier-level documentation, drift detection via Atlas, and Mermaid diagram rendering. A three-month project with 40 components may benefit from declaring their tier structure, but there is no requirement to do so."
+  - id: q4
+    question: A project's arch.yaml declares `#legacy-payment-gateway` in the backend tier. Six months later, the team deprecated and deleted that component. What drift will Atlas report?
+    choices:
+      A: Unassigned — the component was removed from the index
+      B: Missing Purpose — the component is listed in arch.yaml but no longer exists in the symbol index
+      C: No drift — deleted components are automatically removed from arch.yaml
+      D: Critical error — Atlas will block the build
+      E: Unassigned and Missing Purpose simultaneously
+    correct: B
+    explanation: "Missing Purpose drift means: a component is declared in a tier's components array in arch.yaml, but it cannot be found in the live symbol index. When a component is deleted (its .purpose entry removed and paradigm scan run), it disappears from the index. The arch.yaml entry remains until manually updated. Atlas reports this as missing_purpose so the team knows the map is stale. Atlas never blocks — it is advisory-only."
+  - id: q5
+    question: What does the `via` field on a link do?
+    choices:
+      A: It declares which gate must be satisfied when crossing from one tier to another
+      B: It specifies the network protocol (HTTP, gRPC, WebSocket) for rate-limiting purposes
+      C: It provides a human-readable edge label that appears in the Mermaid diagram output
+      D: It is required for all links — omitting it causes a parse error
+      E: It declares the intermediate tier a message passes through before reaching the destination
+    correct: C
+    explanation: "The `via` field is an optional human-readable label placed on the edge between two tiers in the generated Mermaid diagram. For example, `via: REST API` renders as `frontend -->|\"REST API\"| backend` in Mermaid syntax. It has no functional effect on orchestration, gate checking, or drift detection — it is purely for diagram readability. Omitting it is valid; the edge renders without a label."

package/dist/university-content/quizzes/Q-para-701-atlas-agent.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-atlas-agent
+title: 'PARA 701: Agent Mastery — Lesson 12: Atlas — The Cartographer Agent'
+description: 'Quiz for lesson: Lesson 12: Atlas — The Cartographer Agent'
+author: paradigm
+created: '2026-04-28'
+updated: '2026-04-28'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: intermediate
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A Builder agent has just completed implementing a new `#analytics-service` component. The project has a `.paradigm/arch.yaml` with three declared tiers. In the standard orchestration pipeline, when does Atlas run relative to the Documentor?
+    choices:
+      A: Atlas runs before the Builder, to predict what components will be created
+      B: Atlas and the Documentor run simultaneously in parallel
+      C: Atlas runs after the Builder stage and before (or alongside) the Documentor — he surfaces unassigned components from the new build before the Documentor writes .purpose updates
+      D: Atlas only runs when explicitly called by the user — he never fires automatically in orchestration
+      E: Atlas runs after the Documentor, so he can use the updated .purpose files as input
+    correct: C
+    explanation: Atlas fires after the Builder completes and before (or alongside) the Documentor in the post-build review pipeline. When arch.yaml exists, Atlas checks whether the newly built components have been assigned to tiers. The Documentor focuses on .purpose coverage. Both are post-Builder agents, but Atlas surfaces tier-level drift while the Documentor handles symbol-level gaps. Running Atlas before the Documentor ensures architectural drift is visible before .purpose work begins.
+  - id: q2
+    question: Why is Atlas a tier-1 (opus) agent rather than a tier-3 (haiku) agent?
+    choices:
+      A: Tier-1 means Atlas runs first in every orchestration, not that he uses a more capable model
+      B: Atlas is tier-1 because architectural reasoning — explaining what drift means and how to resolve it in context — requires deep understanding of symbol relationships, which benefits from a more capable model
+      C: All agents that deal with YAML files are tier-1 by convention
+      D: Atlas was assigned tier-1 because cartography is a premium feature
+      E: Atlas is tier-1 because he has write access to source files
+    correct: B
+    explanation: Tier assignment reflects the cognitive complexity of the agent's work. Tier-1 (opus) is for decision-makers and agents whose reasoning depth directly affects output quality. Atlas earns tier-1 because his value is not in parsing YAML (any model can do that), but in explaining what architectural drift means in the context of a specific project — why certain components ended up unassigned, what that implies for the team, and how to prioritize resolution. Shallow analysis here produces misleading or useless drift reports.
+  - id: q3
+    question: A project's arch.yaml has 5 tiers. Atlas reports 12 unassigned components after a large feature build. What should the team do?
+    choices:
+      A: Immediately fix the build — Atlas's report means the deployment pipeline is blocked
+      B: Ignore the report permanently — Atlas only reports cosmetic information
+      C: Evaluate the drift at their own pace — they can update arch.yaml to assign components to tiers, leave genuinely cross-cutting utilities unassigned, or declare a new tier if the build introduced a distinct new layer
+      D: Ask Atlas to automatically assign the components to the most likely tier
+      E: Delete arch.yaml to stop Atlas from running
+    correct: C
+    explanation: "Atlas is advisory-only — he never blocks. The team has three valid paths: (1) update arch.yaml to assign components to the correct tiers, (2) intentionally leave cross-cutting utilities unassigned if they genuinely don't belong to one tier, or (3) declare a new tier if the 12 new components represent a distinct architectural layer. The architect typically drives this decision. Atlas surfaces the information; humans make the call."
+  - id: q4
+    question: What is the key distinction between what Atlas reports and what the Documentor reports?
+    choices:
+      A: Atlas reports security drift; the Documentor reports performance drift
+      B: Atlas reports tier-level architectural drift (which components are unassigned to tiers or stale in the map), while the Documentor reports symbol-level coverage gaps (missing .purpose files, undocumented components)
+      C: Atlas and the Documentor report the same information from different perspectives
+      D: Atlas reports drift in portal.yaml; the Documentor reports drift in arch.yaml
+      E: Atlas reports on test coverage; the Documentor reports on code comments
+    correct: B
+    explanation: "Atlas and the Documentor operate at different granularities. Atlas works at tier granularity: given the architectural map, which components lack a tier assignment? Which declared components no longer exist? The Documentor works at symbol granularity: which directories lack a .purpose file? Which components have no description? They complement each other — the Documentor ensures symbols are documented, Atlas ensures documented symbols are architecturally located."
+  - id: q5
+    question: A developer asks Atlas to update `.paradigm/arch.yaml` to add the three new components he just built. What will Atlas do?
+    choices:
+      A: Atlas will update arch.yaml immediately — this is his primary function
+      B: Atlas will ask for confirmation before writing to arch.yaml
+      C: Atlas will decline — he is read-only on arch.yaml. He reports drift but never modifies the map. The developer or architect must update arch.yaml manually.
+      D: Atlas will delegate the update to the Documentor
+      E: Atlas will update arch.yaml only if the developer has the `^architect` gate
+    correct: C
+    explanation: Atlas never modifies arch.yaml. His agent profile restricts write access on all source files, .purpose files, portal.yaml, and arch.yaml itself. He is read-only. The design is intentional — an advisory agent that modifies files would create side effects that undermine trust. The developer or architect updates arch.yaml; Atlas reports on what he finds.