@trohde/earos 1.3.2 → 1.5.0

package/README.md

@@ -29,21 +29,18 @@ Override download URLs with environment variables if needed:
 
 ## What `earos init` Creates
 
-```
-my-architecture/
-├── core/                    Core meta-rubric (universal foundation, 9 dimensions)
-├── profiles/                Artifact-specific profiles (5 bundled: solution-architecture,
-│                            reference-architecture, adr, capability-map, roadmap)
-├── overlays/                Cross-cutting overlays (3 bundled: security, data-governance,
-│                            regulatory)
-├── standard/schemas/        JSON schemas for rubrics, evaluations, and artifacts
-├── templates/               Blank scaffolds for new profiles and evaluations
-├── evaluations/             Your evaluation records go here
-├── calibration/             Calibration artifacts and results
-├── .agents/skills/          10 EaROS skills for any AI coding agent
-├── earos.manifest.yaml      Single source of truth — inventory of all rubric files
-└── AGENTS.md                Project guide for AI agents (agent-agnostic)
-```
+| Path | Purpose |
+|------|---------|
+| `core/` | Core meta-rubric — universal foundation, 9 dimensions |
+| `profiles/` | Artifact-specific profiles (5 bundled: solution-architecture, reference-architecture, adr, capability-map, roadmap) |
+| `overlays/` | Cross-cutting overlays (3 bundled: security, data-governance, regulatory) |
+| `standard/schemas/` | JSON schemas for rubrics, evaluations, and artifacts |
+| `templates/` | Blank scaffolds for new profiles and evaluations |
+| `evaluations/` | Your evaluation records go here |
+| `calibration/` | Calibration artifacts and results |
+| `.agents/skills/` | 10 EaROS skills for any AI coding agent |
+| `earos.manifest.yaml` | Single source of truth — inventory of all rubric files |
+| `AGENTS.md` | Project guide for AI agents (agent-agnostic) |
 
 The workspace is **agent-agnostic** — the `.agents/skills/` directory works with any AI coding agent that reads skill files (Claude Code, Cursor, Copilot Workspace, and others).
 
