@homepages/template-kit 0.1.0 → 0.3.0

package/dist/styles.css

@@ -1,15 +1,26 @@
 /*
- * @homepages/template-kit — theme tokens + kit source registration.
+ * @homepages/template-kit — the global Tailwind preamble.
  *
- * Import this AFTER `@import "tailwindcss";` in your own CSS entry:
+ * Import this AFTER `@import "tailwindcss";` in your own CSS entry, and import your
+ * template's compiled theme after it:
  *
  *   @import "tailwindcss";
  *   @import "@homepages/template-kit/styles.css";
+ *   @import "./theme.css";        // compileThemeToCss(yourTheme) output
  *
  * This file must NOT import Tailwind itself. Exactly one `@import "tailwindcss"` may
  * exist per build graph — your entry owns it. Two double-emit Tailwind's preflight
  * reset (box-sizing declared twice, ~4 KB of duplicate base layer).
  *
+ * WHAT IS HERE: only what is true of EVERY template — the breakpoint ladder, the
+ * spacing base unit, and the motion defaults.
+ *
+ * WHAT IS NOT: your design tokens. Colors, fonts, type, radii and shadows are yours.
+ * Declare them in `theme.ts` under names you choose, and `compileThemeToCss` generates
+ * the `@theme inline` alias layer that turns each one into a utility. Nothing about
+ * your visual system is shared, and there is no global file for you to edit to make a
+ * token of yours usable.
+ *
  * The @source below resolves relative to THIS FILE'S SHIPPED LOCATION (dist/styles.css),
  * registering the kit's compiled JS for class scanning — that is how the utility classes
  * baked into the kit's primitives reach your compiled CSS. It also overrides Tailwind's
@@ -23,107 +34,39 @@
  * utilities and 19 stray @property registrations, ~2.5 KB. If a primitive ever moves out
  * of primitives/, widen this — an unstyled <Image> in every template is the failure mode,
  * and scripts/verify-consumer.mjs is what catches it.
- *
- * The @theme block aliases Tailwind's utility namespace onto the `--tr-*` custom
- * properties your template's theme.ts supplies (`text-ink` → `var(--tr-color-ink)`).
- * The aliases are the cross-template contract; the values behind them are yours.
  */
 @source "./primitives/**/*.js";
 
