@homepages/template-kit 0.2.0 → 0.4.0

package/docs/recipes/second-template.md

@@ -0,0 +1,49 @@
+---
+purpose: Add another template to the workspace.
+status: living
+related: [../new.md, ../check.md]
+updated: 2026-07-15
+---
+# Add a second template
+
+## Goal
+
+Add another template to the workspace.
+
+## The delta
+
+```bash
+template-kit new <name>
+```
+
+`new` creates `templates/<name>/` as a working starter template — the same
+starter shape a fresh workspace ships (a text slot, an image slot, a
+fact-bound slot, an option, fixtures, a fill spec, a `components/` folder, a
+`"use client"` island, `theme.ts`/`theme.css`, `manifest.json`) — and it
+already passes `check` as-is. Edit its sections from there.
+
+A template is a plain folder under `templates/`. Adding one does not
+duplicate anything: every template in the workspace shares the same kit
+version, the same root `package.json`/lockfile, and the same
+`tsconfig.json`/ESLint config. There is nothing per-template to configure
+beyond the folder itself.
+
+`new` refuses to overwrite an existing `templates/<name>/` folder.
+
+## Commands
+
+```bash
+template-kit new <name>
+template-kit check <name>
+```
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop) — a freshly
+created template is check-clean before you change a line.
+
+## See also
+
+- [Adding templates and sections](../new.md) — the full command, including
+  `new-section` for adding a section within a template.
+- [Check](../check.md) — the gate every template (new or edited) must pass.

package/docs/recipes/select-slot.md

