chiltepin 0.47.0

package/templates/skill/reference/patterns.md

@@ -0,0 +1,167 @@
+# Messaging and event patterns — which blocks draw them
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). Read
+this when the request is about events, queues, streams, fan-out, or making a
+write reliable across two systems. Each pattern names the reader question,
+the block stack that answers it, and the trap. Fields: `chiltepin block <type>`.
+
+Three rules hold for every pattern here:
+
+- Topology at rest is a `block` with `preset: event`. Producers are `kind:
+  producer`, subscribers `kind: consumer`, brokers `kind: topic` (fan-out)
+  or `kind: queue` (one taker), streams `kind: stream`. The single
+  `producer` takes the accent; put the fan-out in one column so the topic
+  reads as the hub.
+- One event's contract is an `eventcontract`, never a `table` row: it
+  carries producers, consumers, delivery, ordering, the partition `key`,
+  and retention, which is exactly what a consumer needs to be safe.
+- Time and failure are `sequence` (async arrows `-->` for the broker hop,
+  an `alt` frame for the failure branch) or `flow` (retry loops, decisions).
+  A `block` shows who is wired to whom; it cannot show a retry.
+
+## Publish / subscribe (fan-out to many)
+
+Question: when X happens, who reacts, and does the producer know them?
+Stack: `block` (`preset: event`) → `eventcontract` for the event → prose on
+delivery and ordering. Trap: a `sequence` with one arrow per subscriber
+hides the point, which is that the publisher has no arrows to them.
+
+```block
+preset: event
+groups:
+  - { id: subs, col: 3, row: 1, cols: 1, rows: 3, label: Subscribers }
+nodes:
+  - { id: orders, col: 1, row: 2, kind: producer, name: Orders, tech: order.placed }
+  - { id: t, col: 2, row: 2, kind: topic, name: order-events, tech: Kafka }
+  - { id: mail, col: 3, row: 1, kind: consumer, name: Email }
+  - { id: search, col: 3, row: 2, kind: consumer, name: Search index }
+  - { id: audit, col: 3, row: 3, kind: consumer, name: Audit log }
+edges:
+  - orders -> t: publish
+  - t -> mail
+  - t -> search
+  - t -> audit
+```
+
+## Competing consumers (one taker wins)
+
+Question: how does work spread across N workers, and how many times is a
+message handled? Stack: `block` (`preset: event`, a `queue` not a `topic`,
+the workers in one group, dashed edges to the workers that did not take
+the message) → `spec` for at-least-once and idempotency rules. Trap:
+drawing it as pub/sub; a queue delivers each message once.
+
+## Partitioned log and consumer group (streams)
+
+Question: how does the stream scale, and what keeps order? Stack: `block`
+(partitions as `queue` nodes inside a `Topic` group, consumers in a
+`Consumer group` group, the partition key on the producer edge) → prose on
+what the key is and what happens when a consumer joins or leaves. Trap: a
+`sequence`; the question is placement, not time.
+
+```block
+preset: event
+groups:
+  - { id: t, col: 2, row: 1, cols: 1, rows: 3, label: orders topic (3 partitions) }
+  - { id: cg, col: 3, row: 1, cols: 1, rows: 3, label: billing consumer group }
+nodes:
+  - { id: prod, col: 1, row: 2, kind: producer, name: Orders API }
+  - { id: p0, col: 2, row: 1, kind: queue, name: partition 0 }
+  - { id: p1, col: 2, row: 2, kind: queue, name: partition 1 }
+  - { id: p2, col: 2, row: 3, kind: queue, name: partition 2 }
+  - { id: c0, col: 3, row: 1, kind: consumer, name: billing-1 }
+  - { id: c1, col: 3, row: 2, kind: consumer, name: billing-2 }
+  - { id: c2, col: 3, row: 3, kind: consumer, name: billing-3 }
+edges:
+  - prod -> p0: "key = order_id"
+  - prod -> p1
+  - prod -> p2
+  - p0 -> c0
+  - p1 -> c1
+  - p2 -> c2
+```
+
+## Event-driven backbone (many producers, many consumers)
+
+Question: what is the shape of the whole event system? Stack: `block` in
+`layers` mode (Producers · Backbone · Consumers) with one `topic` node in
+the middle band → `table` of topics × producer × consumers × retention.
+Trap: drawing every topic as a node; past four topics the table carries
+it and the diagram shows the bands.
+
+## Outbox (reliable publish after a commit)
+
+Question: how do we never lose an event when the commit succeeds and the
+publish fails? Stack: `sequence` (API → DB writes row and outbox in one
+transaction; relay polls outbox → broker; `alt` for the broker being
+down) → `state` for the outbox row (pending → published → failed) → `spec`
+for the invariants (same transaction, at-least-once, consumer idempotent).
+Trap: a `block` alone; the pattern is an ordering of writes, so it needs
+time.
+
+## Dead-letter queue and retry (poison messages)
+
+Question: what happens to a message that keeps failing, and who looks at
+it? Stack: `flow` (consume → process → ok / retry with backoff / after N
+to the DLQ, `kind: error` on the DLQ edge) → `block` (`queue` → consumer
+→ `DLQ` queue) → `table` of failure classes × action × owner. Trap: a
+`sequence`; the loop and the threshold are decisions, not messages.
+
+## CQRS (separate read and write models)
+
+Question: why are reads and writes different shapes, and how does a write
+reach the read side? Stack: `block` (command side → write store → events
+→ projector → read store → query side, `dfd` also works) → `sequence` for
+one write and the eventual read → prose on the consistency lag and what
+the UI does about it. Trap: an `erd` of the read model; the reader asked
+for the split, not the columns.
+
+## Event sourcing (append-only log)
+
+Question: where is the truth, and how is current state rebuilt? Stack:
+`block` (commands → aggregate → event store, `replay` dashed back,
+projections subscribing) → `eventcontract` for one event → `spec` for
+replay, snapshots, and schema evolution. Trap: a `state` machine of the
+aggregate; the pattern is about storage, not lifecycle.
+
+## Saga (multi-service undo)
+
+Question: what happens when step three of five fails after steps one and
+two committed? Stack: `saga` (forward steps, compensation under each,
+`failAt`) → `sequence` only if the message order between services is the
+question → `table` of steps × compensation × idempotency key. Trap: a
+`flow`; a saga's shape is steps with their undo, which `flow` cannot say.
+
+## Scatter-gather
+
+Question: how does one request fan out to N workers and come back as one
+answer? Stack: `block` (coordinator → workers group → aggregator) →
+`sequence` with a `par` frame for the parallel calls and the timeout
+branch → `spec` for the partial-result rule. Trap: `flow`; the parallelism
+is the point and `par` draws it.
+
+## Backpressure, retry, and circuit breaker
+
+Question: what does the system do when a downstream slows or fails?
+Stack: `state` for the breaker (closed → open → half-open) or `flow` for
+retry with backoff and the give-up exit → `spec` for the numbers
+(timeout, attempts, backoff, jitter, trip threshold) → `sequence` only for
+the one call that shows the breaker opening. Trap: prose only; the
+numbers are the contract, and `spec` holds them.
+
+## Change data capture and webhooks (events out of a store or to a partner)
+
+Question: how do changes leave the database, or reach a partner, in
+order and exactly once as far as they can tell? Stack: `dfd` (table →
+log → connector → topic → consumers) or `sequence` (producer → partner
+endpoint, signed, retried, `alt` for 5xx) → `eventcontract` for the
+payload → `spec` for signing, retry, and replay. Trap: an `endpoint`
+block for a webhook; the partner's endpoint is not ours to document.
+
+## Idempotency
+
+Question: what happens when the same message or request arrives twice?
+Stack: `sequence` with the duplicate as a second message and an `alt`
+frame (key seen → return stored result) → `spec` for the key, its scope,
+and its TTL → `state` when the record itself moves (received → processed).
+Trap: a `callout` only; the reader needs the exact key and window.

