chiltepin 0.47.0

package/templates/skill/reference/blocks/charts-overviews.md

@@ -0,0 +1,74 @@
+# Chiltepin blocks — Charts & overviews
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: the widest family. Time (`chart`, `gantt`, `journey`, `slopegraph`);
+Grid (`heatmap`, `quadrant`); Flow (`sankey`); Containment (`treemap`, `venn`);
+Network (`graph`, `mindmap`); hierarchy and proportion (`tree`, `pyramid`,
+`chart` kinds); causes behind one outcome (`fishbone`).
+**Answers**: What changes over time? How does the whole split? Where does the
+volume go? Where do items sit on two axes? What causes this?
+**Not this family**: one headline number → `bignumber`; a few KPIs with
+trends → `stats`; exact values → `table`; boundaries → architecture.md.
+
+#### `graph` — node-link graph
+Nodes and edges on a grid, no nesting; `weight` renders on the edge pill.
+Answers: what connects to what? For BFS / DFS / Dijkstra walkthroughs set node
+`state` (visited, current, frontier, target). `graph`, not `flow`, with no start or end.
+#### `tree` — indented hierarchy (HTML, not SVG)
+Nodes by `parent`. Plain: an indented outline. `variant: issue`: a MECE issue
+tree, left to right. `variant: org`: a top-down org chart with `role` under each
+name; more than 6 reports stack in two columns. `value` on nodes makes a driver
+tree: each node shows its number and its share of its parent. Answers: how does
+this break down? `tree`, not `bintree`, for hierarchies; `fishbone` for causes.
+#### `mindmap` — radial idea map
+One `center`, branches right and left, children on each, `accent` per branch.
+Answers: what belongs to this topic? `tree` for a directed hierarchy; `fishbone` for causes.
+#### `gantt` — schedule bars
+Task bars across named periods, tinted by `kind`. Answers: what runs when?
+`gantt`, not `timeline`, when bars span periods.
+#### `chart` — a data chart (bar / stacked / line / area / scatter / donut / pie / gauge / radar / waterfall / funnel / pareto / histogram / bell / boxplot / bullet)
+`labels` + `series` drive bar, stacked, line, area, radar, and category
+scatter; `items` drive donut, pie, gauge, waterfall, funnel, pareto; `points` drive a
+numeric scatter with `guides`; `values` drive histogram and bell (or give
+`mean` + `sd` and `markers`); `boxes` drive boxplot; `bullets` drive bullet. Answers: how does the number move or split?
+Pick the kind by the question: stacked when the total matters as much as the
+split; gauge for one number against a ceiling; donut for a whole that sums;
+waterfall for parts against a `budget`; funnel for drop-off between ordered
+stages; radar needs 3+ labels; pareto for the few causes behind most of the
+effect (80% rule drawn); histogram for how raw values spread; bell for a normal
+curve with named points; boxplot to compare spreads; bullet for a measure vs a target.
+#### `sankey` — how much moves between stages
+Node height and ribbon width share one scale; nodes are inferred from the links.
+Answers: where does the volume go? Declare `nodes` only for a label, an accent, or
+a pinned `col`. `sankey` for volumes; `flow` for the path; funnel `chart` for drop-off.
+#### `treemap` — proportional composition
+Squarified tiles, area = value, biggest first. Answers: what dominates the whole? `treemap`, not donut, past six slices.
+#### `venn` — two or three overlapping sets
+Fixed circles; `shared.sets` names set labels and puts a label in that lens.
+Answers: what do two groups share? A Venn names regions; it never measures.
+#### `fishbone` — cause & effect (Ishikawa)
+One effect at the head, cause categories as bones, specific causes along each
+bone. Keep 1–8 bones and up to 8 short items per bone. Answers: what causes
+this? `fishbone`, not `tree`, for suspected causes behind one outcome.
+#### `slopegraph` — ranked before / after
+One line per item between two value columns on a shared linear scale; crossings
+are the story. Quote `left` / `right` years. Give `accent` to the one or two lines
+that matter. Answers: what rose, what fell, what held? `slopegraph` for many items
+at two points; `chart` line for a few series over many points.
+#### `heatmap` — a numeric grid with an intensity ramp
+Cells tinted light-to-deep on one ramp, normalised to the data (or `min` /
+`max`). Answers: where is it hot? `heatmap` for a dense value grid; `matrix`
+for categorical cells; `table` when the reader needs exact rows.
+#### `pyramid` — stacked hierarchy (top → bottom widening)
+Levels that widen downward, each with a description. Answers: what rests on
+what? `pyramid`, not `layers`, when the widening shape is the message.
+#### `quadrant` — 2×2 matrix
+Items plotted at `x` / `y` (0–1) on two labelled axes. Answers: where does each
+item sit? `quadrant` for placement by judgement; scatter `chart` with `points` for data.
+#### `journey` — user journey map with optional emotion curve
+Stages across the top, rows of cells beneath, an optional emotion curve (0–1 per
+stage). Answers: what does the user experience at each stage? `journey` for
+experience; funnel `chart` for drop-off numbers; `storymap` for scope per activity.

