@homepages/template-kit 0.3.0 → 0.4.1

package/docs/dev.md

@@ -0,0 +1,187 @@
+---
+purpose: The `template-kit dev` command — the local preview server, what it serves, its URLs, and the agent-facing render endpoints.
+status: living
+related: [INDEX.md, theme-and-css.md, schema-system.md, check.md, islands.md]
+updated: 2026-07-16
+---
+# template-kit dev
+
+`template-kit dev` is the local preview server for a workspace's templates. It
+renders every section against its fixtures the same way the platform does —
+server-side, with your template's theme and compiled Tailwind utilities — so you
+see real output while you author, and reload as you edit.
+
+## Usage
+
+```bash
+template-kit dev                  # serve every template in the workspace
+template-kit dev <template>       # preselect one template in the UI
+template-kit dev --port 4000      # choose the port (default 5180)
+```
+
+Run it from the workspace root or from inside a template's own folder — running
+from inside a template preselects it on the home launcher. The server serves every
+template it finds under `templates/`, regardless of where you launched it; the
+command runs until you interrupt it (Ctrl-C).
+
+### What it needs installed
+
+```bash
+npm i -D vite @vitejs/plugin-react tailwindcss @tailwindcss/cli
+```
+
+Like [`check`](check.md), `dev` runs **your** toolchain, resolved from your
+workspace — Vite renders and reloads your sections, and Tailwind compiles your
+theme's utilities. None of these are dependencies of the kit; they resolve from
+your install, so the versions you pinned are the ones that run. A missing one is
+reported by name with the line to install it.
+
+Screenshots (below) additionally need Playwright, which is optional:
+
+```bash
+npm i -D @playwright/test && npx playwright install chromium
+```
+
+## What you get
+
+Open the server's URL and you land on the **home launcher** (`/`) — a template
+selector plus two tool cards, each a self-contained view you open in its own
+page and return from by clicking the `template-kit dev` wordmark:
+
+- **Full template viewer** — opens `/template/<template>`, the whole page as it
+  publishes.
+- **Canvas mirror** — a section and fixture selector, opening
+  `/canvas/<template>/<section>/<fixture>`.
+
+The home launcher is the only place navigation happens; both tools are
+near-chromeless and URL-keyed, so a link to either reloads and shares exactly
+the view you're looking at.
+
+### Live reload
+
+The server watches your template files. Editing a section reloads any open
+preview of it; editing a theme recompiles its Tailwind utilities and hot-swaps
+the stylesheet without a full reload.
+
+### Interactivity (islands)
+
+A section's `"use client"` components hydrate in the preview. The server renders
+the section — including each client component's initial HTML — then the browser
+loads React and hydrates only those components, so they become interactive while
+the rest of the page stays static. A section with no `"use client"` component
+loads no React at all. Editing a client component reloads the preview, re-rendered
+and re-hydrated. See [Islands](islands.md) for the client-component contract.
+
+### Overriding content
+
+A preview page accepts an `overrides` query parameter — base64-encoded JSON,
+deep-merged onto the fixture's resolved props — so you can probe a section against
+content the fixtures don't carry without editing `fixtures.ts`. The decoded JSON
+shape mirrors the props themselves:
+
+```json
+{ "slots": {}, "options": {}, "nav": { "selfAnchor": "", "anchors": {} }, "variants": {} }
+```
+
+All four top-level keys are optional. Merging follows one rule at every level: a
+plain object merges key by key with the fixture's value; anything else — a scalar,
+an array, or `null` — replaces the fixture's value outright. A key the override
+omits keeps the fixture's value; a key set explicitly to `null` replaces it with
+`null`, so you can probe an empty/missing state a fixture doesn't otherwise cover.
+The encoded payload is capped at 16 KB.
+
+## Views: the full template, and the section render behind the canvas
+
+The whole template renders at `/template/<template>` — every section in
+`manifest.json` order, at each section's base fixture (with that instance's manifest
+options), with the template theme and page shell applied and islands hydrating, as
+the published site stacks it. Open it from the home launcher's **Full template
+viewer** card, or point a browser tool at the URL directly. (Cross-section
+`reconcile` rules are a publish-time behavior and are not applied here.)
+
+Every section also has a standalone render at
+`/sections/<template>/<section>/<fixture>` — the document the `/api/screenshot`
+endpoint targets for a single section. It is not a navigation destination in its
+own right.
+
+## Canvas mirror
+
+`/canvas/<template>` — open it from the home launcher's **Canvas mirror** card,
+or directly — mirrors the whole template in an iframe: every section instance
+from `manifest.json`, stacked in one scroll container, exactly as the deliverable
+renders. A paint-only overlay sits on top of it, scoped per section instance —
+the same slot name in two different sections selects independently. Click a slot
+to select it (a gold ring); hover to preview one (a blue ring). Only slots that
+instance's schema marks `editable_by_user: true` select individually — clicking
+anywhere else in a section selects that section instance as a whole. The overlay
+never changes the rendered markup. A mode toggle switches between this canvas
+view and a published view — the clean full-template render, the same page with
+the overlay off. A `template-kit dev` wordmark in the toolbar links back to the
+home launcher (`/`) — the canvas mirror is otherwise chromeless.
+
+The current template, mode, and selection are encoded in the URL as
+`/canvas/<template>?mode=&sel=`, where `sel` names a section instance
+(`<instanceId>`), a slot within it (`<instanceId>~<slotId>`), or one item of
+a repeating slot (`<instanceId>~<slotId>~<itemIndex>`) — so a canvas link
+reloads and shares exactly the view you're looking at.
+
+Selecting a slot (not the section instance as a whole) docks an **edit panel**
+beside the iframe. One JSON editor handles every slot type — you edit the
+slot's value in its own JSON shape rather than switching between per-type
+widgets — alongside a **fill-state badge** (filled / empty / missing) for the
+selected slot and a per-instance **fixture picker**. The picker lists that
+section's whole fixture corpus, including its synthetic empty-content
+fixtures, so you can drive a slot into an empty or missing state without
+touching `fixtures.ts`. Applying a JSON edit, switching the fixture, or
+resetting the instance re-renders that section instance alone, the same way
+it renders in the stack, and swaps its HTML into the iframe in place — no
+page reload, no other instance disturbed — then re-anchors the selection ring
+to the refreshed markup. The kit dev server is the harness's only backend, so
+this loop never touches fixture files, a database, or another service. Edit
+state lives only in the tab: nothing is written to disk, and reloading the
+page loses it. A re-rendered instance's `"use client"` islands stay static —
+they do not re-hydrate — until you rebuild; the panel notes this so it isn't
+mistaken for a bug.
+
+## Agent-facing endpoints
+
+These render a section — or the whole template — without a browser, for an agent
+verifying its work from a terminal.
+
+- `/api/inspect` — the low-context semantic view of a section×fixture as JSON: each
+  declared slot with its `type`, `required`, `fillState` (`filled` / `empty` /
+  `missing`), whether it actually `rendered`, a compact `value` preview, and its
+  `schema.ts:<line>`; plus resolved `options` / `variants` and `nullCorpus` (the
+  synthetic empty-state fixtures, one per optional slot, you can walk to review every
+  missing-content branch). An `empty`/`missing` slot that still shows `rendered: true`
+  is a broken empty shell. Takes `template`, `section`, `fixture`, the same base64
+  `overrides` parameter as a preview page, and `format=text` to add the indented
+  structure outline.
+- `/api/render` — the full structured render payload for one section×fixture
+  (`html`, `resolvedProps`, `slotTree`, `islandMap`, `slotSchema` — that
+  section's slot types and editability — and `slotFills`, the same per-slot
+  fill state `/api/inspect` reports); GET takes `overrides`, POST takes an
+  unencoded JSON body. POST also accepts a manifest `instanceId` in place of
+  `section`+`fixture`: the server resolves that instance's section, its
+  manifest options, and its default fixture the same way the whole-template
+  render does, so re-rendering one instance matches how it renders in the
+  stack. This is what the canvas mirror's edit panel calls to apply a slot
+  edit or switch a fixture.
+- `/api/template-schema?template=<t>` — the editability map for the whole
+  template: every manifest section instance with its per-slot `type` and
+  whether it's user-editable. The canvas mirror's overlay gates selection on
+  this endpoint, not on `/api/render`'s per-section `slotSchema`.
+- `/api/screenshot` — a full-page PNG. Give it `template` + `section` + `fixture` for a
+  section, or `template` alone for the whole template. `width=<px>` sets the viewport
+  (default 1280). Requires Playwright (`npm i -D @playwright/test && npx playwright
+  install chromium`); without it the endpoint answers with the install line.
+
+`/api/catalog.json` returns the full **template × section × fixture** matrix.
+
+## See also
+
+- [Theme and CSS](theme-and-css.md) — the theme the preview compiles, and the
+  `template-kit theme` command that generates it.
+- [Schema system](schema-system.md) — the fixtures the preview renders and the
+  props the `overrides` parameter merges onto.
+- [Check](check.md) — the acceptance gate to run once a section previews cleanly.

