chiltepin 0.47.0

package/templates/skill/reference/intake.md

@@ -0,0 +1,140 @@
+# Intake checklists — what to ask before writing
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). Use
+this in move 1 (*Understand the ask — and ask back*) of every new document.
+
+## The ask-back protocol
+
+1. **Identify the document type.** Match the ask to a checklist below (they
+   mirror the *Document playbooks* table in `SKILL.md`). No match → fall back to
+   the four generic questions: reader & moment · job · scope · form.
+2. **Collect the checklist and diff it against the ask.** Note which items the
+   user already answered — never ask for something they told you.
+3. **Ask everything at once.** Ask for every missing **CRITICAL** item in ONE
+   batched message of 2-6 pointed questions — never drip one question per turn.
+   Fold in a nice-to-have only when its answer would change the outline.
+4. **If the user is unavailable** (or the gaps are minor), proceed with explicit
+   assumptions. Add a `callout` (`tone: note`, title *Assumptions*) near the top
+   of the doc, listing each guess so every one is visible and correctable.
+
+Each checklist marks items **CRITICAL** (the document is wrong without them)
+vs *nice-to-have* (improves it, but safely assumable).
+
+> **Raw tabular data?** When the source material is a spreadsheet/CSV export,
+> don't hand-transcribe it into YAML — import it. `chiltepin sync csv <file>` prints
+> a ready-made `table` / `statustable` / `chart` fence (it auto-picks the
+> block and says why), and dropping the `.csv` onto the studio canvas inserts
+> the block in place. Ask for the export, not a screenshot of it.
+
+## API / endpoint spec
+
+- **CRITICAL** — the routes + methods to document (all of them, or which subset?).
+- **CRITICAL** — the auth model: scheme, token type, scopes/permissions per route.
+- Request/response examples — real payloads beat invented ones.
+- Error codes and what each means to the caller.
+- Rate limits (per key? per IP? headers exposed?).
+- Versioning scheme (URL, header, none).
+
+## System design
+
+- **CRITICAL** — functional requirements: what must the system do, for whom?
+- **CRITICAL** — scale numbers: DAU, writes/day, reads/day, data size and growth.
+- **CRITICAL** — latency and consistency targets (p95/p99; strong vs eventual, where).
+- Existing stack and constraints (languages, cloud, what's already built).
+- Budget envelope (infra spend, buy-vs-build appetite).
+- Team size and skill mix (shapes how much operational complexity is affordable).
+
+## Agent system
+
+- **CRITICAL** — the model(s) used, and where in the loop.
+- **CRITICAL** — the tools: each tool's name and what it actually does.
+- **CRITICAL** — stop conditions: when does the loop end, and what bounds it?
+- Memory strategy (none, scratchpad, vector store, summaries — and eviction).
+- One real transcript of a representative episode (for the `trace` block).
+- Eval criteria — how is "it works" measured?
+- Guardrails: input/output filtering, permissioning, human-in-the-loop points.
+
+## Architecture overview / onboarding
+
+- **CRITICAL** — the system inventory: the services/components and one line each.
+- **CRITICAL** — the one key request path a new joiner will touch most.
+- Owners — which team/person owns each piece.
+- Deploy topology (where it runs: regions, clusters, environments).
+
+## Runbook
+
+- **CRITICAL** — the trigger: which alert/symptom puts you in this runbook?
+- **CRITICAL** — the exact commands to run, verbatim (no "restart the service" hand-waving).
+- **CRITICAL** — the verification step: how do you know it worked?
+- Access needed (VPN, roles, break-glass credentials) before you start.
+- Escalation path — who to page when the runbook doesn't resolve it.
+- Rollback — how to undo the intervention if it makes things worse.
+
+## ADR
+
+- **CRITICAL** — the options actually considered (not a padded strawman list).
+- **CRITICAL** — the deciding constraint: which force actually picked the winner?
+- **CRITICAL** — status: proposed, accepted, superseded?
+- Consequences observed so far (if the decision already shipped).
+
+## Roadmap
+
+- **CRITICAL** — the horizon (quarter? half? year?).
+- **CRITICAL** — the milestones and what "done" means for each.
+- **CRITICAL** — current status per milestone/phase.
+- Owners per workstream.
+- Dependencies between items (and on other teams).
+
+## Design system
+
+- **CRITICAL** — the token source: actual color values, type sizes/weights, spacing.
+- **CRITICAL** — the component list with a status per component (stable/beta/…).
+- Usage rules — the do/don't guidance per token or component.
+- Contribution process — how a new component gets in.
+
+## Deck
+
+- **CRITICAL** — the audience (engineers? leadership? customers?).
+- **CRITICAL** — the time slot (5 minutes and 30 need different decks).
+- **CRITICAL** — the decision sought — what should the room say yes to?
+- The 3 numbers that matter (the exhibits hang off them).
+- Appendix depth — how much backup material to prepare.
+
+## Data model
+
+- **CRITICAL** — the entities and their relationships (with cardinality).
+- **CRITICAL** — lifecycle states: which records have a state machine, and what is it?
+- Volumes per table (rows now, growth rate).
+- Retention — what gets deleted/archived, and when.
+
+## Postmortem / incident
+
+- **CRITICAL** — the timeline: detection → mitigation → resolution, with times.
+- **CRITICAL** — the impact: who/what was affected, how badly, for how long.
+- **CRITICAL** — the root cause (the real one, not the first symptom).
+- Action items with owners (and due dates if agreed).
+
+## Reviewing an existing doc
+
+When asked to review (not write) a doc, walk this checklist top to bottom and
+report findings per item — worst first. Fix only what you were asked to fix.
+
+1. **Skim test.** Read only the `meta` title and the `##` headings: do they
+   tell one story (orient → big picture → detail → plan)? Headings that could
+   sit on any document mean it was templated.
+2. **One lens per beat.** No two blocks drawing the same boxes; no three
+   tables in a row where one wants to be a `matrix`, `list`, or diagram.
+3. **Thin blocks.** A block with fewer than ~3 rows/nodes should fold into
+   prose or a `callout`. An empty block is a `W_EMPTY_BLOCK` waiting to fire.
+4. **YAML pitfalls scan.** Unquoted `,` `:` `#` in `desc`/`note`/`summary`
+   fields, unquoted hex colors, unquoted `1:N` cardinality, numeric-looking
+   strings (`version: 1.0`, `delta: 0`) — the usual parse traps.
+5. **Refs.** Every `ref:` points at an id that exists; same-doc refs use bare
+   `#id`; blocks other docs might need carry an `id:`.
+6. **Title/heading agreement.** Each block's `title` and its `##` heading
+   sound like one author; the `meta` cover matches the doc's actual content.
+7. **Stale facts.** Counts, versions, dates, and status fields
+   (`timeline`/`statustable`/`inventory`) that no longer match reality — flag
+   them even when you can't verify the correction.
+8. **Close with `chiltepin check`.** A review isn't done until the doc validates
+   clean — report any diagnostic verbatim.

package/templates/skill/reference/mermaid.md

@@ -0,0 +1,216 @@
+# Input dialects — Mermaid, DBML, Prisma
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up).
+
+Three fence tags hold a body that is not YAML. The parser converts the body
+into a typed block at read time; validation and rendering are the same as
+for a YAML block. The Markdown file keeps the dialect text until an editor
+changes the block; an edit writes the block back as YAML under its
+canonical tag.
+
+| Fence | Block | Subset |
+|---|---|---|
+| ` ```mermaid ` + `sequenceDiagram` | `sequence` | below |
+| ` ```mermaid ` + `flowchart` / `graph` | `flow` | below |
+| ` ```mermaid ` + `erDiagram` | `erd` | below |
+| ` ```mermaid ` + `stateDiagram` / `stateDiagram-v2` | `state` | below |
+| ` ```mermaid ` + `pie` | `chart` (`kind: donut`) | below |
+| ` ```dbml ` | `erd` | [DBML](#dbml) |
+| ` ```prisma ` | `erd` | [Prisma](#prisma) |
+
+SQL DDL is **not** a fence dialect (a ` ```sql ` fence is usually a code
+sample). Convert a schema file with `chiltepin sync sql schema.sql --out
+docs/data-model.md`; `chiltepin sync dbml` and `chiltepin sync prisma` do the same for
+files.
+
+## The rule
+
+Write a dialect fence when you already have the text in that grammar and
+the diagram needs only what the subset can say. Switch to the typed YAML
+block when you need a field the dialect cannot say: `endpoint`, `foot`,
+`summary` / `code` / `note` on a message, `groups`, `guard`, node `kind`
+overrides, `accent`, `description`, `lede`, or an erd `dir` / relation
+`label`. Never mix: one fence is either dialect text or YAML.
+
+# Mermaid
+
+A ` ```mermaid ` fence whose first non-comment line is one of the five
+keywords above converts. Any other first line (`gantt`, `classDiagram`,
+`mindmap`, `gitGraph`, …) is not converted: the fence stays prose and
+renders as a plain code block, with no diagnostic. `%%` comment lines are
+ignored in every grammar.
+
+## sequenceDiagram
+
+- `participant A`, `participant A as Name`, `actor A as Name` → an actor
+  `{ id, name }`. Without `as`, the id is the name. An id used in a message
+  but never declared is added at its first use, in order, as Mermaid does.
+- Messages: `A->>B: text` sync · `A-->>B: text` response · `A-)B: text`
+  async · `A--)B: text` response · `A-xB: text` and `A--xB: text` error ·
+  `A->B:` sync · `A-->B:` response. The text after `:` is the label.
+- `Note over A,B: text`, `Note right of A: text`, `Note left of A: text` →
+  a message `{ from: A, to: B, kind: note }` (`to` is `A` for a one-actor
+  note).
+- `title Text` → `title`.
+- Fragments: `alt text` / `opt text` / `loop text` / `par text` /
+  `critical text` / `break text` → a frame open `{ frame, label }`; `else
+  text`, `and text`, `option text` → `{ else: text }`; `end` → `{ end: true }`.
+  The frame renders as a UML frame around its messages.
+- `A->>+B: text` sets `activate: true` on the message (a bar opens on B);
+  `B-->>-A: text` sets `deactivate: true` (the bar on B, the sender, closes).
+- Ignored: `autonumber`, standalone `activate X` / `deactivate X` lines, and
+  `rect` / `box` … `end` (the messages inside are kept; the coloured box is
+  lost).
+- Any other line is an error (`E_PARSE_MERMAID`, with the line number).
+
+## flowchart / graph
+
+- Direction: `TD` and `TB` → `dir: TB`; `LR`, `RL`, `BT` → `dir: LR`; none →
+  `TB`. The renderer lays the nodes out; Mermaid positions are not kept.
+- Node shapes: `A[text]`, `A(text)`, `A[/text/]`, `A[\text\]`, `A>text]`,
+  `A[(text)]`, `A[[text]]` → process. `A{text}`, `A{{text}}` → `decision`.
+  `A([text])`, `A((text))` → `start` when the node has no incoming edge,
+  `end` when it has no outgoing edge, otherwise process. A bare `A` uses the
+  id as its label. Quotes around a label are removed. Ids keep their Mermaid
+  spelling.
+- Edges: `A --> B`, `A -->|label| B`, `A -- label --> B`, `A -.-> B`,
+  `A -. label .-> B`, `A ==> B`, `A --- B`. A dotted edge (`-.->`) becomes
+  `kind: dashed`; a thick edge (`==>`) renders as a plain edge. `A --x B` →
+  `kind: error`. `A <--> B` is one edge from A to B.
+- Chains `A --> B --> C` and fans `A & B --> C` expand to one edge per pair.
+  `;` separates statements on one line.
+- Lost: `subgraph … end` framing. The nodes inside are kept; the box is
+  dropped, because `flow` groups need grid coordinates and the auto layout
+  has none. Add `groups` with `col` / `row` in a YAML `flow` block instead.
+- Ignored: `style`, `classDef`, `class`, `click`, `linkStyle`, `direction`
+  inside a subgraph, and `:::class` suffixes.
+
+## erDiagram
+
+- `A ||--o{ B : label` → a relation. Left ends `||` `|o` (one) and `}o` `}|`
+  (many); right ends `||` `o|` (one) and `o{` `|{` (many). One–one → `1:1`,
+  one–many → `1:N`, many–one → `N:1`, many–many → `N:M`. A `..` body sets
+  `identifying: false` (dashed); `--` is identifying. The label loses its
+  quotes; `""` means no label.
+- `A { type name PK "comment" }` → an entity with `columns: [{ name, type,
+  pk }]`. `FK` → `fk: true`, `UK` → `unique: true`, the `"comment"` →
+  `note`. An entity named only in a relation is added with no columns.
+  Names may be quoted: `"Order Line"`.
+- Ignored: `direction`.
+
+## stateDiagram / stateDiagram-v2
+
+- `[*]` becomes a pseudo-state node: `_start` (`kind: start`, the filled
+  dot) or `_end` (`kind: terminal`, the bullseye). `[*] --> A : event` and
+  `A --> [*]` are ordinary transitions from or to that node.
+- `A --> B : event` → `{ from, to, event }`. Without `: event` the event is
+  the empty string, which renders as an unlabelled arrow.
+- `state "Long name" as A` → `{ id: A, name: "Long name" }`. `A : text` sets
+  the name of A. A bare `state A` or an id used only in a transition is named
+  by its id.
+- `direction LR|TB` at the top level → `dir`.
+- Lost: composite states `state A { … }` are flattened. The inner states and
+  transitions are kept; the container box is dropped. An inner `[*]` gets
+  its own pseudo-state, `_start_A` / `_end_A`.
+- Ignored: `note … end note` blocks, one-line `note right of A : text`, `--`
+  concurrency separators, `<<fork>>`-style stereotypes, `classDef`, `class`.
+
+## pie
+
+- `pie`, optionally followed by `showData` and/or `title Text` on the same
+  line. `title Text` on its own line also works.
+- `"Label" : 42` → an item `{ label, value }`. Decimals are accepted.
+- Result: `{ kind: donut, title?, items }`.
+
+# DBML
+
+A ` ```dbml ` fence always converts to an `erd`. The subset:
+
+- `Table [schema.]name [as Alias] { … }` → an entity. A `schema.` prefix
+  sets `schema` (the renderer draws a panel per schema). Header settings
+  (`[headercolor: …]`) are dropped.
+- Column line `name type [settings]`. Settings: `pk` / `primary key` →
+  `pk`; `unique` → `unique`; `not null` → `nullable: false`; `null` →
+  `nullable: true`; `default: value` → `default` (quotes and backticks
+  removed: `` `now()` `` → `now()`); `note: '…'` → `note`; `ref: > t.c` /
+  `< t.c` / `- t.c` / `<> t.c` → a relation (below). `increment` and any
+  other `key: value` setting are dropped. A type with spaces must be
+  quoted (`"double precision"`); `varchar(255)` and `decimal(10, 2)` work.
+- `Note: '…'` (or a `Note: '''…'''` block) inside a table → the entity
+  `note`.
+- `indexes { (a, b) [unique, name: '…'] }` → `indexes` on the entity; a
+  single-column index sets `index` (or `unique`) on the column; `[pk]`
+  marks a composite primary key.
+- `Ref [name]: a.b > c.d` and the `Ref { … }` block: `>` many-to-one (`a.b`
+  is the foreign key, relation `N:1` from `a` to `c`), `<` one-to-many (the
+  key is on `c.d`), `-` one-to-one (`1:1`; the key goes on the side whose
+  column is not the primary key), `<>` many-to-many (`N:M`, no key).
+  Composite ends: `t.(a, b)`. Ref settings (`[delete: cascade]`) are
+  dropped. A referenced table that is never declared becomes an `external`
+  entity.
+- `Enum [schema.]name { value [note: '…'] }` → `enums` (value notes are
+  dropped).
+- `TableGroup name { t1 t2 }` → `groups`.
+- Skipped: `Project { … }`, sticky `Note x { … }`, `TablePartial`; `//` and
+  `/* … */` comments.
+- Any other line is an error (`E_PARSE_DBML`, with the line number).
+
+# Prisma
+
+A ` ```prisma ` fence always converts to an `erd`. The subset:
+
+- `model X { … }` → an entity; `view X { … }` → `kind: view`. A `///` doc
+  comment before the block → the entity `note`.
+- Field line `name Type[?|[]] @attrs`. A scalar or enum type → a column
+  (`String`, `Int`, `DateTime`, … as written; `String[]` keeps the `[]`;
+  `Unsupported("x")` → `x`). `?` → `nullable: true`. `@id` → `pk`;
+  `@unique` → `unique`; `@default(v)` → `default` (`uuid()`, `now()`,
+  `autoincrement()`, `"str"` unquoted, `dbgenerated("…")` unwrapped). A
+  `///` doc comment before the field → `note`.
+- A field whose type is another model is a relation field, never a column.
+  `@relation(fields: [a], references: [b])` marks `a` as the foreign key
+  (`ref: Model.b`) and adds the relation `N:1` from this model — `1:1` when
+  the key columns are unique. An optional relation field (`User?`) makes
+  the key column nullable. A relation `"name"` becomes the `label`. A list
+  on both sides with no `fields` (implicit many-to-many) → one `N:M`. The
+  back side of an explicit relation adds nothing.
+- `@@id([a, b])` → composite `pk`; `@@unique([...])` / `@@index([...])` →
+  `indexes` (single-column ones set `unique` / `index` on the column);
+  `@@schema("x")` → `schema`.
+- Dropped: `@map` / `@@map`, `@db.*`, `@updatedAt`, `@ignore` / `@@ignore`,
+  `onDelete` / `onUpdate`; `datasource`, `generator` and composite `type`
+  blocks; `//` comments.
+- Any other line is an error (`E_PARSE_PRISMA`, with the line number).
+
+# SQL DDL (`chiltepin sync sql`)
+
+Not a fence. `chiltepin sync sql schema.sql` prints an ` ```erd ` fence; add
+`--out docs/data-model.md` to write a doc and validate it. The subset:
+
+- `CREATE TABLE [IF NOT EXISTS] [schema.]name ( … )` with column
+  definitions: `name type` (multi-word and parenthesised types work:
+  `timestamp with time zone`, `numeric(10, 2)`, `int unsigned`, `text[]`),
+  then `NOT NULL` / `NULL`, `PRIMARY KEY`, `UNIQUE`, `DEFAULT expr` (kept
+  as text: `now()`, `'open'::order_status`, `CURRENT_TIMESTAMP`),
+  `REFERENCES t (c) [ON DELETE …]`, MySQL `COMMENT '…'` → `note`, MySQL
+  `ENUM('a','b')` → `enum`. Table constraints: `[CONSTRAINT n] PRIMARY KEY
+  (…)`, `UNIQUE (…)`, `FOREIGN KEY (…) REFERENCES t (…)`, MySQL `KEY` /
+  `INDEX (…)`. A table `COMMENT = '…'` option → `note`.
+- `CREATE [UNIQUE] INDEX … ON t (cols)`, `ALTER TABLE t ADD [CONSTRAINT]
+  PRIMARY KEY | UNIQUE | FOREIGN KEY …`, `CREATE TYPE t AS ENUM (…)` →
+  `enums`, `CREATE [MATERIALIZED] VIEW v [(cols)] AS SELECT …` → a `view`
+  entity (columns from the list or a simple select list), `COMMENT ON
+  TABLE | COLUMN … IS '…'` → `note`.
+- Postgres `"x"`, MySQL `` `x` `` and SQL Server `[x]` quoting; `--`, `#`
+  and `/* … */` comments; `$$` bodies. The `public` / `dbo` schema prefix
+  is dropped; any other prefix sets `schema`.
+- Dropped: `CHECK`, `AUTO_INCREMENT`, `GENERATED … AS IDENTITY`, `COLLATE`,
+  `CHARACTER SET`, `ON DELETE` actions, storage options. Every other
+  statement (`INSERT`, `GRANT`, `CREATE FUNCTION`, …) is skipped.
+- A `CREATE TABLE` the subset cannot read fails with its line.
+
+# Errors
+
+`E_PARSE_MERMAID`, `E_PARSE_DBML` and `E_PARSE_PRISMA` name the body line
+the subset cannot read. Fix the line to match the subset above, or rewrite
+the block as typed YAML. A dialect fence never produces `W_ALIAS_TYPE`.

package/templates/skill/reference/organizing.md

@@ -0,0 +1,118 @@
+# Organizing a documentation set
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). One
+doc is a story; a docs folder is a *library*. Use this when a project outgrows
+a single file — or when you're deciding whether it has.
+
+## Where files live
+
+| Path | What it holds |
+| --- | --- |
+| `docs/` (or the configured `docsDir`) | All docs. One group level: `docs/<area>/<doc>.md`. Deeper nesting is drift. |
+| `dist/` (the build default) | Generated output. Never commit it. |
+| `.chiltepin/` | Tooling state — `skill/` is the authoring skill. |
+| `chiltepin.config.json` | Project config, at the root. |
+| `resources/` (or any folder outside `docsDir`) | Demo and fixture docs. Not part of the built site. |
+
+Doc filenames are kebab-case slugs: lowercase a-z, 0-9, hyphens, `.md`. The
+path is the reference prefix (`doc#id`), so slugs are load-bearing. Put a new
+doc at `docs/<area>/<doc>.md` — `chiltepin check` warns (`W_DOC_CONVENTION`) when a
+name is not kebab-case or a doc sits deeper than one group level.
+
+## Four kinds of document
+
+Readers arrive with one of four needs, and a page that serves two of them
+serves neither (the Diátaxis split, used by Canonical, Python, and
+Cloudflare). Name the kind in `meta.tag` and keep each doc to one:
+
+| Kind | Reader need | Typical blocks |
+| --- | --- | --- |
+| Tutorial | learn by doing, start to finish | `steps`, `code`, `callout` |
+| How-to | get one task done now | `steps`, `flow`, `checklist` items, `table` |
+| Reference | look a fact up | `endpoint`, `table`, `erd`, `spec`, `glossary` |
+| Explanation | understand why it is this way | `c4`, `sequence`, `options`, `scqa`, `timeline` |
+
+A runbook is a how-to. An architecture overview is an explanation. An API
+doc is a reference; its "getting started" section is a tutorial and wants
+its own page once it passes three steps.
+
+## When to split into multiple docs
+
+One document = **one system (or one job) for one audience**. Split when any of
+these hold; otherwise stay in one file — a 4-block doc doesn't need a folder.
+
+- **Two audiences.** An integrator reference and a new-joiner explainer about
+  the same service are two docs, not two halves of one.
+- **Two systems.** The orders service and the notification pipeline each get a
+  doc, even if they talk to each other — connect them with refs, not by merging.
+- **Two jobs.** "How it works" (overview) and "what to do at 3am" (runbook)
+  read at different speeds. A runbook buried in an architecture doc won't be
+  found during the incident.
+- **The skim breaks.** If reading only the `##` headings no longer tells one
+  story (see move 2 in `SKILL.md`), the extra beats want their own doc.
+
+## Slugs — the path *is* the reference prefix
+
+A doc's **slug** is its path under the docs root without `.md`:
+`docs/payments/api.md` → slug `payments/api` → its blocks are referenced as
+`payments/api#some-id`. Renaming a file renames every ref to it, so:
+
+- **kebab-case** file and folder names (`getting-started.md`, not
+  `GettingStarted.md`).
+- **Folders are domains**, not types: `docs/payments/`, `docs/identity/` —
+  never `docs/diagrams/` or `docs/misc/`.
+- Name for the subject, not the format: `orders-api.md`, not `api-doc-v2.md`.
+- Avoid ids named like `section-*` — the renderer uses those for its own
+  section anchors.
+
+## The index / overview doc
+
+Give a multi-doc set a landing page — `docs/overview.md` (or
+`docs/<domain>/overview.md` per domain). It holds a `meta` block, 2-4
+sentences of prose on what the set covers, and one big-picture block (`c4`
+context or `archmap`). When the set is large, add a `table` or `list` of the
+other docs and the job each does. It's the doc a new reader opens first and the
+natural home for ids that many docs reference.
+
+## Cross-doc references
+
+- Ids are **repo-global unique** — `id: seq-place-order` can exist once across
+  the whole docs tree, so a ref always has exactly one target.
+- **Same doc → prefer `#id`** (survives file renames). Other doc →
+  `slug#id` (`payments/api#seq-charge`).
+- Point stories at the diagrams that realize them
+  (`userstory.links[].ref` / `stories.items[].links[].ref` — the ref-bearing
+  fields), rather than redrawing the diagram in the second doc.
+- Draw each diagram in the doc that *owns* it; every other doc links. When a
+  system changes, one block changes.
+- `chiltepin check` fails on dangling refs and duplicate ids across the whole set —
+  run it after any rename or move.
+
+## How `chiltepin build` and `chiltepin studio` (Site mode) consume the set
+
+The layout above is exactly what the site generator reads:
+
+- **`chiltepin build`** renders every doc under the docs root into a static site.
+  `index.html` is a card grid built from each doc's `meta` (title · subtitle ·
+  tag — another reason `meta` is never optional). Each doc becomes
+  `<slug>.html` (folders keep their nesting), and a sidebar lists every doc
+  with the current doc's sections expanded.
+- **Refs become links.** A `userstory`/`stories` link chip navigates to its
+  target block — same page or `other-doc.html#id` across pages. A dangling ref
+  degrades to a plain chip (and `chiltepin check` will name it).
+- **`chiltepin studio` Site mode** is the authoring loop: the studio mounts the
+  same site from memory under `/site/…` and rebuilds + reloads it on every
+  save. Switch the top bar to Site to browse it while you edit.
+
+So the organizing rules pay rent twice: a tidy tree reads well in the repo
+*and* ships as a navigable site with no extra configuration.
+
+## Importing instead of transcribing
+
+When a doc's data-table already exists elsewhere, import it rather than
+retype it. `chiltepin sync csv <file>` turns a CSV export into a ready-made
+`table` / `statustable` / `chart` block (`--out docs/<slug>.md` wraps it in a
+new doc). `chiltepin sync openapi <spec> -o docs/api.md` generates a whole API
+doc — with `--check` keeping it drift-free in CI. The studio accepts the same
+files by drag-drop. The imported result is a normal doc on disk: edit it,
+ref it, `chiltepin check` it like anything hand-written.

