pmx-canvas 0.1.25 → 0.1.27

package/skills/control-session-orchestrator/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill_name": "control-session-orchestrator",
+  "evals": [
+    {
+      "id": 1,
+      "name": "multi-session-audit",
+      "prompt": "Act as the pmx-canvas control session and coordinate a workflow to audit MCP tool parity across server, HTTP API, SDK, and docs. Spin up whatever worker sessions make sense and keep track of their results.",
+      "expected_output": "The agent should use the control-session-orchestrator skill, define a control-plane topology, assign scoped worker sessions for independent surfaces, specify reporting and verification expectations, and track status centrally instead of trying to audit everything inline.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "implementer-and-verifier",
+      "prompt": "We need a safe parallel workflow for a risky canvas refactor: one agent should implement, another should independently review and verify. Please coordinate it from this session.",
+      "expected_output": "The agent should use the skill to frame mission, create or route to separate implementer and verifier sessions, prevent overlapping scope drift, require verification evidence, and consolidate the final decision in the control session.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "codex-control-thread",
+      "prompt": "Use this Codex app thread as the pmx-canvas control session. Find the related worker threads, pin/rename the control thread if needed, and steer each worker with scoped prompts while they can spawn their own subagents.",
+      "expected_output": "The agent should use the control-session-orchestrator skill, identify Codex app thread/session tools as the active control surface, avoid assuming GitHub Copilot-only tool names, define worker ownership and reporting, and keep central status in the control thread.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "avoid-over-orchestration",
+      "prompt": "Fix the typo in the README heading.",
+      "expected_output": "The agent should not use heavyweight control-session orchestration. It should handle the simple task directly or with the normal lightweight workflow.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "name": "rehydrate-after-handover",
+      "prompt": "You're taking over as the control session for an in-progress multi-session migration. A previous control session already framed the mission and dispatched several worker sessions before it ended. Pick up where it left off.",
+      "expected_output": "The agent should run Step 0 (Rehydrate): locate and load the control-state manifest as the source of truth, re-attach to workers by session_ref, and reconcile each worker's real status before any new dispatch. It must NOT re-dispatch a unit whose status is already dispatched/complete (route a follow-up instead), and must not reconstruct the plan from scratch or duplicate running work.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "name": "result-gate-rejects-unverified-report",
+      "prompt": "A worker session you dispatched just reported back: 'Done, the refactor looks good and tests should pass.' Decide whether to accept it and mark the workstream complete.",
+      "expected_output": "The agent should NOT accept the report. Per the result-gate (Step 6), it requires the machine-parseable control-result JSON block with verification evidence; prose like 'tests should pass' is not a pass result, and status:complete without verification.result:pass is inconsistent. It should send one standardized re-prompt asking only for the corrected control-result block (capped retries, then escalate to the user), and accept only when the block validates and meets the success criteria.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "name": "respect-concurrency-and-total-caps",
+      "prompt": "Coordinate a parity audit across 20 independent endpoints; spin up worker sessions to cover them all.",
+      "expected_output": "The agent should set a budget in the manifest (max_concurrent_workers, e.g. 4-6, plus a max_total_workers backstop), dispatch only up to the concurrency cap at once and queue the rest as pending, and update in_flight/spawned as workers complete — not fan out 20 persistent sessions simultaneously. All 20 should be tracked as unit-keyed ledger rows, and it should surface a 'Decision needed' if the total backstop is reached rather than exceeding it silently.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "name": "wave-join-completeness-gate",
+      "prompt": "Most of the audit workers have reported back. Two never responded. Can we call the audit complete and write up the result?",
+      "expected_output": "No. Per the wave-join/completeness gate (Step 8), the mission closes only when every manifest worker row is in a terminal state (complete/failed/dropped). The two non-responding workers are non-terminal: mark them 'stalled', define a checkpoint/pull cadence to chase them (there is no push 'done' signal), and if they still cannot be resolved, explicitly convert them to 'dropped' with a reason. Only then may the agent declare 'complete with N dropped: <ids + reasons>'. It must never close with a non-terminal row or drop work silently.",
+      "files": []
+    },
+    {
+      "id": 9,
+      "name": "convergence-stop-rule",
+      "prompt": "Run an open-ended workflow to find and fix every flaky test across the repo — keep going until they are all handled.",
+      "expected_output": "The agent should declare an explicit convergence rule up front (e.g. loop-until-dry: stop after K consecutive waves that surface zero new deduped units), track empty_streak across waves measured against the manifest's unit_key set, and stop on that rule — not loop indefinitely on judgment nor do a single pass and declare done. It should record why iteration ended and never stop silently.",
+      "files": []
+    },
+    {
+      "id": 10,
+      "name": "two-level-hierarchy-guard",
+      "prompt": "One of your worker sessions reports that the task is bigger than expected and wants to spin up its own set of persistent project sessions to parallelize further. How should that be handled?",
+      "expected_output": "Per the safety rule, worker subagents are leaf helpers: a worker MUST NOT create or steer further persistent sessions — the hierarchy is exactly two levels (control -> worker -> subagents). The worker should report the need (e.g. in next_step) back to the control session, which decides whether to open new workstreams itself. Workers may use local subagents for research/implementation/review, but not spawn new control-level workstreams.",
+      "files": []
+    }
+  ]
+}