@@ -0,0 +1,59 @@
+---
+purpose: Give the user a closed set of choices — an editable content slot, distinct from a behavioral enum option.
+status: living
+related: [../vocabulary.md, ../schema-system.md]
+updated: 2026-07-15
+---
+# A select slot — a closed set of choices
+
+## Goal
+
+Give the user a closed set of choices — an editable content slot, distinct from
+a behavioral `enum` option.
+
+## The delta
+
+A `select` slot still needs a `source` or a `produced_by`, exactly like every
+other slot type — `values` alone only declares the closed set the editor's
+dropdown offers. The cleanest no-AI fill for a closed set is usually a
+`direct()` fact that already resolves to one of a closed set of strings:
+
+```ts
+// schema.ts — add a select slot, seeded from a closed-vocabulary fact
+property_type: {
+  type: "select",
+  editable_by_user: true,
+  required: false,
+  values: ["single_family", "condo_townhome", "multi_family", "investment"],
+  source: direct("property_type"),
+  display_name: "Property type",
+},
+```
+
+```tsx
+// Renderer.tsx — read it like any other text-shaped slot
+<Slot id="property_type" textLeaf>
+  <span>{slots.property_type}</span>
+</Slot>
+```
+
+`slots.property_type` is `string | null` (required is `false`). The general
+`source`/`produced_by` contract still applies to a `select` slot, but no
+fill-spec decision type constrains its output to the closed `values` set —
+so `source: direct(...)` (a fact that already resolves within the set) is
+the reliable way to fill one.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [The closed vocabulary](../vocabulary.md#slot-types) — the slot-type table, including
+  where `select` sits next to `text`/`number`/etc.
+- [The schema system](../schema-system.md) — the full `schema.ts` contract, including
+  `direct()`/`derived()` binding.

package/docs/recipes/static-asset.md

@@ -0,0 +1,103 @@
+---
+purpose: Add a graphic — an icon, a divider, a photo, a font — to a section.
+status: living
+related: [../assets.md, ../check.md, ../rules/bundle-binary-asset.md, image-slot-crop.md, ../theme-and-css.md]
+updated: 2026-07-16
+---
+# Add a static asset (image, icon, font)
+
+## Goal
+
+Add a graphic — an icon, a divider mark, a photo, a custom font — to a section.
+
+## The delta
+
+A binary asset — an image, a font, a video, an archive — may live in a section's own
+`sections/<section>/assets/` folder, but only if the section references it: imported in
+`Renderer.tsx` (`import crest from "./assets/crest.svg"`) or `url()`-referenced from one
+of the section's CSS files. An unreferenced binary in the folder is flagged; see
+[`bundle-binary-asset`](../rules/bundle-binary-asset.md) for the rule and why.
+
+A file shared across sections — a logo, a brand webfont, a texture — lives at the
+**template level** instead, referenced the same way with a `../../assets/…` path. See
+[Static assets](../assets.md) for both paths and the full reference contract. What you
+reach for depends on what the graphic is:
+
+**A vector graphic — an icon, a divider, a decorative mark used only here.** Inline it as
+SVG markup directly in the JSX that draws it. It is text, ships with the rest of your
+component, and needs no file or import at all:
+
+```tsx
+// sections/hero/components/ScrollArrow.tsx
+export function ScrollArrow() {
+  return (
+    <svg viewBox="0 0 16 16" className="h-4 w-4" fill="none" aria-hidden="true">
+      <path d="M8 3v10M3 9l5 4 5-4" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import { ScrollArrow } from "./components/ScrollArrow";
+// …
+<ScrollArrow />
+```
+
+That markup's bytes ship inside the section's renderer bundle, so they count
+toward the same byte budget as the rest of your JSX — see the size stage in
+[Check](../check.md).
+
+**A raster image or watermark used only in this section.** Add it under
+`sections/<section>/assets/` and import it into the component:
+
+```tsx
+// sections/hero/Renderer.tsx
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
+
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
+}
+```
+
+Or reference it from the section's CSS with `url()` instead of importing it — see
+[Static assets](../assets.md) for both forms. Either way the file must be referenced:
+an asset nothing imports or `url()`-references is flagged by
+[`bundle-binary-asset`](../rules/bundle-binary-asset.md).
+
+**A photo.** Not a section asset at all — a section never ships a photo file. A
+photo arrives at runtime through an `image` slot: declare it in `schema.ts`,
+produce it with an `image-assign` decision in `fill-spec.ts`, and render it
+through the `<Image>` primitive, which reads `url`, `alt`, and `responsive` off
+the slot's resolved value. See
+[Image slot with a locked crop](image-slot-crop.md) for the full shape.
+
+**A custom font shared across the template.** Declared once, for the whole
+template, in the theme's `fonts` and optional `fontFaces` block. See
+[Theme and CSS](../theme-and-css.md). A font only one section uses can instead
+live in that section's `assets/` folder and be declared with a `@font-face` in
+the section's own CSS — see [Static assets](../assets.md).
+
+## Commands
+
+None — inlining SVG markup and declaring a slot are content edits. No CLI
+command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [Static assets](../assets.md) — the full reference/import contract, template
+  level vs. section folder.
+- [`bundle-binary-asset`](../rules/bundle-binary-asset.md) — the rule that
+  flags an unreferenced binary in a section folder, and the SVG-inlining fix.
+- [Check](../check.md) — the size stage a large inlined SVG or a bloated
+  renderer bundle counts against.
+- [Image slot with a locked crop](image-slot-crop.md) — the real channel for a
+  photo: an `image` slot, an `image-assign` decision, and the `<Image>`
+  primitive.
+- [Theme and CSS](../theme-and-css.md) — where a template's fonts are declared.

package/docs/recipes/third-party-package.md

@@ -0,0 +1,90 @@
+---
+purpose: Use a third-party npm package in a section.
+status: living
+related: [../islands.md, ../pack.md, ../rules/single-react.md, ../rules/no-bare-css-import.md, ../rules/no-css-import-from-render-path.md]
+updated: 2026-07-15
+---
+# Use a third-party npm package in a section
+
+## Goal
+
+Use an npm package in a section.
+
+## The delta
+
+Install the package like any npm dependency:
+
+```bash
+npm i swiper
+```
+
+**Only a published version.** `pack` refuses to produce a submission zip when a
+dependency uses a local `file:`/`link:` protocol — depend on a real published
+version, never a path on your own machine.
+
+**Where you import it from matters.** A client library — a carousel, a map SDK,
+anything that touches `window` or the DOM — is imported inside a `"use client"`
+island, the same as any other browser-only code:
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …
+}
+```
+
+A server-side import — one that lands in the Renderer or a plain component it
+imports, not behind `"use client"` — must stay pure and deterministic: no reads
+of the clock, randomness, or the network at render time. A package built for a
+browser runtime (it touches `window`, schedules a timer, generates an id) does
+not belong there; move the usage into an island.
+
+**A package that ships its own stylesheet** is imported by its bare specifier,
+from the module that renders it — the Renderer's import graph (the components
+and islands it imports, transitively) is what the CSS build bundles and
+harvests for the section's stylesheet:
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/css"; // ← the sanctioned channel: a bare specifier reaches this section's layer
+```
+
+A **local** `.css` import from that same render path is a different, banned case
+— see [`no-css-import-from-render-path`](../rules/no-css-import-from-render-path.md)
+for the full distinction between the two, and
+[`no-bare-css-import`](../rules/no-bare-css-import.md) for why a hand-written
+stylesheet can't reach the package's CSS with its own `@import` instead.
+
+## Commands
+
+```bash
+npm i <package>
+```
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop) — a green
+`check` after the install confirms the package resolves, its CSS (if any)
+landed in the section's layer, and the workspace still carries exactly one copy
+of React.
+
+## See also
+
+- [Islands](../islands.md) — writing a `"use client"` island; a third-party
+  client library is fine inside one, never in a Renderer.
+- [`template-kit pack`](../pack.md) — why a `file:`/`link:` dependency blocks a
+  submission.
+- [`single-react`](../rules/single-react.md) — a package that pulls its own
+  copy of React breaks hydration; the installed tree may carry only one.
+- [`no-css-import-from-render-path`](../rules/no-css-import-from-render-path.md) —
+  bare package specifier (legal) vs. a local `.css` import (banned) from a
+  section's render path.
+- [`no-bare-css-import`](../rules/no-bare-css-import.md) — why a hand-written
+  stylesheet can't reach a package's CSS with its own `@import` either.