package/templates/skill/reference/recipes.md

@@ -0,0 +1,153 @@
+# Composition recipes
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up).
+These are worked examples of composition, not forms to fill in. Two different
+systems must not produce structurally identical docs.
+
+Start from the reader
+questions, not from a recipe. Keep a block only if your system raises its
+question, and drop it if not. Add a block these stacks never mention when your
+system needs it. Fields: `chiltepin block <type>`; discriminators: the family files.
+
+Each recipe: the reader questions → the block stack in document order → the
+alternatives rejected, and why. The stack notes what each block carries and
+what the prose around it carries. Prose carries why, tradeoff, and consequence — never a
+description of the block beside it.
+
+## Backend architecture
+
+Reader questions: What are the boundaries? · What calls what on the critical
+path? · Who owns what?
+
+1. `meta` — the system's name and its one-line job.
+2. Prose — why the system exists; the one constraint that shaped the design.
+3. `c4` — ours vs external, one level only. Prose after: what the boundary
+   decision costs, not what the picture already shows.
+4. `cluster` or `block` (`preset: infra`) — the deployment topology. Prose
+   after: which parts fail independently.
+5. `sequence` — the one request path that pays the bills, with its failure
+   branch. Prose after: the consequence a client can rely on.
+6. `table` — service × responsibility × owner.
+7. `callout` — the invariant that must not break.
+
+Rejected: `uml` (class detail is the code's job) · `graph` (no boundaries —
+a backend doc is about what contains what).
+
+## AI / agent architecture
+
+Reader questions: What does the loop do? · What can it call? · What fills the
+window? · What does a real run look like?
+
+1. `meta` — the agent's name and the task it owns.
+2. Prose — the task delegated to the agent; where a human stays in the loop.
+3. `agentloop` — environment, tools, memory, stop condition.
+4. `context` — the window budget. Prose after: what gets evicted first, and
+   why that is safe.
+5. `prompt` — the contract the model is held to.
+6. `sequence` — one turn end-to-end, including a tool failure.
+7. `trace` — one real transcript, evidence the loop behaves as drawn.
+8. `callout` — the safety boundary the agent cannot cross.
+
+Rejected: `flow` (the loop is the primitive here, not a branch chart).
+
+## Frontend architecture
+
+Reader questions: What are the modules? · What states can the UI be in? ·
+Where does data come from?
+
+1. `meta` — the app and its rendering model in one line.
+2. Prose — the rendering-model decision (SSR/SPA/islands) and its cost.
+3. `frontend` or `felogic` — the module graph. Prose after: the dependency
+   rule the graph must keep.
+4. `wireframe` — the one screen that matters.
+5. `state` — the UI states, error and empty included. Prose after: which
+   state users actually sit in most.
+6. `sequence` — the data-fetch path.
+7. `table` — the routes.
+
+Rejected: `c4` (usually one container — a boundary diagram with one box says
+nothing).
+
+## Data flow / pipeline
+
+Reader questions: Where does data come from and go? · What shape is it at
+rest? · How fresh is it?
+
+1. `meta` — the pipeline and what depends on its output.
+2. Prose — why batch or stream; the cost of staleness in user terms.
+3. `dfd` (processes and stores) or `sankey` (when volumes are the story).
+   Prose after: the stage that loses or transforms data.
+4. `erd` — the shape at rest.
+5. `steps` — the backfill / replay procedure an operator runs.
+6. `slo` — the freshness targets the team commits to.
+
+Rejected: `sequence` (a pipeline has no request/response pairing to draw).
+
+Zone patterns compose — they are not block types. A medallion view
+(bronze → silver → gold) is `block` with `layers`: one layer per zone, one
+node per dataset with `tech` for format and retention, edges for the
+promotions. A deployment topology is `block` with `preset: infra` and
+`groups` for the account and network boundaries.
+
+## State machine
+
+Reader questions: What states exist? · What forces a transition? · What is
+illegal?
+
+1. `meta` — the object whose lifecycle this is.
+2. Prose — why these states exist; the invariant the machine protects.
+3. `state` — states and transitions.
+4. `table` — transition × guard × side effect.
+5. `sequence` — one path that exercises the risky transition. Prose after:
+   what a caller observes while it runs.
+6. `callout` — the illegal states, and why they must stay illegal.
+
+Rejected: `flow` (flows end; lifecycles loop back).
+
+## Incident writeup
+
+Reader questions: What happened, when? · Why did it break? · What did it
+cost? · What prevents recurrence?
+
+1. `meta` — incident id, date, severity.
+2. `timeline` — detection to resolution. Prose after: where the response was
+   slow, and why.
+3. `sequence` or `flow` — the failure mechanism, not the happy path.
+4. `stats` — the impact in numbers.
+5. `steps` — remediation, each step with an owner.
+6. `takeaways` — what the organization keeps from the incident.
+
+Rejected: `scqa` (a postmortem argues with evidence, not narrative).
+
+## ADR
+
+Reader questions: What forced a decision? · What were the options? · What did
+we accept by choosing?
+
+1. `meta` — the decision's id and title.
+2. Prose (Context) — the forcing fact, with a number in it.
+3. `options` — candidates against the criteria, verdict per card.
+4. `callout` (title "Decision") — the decision in one sentence.
+5. `proscons` — the consequences of the winner, both directions. Prose after:
+   the tradeoff the team explicitly accepts.
+6. `statustable` — the follow-up work the decision creates.
+
+Rejected: `harvey` (only when criteria resist numbers) · `scorecard`
+(weights imply a precision most ADRs do not have).
+
+## API reference
+
+Reader questions: What can I call? · What do errors look like? · How do calls
+compose?
+
+1. `meta` — the API and its version.
+2. Prose — auth model, versioning, base URL: what endpoint cards cannot
+   carry.
+3. `endpoint` × N — one card per operation, examples included.
+4. `sequence` — a multi-call workflow. Prose after: the ordering rule the
+   workflow depends on.
+5. `table` — the error codes and what the client should do about each.
+6. `glossary` — the domain terms the paths use.
+
+Rejected: `packet` (binary protocols only) · standalone `code` (snippets
+live inside the endpoint cards).