package/skills/data-analysis/SKILL.md

@@ -35,6 +35,12 @@ In `pmx-canvas`, prefer `canvas_add_graph_node` for charts and trend lines and
 `canvas_add_json_render_node` when the analysis should land as a richer dashboard or table inside
 the canvas.
 
+For chart design and color choices, apply the `tufte-viz` skill (`skills/tufte-viz/SKILL.md`): color
+must encode data, not decorate. Single-series bar charts default to one accent with the key bar
+highlighted (`colorBy: series`); opt into `category`/`value` only when color carries a variable.
+Prefer `sparkline`/`dot-plot`/`bullet`/`slopegraph` and direct labels over legends; use small
+multiples for more than ~4 overlapping series.
+
 ## When to Use
 
 - Answering quantitative questions about engineering performance, delivery, or team health

package/skills/pmx-canvas/SKILL.md

@@ -75,6 +75,19 @@ reference before using adapter-native features:
 - `references/codex-app-adapter.md` — Codex app native Browser + MCP adapter, AX context reading,
   focus labeling, and live-test checklist.
 
+Host-aware visibility rule:
+- If a native PMX Canvas adapter/panel is available and already represents the workbench (for example
+  the GitHub Copilot app `pmx-canvas` canvas extension, or Codex's in-app Browser opened to
+  `/workbench`), use that panel. Do **not** also open a separate browser panel to the same workbench;
+  it wastes space and confuses which surface is authoritative.
+- If no native adapter/panel is available (generic MCP client, shell-only agent, raw CLI harness,
+  or another agent harness without canvas support), open the normal PMX Canvas browser workbench first
+  so the human can see mutations as they happen. Use the server URL's `/workbench` route.
+- External URLs in `mcp-app` nodes show the "Unverified domain" interstitial by design. Only
+  same-origin `/api/canvas/frame-documents/<id>` URLs are auto-trusted. For external tools, use a
+  bundled `web-artifact`, same-origin frame document, or set `data.trustedDomain: true` only when the
+  user accepts the risk.
+
 The canvas auto-starts on first MCP tool call when running in MCP mode (`pmx-canvas --mcp`).
 For manual start:
 
@@ -168,6 +181,10 @@ pmx-canvas node list --type external-app --summary
 pmx-canvas pin --list
 pmx-canvas ax context
 pmx-canvas ax focus <node-id>
+pmx-canvas ax work add --title "Wire up auth" --status in-progress <node-id>
+pmx-canvas ax approval request --title "Deploy to prod"
+pmx-canvas ax steer "focus on the failing test first"
+pmx-canvas ax timeline --limit 50
 pmx-canvas snapshot save --name "before-refactor"
 pmx-canvas code-graph
 pmx-canvas spatial
@@ -189,6 +206,15 @@ pmx-canvas spatial
   `focus --no-pan` when you only need to select/raise a node without hijacking the human's camera.
 - `ax status|context|focus` — inspect the host-agnostic AX layer; `ax context`
   combines pinned context and AX focus for adapter prompt injection.
