chiltepin 0.47.0

package/templates/skill/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: chiltepin
+description: >-
+  Write, edit, validate, and render Chiltepin docs: Markdown with typed YAML
+  blocks for diagrams, API references, ADRs, runbooks, and slides. Use when
+  the user requests Chiltepin or the chiltepin CLI, or edits typed-block docs in a
+  Chiltepin project (chiltepin.config.*). Preserve an explicitly requested format;
+  installing this skill alone does not make every Markdown task a Chiltepin task.
+---
+
+# Chiltepin — docs as Markdown with typed YAML blocks
+
+A doc is plain Markdown. Anything structured — a diagram, a table, a plan — is
+a fenced block whose info-string is the block type and whose body is YAML.
+The `.md` file is the only source of truth. Never paste HTML or SVG. Never
+place pixels: the renderer owns layout, you own content.
+
+````
+## Request flow
+
+```sequence
+actors:
+  - { id: Client, name: Client }
+  - { id: API, name: Orders API }
+messages:
+  - Client -> API: POST /orders
+  - API --> Client: 201 Created
+```
+````
+
+## Fast path
+
+Use the project's installed CLI (`pnpm exec chiltepin` or `npx --no-install chiltepin`)
+to match its dependency version. Otherwise, `npx -y chiltepin …` downloads and
+runs the published CLI. In the Chiltepin source repo, use the built
+`node packages/cli/dist/bin.js`. The commands below show the fallback form.
+
+Detailed references live beside this file — read them on demand; the table
+at the end explains which reference each task needs.
+
+1. **Pick the blocks from the reader's question**, not from the words in the
+   request. Use the table below. For a full doc, two to five structural blocks
+   often suffice. A single diagram request needs only that diagram. Use prose
+   when a small list communicates the same information more clearly.
+   Unsure which block exists: `npx -y chiltepin block` lists all 107 block types.
+2. **Look up each block you will write**: `npx -y chiltepin block <type>`.
+   It prints the fields, enums, terse one-line forms, and a validating
+   example. Read a family selection sheet only when the choice remains unclear.
+3. **Write the doc.** For a full doc, put `meta` first (title, subtitle, tag). A `##` heading
+   above a block is its title. Prose carries why and consequence, never a
+   description of the block below it. Rules in the two sections after the
+   table.
+4. **Check**: `npx -y chiltepin check <file> --json`. Every diagnostic carries
+   a stable code and the failing value; `reference/check.md` maps each code
+   to its fix. Fix errors and rerun while you make progress. Stop and report
+   the blocker if a diagnostic repeats without a new fix or needs missing facts.
+   Warnings do not fail the check by default; review them and report relevant ones.
+   A non-zero exit is never "done". If the CLI is unavailable, report validation
+   as unverified. Never invent a successful check.
+5. **Render when asked**: `npx -y chiltepin html <file> -p` (page) or
+   `slides <file> -p` (deck).
+
+Handoff: the file path, actual check result, and any unresolved diagnostics.
+Explain block selection only when the user asks or a tradeoff needs explanation.
+
+Editing an existing doc: read it whole first. Change the one block, and
+carry the fact into related blocks within the requested scope. Preserve unrelated
+content. Rewrite the whole document only when the user requests a rewrite.
+
+## Pick the block by the reader's question
+
+| Reader question | Blocks | Choose by |
+|---|---|---|
+| What calls what? | `sequence` · `graph` · `c4` | ordered messages → sequence; topology at rest → graph or c4 |
+| What path does a request take through the infrastructure? | `block` · `c4` · `cluster` | tiers and hops → block; system context for a stakeholder → c4; namespaces and replicas → cluster |
+| What happens when this fails? | `flow` · `saga` · `state` · `sequence` | branching decisions → flow; multi-service undo → saga; one object's lifecycle → state |
+| Where did the time go? | `spans` · `sequence` | measured durations → spans; call order only → sequence |
+| What does the event carry, who emits and consumes it? | `eventcontract` · `table` | one event → eventcontract; a catalog → table |
+| Who publishes, who subscribes, how does work fan out? | `block` (`preset: event`) · `dfd` · `sequence` | topology of producers, topics, queues, consumers → block; the hop order with the failure branch → sequence; `reference/patterns.md` names the stack per pattern |
+| How does this ship, and what stops it? | `rollout` · `steps` · `timeline` | staged traffic with gates → rollout; manual procedure → steps; dated milestones → timeline |
+| What lives inside what? | `c4` · `cluster` · `block` · `layers` · `archmap` · `tree` · `composition` · `treemap` | runtime boundaries → c4/cluster/block; conceptual tiers → layers; capability landscape → archmap; part-of → tree/composition; area budget → treemap |
+| What changes over time? | `timeline` · `gantt` · `changelog` · `chart` · `slopegraph` · `state` | events → timeline; scheduled work → gantt; released work → changelog; a measured quantity → chart; two snapshots → slopegraph |
+| How do these options compare? | `options` · `proscons` · `matrix` · `scorecard` · `benchmark` · `quadrant` · `harvey` | criteria × candidates → options; one option → proscons; numbers → benchmark; two axes → quadrant |
+| Where does data go? | `dfd` · `sankey` · `erd` | processes and stores → dfd; volumes → sankey; shape at rest → erd |
+| Who does what, when? | `swimlane` · `journey` · `agenda` · `team` · `kanban` | ownership across steps → swimlane; experience over stages → journey; work in flight → kanban |
+| What are the exact steps? | `steps` · `flow` | linear → steps; branches or retries → flow |
+| What do we build, in what order? | `storymap` · `timeline` · `gantt` | scope per journey step by release → storymap |
+| How big, how fast, how much? | `bignumber` · `stats` · `chart` · `envelope` · `benchmark` | one headline → bignumber; a set → stats; napkin math → envelope |
+| What is this made of? | `anatomy` · `composition` · `erd` · `layers` | labeled parts of a string → anatomy; proportions → composition |
+| What causes this? | `fishbone` · `matrix` | one effect, branching causes → fishbone |
+| Why did we decide this? | `options` · `proscons` · `scqa` · `takeaways` · `callout` | the ADR shape → `reference/recipes.md`; the decision alone → callout |
+| What does the API accept and return? | `endpoint` · `code` · `packet` · `table` | HTTP surface → endpoint; wire format → packet; error codes → table |
+| How does the agent behave? | `agentloop` · `trace` · `prompt` · `context` | the loop → agentloop; one real run → trace; the contract → prompt; window contents → context |
+| What did the review find, and are we ready? | `audit` · `checklist` · `risk` | defects found with evidence → audit; a standard applied once → checklist; what might go wrong → risk |
+| Are we within budget, and how slow is the tail? | `perfbudget` · `percentiles` · `slo` · `benchmark` | targets with a pass line → perfbudget; p50…p99 per endpoint → percentiles; targets over time → slo |
+| Where can this be attacked? | `threatmodel` · `dfd` · `audit` | STRIDE on a data flow with trust boundaries → threatmodel; the flow alone → dfd |
+| Who uses the system for what, and which module may depend on which? | `usecase` · `pkg` · `uml` · `timing` | actors and cases → usecase; module dependencies → pkg; classes → uml; states over time with durations → timing; `reference/patterns-design.md` maps the GoF and distributed patterns to blocks |
+| What is the model's shape, and what may it be used for? | `neuralnet` · `modelcard` · `chart` | layers → neuralnet; the card → modelcard; loss curves → chart line |
+| What ships when, by theme, and where are we in the process? | `roadmap` · `chevrons` · `gantt` · `mindmap` | quarters × themes → roadmap; phases with the current one → chevrons; dated tasks → gantt; unordered ideas around a topic → mindmap |
+| What must always hold? | `spec` · `slo` · `glossary` · `callout` | invariants → spec; service targets → slo; terms → glossary |
+| What does the user see? | `wireframe` · `frontend` · `felogic` | screens → wireframe; component tree → frontend; module graph with edges → felogic |
+| How does the algorithm move through the data? | `array` · `linkedlist` · `bintree` · `hashmap` · `graph` · `code` | pointers, a window, or binary search over cells → array; pointer rewiring → linkedlist; a tree shape → bintree (never `tree`, that is a file hierarchy); hashing → hashmap; visit order → graph with node `state`; the reference implementation → code. A `flow` or `table` is the keyword trap here. |
+
+The type name is a hint, not a cage: a `quadrant` is any two-axis 2×2, a
+`journey` any staged progression, a `cvt` any before → after. Relabel every
+axis, column, and unit in the user's own nouns.
+
+Twelve old names still work as aliases (`infra` `event` `ddd` `network` →
+`block`, `belogic` → `felogic`, `dag` → `flow`, `waterfall` `funnel` →
+`chart`, `diff` `terminal` → `code`, `mece` → `tree`, `tracker` →
+`statustable`). Write the canonical name in new blocks; never rewrite an
+existing fence only to silence the `W_ALIAS_TYPE` warning.
+
+## Writing rules
+
+- Use only the fields `chiltepin block <type>` prints. Schemas are strict: an
+  unknown field is an error.
+- **Quote any YAML value that contains `,` `:` `#` `{` `}` or starts with a
+  special character.** Inside `{ a: b, c: d }` an unquoted comma splits a
+  phrase into keys. Numbers that must be strings (`version: "1.0"`, `delta:
+  "0"`) get quotes. Prose fields (`desc`, `note`, `summary`, `description`)
+  are always quoted. When unsure, write the body as JSON — it is valid YAML.
+- Prefer the terse one-line item forms the contract prints (`a -> b: label`,
+  `Term — definition`). Switch to the object form only for a field the
+  grammar cannot say.
+- Give a block an `id:` when another block references it; reference it as
+  `doc#id`, or `#id` inside the same doc. A ref to a missing id fails the
+  check.
+- Use the user's nouns verbatim, and the same name for the same thing in
+  every block. Headings say what the reader sees, never the block type.
+- **Vary the lens.** One `callout` per doc (the assumptions), never a row of
+  them: several points are a `list`, a `spec`, a `faq`, or `takeaways`. A
+  third block of the same type is a warning (`W_LENS_REPEAT`). Reach past
+  the habitual four (`callout`, `table`, `sequence`, `flow`): ownership
+  across steps is a `swimlane`; code the reader will copy or diff is a
+  `code` block (`kind: compare` for before / after); terms are a
+  `glossary`; questions a reader will ask are a `faq`; a runbook is
+  `steps`; side-by-side snippets or nested diagrams are a `gallery`.
+- Diagram data (node names, messages, labels, values) is never trimmed to
+  fit. Split a dense diagram into two; `chiltepin check` warns at the caps.
+- Every arrow says what crosses it, as a verb phrase, never "uses". A `c4`
+  edge without a label is a warning; at container level add `tech` too.
+  Solid is a call, dashed is async or optional. Flow runs left to right or
+  top to bottom, one direction per diagram.
+- `sequence`, `flow`, `erd`, `state`, and pie `chart` also accept a
+  ```mermaid fence; `erd` accepts ```dbml and ```prisma. Subsets are in
+  `reference/mermaid.md`.
+
+## Prose rules
+
+`reference/style-ste.md` is the authority. Between blocks: three sentences
+per paragraph by default, five at most. Every sentence carries a fact, a
+decision, or a consequence. Banned openers: "In this section", "This diagram
+shows", "It's important to note", "At a high level". Block text fields keep
+every fact in short active sentences. Diagram data is untouchable.
+
+## Read more only when the task needs it
+
+| File | When |
+|---|---|
+| `reference/blocks/INDEX.md` | Scanning every block with a one-line description (same as `chiltepin block`). |
+| `reference/blocks/<family>.md` | Choosing between neighbours in one family — discriminators and hard rules the schema cannot express. |
+| `reference/writing.md` | The full terse-form table, every YAML trap, `doc#id`, naming. |
+| `reference/check.md` | A diagnostic code you do not recognise. |
+| `reference/recipes.md` | Composing a whole document: architecture, ADR, API reference, incident, pipeline, agent system. |
+| `reference/patterns.md` | Anything with events, queues, streams, fan-out, outbox, CQRS, sagas, retries: which blocks draw each pattern and the trap. |
+| `reference/patterns-design.md` | A GoF or architectural design pattern (Strategy, Observer, CQRS, Circuit breaker …): the block stack that documents it. |
+| `reference/system-design.md` | Any "design an X" ask — the eight-step method. |
+| `reference/intake.md` | A new document with an unclear reader or scope — the questions to ask back. |
+| `reference/decks.md` | Any slides or deck ask. |
+| `reference/organizing.md` | Multi-doc work — file naming, splitting, index docs. |
+| `reference/exemplars/*.md` | Ten finished documents to model on. |

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