package/templates/skill/reference/style-ste.md

@@ -0,0 +1,119 @@
+# STE discipline — style rules for Chiltepin text
+
+Aerospace maintenance manuals follow rules like these so that a technician who
+reads English as a second language cannot read a step in two ways. Our failure
+mode is the same: text that looks fluent but means several things. These rules
+adapt ASD-STE100 Simplified Technical English to software documentation. They
+trade style for one property: each sentence has exactly one reading.
+
+## Vocabulary and terms
+
+- One word, one meaning. If `build` names a command, do not also use it for
+  the compiled output.
+- One concept, one word. If the doc says `endpoint`, it never says `route`,
+  `path`, or `handler` for the same thing.
+- Project terms live in a `glossary` block. That block is the approved term
+  list for the doc. For every term outside it, use ordinary English.
+- Prefer the short common word: use, not utilize; before, not prior to; end,
+  not terminate; about, not approximately.
+
+## Sentences
+
+- Length limits: instructions, 20 words at most; descriptive sentences, 25.
+- Write one instruction per sentence.
+- Instructions are always active voice: "Run `chiltepin check`", never "`chiltepin check`
+  should be run". Passive voice is allowed only in descriptive text, and only
+  when the actor is truly unknown or irrelevant.
+- Use simple tenses only: past, present, future. No perfect or continuous
+  forms.
+- Put the main action first and the condition after it: "Rerun the build if
+  the check fails."
+- Keep articles and relative pronouns: "Run the check that validates the doc",
+  not "Run check validates doc". When you drop these small words, the sentence
+  becomes ambiguous.
+- Keep noun clusters to 3 words at most. Write "the handler that refreshes
+  authentication tokens", not "authentication token refresh handler".
+- Do not use an -ing word as a noun or modifier where a verb or clause works.
+  Write "when the parser fails", not "on parsing failure".
+
+## Paragraphs
+
+- Descriptive paragraphs hold 6 sentences at most; procedural paragraphs, 3.
+- Give each paragraph one topic. Announce the topic in the first sentence.
+- Put warnings and prerequisites before the step they apply to, never after.
+
+## Where each level applies
+
+**Full STE** — procedural and machine-adjacent text: `steps` blocks, CLI help,
+`chiltepin check` diagnostics, error messages, MCP tool descriptions, and the skill's
+own instructions. A reader parses this text under pressure, and the reader is
+sometimes another model. Every rule above applies.
+
+**STE-lite** — `prose`, `callout`, and `pullquote` content, and plain Markdown
+paragraphs. Every rule applies except the restricted vocabulary. Prose carries
+tradeoffs and consequences; a controlled word list flattens that. Keep the
+sentence limits, active voice, and simple tenses, and keep one word per
+concept.
+
+**STE-lite, completeness first** — block text fields (`description`, `lede`,
+`body`, `note`, `subtitle`, `summary`). The form rules apply, but never delete
+a fact to satisfy a length rule. Split a long sentence into two sentences.
+Keep every component, value, and condition the field states.
+
+**Not applied** — marketing copy, changelog voice, code comments. Diagram data
+(node names, messages, edge labels, states, values) is never edited for style:
+the diagram is the data, and it must stay complete.
+
+## Worked pairs
+
+**Pair 1 — a restated diagram (docs/showcase.md:512).**
+
+```
+Before: A controller calls OrderService, which loads via an OrderRepository,
+charges through a PaymentGateway interface (Stripe/Adyen adapters), and
+egresses to Postgres, the event bus, and external gateways.
+
+After:  Payment providers sit behind one interface, so a Stripe outage is a
+config change, not a code change.
+```
+
+The before repeats what the diagram already shows. The after states the
+consequence that the diagram cannot show.
+
+**Pair 2 — a lede with three jobs (resources/orders-api.md:29).**
+
+```
+Before: Time runs downward. Solid arrows are synchronous requests; dashed are
+responses. The order row exists as PENDING only inside the transaction — it is
+CONFIRMED before commit, or rolled back to CANCELLED on decline.
+
+After:  An order is never visible as PENDING outside the transaction: it
+commits as CONFIRMED or rolls back to CANCELLED. Clients can treat every read
+as final.
+```
+
+The before teaches notation, describes arrows, and buries the invariant. The
+after does one job: the guarantee, and what it lets clients do.
+
+**Pair 3 — the wrapper opener (docs/showcase.md:9).**
+
+```
+Before: The blocks below are rendered from typed YAML fences. Edit the source
+.md file, rerun `chiltepin html`, and the HTML updates accordingly.
+
+After:  Edit a YAML block to change its diagram. Then run `chiltepin html`. The
+.md file is the only source; there is no rendered state to fix by hand.
+```
+
+The before is passive, restates the page, and stacks two instructions into one
+sentence. The after gives one instruction per sentence, plus the fact that
+makes the edit safe.
+
+## Constraints on how we use STE
+
+- ASD-STE100 is free to obtain but not free to redistribute. Never copy the
+  specification text or its ~900-word approved dictionary into this repo. We
+  apply the rules and keep our own term list.
+- Never claim Chiltepin output "is STE" or "is STE-compliant". Write
+  "STE-informed" or "follows STE writing discipline". Certified compliance
+  requires the real dictionary, and we do not ship it.

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