package/templates/skill/reference/blocks/data-model.md

@@ -0,0 +1,34 @@
+# Chiltepin blocks — Data model
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Network — entities joined by cardinality edges, no nesting
+(`erd`).
+**Answers**: What shape is the data at rest, and how do the entities relate?
+**Not this family**: data in motion → `dfd` (flows.md) or `sankey`
+(charts-overviews.md); classes with behavior → `uml` (architecture.md);
+example rows the reader should scan → `table` (tables-data.md).
+
+### Data model
+
+#### `erd` — entities and relations
+Entity cards with columns and key markers, joined by crow's-foot edges. The
+renderer centres the aggregate root (the "one" side of most relations), fans
+neighbours out by relation depth, and never truncates a card.
+Answers: what shape is the data at rest, and how do the entities relate?
+Write columns and relations in the terse forms. Use `fromCol` / `toCol` only
+when the FK cannot be inferred from `ref` or the column name. `schema` on an
+entity, or `groups`, draws a panel around the entities that share it.
+Budget: 20 entities or 60 columns per block; `chiltepin check` warns past that.
+Split the model by domain.
+`erd`, not `uml`, for data at rest; `uml` for classes with behaviour; `dfd`
+for data in motion.
+
+### Other ways to write it
+
+A ` ```dbml ` or ` ```prisma ` fence, or a ` ```mermaid ` fence with
+`erDiagram`, parses into an `erd`. `chiltepin sync sql schema.sql --out
+docs/data-model.md` (or `sync dbml` / `sync prisma`) converts a schema file.
+The dialect subsets are in `reference/mermaid.md` (Input dialects).

package/templates/skill/reference/blocks/design-system.md

@@ -0,0 +1,50 @@
+# Chiltepin blocks — Design system & UI mockups
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Structure & emphasis — token specimens, usage rules, and low-fi
+screens (`palette`, `typescale`, `dodont`, `inventory`, `wireframe`).
+**Answers**: What does the UI look like before it exists? What tokens and
+styles exist, and what does correct use look like?
+**Not this family**: a real screenshot → `figure` (narrative.md); the
+component tree → `frontend` (architecture.md); component code → `code`
+(tables-data.md); shipped history → `changelog` (planning.md).
+
+### Design system
+
+#### `palette` — color-token swatches
+A card grid of swatches: the hex in mono, the token name, its usage. Text
+contrast on each swatch is automatic. Answers: which colour tokens exist,
+and what is each for? Always quote hex values (`"#0E54A1"`): an unquoted
+`#` starts a YAML comment. An invalid colour falls back to gray.
+`palette` for colour tokens; `stats` for numbers.
+
+#### `typescale` — a live type specimen
+One row per style; the sample text renders live at that size, weight, and
+font. Answers: what does each text style look like?
+Sizes over 64px render clamped at 64 but keep the true label.
+`typescale` when the visual matters; `table` for a token list with no visual
+payoff.
+
+#### `dodont` — do / don't guideline cards
+Two cards side by side, DO green and DON'T red; both lists are required.
+Answers: what does correct use look like? An item's `example` renders
+beneath it as a mono chip, good for label copy.
+`dodont` for usage rules; `proscons` to weigh a decision; `callout` for one
+warning.
+
+#### `inventory` — component / feature status board
+Hairline rows, each with a name, a tag chip, an optional note, and a
+colour-coded maturity chip. Answers: how mature is each component?
+`inventory` for maturity; `statustable` for task work; `changelog` for
+shipped history.
+
+#### `wireframe` — low-fi screen mockups (desktop / browser / phone)
+Device frames left to right, each a top-to-bottom stack of gray elements.
+Answers: what does the UI look like before it exists?
+`nav` and `tabs` read their items from a comma-separated `label`; quote it.
+`rows` repeats a list or card and sizes text or a spacer.
+Keep it low fidelity: a wireframe, not a comp. `figure` for a real
+screenshot; `frontend` for the component tree.

