@homepages/template-kit 0.3.0 → 0.4.0

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 //#endregion
 export { version };

package/dist/ssr.d.ts

@@ -0,0 +1,31 @@
+import { ResolvedFixture } from "./schema/fixture-schema.js";
+import "./schema/index.js";
+import { hasClientDirective } from "./eslint/is-client-file.js";
+import { isClientComponentFile, islandKey } from "./islands/detect.js";
+import { wrapClientModuleSource } from "./islands/wrap.js";
+import { findSectionIslands } from "./islands/discover.js";
+import { islandTransformEsbuildPlugin } from "./islands/esbuild-plugin.js";
+import { ComponentType } from "react";
+//#region src/ssr/index.d.ts
+type LoadedSection = {
+  Renderer: ComponentType<Record<string, unknown>>;
+  snapshotFixtures: ResolvedFixture[];
+  invariantFixtures: ResolvedFixture[];
+  schemaSlots: Record<string, {
+    type: string;
+    editable_by_user?: boolean;
+    required?: boolean;
+  }>;
+};
+type SectionModuleLoader = (dir: string, file: string) => Promise<unknown>;
+declare const nativeSectionLoader: SectionModuleLoader;
+/**
+ * Load a bundle's Renderer plus its resolved snapshot and invariant fixture
+ * sets from the bundle directory `dir`. `load` resolves each of the four
+ * contract files; it defaults to native dynamic import.
+ */
+declare function loadSectionBundle(dir: string, load?: SectionModuleLoader): Promise<LoadedSection>;
+/** Render a resolved fixture's props to static markup — the byte-for-byte page render. */
+declare function renderSectionHtml(renderer: ComponentType<Record<string, unknown>>, props: Record<string, unknown>): string;
+//#endregion
+export { LoadedSection, SectionModuleLoader, findSectionIslands, hasClientDirective, isClientComponentFile, islandKey, islandTransformEsbuildPlugin, loadSectionBundle, nativeSectionLoader, renderSectionHtml, wrapClientModuleSource };

package/dist/ssr.js

@@ -0,0 +1,46 @@
+import { FixtureModuleShape, buildFixtureSet, buildInvariantFixtures } from "./schema/fixture-schema.js";
+import { hasClientDirective } from "./eslint/is-client-file.js";
+import { isClientComponentFile, islandKey } from "./islands/detect.js";
+import { findSectionIslands } from "./islands/discover.js";
+import { wrapClientModuleSource } from "./islands/wrap.js";
+import { islandTransformEsbuildPlugin } from "./islands/esbuild-plugin.js";
+import { createElement } from "react";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { renderToStaticMarkup } from "react-dom/server";
+
+//#region src/ssr/index.ts
+const nativeSectionLoader = (dir, file) => import(pathToFileURL(join(dir, file)).href);
+/**
+* Load a bundle's Renderer plus its resolved snapshot and invariant fixture
+* sets from the bundle directory `dir`. `load` resolves each of the four
+* contract files; it defaults to native dynamic import.
+*/
+async function loadSectionBundle(dir, load = nativeSectionLoader) {
+	const rendererMod = await load(dir, "Renderer.tsx");
+	const fixturesMod = await load(dir, "fixtures.ts");
+	const schemaMod = await load(dir, "schema.ts");
+	const parsed = FixtureModuleShape.parse(fixturesMod.default);
+	const selfAnchor = schemaMod.schema.meta?.anchor ?? basename(dir);
+	return {
+		Renderer: rendererMod.default,
+		snapshotFixtures: buildFixtureSet({
+			schema: schemaMod.schema,
+			module: parsed,
+			selfAnchor
+		}),
+		invariantFixtures: buildInvariantFixtures({
+			schema: schemaMod.schema,
+			module: parsed,
+			selfAnchor
+		}),
+		schemaSlots: schemaMod.schema.slots
+	};
+}
+/** Render a resolved fixture's props to static markup — the byte-for-byte page render. */
+function renderSectionHtml(renderer, props) {
+	return renderToStaticMarkup(createElement(renderer, props));
+}
+
+//#endregion
+export { findSectionIslands, hasClientDirective, isClientComponentFile, islandKey, islandTransformEsbuildPlugin, loadSectionBundle, nativeSectionLoader, renderSectionHtml, wrapClientModuleSource };

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-15
+updated: 2026-07-16
 ---
 # template-kit docs — router
 
