@sema-agent/server 1.196.0 → 1.198.0

package/dist/task-cwd.js

@@ -11,6 +11,20 @@ export function isValidCwd(cwd) {
 export function cwdHonored(config) {
     return config.remoteExec?.provider === "host" && config.requirePrincipal !== true;
 }
+export function inProcessSingleUserLane(config) {
+    return config.remoteExec === undefined && config.requirePrincipal !== true;
+}
+export function satisfiedByProcessCwd(requested, realpath, cwd = process.cwd) {
+    try {
+        return realpath(requested) === realpath(cwd());
+    }
+    catch {
+        return false;
+    }
+}
+export function shellEnvMismatchCount(requested, procEnv) {
+    return Object.keys(requested).filter((k) => procEnv[k] !== requested[k]).length;
+}
 export const MAX_ADDITIONAL_DIRS = 64;
 export function parseAdditionalDirectories(raw) {
     if (!Array.isArray(raw))

package/dist/task-cwd.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-cwd.js","sourceRoot":"","sources":["../src/task-cwd.ts"],"names":[],"mappings":"AAiBA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC;AAQnC,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,CAAC,MAAM,GAAG,CAAC;QACd,GAAG,CAAC,MAAM,IAAI,aAAa;QAC3B,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CACnC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,UAAU,CAAC,MAA0E;IACnG,OAAO,MAAM,CAAC,UAAU,EAAE,QAAQ,KAAK,MAAM,IAAI,MAAM,CAAC,gBAAgB,KAAK,IAAI,CAAC;AACpF,CAAC;AAGD,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAYtC,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,MAAM,IAAI,mBAAmB;YAAE,MAAM;QAC7C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACpD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAeD,MAAM,UAAU,sBAAsB,CACpC,UAA8B,EAC9B,GAA+C;IAE/C,OAAO,UAAU,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAClF,CAAC"}
+{"version":3,"file":"task-cwd.js","sourceRoot":"","sources":["../src/task-cwd.ts"],"names":[],"mappings":"AAiBA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC;AAQnC,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,CAAC,MAAM,GAAG,CAAC;QACd,GAAG,CAAC,MAAM,IAAI,aAAa;QAC3B,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CACnC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,UAAU,CAAC,MAA0E;IACnG,OAAO,MAAM,CAAC,UAAU,EAAE,QAAQ,KAAK,MAAM,IAAI,MAAM,CAAC,gBAAgB,KAAK,IAAI,CAAC;AACpF,CAAC;AAWD,MAAM,UAAU,uBAAuB,CAAC,MAA0E;IAChH,OAAO,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,MAAM,CAAC,gBAAgB,KAAK,IAAI,CAAC;AAC7E,CAAC;AAKD,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,QAA+B,EAAE,MAAoB,OAAO,CAAC,GAAG;IACvH,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAKD,MAAM,UAAU,qBAAqB,CAAC,SAAiC,EAAE,OAA2C;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAClF,CAAC;AAGD,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAYtC,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,MAAM,IAAI,mBAAmB;YAAE,MAAM;QAC7C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACpD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAeD,MAAM,UAAU,sBAAsB,CACpC,UAA8B,EAC9B,GAA+C;IAE/C,OAAO,UAAU,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAClF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.196.0",
+  "version": "1.198.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -17,6 +17,7 @@
     "!dist/sema-server*",
     "!dist/run-local-linux-x64",
     "!dist/run-local-darwin-arm64",
+    "skills",
     "deploy/sema-up"
   ],
   "bin": {

package/skills/code-review.md

@@ -0,0 +1,28 @@
+---
+name: code-review-rubric
+description: How to produce a prioritized, actionable code review (severity, path:line, concrete fixes).
+scenarios: code-review
+---
+# Code review rubric
+
+Produce a review that an engineer can act on immediately.
+
+## Output shape
+1. **Summary** — 2–3 lines: overall health + the single most important thing to fix.
+2. **Findings**, grouped by severity:
+   - **Blocker** — correctness/security bug, data loss, or a crash path. Must fix before merge.
+   - **Major** — likely bug, missing error handling, race, leak, or a design problem.
+   - **Minor** — style, naming, small simplification, nit.
+3. Each finding: `path:line — what's wrong — concrete fix`. Cite the actual code; reference real symbols.
+
+## What to look for
+- **Correctness**: edge cases, off-by-one, race conditions, resource leaks, missing/incorrect error paths, unhandled rejections.
+- **Security**: authz/ownership checks, input validation, injection (SQL/command/path), secrets in code/logs, unsafe deserialization, SSRF.
+- **Architecture**: module boundaries, coupling, data flow, error propagation, concurrency model, idempotency of side effects.
+- **Performance**: hot paths, N+1 queries, unnecessary allocations/copies, blocking IO on the request path, missing caching/pooling.
+- **Tests**: are the risky paths covered? Do tests assert behavior, not implementation?
+
+## Discipline
+- **Read before you judge.** Use `repo_tree` to map the repo, then `repo_read_file` for the files you assess. Never invent files, lines, or symbols.
+- Prefer a few high-signal findings over an exhaustive list of nits.
+- When delegating to specialist reviewers, give each a clear scope; merge their findings, de-duplicate, and resolve disagreements.

package/skills/commit-push-pr.md

@@ -0,0 +1,77 @@
+---
+name: commit-push-pr
+description: Commit the current changes, push the branch, and open (or update) a pull request — one clean commit, a short PR title, and a Summary / Test plan body.
+---
+
+## Context
+
+Gather the real state first — run these and read the output:
+
+```bash
+whoami
+git status
+git diff HEAD
+git branch --show-current
+git log --oneline <base>..HEAD        # commits that will ride in the PR
+git diff <base>...HEAD                # the FULL diff the PR will contain
+gh pr view --json number 2>/dev/null || true   # does a PR already exist?
+```
+
+`<base>` is the default branch (usually `main` or `master`; check
+`git remote show origin` if unsure).
+
+## Git Safety Protocol
+
+- NEVER update the git config
+- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER force push to main/master; warn the user if they request it
+- Do not commit files that likely contain secrets (.env, credentials.json, etc)
+- Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported
+
+## Your task
+
+Analyze all changes that will be included in the pull request, making
+sure to look at all relevant commits (NOT just the latest commit, but
+ALL commits that will be included in the pull request from the
+`git diff <base>...HEAD` output above).
+
+Based on the above changes:
+
+1. Create a new branch if you are currently on the default branch
+   (prefix the branch name with the username from `whoami`, e.g.
+   `username/feature-name`).
+2. Create a single commit with an appropriate message:
+
+```bash
+git commit -m "$(cat <<'EOF'
+Commit message here.
+EOF
+)"
+```
+
+3. Push the branch to the repo's remote (usually `origin`; use the
+   remote this repo is actually configured with), with `-u` on first
+   push.
+4. If a PR already exists for this branch (check the `gh pr view`
+   output above), update the PR title and body using `gh pr edit` to
+   reflect the current diff. Otherwise, create a pull request using
+   `gh pr create` with the multi-line body syntax shown below.
+   - IMPORTANT: Keep PR titles short (under 70 characters). Use the
+     body for details.
+
+```bash
+gh pr create --title "Short, descriptive title" --body "$(cat <<'EOF'
+## Summary
+- What changed and why, in a few bullets
+
+## Test plan
+- How this was verified (commands run, flows driven, or why not applicable)
+EOF
+)"
+```
+
+You have the capability to call multiple tools in a single response.
+You MUST do all of the above in a single message.
+
+Return the PR URL when you're done, so the user can see it.

package/skills/dataviz/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: dataviz
+description: Use this skill whenever you are about to create ANY chart, graph, plot, dashboard, or data visualization, in ANY output medium - an HTML or React artifact, inline SVG, plotting code in any library (matplotlib, plotly, d3, Recharts, ...), or an image/PNG you will render and share. Read it BEFORE writing the first line of chart code, choosing chart colors, building a stat tile / meter / KPI row, or laying out a dashboard. Produces visualizations that read as one system - elegant, accessible, consistent in light and dark - using a brand-neutral placeholder palette you swap for your own. Teaches a design-system-agnostic method: a form heuristic, a color formula with a runnable validator, mark specs, and interaction rules. A validated default palette is documented in `references/palette.md` - swap that file's values for your brand's. Triggers on: "chart", "graph", "plot", "data viz", "visualization", "dashboard", "analytics", "visualize data", "categorical colors", "sequential / diverging palette", "stat tile", "sparkline", "heatmap", "legend", "axis", "tooltip", "chart colors", "color by series".
+---
+
+# Data Visualization
+
+A chart is **read by people and executed by you**. This skill turns "make it look
+good" into a procedure with checks, so the result is right by construction rather
+than by taste.
+
+**The method here is design-system-agnostic.** Nothing in the procedure, the form
+heuristic, the six checks, or the mark specs is specific to one product. A design
+system supplies a small set of *parameters* (its ramps, a categorical order, a
+diverging pair, a status palette, a texture, its surfaces, its filter components);
+the method consumes them unchanged. A **validated default palette** is the
+reference instance, fully specified in `references/palette.md`. To target your
+brand, read that file's structure and substitute its values — touch nothing else.
+
+> The single most important habit: **the color part is computable, so compute it.**
+> Never eyeball whether a palette is colorblind-safe — run `scripts/validate_palette.js`.
+
+## The procedure — do these in order
+
+Color comes LAST. Most bad charts pick colors first.
+
+1. **Pick the form.** What is the data's job — magnitude, identity, polarity, a
+   single headline, change-over-time? The job picks the chart type, and sometimes
+   the answer is *not a chart* (a stat tile or hero number). → `references/choosing-a-form.md`
+2. **Assign color by the job it does.** Categorical (identity), sequential
+   (magnitude), diverging (polarity), or status (state) — each has one rule.
+   Assign categorical hues in fixed order, never cycled. → `references/color-formula.md`
+3. **VALIDATE the palette — run the script, don't reason about ΔE.**
+   `node scripts/validate_palette.js "<hex,hex,…>" --mode light` (relative to
+   this skill's base directory — or load it as `<script type="module">` in the
+   chart's own page, where it reads
+   `data-palette` off `<body>` and logs a `console.table` report). It returns
+   pass/fail on the lightness band, chroma floor, adjacent-pair CVD separation,
+   and contrast. Fix anything that FAILs before continuing. Re-run for
+   `--mode dark` with that mode's surface.
+4. **Apply mark specs & spacers.** Thin marks, 4px rounded data-ends anchored to
+   the baseline, 2px lines, ≥8px markers, a 2px surface gap between fills (stacked
+   segments and adjacent bars alike) and a 2px surface ring on overlapping marks,
+   selective direct labels. → `references/marks-and-anatomy.md`
+5. **Add the hover layer — by default.** An HTML/SVG chart *is* interactive; ship
+   a crosshair+tooltip on line/area and a per-mark hover tooltip on bar/dot/cell.
+   The only form that skips it is a bare stat tile with no plot. Hit targets bigger
+   than the mark; filters in one row above the charts. → `references/interaction.md`
+6. **Final accessibility pass.** For ≥ 2 series a legend is always present and ≤ 4
+   are also direct-labeled (a single series needs no legend box — the title names
+   it), so identity is never color-alone; a table view exists; dark mode is **selected** — its own
+   steps from the same ramps, validated against the dark surface, not an automatic
+   flip; texture is available for the CVD/print/forced-colors case.
+7. **Render it and look at it.** The validator checks color, not layout — open or
+   screenshot the output and eyeball it for label collisions, geometry, and overflow
+   before calling it done.
+
+Then check the result against **`references/anti-patterns.md`** — it is the catalog
+of what goes wrong. If your chart matches an entry, it's wrong.
+
+## Non-negotiables (true in every design system)
+
+- **Assign categorical hues in fixed order, never cycled.** A 9th series is never a
+  generated hue — it folds into "Other," small multiples, or composite encoding.
+- **One axis.** Never a dual-axis chart (two y-scales). Two measures of different
+  scale → two charts, small multiples, or indexed to a common base. *(This is the
+  #1 chart mistake — see anti-patterns.)*
+- **Color follows the entity, never its rank.** A filter that changes the series
+  count must not repaint the survivors.
+- **Sequential = one hue, light→dark. Diverging = two hues + a neutral gray
+  midpoint.** Never a rainbow; never a hue at the diverging midpoint.
+- **Run the validator before shipping any categorical palette.** CVD ≥ 12 is the
+  target; 8–12 is a floor that is legal ONLY with secondary encoding. A contrast WARN
+  obligates visible labels or a table view — it is not dismissable.
+- **Thin marks; a legend always present for ≥ 2 series (none for one), with
+  selective direct labels (never a number on every point); recessive grid/axes.**
+- **Text wears text tokens, never the series color** — values, labels, and legends
+  stay in primary/secondary/muted ink; a colored mark beside them carries identity.
+- **Status colors are reserved** (good/warning/serious/critical) and never reused
+  for "series 4"; they ship with an icon + label, never color alone.
+
+## Plugging in a design system
+
+The method is invariant; only these parameters change per system. The reference
+instance — every value filled in — is `references/palette.md`.
+
+| Parameter | What the system provides |
+|---|---|
+| **Ramps** | the hue scales (named steps) the palette draws from |
+| **Categorical theme** | the fixed hue order (a named theme); default + alternates |
+| **Sequential hue** | the default single hue for magnitude |
+| **Diverging pair** | two warm/cool poles + a neutral midpoint |
+| **Status palette** | good / warning / serious / critical — steps distinct from categorical |
+| **Texture fill** | one directional hand-drawn fill, used at 45° / 135° |
+| **Surfaces** | light & dark chart-surface colors (the validator needs these) |
+| **Filter controls** | date-range & dimension controls (behavioral spec in `interaction.md`) |
+
+To onboard a new system: fill those rows, feed its ramps to the validator, and let
+it snap each slot to the nearest passing step. Structure and rules stay as written.
+
+## Reference files
+
+| File | What it answers |
+|------|-----------------|
+| `references/choosing-a-form.md` | Which chart type / is it even a chart? |
+| `references/color-formula.md` | The four jobs, the six checks, snap-to-passing |
+| `references/marks-and-anatomy.md` | Mark specs, spacers, labels, figures, hero number |
+| `references/interaction.md` | Tooltips & hover, filters & time ranges |
+| `references/components.md` | The pieces a chart is made of — build each in plain HTML |
+| `references/anti-patterns.md` | **What goes wrong — check every chart against this** |
+| `references/palette.md` | **The reference palette instance** — every parameter, filled in; swap for your brand's |
+| `scripts/validate_palette.js` | Runnable six-checks validator (run it; don't eyeball) |

package/skills/dataviz/references/anti-patterns.md

@@ -0,0 +1,119 @@
+# Anti-patterns — what goes wrong
+
+Check every chart against this list. If your output matches an entry, it is wrong —
+fix it before shipping. These are real failure modes, each caught in shipping
+dashboards.
+
+## Color & encoding
+
+**❌ Dual-axis charts (two y-scales on one plot).**
+Why it misleads: the alignment of the two scales is arbitrary, so the chart invents a
+correlation that isn't in the data. Real example: an "Adoption" chart plotting Users
+(0–30k) against Sessions (0–800k) — a reviewer flagged it as looking "hallucinated."
+✅ Do instead: two charts, small multiples, or index both series to a common base
+(=100 at t0) on **one** axis.
+
+**❌ Recolor-on-filter.** Assigning colors by current rank, so filtering out a series
+repaints the survivors.
+Why: a reader who learned "Acme is blue" is now misled.
+✅ Color follows the entity, not its row number. Survivors keep their hue.
+
+**❌ Cycling / generating hues past 8.** A 9th categorical color, generated or reused.
+Why: indistinguishable from an existing slot under CVD; breaks the order check.
+✅ Fold the tail into "Other," facet into small multiples, or use composite encoding.
+
+**❌ Eyeballing colorblind-safety.** "These look different enough."
+✅ Run `scripts/validate_palette.js`. Adjacent ΔE ≥ 12, or 8–12 WITH secondary encoding.
+
+**❌ A value-ramp on nominal categories.** Coloring each bar darker-where-bigger
+when the categories have no natural order (products, teams, endpoints).
+Why: it double-encodes bar length as hue, burns the only free channel on
+information the chart already shows, and fails the categorical checks by design
+(a ramp spans the lightness band and drops below the chroma floor).
+✅ One series → one color (slot 1) for every bar. Ordered categories (funnel,
+tiers, age bands) → the ordinal ramp, validated with `--ordinal`.
+
+**❌ Rainbow / non-neighbor sequential.** A multi-hue ramp for magnitude.
+✅ One hue, light→dark. (Analogous neighbors or semantic heat are the only multi-hue
+sequential exceptions, always with a scale legend.)
+
+**❌ A hue at the diverging midpoint, or two cool hues as the two poles.**
+Why: the midpoint must read as "nothing"; poles must read as opposite. blue↔aqua
+fails this (both cool); blue↔red or blue↔orange succeed (warm/cool).
+✅ Two hues that read as opposite + a neutral gray midpoint.
+
+**❌ Status color used for a non-status series** (or a series color used for status).
+✅ Status tokens only when the color *means* good/bad; categorical when it's identity.
+
+## Form
+
+**❌ Eight categorical hues when the story is one number.** The most common way a
+chart misses its point.
+✅ Emphasis (highlight one, gray the rest), or a stat tile / hero number.
+
+**❌ A one-bar bar chart, or a 2-slice pie.**
+✅ A stat tile. The number is the chart.
+
+**❌ A donut/pie for comparing close values.**
+✅ A bar, or the numbers. Part-to-whole at a glance only, ≤ 6 segments.
+
+**❌ More than ~7 color classes carrying meaning.**
+✅ A table, or table + chart. Past ~7 bins, adjacent classes blur.
+
+## Marks & chrome
+
+**❌ Thick saturated blocks, heavy gridlines, no breathing room.** Reads loud, even
+childish, at scale.
+✅ Thin marks, hairline recessive grid/axes, generous padding. Saturated fills are
+for small marks and accents, never large blocks.
+
+**❌ Dashed gridlines or axis rules.** Dashing adds visual noise and reads as
+"projection" or "threshold" when it's just a grid.
+✅ Gridlines and axes are solid hairlines, one shade off the surface.
+
+**❌ A number on every data point.** A value beside every dot or segment is chaos and goes unread.
+✅ A legend is always present for ≥ 2 series; direct-label *selectively* (the endpoint, the extreme, the one series that matters) and let the axis + tooltip carry the rest.
+
+**❌ A border drawn around marks to separate them.**
+✅ A 2px surface gap between fills (stacked segments and adjacent bars alike) and a 2px surface ring (on overlapping markers).
+
+**❌ A label clipped by, or overflowing, a too-small bar or stacked segment** —
+including `overflow: hidden` cropping the first/last characters of an in-segment label.
+✅ Only render a label inside a mark when it fits with padding; otherwise move it
+outside the bar end, or drop it to the tooltip/legend (the value stays in the table view).
+
+**❌ A chart container whose fixed height excludes the x-axis band** — the plot
+fits, the axis labels don't, so the card gets a tiny nested vertical scroll.
+✅ Size the container to include the axis labels (plot height + x-axis band),
+or let the container grow with its content instead of fixing a height.
+
+**❌ A display or serif face on the hero figure.** It reads as off-brand decoration.
+✅ The hero figure uses the same sans as everything else.
+
+**❌ `tabular-nums` on a large standalone number.** Equal-width digits make `121`
+look loose at display sizes.
+✅ Proportional figures on hero and stat-tile values; `tabular-nums` only where
+numbers align vertically (table rows, axis ticks).
+
+**❌ Texture on by default, or as decoration.** Dense angled fields are a vestibular
+risk and read as noise on value scales.
+✅ Texture is opt-in (a11y setting, print, forced-colors), 45°/135° only, ordered on
+value scales.
+
+## Interaction & accessibility
+
+**❌ A tooltip as the only way to read a value.**
+✅ Tooltips enhance, never gate — every value is also reachable via direct labels or
+the table view; keyboard focus shows the same as hover.
+
+**❌ Pinpoint hover targets — an 8px scatter dot you must land on dead-center.**
+✅ The hit area includes the 2px gap and meets a ~24px minimum; dense scatter uses a nearest-point / Voronoi layer.
+
+**❌ Per-chart filters, or filters inside a chart card.**
+✅ One filter row above everything it scopes; all charts re-render against the same slice.
+
+**❌ Skeleton flash on refetch.**
+✅ Hold the previous render at reduced opacity — no layout jump.
+
+**❌ No table view / color-only encoding on a continuous scale.**
+✅ Every chart has a table-view twin (the WCAG-clean equivalent).

package/skills/dataviz/references/choosing-a-form.md

@@ -0,0 +1,57 @@
+# Choosing a form
+
+Decide this **before** color. The data's job picks the form — and sometimes the
+right form is not a chart.
+
+## Is it even a chart?
+
+| The data is… | Use | Not |
+|---|---|---|
+| A single current value (+ maybe a trend) | **Stat tile** (value + delta + sparkline) | A one-bar bar chart |
+| A handful of headline numbers | **KPI row** of stat tiles | A grouped bar chart |
+| The one number a dashboard leads with | **Hero figure** (≥48px, sans) | — |
+| A single ratio against a limit | **Meter** (same-ramp track) | A pie of 2 slices |
+| More than ~7 classes that all carry meaning | A **table** (or table + chart) | More colors |
+
+If a chart *is* right, pick the type by the job:
+
+## The job → the type
+
+| Job (what the reader must do) | Default form | Color job |
+|---|---|---|
+| Compare magnitude, low → high | bar / column; **heatmap** for a grid | sequential (one hue) |
+| Trend over time | line; area for a single series | sequential or 1 categorical |
+| Tell distinct series apart | grouped/stacked bar, multi-line | **categorical** |
+| One series is the point, rest are context | **emphasis** (highlight one, gray the rest) | 1 hue + gray |
+| Above/below a baseline; Δ to target | diverging bar, or line vs baseline | diverging |
+| Part-to-whole | **stacked bar** (go horizontal for many / long-named categories) | categorical |
+| Ordered-scale share (Likert, sentiment, agree↔disagree) | **diverging stacked bar**, centered on neutral | diverging |
+| Before → after per item | dumbbell | 1 hue, 2 shades |
+
+## The rules behind the table
+
+- **Sequential is the safe default.** One hue, more-is-darker. It stays legible and
+  consistent and is hard to misread. Reach for it unless the data's job is
+  specifically *identity* or *polarity*.
+- **Categorical is for when the series ARE the subject** — and it has a real cost:
+  it can bury the one data point that actually matters. If the story is "this one
+  went up," that's **emphasis**, not categorical.
+- **Emphasis** = the most underused form. One series in the accent hue, the rest in
+  the de-emphasis gray. Often the honest answer to "make this chart clearer."
+- **Texture is an opt-in expression, not a default form.** It earns its place only
+  for accessibility (full CVD), print/export, and `forced-colors`. Never decorative.
+  → see `marks-and-anatomy.md`.
+
+## Series-count ladder (categorical)
+
+| Series | Treatment |
+|---|---|
+| 1–3 | color alone is comfortable for everyone; direct-label |
+| 4 | the CVD floor enters — direct labels become mandatory, not a courtesy |
+| 5–6 | soft cap; legend or small multiples |
+| 7–8 | token ceiling; past it, fold the tail into "Other," facet into small multiples, or use composite encoding (hue × shape) |
+
+Never solve "too many series" by generating more hues. A generated 9th hue is
+indistinguishable from an existing one under CVD and breaks every check.
+
+---

package/skills/dataviz/references/color-formula.md

@@ -0,0 +1,113 @@
+# Color formula
+
+Color is **not hand-picked**. Every chart color does exactly one of four jobs, and a
+palette is legal only if it passes six checks. The checks are the product — they are
+what makes a palette safe to change and what lets the same method run on any design
+system's ramps.
+
+## The four jobs
+
+| Job | What it encodes | Structure |
+|---|---|---|
+| **Categorical** | identity (which series) | 8 hues, fixed order, assigned in sequence, never cycled |
+| **Ordinal** | position in a sequence (funnel stage, tier, bucket) | one hue, monotone lightness steps; light end still ≥ 2:1 on surface |
+| **Sequential** | magnitude (how much) | one hue, steps 100→700, light→dark; flips anchor in dark |
+| **Diverging** | polarity (which side of a baseline) | two hues + a neutral gray midpoint; equal steps per arm |
+| **Status** | state (good→critical) | a small fixed scale, reserved meaning, always icon+label |
+
+**Categorical or ordinal?** If swapping the category order would change the
+meaning — funnel stages, size tiers (S/M/L), age bands, cohort buckets — it is
+**ordinal** and takes a one-hue ramp so the reader sees the order in the color.
+If swapping would not — product names, teams, regions, endpoints — it is
+**nominal categorical** and each bar takes the *same* slot-1 hue (one series,
+so no legend box — the title names it), or slots 1..N when there are N separate
+series. Never color nominal bars by their value: that spends the identity channel
+re-encoding what bar length already shows.
+
+## The six checks
+
+Every categorical color — current or proposed — must pass all six.
+
+1. **Fixed hue anchors.** Eight families in a fixed order. The order is the
+   CVD-safety mechanism; it never changes. *(structural — enforced, not measured)*
+2. **Lightness band per mode.** OKLCH L ≈ 0.43–0.77 light; ≈ 0.48–0.67 dark. *(validator)*
+3. **Chroma floor.** OKLCH C ≥ ~0.10 — below it a hue reads as gray and stops doing
+   identity work. *(validator)*
+4. **CVD separation.** Machado-2009 ΔE ≥ 12 target / ≥ 8 floor (floor legal only with
+   secondary encoding), under protanopia & deuteranopia. *Adjacent* pairs for
+   stacks/bars/lines (only neighbors touch — assignment never skips); **all pairs for
+   scatter, bubble, choropleth, and small-multiples**, where any two marks can sit side
+   by side — pass `--pairs all` there or a real collapse stays hidden. *(validator)*
+5. **Contrast vs surface.** ≥ 3:1 for marks; conditionally relaxed where values are
+   readable another way (visible labels or the table view). *(validator)*
+6. **Documented palette only.** Every slot is a hex from the instance file
+   (`palette.md` or its equivalent) — no eyeballed values. *(structural; for a
+   customer's ramps, snap to nearest — below)*
+
+## Run the checks — never eyeball them
+
+```
+node scripts/validate_palette.js \
+  "#2a78d6,#1baf7a,#eda100,#008300,#4a3aa7,#e34948,#e87ba4,#eb6834" --mode light
+```
+
+(`scripts/` is relative to this skill's base directory, shown at the top of the prompt.)
+
+(or load it as `<script type="module">` in the chart's own page — it reads
+`data-palette` off `<body>` and logs a `console.table` report)
+
+Reports each computable check (2–5) with PASS / WARN / FAIL plus the worst CVD pair.
+Exit 0 = no hard FAIL (WARN bands — floor-band CVD 8–12 and sub-3:1 contrast relief —
+still exit 0 and require secondary encoding); exit 1 on any FAIL. Run once per mode
+(`--mode dark --surface "#1a1a19"`), and add
+`--pairs all` for scatter / bubble / map / small-multiples charts (where any two marks
+can be neighbors — the default adjacent check would hide a collapse). For an
+**ordinal** ramp pass `--ordinal` — it switches to the ramp checks (monotone L,
+adjacent ΔL ≥ 0.06, light-end contrast ≥ 2.0:1, single hue) instead of the
+categorical six.
+A WARN on CVD (8–12 floor) is legal **only** if you also ship secondary encoding
+(direct labels, gaps, or texture). A WARN on contrast is **not dismissable** — it
+obligates a relief channel (visible direct labels or the table view); shipping the
+sub-3:1 fill with neither is a fail.
+
+**Scope — what the validator does and doesn't cover.** These six checks validate a
+*categorical* palette (series identity). They do **not** judge a lone status/text
+color or a sequential ramp. For a single status or text color, run a WCAG *text*-
+contrast check (4.5:1 normal, 3:1 large) — `validate_palette.js` exports
+`contrast(a, b)` for exactly this. For sequential/diverging, the check is lightness
+monotonicity across the ramp, not adjacency CVD — running the categorical validator on
+a sequential ramp **will FAIL by design** (it spans the band; steps sit close), which
+is expected, not a real failure; don't "fix" a good ramp to satisfy it.
+
+## Snap-to-passing (any design system)
+
+Given a customer's ramps and a desired order:
+1. For each slot, pick the step whose OKLCH L sits in the mode's band and C ≥ floor.
+2. Run the validator. For any adjacent pair below ΔE 12, nudge one slot ± a step
+   (hold its hue, move its lightness) and re-run.
+3. Repeat until the worst adjacent pair clears the floor. Function preserved, the
+   customer's hues kept.
+
+## Themes
+
+The slot **order** is a separable, named choice — a *theme* — on the same hues and
+the same six checks. Each design system names a default order and any alternates;
+swapping themes tunes the mood without touching the method. A surface adopts one
+theme and freezes it; never mix themes within a dashboard. (See `palette.md`.)
+
+**Deriving an order when a system has no theme yet:** don't guess. Enumerate candidate
+orderings of the system's hues, run the validator on each, and pick the one that
+maximizes the *minimum adjacent* CVD ΔE. (Seeding from a known-good order by hue-family
+analogy, then optimizing, is fine — this is exactly how the default in
+`palette.md` was derived.)
+
+## Status is fixed
+
+Status never follows the theme — it is a small fixed scale (good → warning → serious
+→ critical) with reserved meaning, on steps deliberately distinct from the categorical
+slots so a status color never impersonates a series, and always paired with an
+icon + label (on a light surface warning and serious sit below 3:1 by design —
+the pairing is the mitigation). (Exact steps in `palette.md`.) The collision rule: when a series *means* good/bad (error rate, pass/fail) it wears
+status tokens; when it's just "series 4" it wears categorical — never both in one chart.
+
+---

package/skills/dataviz/references/components.md

@@ -0,0 +1,39 @@
+# Components — the pieces a chart is made of
+
+A chart is built from these parts, assembled in plain HTML/SVG. Tier 0 is the
+foundation everything mounts on; the System tier is what makes the method
+portable (and is, itself, this skill).
+
+## Tier 0 — Foundations
+- **Color roles** — categorical (8 × light/dark), sequential ramps, diverging pairs,
+  status (4), de-emphasis / "Other", grayscale chart furniture (axis/grid/label/surface).
+  Defined as CSS custom properties at the top of the HTML — see `palette.md`.
+- **Texture fill** — the directional fill + 45°/135° rotations.
+- **Chart container** — a `<figure>` (or card `<div>`) that owns responsive
+  sizing, title/caption, and the **table-view toggle** (the accessibility twin
+  of every chart). **Any fixed height includes the x-axis band** (plot height
+  + axis labels) so the card never gets a nested vertical scroll; prefer
+  letting the container grow with its content.
+- **Legend** (toggle-to-isolate, texture-aware swatches) · **Tooltip** · **Axis** · **Data label**.
+
+## Tier 1 — The charts people ask for
+- **Bar chart** — grouped + stacked, thin-bar default, horizontal + vertical.
+- **Line chart** — multi-series, soft-fill area variant, accessibility markers.
+- **Stat tile** — value + delta + optional sparkline (the figure contract).
+- **Meter / progress track** — same-ramp tracks.
+
+## Tier 2 — Rounding out the kit
+- **Area chart** (stacked, band-edge = line) · **Sparkline** · **Heatmap**
+- **Scale legend** (sequential / diverging) · **Chart filters / time range** · **Empty state**
+
+## System tier — becomes the skill
+- **Six-checks validator** — `scripts/validate_palette.js` (palette validation).
+- **Theming engine** — snap a customer's ramps to passing values (color-formula.md).
+- **Chart-type heuristic** — pick the form (choosing-a-form.md).
+- **Table-view generator** — the WCAG-clean equivalent of any chart.
+
+Notes: part-to-whole rides on the stacked bar chart; donut stays deprioritized.
+Small multiples is a layout pattern over these, not a separate piece. Scatter
+joins Tier 2 if scatter-heavy surfaces land.
+
+---