m0saic 0.2.1 → 0.3.0

package/node_modules/@m0saic/knowledge/docs/skills/passthrough-semantics.md

@@ -0,0 +1,136 @@
+## Passthrough & Carry Semantics
+
+`0` (passthrough) is the zero-frame donation primitive. Misused, a layout is either
+invalid (`PASSTHROUGH_TO_NOTHING`) or geometrically wrong. This doc covers donation
+mechanics, claimant/carry scoping, overlay behavior on zero-runs, the trailing rule,
+and the weighted-split encoding.
+
+> **Source of truth:** passthrough handling in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts)
+> and validator rules in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts).
+> Trailing-passthrough error code `PASSTHROUGH_TO_NOTHING` in [`errors/errors.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+> Validity examples below runtime-verified against https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/dist on 2026-07-27.
+
+## What `0` means
+
+`0`:
+
+- Consumes a split slot
+- Produces no rendered frame
+- Donates its space forward to the next claimant
+
+It does NOT render. It only contributes geometry.
+
+> Design intent: `0` exists primarily to encode weighted / percentage splits in a
+> deterministic integer-only way.
+
+## What is a claimant?
+
+A claimant is the first non-zero node after a run of `0`s:
+
+- `1` (tile)
+- `-` (null)
+- `N(...)` / `N[...]` (group)
+
+When a claimant appears:
+
+- It absorbs ALL donated space from the run
+- It absorbs its own slot
+- Its position snaps back to the start of the run
+
+## Donation run example
+
+    3(0,0,1)
+
+- First `0` → carry = 1 slot
+- Second `0` → carry = 2 slots
+- `1` appears → absorbs carry + own slot = 3 slots
+
+Result: the tile spans the entire width of the classifier.
+
+## Carry is scoped per classifier
+
+Carry does NOT leak outside the classifier body, and resets after each claimant:
+
+    7(0{1},1,0{1},1,1,1,1)
+
+Two separate runs:
+
+- Run 1: `0{1}` starts carry → first `1` absorbs the run
+- Run 2: new `0{1}` → fresh carry → next `1` absorbs it
+
+## Overlay behavior on `0`
+
+### `0{...}` targets the merged region so far
+
+    4(0,0{2(1,1)},0,1)
+
+1. First `0` — carry = 1 slot
+2. Second `0{2(1,1)}` — carry = 2 slots; overlay canvas = merged 2-slot region
+3. Third `0` — carry = 3 slots
+4. `1` — absorbs 4 slots total
+
+Overlay size is fixed at the moment it appears. Later carry growth does NOT resize
+earlier overlays.
+
+### Multiple zero overlays grow monotonically
+
+    5(0{1},0{1},0,0,1)
+
+- First `0{1}` → overlay spans 1 slot
+- Second `0{1}` → overlay spans 2 slots
+- Remaining `0`s → carry grows
+- `1` absorbs all 5
+
+Each overlay anchors to the region size at its creation time. Zero-overlay prefix
+geometry as a deliberate technique (progressive region staging, area-ordered
+layering) has its own doc: [`zero-overlay-analysis.md`](zero-overlay-analysis.md).
+
+## Trailing passthrough rule (`PASSTHROUGH_TO_NOTHING`)
+
+A trailing `0` inside a classifier is **always** invalid — even if it carries an
+overlay. No claimant absorbs the donation; an overlay on `0` does not change that.
+
+Invalid:
+
+    2(1,0)       — bare trailing passthrough
+    2(1,0{1})    — trailing passthrough with overlay (still invalid)
+    3(1,1,0{1})  — trailing passthrough with overlay
+    0{1}         — whole-string passthrough: no sibling exists to claim
+
+Valid:
+
+    2(0,1)       — passthrough donates to claimant
+    2(0{1},1)    — passthrough with overlay, not trailing
+    3(1,0,1)     — passthrough in middle position
+
+The rule applies recursively inside nested classifiers AND overlay bodies:
+`1{2(1,0)}` rejects with `PASSTHROUGH_TO_NOTHING`.
+
+## Weighted split encoding
+
+Zero-runs are how weighted splits are encoded. To encode a 60/40 split:
+
+    [60% region][40% region]
+
+DSL representation (conceptual pattern):
+
+    100( 59 zeros, 1, 39 zeros, 1 )
+
+The zero-run before each `1` encodes how much space that tile absorbs. Mechanical
+and deterministic.
+
+### The stdlib GCD-reduces this for you
+
+Never hand-roll the 100-slot form. `weightedSplit` (and the unified `split`
+transform's `weights` option) default to `mode: "optimized"`, which divides all
+weights by their GCD before emitting slots:
+
+    weightedSplit([60, 40], "col")     →  5(0,0,1,0,1)   — not 100(...)
+    weightedSplit([50, 25, 25], "col") →  4(0,1,1,1)
+
+Verified 2026-07-27: GCD reduction in
+[https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/weightedSplit.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/weightedSplit.ts):119–122;
+the `split` transform routes through the same reduction in
+[`buildSplitFragment.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/transforms/primitives/split/_internal/buildSplitFragment.ts)
+(default `mode = "optimized"`). `mode: "literal"` keeps raw weights (legacy);
+`precision` rescales weights to an exact slot budget first (largest-remainder).