@@ -0,0 +1,141 @@
+# The 107 block types — by family
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, two folders up). One
+line per block, mapped to the family file that holds its selection guidance.
+For a block's fields and a validating example, run `npx -y chiltepin block
+<type>`; bare `chiltepin block` prints this same list. Twelve old block names
+remain valid as permanent aliases — see the table at the bottom.
+
+| Block | Family file | What it represents |
+|---|---|---|
+| `meta` | `narrative.md` | Document header — title, subtitle, tag pill. Always the first block. |
+| `callout` | `narrative.md` | A single aside: note / tip / warn / danger. |
+| `table` | `tables-data.md` | Genuinely tabular data (rows × columns of values); cells can carry tone. |
+| `sequence` | `flows.md` | Messages between actors **over time** (lifelines, returns); optional step list + endpoint pill. |
+| `erd` | `data-model.md` | Entity-relationship diagram — tables, views, enums, columns with key markers, schema groups, crow's-foot cardinality; also written as ```dbml / ```prisma. |
+| `userstory` | `planning.md` | An agile story: role / want / soThat + acceptance criteria + links. |
+| `timeline` | `planning.md` | Phases in order with status dots (done / current / next / future). |
+| `kanban` | `planning.md` | Flexible named columns (e.g. Now / Next / Later) of cards. |
+| `prose` | `narrative.md` | Structured prose (headings, paragraphs, lists, quotes) carried as data. |
+| `glossary` | `narrative.md` | Term → definition rows. |
+| `proscons` | `planning.md` | Two columns weighed against each other: pros vs cons. |
+| `cvt` | `planning.md` | Current → target (before / after) as two side-by-side panels. |
+| `stats` | `tables-data.md` | KPI cards — a value with a delta and an up/down/flat trend. |
+| `code` | `tables-data.md` | Code the reader will copy or diff — `highlight` line bands, `lines`, a `cols` grid; `kind: compare` before / after, `kind: diff` a unified diff, `kind: terminal` a shell session. |
+| `agenda` | `planning.md` | Meeting agenda — time, duration, owner, topic per row. |
+| `tree` | `charts-overviews.md` | An indented file/folder hierarchy (HTML, not SVG); `variant: issue` draws a MECE issue tree. |
+| `pyramid` | `charts-overviews.md` | A layered pyramid (strategy / hierarchy), widening top → bottom. |
+| `flow` | `flows.md` | A decision flowchart — start / process / decision / end nodes, with `error` exits; `variant: dag` frames it as a pipeline / DAG. |
+| `state` | `flows.md` | A state machine — states + event transitions (+ a transition table). |
+| `dfd` | `flows.md` | Data-flow — processes, external entities, and datastores. |
+| `journey` | `charts-overviews.md` | A user journey across stages, with an optional emotion curve. |
+| `gantt` | `charts-overviews.md` | A schedule — tasks as bars across date columns. |
+| `graph` | `charts-overviews.md` | A generic node-link graph with colour-cycled groups. |
+| `quadrant` | `charts-overviews.md` | A 2×2 matrix (e.g. effort vs impact) with plotted items. |
+| `swimlane` | `flows.md` | A cross-functional process with one horizontal lane per role. |
+| `c4` | `architecture.md` | C4 model (context / container / component) — people, systems, containers, stores. |
+| `uml` | `architecture.md` | A class diagram — attributes, methods, UML relationships. |
+| `frontend` | `architecture.md` | A top-down component tree — root / layout / page / component / provider / hook / store. |
+| `cluster` | `architecture.md` | Kubernetes-style namespaces holding services, with replica counts. |
+| `block` | `architecture.md` | Generic boxes-and-arrows architecture — grid **or** horizontal `layers`, `groups` zones that nest by `parent`, node `replicas`; `preset: infra \| event \| ddd \| network \| k8s` re-frames it for cloud, pub/sub, DDD, security-zone, or Kubernetes maps. |
+| `felogic` | `architecture.md` | Frontend module/logic graph — components, hooks, interfaces, strategies; group zones + egress edges; `variant: be` re-frames it for the backend (controller / service / repository / adapter). |
+| `wireframe` | `design-system.md` | Low-fi UI mockups inside device frames — desktop / browser / phone screens. |
+| `endpoint` | `api.md` | A Swagger-style API endpoint card — method, path, params, request body, responses, examples. |
+| `pullquote` | `narrative.md` | A standout pull-quote with optional attribution. |
+| `layers` | `narrative.md` | A layered explanation — N numbered layers, each a kicker / title / source / question + body. |
+| `matrix` | `business.md` | A role × resource capability grid; cells tint by permission level. |
+| `anatomy` | `business.md` | The labelled parts of a structured string (e.g. `app:feature:action`). |
+| `composition` | `business.md` | Effective access as intersected gates — `gate₁ ∩ gate₂ ∩ … = result`. |
+| `drivers` | `business.md` | A grid of factor/driver cards — icon + title + body + tag, the forces that shaped a design. |
+| `options` | `business.md` | Approaches explored — cards with pros / cons / verdict; the chosen one is highlighted. |
+| `spec` | `business.md` | A labelled spec sheet — `label → value` rows (a value can be an inline step-flow). |
+| `list` | `planning.md` | A fancy bullet list — bold lead + supporting line per row, in one of four marker styles (accent bar / check / icon / number). |
+| `stories` | `planning.md` | A collapsible backlog of user stories — many stories as `<details>` accordions in one section. |
+| `pattern` | `planning.md` | A design-pattern reference card — intent · forces · participants · consequences. |
+| `gallery` | `planning.md` | A responsive grid of cards — code snippets or notes (a bug gallery, a comparison grid). |
+| `chart` | `charts-overviews.md` | A data chart in pure SVG — `kind:` bar / line / area / donut / radar, plus `waterfall` (budget cascade) and `funnel` (conversion bands). |
+| `figure` | `narrative.md` | An image with a caption in a bordered card (optional pixel width cap). |
+| `steps` | `flows.md` | A numbered how-to / runbook stepper — title + body + optional command + note per step. |
+| `cycle` | `flows.md` | A closed loop of stages arranged in a circle — the last step feeds the first; descriptions become a numbered legend. |
+| `faq` | `narrative.md` | Q&A accordions — native `<details>`, question in the summary, answer expands. |
+| `envelope` | `business.md` | Back-of-envelope capacity math — assumptions, derivation rows, a highlighted bottom line. |
+| `slo` | `tables-data.md` | Service-level objectives — SLI, target vs current, and an error-budget burn bar. |
+| `benchmark` | `tables-data.md` | Measured results side by side — subject columns × metric rows, the best number in each row derived and highlighted; one column can be outlined as the focus. |
+| `swot` | `business.md` | A classic SWOT 2×2 — strengths / weaknesses / opportunities / threats as tinted quadrant cards. |
+| `okr` | `business.md` | Objectives + key results — one card per objective, a status-coloured progress bar per KR. |
+| `persona` | `business.md` | User persona cards — avatar, role, quote, goals, frustrations, tools. |
+| `changelog` | `planning.md` | Release history on a vertical rail — version pills, dates, and typed change chips. |
+| `team` | `business.md` | Compact people cards — initials avatar, name, role, focus area. |
+| `heatmap` | `charts-overviews.md` | A numeric grid with an intensity ramp — rows × columns of tiles tinted by value. |
+| `sankey` | `charts-overviews.md` | Flow volumes between stages — node height and ribbon thickness are the value, so the widest ribbon is where the volume goes. |
+| `gitgraph` | `flows.md` | A branching and release model — lanes for branches, dots for commits, curves where one forks and merges back; tags mark releases. |
+| `treemap` | `charts-overviews.md` | Proportional composition as nested tiles — area is the value, so thirty items stay readable where a donut gives up at six. |
+| `packet` | `api.md` | A wire format laid out bit by bit — fields wrap across rows of `width` bits, the way an RFC header diagram reads. |
+| `venn` | `charts-overviews.md` | Two or three overlapping sets with the shared regions labelled — scope, ownership, responsibility. |
+| `wardley` | `business.md` | A Wardley map — components placed by visibility to the user and by evolution (genesis → commodity), joined into a value chain. |
+| `harvey` | `business.md` | A rated comparison — options across the top, criteria down the side, a Harvey ball per judgement, and the recommended column marked. |
+| `scqa` | `business.md` | An executive summary in Minto order — situation, complication, question, and the answer the deck exists to deliver. |
+| `scenarios` | `business.md` | Base, upside and downside against the same drivers — assumptions in columns, the outcome each produces on its own row. |
+| `scorecard` | `business.md` | A weighted decision matrix — criteria rows × option columns, weighted totals, winner highlighted. |
+| `risk` | `planning.md` | A risk register — severity derived from likelihood × impact, with mitigation, owner, status. |
+| `palette` | `design-system.md` | Color-token swatches — name, hex value, and usage per color, on a card grid. |
+| `typescale` | `design-system.md` | A live type specimen — each row renders the sample text at its real size / weight / font. |
+| `dodont` | `design-system.md` | Do / don't guideline cards — what to do (green ✓) vs what to avoid (red ✕), with optional mono examples. |
+| `inventory` | `design-system.md` | A component / feature status board — name + color-coded status chip (stable · beta · experimental · deprecated · planned) per row. |
+| `array` | `algorithms.md` | Array cells for algorithm walkthroughs — tones, pointer labels below cells, a dashed index-window highlight. |
+| `linkedlist` | `algorithms.md` | A pointer-chain diagram (singly or doubly) — boxed nodes with next/prev arrows, markers like `head`/`curr`, a ∅ terminator. |
+| `bintree` | `algorithms.md` | A binary tree — nodes placed by `parent` + `side`, tinted to show search paths, traversals, heap shapes. |
+| `hashmap` | `algorithms.md` | Hash buckets with chained entries — collision chains read left → right as key/value pills. |
+| `agentloop` | `agentic.md` | The canonical LLM agent loop — environment → agent (model chip) → tools column, memory cylinder, numbered loop arrows, stop condition. |
+| `trace` | `agentic.md` | An agent / session execution transcript — user / assistant / tool / system turns, with `thinking` and tool `args` → `result`. |
+| `prompt` | `agentic.md` | Prompt anatomy — stacked role segments (system / user / assistant / tool) with `{{variable}}` chips and a variable legend. |
+| `context` | `agentic.md` | A context-window token budget — one stacked bar sized against the window, with free space and over-budget overflow. |
+| `archmap` | `architecture.md` | A target-architecture capability map — a mosaic of tinted domain areas packed with small status-coded capability tiles (current · target · new · gap · deprecated). |
+| `divider` | `narrative.md` | A full-width section break — kicker ("PART 2"), display title, optional subtitle on an accent-washed band; a clean interstitial slide in decks. |
+| `bignumber` | `narrative.md` | One hero metric at presentation scale — a display-size value with an optional delta + neutral trend arrow, a one-line claim, and a context line. |
+| `takeaways` | `narrative.md` | The 2-6 things to remember — numbered rows at presentation scale, each a bold one-liner with an optional detail; a deck's closing slide. |
+| `statustable` | `planning.md` | A task table — free columns (task / update) plus a colored status pill per row, from a user-defined label → color vocabulary; rows can nest one level of subtasks. |
+| `fishbone` | `charts-overviews.md` | Cause & effect (Ishikawa) — one effect at the head, cause categories as bones off the spine, specific causes along each bone. |
+| `storymap` | `planning.md` | User story map — the ordered backbone of activities across the top, release slices as rows of cards under each step. |
+| `eventcontract` | `api.md` | An async event contract card — name, version, channel, producers → consumers, delivery / ordering / retention, payload fields with the partition key marked; the twin of `endpoint`. |
+| `saga` | `flows.md` | A distributed transaction — forward steps left to right, the compensation under each, and the compensating flow drawn back from the step that fails (`failAt`). |
+| `slopegraph` | `charts-overviews.md` | Ranked before / after — one line per item between two labeled columns; the slopes show what rose, fell, or held. |
+| `spans` | `flows.md` | A distributed-trace waterfall — one lane per service, each span a bar on a shared time axis, nested by parent; the critical path is marked. |
+| `rollout` | `planning.md` | A progressive-delivery plan — stages left to right with their traffic share, hold time, and the gate each must pass; the rollback move as the footer. |
+| `neuralnet` | `agentic.md` | A layered neural network — one column per layer with unit counts, kinds, activations; dense mesh between layers. |
+| `modelcard` | `agentic.md` | An ML model card — identity, intended use, training data, metrics per split, limitations. |
+| `mindmap` | `charts-overviews.md` | A radial mind map — one centre, branches left and right, sub-branches per branch. |
+| `audit` | `quality.md` | An audit findings register — severity-ranked rows with evidence, fix, owner, status; counts per severity. |
+| `checklist` | `quality.md` | A pass / fail checklist with evidence per item; pass rate derived. `"[pass] item — evidence"`. |
+| `perfbudget` | `quality.md` | Performance budgets vs measured — one bar per metric with the budget mark; over / near / ok derived. |
+| `percentiles` | `quality.md` | Latency percentiles per row — p50 … p99 · max on one axis with the SLO rule. |
+| `threatmodel` | `quality.md` | A STRIDE threat model — data-flow shapes inside trust boundaries plus a threats table. |
+| `usecase` | `architecture.md` | A UML use-case diagram — actors, system boundary, use cases, include / extend / generalize. |
+| `pkg` | `architecture.md` | A UML package diagram — tabbed folders with members, dashed import / use dependencies. |
+| `timing` | `flows.md` | A UML timing diagram — lifelines stepping through states over time, with events and constraints. |
+| `chevrons` | `planning.md` | A process chevron strip — phases left to right, the current one highlighted. |
+| `roadmap` | `planning.md` | A roadmap — themes × periods with status chips spanning their periods and a "now" rule. |
+
+## Old names → canonical — the permanent aliases
+
+These 12 former block types merged into a canonical block. **The old spelling
+keeps working forever.** An alias fence parses to the canonical type with the
+listed fields injected (only for keys the body doesn't set). It renders
+exactly as it always did, and `chiltepin check` notes the mapping as a
+`W_ALIAS_TYPE` warning (warnings never fail a check). Write the canonical spelling in new
+blocks; don't rewrite existing fences just to silence the warning.
+
+| Alias | Canonical | Injected fields |
+|---|---|---|
+| `infra` | `block` | `preset: infra` |
+| `event` | `block` | `preset: event` |
+| `ddd` | `block` | `preset: ddd` |
+| `network` | `block` | `preset: network` |
+| `belogic` | `felogic` | `variant: be` |
+| `dag` | `flow` | `variant: dag` |
+| `waterfall` | `chart` | `kind: waterfall` |
+| `funnel` | `chart` | `kind: funnel` |
+| `diff` | `code` | `kind: diff` |
+| `terminal` | `code` | `kind: terminal` |
+| `mece` | `tree` | `variant: issue` |
+| `tracker` | `statustable` | `variant: tracker` |

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

@@ -0,0 +1,63 @@
+# Chiltepin blocks — AI & agents
+
+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 — four fixed frames for one LLM agent: the
+loop (`agentloop`), one real episode (`trace`), the contract (`prompt`), and
+the window budget (`context`).
+**Answers**: What does the loop do? What can it call? What is the model
+told? What fills the window? What did a real run look like?
+They compose — the AI / agent recipe in `reference/recipes.md` stacks all
+four.
+**Not this family**: the architecture around the agent (services, queues,
+vector stores) → `block` (architecture.md; `kind: llm` / `agent` gets the
+violet card); one turn's message timing between services → `sequence`
+(flows.md).
+
+### AI & agents
+
+#### `agentloop` — the canonical agent-loop diagram
+Environment left, agent card centre, tools stacked right, a memory cylinder
+below. Answers: what does one loop turn do, and what can the agent call?
+The four numbered arrows are fixed (prompt → tool call → result → response).
+List only tools the agent can call; the render shows 5 and folds the rest.
+The memory cylinder draws only when `memory:` is present.
+`agentloop` for the loop itself; `block` for the deployment around it.
+
+#### `trace` — an agent / session execution transcript
+A vertical transcript: one card per turn with a role chip (user, assistant,
+tool, system). Answers: what did one real episode do, step by step?
+Quote `args` and `result`: JSON braces and colons are YAML syntax. Block
+scalars (`|`) keep line breaks.
+`trace`, not `sequence`, to follow one conversation; `sequence` for the
+timing between services.
+
+#### `prompt` — prompt anatomy with variable highlighting
+Stacked segment cards with role kickers; every `{{variable}}` highlights as
+a chip. Answers: what is the model told, and where does each value come from?
+Quote any `text` that contains `{{ }}`: bare braces are YAML flow syntax.
+List each variable in `vars` so the legend explains it.
+`prompt`, not `code`, for templates and system prompts; `code` for programs.
+
+#### `context` — context-window token budget
+One horizontal bar sized against `window`, segments left to right, free space
+dim. Answers: what fills the window, and how much is left?
+A sum past `window` draws red past a dashed boundary with an "over budget"
+chip. Use it to show the failure case on purpose.
+`context` for token budgets; a waterfall `chart` for latency and cost.
+
+#### `neuralnet` — layered network
+One column per layer with `units`, `kind` (input / conv / pool / dense /
+attention / output …) and `activation`; dense mesh between layers, an
+ellipsis when a layer is wider than `maxUnits`. Answers: what is the model's
+shape? List the layers a reader would name, not every repeated block: fold
+"12 × transformer block" into one `attention` layer with a `note`.
+`neuralnet` for the architecture; `flow` (`variant: dag`) for the training
+pipeline; `chart` line for loss curves.
+#### `modelcard` — model card
+Identity, intended use and out-of-scope, training data, metrics per split,
+limitations, ethics. Answers: what is this model, and what may it be used
+for? The endpoint card for a model: one per deployed model version.
+`modelcard`, not `spec`, for a model; `benchmark` to compare candidates.

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

@@ -0,0 +1,49 @@
+# Chiltepin blocks — Algorithms & data structures
+
+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 — one data structure frozen at one step
+(`array`, `linkedlist`, `bintree`, `hashmap`). One step per block; freeze a
+moment, don't animate.
+**Answers**: What does the structure hold at this step, and where do the
+pointers stand?
+**Not this family**: graph algorithms (BFS / DFS / Dijkstra) → `graph` with
+node `state` + edge `weight` (charts-overviews.md); a file hierarchy →
+`tree` (charts-overviews.md); control flow → `flow` (flows.md).
+
+### Algorithms & data structures
+
+All four blocks share one `tone` enum: `active` is the element under
+examination, `visited` is processed, `target` is the goal, `muted` is out of
+play. Quote numeric values (`value: "19"`); they are strings.
+
+#### `array` — array cells for algorithm walkthroughs
+A row of square cells, indices above, pointer labels (`lo`, `mid`) below.
+Answers: where do the pointers stand at this step?
+`window` outlines a 0-based inclusive index range.
+`array`, not `table`, for binary search, two pointers, and sliding windows;
+`table` for tabular data.
+
+#### `linkedlist` — pointer-chain diagram
+Boxed nodes joined by arrows; the chain ends in a ground symbol.
+Answers: which node does each pointer hold during a reversal or insertion?
+`kind: doubly` adds a back-arrow per link. Pointer labels render above.
+`linkedlist`, not `flow`, for pointer manipulation; `flow` for control flow.
+
+#### `bintree` — binary tree
+Nodes placed by parent and side; a parent centres over its children, so an
+unbalanced chain slants. Answers: which path does a search or traversal take?
+Every node with a `parent` must set `side`. Two children on one side is a
+schema error. Several parentless nodes draw as side-by-side roots (rotations).
+`bintree`, not `tree`, for BSTs, heaps, and traversals; `tree` for file
+hierarchies.
+
+#### `hashmap` — buckets + chained entries
+A column of bucket slots; entries in one bucket chain rightward in entry
+order. Answers: where does each key land, and which keys collide?
+An entry whose `bucket` is outside `0..buckets-1` is skipped, not clamped.
+The render caps at 12 buckets; keep the count readable.
+`hashmap`, not `table`, for hashing and collision walkthroughs; `table` for a
+plain key-value listing.

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

@@ -0,0 +1,40 @@
+# Chiltepin blocks — API reference
+
+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 — one contract card per operation
+(`endpoint`) or per event (`eventcontract`) — plus Exchange at the byte
+level (`packet`).
+**Answers**: What can I call, with what, and what comes back? Who emits this
+event, who consumes it, and what does the payload guarantee? What does the
+wire carry, bit by bit?
+**Not this family**: how calls compose over time → `sequence` (flows.md);
+an error-code listing → `table` (tables-data.md); the API already has an
+OpenAPI spec → generate the cards with `chiltepin sync openapi`.
+
+### API reference
+
+#### `endpoint` — a Swagger-style API endpoint card
+One card per operation: method pill, path, parameters, body, responses, and
+example request and response. Answers: what can I call, with what, and what
+comes back? Only `method` and `path` are required.
+For a whole spec, run `chiltepin sync openapi` instead of writing cards by hand.
+`endpoint`, not `sequence`, for the contract of one call; `sequence` for how
+calls compose over time.
+
+#### `eventcontract` — an async event contract, the twin of endpoint
+One card per event: a producers → consumers strip, delivery facts as chips,
+and the payload table with the partition key marked. Answers: who emits
+this, who consumes it, and what does the payload guarantee?
+Only `name` is required. The card needs no title.
+`eventcontract`, not `endpoint`, when the channel is a topic or queue and the
+caller never waits for a reply.
+
+#### `packet` — a wire format, bit by bit
+A bit ruler across the top, then fields whose cell width is their bit count.
+A field that overflows its row wraps and is marked `(cont.)`. The footer
+totals bits and bytes. Answers: what does the wire carry, bit by bit?
+`packet`, not `table`, when position and width on the wire are the point;
+`table` for a field listing.

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

@@ -0,0 +1,94 @@
+# Chiltepin blocks — Architecture
+
+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**: Containment — boundaries and what lives inside them (`c4`,
+`block` + presets, `cluster`, `archmap`) — and Network for module, class,
+and actor graphs (`felogic`, `frontend`, `uml`, `usecase`, `pkg`).
+**Answers**: What lives inside which boundary? What depends on what, at rest?
+**Not this family**: the order of calls → `sequence` (flows.md); branching or
+a lifecycle → `flow` / `state` (flows.md); data shape → `erd` (data-model.md);
+tiers with no arrows → `layers`; area by number → `treemap`; a CI/CD pipeline
+→ `flow` with `variant: dag`.
+
+#### `c4` — context / container / component
+Boxes with kind chips inside dashed boundaries; the frame tag shows the
+level. Answers one question per level. `c4`, not `block`, when C4 levels and
+system boundaries carry the message; `sequence` for the order of calls.
+- `level` is required, and one diagram holds one level. Never mix levels.
+- Context: who uses it and what does it talk to. `person`, `system` (usually
+  one), and `external` only. 4–8 nodes.
+- Container: the deployable pieces. One `boundary` (or `boundaries[]`) is the
+  system; every container carries `tech`; persons and externals sit outside.
+  5–9 nodes; past that, split the diagram.
+- Component: inside ONE container, named in the title; `family` codes the layer.
+- Every edge is a sentence: `label` an active verb phrase, `tech` the protocol.
+  One arrow from the caller; the reply is implied. Async edges are `dashed`.
+- Externals are things you do not deploy. If your team owns it, it is a container.
+- Omit `col`/`row` on every node for auto-layout; `dir: TB` flips it.
+
+#### `block` — grid architecture with optional groups
+Boxes and arrows on a grid. Known `kind`s (db, queue, cache, gateway, cdn,
+and vendor names like postgres, s3, kafka, redis) get a glyph and a shape;
+an unknown kind draws a plain box. Answers: what talks to what, at rest?
+`block`, not `c4`, for free kinds, nested zones, and presets.
+- `gateway`, `lb`, `proxy`, and `ingress` draw as the tall vertical bar of
+  system-design diagrams. It spans the rows of the services it fans out to
+  on its own; set `h` to choose the span. Put the bar in its own column.
+- `preset` (infra, event, ddd, network, k8s) changes only the framing: the tag,
+  the eyebrow, and which kind is the accent entry. The YAML is the same.
+- Omit `col`/`row` on every node for auto-layout. Use coordinates for a
+  deliberate shape, and always with `groups`.
+- `layers:` switches to horizontal bands; nodes then use `layer`, not
+  `col`/`row`. Do not mix the two modes.
+- `groups` nest by overlap (the larger paints first) or by `parent`. A child's
+  cells must lie inside its parent's range (`W_GROUP_NESTING`).
+- `replicas: N` (2 or more) draws a stacked card. For a database replica set
+  use two nodes and a dashed `replicates` edge.
+- `preset: k8s`: a namespace is a group and `ingress` is the entry; nest
+  namespaces inside a cluster with `parent`.
+```block
+groups:
+  - { id: vpc, col: 1, row: 1, cols: 2, rows: 2, label: VPC }
+  - { id: pub, parent: vpc, col: 1, row: 1, cols: 2, rows: 1, label: Public subnet }
+  - { id: priv, parent: vpc, col: 1, row: 2, cols: 2, rows: 1, label: Private subnet }
+nodes:
+  - { id: alb, col: 1, row: 1, kind: gateway, name: ALB }
+  - { id: api, col: 1, row: 2, kind: service, name: orders-api, replicas: 3 }
+edges:
+  - alb -> api
+```
+
+#### `cluster` — k8s-style nested boxes with services
+Namespace boxes holding service cards with replica bars; a single `gateway`
+service takes the accent. Answers: which services run in which namespace?
+`block` with `preset: k8s` for nested namespaces or a mixed cloud + cluster map.
+
+#### `archmap` — target-architecture capability map
+A mosaic of tinted domain areas packed with capability tiles. A plain string
+is a current capability; `status` marks target, new, gap, or deprecated.
+Answers: what lives in each domain? `block` when the arrows between systems matter.
+
+#### `felogic` — frontend / backend module graph
+Module boxes with UML stereotype banners (interface, controller, service,
+repository) and typed edges. `variant: be` changes only the framing.
+Answers: which module uses or implements which? Omit `col`/`row` and
+`groups` for auto-layout. `felogic`, not `uml`, for a module graph.
+
+#### `frontend` — top-down component tree
+Parents above children with link paths, one `root`. Answers: how do the
+components nest? `frontend`, not `tree`, for a UI component tree with kinds
+(layout, page, hook, store).
+
+#### `uml` — class diagram
+Class boxes with attributes and methods; the relation `kind` drives the
+arrow marker. Answers: which classes inherit, implement, or depend on which?
+`uml`, not `erd`, for classes with behaviour; `erd` for tables and cardinality.
+#### `usecase` — UML use-case diagram
+Actors outside the `system` boundary, cases (verb phrases, ≤ 12) inside,
+`links` as `actor -> case`, `relations` `kind: include | extend | generalize`. Answers: who uses it for what?
+#### `pkg` — UML package diagram
+Tabbed folders with `contains` members, `parent` to nest, `deps` dashed with
+`kind: import | use | access | merge`. Answers: which module may depend on which?

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

@@ -0,0 +1,70 @@
+# Chiltepin blocks — Business, decisions & access
+
+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 — compare, score, locate (`matrix`, `scorecard`, `harvey`,
+`swot`, `scenarios`); cards for decisions, strategy, and access (the rest).
+**Answers**: How do the options compare, and which won? Who may do what?
+What forces shaped this design? Do the numbers pencil out?
+**Not this family**: measured numbers → `benchmark` (tables-data.md); one
+option's tradeoffs → `proscons` (planning.md); the decision in one line →
+`callout` (narrative.md); day-to-day task state → `statustable` (planning.md).
+
+#### `matrix` — a role × resource capability grid
+Rows are roles, columns resources, each cell a permission level tinted by meaning.
+Answers: who may do what? `matrix`, not `table`, when every cell is a permission.
+#### `anatomy` — the parts of a structured string (e.g. a permission)
+The full string with each segment coloured, then one card per segment.
+Answers: what does each part of this identifier mean? One string per block.
+#### `composition` — effective access as intersected gates
+Renders gate ∩ gate ∩ gate = result. Answers: which independent checks must
+all pass? `composition`, not `flow`, when access is an AND of checks rather
+than an ordered sequence.
+#### `drivers` — the forces that shaped a design
+A card grid, one card per driver with an icon and a tag; each is a real requirement
+with its consequence. Answers: why is the design like this? `list` for plain points.
+#### `team` — people cards (who owns what)
+Compact cards: initials avatar, name, role, one-line focus; set `initials` for a group.
+Answers: who owns what? `team` for real people; `persona` for user archetypes.
+#### `options` — approaches explored, with a verdict
+One card per option: how, pros, cons, verdict; `tone: chosen` marks the
+winner. Answers: which approaches did we weigh, and which won?
+`options`, not `proscons`, for several candidates; `proscons` weighs one.
+#### `scorecard` — a weighted decision matrix
+Criteria as rows, options as columns, a weighted TOTAL row; the winner is
+derived. Answers: which option scores highest? `scorecard` when the decision
+was scored; `options` for qualitative verdicts; `harvey` for judgements.
+#### `spec` — a labelled spec sheet
+A fact sheet for one approach or component; a row with `steps` draws a pill flow.
+Answers: what are the facts of this one thing? `spec`, not `table`, for one subject.
+#### `envelope` — back-of-envelope capacity math
+Givens, one derivation row per step, then a highlighted bottom line. Every
+value is a string; write units and `≈` freely. Answers: do the numbers pencil
+out? `envelope` for the estimate that justifies a design; `stats` for KPIs.
+#### `swot` — strengths / weaknesses / opportunities / threats
+The 2×2 draws itself from four string lists; an empty quadrant still draws.
+Answers: where do we stand? `swot` for a position; `quadrant` to plot items.
+#### `okr` — objectives + key results
+One card per objective, a progress bar per key result coloured by status.
+Answers: how far are we on each goal? `slo` for reliability; `statustable` for tasks.
+#### `persona` — user persona cards
+Cards with an avatar, role, quote, goals, frustrations, and tool chips.
+Answers: who do we build for? `persona` for archetypes; `team` for people.
+#### `wardley` — value chain against evolution
+Components plotted by user visibility (up) and evolution (right), both 0–1;
+`movement` draws where one is heading. Answers: what do we build, and what
+do we buy? A position on the map replaces an opinion.
+#### `harvey` — the rated comparison
+Options across, criteria down, a filled ball per judgement (0–4), a weighted
+footer. A short `ratings` row means "not assessed", not zero. Answers: which
+option fits best? `harvey` for judgements; `benchmark` for measured numbers.
+#### `scqa` — the executive summary, in Minto order
+Situation, complication, question as a ladder; the answer as the filled
+card with its support. Answers: what is the recommendation, and why?
+The order is fixed; keeping it is the block's job.
+#### `scenarios` — base, upside and downside
+Cases as columns, drivers as rows, the outcome in its own row; the base case
+is badged. A missing value renders `·`, not zero. Answers: how much of the
+outcome hangs on each assumption?