package/templates/skill/reference/blocks/flows.md

@@ -0,0 +1,74 @@
+# Chiltepin blocks — Flows, sequences & state
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Exchange — actors trading messages over time (`sequence`) and one
+request's time split across services (`spans`); Flow — steps and branches
+through a graph (`flow`, `dfd`, `swimlane`, `cycle`, `gitgraph`, `saga`);
+Modes — one object, discrete states (`state`); plus one Structure block for
+linear procedures (`steps`).
+**Answers**: What calls what, in what order? What happens when this fails?
+What states can it be in? What are the exact steps?
+**Not this family**: topology at rest → `c4` / `block` (architecture.md) or
+`graph` (charts-overviews.md); how much moves → `sankey` (charts-overviews.md);
+tasks with owner and status → `statustable` (planning.md).
+
+#### `sequence` — interaction over time (rich SVG + step list + footer)
+Lifelines, numbered arrows, frames, activation bars, a step list under the SVG.
+Answers: who calls whom, in what order? `sequence`, not `flow`, when the question
+is message order between actors. Short `label` on the arrow; detail in `summary`.
+`kind: note` is a box, not a message. Close every frame with `end` (`W_SEQ_FRAME`).
+Activation: `-> +B` opens a bar on B; `--> -A` closes the SENDER's bar. Only the
+first `-` closes, so inside an `alt` put the sign on the LAST branch's reply.
+#### `spans` — distributed-trace waterfall (where did the time go?)
+One lane per service, one bar per span on a shared time axis, nested by `parent`;
+the critical path takes the accent. Bars sit exactly where the span ran. Answers:
+how long did each call take, and which one did the response wait on? One request
+per block; the density check warns past 40 spans. `sequence` for order, not duration.
+#### `state` — state machine (+ transition table)
+States on a grid joined by event arrows, plus a transition table. Answers: what
+states can it be in, and what moves it? Give it one `kind: start` state and mark
+`terminal` states. `state`, not `flow`, for one object's discrete modes.
+#### `flow` — flowchart with decisions
+Start, process, decision, and end nodes with labelled edges; `variant: dag`
+frames it as a pipeline. Answers: what happens next, and what if the check
+fails? Flows run across, not down: the main path on `col` 1, 2, 3, branches
+on `row: 2`. Omit `col`/`row` for auto-layout (`dir: TB` works only there).
+A label that starts with no / fail / error / reject renders red. `groups`
+draw dashed zones over cell ranges. `flow`, not `sequence`, for branching.
+#### `dfd` — data-flow diagram
+External entities, numbered processes, and stores joined by labelled data
+flows. Answers: where does the data come from, and where does it land?
+`dfd`, not `flow`, when the arrows carry data rather than control.
+#### `gitgraph` — the branching and release model
+Commit dots on branch lanes, in the order the history happened. The first
+commit on a branch opens its lane; `merge: <branch>` closes that branch into
+the commit's branch; `tag` marks a release. Answers: how do branches fork,
+merge, and ship? `gitgraph` for branches; `timeline` for phases.
+#### `swimlane` — who does which step, in what order
+One lane per owner; a step names its lane by label (`lane: Sales`) and takes its
+column from the links (`col` only to pin one). `phases` bands the columns; `accent:
+true` marks the focal step. `flow` for one object's decisions; `sequence` for messages.
+#### `saga` — a distributed transaction and what runs backwards
+Forward steps left to right, the compensation under each, and the compensating
+flow drawn back from the failing step. Answers: what happens when step 3 fails?
+`failAt` derives every status (failed, compensated, skipped); set `status` only to
+override. Without `failAt` it draws the happy path. Keep it to 12 steps.
+`saga` for the transaction as a whole; `sequence` for the messages of one step.
+#### `steps` — a numbered how-to / runbook stepper
+A vertical stepper: title, body, an optional command on the dark surface, a note.
+Answers: what are the exact steps, in order? `steps` for a linear procedure a person
+runs; `flow` / `swimlane` when it branches; `statustable` when items carry status.
+#### `cycle` — a closed loop of stages arranged in a circle
+Stages clockwise from 12 o'clock, numbered, the last feeding the first; `center`
+labels the hub. 2–8 stages. Answers: what repeats? `cycle` when the process loops;
+`flow` when it branches and ends; `steps` for a one-shot procedure.
+#### `timing` — UML timing diagram
+One lane per lifeline stepping through `states` over a shared time axis
+(`from` … `to` in `unit`), `events` as instants, `constraints` as duration
+brackets. Answers: what state is each part in at time t, and how long does
+a phase last? `timing` when durations and overlaps are the point (a circuit
+breaker, a lease, a handshake); `state` for the transitions without time;
+`sequence` for message order; `spans` for measured traces.