@@ -0,0 +1,161 @@
+# Designing systems — the design method & the architecture blocks
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). Read
+this for any architecture or design ask.
+
+## Designing a system — reason it, don't template it
+
+"Design an X" asks (a notification system, a rate limiter, "how would you build Y
+at scale") are where templating shows worst. Every real system's document
+is shaped by *its* bottleneck. Do the design reasoning; each step emits the block
+that carries it:
+
+1. **Requirements — ask, then pin them down.** Functional (what it does) and
+   non-functional (scale, latency, consistency, durability). If the user gave no
+   scale or constraints, **ask back** (move 1 of the method in `SKILL.md`; checklists in `intake.md`). Emit `drivers` — each driver a
+   real requirement with its consequence, never a platitude.
+2. **Envelope math.** Users × actions × fan-out → QPS, storage/day, peak factor.
+   Emit `stats` with the numbers that justify the architecture — skip when scale
+   genuinely isn't the story.
+3. **Contract.** The API surface (`endpoint` per route that matters) and the data
+   model (`erd`). These fix the names every later block reuses.
+4. **High level, shaped by the dominant motion.** Request/reply system → `c4`;
+   things flowing through stages → `block` (`preset: event`) or `dfd`;
+   deployment/regions/zones → `block` (`preset: infra`); a k8s estate →
+   `cluster`. One overview diagram of the whole system, using the real names
+   from step 3.
+5. **Deep-dive the bottleneck — this is where documents differ.** Work out what
+   actually breaks at the stated scale, and design *that* section:
+   - hot reads → caching + invalidation (a `sequence` of the miss path)
+   - write spikes → queue + backpressure (a `flow` with the shed path)
+   - fan-out → push vs pull (`options`, then the chosen `sequence`)
+   - cross-service consistency → outbox/saga (a `state` of the saga)
+   - geo-latency → replication + CDN (a `preset: infra` `block` per region)
+
+   One or two deep dives, chosen by the numbers from step 2 — never a fixed list.
+6. **Trade-offs on the record.** The genuine alternatives as `options` (with
+   `tone: chosen` on the winner), or `proscons` when only one option's tension
+   matters. A design doc with no rejected alternative wasn't a decision.
+7. **Failure & operations.** What breaks, the blast radius, how it degrades: a
+   `table` of failure modes → responses, `kind: error`/`forbidden` edges on the
+   diagrams, a `flow` of the degradation path.
+8. **Plan.** `timeline` for phasing, `statustable` for the open questions you
+   asked in step 1 but didn't get answered.
+
+**Patterns are ingredients, not the meal.** When a named pattern is load-bearing
+(pub-sub, saga, circuit breaker, CQRS, …), write it as a `pattern` card plus
+one structure diagram that fits it (`block` for system patterns, `felogic` or
+`uml` for code patterns, `flow`/`state`/`sequence` for agent patterns). Then
+**name every node in the user's domain**: a card whose participants are still
+"ServiceA" was pasted, not designed. Comparing patterns side by side → a
+`gallery` with a nested `pattern`/diagram per cell.
+
+The outline that falls out of steps 1-8 differs per system. A rate limiter's doc
+is mostly steps 4-6 with algorithmic depth (`state`, `code`). A social feed's is
+dominated by step 5 fan-out math, a payments integration by step 7 failure
+semantics. **If two of your design docs share the same section list, you skipped
+step 5.**
+
+
+## Architecture and topology (which one when?)
+
+| If you want to show… | Use | Notes |
+|---|---|---|
+| Who uses the system + which external systems it depends on | `c4` (level: context) | One node per actor / system |
+| Containers inside a system, with optional boundary box | `c4` (level: container) | Use `family` to colour-code (client / service / data / store) |
+| Components inside one container | `c4` (level: component) | Same shape, finer granularity |
+| Generic boxes-and-arrows architecture | `block` | Grid layout; add `groups` for dashed zones; add `layers` to switch to horizontal-band layout |
+| Cloud deployment (CDN, gateway, compute, DB, …) | `block` (`preset: infra`) | Same engine; the preset frames it for cloud topology |
+| Pub/sub event topology (producers → topics → consumers) | `block` (`preset: event`) | Same engine; framed for choreography |
+| Bounded-context map for DDD | `block` (`preset: ddd`) | Same engine; framed for context maps |
+| Security zones with trust boundaries | `block` (`preset: network`) | Same engine; supports `kind: forbidden` edges (red) |
+| Kubernetes-style namespaces with services inside | `cluster` | Has its own nested-box engine; supports `replicas` count |
+
+> Every `block` preset shares **one renderer** — presets differ only by the
+> colored tag pill above the diagram (ARCH / INFRA / EVENT / DDD / ZONES) and
+> the section eyebrow. Pick the preset that best signals intent to a reader;
+> the YAML grammar is identical. (The old type names `infra` / `event` / `ddd`
+> / `network` still work as permanent aliases.)
+
+**Quick mode — no coordinates.** Every architecture diagram can be written as
+just nodes + edges. Omit `col`/`row` on **all** nodes and the renderer computes a
+clean left-to-right layered layout from the edges. This is the default way to
+sketch a system fast.
+
+Add explicit coordinates only when you want a deliberate
+shape — and always when you use `groups`. Zones are anchored to grid cells, so
+they need placed nodes. If *any* node has coordinates but others don't, the
+auto-layout replaces all of them — place all or none.
+
+**Edge labels — dense diagrams renumber themselves.** On every edge-bearing
+diagram (`block` — any preset, `flow`, `dfd`, `graph`,
+`swimlane`, `uml`, `cluster`, `felogic`), up to three labelled edges
+render as text pills riding the arrows. At **four or more labelled edges** the
+renderer switches to circled step numerals and moves the label
+text to a numbered legend under the diagram. (`state` is the one exception —
+its numerals point at the transition table's rows instead of a second legend.)
+You don't opt in or lay anything out. Just keep edge labels short (a verb
+phrase, a couple of words) so they read well as a pill or a legend entry.
+
+**Node kinds** (block family; free strings — known ones get a colour + glyph):
+`client` · `service`/`microservice`/`compute`/`container` · `worker`/`etl` ·
+`db`/`store`/`database` · `bucket`/`blob` · `queue`/`mq`/`broker` · `stream` ·
+`cache` · `gateway`/`lb`/`proxy` · `function`/`lambda` · `cdn` · `dns` ·
+`waf`/`firewall`/`shield` · `auth`/`idp`/`iam`/`oauth`/`sso` ·
+`secrets`/`vault`/`kms` · `monitor`/`metrics`/`logs`/`tracing` ·
+`scheduler`/`cron`/`job` · `warehouse`/`lake` · `analytics`/`bi` ·
+`search`/`index` · `ml`/`model`/`llm`/`agent` · `vm`/`server`/`host` ·
+`user`/`person`/`browser`/`mobile` · `users`/`crowd` · `device`/`iot` ·
+`notification`/`webhook` · `email`/`sms` · `ci`/`cicd`/`pipeline` · `git`/`repo`
+· `registry` · `config` · `shard`/`sharded` · `replica`/`replicaset` ·
+`region`/`geo`/`globe` · `producer`/`topic`/`consumer` · `context` · `external`.
+**Vendor names work too**: `postgres`/`mysql`/`mongo`/`dynamo` → db, `s3` →
+bucket, `sqs`/`rabbitmq` → queue, `kafka`/`kinesis` → stream,
+`redis`/`memcached` → cache, `elasticsearch`/`opensearch` → search. Pick the
+closest kind — an unknown kind renders as a neutral box.
+
+**Kinds also pick the shape** (the canonical system-design silhouettes — you get
+the right one automatically by choosing the right kind):
+
+| Shape | Kinds |
+|---|---|
+| cylinder | `db` `database` `store` `postgres` `mysql` `mongo` `dynamo` |
+| tiered cylinder | `warehouse` `lake` |
+| pail (bucket) | `bucket` `blob` `object` `s3` |
+| **sharded trio** (3 small cylinders) | `shard` `shards` `sharded` |
+| **replica set** (stacked cylinders) | `replica` `replicas` `replicaset` |
+| horizontal cylinder (pipe) | `queue` `topic` `stream` `mq` `broker` `sqs` `rabbitmq` `kafka` `kinesis` |
+| cloud | `cdn` `external` |
+| hexagon | `gateway` `proxy` |
+| octagon | `lb` |
+| instance stack (receding cards) | `cache` `redis` `memcached` `worker` `etl` |
+| server rack (stacked slabs) | `vm` `server` `host` |
+| shield | `waf` `firewall` `shield` |
+| actor figure (boxless) | `user` `person` `actor` |
+| crowd (overlapping figures) | `users` `crowd` |
+| browser window | `browser` `web` |
+| phone frame | `mobile` |
+| circle with ƒ | `function` `lambda` |
+| calendar with clock badge | `scheduler` `cron` `job` |
+| padlock | `secrets` `vault` `kms` |
+| globe (boxless) | `region` `geo` `globe` |
+| clean rounded card + glyph | everything else |
+
+The same silhouettes apply inside `felogic` (db/store → cylinder,
+queue/bus/broker → pipe, cache → stack, external/backend/api → cloud), in `c4`
+(`kind: store` → cylinder), and in `cluster` (db services → cylinder). A
+database looks like a database in every diagram.
+
+**C4 extras.** Edges take `tech:` — rendered as `label [tech]`, the C4
+convention for the protocol. `boundaries[]` draws several named dashed boxes,
+each fitted around an explicit `nodes: [ids]` list (optional `color`) — so one
+diagram shows your platform and a partner's estate side by side. The single
+auto-fit `boundary:` still works for one system.
+
+**Mixing architecture views — one overview + one zoom.** Show the whole system
+once (`c4` context, or a `block` landscape), then zoom into the one or
+two places the doc is actually about. Zoom with `felogic` (or its `variant:
+be`) for a module's internals, a `preset: infra` `block` or `cluster` for
+deployment, and a `sequence` for the runtime of one path. Never redraw the same boxes in a
+second engine — pick one block per level of zoom and stitch them with prose
+("inside the `api` container: …").