+/* `@theme inline` so a spacing/breakpoint value is substituted straight into the
+ * utilities Tailwind generates (`.gap-2 { gap: .5rem }`), rather than emitted as a
+ * `:root` custom property the utilities then read through `var()`. These are fixed
+ * global constants, not per-page-overridable tokens, so inlining is both correct and
+ * what keeps the compiled output stable. Nothing here may reference a token a theme.ts
+ * defines. */
 @theme inline {
-  /* ---------- Colors (alias to the --tr-color-* values a theme.ts supplies) ---------- */
-  --color-ink:           var(--tr-color-ink);
-  --color-ink-soft:      var(--tr-color-ink-soft);
-  --color-ink-mute:      var(--tr-color-ink-mute);
-  --color-background:    var(--tr-color-background);
-  --color-surface:       var(--tr-color-surface);
-  --color-surface-alt:   var(--tr-color-surface-alt);
-  --color-border:        var(--tr-color-border);
-  --color-border-strong: var(--tr-color-border-strong);
-  --color-accent:        var(--tr-color-accent);
-  --color-accent-strong: var(--tr-color-accent-strong);
-  --color-accent-contrast: var(--tr-color-accent-contrast);
-  --color-primary:         var(--tr-color-primary);
-  --color-primary-fg:      var(--tr-color-primary-fg);
-  --color-primary-darker:  var(--tr-color-primary-darker);
-  --color-overlay:        var(--tr-color-overlay);
-  --color-overlay-strong: var(--tr-color-overlay-strong);
-  --color-overlay-light:  var(--tr-color-overlay-light);
-  --color-footer-bg:      var(--tr-color-footer-bg);
-  --color-footer-fg:      var(--tr-color-footer-fg);
-  --color-footer-fg-mute: var(--tr-color-footer-fg-mute);
-  --color-footer-divider: var(--tr-color-footer-divider);
-
-  /* Decorative brand swatches — the open `palette` escape hatch in TokenTheme.
-   * A theme that omits one leaves its utility resolving to an unset custom
-   * property; only reach for these when a semantic role genuinely doesn't fit. */
-  --color-yellow-deep:  var(--tr-color-yellow-deep);
-  --color-yellow-200:   var(--tr-color-yellow-200);
-  --color-yellow-100:   var(--tr-color-yellow-100);
-  --color-brown:        var(--tr-color-brown);
-  --color-green:        var(--tr-color-green);
-  --color-blue:         var(--tr-color-blue);
-  --color-rule:         var(--tr-color-rule);
-  --color-gray-light:   var(--tr-color-gray-light);
-  --color-team-gold:   var(--tr-color-team-gold);
-  --color-mute:         var(--tr-color-mute);
-  --color-scrim:        var(--tr-color-scrim);
-  --color-footer-line:  var(--tr-color-footer-line);
-  --color-footer-mute:  var(--tr-color-footer-mute);
-  --color-divider-40:   var(--tr-color-divider-40);
-  --color-contact-deep: var(--tr-color-contact-deep);
-  --color-header-deep:  var(--tr-color-header-deep);
-
-  /* ---------- Fonts ---------- */
-  --font-sans:    var(--tr-font-sans);
-  --font-display: var(--tr-font-sans);
-  --font-serif:   var(--tr-font-serif);
-  --font-num:     var(--tr-font-num);
-  --font-label:   var(--tr-font-label);
-
-  /* ---------- Type scale (mobile baseline; layer up with md:/lg:) ---------- */
-  --text-xs:      var(--tr-text-xs);
-  --text-sm:      var(--tr-text-sm);
-  --text-base:    var(--tr-text-base);
-  --text-lg:      var(--tr-text-lg);
-  --text-xl:      var(--tr-text-xl);
-  --text-2xl:     var(--tr-text-2xl);
-  --text-3xl:     var(--tr-text-3xl);
-  --text-4xl:     var(--tr-text-4xl);
-  --text-5xl:     var(--tr-text-5xl);
-  --text-display: var(--tr-text-display);
-
-  /* ---------- Spacing scale (alias to --tr-space-*) ---------- */
+  /* ---------- Spacing ---------- */
   --spacing: 0.25rem;  /* v4 base unit; Tailwind multiplies (e.g. p-4 = 1rem) */
 
-  /* ---------- Radii ---------- */
-  --radius-sm:   var(--tr-radius-sm);
-  --radius-md:   var(--tr-radius-md);
-  --radius-lg:   var(--tr-radius-lg);
-  --radius-full: var(--tr-radius-full);
-
-  /* ---------- Shadows ---------- */
-  --shadow-sm: var(--tr-shadow-sm);
-  --shadow-md: var(--tr-shadow-md);
-  --shadow-lg: var(--tr-shadow-lg);
-
-  /* ---------- Motion ---------- */
+  /* ---------- Motion ----------
+   * The --tr-* values these read are defined in base.css, which every page loads. */
   --default-transition-duration: var(--tr-duration-fast);
   --default-transition-timing-function: var(--tr-ease);
 
   /* ---------- Canonical breakpoint ladder ----------
-   * Eight canonical widths — the same set the preview grid and the screenshot
-   * harness verify a section against (VERIFICATION_WIDTHS is the matching TS
-   * constant). 350 is the mobile-first BASE (no prefix); the other seven are
-   * named breakpoints:
+   * Eight canonical widths — the same set the preview grid and the screenshot harness
+   * verify a section against. `VERIFICATION_WIDTHS` (design-system/breakpoints.ts) is
+   * the matching TS constant; CSS cannot import it, so `src/css/styles.test.ts` fails
+   * the build if the two ever drift.
+   *
+   * 350 is the mobile-first BASE (no prefix); the other seven are named breakpoints:
    *
    *   bp390 (390) · bp425 (425) · bp512 (512) · md (768) · lg (1024)
    *   · bp1440 (1440) · bp1920 (1920)
    *
    * `md` and `lg` keep Tailwind's own names and values. The off-ladder defaults
-   * (sm/xl/2xl) are reset to `initial` so a section cannot come to depend on a
-   * width nobody screenshots. A swap-heavy section may still reach for a raw
-   * `@media` micro-breakpoint at an off-ladder width (e.g. 640 / 769).
+   * (sm/xl/2xl) are reset to `initial` so a section cannot come to depend on a width
+   * nobody screenshots. A swap-heavy section may still reach for a raw `@media`
+   * micro-breakpoint at an off-ladder width (e.g. 640 / 769).
    */
   --breakpoint-sm:    initial;
   --breakpoint-bp390:  390px;

package/docs/INDEX.md

@@ -2,7 +2,7 @@
 purpose: Router for the docs corpus that ships inside the @homepages/template-kit npm package.
 status: living
 related: []
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit docs — router
 
@@ -16,6 +16,8 @@ detail.
 | `llms.txt` | Machine-readable index of this corpus for an agent working inside an installed kit | orienting an agent in a consuming workspace |
 | `schema-system.md` | The section authoring contract: `schema.ts` / `fill-spec.ts` / `fixtures.ts` / `Renderer.tsx`, `SectionProps` inference, the closed source/transform vocabulary, and the golden property fixtures | authoring or changing any section |
 | `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
-| `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
+| `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme` (your own token names → your own Tailwind utilities), the `template-kit theme` command that generates `theme.css` from `theme.ts`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
 | `islands.md` | Interactivity: `"use client"` components, the serializable-props rule, editor options, the loader | anything interactive in a section |
-| `eslint.md` | The `@homepages/template-kit/eslint` preset: zero-config setup, its glob scope, and the eleven `template-kit/*` rule ids | wiring up lint in a template workspace, or adding/changing an authoring rule |
+| `eslint.md` | The `@homepages/template-kit/eslint` preset: the two-line config, the ESLint + parser install it expects, and its glob scope | wiring up lint in a template workspace |
+| `check.md` | The `template-kit check` CLI command: the toolchain it resolves from your workspace, its stages, `--all`/`--json`, output shape, and exit code | running `check` locally or wiring it into CI |
+| `rules/` | One page per rule-id (`template-kit/*`), across both venues — the id printed by a lint or `check` failure resolves here. `rules/INDEX.md` routes them; `rules/server-vs-client.md` is the concept the server-rendering rules assume | any lint or `check` failure |

package/docs/check.md

@@ -0,0 +1,121 @@
+---
+purpose: The `template-kit check` command — what it runs, its flags, its output shape, and its exit code.
+status: living
+related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md]
+updated: 2026-07-15
+---
+# template-kit check
+
+`template-kit check` is the one command that answers "will the platform accept this
+template?" — the same gate you run locally and the one the registry re-runs when you
+submit. Every failure prints a stable `template-kit/<id>`, a `file:line` where one
+applies, and a one-line fix hint. The id resolves to its own page under
+[`rules/`](rules/INDEX.md).
+
+## Usage
+
+```bash
+template-kit check                # infer the template from cwd, or the workspace's one template
+template-kit check <template>     # check one named template by its key
+template-kit check --all          # check every template in the workspace
+template-kit check --json         # machine-readable report (combine with any of the above)
+```
+
+Run it from the workspace root, or from inside a template's own folder — a bare `check`
+infers which template you mean. A workspace with more than one template must either name
+one or pass `--all`.
+
+### What it needs installed
+
+```bash
+npm i -D typescript eslint @typescript-eslint/parser esbuild
+```
+
+`check` runs **your** toolchain, not a copy of its own: it resolves TypeScript, ESLint
+and esbuild from your workspace, so the compiler that judges your types is the one you
+pinned, and a linter and a bundler never end up in the production install of a package
+whose job is to render sections. A missing one is reported by name, with the install
+line to fix it.
+
+## What it runs
+
+Two granularities, because a workspace has one `package.json` and one lockfile, but can
+hold many templates.
+
+**Six authoring stages**, run in order, once per selected template. None of them abort
+the run — a template with several unrelated problems reports all of them in one pass, not
+one class of fix at a time:
+
+1. **typecheck** — the workspace's own TypeScript compiles the template's files, judged
+   against the workspace's own `tsconfig.json`.
+2. **lint** — the workspace's own ESLint, running the kit's shipped preset over the
+   template's files. See [the ESLint preset](eslint.md) for the rules this stage shares
+   with your editor.
+3. **validate** — the schema, fill-spec, fixtures, and manifest contracts: every
+   cross-reference between a section's contract files, and a template's `manifest.json`
+   against the sections it composes.
+4. **tree** — the rules a one-file-at-a-time linter cannot express: a missing contract
+   file, a slot declared in `schema.ts` with no marker anywhere in the section's JSX, a
+   hand-written CSS file's own rules.
+5. **render** — a determinism probe (every fixture is rendered twice; the two outputs
+   must be byte-identical) and a scan of the rendered HTML for objective defects — a
+   stray `[object Object]`, a bare `null`/`undefined`/`NaN` leaf, a `src`-less `<img>` —
+   plus, for the `typical` fixture, that the editor's sidebar order matches the page's
+   real render order.
+6. **size** — every section's renderer bundle and compiled stylesheet, gzipped, against a
+   fixed byte budget.
+
+**The dependency gates** run once per invocation, never once per template — they are
+properties of the workspace's one lockfile and installed tree, not of any one template:
+a lockfile present and satisfying `package.json`, exactly one copy of React installed,
+no `npm audit` finding at high or critical severity, and every shipped dependency's
+license on an allowlist.
+
+A run that selects zero templates to check is itself a failure —
+[`no-templates`](rules/no-templates.md) — never a silent pass.
+
+## Output
+
+Human-readable output prints one line per template (`✓ <key>`, or `✗ <key> — N
+problem(s)` followed by each finding), then any workspace-level findings from the
+dependency gates, then `check passed` if everything passed.
+
+`--json` prints one report object instead, keyed per template so a single-template
+consumer (the registry, ingesting one submission) and an all-templates consumer (your
+own CI) parse the same shape:
+
+```ts
+{
+  ok: boolean,
+  kitVersion: string,
+  templates: {
+    [templateKey: string]: { ok: boolean, diagnostics: Diagnostic[] },
+  },
+  // Dependency-gate findings — evaluated once, not per template.
+  workspace: { ok: boolean, diagnostics: Diagnostic[] },
+}
+```
+
+Each `Diagnostic` carries a `ruleId` (`template-kit/<id>`), the `template` it belongs to,
+an optional `section` and `file`/`line`, a `message`, and a `fix`.
+
+## Exit code
+
+`0` iff every selected template and the workspace pass. `1` otherwise — including when
+the run itself can't proceed at all (an unknown template name, no `templates/` folder
+in the workspace).
+
+## Thresholds are not configurable
+
+Every byte budget, severity floor, and license allowlist `check` enforces is a platform
+acceptance criterion, not a per-workspace preference — there is no config file or flag
+that raises them. If a template has a legitimate reason to need an exception, ask the
+platform team; a workaround that quietly disables a gate will simply fail again at
+submission.
+
+## See also
+
+- [Rules](rules/INDEX.md) — every id `check` (and the lint preset) can print, one page
+  each, Rule / Reason / Fix.
+- [ESLint preset](eslint.md) — the one-file-at-a-time half of the same rule set, run
+  directly by your editor, not only through `check`.