package/templates/skill/reference/blocks/narrative.md

@@ -0,0 +1,65 @@
+# Chiltepin blocks — Narrative & prose
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Structure & emphasis — text that must stand out from the page
+(`callout`, `pullquote`, `bignumber`, `takeaways`), plus the document frame
+(`meta`, `divider`, `prose`, `figure`) and one Containment block (`layers`)
+for ordered conceptual tiers.
+**Answers**: What must the reader notice or remember? What does this term
+mean (`glossary`, `faq`)?
+**Not this family**: a row of KPIs → `stats` (tables-data.md); a procedure →
+`steps` (flows.md); weighing a choice → `options` (business.md) or
+`proscons` (planning.md); an ordinary bullet list → `list` (planning.md).
+
+### Narrative & prose
+
+#### `meta` — document cover (first block only)
+Title, subtitle, tag pill, and an optional logo (absolute https URL).
+Answers: what is this document? One `meta` per doc, always first; `divider`
+for a cover inside the doc.
+#### `prose` — structured prose (heading / paragraph / list / quote)
+Headings, paragraphs, lists, and quotes carried as data. Answers: what is
+the context? Plain Markdown outside blocks does the same job; use `prose`
+when the text must live inside a block, such as a `gallery` cell.
+#### `callout` — note / tip / warning / danger
+One aside with a tone band. Bare text with no `field:` lines is the body.
+Answers: what must the reader notice here? `callout` for one aside;
+`takeaways` for the closing list; `faq` for several questions.
+#### `glossary` — term / definition rows
+Term → definition rows. Answers: what does this word mean in this doc?
+The object form adds `avoid`, the words the doc must not use instead;
+`chiltepin check` flags an avoided word anywhere in the doc's prose
+(`W_PROSE_TERM_DRIFT`). This makes the glossary the approved term list.
+#### `figure` — an image with a caption
+A real image with alt text and a caption. Answers: what did it look like?
+`figure` only for screenshots, photos, and exports from other tools.
+Anything the renderer can draw belongs in a typed diagram block.
+#### `faq` — Q&A accordions (native details, no JS)
+One accordion per question; `open: true` starts one expanded. Blank lines in
+an answer become paragraphs. Answers: what do readers ask?
+`faq`, not `glossary`, for questions; `callout` for a single aside.
+#### `divider` — a full-width section break ("PART 2")
+A band with a mono kicker, a title, and a subtitle. Answers: where does the
+next part start? In a deck, put a `divider` alone under its own `##`
+heading and it becomes an interstitial slide.
+#### `bignumber` — one hero metric that carries the slide
+One value with a label, context, and a delta. Quote numeric-looking values
+(`"-75%"`). Answers: what is the one number? The trend arrow is neutral
+gray on purpose: "down" is often good. `bignumber` for ONE number; `stats`
+for a row of KPIs.
+#### `takeaways` — the 2-6 things to remember
+Numbered bold one-liners, each with an optional detail line. Answers: what
+should the reader remember? The natural closing slide of a deck.
+`takeaways` to close; `list` for ordinary bullets inside a document.
+#### `pullquote` — a standout quote
+Bare text is the quote; lead with `text:` / `attribution:` for fields.
+Answers: whose words frame this section? `pullquote` for a quote; `callout`
+for an aside.
+#### `layers` — a layered explanation (N numbered layers)
+Numbered tiers, each with a kicker, a source, a question, and a body.
+Answers: which tier answers which question? `layers`, not `table`, when the
+content reads as ordered tiers (an L1 / L2 / L3 model); `block` with
+`layers:` when arrows join the tiers.