package/docs/rules/INDEX.md

@@ -1,8 +1,8 @@
 ---
 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, ../INDEX.md]
-updated: 2026-07-14
+related: [server-vs-client.md, ../eslint.md, ../check.md, ../INDEX.md]
+updated: 2026-07-15
 ---
 # Rules
 
@@ -13,8 +13,8 @@ and resolves to exactly one page here: `docs/rules/<id>.md`.
 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`. You never need to know which engine produced a violation — only
-the id, which names its page either way.
+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,
@@ -31,9 +31,13 @@ and it is explained there rather than on each of them.
 | [`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. Islands are NOT exempt. |
+| [`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 | An unreferenced binary asset sits in a section folder. |
+| [`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. |
@@ -41,6 +45,7 @@ and it is explained there rather than on each of them.
 | [`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. |
@@ -50,9 +55,13 @@ and it is explained there rather than on each of them.
 | [`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. |
+| [`size-island-bundle`](size-island-bundle.md) | check | A section's island (browser) bundle exceeds its byte budget. |
+| [`size-assets`](size-assets.md) | check | A section's static assets exceed their 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/bundle-binary-asset.md

@@ -0,0 +1,83 @@
+---
+purpose: The template-kit/bundle-binary-asset authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, bundle-incomplete.md, ../primitives.md, ../assets.md]
+updated: 2026-07-16
+---
+# template-kit/bundle-binary-asset
+
+> A static asset may live in a section folder — but only if something references it. An
+> unreferenced binary is dead weight and can never be served.
+
+## Rule
+
+A binary asset inside a section folder is allowed **only when the section references it** —
+imported in `Renderer.tsx` (`import crest from "./assets/crest.svg"`) or `url()`-referenced
+from one of the section's CSS files. A binary that nothing references is flagged. The check
+looks two ways to find candidates:
+
+- **By extension** — `.svg`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, `.avif`, `.ico`,
+  `.woff`/`.woff2`, `.ttf`, `.otf`, `.eot`, `.mp4`, `.webm`, `.mov`, `.mp3`, `.wav`,
+  `.pdf`, `.zip`.
+- **By content** — any other file whose first bytes contain a NUL byte.
+
+## Reason
+
+A referenced asset is first-class: the build content-hashes it to a stable
+`/section-assets/` URL and the publish pipeline uploads it — identical in the `dev`
+preview, the editor, and the published page. An *unreferenced* binary has no such URL: it
+is never emitted or uploaded, yet it still counts toward the section's content hash (its
+identity). So it is pure dead weight — a file that ships nowhere.
+
+## Fix
+
+Either reference the asset, or delete it.
+
+- **Reference it from a component:** `import crest from "./assets/crest.svg"` and render it
+  with the `Image` primitive — `<Image src={crest} alt="…" />`. See [Static assets](../assets.md).
+- **Reference it from CSS:** `background-image: url("./assets/crest.svg")` (or a
+  `@font-face` `src`) in the section's `styles.css`.
+- **Delete it** if it is left over and unused.
+
+### Before
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+  assets/
+    crest.svg          ← nothing imports or url()-references this file
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
+
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
+}
+```
+
+For a tiny glyph or divider, prefer inline `<svg>` markup over a file at all — it ships with
+your JSX, needs no asset at all, and costs no extra request:
+
+```tsx
+export function ScrollArrow() {
+  return (
+    <svg viewBox="0 0 16 16" className="h-4 w-4" fill="none" aria-hidden="true">
+      <path d="M8 3v10M3 9l5 4 5-4" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+```
+
+## See also
+
+- [Static assets](../assets.md) — where an asset may live and how to reference it.
+- [`bundle-incomplete`](bundle-incomplete.md) — the other rule on the folder's contents.
+- [Contract primitives](../primitives.md) — `Image`, which renders an asset URL you import.

package/docs/rules/bundle-incomplete.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/bundle-incomplete authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../schema-system.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/bundle-incomplete
 
@@ -30,7 +30,7 @@ Two near-misses do **not** satisfy it:
   searched for down the tree.
 
 Everything else in the folder is unconstrained. `components/`, `hooks/`, `utils/`, any
-nesting, any number of support modules, islands, stylesheets, enhancers: the check has no
+nesting, any number of support modules, islands, stylesheets: the check has no
 opinion about them, and neither does the rest of the kit.
 
 ## Reason

package/docs/rules/css-reason.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/css-reason authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/css-reason
 
@@ -36,7 +36,7 @@ and cannot leak into another section on the same page. Hand-written CSS gives al
 up.
 
 There is exactly one thing utilities cannot do: style **DOM that Tailwind's scanner never
-sees**. Markup an enhancer builds at runtime has no class in your source for the scanner
+sees**. Markup an island builds at runtime has no class in your source for the scanner
 to find, and a third-party widget's own DOM was never yours to put classes on. Those are
 the cases hand-CSS exists for.
 
@@ -67,7 +67,7 @@ classes on the markup.
 ### After
 
 ```css
-/* css-reason: styles the marker DOM the neighborhood-map enhancer builds at runtime —
+/* css-reason: styles the marker DOM the neighborhood-map island builds at runtime —
    the nodes are created by the map library after hydration, so Tailwind's scanner never
    sees a class to compile. */
 .tr-map-marker {

package/docs/rules/fixtures-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/fixtures-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/fixtures-invalid
+
+> `fixtures.ts` is the one contract file nothing else parses for you. This is that parse.
+
+## Rule
+
+The default export of `fixtures.ts` must satisfy the fixture-module shape:
+
+```ts
+{
+  base: {
+    slots: { /* every required slot, with a valid value */ },
+    options: { /* optional */ },
+    anchors: { /* optional */ },
+    variants: { /* optional */ },
+  },
+  option_matrix: [ /* optional: { label?, options } entries */ ],
+  states: { /* optional: named scenario → { label?, slots?, options?, anchors?, variants? } */ },
+}
+```
+
+`base` is required and must be an object holding a `slots` record — every other key is
+optional. Each violation names the exact path inside the module that's wrong (`"base"`,
+`"base.slots"`, `"states.empty-address"`, …) and what shape was expected there instead.
+
+## Reason
+
+`schema.ts` and `fill-spec.ts` are both Zod-parsed on the way into every other check, so a
+malformed one is caught immediately. `fixtures.ts` used to be the exception: nothing
+touched it until the render stage read it directly, so a wrong shape there surfaced as a
+raw crash mid-render, blamed on whatever line happened to dereference the missing field —
+never on the fixture that was actually wrong.
+
+This gate exists to move that failure to where the mistake was made, with a message about
+the fixture module instead of a stack trace from three files away.
+
+## Fix
+
+Read the message's path — it points at the exact key that's wrong — and bring that key's
+shape in line with what's documented above.
+
+### Before
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: 12 },
+    //                                                 ^ label must be a string
+  },
+};
+
+export default fixtures;
+```
+
+```text
+Section "hero": fixtures.ts — "states.no-photo.label": Expected string, received number.
+```
+
+### After
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: "No hero photo" },
+  },
+};
+
+export default fixtures;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — `fixtures.ts`'s place among the section's
+  four contract files.
+- [`schema-invalid`](schema-invalid.md) — the sibling gate on `schema.ts` and
+  `fill-spec.ts`.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when
+  `fixtures.ts` is missing outright, rather than present and wrong.

package/docs/rules/license-denied.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/license-denied authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, audit-severity.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/license-denied
 
@@ -31,8 +31,16 @@ Two cases people expect to slide through, and neither does:
 - **A missing `license` field is a denial**, not a pass. An unlicensed package is not a
   permissive one — by default, no rights are granted at all.
 
-**Scope: the production tree only.** `devDependencies` are not evaluated — your bundler,
-your test runner, and your formatter do not ship to anyone.
+**Scope: the production tree only.** "Production tree" means exactly what
+`npm ci --omit=dev` installs. `devDependencies` are not evaluated — your bundler, your
+test runner, and your formatter do not ship to anyone.
+
+**An optional peer you have anyway counts.** If a production package declares an
+optional `peerDependency` and your workspace has that package for any reason (even as a
+`devDependency`), npm resolves the peer and keeps it in the `--omit=dev` install — so it
+is in the production tree and its license is checked, transitively. An optional peer you
+do **not** have is never installed and is not evaluated. Run `npm ci --omit=dev` and look
+at the resulting `node_modules` if you want the exact set the check sees.
 
 **There is no per-package override.** No allowlist entry you can add, no waiver comment. By
 design.