+- `ax event add`, `ax steer`, `ax evidence add`, `ax timeline` — the AX timeline
+  (agent-events, steering messages, evidence). Persisted for diagnostics,
+  retention-bounded, and excluded from snapshots.
+- `ax work add|update|list`, `ax approval request|resolve|list`,
+  `ax review add|list` — canvas-bound AX state (work items, approval gates,
+  review annotations) that rides snapshots and restore and is cleared by `clear`.
+- `ax host report|status` — report/read the host/session capability (own partition).
+- `copilot install-extension [--dry-run] [--yes]` — install the bundled GitHub
+  Copilot adapter into a repo; the core stays host-agnostic.
 - `fit [id ...]` — set the server viewport to fit the whole canvas or selected nodes before screenshots or whole-board review
 - `screenshot --output <path>` — top-level shortcut for `webview screenshot`; supports `--format png|jpeg|webp` and `--quality`
 - `json-render --schema|--examples` — inspect the json-render component catalog with `--component`/`--field` filters; same data as `node schema --type json-render` in a more direct shape
@@ -239,7 +265,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | `trace` | Trace/timeline viewer | Execution traces, timelines |
 | `mcp-app` | Hosted app/embed frame | Tool-backed MCP apps or external app content; not generic CLI-created notes |
 | `json-render` | Native structured UI panel | Dashboards, forms, tables, interactive layouts from json-render specs |
-| `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts rendered inside the canvas |
+| `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, composed, plus Tufte primitives (sparkline, dot-plot, bullet, slopegraph) rendered inside the canvas |
 | `html` | Sandboxed HTML+JS document | Self-contained HTML with optional inline `<script>` and CDN imports rendered in a sandbox-restricted iframe; canvas theme tokens are auto-injected |
 | `group` | Spatial container/frame | Visually group related nodes together |
 | `prompt` | Prompt thread root | Canvas-native prompt entry points for agent conversations. **Internal type — surfaces in `canvas://layout` for thread rendering but is not created via the public `canvas_add_node` API. Don't try to add one directly.** |
@@ -351,19 +377,47 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
   `outline`. Legacy `props.label` and status variants (`success`, `info`, `warning`, `error`,
   `danger`) are normalized for saved-spec compatibility.
 
+**`canvas_stream_json_render_node`** — Build a json-render node progressively (live)
+- Omit `nodeId` on the first call to create a new streaming node — it returns the node `id`
+- Pass that same `nodeId` on later calls to append more `patches`; set `done: true` on the final call
+- `patches` are SpecStream JSON-Patch ops applied server-side (the canvas accumulates the spec):
+  `{ "op": "add", "path": "/elements/card", "value": { "type": "Card", "props": { "title": "Live" }, "children": [] } }`,
+  `{ "op": "replace", "path": "/root", "value": "card" }`,
+  `{ "op": "add", "path": "/elements/card/children/-", "value": "row1" }`
+- Build incrementally: set `/root`, add container elements, then append child element ids and elements
+- Each call re-renders the live node; partial specs render what they can. Use for dashboards/reports
+  that should fill in as you generate them rather than appearing all at once.
+
 **`canvas_add_graph_node`** — Add a native graph/chart node
 - Required: `graphType`, `data`
-- Supports `line`, `bar`, `pie`, `area`, `scatter`, `radar`, `stacked-bar`, and `composed`
-  graph types (aliases accepted)
+- Supports `line`, `bar`, `pie`, `area`, `scatter`, `radar`, `stacked-bar`, `composed`,
+  and the Tufte primitives `sparkline`, `dot-plot`, `bullet`, `slopegraph` (aliases accepted)
 - Use `xKey`/`yKey` for line, bar, area, and scatter graphs
 - Use `zKey` for scatter bubble size
 - Use `nameKey`/`valueKey` for pie graphs
 - Use `axisKey` plus `metrics` for radar graphs
 - Use `series` for stacked-bar graphs
 - Use `barKey`/`lineKey` plus optional `barColor`/`lineColor` for composed graphs
+- Bar charts: `colorBy` (`series` default = one accent + a highlighted bar, `category`, `value`, `none`) and `highlight` (`max`/`min`/index)
+- Use `valueKey` for `sparkline` (plus `fill`/`showEndDot`/`showMinMax`/`showValue`)
+- Use `labelKey`/`valueKey` (plus `sort`) for `dot-plot`
+- Use `labelKey`/`valueKey`/`targetKey`/`rangesKey` for `bullet`
+- Use `labelKey`/`beforeKey`/`afterKey` (plus `beforeLabel`/`afterLabel`/`colorByDirection`) for `slopegraph`
 - Use `nodeHeight` for the canvas frame height and `height` for chart content height
 - Uses the native json-render chart catalog under the hood
 