package/templates/skill/reference/blocks/planning.md

@@ -0,0 +1,74 @@
+# Chiltepin blocks — Planning, lists & backlogs
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Time — what happened or is planned (`timeline`, `changelog`,
+`rollout`, `roadmap`, `chevrons`); Grid — one option weighed (`proscons`);
+work items and cards (`userstory`, `stories`, `kanban`, `storymap`,
+`statustable`, `risk`, `list`, `cvt`, `agenda`, `pattern`, `gallery`).
+**Answers**: What work exists, in what state, owned by whom? What shipped when?
+**Not this family**: bars against dates → `gantt`; verdicts → `options`; targets → `slo`.
+
+#### `userstory` — agile story + acceptance criteria + links
+One story as its own section: role / want / soThat, criteria, links. Use a short
+stable `id` (`US-142`); other docs reference it. `links[].ref` (`doc#id`) is a real
+cross-reference that `chiltepin check` verifies. Answers: what does done mean? `stories` for many.
+#### `timeline` — phases / roadmap
+Phases in order with a status dot each. Answers: what happens in which phase?
+`timeline` for plans ahead; `changelog` for history; `gantt` for bars.
+#### `changelog` — release history
+A rail with a dot per release (red for `tag: breaking`), a version pill, a date,
+and typed items. Newest first. Answers: what shipped when?
+#### `kanban` — flexible columns
+Named columns of cards (Now / Next / Later). Answers: what is in flight?
+`kanban` for work in flight; `storymap` for scope; `statustable` for status.
+#### `storymap` — user story mapping (backbone + release slices)
+Activities across the top; each release slice is a band of cards under the step
+they belong to. Each slice's `cells` carries exactly one entry per backbone step,
+in order; write `[]` for an empty step. Answers: what do we build, in what order?
+#### `rollout` — how a change ships, and what stops it
+Stages left to right with traffic share, hold time, and the gate that must pass
+before the next stage; the gate belongs to the stage it closes. `rollback` is the
+footer: the move, not the wish. Answers: what condition starts the next stage?
+#### `statustable` — task table with an update column + colored status pills
+Free cells under `columns`, then a Status pill per row; one level of `subtasks`.
+`statuses` is your label → colour vocabulary; built-in defaults are in progress,
+blocked, completed, todo, done. Any other status fails `chiltepin check`. A parent's status
+never rolls up. Answers: what state is each task in? `list` when items carry no status.
+#### `risk` — a risk register
+One row-card per risk; severity derives from likelihood × impact. Answers: what
+could go wrong, and who owns it? `swot` for strategic position.
+#### `cvt` — current vs target (before / after)
+Two side-by-side panels of items, today and target, with a note. Answers: what
+changes between now and the target? `options` when several targets compete.
+#### `proscons` — pros vs cons (two columns)
+Two columns weighing ONE option. Answers: is this one option worth it?
+`options` for several candidates with verdicts; `gallery` for side by side.
+#### `agenda` — meeting agenda
+Timed rows with duration, title, owner, and description. Answers: what happens
+when in this meeting? `agenda`, not `timeline`, for one meeting.
+#### `list` — a fancy bullet list (four marker styles)
+A bold lead plus text per item; `style` picks accent, check, icon, or number markers.
+Answers: what are the points? `statustable` when items carry status; `takeaways` to close.
+#### `stories` — a collapsible user-story backlog
+Every story as an accordion in one section; `open: true` expands one.
+Answers: what is in the backlog? `userstory` for one with its own section.
+#### `pattern` — a design-pattern reference card
+A GoF-style card: intent, forces, participants, consequences; only `name` is required.
+Answers: what does this pattern do and cost? Start from the pattern library in
+`reference/system-design.md`; pair with `felogic` (structure) and `sequence` (runtime).
+#### `gallery` — a responsive grid of cells
+A real grid (2 columns by default, `cols` up to 4). A cell is a note, a `code`
+snippet, or a nested `block`: a whole diagram checked against its own schema.
+Answers: how do these compare side by side? When the user says "compare X vs Y",
+put each side in a cell as a nested block (a `pattern` card or a diagram), not
+prose or a table. `gallery`, not `code` with `blocks[]`, for a grid.
+#### `chevrons` — process chevron strip
+2–8 chevrons left to right, `current` highlighted, a `desc` under each. Answers:
+what are the phases, and where are we? `steps` to execute them; `cycle` when it loops.
+#### `roadmap` — themes × periods
+`themes` as rows, `periods` as columns, items as status chips spanning
+`from` … `to`, `now` as a rule. Answers: what ships when, by theme? Coarser
+than `gantt` (no days, no dependencies); `kanban` when nothing is dated.