package/node_modules/@m0saic/knowledge/docs/skills/structural-construction.md

@@ -0,0 +1,86 @@
+# Structural construction — emitting valid canonical m0
+
+Operational construction rules. The Handbook is canonical for grammar
+([`../handbook/dsl-rules.md`](../handbook/dsl-rules.md)) — this doc is the build-time
+checklist form of the same rules; on any conflict, the handbook wins.
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts)
+> and [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+
+## 1. Canonical output only
+
+Emit `1` not `F`, `0` not `>`, no whitespace; allowed characters: `0–9 ( ) [ ] { } , -`.
+Never emit pretty aliases.
+
+## 2. Numeric containers must match exactly
+
+`N(child1, …, childK)` requires `K === N`. No compression, no implicit slots, no
+empty classifiers (`2()`, `3[]` invalid). Build children first, count them, then
+prefix with N.
+
+Valid: `2(1,1)` · `3[1,0,1]`  Invalid: `2(1)` · `3(1,1)` · `2(1,1,1)` · `3()`
+
+## 3. First token rule
+
+A valid string starts with `1`, or a NUMBER > 1 followed immediately by `(` or `[`.
+`0`, `-`, `,1`, `{1}` are invalid openers. `1(...)` / `1[...]` is
+`ILLEGAL_ONE_SPLIT` — never wrap a single child in a pseudo-container.
+
+## 4. NUMBER must be followed by a classifier
+
+`2,1` and `2{1}` are invalid; `2(1,1)` and `2[1,1]` are valid.
+
+## 5. Overlay discipline — objects vs nesting
+
+- **At most one immediate overlay object per node**: `1{1}`, `2(1,1){1}`, `0{1}`,
+  `-{1}` valid; `1{1}{1}` invalid.
+- **Layer via nesting**: `1{1{1}}` — base tile, overlay subtree, overlay on the
+  overlay.
+- **Multiple overlay layers/regions via structure inside the body**:
+  `1{2(1,-){2(-,1)}}` — the overlay body is a container that owns its own overlay;
+  holes (`-`) isolate which regions show tiles. "One overlay object per node" does
+  not limit overlay depth.
+
+## 6. No trailing passthrough
+
+A trailing `0` inside a classifier is always invalid — **even with an overlay**
+(`PASSTHROUGH_TO_NOTHING`): `2(1,0)` and `2(1,0{1})` invalid; `2(0,1)` and
+`2(0{1},1)` valid. A passthrough must donate to a claimant; an overlay does not
+exempt it.
+
+## 7. Overlay bodies — valid, but sourceless is LEGAL
+
+Bodies validate recursively as full m0 sub-expressions. A body must contain at
+least one node, but it does NOT need a leaf `1` — the legacy `ZERO_SOURCE_OVERLAY`
+rule was **relaxed 2026-06-03** and is no longer raised
+(`m0StringValidator.ts:485`). Canonical overlay rules:
+[`overlay-semantics.md`](overlay-semantics.md).
+
+Invalid: `1{}` (INVALID_EMPTY) · `1{0}` (INVALID_EMPTY) · `1{2(1,0)}` (trailing
+passthrough in body)
+Valid: `1{1}` · `1{2(1,1)}` · `1{1{1}}` · `1{2(-,1)}` · `1{-}` · `1{2(-,-)}`
+
+## 8. No-sources rule
+
+The layout as a whole needs ≥1 leaf `1` (`NO_SOURCES`) — a source inside an
+overlay counts: `2(-,-)` invalid, `2(-,-){1}` valid.
+
+## Quick reference
+
+```
+VALID:    1 · 2(1,1) · 2(1{1},1) · 3[1,0{1},1] · 1{1{1}} · 1{2(1,-){2(-,1)}} · 1{-}
+INVALID:  0 · - · 2(1) · 2(1,1,1) · 1{{1}} · 1{1}{1} · 2(1,0) · 2(1,0{1}) · 1{} · 1{0} · 2(-,-)
+```
+
+## Construction procedure
+
+1. Decide the structure shape (tree of splits + leaves).
+2. Build child arrays per split; count them; prefix the exact numeric classifier.
+3. Attach at most one overlay object per node; get extra layers via nesting or
+   split/hole structure inside the body.
+4. Canonicalize.
+5. Validate with `isValidM0String` / `validateM0String` from `@m0saic/dsl`
+   (returns `{ok: true} | {ok: false, error}` — singular `error`).
+6. On failure: discard and rebuild. Never patch a broken string by hand — fix the
+   generator ([`m0saic-string-generation.md`](m0saic-string-generation.md) §3 has
+   the per-code repair moves).

package/node_modules/@m0saic/knowledge/docs/skills/text-in-templates.md

@@ -0,0 +1,126 @@
+# Text in templates
+
+How to put text into a template without it silently clipping.
+
+---
+
+## ⚠️ The rule that bites: nothing soft-wraps
+
+**No rasterizer in m0saic wraps text.** A long string in a single `MosaicTextLayer`
+renders as **one line and clips off the cell** — no error, no warning, no visual cue
+in the plan. It just disappears past the edge.
+
+This is true for **both** rasterizers:
+
+- `drawtext` (ffmpeg) has no soft-wrap.
+- `rasterizer: "svg"` converts glyphs to outlines via `@m0saic/text` — there is no
+  wrapping logic in that path either.
+
+**Any template that puts user-typed or composed strings into text MUST pre-break
+them.** Use `multilineTextLayers` (below); don't hand-roll.
+
+The failure is worst with user data — a title that fits every fixture and clips on the
+one real input nobody tested.
+
+---
+
+## The source shape
+
+A text tile is one `MosaicTextSource` per leaf cell:
+
+```ts
+{
+  type: "text",
+  style: { fontSize, fontColor, fontFamily },   // source-level, applies to all layers
+  layers: [ /* MosaicTextLayer[] — one per LINE */ ],
+  placement: { hAlign, vAlign },                // optional if layers carry their own
+  visual: { backgroundColor },                  // solid fill behind the text
+  renderMode: { kind: "image" },                // see below
+}
+```
+
+A `MosaicTextLayer` is
+`{ content: { kind: "literal", text } | { kind: "expr", expr }, style?, placement? }`.
+Layers stack within one source; each may carry its own `placement` (including a
+`yExpr`) to position itself in the cell.
+
+### Two orthogonal knobs — don't confuse them
+
+| Knob | Values | Question it answers |
+|---|---|---|
+| `renderMode` | `{ kind: "image" }` \| `{ kind: "video" }` | single RGBA frame, or an RGBA video for `ctx.target.durationMs`? |
+| `rasterizer` | `"drawtext"` \| `"svg"` | which mechanism turns glyphs into pixels? |
+
+**Choose the rasterizer on dynamism**, per `templates/patterns/perf-authoring-rules.md`
+**R9**: `svg` for static text (a mask + colour tile — no drawtext, no per-frame
+shaping), `drawtext` only when the text is genuinely per-frame dynamic. `svg` does
+**not** support expressions; the fallback to drawtext for those is correct. Read R9
+before scaling up — it carries the density budgets (hundreds of glyph masks in one
+panel approach the argv wall) and the note that **the app fits text wider than the
+CLI**, so leave generous fixed-font margins.
+
+---
+
+## Helpers — use these, don't hand-roll
+
+All from `@m0saic/template-utils`:
+
+| Helper | Signature | Use |
+|---|---|---|
+| `multilineTextLayers` | `({ text, maxCharsPerLine, fontSize, lineHeightRatio?, hAlign? }) => MosaicTextLayer[]` | **The one you usually want.** Wraps and returns one centred layer per line, vertically stacked via `yExpr`. Feed straight into `layers`. |
+| `wrapText` | `(text, maxCharsPerLine) => string[]` | Greedy word-wrap by character count. Never splits a word. Use when you need the lines themselves. |
+| `makeErrorMosaic` | `(message, { width, height, title?, errorCode?, … })` | Fail-fast card that **also sets `engine.renderStatus = "error"`** — the UI disables Make, and the CLI exits **3** (RENDER DEGRADED) after writing the card. Use for invalid input, and **pass `errorCode`**: it is what lands in the `--report` sidecar's `renderErrorCodes` (omit it and the caller only sees `ENGINE_ERROR`). See `runtime/cli-usage.md` → "Exit codes". |
+| `makeStubMosaic` | `(label, { width, height, backgroundColor?, textColor?, note? })` | "STUB" placeholder. Auto-sizes the font. Does **not** mark an error — validate-only still passes. |
+| `animateNumbersInText` | `(text, { startSec, durationSec, ease }) => string` | Returns an `expr` that counts numbers up on intro (KPI / stat cards). |
+| `fadeInExpr` | `(startSec, durSec, ease?) => string` | Overlay-alpha expression for a timed fade-in. |
+
+> `multilineTextLayers` returns `[]` for empty input — **check and omit the source**
+> rather than emitting a text tile with no layers.
+
+> `makeErrorMosaic` vs `makeStubMosaic` is a real distinction, not a style choice:
+> error blocks the render path, stub does not. Reach for stub only when "not
+> implemented yet" is a legitimate state.
+
+Both size their cards from dimensions **you** pass — pass `ctx.target.{width,height}`,
+never `ctx.output` (see `rendering-model-contract.md` Rule 5b).
+
+---
+
+## Sizing
+
+`maxCharsPerLine` is coarse — glyph widths vary by font. Start from:
+
+```
+maxCharsPerLine = floor(cellWidthPx / (fontSize * 0.55))
+```
+
+and tune per font. **Scale `fontSize` to the cell** — `clamp(width / N, lo, hi)` —
+rather than hard-coding pixels, so the template survives a resolution change.
+
+### Canonical wrapped, centred text tile
+
+```ts
+import { multilineTextLayers } from "@m0saic/template-utils";
+
+function textTile(text: string, fontSize: number, bg: string, cellWidth: number) {
+  const maxChars = Math.max(8, Math.floor(cellWidth / (fontSize * 0.55)));
+  return {
+    type: "text" as const,
+    style: { fontSize, fontColor: "#ffffff", fontFamily: "Arial" },
+    layers: multilineTextLayers({ text, maxCharsPerLine: maxChars, fontSize }),
+    visual: { backgroundColor: bg },
+    renderMode: { kind: "image" as const },
+  };
+}
+```
+
+---
+
+## Related
+
+- **`templates/patterns/perf-authoring-rules.md` R9** — rasterizer choice + density budgets.
+- **`templates/construction-strategy.md`** — "Drawing shapes: SVG inline-mask on a
+  color source". Text is for *words*; never draw a shape with a glyph — ffmpeg drops
+  `▲`/`▼`/emoji as tofu.
+- **`templates/rendering-model-contract.md` Rule 5b** — size error/stub cards off
+  `ctx.target`.

package/node_modules/@m0saic/knowledge/docs/skills/zero-overlay-analysis.md

@@ -0,0 +1,87 @@
+# The `0{}` operator — phantom geometry, deferred paint
+
+`0` is a passthrough: it donates its space to the next claimant and renders nothing.
+`0{...}` is a passthrough whose overlay still renders: the base donates space as
+usual, but the body receives the accumulated carry rect and **paints on top of the
+claimant, deferred**. An element that gives its space away, then draws over the
+sibling that absorbed it. Trimmed 2026-07-27 from a longer essay (git history).
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts)
+> (+ `parse/sortDeferredOverlays.ts`). Basics: [`passthrough-semantics.md`](passthrough-semantics.md),
+> [`overlay-semantics.md`](overlay-semantics.md).
+
+## The four quadrants
+
+| | Owns space | Doesn't own space |
+|---|---|---|
+| **Paints** | `1` (tile) | `0{}` (phantom overlay) |
+| **Doesn't paint** | `-` (null gap) | `0` (passthrough) |
+
+`0{}` is the fourth quadrant: spatial accounting and visual presence, fully
+decoupled.
+
+## The mechanism (verified at runtime)
+
+`3(1, 0{1}, 1)` @ 1080×720 — three 360px slots; the `0` donates, the last tile
+claims 720px; the overlay body gets the merged carry rect and paints LAST:
+
+| Paint order | What | Rect | `logicalIndex` |
+|---|---|---|---|
+| 0 | first tile | `{x:0, w:360}` | 0 |
+| 1 | claimant (expanded) | `{x:360, w:720}` | 2 |
+| 2 | deferred zero-overlay | `{x:360, w:360}` | 1 |
+
+Note the split between orders: the overlay is `logicalIndex` **1** (encountered
+before the claimant in DFS) but paints **after** it. Build sources in logical
+order; paint order is derived.
+
+**Multiple `0{...}` before one claimant sort area-DESCENDING at flush** — widest
+paints first (background), narrowest last (top). `5(0{1},0{1},0{1},0,1)` @1000px:
+claimant 1000px paints first, then 600 → 400 → 200 on top. Free z-ordering from
+coverage, no z-index.
+
+**Rects grow monotonically:** each `0{...}` in a run captures the prefix sum of
+slot widths, anchored at the run start — `4(0{1},0{1},0{1},1)` @800px yields
+overlays at `{x:0, w:200/400/600}` under a full-width claimant. Concentric framing
+from pure geometry.
+
+**Trailing `0{}` is always invalid** — `PASSTHROUGH_TO_NOTHING`; an overlay does
+not exempt the donation from needing a claimant. `2(1,0{1})` invalid;
+`2(0{1},1)` valid.
+
+## The body is a full m0 sub-expression
+
+Splits, nulls, passthroughs, nested overlays — all legal inside `0{...}`, parsed
+into the merged rect like an independent document. So a phantom can carry an entire
+sub-layout: holes that let the claimant show through (`0{4(1,-,-,1)}`), stacked
+rows (`0{3[1,1,1]}`), thin gridline rules at precise offsets
+(`0{100[0,…,1,…,0,1,…]}`), even nested overlay depth (`0{2(1{1},1{1})}` — four
+sources from one zero-space element). Source count = whatever the body demands.
+
+## Patterns (one line each)
+
+- **Floating annotation** — grid-positioned callout over an expanded tile's region.
+- **Progressive reveal** — monotone widths + per-source `startAtSec`: layers peel
+  front-to-back.
+- **Gradient banding** — N phantoms at fractional widths, solid colors at
+  decreasing opacity.
+- **Watermark/badge** — a tiny phantom deep in a 100-split places a corner stamp;
+  content and stamp stay structurally independent.
+- **Conditional layer** — phantom sources honor `overlay.enable` windows: a flash
+  highlight with zero structural change.
+- **Debug overlay** — inject `0{1}` tints/labels during development; removing `{1}`
+  restores the bare `0` with geometry untouched.
+
+## When `0{}` is wrong
+
+- The layer should CLAIM space (push siblings) → use `1` or `-`.
+- The template has many sources and non-expert consumers → the logical/paint order
+  split confuses source mapping; keep `0{}` inside internal primitives.
+
+## For agents
+
+You will almost never need `0{}` — `1`, `-`, `0`, and `1{1}` cover ~99% of
+layouts. Reach for it only when all three hold: (1) a visual layer at a specific
+grid position, (2) painting on top of whatever fills that region, (3) claiming no
+layout space. When all three hold, `0{}` is the correct expression, not a
+workaround.