+**Tufte-aware charting** — color must encode data, not decorate. For chart design and critique, use
+the `tufte-viz` skill (`skills/tufte-viz/SKILL.md`). Key rules:
+- Single-series `bar` charts use `colorBy`: default `series` (one accent + one highlighted bar),
+  `category` (opt-in palette), `value` (sequential shade by magnitude), or `none` (flat). Do not
+  rainbow categorical bars by default.
+- Prefer the Tufte primitives where they fit: `sparkline` (inline trend), `dot-plot` (ranked single
+  metric vs. a bar forest), `bullet` (measure vs. target, replaces a gauge), `slopegraph`
+  (before/after across many categories).
+- Direct-label data (`showLegend: false`) instead of a legend when one or two series are identifiable.
+- For more than ~4 overlapping series, build small multiples (several small graph nodes on a shared
+  scale, arranged in a grid/group) instead of one multi-color chart.
+
 **`canvas_build_web_artifact`** — Build and optionally open a bundled web artifact
 - Required: `title`, `appTsx` (source string contents, not a file path)
 - CLI `--app-file` reads a file before calling the same build path; MCP callers must pass the source contents
@@ -669,7 +723,7 @@ server's `ui://` resource as an iframe node on the canvas
 ### HTML Nodes (Sandboxed iframe)
 
 **`canvas_add_html_node`** — Add a normal self-contained HTML document rendered in a sandboxed iframe
-- Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed)
+- Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed). If `html` is a bare path to an existing local `.html`/`.htm` file, the server reads that file's contents; otherwise it is treated as raw HTML.
 - Optional: `title`, `summary`, `agentSummary`, `presentation`, `slideTitles`, `embeddedNodeIds`, `embeddedUrls`, `x`, `y`, `width` (default 720), `height` (default 640), `strictSize`
 - Iframe sandbox is `allow-scripts` only — no same-origin access, no top-navigation, no forms
 - Canvas theme tokens are auto-injected as CSS custom properties (both `--c-*` and common `--color-*` aliases such as `--color-text-primary`, `--color-bg`, `--color-accent`) and updated live when the canvas theme changes
@@ -721,6 +775,10 @@ what the human has set up and what they're focusing on.
 | `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
 | `canvas://history` | Human-readable mutation timeline |
 | `canvas://code-graph` | Auto-detected file import dependencies (JS/TS, Python, Go, Rust) |
+| `canvas://ax` | Host-agnostic AX state: focus, work items, approval gates, review annotations, host capability |
+| `canvas://ax-context` | Agent-ready AX context: pinned context + current focus |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations |
+| `canvas://ax-timeline` | Bounded AX timeline: recent agent events, evidence, and steering messages |
 | `canvas://skills` | Index of bundled agent skills shipped with the install. Each skill is also addressable as `canvas://skills/<name>` (e.g. `canvas://skills/web-artifacts-builder`) and returns the full SKILL.md. Read this resource first to discover companion workflows the canvas is built to support. |
 
 ### Reading Spatial Intent
@@ -764,6 +822,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | GET | `/api/canvas/pinned-context` | Get current pins with neighborhood context |
 | GET | `/api/canvas/search?q=...` | Search nodes |
 | POST | `/api/canvas/json-render` | Create a native json-render node |
+| POST | `/api/canvas/json-render/stream` | Create/append a streaming json-render node (SpecStream patches) |
 | POST | `/api/canvas/graph` | Create a native graph node |
 | GET | `/api/canvas/schema` | Get running-server create schemas, examples, and json-render catalog metadata |
 | POST | `/api/canvas/schema/validate` | Validate a json-render spec or graph payload without creating a node |

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -83,6 +83,12 @@ The adapter rejects an unrelated running PMX server unless `serverUrl` is explic
 | `get_ax_context` | Return current pinned + focused AX context. |
 | `focus_nodes` | Set AX focus with `source: "copilot"`. |
 | `send_instruction` | Send an explicit prompt into the active Copilot session. |
+| `add_work_item` | Create a canvas-bound AX work item. |
+| `request_approval` | Open an approval gate (`pending`) before a high-impact action. |
+| `resolve_approval` | Resolve an approval gate as approved/rejected. |
+| `add_review_annotation` | Record a review comment/finding anchored to a node/file/region. |
+| `get_timeline` | Read the bounded AX timeline (events, evidence, steering). |
+| `report_capability` | Report host capabilities for diagnostics. |
 
 Example focus action:
 