package/docs/eslint.md

@@ -1,7 +1,7 @@
 ---
-purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup, scope, and the eleven rule ids.
+purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup and scope. Per-rule reference lives in `rules/`.
 status: living
-related: [INDEX.md, islands.md, theme-and-css.md, primitives.md]
+related: [INDEX.md, rules/INDEX.md, check.md, islands.md, theme-and-css.md, primitives.md]
 updated: 2026-07-14
 ---
 # ESLint preset
@@ -12,6 +12,10 @@ rule namespace.
 
 ## Setup
 
+```bash
+npm i -D eslint @typescript-eslint/parser
+```
+
 ```js
 // eslint.config.mjs
 import kit from "@homepages/template-kit/eslint";
@@ -19,9 +23,15 @@ export default kit;
 ```
 
 That is the whole setup — no plugin registration, no parser wiring, no tsconfig.
-The preset ships its own parser (`@typescript-eslint/parser`, a real `dependency`
-of the kit, not a devDependency) and sets `languageOptions` itself, so `npm i -D
-eslint` plus the three lines above is a complete consumer config.
+The preset registers its rules and sets `languageOptions` (parser included) itself,
+so those two lines are a complete config.
+
+You install ESLint and the parser yourself because the kit deliberately does **not**
+depend on them: a package whose main entry is a set of React primitives must not drag
+a linter into the production install of every app that renders a template. The preset
+resolves the parser from your workspace when you import it. If you see
+`Cannot find package '@typescript-eslint/parser'`, that is the install line above
+missing.
 
 The preset is **syntactic only** — it never sets `parserOptions.project` or
 `projectService`. Nothing it enforces requires type information, which is what