package/node_modules/@m0saic/knowledge/docs/templates/README.md

@@ -0,0 +1,65 @@
+# templates/ — the authoring surface
+
+Read as a path: **contract → build → verify → publish**. The required authoring
+process (add / deprecate / tests / registry) is the agent contract §10 — not
+duplicated here.
+
+## The path
+
+1. [`philosophy-and-contract.md`](philosophy-and-contract.md) — what a template
+   IS: the typed contract, ctx.target vs ctx.output, tiers, props-as-schema.
+   - **Defaults are part of the contract**: every optional boolean / closed-set
+     knob carries a `defaultProps` value, every plain string/number a default or
+     a placeholder — enforced inside `defineMosaicTemplate` (throws first-party).
+2. [`construction-strategy.md`](construction-strategy.md) — how to build one:
+   the Rect Thesis, styles, smell tests.
+   - **Constraints first.** Declare the props contract and the layout
+     constraints, THEN build, THEN check in a loop across canvases × prop
+     combinations; the build itself is the first gate —
+     [`standalone-pack-authoring.md`](standalone-pack-authoring.md) §0.
+3. [`geometry-recipes.md`](geometry-recipes.md) — the four placement recipes
+   (SNAP_PX · placeInsetPieces · placeOptimizedPieces · lattice ratio-grid).
+4. [`rendering-model-contract.md`](rendering-model-contract.md) — the 12-rule
+   output contract the engine holds you to.
+   - [`output-resolution-tree.md`](output-resolution-tree.md) — how top-level
+     duration / size / fps / format / audio resolve (user > template intent >
+     host hints > engine defaults); read before touching any of them.
+5. [`layout-contract.md`](layout-contract.md) — verify layout intent
+   (withLayoutContract / checkLayout / assertLayout). **Before the first
+   candidate** for anything that paints text: tag fitted text, declare
+   `textFits`, sweep `assertLayout` at the 7-canvas set in the gate test.
+
+## By topic
+
+- [`recursion-nested-rendering.md`](recursion-nested-rendering.md) — children,
+  bottom-up eval, nested-mosaic-as-clip-region.
+- [`data-pipeline.md`](data-pipeline.md) — fetcher / adapter / handle patterns +
+  the operational how-to.
+- [`render-lifecycle.md`](render-lifecycle.md) — the four entry points
+  (`render` required; `renderLite` / `renderCover` / `renderTutorial` opt-in),
+  the null-on-absent dispatch rule, and the onboarding-surface checklist.
+- [`capability-templates.md`](capability-templates.md) — self-fetch app-runnable
+  templates; renderLite rules.
+- [`emission-patterns.md`](emission-patterns.md) — non-pixel outputs (data /
+  sidecars / telemetry).
+- [`theming.md`](theming.md) — design tokens over the upstream channel.
+- [`ui-controls.md`](ui-controls.md) — the `picker` taxonomy + prop controls.
+- [`standalone-pack-authoring.md`](standalone-pack-authoring.md) — branded pack
+  playbook (alpine is the reference).
+
+## reference/ — lookup specs (types & builders)
+
+[`placement-props`](reference/mosaic-placement-props.md) ·
+[`prop type: json`](reference/json-prop-type.md) ·
+[`template flags`](reference/template-flags.md) ·
+[`grid builder`](reference/grid.md) · [`MosaicColor`](reference/mosaic-color.md) ·
+[`prop bindings`](reference/prop-bindings.md)
+
+## patterns/ — distilled experience
+
+- [`perf-authoring-rules.md`](patterns/perf-authoring-rules.md) — R1–R11, each
+  paid for by a measured incident. Read before shipping any template.
+- [`case-study-lessons.md`](patterns/case-study-lessons.md) — L1–L9 from the
+  early template generation.
+- [`primitive-extraction-pattern.md`](patterns/primitive-extraction-pattern.md)
+  — when/how to extract primitives (incl. Rule 7: verify NESTED).