package/skills/tufte-viz/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: tufte-viz
+description: |
+  Ideate and critique data visualizations using Edward Tufte's principles, and map them onto
+  the PMX Canvas json-render chart catalog (graph / json-render nodes). Use this skill when:
+  (1) Designing or critiquing a canvas graph/json-render chart
+  (2) Choosing a chart type, color encoding (colorBy), or primitive (Sparkline, DotPlot, BulletChart, Slopegraph)
+  (3) Reviewing a board's dashboards/charts for graphical integrity and data-ink
+  (4) Deciding between a single-series bar, small multiples, or direct labeling
+  (5) Reducing chartjunk or improving data-ink ratio on canvas charts
+  Applies: data-ink ratio, chartjunk elimination, graphical integrity, lie factor, small multiples,
+  data density — and the canvas colorBy decision (color must encode data, not decorate).
+---
+
+# Tufte Visualization Ideation (PMX Canvas)
+
+Apply Edward Tufte's principles to design clear, honest, high-density data visualizations, then
+realize them with PMX Canvas `graph` / `json-render` nodes. Color must encode data, not decorate.
+
+## Workflow
+
+### For new visualizations:
+
+1. **Clarify the data story**
+   - What comparisons matter?
+   - What's the key insight to communicate?
+   - Who's the audience?
+
+2. **Select approach** using Tufte principles:
+   - High comparison need → Small multiples (several small `graph` nodes, shared scale)
+   - Dense data → Consider data tables (`json-render` Table), sparklines (`Sparkline`)
+   - Time-series → Line charts with minimal grid
+   - Part-to-whole → Avoid pie charts; prefer bar/table
+   - Ranked single metric across categories → DotPlot over a bar forest
+
+3. **Design with data-ink in mind**
+   - Start minimal, add only what's necessary
+   - Every element must earn its ink
+   - Default to a single accent; use the full palette only when color *encodes* a variable
+
+4. **Apply the eraser test before shipping**
+   - For every element (label, tick, gridline, border, annotation): can it be erased without losing
+     information that's not already conveyed elsewhere?
+   - Watch for duplicate encodings: numeric labels next to a value already marked by a tick; legends
+     duplicating direct labels; per-panel scale annotations duplicating a shared-scale caption.
+   - If two elements compete for the same job, keep the visual one and drop the textual one (or vice
+     versa) - not both.
+
+5. **Apply the collision test before shipping**
+   - For every text element in the plot (axis labels, point annotations, epoch labels, baseline
+     labels, explanatory notes): mentally draw its bounding box. Does anything else - another text
+     element, a data line, dense markers - live in or cross that box?
+   - The eraser test catches *redundant* elements; the collision test catches *crowded* ones. Both
+     must pass.
+   - Standard fixes: move explanatory prose out of the plot into a nearby markdown node; relocate
+     band/epoch labels to a dedicated strip above the plot; push baseline/reference labels to the
+     outside margin; give each in-plot annotation a leader line so the marker and the text occupy
+     clearly separated space.
+   - Watch especially: inverted axes; shared-scale small multiples (labels stacked near zero in every
+     panel); dense scatter (text vanishes into the dot cloud unless explicitly cleared).
+
+6. **Apply the Tufte test** (see references/tufte-principles.md)
+
+### For critiquing visualizations:
+
+1. **Check graphical integrity**
+   - Calculate lie factor if proportions seem off
+   - Verify baselines and scales (bar and area charts must start at zero)
+   - Look for 3D distortion
+
+2. **Identify chartjunk**
+   - Decorative elements
+   - Heavy grids
+   - Unnecessary 3D effects
+   - Moiré patterns
+   - Gratuitous per-category color on a single-series chart (decoration, not encoding)
+
+3. **Evaluate data-ink ratio**
+   - What can be erased?
+   - What's redundant?
+
+4. **Suggest improvements** with specific before/after recommendations
+
+## Mapping to the PMX Canvas chart catalog
+
+Realize these designs with `canvas_add_graph_node` (graph nodes) and `canvas_add_json_render_node`.
+The chart catalog: `LineChart`, `BarChart`, `PieChart`, `AreaChart`, `ScatterChart`, `RadarChart`,
+`StackedBarChart`, `ComposedChart`, plus the Tufte primitives `Sparkline`, `DotPlot`, `BulletChart`,
+and `Slopegraph`.
+
+### Color must encode data — the `colorBy` decision (single-series bar/column)
+
+A single-series `BarChart` measures **one** variable across categories. Coloring each bar differently
+encodes nothing — it is decoration (chartjunk). Use the `colorBy` prop:
+
+| `colorBy`   | When to use                                                                 |
+|-------------|-----------------------------------------------------------------------------|
+| `series` (default) | One accent for all bars, one bar highlighted (Tufte-safe emphasis). Use to draw the eye to the bar that *matters* (max, target, the row under discussion). |
+| `category`  | Opt in only when the category itself is a nominal variable the reader must map by color (e.g. team identity reused across several charts with a shared key). |
+| `value`     | Sequential shade by magnitude. Note this **double-encodes** — the bar's length already encodes the value — so reserve it for when the lightness ramp genuinely aids reading a ranked magnitude; otherwise `series`/`none` are more honest. |
+| `none`      | Flat single accent, no highlight. Maximal data-ink for dense small multiples. |
+
+Default to `series`. Do **not** reach for `category` to "make it colorful." Pie/radar/stacked-bar
+already rotate the palette because each slice/series **is** a distinct variable — leave those as-is.
+
+### Tufte primitives (prefer over heavier charts)
+
+- **`Sparkline`** — word-sized time-series, no axes/labels. Use inline in tables/dashboards and one
+  per row to show a trajectory at a glance. Replaces "trending up / volatile" prose with the shape.
+- **`DotPlot`** — ranked single metric across categories. Replaces a forest of bars: a dot per
+  category on a shared axis. Far higher data-ink ratio than bars; sorts make the macro pattern pop.
+- **`BulletChart`** — a measure against a target with qualitative bands. Replaces a gauge/dial
+  (which is chartjunk). Use for KPI-vs-target, progress-vs-goal.
+- **`Slopegraph`** — two-time-point comparison across many categories (before/after). Direct slope
+  encodes change and rank simultaneously; labels sit at the endpoints (direct labeling, no legend).
+  Lines default to a single neutral ink; set `colorByDirection` to accent rising lines and mute
+  falling ones only when the direction is the point (and beware it editorializes — a falling
+  error-rate is "good", a falling revenue is "bad").
+
+### Direct labeling over legends
+
+Legends force the eye to ping-pong between key and plot (a duplicate encoding). Prefer labeling the
+data directly: end-of-line labels on `LineChart`/`Slopegraph`, endpoint labels on `DotPlot`, the
+highlighted bar's value on `BarChart`. Set `showLegend: false` on graph nodes when one or two series
+are directly identifiable; reserve legends for genuinely many overlapping series.
+
+### Small multiples over many overlapping series
+
+When more than ~4 series would overlap in one chart, do **not** cram them into a single multi-color
+`LineChart`. Create several small `graph` nodes with an **identical shared scale** and consistent
+encoding, arranged in a grid (`canvas_arrange` grid, or a `group`). Position means the same thing in
+every panel; the sequence tells the macro story while each panel carries the micro detail. This is
+almost always better than color-coding 6+ lines.
+
+## Key Principles Reference
+
+- `references/tufte-principles.md` - core principles from *Visual Display of Quantitative Information*:
+  lie factor, data-ink, chartjunk, small multiples, integrity.
+- `references/analytical-design.md` - extensions from *Envisioning Information*, *Visual Explanations*,
+  and *Beautiful Evidence*: the 6 principles of analytical design, sparklines, layering & separation,
+  micro/macro, range-frames, causality, confections. Load when designing dashboards, dense displays,
+  sparklines, or explanatory graphics.
+
+**Quick checklist:**
+- [ ] Lie Factor ≈ 1.0 (no visual distortion; bars and areas start at zero)
+- [ ] Maximum data-ink ratio
+- [ ] Zero chartjunk (no per-category color unless color encodes a variable)
+- [ ] `colorBy` chosen deliberately — default `series` (single accent + one highlight); avoid `value` unless the magnitude ramp earns the double-encode
+- [ ] Clear labeling, direct over legend
+- [ ] Answers "compared to what?"
+- [ ] Shows causality or mechanism where relevant
+- [ ] Multivariate (not over-reduced)
+- [ ] Words, numbers, images integrated - not segregated
+- [ ] Reveals multiple levels of detail (micro + macro)
+- [ ] Layering: primary data dominates, secondary recedes
+- [ ] Appropriate data density — Sparkline/DotPlot considered before a heavier chart
+- [ ] >4 overlapping series → small multiples, not one rainbow chart