package/templates/skill/reference/blocks/quality.md

@@ -0,0 +1,43 @@
+# Chiltepin blocks — Quality & audits
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Verdicts with evidence. What is wrong now (`audit`), what passes
+and fails a standard (`checklist`), what is over budget (`perfbudget`), how
+long the tail is (`percentiles`), and what an attacker can do (`threatmodel`).
+**Answers**: What did the review find? Are we ready? Are we within budget?
+How slow is the slow path? Where can this be attacked, and what stops it?
+**Not this family**: what MIGHT go wrong → `risk` (planning.md); service
+targets over time → `slo` (tables-data.md); measured results side by side →
+`benchmark` (tables-data.md); where the time goes in one request → `spans`.
+
+#### `audit` — findings register
+Severity-ranked rows with evidence, fix, owner, status, and a count strip per
+severity. Answers: what did the review find, and how bad is it? One finding
+per row; `evidence` is what was observed (a path, a query, a log line), `fix`
+the change. `audit`, not `risk`, for defects found; `risk` for possibilities.
+`audit`, not `table`: the severity order and the counts are derived.
+#### `checklist` — pass / fail with evidence
+Items, or `groups` of items, each with a verdict and the evidence behind it;
+the footer derives the pass rate. Terse: `"[pass] item — evidence"` (quote
+it: the bracket is YAML flow syntax). Answers: are we ready, and what is
+missing? `checklist` for a standard applied once; `statustable` for work in
+flight; `list` with `check` markers when nothing is being verified.
+#### `perfbudget` — budgets vs measured
+One bar per metric against its budget mark; over / near / ok derived
+(`lowerIsBetter: false` for scores and throughput). Answers: are we within
+budget, and by how much? `perfbudget` for targets with a pass line;
+`benchmark` for candidates against each other; `stats` for KPIs with trends.
+#### `percentiles` — latency distribution per row
+p50 · p90 · p95 · p99 · max per endpoint on one axis, the SLO as a rule;
+`scale: log` for a long tail. Answers: how slow is the slow path? A p99 past
+the SLO is marked. `percentiles` for the tail; `chart` line for latency over
+time; `spans` for where the time goes inside one request.
+#### `threatmodel` — STRIDE on a data flow
+The dfd shapes inside dashed trust `boundaries`, `channel: plain` hops marked,
+and a `threats` table keyed to nodes or edges with the STRIDE letter.
+Answers: where can this be attacked, and what stops it? One trust boundary
+per block; put the mitigations in the table, not in prose. `threatmodel`,
+not `dfd`, when threats are the question; `audit` for what a review found.