package/docs/islands.md

@@ -1,8 +1,8 @@
 ---
 purpose: How interactivity works in a template — client components ("islands"), their props contract, and their editor options.
 status: living
-related: [INDEX.md, eslint.md]
-updated: 2026-07-14
+related: [INDEX.md, eslint.md, dev.md]
+updated: 2026-07-15
 ---
 
 # Islands: interactivity in a template
@@ -17,6 +17,9 @@ If a page contains no islands, it loads no React and no island code — every pa
 still ships the small island loader (a few KB, gzipped), but that loader only ever
 reaches React through a dynamic import it takes when an island is actually on the page.
 
+[`template-kit dev`](dev.md) hydrates a section's islands in its preview, so you can
+exercise one as you author it.
+
 ## Writing one
 
 ```tsx

package/docs/llms.txt

@@ -6,16 +6,30 @@
 
 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 `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.
+CLI's `check`, `theme`, `dev`, `pack`, `new`, and `new-section` commands are
+implemented — see [Check](check.md), [Theme and CSS](theme-and-css.md#generating-themecss),
+[Dev](dev.md), [Pack](pack.md), and [Adding templates](new.md); its remaining
+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
 (`./styles.css`, `./base.css`) are the deliberate exception.
 
+## Start here
+
+To build a section, start at [Quickstart](quickstart.md), then the task
+[Recipes](recipes/INDEX.md) ("how do I X" → the recipe). For the mental model,
+read [Overview](overview.md). For the closed sets — slot types, `direct()`
+sources, `derived()` transforms — see [Vocabulary](vocabulary.md). When a lint
+or `check` prints a rule id, resolve it at `rules/<id>.md`.
+
 ## Docs
 
+- [Quickstart](quickstart.md): the cold-start tutorial — create a workspace,
+  preview the starter's `hero` section, read its four files, make one edit,
+  and check it. Owns the author-loop anchor every recipe ends with.
+- [Overview](overview.md): the one-page mental model — workspace → templates →
+  sections, the four reserved files, and the server-vs-client mapping.
 - [Schema system](schema-system.md): the section authoring contract. A section is
   four files — `schema.ts` (slots + options + `meta.groups`), `fill-spec.ts` (how AI
   fills them), `fixtures.ts` (preview content, built on the kit's golden property
@@ -23,6 +37,9 @@ Everything an author writes a section against is imported from the package root
   `SectionProps<typeof schema>`). Covers the `as const satisfies` requirement, binding
   slots to property facts with `direct()`/`derived()` over a closed vocabulary, and
   fact-driven variants.
+- [Vocabulary](vocabulary.md): the closed authoring vocabulary — the 9 slot
+  types, the `direct()` source fields, and the `derived()` transforms, with
+  selection semantics (which one to pick).
 - [Contract primitives](primitives.md): the only five components the kit ships —
   `Section` (full-bleed section root), `Slot` (`data-slot-id`), `SlotItem` (per-item
   handle in an `object_list` / `image_collection`), `SlotGroup` (`data-slot-group`),
@@ -41,6 +58,10 @@ Everything an author writes a section against is imported from the package root
   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.
+- [Static assets](assets.md): shipping a logo, texture, icon, or brand font with a
+  template — where an asset file lives (template level, or a section folder if the
+  section references it), referencing it from a section's CSS with `url()`/`@font-face`
+  or importing it into a component, and the asset-vs-content-image distinction.
 - [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).
@@ -49,7 +70,24 @@ Everything an author writes a section against is imported from the package root
   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.
+- [Dev](dev.md): the `template-kit dev` CLI command — the local preview server. Its
+  home launcher with a full template viewer (`/template/<template>`) and a canvas
+  mirror (`/canvas/<template>/<section>/<fixture>`), live reload, the Vite + Tailwind
+  toolchain it resolves from your workspace, and the `inspect` / `render` / `screenshot`
+  endpoints an agent uses to verify a render from a terminal.
+- [Pack](pack.md): the `template-kit pack <template>` CLI command — builds a template's
+  submission zip (the template's source, the workspace lockfile, and a stamped
+  `pack-manifest.json`), and the conditions it refuses to pack under: a failing
+  `check`, a missing lockfile, or a local `file:`/`link:` dependency.
+- [Adding templates](new.md): the `template-kit new <template>` and
+  `template-kit new-section <template>/<section>` CLI commands — scaffolding a new
+  template with a working starter section, or adding a bare section (the four
+  reserved contract files, no island) to an existing template. Both refuse to
+  overwrite an existing folder.
 - [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.
+- [Recipes](recipes/INDEX.md): task recipes routed by "how do I…" — each one a minimal,
+  complete delta from the starter's `hero` section (never a from-scratch file), ending in
+  the [author loop](quickstart.md#the-author-loop).

package/docs/new.md

@@ -0,0 +1,27 @@
+---
+purpose: Add a template or a section to a workspace with template-kit new / new-section.
+status: living
+related: [INDEX.md, dev.md, check.md]
+updated: 2026-07-15
+---
+
+# Adding templates and sections
+
+A workspace starts with one template (`templates/starter/`). Add more without
+duplicating any shared context — templates are plain folders, and the kit,
+configs, and docs stay at the workspace root.
+
+## `template-kit new <template>`
+
+Creates `templates/<template>/` with a working starter section (a text slot, an
+image slot, a fact-bound slot, an option, fixtures, a fill spec, a nested
+`components/` folder, and a `"use client"` island), plus `theme.ts`/`theme.css`
+and a `manifest.json`. It passes `check` as-is; edit it into your template.
+
+## `template-kit new-section <template>/<section>`
+
+Adds `templates/<template>/sections/<section>/` — the four reserved contract
+files (`Renderer.tsx`, `schema.ts`, `fill-spec.ts`, `fixtures.ts`), no island.
+Reference the new section by name in the template's `manifest.json`.
+
+Both refuse to overwrite an existing folder.

package/docs/overview.md

@@ -0,0 +1,57 @@
+---
+purpose: The mental model in one page — workspace, templates, sections, and the server-vs-client mapping.
+status: living
+related: [schema-system.md, islands.md, rules/server-vs-client.md]
+updated: 2026-07-15
+---
+# Overview
+
+## Workspace → templates → sections
+
+A **workspace** is the container: one kit version, one shared config. A
+**template** is the authored, submitted unit — a folder of sections plus a
+manifest and theme. A **section** is four reserved files in an otherwise
+free-form folder:
+
+```
+templates/<template>/sections/<section>/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+```
+
+Everything else in that folder — extra components, an island, helpers — is
+yours. See [Adding templates and sections](new.md).
+
+## The four files
+
+| File | Declares | Reference |
+|---|---|---|
+| `schema.ts` | The slots and options the section has | [schema-system.md](schema-system.md#schemats--what-the-section-contains) |
+| `fill-spec.ts` | How AI fills those slots | [schema-system.md](schema-system.md#fill-spects--how-ai-fills-the-slots) |
+| `fixtures.ts` | Sample content for local preview | [schema-system.md](schema-system.md#fixturests--content-for-local-preview) |
+| `Renderer.tsx` | The markup | [schema-system.md](schema-system.md#renderertsx--props-derived-never-hand-written) |
+
+## Slots, options, fill, fixtures
+
+A **slot** is editable content; an **option** is a behavior switch — see
+[the schema system](schema-system.md#schemats--what-the-section-contains) for
+the distinction and [the closed vocabulary](vocabulary.md) for the types.
+**Fill** is how AI assigns slot values via `fill-spec.ts`'s decisions, covered
+in [schema-system.md](schema-system.md#fill-spects--how-ai-fills-the-slots).
+**Fixtures** are the sample content a section previews against, built on the
+kit's golden property dataset — see
+[schema-system.md](schema-system.md#fixturests--content-for-local-preview).
+
+## Server vs client — your Next.js instinct, mapped
+
+A `Renderer.tsx` is a server component: a pure function of props, ships no
+JS. Interactivity goes in a `"use client"` island, hydrated in the browser.
+The directive is **per file**. See [server vs client](rules/server-vs-client.md)
+for the precise rule and [Islands](islands.md) for how to write one.
+
+## The author loop
+
+For the write → preview → check cycle, see
+[the author loop](quickstart.md#the-author-loop).

package/docs/pack.md

@@ -0,0 +1,46 @@
+---
+purpose: The `template-kit pack` command — what it produces, what it refuses, and why.
+status: living
+related: [INDEX.md, check.md]
+updated: 2026-07-15
+---
+# template-kit pack
+
+Build a template's submission artifact: a zip of the template's source plus the
+workspace lockfile, validated and stamped.
+
+## Usage
+
+```bash
+template-kit pack <template>
+```
+
+Run it from the workspace root, or from inside a template folder (the template is
+inferred). In a workspace with several templates you must name one — the submission
+unit is a single template.
+
+## What it produces
+
+`<template>.zip` at the workspace root, containing:
+
+- `pack-manifest.json` — the exact kit version the source was validated against, a
+  content hash of the template tree, the pack timestamp, and a `check` flag
+  recording that validation passed.
+- `package.json` and `package-lock.json` from the workspace root, so the build is
+  reproducible with `npm ci`.
+- `templates/<template>/` — the template's source only (sections, manifest, theme,
+  README). No `node_modules`, no build output, no other template.
+
+## What it refuses
+
+`pack` will not produce a zip when:
+
+- `check <template>` is not green — fix the reported problems first.
+- the workspace has no `package-lock.json` — run `npm install` and commit it.
+- a dependency uses a local `file:`/`link:` protocol — depend on published versions.
+
+Fix the reported cause and run it again.
+
+## See also
+
+- [Check](check.md) — the gate `pack` runs before it will produce a zip.

package/docs/primitives.md

@@ -2,7 +2,7 @@
 purpose: The five contract primitives a section renderer must use, and the marker attributes they emit.
 status: living
 related: [schema-system.md, theme-and-css.md, eslint.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # Contract primitives
 
@@ -106,8 +106,8 @@ whole — no per-item selection, no per-item image cropping, no per-item live su
 `index` **must** be the item's zero-based position in the slot's array as rendered. The
 editor writes edits back by that index, so an index that doesn't match its position edits
 the wrong row. `index` is an array position, not a schema key, so unlike `Slot`'s and
-`SlotGroup`'s `id` it is exempt from the [`template-kit/slot-marker-literal`](eslint.md#markers-and-schema)
-lint rule.
+`SlotGroup`'s `id` it is exempt from the
+[`template-kit/slot-marker-literal`](rules/slot-marker-literal.md) lint rule.
 
 ## `SlotGroup` — slots edited as one unit
 
@@ -206,7 +206,6 @@ magic string.
 | `ATTR_SLOT_ITEM` | `data-slot-item` | one item of a collection slot |
 | `ATTR_SLOT_GROUP` | `data-slot-group` | the container wrapping a group's members |
 | `ATTR_SECTION_INSTANCE_ID` | `data-section-instance-id` | the section root — **written by the platform**, not by a primitive |
-| `ATTR_TR_ENHANCE` | `data-tr-enhance` | opt-in hook telling an enhancer to attach to this element |
 
 Changing what an attribute means is a platform contract break, so these names are stable
 across a major version of the kit.
@@ -215,5 +214,5 @@ across a major version of the kit.
 
 Renderers are pure functions of props: no fetches, no globals, no `useEffect` for data,
 no `Date.now()` / `Math.random()`. They are rendered to static markup by the publisher
-and re-mounted constantly by the editor. Interactivity that needs the browser attaches
-through `data-tr-enhance`, not through render-time side effects.
+and re-mounted constantly by the editor. Interactivity that needs the browser moves into
+a `"use client"` island (see [Islands](islands.md)), never into render-time side effects.

package/docs/quickstart.md

@@ -0,0 +1,102 @@
+---
+purpose: Zero to a rendered, checked section in under an hour, on the scaffolded starter.
+status: living
+related: [overview.md, dev.md, check.md, schema-system.md]
+updated: 2026-07-15
+---
+# Quickstart
+
+This walks the scaffolded starter template end to end: create a workspace, see
+its one section render, read how it's built, make one edit, and check it. It
+does not re-teach the authoring contract — see [Overview](overview.md) for the
+mental model and [Schema system](schema-system.md) for the four files in
+depth.
+
+## Create your workspace
+
+```bash
+npm create homepages-workspace@latest my-workspace
+```
+
+This stamps a workspace with one template, `starter`, and one section in it,
+`hero` — a working section built on the real contract, not a stub. See
+[Overview](overview.md) for what a workspace, template, and section are.
+
+## See it render
+
+```bash
+cd my-workspace
+npm run dev
+```
+
+This opens the **home launcher** in your browser: from there the **canvas
+mirror** renders the template with `starter`'s `hero` in it, and the
+full-template viewer shows the whole page. See [Dev](dev.md) for the launcher,
+the canvas mirror, and live reload.
+
+If you're an agent (or otherwise browser-less), hit the inspect endpoint
+instead — it returns each slot's fill state and a text outline of the render:
+
+```bash
+curl 'http://localhost:<port>/api/inspect?template=starter&section=hero&fixture=typical&format=text'
+```
+
+`typical` is the starter hero's baseline fixture; it also has `left` and
+`long-blurb` fixtures exercising an option and a content-length branch. See
+[Dev](dev.md#agent-facing-endpoints) for `/api/inspect` and the other
+agent-facing endpoints.
+
+## Read the worked example
+
+Before changing anything, read the four files that make up the starter's
+`hero` section — `templates/starter/sections/hero/`:
+
+- `schema.ts` — the slots (`hero_image`, `headline`, `blurb`) and the `align`
+  option, each comment explaining why it's declared the way it is.
+- `fill-spec.ts` — how AI fills `hero_image` and `blurb`; `headline` needs no
+  decision because it's fact-bound.
+- `fixtures.ts` — the `typical` baseline plus the `left`/`long-blurb` states.
+- `Renderer.tsx` — the markup, including the one interactive part: `blurb`
+  wrapped in a `"use client"` island.
+
+Each file is annotated in place. For the concepts behind them, see
+[Schema system](schema-system.md).
+
+## Make one edit
+
+Open `templates/starter/sections/hero/fixtures.ts` and change the `headline`
+value under `base`:
+
+```diff
+- headline: "101 Queensway, Jamaica Plain, MA 02130",
++ headline: "12 Elm Street, Jamaica Plain, MA 02130",
+```
+
+Save it. If `npm run dev` is running, any open preview of the `hero` section
+reloads with the new headline; re-running the `/api/inspect` call above also
+shows the new value.
+
+## Check it
+
+```bash
+npm run check
+```
+
+```
+✓ starter
+check passed
+```
+
+A green `check` is the acceptance gate — see [Check](check.md) for what its
+six stages verify and what a failure looks like.
+
+## The author loop
+
+Every section, and every change to one, runs the same three-step loop:
+
+1. **Edit** a section's files.
+2. **Preview** the result — `npm run dev` in a browser, or `/api/inspect` from
+   a terminal.
+3. **Check** it — `npm run check` — until it's green.
+
+Every recipe in this corpus ends by running this loop.

package/docs/recipes/INDEX.md

@@ -0,0 +1,27 @@
+---
+purpose: Task router — how do I… → the recipe.
+status: living
+related: []
+updated: 2026-07-16
+---
+# Recipes
+
+Every recipe is a **delta from the starter's `hero` section** — never a
+from-scratch file — ending in the same [author loop](../quickstart.md#the-author-loop)
+as everything else in this corpus: edit, preview, check. Find your task below and
+copy the shapes from its recipe, not from memory.
+
+| How do I… | Recipe |
+|---|---|
+| add an image slot the editor can crop | [`image-slot-crop.md`](image-slot-crop.md) |
+| fill a slot from a property fact without AI | [`bind-property-fact.md`](bind-property-fact.md) |
+| give the user a closed set of choices | [`select-slot.md`](select-slot.md) |
+| add a repeating list the user edits per item (unit table, cards, gallery) | [`collection-slot.md`](collection-slot.md) |
+| have AI write a slot's content | [`fill-spec-decision.md`](fill-spec-decision.md) |
+| preview a section's structural edge cases / states | [`fixture-states.md`](fixture-states.md) |
+| make part of a section interactive (an island) | [`interactive-island.md`](interactive-island.md) |
+| organize a section's files beyond the four reserved | [`organize-section-folder.md`](organize-section-folder.md) |
+| ship a static asset (image/svg/font) with a section | [`static-asset.md`](static-asset.md) |
+| use a third-party npm package in a section | [`third-party-package.md`](third-party-package.md) |
+| add another template to the workspace | [`second-template.md`](second-template.md) |
+| package a template for submission | [`prepare-submission.md`](prepare-submission.md) |

package/docs/recipes/bind-property-fact.md

@@ -0,0 +1,58 @@
+---
+purpose: Fill a slot from a known property fact, no AI.
+status: living
+related: [../vocabulary.md, ../schema-system.md, ../rules/schema-invalid.md]
+updated: 2026-07-15
+---
+# Bind a slot to a property fact
+
+## Goal
+
+Fill a slot from a known property fact, no AI.
+
+## The delta
+
+Give the slot a `source: direct("<field>")` instead of a `produced_by` — the
+same pattern the starter's `headline` already uses
+(`source: direct("address")`). Model it on an AI-produced slot you want to
+make fact-bound instead: swap its `produced_by` for `source`, and drop the
+matching decision from `fill-spec.ts`.
+
+```ts
+// schema.ts — was produced_by: "blurb_text"
+blurb: {
+  type: "text",
+  size: "long",
+  editable_by_user: true,
+  required: true,
+  source: direct("lot_size"),
+  display_name: "Blurb",
+},
+```
+
+Then delete the now-unused `blurb_text` decision from `fill-spec.ts`'s
+`decisions` array — a `direct()`-bound slot needs none; the fact is baked in
+at fill time, and the [`schema-invalid`](../rules/schema-invalid.md) check
+rejects a slot that declares both `source` and `produced_by`.
+
+The same pattern works for any slot type — pick a field whose runtime shape
+matches. For a `number` slot, `source: direct("beds")`; for `text`,
+`source: direct("address")` or any other text-shaped field in
+[the closed vocabulary](../vocabulary.md#direct-sources).
+
+## 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#direct-sources) — every `direct()` field,
+  grouped by what it resolves against.
+- [The schema system](../schema-system.md#binding-a-slot-to-a-property-fact) — the
+  `direct()`/`derived()` contract and why a bad name is a compile error.
+- [`schema-invalid`](../rules/schema-invalid.md) — fires if a slot declares both
+  `source` and `produced_by`, or neither.