@@ -116,19 +113,7 @@ See the [EaROS repository](https://github.com/ThomasRohde/EAROS) for full skill
 
 EaROS uses a **three-layer model**:
 
-```
-┌─────────────────────────────────────────────────────┐
-│  OVERLAYS  — cross-cutting concerns                 │
-│  security · data-governance · regulatory            │
-├─────────────────────────────────────────────────────┤
-│  PROFILES  — artifact-specific extensions           │
-│  solution-architecture · reference-architecture     │
-│  adr · capability-map · roadmap                     │
-├─────────────────────────────────────────────────────┤
-│  CORE  — universal foundation (always applied)      │
-│  9 dimensions · 10 criteria                         │
-└─────────────────────────────────────────────────────┘
-```
+![EaROS three-layer model](https://thomasrohde.github.io/EAROS/diagrams/earos-layers.svg)
 
 **Scoring** uses a 0–4 ordinal scale (0 = Absent → 4 = Strong) with explicit gate types that prevent weak scores from being hidden by weighted averages:
 

package/assets/init/.agents/skills/earos-assess/SKILL.md

@@ -91,6 +91,7 @@ For each criterion:
 Minimum output per criterion:
 ```
 criterion_id: [ID]
+criterion_question: "[full question text from the rubric]"
 score: [0-4 or N/A]
 evidence_class: [observed/inferred/external/none]
 confidence: [high/medium/low]

package/assets/init/.agents/skills/earos-assess/references/output-templates.md

@@ -55,12 +55,14 @@ overall_score: [weighted average to 1 decimal place — e.g. 2.8]
 
 gate_failures:
   - criterion_id: [ID]
+    criterion_question: "[full question text from the rubric]"
     severity: [critical | major]
     effect: [what the gate failure causes]
 # If no gate failures: gate_failures: []
 
 criterion_results:
   - criterion_id: [ID]
+    criterion_question: "[full question text from the rubric]"
     # Use IDs from the rubric YAML, e.g. STK-01, SCP-01, TRC-01
     score: [0 | 1 | 2 | 3 | 4 | "N/A"]
     evidence_class: [observed | inferred | external]

package/assets/init/.agents/skills/earos-report/references/portfolio-template.md

@@ -72,9 +72,9 @@ Use this template when generating a report covering 2 or more EAROS evaluation r
 
 [If gate failures present:]
 
-| Criterion | Gate Severity | Artifacts Failed | Failure Rate | Status Effect |
-|-----------|--------------|-----------------|-------------|---------------|
-| [ID] | [critical/major] | [N] ([list artifact names]) | [%] | [reject/cap at conditional_pass] |
+| Criterion | Name | Gate Severity | Artifacts Failed | Failure Rate | Status Effect |
+|-----------|------|--------------|-----------------|-------------|---------------|
+| [ID] | [criterion question] | [critical/major] | [N] ([list artifact names]) | [%] | [reject/cap at conditional_pass] |
 | ... | | | | |
 
 **Systemic gate failures** (criterion failing in ≥30% of artifacts):
@@ -161,9 +161,9 @@ Use this template when generating a report covering 2 or more EAROS evaluation r
 
 *Score distribution across all artifacts by criterion.*
 
-| Criterion | Avg | [Art 1] | [Art 2] | [Art 3] | ... |
-|-----------|-----|---------|---------|---------|-----|
-| [ID] | [avg] | [score] | [score] | [score] | |
+| Criterion | Name | Avg | [Art 1] | [Art 2] | [Art 3] | ... |
+|-----------|------|-----|---------|---------|---------|-----|
+| [ID] | [criterion question] | [avg] | [score] | [score] | [score] | |
 | ... | | | | | |
 
 **Colour key:** 🟢 Score ≥3 | 🟡 Score 2 | 🟠 Score 1 | 🔴 Score 0 | — N/A

package/assets/init/.agents/skills/earos-report/references/single-artifact-template.md

@@ -96,9 +96,9 @@ Actions are ordered by priority. Gate-related actions must be addressed before r
 
 ## Detailed Criterion Results
 
-| Criterion | Dimension | Score | Conf. | Evidence Class | N/A Reason |
-|-----------|-----------|-------|-------|---------------|------------|
-| [ID] | [dim] | [0-4/N/A] | [H/M/L] | [obs/inf/ext] | [if N/A: reason] |
+| Criterion | Name | Dimension | Score | Conf. | Evidence Class | N/A Reason |
+|-----------|------|-----------|-------|-------|---------------|------------|
+| [ID] | [criterion question] | [dim] | [0-4/N/A] | [H/M/L] | [obs/inf/ext] | [if N/A: reason] |
 | ... | | | | | |
 
 ---

package/assets/init/docs/getting-started.md

@@ -32,6 +32,8 @@ If your artifact does not match any profile, apply only the core rubric. The cor
 
 ## Step 2: Select Your Rubric Set
 
+![Rubric composition model](https://thomasrohde.github.io/EAROS/diagrams/rubric-composition.svg)
+
 Every assessment starts with the core and adds a profile, plus any applicable overlays.
 
 **Minimum (core only):**
@@ -110,6 +112,8 @@ Gate criteria represent non-negotiable minimums on their respective concern. A c
 
 ## Step 7: Determine the Status
 
+![Status determination decision tree](https://thomasrohde.github.io/EAROS/diagrams/status-determination.svg)
+
 The scoring sheet calculates the weighted dimension average automatically. Read the status from the aggregation tab:
 
 | Weighted Average | Status |

package/assets/init/docs/onboarding/agent-assisted.md

@@ -12,6 +12,8 @@ At Level 3, human reviewers follow the RULERS protocol with calibrated judgment.
 
 Agent evaluations follow an 8-step directed acyclic graph (DAG). Each step must complete before the next begins. No steps may be skipped.
 
+![8-step DAG evaluation flow](https://thomasrohde.github.io/EAROS/diagrams/dag-evaluation-flow.svg)
+
 ### The 8-Step DAG Evaluation Flow
 
 **Step 1 — Structural Validation.** The agent confirms the artifact conforms to its declared type. Does it have the expected sections? Is it machine-readable or does it require OCR? Can the agent identify the artifact's scope and purpose?

package/assets/init/docs/onboarding/first-assessment.md

@@ -110,6 +110,8 @@ In the core rubric, two criteria have **critical** gates: **SCP-01** (Scope and
 
 ## Interpreting Your Results
 
+![Status determination decision tree](https://thomasrohde.github.io/EAROS/diagrams/status-determination.svg)
+
 After scoring all criteria and checking gates, compute the weighted average across dimensions and apply the status thresholds:
 
 | Status | Threshold |

package/assets/init/docs/onboarding/governed-review.md

@@ -77,6 +77,8 @@ Observed evidence is always preferred. If you find yourself relying heavily on i
 
 ## The Three Evaluation Types
 
+![Three evaluation lenses](https://thomasrohde.github.io/EAROS/diagrams/evaluation-lenses.svg)
+
 EAROS distinguishes three distinct judgment types that should not be collapsed into a single opaque score:
 
 | Type | Question It Answers | Example |

package/assets/init/docs/onboarding/overview.md

@@ -15,6 +15,8 @@ EAROS applies these lessons to a specific domain: architecture artifact evaluati
 
 ## The Five Levels
 
+![EaROS maturity levels](https://thomasrohde.github.io/EAROS/diagrams/maturity-levels.svg)
+
 ### Level 1 — Ad Hoc
 
 No formal review process. Evaluation quality depends entirely on who happens to review the artifact. Different reviewers apply different mental models, and feedback is inconsistent and unreproducible.

package/assets/init/docs/plans/2026-03-23-003-feat-excalidraw-diagrams-for-site-docs-plan.md

@@ -0,0 +1,144 @@
+---
+title: "Add Excalidraw diagrams to site documentation"
+type: feat
+status: tier1-complete
+date: 2026-03-23
+---
+
+# Add Excalidraw diagrams to site documentation
+
+## Overview
+
+The EaROS documentation site renders markdown content on GitHub Pages. Several key concepts — evaluation flows, rubric composition, gate logic, maturity levels — are abstract enough that text and tables alone leave readers to build their own mental model. Excalidraw SVG diagrams can make these concepts immediately visual without adding build complexity.
+
+The `excal` CLI workflow is already established (see `docs/solutions/tools/excal-cli-excalidraw-diagrams.md`) and one diagram is live (`site/public/diagrams/earos-layers.svg`). This plan identifies the highest-value opportunities and sequences them.
+
+## Approach
+
+Create `.excalidraw` source files, render to SVG with `excal render --svg --no-background`, place in `site/public/diagrams/`, and embed in the relevant markdown via full GitHub Pages URL. Commit both source and rendered output.
+
+All diagrams follow the established style: `roughness: 1` (handwritten), `fontFamily: 1` (Virgil), pastel fills, transparent backgrounds.
+
+## Diagram Opportunities
+
+### Tier 1 — Highest impact (abstract concepts, most benefit from visualisation)
+
+These five diagrams address the most complex or frequently misunderstood parts of the framework.
+
+#### 1. Eight-step DAG evaluation flow
+- **Doc:** `docs/onboarding/agent-assisted.md` (lines 13–33)
+- **What:** Eight sequential boxes with arrows showing the evaluation pipeline: Structural Validation → Content Extraction → Criterion Scoring → Cross-Reference Validation → Dimension Aggregation → Challenge Pass → Calibration → Status Determination.
+- **Why:** This is the single most abstract concept in the docs. The sequential ordering and the "challenge pass bottleneck" are frequently misunderstood. A Mermaid version exists in the repo README but is not rendered on the site docs page.
+- **Elements:** 8 rectangles (numbered), directional arrows, annotation callout on Challenge Pass ("most commonly skipped").
+- **File:** `site/public/diagrams/dag-evaluation-flow.excalidraw`
+
+#### 2. Status determination decision tree
+- **Docs:** `standard/EAROS.md` (lines 238–259), `docs/getting-started.md` (lines 111–123), `docs/onboarding/first-assessment.md` (lines 111–122)
+- **What:** Flowchart showing gate-first logic: check critical gates → if fail, Reject/Not Reviewable (stop). Otherwise compute weighted average → ≥ 3.2 Pass, 2.4–3.19 Conditional Pass, < 2.4 Rework Required.
+- **Why:** The two-phase logic (gates first, then thresholds) is the core of the scoring model and is easy to get wrong from text alone.
+- **Elements:** Diamond decision nodes for gate checks, rectangle outcome nodes colour-coded by status (green/yellow/orange/red), threshold labels on arrows.
+- **File:** `site/public/diagrams/status-determination.excalidraw`
+- **Reuse:** Embed in all three docs that describe status determination.
+
+#### 3. Rubric composition model
+- **Doc:** `docs/getting-started.md` (lines 33–57)
+- **What:** Visual showing how Core + Profile + Overlays stack to form a complete rubric set. Example scenario: "Evaluating a payment service architecture" → Core (always) + Solution-Architecture profile + Security overlay + Regulatory overlay.
+- **Why:** The three-layer concept is central to EaROS. The existing `earos-layers.svg` shows the layers but not how a practitioner *assembles* them for a specific evaluation.
+- **Elements:** Three layer blocks (core at bottom, profile in middle, overlays on top), example artifact callout on the left, arrows showing selection.
+- **File:** `site/public/diagrams/rubric-composition.excalidraw`
+
+#### 4. Maturity progression with capability stacking
+- **Doc:** `docs/onboarding/overview.md` (lines 16–64)
+- **What:** Five levels shown as ascending blocks. Each level adds capabilities on top of the previous: Level 1 (Ad Hoc) → Level 2 (Rubric-Based: add core rubric, scoring, evidence) → Level 3 (Governed: add profiles, overlays, calibration) → Level 4 (Hybrid: add AI agents, challenge pass) → Level 5 (Optimised: add CI/CD, continuous calibration).
+- **Why:** The site renders this as a stepper component, but the capability *accumulation* is invisible. A stacked diagram shows what's new at each level.
+- **Elements:** 5 horizontal bars of increasing width, each labelled with what's added, arrow showing progression.
+- **File:** `site/public/diagrams/maturity-levels.excalidraw`
+
+#### 5. Three evaluation lenses
+- **Doc:** `docs/onboarding/governed-review.md` (lines 78–90)
+- **What:** Three overlapping circles (or three columns) showing: Artifact Quality (completeness, coherence, clarity), Architectural Fitness (soundness, quality attributes, risks), Governance Fit (compliance, controls, review expectations).
+- **Why:** Reviewers often conflate these perspectives. A diagram showing them as distinct but complementary lenses sharpens evaluation quality.
+- **Elements:** Three labelled regions with key concerns listed inside each.
+- **File:** `site/public/diagrams/evaluation-lenses.excalidraw`
+
+### Tier 2 — Medium impact (process flows, relationships)
+
+#### 6. Calibration workflow loop
+- **Doc:** `docs/onboarding/governed-review.md` (lines 94–122)
+- **What:** 7-step calibration process with a feedback loop: Select artifacts → Score independently → Compare → Identify disagreements → Resolve → Compute κ → Update decision trees → (loop back).
+- **File:** `site/public/diagrams/calibration-workflow.excalidraw`
+
+#### 7. Hybrid evaluation model
+- **Doc:** `docs/onboarding/agent-assisted.md` (lines 71–87)
+- **What:** Side-by-side comparison: Human path (contextual judgment) ↔ AI path (consistency, coverage) → Reconciliation centre → Final evaluation record.
+- **File:** `site/public/diagrams/hybrid-model.excalidraw`
+
+#### 8. CI/CD integration pipeline
+- **Doc:** `docs/onboarding/scaling-optimization.md` (lines 11–31)
+- **What:** Pipeline diagram: Architecture artifact modified → PR/MR → EAROS evaluation triggered → colour-coded outcomes (red: blocked, yellow: conditional, green: clean merge).
+- **File:** `site/public/diagrams/cicd-pipeline.excalidraw`
+
+#### 9. Profile selection matrix
+- **Doc:** `docs/onboarding/governed-review.md` (lines 17–33)
+- **What:** Artifact type → profile mapping with visual callouts showing what each profile adds.
+- **File:** `site/public/diagrams/profile-selection.excalidraw`
+
+#### 10. Continuous calibration feedback loop
+- **Doc:** `docs/onboarding/scaling-optimization.md` (lines 33–48)
+- **What:** Circular flow: Evaluations → Score distribution tracking → Wasserstein distance → Threshold check → Recalibration (if needed) → (loop).
+- **File:** `site/public/diagrams/continuous-calibration.excalidraw`
+
+### Tier 3 — Clarification (helpful but lower priority)
+
+#### 11. Nine dimensions grid
+- **Doc:** `docs/onboarding/first-assessment.md` (lines 48–64)
+- **What:** 3×3 visual grid of the 9 core dimensions, with gate indicators.
+- **File:** `site/public/diagrams/nine-dimensions.excalidraw`
+
+#### 12. Gate severity hierarchy
+- **Doc:** `docs/onboarding/first-assessment.md` (lines 97–109)
+- **What:** Three-level severity stack: Advisory → Major → Critical, with effects.
+- **File:** `site/public/diagrams/gate-hierarchy.excalidraw`
+
+#### 13. Evidence extraction workflow
+- **Doc:** `docs/getting-started.md` (lines 81–99)
+- **What:** 5-box flow: Find evidence → Record citation → Match to scoring guide → Assign score → Flag uncertainty.
+- **File:** `site/public/diagrams/evidence-workflow.excalidraw`
+
+#### 14. Overlay selection triggers
+- **Doc:** `docs/onboarding/governed-review.md` (lines 35–49)
+- **What:** Decision tree for when to apply each overlay (Security, Data Governance, Regulatory).
+- **File:** `site/public/diagrams/overlay-selection.excalidraw`
+
+#### 15. Profile creation workflow
+- **Doc:** `docs/onboarding/scaling-optimization.md` (lines 51–69), `docs/profile-authoring-guide.md` (lines 14–22)
+- **What:** 6-step design method selection with decision points.
+- **File:** `site/public/diagrams/profile-creation.excalidraw`
+
+## Acceptance Criteria
+
+- [ ] Tier 1 diagrams (5) created, validated, rendered, and embedded in their docs
+- [ ] Each diagram follows style conventions: roughness 1, Virgil font, pastel fills, transparent background
+- [ ] Both `.excalidraw` source and `.svg` output committed for every diagram
+- [ ] SVGs embedded via full GitHub Pages URL for cross-platform rendering
+- [ ] Site deployed and diagrams verified on live pages
+- [ ] Tier 2 diagrams (5) created and embedded
+- [ ] Tier 3 diagrams (5) created and embedded (stretch)
+
+## Implementation Notes
+
+- All diagrams live in `site/public/diagrams/` so the Deploy Site workflow picks them up automatically.
+- The status determination diagram (#2) is reused across 3 docs — embed the same SVG URL in each.
+- The Deploy Site workflow triggers on `site/**` and `docs/**` changes, so pushing diagrams + updated docs in the same commit triggers a single deploy.
+- For complex diagrams (DAG flow, decision tree), consider using frames in Excalidraw to group related elements.
+- Run `excal validate` on every `.excalidraw` file before rendering.
+
+## Sequencing
+
+Start with Tier 1 in order (DAG flow first — highest value, most complex). Each diagram is independent, so they can be done in parallel if needed. Tier 2 and 3 follow once Tier 1 is verified on the live site.
+
+## Sources
+
+- Excal CLI learning: `docs/solutions/tools/excal-cli-excalidraw-diagrams.md`
+- Existing example: `site/public/diagrams/earos-layers.excalidraw` / `.svg`
+- Style conventions: roughness 1, fontFamily 1, `--no-background`, pastel palette (#a5d8ff, #b2f2bb, #ffec99, #fcc2d7, #dee2e6)

package/assets/init/docs/solutions/tools/excal-cli-excalidraw-diagrams.md

@@ -0,0 +1,150 @@
+---
+title: "Creating Excalidraw diagrams with the excal CLI"
+category: tools
+date: 2026-03-23
+tags:
+  - excalidraw
+  - excal-cli
+  - svg
+  - diagrams
+  - documentation
+component: "diagrams / documentation"
+problem_type: technique
+severity: low
+resolved: true
+resolution_type: workflow
+---
+
+## Purpose
+
+`excal` is an agent-first CLI for creating, validating, and rendering Excalidraw diagrams. It produces resolution-independent SVGs that render identically across GitHub Pages, npmjs, VS Code preview, and any browser — unlike unicode art or ASCII diagrams, which depend on font support.
+
+Use it whenever documentation needs a visual: architecture layers, data flows, component relationships, deployment topologies.
+
+## Workflow
+
+### 1. Create an Excalidraw scene
+
+Write a `.excalidraw` JSON file:
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "elements": [ ... ],
+  "appState": { "viewBackgroundColor": "#ffffff" },
+  "files": {}
+}
+```
+
+Elements include rectangles, ellipses, diamonds, arrows, lines, text, and images. Run `excal skill` for the full element reference.
+
+### 2. Bound text (labels inside shapes)
+
+To place text inside a rectangle:
+
+- Rectangle: `"boundElements": [{ "id": "text-id", "type": "text" }]`
+- Text: `"containerId": "rectangle-id"`
+- Text `x` = `container.x + padding` (e.g., 20px)
+- Text `y` = `container.y + (container.height - textHeight) / 2`
+- Text `width` = `container.width - (2 × padding)`
+- `"textAlign": "center"`, `"verticalAlign": "middle"`
+
+**Critical:** Text `x` must be the **left edge** of the text area, not the center point. `textAlign: "center"` handles horizontal centering within the text width. Setting `x` to the container center pushes text to the right.
+
+### 3. Style conventions
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| `roughness` | `1` | Handwritten/sketchy (project standard) |
+| `fontFamily` | `1` | Virgil — Excalidraw's handwritten font |
+| `fillStyle` | `"solid"` | Solid background fills |
+| `strokeWidth` | `2` | Visible but not heavy |
+| `roundness` | `{ "type": 3 }` | Rounded corners on rectangles |
+
+Pastel fill palette:
+
+| Colour | Hex | Use |
+|--------|-----|-----|
+| Blue | `#a5d8ff` | Primary / top layer |
+| Green | `#b2f2bb` | Secondary / middle layer |
+| Yellow | `#ffec99` | Tertiary / foundation layer |
+| Pink | `#fcc2d7` | Alerts / warnings |
+| Gray | `#dee2e6` | Neutral / background |
+
+### 4. Validate
+
+```bash
+excal validate diagram.excalidraw
+```
+
+Returns structured JSON. Check `result.valid` is `true` before rendering. Also validates frame references, bound text bindings, and arrow connections.
+
+### 5. Render to SVG
+
+```bash
+excal render diagram.excalidraw --svg --no-background --outDir ./output
+```
+
+Key flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--svg` | SVG output (default) |
+| `--png` | PNG output (requires Playwright) |
+| `--no-background` | Transparent background — required for dark-mode compatibility |
+| `--dark-mode` | Render with dark theme |
+| `--scale <n>` | Scale factor for PNG (default: 2) |
+| `--frame <id\|name>` | Export a single frame |
+| `--padding <n>` | Padding in pixels (default: 20) |
+| `--dry-run` | Validate pipeline without writing files |
+
+### 6. Embed in markdown
+
+Use the full published URL for cross-platform rendering:
+
+```markdown
+![Diagram description](https://thomasrohde.github.io/EAROS/diagrams/diagram-name.svg)
+```
+
+Full URLs work on GitHub Pages, npm README pages, and VS Code preview. Relative paths resolve inconsistently across platforms.
+
+### 7. Commit and deploy
+
+Commit both the `.excalidraw` source (for future edits) and the `.svg` output (for rendering). Place SVGs under a path the deploy workflow watches.
+
+## CLI Reference
+
+| Command | Purpose |
+|---------|---------|
+| `excal inspect <file>` | Element counts, bounds, metadata |
+| `excal validate <file>` | Structural consistency check |
+| `excal render <file>` | Render to SVG, PNG, or PDF |
+| `excal guide` | Full CLI guide as markdown |
+| `excal skill` | Excalidraw domain knowledge for agents |
+
+All commands return a structured JSON envelope with `ok`, `result`, `warnings`, `errors`, and `metrics`.
+
+## Checklist
+
+When adding a diagram to documentation:
+
+- [ ] Authored as `.excalidraw` source file
+- [ ] `roughness: 1`, `fontFamily: 1` (handwritten style)
+- [ ] Text centered: `textAlign: "center"`, `verticalAlign: "middle"`
+- [ ] Validated with `excal validate`
+- [ ] Rendered with `excal render --svg --no-background`
+- [ ] Embedded using full URL
+- [ ] Both `.excalidraw` and `.svg` committed
+
+## Example
+
+The EaROS three-layer model diagram:
+
+- Source: `site/public/diagrams/earos-layers.excalidraw`
+- Rendered: `site/public/diagrams/earos-layers.svg`
+- Embedded in: `tools/editor/README.md`
+
+## Origin
+
+Discovered while replacing unicode box-drawing diagrams that rendered poorly on GitHub Pages. Unicode characters like `─` (U+2500) are invisible in many web monospace fonts. The `excal` approach solves this and generalises to any diagram need.