package/templates/skill/reference/blocks/tables-data.md

@@ -0,0 +1,55 @@
+# Chiltepin blocks — Tables, metrics & code
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up).
+Run `chiltepin block <type>` for the fields and an example; block → family map:
+`INDEX.md`. Schemas reject unknown fields.
+
+**Shape**: Grid — two axes of exact values (`table`, `benchmark`) — plus
+Structure & emphasis for headline numbers, targets, and code as evidence
+(`stats`, `slo`, `code`).
+**Answers**: What are the exact values? How big, fast, or reliable is it,
+as measured?
+**Not this family**:
+
+- cells are permission levels → `matrix` (business.md)
+- a value grid read by intensity → `heatmap` (charts-overviews.md)
+- the numbers move over time → `chart` (charts-overviews.md)
+- scores you invented rather than measured → `scorecard` or `harvey`
+  (business.md)
+
+### Tables & metrics
+
+#### `table` — comparison table
+Rows × columns of exact values; a cell can carry a tone and emphasis.
+Answers: what are the exact values?
+`table`, not `matrix`, when cells are data rather than permissions; not
+`heatmap` when the reader needs the numbers rather than the pattern.
+
+#### `stats` — KPI / metric cards
+A row of cards: value, label, delta, and a trend arrow.
+Answers: how big is it right now?
+`stats` for a few KPIs with trends; `bignumber` for one hero number; `chart`
+when the numbers move over time; `envelope` for an estimate.
+
+#### `slo` — service-level objectives with error budgets
+One row-card per objective: SLI, target, current, window, and a burn bar.
+Answers: are we inside the error budget?
+`budget` is the fraction consumed (0–1): the bar turns amber past 0.5, red
+past 0.8, "exhausted" at 1. Omit it to skip the bar.
+`slo` for reliability targets; `okr` for goals; `stats` for plain KPIs.
+
+#### `benchmark` — measured results, side by side
+Subject columns × metric rows; the best cell per row is derived from the
+numbers and highlighted. Never bold a winner yourself. `better: low` flips a
+row (latency, cost); `better: none` turns the highlight off; `best: true`
+forces it for a tie. `variants` on a row stacks one value per condition and
+compares each condition on its own line. Answers: what did we measure?
+`benchmark` for measured numbers; `scorecard` or `harvey` for scores you gave.
+
+#### `code` — code the reader will copy or diff
+When the reader will copy or diff it, it is a `code` block, not prose or a
+table; when the change is the point, `kind: compare` or `kind: diff`.
+`highlight: "3-5, 8"` bands the lines that matter; `lines: true` numbers
+them; `cols: 2` sets snippets side by side (request / response); `kind:
+compare` is before / after under eyebrows; `kind: terminal` is a `session`.
+`steps` for a runbook with prose between commands; `gallery` for a card grid.

package/templates/skill/reference/check.md