package/templates/skill/reference/patterns-design.md

@@ -0,0 +1,59 @@
+# Design patterns — which blocks document them
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). Read
+this when the request names a design pattern or asks "how is X structured".
+Every pattern here is the same stack, in this order:
+
+1. `pattern` — the card: intent, forces, participants, consequences. One
+   per pattern, always first.
+2. `uml` — the structure: participants as classes, the relation `kind`
+   carrying the meaning (`implements` for the interface, `composition` for
+   ownership, `dependency` for a call).
+3. `sequence` — the behaviour, only when the order of calls IS the pattern.
+4. `code` — the smallest real example, when the doc is for implementers.
+
+Fields: `chiltepin block pattern`, `chiltepin block uml`. Never draw a pattern as a
+`flow`: a pattern is a set of roles and their relations, not a procedure.
+
+## Gang of Four
+
+| Pattern | The structural fact `uml` must show | Add |
+|---|---|---|
+| Singleton | one class, a private constructor, a static `instance()` | — |
+| Factory Method | creator ↔ product interfaces, concrete pairs `implements` | — |
+| Abstract Factory | one factory interface, one family per concrete factory | `table` of families × products |
+| Builder | director `dependency` builder; builder `implements`; product built | `sequence` (build steps) |
+| Prototype | `clone()` on the interface, concretes `implements` | — |
+| Adapter | client → target interface; adapter `implements` target, `composition` adaptee | — |
+| Bridge | abstraction `composition` implementor; both have hierarchies | — |
+| Composite | component interface; leaf and composite `implements`; composite `composition` component (the self-reference) | `tree` of a real instance |
+| Decorator | decorator `implements` component AND `composition` component | `sequence` (the wrapping chain) |
+| Facade | facade `dependency` on each subsystem class; client sees one | `c4` component when it is a service boundary |
+| Flyweight | factory returns shared intrinsic state; extrinsic passed in | `envelope` (memory saved) |
+| Proxy | proxy `implements` subject, `composition` real subject | `sequence` (lazy load / access check) |
+| Chain of Responsibility | handler `composition` next handler (self) | `sequence` (one request through the chain) |
+| Command | command interface; invoker `composition` command; receiver | `sequence` (undo) |
+| Interpreter | expression interface; terminal / non-terminal `implements` | `tree` (a parsed expression) |
+| Iterator | iterator interface; aggregate creates it | — |
+| Mediator | colleagues `dependency` mediator, never each other | `sequence` |
+| Memento | originator creates memento; caretaker `composition` memento | `sequence` (save / restore) |
+| Observer | subject `composition` observers; `notify()` | `sequence` (one change, N updates); at system scale → `reference/patterns.md` pub/sub |
+| State | context `composition` state; concretes `implements` | `state` (the machine itself) |
+| Strategy | context `composition` strategy interface; concretes `implements` | `options` when the choice of strategy is the decision |
+| Template Method | abstract class with the skeleton; hooks overridden in subclasses | `steps` (the fixed order) |
+| Visitor | visitor interface with one `visit` per element; elements `accept` | `matrix` of visitors × elements |
+
+## Architectural and distributed
+
+| Pattern | Stack | Trap |
+|---|---|---|
+| Layered / Clean / Hexagonal | `pkg` (allowed `deps` between layers, `dependency` arrows only inward) → `block` for the runtime | `c4` alone hides the dependency rule |
+| Repository / Unit of Work | `uml` (interface + implementation) → `sequence` for one transaction | `erd` (that is the data, not the pattern) |
+| CQRS, Event sourcing, Saga, Outbox | `reference/patterns.md` | — |
+| Circuit breaker, Retry, Bulkhead | `state` (closed → open → half-open) or `timing` (breaker vs downstream over time) → `spec` for the numbers | prose only |
+| Cache-aside / Read-through | `sequence` with an `alt` (hit / miss) → `spec` for TTL and invalidation | `flow` |
+| Sidecar / Ambassador | `cluster` or `block` (`preset: k8s`) with the sidecar in the pod | — |
+| Strangler fig | `block` (facade in front of legacy + new) → `roadmap` for the migration by theme | `timeline` |
+| BFF (backend for frontend) | `c4` container view with one BFF per client → `endpoint` per BFF | — |
+| Microkernel / Plugin | `pkg` (core + plugin packages, `deps` inward) → `uml` for the plugin interface | — |
+| Pipes and filters | `flow` (`variant: dag`) → `dfd` when data shape matters | `sequence` |