@@ -36,55 +46,20 @@ three config entries, matched by glob rather than by directory depth:
 
 | Entry | Files | Rules |
 |---|---|---|
-| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the nine file-scoped rules below |
+| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the eleven file-scoped rules — see [`rules/`](rules/INDEX.md) |
 | `template-kit/contract-files` | `**/Renderer.tsx`, `**/schema.ts`, `**/fill-spec.ts`, `**/fixtures.ts` | `no-client-directive-in-contract` |
 | `template-kit/renderer` | `**/Renderer.tsx` | `props-from-schema` |
 
 Server-vs-client scoping is decided **per file**, by the `"use client"` directive
-prologue — not by an import graph or a build transform. A file carrying the
-directive is an island: it hydrates in the browser, so effects, state, event
-handlers, and inline `style` are legal there and the corresponding rules exempt
-it. A rule that does not exempt islands says so explicitly below.
+prologue — see [server vs client](rules/server-vs-client.md) for what that means
+and exactly which rules stop at that boundary.
 
 ## The rules
 
-Rules that are properties of one file live here. Rules that are properties of the
-**tree** — a missing contract file, a slot declared in `schema.ts` but unmarked in
-`Renderer.tsx`, a CSS rule — cannot be expressed one-file-at-a-time; they belong to
-`template-kit check` (not yet built) under the same `template-kit/<id>` namespace.
-One namespace, two venues.
-
-### Server-rendered code
-
-| Rule | What it bans |
-|---|---|
-| `no-nondeterminism` | Clock/randomness reads (`Date.now()`, `new Date()` with no args, `Math.random()`, `crypto.randomUUID()`/`getRandomValues()`, `performance.now()`) — the publisher and the editor must render byte-identical HTML. Exempt inside an island. |
-| `no-client-runtime-in-server` | Effects, state hooks, event handlers, and browser globals (`fetch`, `window`, `document`, …) — a Renderer must be a pure function of its props. Exempt inside an island. |
-| `no-inline-style` | The `style=` JSX prop — it bypasses the cascade and Tailwind's responsive prefixes. Exempt inside an island. |
-| `no-raw-element` | Raw `<section>`/`<img>` — each has a contract-bearing primitive (`Section`/`Image`) that must be used instead. |
-| `image-bare-needs-reason` | `<Image bare>` with no `// bare: <reason>` comment justifying the skipped frame. |
-| `no-css-import-from-render-path` | A `.css` import anywhere in a section's render path — the SSR graph drops it silently. Import CSS from the section's own `styles.css` instead. |
-
-### Islands
-
-| Rule | What it checks |
-|---|---|
-| `serializable-island-props` | A statically-visible prop passed to an island (a literal function, `new Date()`/`Map`/`Set`/etc., a bigint literal, `NaN`/`Infinity`) that cannot cross the server→browser JSON boundary. It is the static twin of the runtime check — see [islands.md](islands.md#props-must-be-json-serializable). |
-
-### Universal — no island exemption
-
-| Rule | What it bans |
-|---|---|
-| `no-hex` | Hex color literals and CSS color functions (`oklch`/`oklab`/`rgb`/`rgba`/`hsl`/`hsla`/`color-mix`) in a color context (a Tailwind color-utility bracket, an arbitrary-property color declaration, or an inline `style` value). Token discipline is universal — see [theme-and-css.md](theme-and-css.md#color-roles). |
-
-Deliberate asymmetry: `no-inline-style` exempts islands, `no-hex` does not — the
-hydration boundary is not a palette boundary. A section carries no palette of its
-own in either render path.
-
-### Markers and schema
-
-| Rule | What it checks |
-|---|---|
-| `slot-marker-literal` | A slot-key-bearing marker (`<Slot id>`, `<SlotGroup id>`, `slotId`, `data-slot-id`, `data-slot-group`) must carry a string-literal key, not an expression — the slot-marker completeness check (`template-kit check`) reads these keys statically. `SlotItem` is exempt: its prop is `index: number`, an array position, so there is no schema key to cross-check. |
-| `props-from-schema` | A `Renderer.tsx`'s exported `Props` type must come from `SectionProps<typeof schema>`. A hand-written `Props` shadows that inference and drifts. |
-| `no-client-directive-in-contract` | `"use client"` in a section's four contract files (`Renderer.tsx`, `schema.ts`, `fill-spec.ts`, `fixtures.ts`) — the platform reads them outside a browser; marking one an island takes the section's server-rendered HTML with it. |
+Every rule the preset enforces — what it bans, why, and a before/after fix — is
+documented once, per id, in [`rules/`](rules/INDEX.md). Rules scoped to a single
+file are enforced here, by this preset; rules scoped to the **tree** — a missing
+contract file, a slot declared in `schema.ts` but unmarked in `Renderer.tsx`, a CSS
+budget — cannot be expressed one-file-at-a-time and belong to
+[`template-kit check`](check.md) under the same `template-kit/<id>` namespace. One
+namespace, two venues: the id printed by either failure resolves to exactly one page.

package/docs/llms.txt

@@ -4,9 +4,11 @@
 > inside the npm package so an agent can read it locally, versioned in lockstep
 > with the code it describes.
 
-Status: 0.0.x. The schema system, the contract primitives, and the theme tokens are
+Status: 0.0.x. The schema system, the contract primitives, and the theme system are
 complete — a section is authorable end to end against the kit. The `template-kit`
-CLI's commands arrive with the surfaces they drive.
+CLI's `check` and `theme` commands are implemented — see [Check](check.md) and
+[Theme and CSS](theme-and-css.md#generating-themecss); its other commands arrive with
+the surfaces they drive.
 
 Everything an author writes a section against is imported from the package root —
 `@homepages/template-kit`, no subpath imports. The two CSS entries
@@ -27,14 +29,27 @@ Everything an author writes a section against is imported from the package root
   and `Image` (responsive `<picture>`, empty-state box). Plus the marker-attribute
   contract (`ATTR_SLOT_ID`, `ATTR_SLOT_ITEM`, …). Presentation is the template's own JSX.
 - [Theme and CSS](theme-and-css.md): the two CSS entries and how they load; import
-  Tailwind exactly once; `TokenTheme` + `compileThemeToCss`; the breakpoint ladder
-  (base 350, `bp390` `bp425` `bp512` `md` `lg` `bp1440` `bp1920`); the opt-in
-  `content-visibility` recipe for long, image-heavy pages, and why it requires a
-  full-screen overlay to be appended to `document.body` rather than rendered inside
-  the section.
+  Tailwind exactly once; `base.css` ships no reset of its own — it requires the
+  preflight your Tailwind entry brings; `TokenTheme` — a template declares its own
+  tokens under names it chooses (`colors` `fonts` `type` `radii` `shadows` `layout`,
+  kebab-case, emitted verbatim) and each becomes a Tailwind utility; the `template-kit
+  theme` CLI command that compiles `theme.ts` to the generated `theme.css` the
+  Tailwind entry `@import`s after the kit's `styles.css`; the required `document`
+  block; the breakpoint ladder (base 350, `bp390` `bp425` `bp512` `md` `lg` `bp1440`
+  `bp1920`); the opt-in `content-visibility` recipe for long, image-heavy pages, and
+  why it requires a full-screen overlay to be appended to `document.body` rather than
+  rendered inside the section.
 - [README](../README.md): install, exports, and the release flow.
 - [Islands](islands.md): interactivity — client components, the serializable-props contract, editor options, and the browser loader.
-- [ESLint preset](eslint.md): `@homepages/template-kit/eslint`, the zero-config flat-config
-  preset covering the eleven `template-kit/*` authoring rules — determinism, the
-  server/island boundary, serializable island props, the marker and schema contracts,
-  and token discipline.
+- [ESLint preset](eslint.md): `@homepages/template-kit/eslint`, the flat-config preset —
+  a two-line config with no parser wiring, over an ESLint + `@typescript-eslint/parser`
+  install of your own (the kit depends on neither — both resolve from your workspace).
+  Its three-entry glob scope. Per-rule reference lives in `rules/`.
+- [Check](check.md): the `template-kit check` CLI command — the toolchain it runs (your
+  TypeScript, ESLint and esbuild, resolved from your workspace), its six per-template
+  stages, the once-per-invocation dependency gates, `--all`/`--json`, the report shape,
+  and the exit code. Thresholds are fixed platform acceptance criteria, not configurable.
+- [Rules](rules/INDEX.md): every rule-id a lint or `check` failure can print, under the
+  `template-kit/<id>` namespace, one page each at `docs/rules/<id>.md` — Rule / Reason /
+  Fix / Before→After. **The loop:** see an id in a failure → read `docs/rules/<id>.md` →
+  fix. Nothing else to search for; the id is the filename.

package/docs/primitives.md

@@ -176,6 +176,11 @@ When `src` is empty the wrapper renders alone as a neutral `role="img"` rect, ke
 layout box and the slot selectable. **That deterministic empty state is the reason the
 frame exists**, so pass `aspectRatio` rather than sizing the image from its own content.
 
+The frame's placeholder fill rides on `.tr-image-frame` (from
+[`base.css`](theme-and-css.md#basecss-requires-a-tailwind-entry)), not on a theme utility:
+you name your own tokens, so no primitive may assume a colour of yours exists. Retint it
+per template by setting `--tr-image-frame-bg`; it defaults to a neutral grey.
+
 **Responsive.** Given a `responsive` descriptor the `<img>` is wrapped in `<picture>` with
 per-format AVIF/WebP `<source srcset>` (the base raster stays on the `<img>`), plus a
 media-gated mobile crop when `responsiveMobile` + `mobileBreakpoint` are set, and carries

package/docs/rules/INDEX.md

@@ -0,0 +1,65 @@
+---
+purpose: Router for the rule corpus — every template-kit/<id> an author can hit, and the page that explains it.
+status: living
+related: [server-vs-client.md, ../eslint.md, ../check.md, ../INDEX.md]
+updated: 2026-07-14
+---
+# Rules
+
+Every authoring rule the kit enforces is printed under one namespace, `template-kit/<id>`,
+and resolves to exactly one page here: `docs/rules/<id>.md`.
+
+**One namespace, two venues.** Some rules are properties of **one file** (a `Date.now()`
+in a Renderer) and are enforced by the ESLint preset. Others are properties of the
+**tree** (a slot declared in `schema.ts` but never marked in the JSX, a stylesheet, a
+dependency, a byte budget) and cannot be expressed one file at a time; those are enforced
+by [`template-kit check`](../check.md). You never need to know which engine produced a
+violation — only the id, which names its page either way.
+
+Read [server vs client](server-vs-client.md) first if you are here for any rule that
+mentions "server-rendered code" or an island. It is the one concept those rules assume,
+and it is explained there rather than on each of them.
+
+| Rule | Venue | What it enforces |
+|---|---|---|
+| [`no-nondeterminism`](no-nondeterminism.md) | eslint | No clock or randomness reads in server-rendered code. |
+| [`no-client-runtime-in-server`](no-client-runtime-in-server.md) | eslint | No effects, state, event handlers, network, or browser globals in server-rendered code. |
+| [`serializable-island-props`](serializable-island-props.md) | eslint | Props handed to an island must be JSON-serializable. |
+| [`no-client-directive-in-contract`](no-client-directive-in-contract.md) | eslint | No "use client" in a section's four contract files. |
+| [`props-from-schema`](props-from-schema.md) | eslint | A Renderer's Props type must be derived from schema.ts, not hand-written. |
+| [`no-inline-style`](no-inline-style.md) | eslint | No inline style= in server-rendered JSX. Islands are exempt. |
+| [`no-raw-element`](no-raw-element.md) | eslint | No raw `<section>` or `<img>` — use `<Section>` and `<Image>`. |
+| [`image-bare-needs-reason`](image-bare-needs-reason.md) | eslint | `<Image bare>` needs a `// bare:` comment saying why it skips the frame. |
+| [`slot-marker-literal`](slot-marker-literal.md) | eslint | A slot-marker key must be a string literal, not an expression. |
+| [`no-hex`](no-hex.md) | eslint | No hard-coded colours — the one legal colour function is a `color-mix()` over theme-derived arguments. Islands are NOT exempt. |
+| [`no-css-import-from-render-path`](no-css-import-from-render-path.md) | eslint | No relative/absolute .css import from a section's render path — a package's is the sanctioned channel. |
+| [`bundle-incomplete`](bundle-incomplete.md) | check | A section folder is missing one of its four required files. |
+| [`bundle-binary-asset`](bundle-binary-asset.md) | check | A binary asset file sits in a section folder — not supported yet. |
+| [`schema-invalid`](schema-invalid.md) | check | A section's schema.ts or fill-spec.ts fails a contract assertion, or cannot be loaded. |
+| [`fixtures-invalid`](fixtures-invalid.md) | check | A section's fixtures.ts does not satisfy the fixture-module shape. |
+| [`manifest-invalid`](manifest-invalid.md) | check | A template's manifest.json is missing, unparseable, or violates the manifest contract. |
+| [`missing-slot-marker`](missing-slot-marker.md) | check | An editable slot in schema.ts has no marker in the section's JSX. |
+| [`slot-group-marker`](slot-group-marker.md) | check | A group with two or more members has no `<SlotGroup>` wrapper. |
+| [`css-reason`](css-reason.md) | check | A hand-written CSS file must open with a `css-reason:` comment. |
+| [`no-bare-css-import`](no-bare-css-import.md) | check | No @import in hand-written CSS — the browser drops it silently. |
+| [`unlayered-fence`](unlayered-fence.md) | check | An `/* unlayered: */` escape hatch must be balanced and give a reason. |
+| [`sidebar-order`](sidebar-order.md) | check | Schema slot order must match the order the page renders them in. |
+| [`typecheck`](typecheck.md) | check | The template must compile under TypeScript. |
+| [`parse-error`](parse-error.md) | check | A file could not be parsed at all — a syntax error, not a rule violation. |
+| [`determinism-drift`](determinism-drift.md) | check | Rendering the same fixture twice must produce byte-identical HTML. |
+| [`render-invariant`](render-invariant.md) | check | Rendered output must carry no [object Object], bare null/undefined/NaN leaf, or src-less `<img>`. |
+| [`lockfile-missing`](lockfile-missing.md) | check | The workspace has no package-lock.json. |
+| [`lockfile-stale`](lockfile-stale.md) | check | The lockfile does not satisfy package.json — an `npm ci` would fail. |
+| [`single-react`](single-react.md) | check | The installed tree carries more than one copy of react or react-dom. |
+| [`audit-severity`](audit-severity.md) | check | A dependency carries a high or critical security advisory. |
+| [`license-denied`](license-denied.md) | check | A production dependency's license is not on the allowlist. |
+| [`size-renderer-bundle`](size-renderer-bundle.md) | check | A section's renderer bundle exceeds its byte budget. |
+| [`size-section-css`](size-section-css.md) | check | A section's compiled CSS exceeds its byte budget. |
+| [`no-templates`](no-templates.md) | check | The workspace has no template to check at all. |
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and which rules stop at
+  the hydration boundary.
+- [ESLint preset](../eslint.md) — setting the preset up in a template workspace.
+- [Check](../check.md) — running `template-kit check`, its flags, output shape, and exit code.

package/docs/rules/audit-severity.md

@@ -0,0 +1,91 @@
+---
+purpose: The template-kit/audit-severity authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, license-denied.md]
+updated: 2026-07-14
+---
+# template-kit/audit-severity
+
+> A dependency with a **high** or **critical** advisory fails. Low and moderate pass, on
+> purpose. There is no way to suppress it.
+
+## Rule
+
+`npm audit` runs over your workspace, and a violation is reported for each advisory at
+severity **high** or **critical**.
+
+**Low and moderate advisories are a deliberate pass.** They are not "not yet enforced" —
+they are not enforced. Nobody will ask you to clear them.
+
+**There is no suppression mechanism.** No inline waiver, no ignore file, no severity
+override. If you are looking for the flag, there isn't one, and that is the design.
+
+## Reason
+
+The kit lets you reach for third-party packages — a carousel, a map SDK, a date formatter —
+because a section that has to hand-write everything is a section nobody finishes. The
+consequence is that your dependency tree ships to a published page we host for a customer,
+so the supply chain is part of the submission.
+
+This gate is the **floor**, not a review. Cutting at high/critical is what keeps it a floor:
+a rule that fired on every transitive moderate would be a rule everyone learned to route
+around, and the exception would swallow the check. Two severities, no exceptions, and a
+clear answer to "can I ship this."
+
+## Fix
+
+In order of preference:
+
+1. **`npm audit fix`** — resolves most advisories by moving a transitive dependency inside
+   its existing range.
+2. **Upgrade the offending package.** If the fix is in a new major, `npm audit fix --force`
+   will take it, but read what it changes first.
+3. **Drop the package.** An advisory with no fix available is a package with no fix
+   available. Replace it, or hand-write the part of it you actually use.
+
+Then re-run `npm audit` and commit the lockfile.
+
+### Before
+
+```text
+$ npm audit
+# npm audit report
+
+marked  <4.0.10
+Severity: high
+Inefficient Regular Expression Complexity in marked
+fix available via `npm audit fix --force`
+
+1 high severity vulnerability
+```
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "marked": "^3.0.8"
+  }
+}
+```
+
+### After
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "marked": "^14.1.2"
+  }
+}
+```
+
+```text
+$ npm audit
+found 0 vulnerabilities
+```
+
+## See also
+
+- [`license-denied`](license-denied.md) — the other supply-chain gate on your production
+  dependencies.
+- [`lockfile-stale`](lockfile-stale.md) — commit the lockfile the fix regenerated.