@m0saic/knowledge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m0saic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @m0saic/knowledge
+
+The m0saic knowledge base, as plain Markdown: the **m0 handbook** (grammar,
+semantics, the geometry math), the **skills** (engine mental models and
+invariants), and the **template-authoring contract**. It is the same tree the
+m0saic maintainers' agents work from, generated from the monorepo with every
+internal reference rewritten to a public one.
+
+**If you are a coding agent about to write a template: read this file, then
+[`docs/m0saic-thesis.md`](docs/m0saic-thesis.md), then follow the router in
+[`docs/README.md`](docs/README.md).** Nothing here needs a build, a network,
+or a login.
+
+## Where it lives on disk
+
+- Installed: `node_modules/@m0saic/knowledge/docs/` — the template repo
+  starters list this package as a devDependency, so `npm install` puts it
+  beside your code.
+- On GitHub: [`m0saic-project/m0saic-packages/packages/knowledge`](https://github.com/m0saic-project/m0saic-packages/tree/main/packages/knowledge).
+
+## Authority order
+
+1. `docs/handbook/` — canonical truth for the m0 language and its geometry.
+2. `docs/skills/` — mental models and invariants; subordinate to the handbook.
+3. `docs/templates/` — the template contract, construction strategy, recipes,
+   perf rules; subordinate to both.
+
+Handbook wins over skills, skills over templates, and **code wins over every
+doc**: when a document and the packages disagree, the packages are right. The
+one idea everything rests on: a layout is one string of rectangles
+(`docs/m0saic-thesis.md`).
+
+## Read code, not just prose — the three example repos
+
+| Repo | What it is | Good for |
+|---|---|---|
+| [`m0saic-project/m0saic-template-repo-starter`](https://github.com/m0saic-project/m0saic-template-repo-starter) | ~80 one-concept templates, one lesson each, zero-build | learning the shape of a template; copying a pattern in isolation |
+| [`m0saic-project/m0saic-community-templates`](https://github.com/m0saic-project/m0saic-community-templates) | the public library, one folder per publisher, signed releases | a real submission's layout, tests, registry entry, `deprecated.replacement` |
+| [`m0saic-project/m0saic-packages/packages/templates`](https://github.com/m0saic-project/m0saic-packages/tree/main/packages/templates) | the official library that ships in the product (100+ templates) | the house standard for every kind of template: brand, charts, media, data-driven, pipelines |
+
+Start your own from the scaffold:
+[`m0saic-template-repo-starter-base`](https://github.com/m0saic-project/m0saic-template-repo-starter-base)
+(rename its placeholder identity in `src/repo.ts` before you publish).
+
+## Verify before you claim it works
+
+- `validateM0String(str)` from `@m0saic/dsl` — never ship an m0 string you
+  did not validate; `isValidM0String` is the boolean form.
+- `npm run verify` in a starter clone — build, lint, tests, the loader
+  contract, the dependency policy.
+- `m0saic doctor <repo>` — the CLI's convention audit over a template repo;
+  its `latticeSmooth` finding is blocking.
+- `m0saic make <id> --template-repo <repo> --validate-only` — the plan
+  without the render.
+
+## What is deliberately not here
+
+The engine's internals — filtergraph construction, the cost model, the
+ffmpeg walls and their mitigations, the private app internals. Where a page
+would have cited one it says so in plain text ("absent in the shipped copy")
+and stands on its own. Every author-facing consequence of those internals is
+distilled into [`docs/templates/patterns/perf-authoring-rules.md`](docs/templates/patterns/perf-authoring-rules.md).
+
+## Maintenance
+
+`docs/` is generated — do not edit it here. The source is the maintainers'
+knowledge tree in the m0saic monorepo; a sync script regenerates this copy
+and fails if any reference to private code survives. Found something wrong?
+Open an issue on the mirror repo.
+
+MIT — see LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/** Absolute path of the Markdown tree (`docs/`). */
+export declare const docsDir: string;
+/** The agent front door (this package's README). */
+export declare const readme: string;
+/** `docs/m0saic-thesis.md` — the one load-bearing idea. */
+export declare const thesis: string;
+/** `docs/README.md` — the "doing X → read Y" router. */
+export declare const router: string;

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// The one programmatic surface: where the docs are, for tools that want to
+// point an agent at them (`require.resolve("@m0saic/knowledge")` → this file,
+// `docsDir` → the Markdown tree). The content is the docs themselves.
+const path = require("path");
+const docsDir = path.join(__dirname, "..", "docs");
+module.exports = { docsDir, readme: path.join(__dirname, "..", "README.md"), thesis: path.join(docsDir, "m0saic-thesis.md"), router: path.join(docsDir, "README.md") };

package/docs/README.md

@@ -0,0 +1,60 @@
+# `docs/` — the m0saic knowledge base
+
+Golden rules and mental models for working in the m0saic ecosystem. This folder is
+**shippable**: it may be published to the public m0saic ecosystem as-is, so new
+engineers can point their agents at it. Read
+[`m0saic-thesis.md`](m0saic-thesis.md) first — the one load-bearing idea.
+
+## The moat contract
+
+Nothing in this folder may document private engine internals. Deep dives on the
+engine (filtergraph builders, cost-model coefficients, ffmpeg walls and their
+mitigations, private-app internals) live in **`.ai/moat/`** — internal-only, never
+shipped. Public docs here stand alone; where one references an internal deep-dive
+it uses the marked form ``(internal: `.ai/moat/…` — absent in the shipped copy)``
+as plain text, never a markdown link. Moat docs may link here freely; docs here
+must never *depend* on moat content.
+
+## Authority hierarchy (from the agent contract §0)
+
+1. **handbook/** — canonical truth for DSL grammar, semantics, geometry math
+2. **skills/** — mental models & invariants (subordinate to handbook)
+3. **templates/** — concrete constructs & the authoring surface
+
+Handbook wins over skills; skills win over templates. Code wins over all docs —
+found drift? Propose a fix via (internal design history) (agents propose; the owner
+disposes).
+
+## Folder map
+
+| Folder | Contents | Start with |
+|---|---|---|
+| [`handbook/`](handbook/README.md) | DSL grammar + the geometry math (canonical) | `m0-construction-methods.md` |
+| [`skills/`](skills/README.md) | DSL/engine mental models | per-task, see its README |
+| [`templates/`](templates/README.md) | Template contract, construction, authoring | `philosophy-and-contract.md` |
+| `file-formats/` | `.m0` family persistence + the agent-iteration protocol | `m0p-and-custom-field.md` |
+| `runtime/` | CLI usage + author-facing render guidance | `cli-usage.md` |
+
+## Doing X → read Y
+
+| Task | Read |
+|---|---|
+| Generate / mutate an m0 string | `handbook/m0-construction-methods.md` → `handbook/dsl-rules.md` → `skills/m0saic-string-generation.md` |
+| Any geometry work (splits, grids, gutters) | `handbook/feasibility-precision-quantization.md` (start here — contract §1) |
+| Nesting / composition math | `handbook/composition-arithmetic.md` |
+| Overlays, passthroughs, identity | `skills/overlay-semantics.md`, `skills/passthrough-semantics.md`, `skills/identity.md` |
+| Build a template | `templates/philosophy-and-contract.md` → `templates/construction-strategy.md` → `templates/geometry-recipes.md` |
+| Template perf | `templates/patterns/perf-authoring-rules.md` |
+| Data-driven templates | `templates/data-pipeline.md` |
+| Read/write `.m0` / `.m0c` / `.m0p` / `.m0v` | `file-formats/m0p-and-custom-field.md` |
+| Render via the CLI | `runtime/cli-usage.md` |
+
+## House conventions for docs in this tree
+
+- **Golden-rule register**: rule → evidence → code pointer (`file:line`). No essays.
+- **Date volatile claims** ("as of 2026-07-27") and ship a one-line re-verification
+  grep alongside anything that can drift. Citation density predicts accuracy — the
+  docs that named exact files and constants survived audit; the ones that didn't,
+  rotted.
+- Code is the source of truth. A doc that contradicts the code is wrong; fix the
+  doc (via (internal design history) if you're an agent).

package/docs/file-formats/m0-iteration-protocol.md

@@ -0,0 +1,120 @@
+# `.m0` iteration protocol — one file, one prompt
+
+## Mental model
+
+A `.m0` / `.m0c` / `.m0p` file is the **atomic unit** of an iteration: ONE geometry, ONE
+question from the writing party, ONE response from the reading party.
+
+**Iteration produces NEW files.** The conversation lives in the *directory*, not inside
+any single file. Think of a chess endgame book — each file is a position plus the
+discussion that graded it, and the next move sits in the next file over.
+
+Two payoffs:
+
+- **Corpus value.** Over time the directory becomes a graded pattern bank: future agents
+  browse `(question, geometry, response)` triples and learn what actually worked.
+- **Context survival.** Agent context windows reset; the directory doesn't. Stepping
+  back through an old session's files reconstructs the whole design discussion, however
+  many resets ago it happened.
+
+---
+
+## Canonical types
+
+**`@m0saic/momo-types` (`src/agent.ts`) is the canonical home** — one lightweight,
+dependency-free package for the agent layer, so `@m0saic/dsl-file-formats`, the desktop
+app, and momo's runtime all point at the same upstream instead of maintaining
+structural mirrors.
+
+> `@m0saic/momo` (`src/agent/meta.ts`) is now a **re-export shim** kept for
+> back-compat. Import from `momo-types`; momo remains the heavier runtime (agent loop,
+> prompt building) layered on the shared vocabulary. Docs or code still treating
+> `momo/src/agent/meta.ts` as the definition site are stale.
+
+| Field | Audience | Shape |
+|---|---|---|
+| `note` | reading party (prose) | string |
+| `question` | reading party (the ask) | string |
+| `regions` | downstream router | `stableKey → label` |
+| `context` | downstream router | unknown (JSON) |
+| `response.body` | originating party | string |
+| `response.from` | provenance / routing | `human…` / `agent:<role>` |
+| `response.at` | provenance | ISO 8601 |
+| `comments[]` | human review / provenance | `M0AgentComment[]` |
+
+Carried as `# m0agent:<key>: <json-or-prose>` headers in `.m0`, and under the top-level
+`agent` JSON slot in `.m0c` / `.m0p`.
+
+Prose fields (`note`, `question`, `response.body`, `comments[].body`) render as
+**markdown** in the Momo FILE pane, and the JSON formats preserve newlines — use short
+lists and tables. The line-based `.m0` format flattens prose to one line, so reach for
+`.m0c` when the question needs real structure.
+
+---
+
+## The shape: Reddit-style threading
+
+Each file is one post:
+
+| Slot | Role |
+|---|---|
+| `note` / `question` / `regions` / `context` | the OP's body |
+| `response` | **the** answer — canonical |
+| `comments[]` | the thread below — orbiting discussion |
+
+**`response` is single-valued on purpose.** OP + response together are the canonical
+record of one design exchange. Iterating the geometry produces a **new file** (a new
+post), never a second response on this one — because the geometry itself is what
+changed, and the protocol mirrors that.
+
+**`comments[]` is explicitly non-canonical.** Append-only by convention; anyone (human
+or agent) may add one to share context, raise a concern, link a related candidate, or
+record a side observation that doesn't merit its own file. Flat array — **no nested
+replies** — ordered chronologically by `at`, falling back to insertion order.
+
+> Future agents **route on `response`**. Comments are for human review and provenance.
+> Don't put a verdict in a comment and expect tooling to find it. Mosaic renders
+> comments as URL-hash anchors (`#c-<id>`), so other files and external systems can link
+> a specific post.
+
+This is the one place the "single answer" model bends, and it bends deliberately: the
+thread absorbs discussion that would otherwise either pollute the response slot or force
+a spurious new file.
+
+---
+
+## The loop
+
+1. Writing party generates `candidate-N.m0c`, hands over the path.
+2. Reading party opens it — File Details jumps to the agent annotations; `regions`
+   hover-highlight in the wireframe.
+3. Reader writes a response, saves. **The same file is rewritten in place.**
+4. Writing party reads the response and generates `candidate-N+1` with new geometry.
+   **The old file stays, frozen at its graded state.**
+5. Anyone steps through the directory later to reconstruct the discussion.
+
+⚠️ **Never mutate a file that already carries a response.** The verdict is bound to the
+exact geometry it was given; editing the geometry underneath it silently invalidates the
+record and collapses the iteration trail.
+
+---
+
+## Party-agnostic by design
+
+`response.from` discriminates the responder — `"human"`, `"human:quentin"`,
+`"agent:claude"`, `"agent:brand-x-stylist"`. Tooling routes on the `human:` / `agent:`
+prefix. One shape covers human↔agent, agent↔agent, and future multi-agent review
+workflows (a brand-trained stylist, a data-viz reviewer, a music-video sensibility
+model).
+
+---
+
+## Cross-references
+
+- **https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md** — the full operational protocol: file naming,
+  `-a`/`-b` forking for parallel sessions, when to start a new session, anti-patterns,
+  and the `m0saic open` handoff. **Read it before authoring or iterating a candidate.**
+- `tools/wireframe.mjs` — single-shot wireframe helper for minting a candidate image.
+- `file-formats/m0p-and-custom-field.md` — the `agent` block coexists with `custom.*`:
+  `custom` is per-template payload, `agent` is per-iteration metadata. Different
+  lifetimes, different owners.

package/docs/file-formats/m0p-and-custom-field.md

@@ -0,0 +1,195 @@
+# File Formats: `.m0p` Packs and the `custom.*` Sidecar Pattern
+
+## Purpose
+
+Reference for m0saic's file-format model. Covers:
+
+- When to use `.m0` vs. `.m0c` vs. `.m0p` (see §1's note for the two later arrivals, `.m0g` and `.m0v`).
+- How to read, write, and convert between the formats via `@m0saic/dsl-file-formats`.
+- The `custom: unknown | null` field — the canonical persistence carrier for tool-defined sidecar data.
+- The label and pack validators that ride on top of the formats.
+
+These features shipped together in April 2026. They are foundational to v2 work — most v2 features (animation tracks, constraint maps, region asset bindings, mask sets, rank sets, Figma round-trip, SVG round-trip) persist in `custom.*` until convergence justifies promotion to first-class fields.
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src). Types in [`types.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/types.ts); pack format in [`m0p/m0pFile.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/m0p/m0pFile.ts); conversions in [`conversions.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/conversions.ts); validators in [`validate/`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/validate).
+
+---
+
+## 1. The file formats — five, not three (updated 2026-07-26)
+
+| Format | Shape | When to use |
+|---|---|---|
+| `.m0` | Canonical text DSL + lightweight headers (incl. the `m0agent:*` block) | One layout, one canvas, no labels / no derive image / no per-region metadata |
+| `.m0c` | JSON: DSL + StableKey-keyed labels + derive image + meta | One layout, with labels / overlays / derive thumbnail / `custom.*` |
+| `.m0g` | `.m0c`-shaped JSON with `format: "m0g"` + the `M0cGold` `gold` block | A **m0saic golden** ("mogging") — a tried-and-true, signed-off layout; `#mogging` comment-line convention (`types.ts`) |
+| `.m0p` | JSON: pack of `.m0c`-shaped variants under shared identity | Multiple coordinated variants (cross-canvas, brand pack, content set, themed collection) |
+| `.m0v` | JSON: `outputs` / `assets` / `custom` (`src/m0v/m0vFile.ts`) | **Mosaic Vocabulary** — user-tier shared brand language: output presets, palette, typography, asset paths. CLI `--m0v <path>`; `m0saic open` accepts it |
+
+`.m0` and `.m0c` are unchanged by the later formats' arrival — each is purely additive.
+This doc covers `.m0`/`.m0c`/`.m0p` in depth; `.m0g` and `.m0v` have their own type
+homes in the same package (conversion helpers for them are not exported — the §3
+matrix below is `.m0`/`.m0c`/`.m0p` only, by design).
+
+All JSON formats (and `.m0` via its header block) also carry the top-level
+`agent` slot (`M0AgentMeta`) used by the sandbox iteration protocol — see
+[`m0-iteration-protocol.md`](m0-iteration-protocol.md).
+
+---
+
+## 2. `.m0p` — multi-variant pack format
+
+A single JSON container that bundles multiple `.m0c`-shaped layout variants under one shared identity.
+
+```ts
+type M0pFile = {
+  format: "m0p";
+  version: 1;
+  created: string;             // ISO timestamp
+  app?: string | null;
+  appVersion?: string | null;
+  meta?: M0FileMeta | null;
+  regions?: M0pRegions | null;
+  custom?: unknown | null;     // pack-level custom JSON
+  variants: Record<string, M0pVariantEntry>;
+};
+
+type M0pVariantEntry = {
+  meta?: M0FileMeta | null;    // overrides pack-level when present
+  size: { width: number; height: number };
+  m0: M0String;
+  labels?: Record<StableKey, { text: string }> | null;
+  derive?: { image: string | null };
+  custom?: unknown | null;     // per-variant custom JSON
+};
+```
+
+**Variant keys** validated as `^[a-z0-9][a-z0-9-]*$` (kebab-case). Examples: `desktop`, `mobile`, `square`, `story`.
+
+**Pack-level fields are defaults.** Per-variant overrides for `meta` are supported but only emitted when they differ — roundtripping doesn't manufacture spurious overrides.
+
+**Pack-level `regions` registry** declares the shared semantic vocabulary (e.g. `headline`, `hero`, `logo`, `cta`) that variants reference *by label text* (not by StableKey — keeping StableKey purely structural).
+
+**Deterministic serialization.** Variant keys sorted alphabetically, region keys sorted, label keys sorted by StableKey, DSL canonicalized, fixed field order, 2-space indent + trailing newline. Byte-stable roundtrip.
+
+**Forward-compatible.** Unknown fields silently preserved at every level (same posture as `.m0c`).
+
+Live type definitions: see `M0pFile`, `M0pVariantEntry`, `M0pRegions`, `M0FileMeta`, `M0cFile`, `M0File` in [`types.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/types.ts). **Trust the types over the snippets above** if they ever drift.
+
+---
+
+## 3. The 3×3 conversion matrix
+
+`@m0saic/dsl-file-formats` exposes one canonical entry point for every direction:
+
+| from \ to | `.m0` | `.m0c` | `.m0p` |
+|---|---|---|---|
+| `.m0` | identity | `upgradeM0ToM0c` | `upgradeM0ToPack` |
+| `.m0c` | `downgradeM0cToM0` ⚠ | identity | `bundleM0cIntoPack` |
+| `.m0p` | `extractVariantAsM0` ⚠ | `extractVariantAsM0c` | identity |
+
+⚠ = lossy by design. Named `downgrade*` / `extract*` so the data loss is visible at the call site rather than hidden in an `as`-style cast.
+
+All conversions are pure object transforms — no I/O, no async.
+
+`upgradeM0ToM0c` / `downgradeM0cToM0` / `upgradeM0ToPack` / `extractVariantAsM0` live in [`conversions.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/conversions.ts). `bundleM0cIntoPack` / `extractVariantAsM0c` live in [`m0p/m0pFile.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/m0p/m0pFile.ts).
+
+**Discovery helpers** (also exported from `m0p/m0pFile.ts`): `listVariantKeys(pack)` (alphabetical), `getVariant(pack, key)`, `findVariantBySize(pack, w, h)`.
+
+---
+
+## 4. The `custom: unknown | null` field
+
+Both `.m0c` and `.m0p` carry a `custom` field at every level — pack root + per-variant. JSON round-trips byte-stable; the format treats it as opaque.
+
+**Why opaque.** Tool-defined metadata that the format spec does not bless. Tools that care read `custom.<key>`; tools that don't ignore it. No validator commitment, no conversion-matrix obligation, no schema enforcement.
+
+**The persistence pattern for v2 sidecar data.** Multiple v2 features use `custom.*` keys:
+
+| `custom.*` key | What it carries | Owning ticket / surface |
+|---|---|---|
+| `custom.animation` | Animation tracks + keyframes | ED-4 (animation timeline) |
+| `custom.constraints` | Per-tile / per-region constraint maps | SL-8 (constraints layer) |
+| `custom.assets` | StableKey → asset binding | ED-10a (asset registry) |
+| `custom.maskSets` | Named subsets of StableKeys | ED-10b (mask editor) |
+| `custom.rankSets` | Named ordered StableKey lists | ED-10c (rank editor) |
+| `custom.figma` | Figma round-trip metadata | XP-4 (Figma plugin) |
+| `custom.svg` | SVG import round-trip metadata | ED-7 / XP-3 |
+
+**Promotion rule.** A shape lives in `custom.*` first. Promote to a first-class field only when (a) ≥2 tools have converged on the shape, and (b) a real exchange need exists. This is how the format stays additive without committing to schemas that need to evolve.
+
+**Already promoted (first-class per-frame fields).** Several shapes have walked this path and now sit next to `labels` on both `M0cFile` and `M0pVariantEntry`, every one keyed by `StableKey` (structural identity that survives splits / overlays / repacks) — `masks` (`{ localPath, bounds }` inline silhouettes), `fill` (`{ color?, mediaRef? }` rect fill), `rankSets` (named sweep-progress maps), and `insets` (`{ top, right, bottom, left }`, per-edge fractions 0..1 of the frame's cell). **Trust `types.ts` for the live field list.** Notes on `insets` (the newest, shipped 2026-07):
+
+- It's the render-time box a source shrinks its cell to — promoted from the engine-only `MosaicSource.placement.inset`. It's the **resolved projection** of `placement.inset`'s `MosaicBoxFrac` superset (`number | {x,y} | per-side`), collapsed to the one four-edge wire form at the extraction boundary (the app's `resolveBoxFrac`), byte-identical to ViewFrame's `insetBoxes` prop. If `MosaicBoxFrac` grows a new authoring form, the `resolveBoxFrac` call sites resolve it — `M0cInset` doesn't change (see `MIRRORED_TYPES.md`).
+- It's the persisted home for **quantization-hostile** layout: quantize cells outward onto a coarse divisor lattice, then recover the exact painted rect at render time via half-pixel-centered fractions (`(n + 0.5) / dim`; the engine floors `frac * dim`) — zero drift at the authored canvas size, ≤1px degradation at other sizes. This is the `placeInsetRects` launder given a file-format home.
+- **Null semantics follow `fill`, not `masks`:** no inner explicit `null` (key absence = "no inset"); all-zero entries are dropped by normalizer and parser.
+- `validateInsets` warns (never errors — the engine clamps): `ORPHANED_INSET`, `INSET_OUT_OF_RANGE` (edge < 0 or ≥ 1), `INSET_COLLAPSES_FRAME` (`top+bottom ≥ 1` or `left+right ≥ 1`). Rolled into `validatePack` as `PackVariantIssues.insetIssues`.
+- **Derived-vs-sidecar precedence, no merge logic:** Make / Compose paint *derived* insets from live sources (`buildGeometryDecor`); Layout paints the *sidecar* (`m0cExtras.insets`). Layout has no sources → no conflict. The Make → Layout handoff converts derived → sidecar once at send time; the Layout → Compose join writes the sidecar back onto `sources[i].placement.inset`. A public `(m0, inset map) → exact rects` adapter is deferred until a real caller appears.
+
+**Default value.** `null`. Round-tripping a file without a `custom` field through serialize→parse→serialize is byte-stable.
+
+---
+
+## 5. Label and pack validators
+
+**Four** pure validators ship in `@m0saic/dsl-file-formats` ([`validate/`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/validate)): `validateLabels`, `validateFill`, `validateInsets` (§4 above), and `validatePack`. All return structured results — no React, no DOM, no parsing inside. This section details the label + pack pair.
+
+Result types: `LabelValidationResult`, `PackValidationResult`, `PackVariantIssues` in [`validate/types.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/validate/types.ts). Empty-result sentinels: `EMPTY_LABEL_RESULT`, `EMPTY_PACK_RESULT`.
+
+### `validateLabels`
+
+```ts
+validateLabels({
+  validStableKeys: Set<StableKey>,
+  labels: Record<StableKey, { text: string }>,
+}): LabelValidationResult;
+```
+
+Flags labels whose `stableKey` no longer maps to a frame in the layout's parsed frame set. Surfaces "you split the frame I was labeled on, my label is now floating in space."
+
+The caller supplies the parsed `validStableKeys` set so editors can reuse a parse they were already going to do (`<ViewFrame>` runs `parseM0StringComplete` on every geometry change; the validator just consumes its output).
+
+### `validatePack`
+
+```ts
+validatePack(
+  pack: M0pFile,
+  opts?: { liveVariantOverride?: ...; parseCache?: ... }
+): PackValidationResult;
+```
+
+Three classes of issue:
+
+1. **Region coverage.** Variants missing required regions (per `pack.regions`).
+2. **Region duplicates.** Variants where multiple labels resolve to the same region (case-insensitive duplicate).
+3. **Per-variant orphan labels.** Same shape `validateLabels` produces, scoped per variant.
+
+Returns aggregates at the pack level + a per-variant breakdown.
+
+---
+
+## 6. When to use what — decision tree
+
+- One layout, one canvas, no metadata → **`.m0`**
+- One layout, with labels / overlays / derive image → **`.m0c`**
+- One layout, with tool-defined sidecar data → **`.m0c` with `custom.*`**
+- Multiple coordinated variants of one design (responsive) → **`.m0p`**
+- Multiple unrelated layouts under shared identity (brand pack, content set) → **`.m0p`**
+- Anything format-doesn't-bless-yet → **`custom.*` on the appropriate format**
+
+---
+
+## 7. Common mistakes to avoid
+
+- **Don't promote a `custom.*` shape to a first-class field early.** Wait for ≥2 tools on the shape.
+- **Don't put random data on the root of `.m0c` or `.m0p`.** It will be silently preserved as an unknown field but won't go through `custom.*` validation hooks.
+- **Don't use StableKeys as region names.** Regions reference labels by *text*, not by StableKey, so labels survive structural edits while regions stay stable.
+- **Don't skip `validateLabels` after structural edits.** Splitting a frame can orphan labels; the validator surfaces this immediately.
+- **Don't rely on `.m0p` variant order.** Serialization sorts variant keys alphabetically. If your tool depends on order, store it explicitly in `custom.*`.
+
+---
+
+## See also
+
+- `../handbook/dsl-rules.md` — DSL grammar for the m0 strings each variant carries.
+- Quality scoring works against any of these formats — internal: `.ai/moat/skills/score-layout-primitive.md`.
+- `../skills/identity.md` — the StableKey contract, overlay namespace, and identity-continuity rules that labels and regions ride on.

package/docs/handbook/README.md

@@ -0,0 +1,27 @@
+# handbook/ — canonical DSL truth
+
+The authoritative layer (contract §0): grammar, semantics, and the geometry math.
+On any conflict with skills/ or templates/, this folder wins; the code wins over
+this folder.
+
+## Read order
+
+1. [`m0-construction-methods.md`](m0-construction-methods.md) — **the entry
+   point**: every way to produce an m0, the four currencies, the canonical
+   8-rung launder ladder, pairwise discriminators.
+2. [`dsl-rules.md`](dsl-rules.md) — what's legal: surface grammar, tokens,
+   canonicalization, the 11 error codes × kind taxonomy, warnings surface.
+3. [`feasibility-precision-quantization.md`](feasibility-precision-quantization.md)
+   — will ONE split render, look right, stay balanced: the two independent
+   floors, the three drafting modes (§3c), quantization fixes. **Start here for
+   any geometry work** (contract §1).
+4. [`composition-arithmetic.md`](composition-arithmetic.md) — will STACKED
+   splits work: prime-factor budgets, the 5-smooth invariant, base×fiber,
+   hereditary quantization.
+
+## Reference
+
+- [`precision-tiers.md`](precision-tiers.md) — light primitives / precise heads,
+  and the GCD-collapse search.
+- [`dsl-complexity.md`](dsl-complexity.md) — the complexity metrics API
+  (`getComplexityMetricsFast`).