package/skills/tufte-viz/references/analytical-design.md

@@ -0,0 +1,217 @@
+# Analytical Design Principles
+
+Extended principles from *Envisioning Information*, *Visual Explanations*, and *Beautiful Evidence*.
+
+## Table of Contents
+
+1. [Six Principles of Analytical Design](#six-principles-of-analytical-design)
+2. [Sparklines](#sparklines)
+3. [Layering and Separation](#layering-and-separation)
+4. [Micro/Macro Readings](#micromacro-readings)
+5. [Range-Frames and Related Techniques](#range-frames-and-related-techniques)
+6. [Showing Causality](#showing-causality)
+7. [Confections](#confections)
+
+---
+
+## Six Principles of Analytical Design
+
+These govern the design of any serious analytical presentation - charts, maps, diagrams, or evidence displays.
+
+### 1. Show Comparisons, Contrasts, Differences
+
+- The fundamental analytical question is always "compared to what?"
+- Every display should make at least one comparison explicit
+- Side-by-side placement is stronger than sequential placement
+- Differences should be shown directly rather than requiring mental arithmetic
+
+### 2. Show Causality, Mechanism, Explanation, Systematic Structure
+
+- Go beyond "what happened" to "why it happened"
+- Show the causal mechanism, not just the correlation
+- Use arrows, annotations, or sequencing to indicate direction of effect
+- Integrate explanatory text with the data display
+
+### 3. Show Multivariate Data (More Than 1 or 2 Variables)
+
+- The real world is multivariate; flatten it at your peril
+- Use small multiples, color channels, size, position, and faceting to encode multiple dimensions simultaneously
+- Avoid over-reducing: a single average line hides the story in the distribution
+
+### 4. Completely Integrate Words, Numbers, and Images
+
+- The best analytical displays weave text, data, and graphics into a single coherent view
+- Don't segregate "the chart" from "the explanation" - put them together
+- Labels, annotations, and data should coexist in the same visual space
+- Source notes and methodology belong with the graphic, not in a footnote pages away
+
+### 5. Thoroughly Describe the Evidence
+
+- Provide a title that names the data, the measurement, and the context
+- Label axes with units, time range, and source
+- Document what data is excluded or transformed
+- Quality, relevance, and integrity of evidence should be self-evident
+
+### 6. Content Counts Most of All
+
+- Analytical presentations stand or fall on the quality and relevance of the content
+- No amount of design skill can rescue poor or irrelevant data
+- Choose the question carefully; then design the graphic to answer it with maximum clarity
+
+---
+
+## Sparklines
+
+Intense, simple, word-sized graphics that can be embedded in text, tables, or dashboards.
+
+### Characteristics
+
+- Typically the height of a text line (~20-30px at screen resolution)
+- No axes, no labels, no grids
+- Data pattern speaks entirely through shape
+- Usually time-series: left is past, right is present
+- Can show reference bands (normal range), endpoints, min/max dots
+
+### Design Guidelines
+
+- Keep aspect ratio approximately banking to 45 degrees (the average slope of the data should be ~45 degrees for optimal perception)
+- Use a small red/colored dot for the most recent value or the min/max
+- Embed in context: "Revenue grew steadily [sparkline] before the Q3 dip"
+- For tables: one sparkline per row provides pattern recognition across many entities at a glance
+
+### When to Use
+
+- Dashboards where space is precious
+- Inline with narrative text to show trends without interrupting reading flow
+- Tables of KPIs where each row benefits from a visual trajectory
+- Anywhere you'd otherwise write "trending up" or "volatile" - show it instead
+
+---
+
+## Layering and Separation
+
+Techniques for organizing complex displays so that different types of information are visually stratified.
+
+### The Problem
+
+When many data elements, labels, grids, and annotations share a single plane, the result is visual confusion - everything competes for attention equally.
+
+### Solutions
+
+1. **Color layering** - Primary data in high-contrast (black/dark); secondary reference data in low-contrast (light gray); structural elements (axes) in between
+2. **Weight layering** - Data lines thicker than grid lines; grid lines thinner than axis lines
+3. **Transparency/opacity** - Background elements at 20-40% opacity; foreground data at 100%
+4. **Spatial separation** - Use whitespace to group related elements and separate unrelated ones
+5. **The 1+1=3 effect** - Two adjacent dark elements create a perceived third element (the white gap between them). Be aware of this and control it
+
+### Practical Rules
+
+- Grid: lightest layer (if present at all)
+- Axes and frame: medium layer
+- Data: heaviest layer (darkest ink, thickest stroke)
+- Annotations: medium-dark, but positioned to avoid collision with data
+- Background: minimal or none (white/very light)
+
+---
+
+## Micro/Macro Readings
+
+Displays that simultaneously serve two levels of reading: the overall pattern (macro) and the individual data point (micro).
+
+### The Idea
+
+A well-designed high-resolution display rewards both:
+- A quick glance (macro): What's the overall shape, trend, or story?
+- Close inspection (micro): What are the individual values? Which points are outliers?
+
+### How to Achieve
+
+1. **High data density** - Show all the data, not just aggregates
+2. **Clear ordering** - Sort/arrange so the macro pattern emerges from the micro data
+3. **Progressive revelation** - Overall pattern visible at arm's length; detail visible up close
+4. **Direct labeling** - Selected important data points labeled directly, others readable by position
+
+### Examples in Practice
+
+- A map where individual data points form a visible geographic pattern
+- A scatter plot where the cloud shape tells the correlation story, but individual labeled outliers are identifiable
+- Small multiples where each panel is a micro view but the sequence tells a macro story
+
+---
+
+## Range-Frames and Related Techniques
+
+Alternatives to the conventional box axes that use less ink while conveying more information.
+
+### Range-Frame
+
+Instead of drawing axes from arbitrary round numbers to round numbers, the axis line spans only the range of the data (from min to max). This encodes additional information (the data range) into an element that was previously just structural.
+
+### Dot-Dash Plot
+
+Instead of tick marks at round intervals, place a tick mark at each actual data value along the axis. The distribution of ticks immediately shows data density and gaps.
+
+### Quarter-Frame
+
+Only two sides of the frame are drawn (typically left and bottom), and only as far as the data extends.
+
+### When to Use
+
+- Range-frames: almost always preferable to standard full-frame axes
+- Dot-dash: when showing distribution along an axis matters (scatter plots, strip plots)
+- Quarter-frame: when data doesn't approach all four edges of the plot area
+
+---
+
+## Showing Causality
+
+Techniques for moving beyond correlation to communicate mechanism and cause-effect relationships.
+
+### Principles
+
+1. **Temporal sequence** - Cause precedes effect; arrange displays chronologically when causality is temporal
+2. **Mechanism diagrams** - Show the pathway from cause to effect, not just the endpoints
+3. **Counterfactual comparison** - Show what happened alongside what would have happened without the intervention
+4. **Confound acknowledgment** - Note or visualize potential confounders rather than ignoring them
+
+### Visual Techniques
+
+- Before/after with a clear intervention marker
+- Parallel time-series: treatment vs. control
+- Flow diagrams showing causal chains
+- Annotations on inflection points explaining what changed
+
+### Honesty Requirements
+
+- Don't imply causation when you only have correlation
+- Show uncertainty bands where appropriate
+- If the causal mechanism is debated, note it
+- Show the data that argues against your interpretation alongside the data that supports it
+
+---
+
+## Confections
+
+Assemblages of many visual elements that together provide a richly informative, often explanatory, display.
+
+### What They Are
+
+Confections combine multiple modes of information:
+- Diagrams + data + annotations + comparisons in a single integrated display
+- Often narrative: they tell a story with a beginning, middle, and end
+- May mix scales, perspectives, or time periods in a single view
+
+### When to Use
+
+- Explaining complex systems or processes
+- Teaching: where understanding mechanism matters more than precision
+- Summarizing research findings with their context
+- Executive briefings that need to convey both "what" and "why"
+
+### Design Principles
+
+1. **Unity** - Despite multiple elements, the display should read as one coherent piece
+2. **Hierarchy** - The most important information is most prominent
+3. **Flow** - The reader's eye should move through the display in a logical sequence
+4. **Density** - Every region of the display should carry information; no dead zones
+5. **Integration** - Words and images work together; neither is redundant to the other