package/node_modules/@m0saic/knowledge/docs/templates/capability-templates.md

@@ -0,0 +1,72 @@
+# Capability-tier templates
+
+The tier contract itself (what `{ tier: "capability", caps }` unlocks, default-deny
+caps, when to stay core) lives in [`philosophy-and-contract.md`](philosophy-and-contract.md).
+This doc carries the two shipped patterns that go beyond the contract: app-runnable
+self-fetch templates, and the `renderLite` preview rule.
+
+> **Source of truth:** capability declaration shape in
+> https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/defineMosaicTemplate.ts; the shipped exemplar
+> `@m0saic/github/weekly-pulse/v1` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/github/weekly-pulse/v1).
+
+---
+
+## App-runnable capability templates (self-fetch)
+
+The `.mosaicx`/cron chain (fetcher → adapter → runner) can't run from the Templates
+UI — the core runner is core-tier (mock/upstream only) and the live chain only exists
+as a `.mosaicx`. The shipped pattern: a single **capability-tier** template that IS the
+whole chain in one pickable unit — `@m0saic/github/weekly-pulse/v1`. It
+`fetch → derive → render`s itself when flipped to `source: "live"` (+ repo + token),
+and replays a frozen sample by default (network-free).
+
+- It's a **plain-object** `MosaicTemplate` (not `defineMosaicTemplate`) because it
+  returns a duration-follows-timings pipeline, so it skips the wrapper's
+  `assertTiming` (the CLI `make` path still applies assertTiming — a plain object
+  does NOT escape it there).
+- It reuses the runner's extracted `buildPulsePipeline`, so the app-runnable version
+  and the cron runner emit the identical beat pipeline.
+- A template can't be "core sometimes, capability sometimes" — the app-runnable live
+  version is a SEPARATE capability template, leaving the runner core-tier for the
+  cron path.
+
+### Live-mode clock exception
+
+An app-runnable capability template MAY read the wall clock for ONE thing: a
+live-mode default window (`props.window ?? lastFullWeek(now)`), documented as a
+deliberate exception to the clock rule (this template is non-deterministic in live
+mode by design). Pinning `window` or using the cron `{{lastFullWeek*}}` tokens keeps
+it deterministic. Replay mode never reads the clock. A `livePreview: true` escape
+hatch lets power users fetch real data into the geometric preview on demand.
+
+---
+
+## renderLite is PREVIEW-ONLY (RenderHero uses the real render geometry)
+
+> `renderLite` is one of FOUR render entry points, and it is not a capability-tier
+> feature — a core template may declare it too. The lifecycle contract for all
+> four (including the opt-in `renderCover` / `renderTutorial` onboarding
+> surfaces) is [`render-lifecycle.md`](render-lifecycle.md). This section keeps
+> the part that IS capability-specific: why a self-fetching template's stand-in
+> must never reach RenderHero, and the `renderable_ready` wiring that avoids it.
+
+`renderLite()` returns a stand-in (a themed "ready" card) so selecting a
+side-effecting template never runs its real work. It must feed ONLY the idle-state
+GeometricPreview — NEVER the render-progress hero (RenderHero), which would otherwise
+show the card while ffmpeg renders the real beats. Shipped wiring:
+
+- `templates:get` returns `hasRenderLite: typeof tmpl.renderLite === "function"` so
+  the host/UI knows a preview is a stand-in.
+- `templates:renderToFile`: right after the real `render()` (BEFORE ffmpeg's
+  `render_start`), for renderLite templates the host forwards the resolved renderable
+  via a `renderable_ready` renderEvent.
+- MakePage captures it as `liveRenderable` and flattens THAT into the hero filmstrip;
+  a stand-in preview never drives the hero. Until `renderable_ready` lands (a few ms)
+  or if it can't be flattened, the hero shows the neutral loader — never the card.
+  Core templates (no renderLite) are unchanged: their preview already IS the render
+  geometry.
+
+**Rule for authors/hosts:** if `render()` returns geometry structurally different
+from `renderLite()` (as any self-fetching capability template does), the host must
+not reuse the renderLite doc for render-progress; it must hook the real `render()`
+output.