@@ -13,11 +13,19 @@ detail.
 
 | Doc | What it covers | Read when you're touching... |
 |---|---|---|
+| `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 links to | your first section, end to end |
+| `overview.md` | The one-page mental model: workspace → templates → sections, the four reserved files, and the server-vs-client mapping | orienting yourself before your first section |
 | `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 |
+| `vocabulary.md` | The closed authoring vocabulary — the 9 slot types, the `direct()` source fields, and the `derived()` transforms, with selection semantics | choosing which slot type / source / transform to use |
 | `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
+| `assets.md` | Static assets (svg/images/fonts): where they live (template level or a section folder, if referenced), referencing them from a section's CSS with `url()`/`@font-face` or importing them into a component, and the asset-vs-content-image distinction | shipping a logo, texture, icon, or brand font with a template |
 | `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: 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 |
+| `dev.md` | The `template-kit dev` CLI command: the local preview server, its home launcher and two tool cards (full template viewer, canvas mirror), the canvas mirror's selection overlay and per-slot edit panel, live reload, the content-override protocol, and the render/inspect/screenshot endpoints | previewing sections as you author them |
+| `new.md` | The `template-kit new` / `new-section` CLI commands: scaffolding a new template with a working starter section, or adding a bare section to an existing template | adding a template or a section to a workspace |
+| `pack.md` | The `template-kit pack` CLI command: builds a template's submission zip — template source, the workspace lockfile, and a stamped `pack-manifest.json`; refuses on a failing `check`, a missing lockfile, or a local-protocol dependency | packaging a template for submission |
 | `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 |
+| `recipes/` | Task recipes: how do I add a slot, bind a fact, add an island, package a template… Each is a minimal delta from the starter's `hero` section, ending in the author loop. `recipes/INDEX.md` routes them by task | doing something specific and not sure which file to touch |

package/docs/assets.md

@@ -0,0 +1,128 @@
+---
+purpose: Authoring static assets (svg, images, fonts) at the template level or in a section folder, and how they differ from content images.
+status: living
+related: [INDEX.md, primitives.md, theme-and-css.md, rules/size-assets.md, rules/bundle-binary-asset.md, rules/no-raw-element.md]
+updated: 2026-07-16
+---
+# Static assets
+
+A **static asset** is a file that is part of the template itself — a logo, a
+background texture, an icon, a brand webfont. It is authored once, is the
+**same for every deliverable** rendered from the template, and is referenced
+either from your CSS or from a component.
+
+## Where an asset lives
+
+An asset lives in one of two places:
+
+- **Template level** — e.g. `templates/<template>/assets/` — shared across every
+  section in the template. Reference it from a section's CSS with a `../../assets/…`
+  path (below).
+- **Section folder** — e.g. `sections/<section>/assets/` — local to that one
+  section. A section-folder asset must be *referenced*: imported in `Renderer.tsx`
+  or `url()`-referenced from one of the section's CSS files. An unreferenced binary
+  in a section folder is flagged by [`bundle-binary-asset`](rules/bundle-binary-asset.md) —
+  it has no build meaning and can never be served.
+
+Keep a logo, texture, or font that several sections share in the template-level
+folder; keep one that only a single section uses alongside that section.
+
+## Supported files
+
+```
+.svg .png .jpg .jpeg .gif .webp .avif .ico    images
+.woff .woff2 .ttf .otf .eot                   fonts
+.mp4 .webm .mov .mp3 .wav                      audio / video
+.pdf .zip                                      documents
+```
+
+## Referencing an asset — from CSS with `url()`
+
+Reference a template-level asset from a section's `styles.css` with `url()` —
+a `@font-face` `src` or a `background-image` resolves to the asset's built URL,
+identical in the `template-kit dev` preview, in the editor, and on the published
+page. Hand-CSS opens with a `css-reason:` comment (see
+[`css-reason`](rules/css-reason.md)):
+
+```css
+/* css-reason: brand webfont + crest watermark, both template assets */
+@font-face {
+  font-family: "Brand Serif";
+  src: url("../../assets/fonts/brand.woff2") format("woff2");
+  font-display: swap;
+}
+
+.hero-crest {
+  background-image: url("../../assets/crest.svg");
+}
+```
+
+The `../../assets/…` path climbs out of the section folder to the template-level
+`assets/` directory. A font you declare here is available to the whole section.
+If the family you want is one the template's theme already loads, reference that
+instead — see [Theme and CSS](theme-and-css.md); a font the page already has
+costs nothing to reuse.
+
+A **section-folder** asset is referenced the same way, with a section-relative
+path instead — no climbing out of the folder:
+
+```css
+/* css-reason: hero watermark, local to this section */
+.hero-crest {
+  background-image: url("./assets/crest.svg");
+}
+```
+
+## Referencing an asset — from a component with `import`
+
+An asset you render as an element — a logo, a crest — can be imported in the component and
+handed to the `Image` primitive, whose `src` accepts a URL string:
+
+```tsx
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
+
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
+}
+```
+
+The import resolves to the asset's built `/section-assets/…` URL — the same URL in the
+`dev` preview, the editor, and the published page. The kit ships an ambient TypeScript
+declaration that types every supported asset import as that URL string, so the import
+typechecks with no per-workspace setup. Use `alt=""` for a purely decorative
+asset. (Never a raw `<img>` — `Image` carries the responsive/fallback contract; a raw
+`<img>` is rejected by [`no-raw-element`](rules/no-raw-element.md).)
+
+## Which to use
+
+- CSS decoration (backgrounds, `@font-face`, masks) → `url()`.
+- An asset rendered as an element → `import` + `<Image>`.
+- A tiny glyph or icon → inline `<svg>` markup — no file at all.
+
+## Assets vs. content images
+
+These are two different things; keep them apart.
+
+- A **static asset** is authored template decoration — a logo, a texture, a brand
+  font. It ships inside the template, is the same on every deliverable, and you
+  reference it from your CSS with `url()` or by importing it into a component (above).
+- A **content image** is the property's own content — listing photos, floor
+  plans, a headshot. It differs on every deliverable and flows through the
+  section's slots via the [`Image`](primitives.md) descriptor, never as a file in
+  your template. Declare an image slot in your schema and render it with the
+  `Image` primitive; the platform supplies the actual photo per deliverable.
+
+Rule of thumb: if the picture is the same for every home the template ever
+renders, it's an asset — place it at the template level or in the section folder
+and reference it from CSS or a component `import`. If it changes with the
+property, it's content — give it a slot. Never hard-code a listing photo as an
+asset.
+
+## Keep them lean
+
+Every asset a section pulls in counts toward its asset budget — see
+[`size-assets`](rules/size-assets.md). Fonts and images are already compressed, so
+the budget is raw bytes: subset a webfont to the weights and characters you use,
+export images at the size they render, and drop anything a section doesn't
+actually reference.

package/docs/check.md

@@ -1,7 +1,7 @@
 ---
 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]
+related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md, dev.md]
 updated: 2026-07-15
 ---
 # template-kit check
@@ -62,8 +62,9 @@ one class of fix at a time:
    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.
+6. **size** — every section's renderer bundle, compiled stylesheet, and largest island
+   (browser) bundle, gzipped, against a fixed byte budget; and its static assets
+   (svg/images/fonts), budgeted by raw bytes since they are already compressed.
 
 **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:
@@ -119,3 +120,5 @@ submission.
   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`.
+- [Dev](dev.md) — the other workspace command: preview sections in a browser as you
+  author, before running `check` as the acceptance gate.

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).