@@ -0,0 +1,62 @@
+# Check and fix — step 7 of the procedure
+
+After you create or edit any doc, run the CLI and fix everything it reports.
+**A change is not done until `chiltepin check` passes.**
+
+```
+chiltepin check                       # validate all docs: schema + dangling refs + dup ids
+chiltepin check docs/orders-api.md    # validate one file
+chiltepin check --json                # machine-readable: every diagnostic with its code, file, line, value
+chiltepin check --strict-prose        # prose warnings become errors
+chiltepin block <type>                # the fields, enums, terse forms, and example for one block
+chiltepin html docs/orders-api.md -p  # render and open it (slides … -p for a deck)
+chiltepin new <name>                  # scaffold a whole doc (adr, runbook, …) or one block
+chiltepin build                       # static site (index + nav + cross-doc links) → dist/
+chiltepin sync openapi spec.yaml --out docs/api.md   # doc from an OpenAPI spec
+```
+
+Prefix every command with `npx -y chiltepin` when `chiltepin` is not on PATH.
+
+`chiltepin check` exits non-zero on any error and names the file, line, and
+offending value. Warnings never fail the check, but read each one: most name a
+real problem.
+
+## Error codes
+
+Every diagnostic carries a stable code. Apply the matching fix:
+
+| Code | Meaning | First check |
+|---|---|---|
+| `E_PARSE_YAML` | YAML body failed to parse. | Re-read *YAML pitfalls* in `writing.md`. Unquoted `,`/`:`/`#` in a `desc` is the usual cause. |
+| `E_PARSE_MERMAID` | A ` ```mermaid ` body has a line outside the supported subset; the message names the line. | Compare against `mermaid.md`. Fix the line, or write the block as typed YAML. |
+| `E_PARSE_DBML` / `E_PARSE_PRISMA` | A ` ```dbml ` / ` ```prisma ` body has a line outside the supported subset; the message names the line. | Compare against `mermaid.md` (Input dialects). Fix the line, or write the block as an `erd` in YAML. |
+| `E_SCHEMA` | A field is missing, wrong-typed, or unknown; the message contains the path. | Compare against `chiltepin block <type>`. Do not add undocumented fields — the schema is strict. |
+| `E_DANGLING_REF` | A `ref` points at an id that exists nowhere. | Fix the ref string, or add the missing `id:` to the target block. |
+| `E_SWIMLANE_LANE` | A `swimlane` step's `lane` matches no lane label, id, or index. | Use one of the lane labels the hint lists, exactly as written (case does not matter). |
+| `E_DUP_ID` | The same `id:` in two blocks; the message names both. | Ids are repo-global. Rename one. |
+| `E_BAD_REF_FORMAT` | A `ref:` is not `doc#id` or `#id` shape. | Match the format; the id slug is `[\w-]+`. |
+| `E_UNKNOWN_BLOCK` | A segment claims an unknown block type (rare — unknown fences normally fall through to plain code). | Use exactly one of the types `chiltepin block` lists. |
+
+Common `E_SCHEMA` shapes: `Expected string, received number` → quote the
+value (`tech: "16"`). `Invalid enum value` → use the documented enum only.
+`Unrecognized key(s)` → you added an undocumented field, or an unquoted comma
+in a flow-style mapping split a phrase into keys. `meta` fails → it must be
+the first block in the file.
+
+## Warning codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `W_EMPTY_BLOCK` | A typed block had an empty body. | Add fields or remove the block. |
+| `W_SUSPECT_BLOCK` | A fence tag is within typo distance of a real type (e.g. ` ```sequnce `); it rendered as plain text. | Rename the fence to the suggested type. |
+| `W_ALIAS_TYPE` | The fence uses one of the 12 old merged names. It parsed and rendered fine. | Nothing — both spellings work forever. Use the canonical name in new blocks; do not churn existing fences. |
+| `W_DENSE_BLOCK` | A diagram is past its density budget. | Split it into two focused blocks. A diagram past its budget reads worse than two. |
+| `W_EDGE_LABEL` | A `c4` relationship has no `label`. | Add the verb phrase that crosses the line; at container level add `tech` (the protocol). |
+| `W_LENS_REPEAT` | A third `callout`, or a fourth block of any other structural type, in one doc. | Merge them, or answer the third question with a different lens — the hint names the usual one. |
+| `W_PROSE_*` | A prose rule broke: a paragraph too long, a banned opener, a sentence that restates the block. | Apply the prose rules in `SKILL.md` and `style-ste.md`. Block text fields are exempt from the length cap. |
+| `W_DOC_CONVENTION` | The file path breaks the on-disk convention. | See `organizing.md`. Never rename a file only to silence this. |
+
+## The final read
+
+After the check passes, reread only the headings and block titles. The skim
+must still tell the story from step 1. Cut any section that reads as filler.