@homepages/template-kit 0.3.0 → 0.4.0

package/docs/rules/bundle-binary-asset.md

@@ -1,44 +1,43 @@
 ---
 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]
-updated: 2026-07-14
+related: [INDEX.md, bundle-incomplete.md, ../primitives.md, ../assets.md]
+updated: 2026-07-16
 ---
 # template-kit/bundle-binary-asset
 
-> A section folder holds code, not static files. A binary asset dropped into it has no
-> build meaning yet.
+> 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
 
-No file inside a section folder may be a binary asset: an image, a font, a video, an
-audio file, an archive, a document. The check looks two ways:
+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, catching an
-  asset type the extension list doesn't name.
-
-This is scoped to the section folder itself (`Renderer.tsx`, `schema.ts`, `components/`,
-everything under it) — not to the photos a listing supplies. Those arrive at runtime
-through a slot's `src`, never as a file that ships inside your section.
+- **By content** — any other file whose first bytes contain a NUL byte.
 
 ## Reason
 
-A section folder is published as source: its content hash covers every file in it, and
-the platform has no pipeline yet to fingerprint, optimize, or serve a binary file that
-lives alongside your code. A `.png` committed today has no URL tomorrow — there is
-nowhere for it to be requested from.
-
-Everything a section needs to draw — an icon, a divider graphic, a background pattern —
-is expressible as markup instead: an inline `<svg>`, or a shape built from CSS. That
-markup is text, ships with the rest of your JSX, and needs no pipeline at all.
+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
 
-Delete the binary file and inline its content as SVG markup — either directly in the
-JSX that used it, or as its own small component if more than one place needs it.
+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
 
@@ -49,32 +48,25 @@ sections/hero/
   fill-spec.ts
   fixtures.ts
   assets/
-    arrow.svg          ← binary asset in the bundle
+    crest.svg          ← nothing imports or url()-references this file
 ```
 
+### After
+
 ```tsx
 // sections/hero/Renderer.tsx
-import arrowUrl from "./assets/arrow.svg";
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
 
-export function Renderer() {
-  return <img src={arrowUrl} alt="" className="h-4 w-4" />;
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
 }
 ```
 
-### After
-
-```text
-sections/hero/
-  Renderer.tsx
-  schema.ts
-  fill-spec.ts
-  fixtures.ts
-  components/
-    ScrollArrow.tsx     ← markup, not a binary file
-```
+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
-// 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">
@@ -84,19 +76,8 @@ export function ScrollArrow() {
 }
 ```
 
-```tsx
-// sections/hero/Renderer.tsx
-import { ScrollArrow } from "./components/ScrollArrow.js";
-
-export function Renderer() {
-  return <ScrollArrow />;
-}
-```
-
 ## See also
 
-- [`bundle-incomplete`](bundle-incomplete.md) — the other rule on the folder's contents,
-  checked by the same pass over the section anatomy.
-- [Contract primitives](../primitives.md) — `Image`, the primitive that owns every photo
-  a listing supplies. It reads a `src` at runtime; it is not a way to ship a binary file
-  inside your section.
+- [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/no-bare-css-import.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-bare-css-import 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/no-bare-css-import
 
@@ -59,11 +59,11 @@ in the whole kit: the only signal is that the styles are not there.
 Delete the `@import`.
 
 **A package's stylesheet is reached from the code that needs it**, not from CSS. Write
-`import "swiper/css";` in the component, island, or enhancer that renders the thing — the
-CSS build bundles your `Renderer.tsx` and every marked enhancer, transitively, precisely to
-harvest those imports, and it compiles what they pull in into **this section's cascade
-layer**. Package CSS goes in first and your own hand-CSS second, so at equal specificity
-your rules win.
+`import "swiper/css";` in the component or island that renders the thing — the CSS build
+bundles your `Renderer.tsx` and everything it imports, transitively, precisely to harvest
+those imports, and it compiles what they pull in into **this section's cascade layer**.
+Package CSS goes in first and your own hand-CSS second, so at equal specificity your rules
+win.
 
 Two things authors get wrong immediately after:
 
@@ -79,7 +79,7 @@ Two things authors get wrong immediately after:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: styles the slide DOM the Swiper enhancer builds at runtime. */
+/* css-reason: styles the slide DOM the Swiper carousel builds at runtime. */
 @import "swiper/css";              /* template-kit/no-bare-css-import — silently dropped */
 
 .tr-gallery .swiper-pagination-bullet-active {
@@ -95,7 +95,7 @@ The `@import` is gone from the stylesheet:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: overrides the Swiper pagination DOM the enhancer builds at runtime —
+/* css-reason: overrides the Swiper pagination DOM the carousel builds at runtime —
    those nodes carry the library's own classes, which Tailwind's scanner never sees. */
 .tr-gallery .swiper-pagination-bullet-active {
   background: var(--tr-color-primary);

package/docs/rules/no-css-import-from-render-path.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-css-import-from-render-path 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/no-css-import-from-render-path
 
@@ -31,8 +31,8 @@ server-rendered inline before it is hydrated.
 ## Reason
 
 The section's CSS build works by **bundling the render path itself** — `Renderer.tsx` and
-any enhancer that carries `export const enhancer` — and harvesting the CSS its imports
-pull in. A bare specifier resolves into `node_modules`, which is exactly what that build
+every module it imports, components and islands alike — and harvesting the CSS those
+imports pull in. A bare specifier resolves into `node_modules`, which is exactly what that build
 looks for: `import "swiper/css";` in `Renderer.tsx` is not a mistake, it is the mechanism.
 
 A **local** stylesheet is a different problem. Every `.css` file that already lives in the
@@ -47,11 +47,10 @@ Delete the import. A local stylesheet already ships — the build picks up every
 in the section folder on its own; importing it again only makes it double-emit.
 
 A package's stylesheet is different: import it **by its bare specifier**, from the module
-that needs it. The build bundles `Renderer.tsx` and every marked enhancer's import graph
-**transitively**, so a bare specifier is equally legal in the Renderer itself, in a marked
-enhancer, or in any component either one imports — not only at the top of the tree. That
-import is how the build finds the stylesheet and routes it into the section's cascade
-layer.
+that needs it. The build bundles `Renderer.tsx`'s import graph **transitively**, so a bare
+specifier is equally legal in the Renderer itself or in any component or island it
+imports — not only at the top of the tree. That import is how the build finds the
+stylesheet and routes it into the section's cascade layer.
 
 ### Before
 

package/docs/rules/size-assets.md

@@ -0,0 +1,88 @@
+---
+purpose: The template-kit/size-assets authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-section-css.md, ../theme-and-css.md]
+updated: 2026-07-15
+---
+# template-kit/size-assets
+
+> A section's static assets — the svg, images, and fonts it imports or `url()`-references —
+> must total **≤ 250 KB raw.** Raw, not gzip: images and fonts are already compressed
+> formats, so gzipping them again buys nothing.
+
+## Rule
+
+A section's static assets are budgeted by **total raw bytes, 250 KB or less**. What is
+measured is every asset the published section actually ships:
+
+- an svg, image, or font `import`ed directly in `Renderer.tsx` (or an island), and
+- an svg, image, or font `url()`-referenced from the section's own CSS or from a
+  package stylesheet its module graph pulls in — including a webfont `@font-face`s.
+
+The same asset referenced twice (from both a stylesheet and a component, say) counts
+once, not twice.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
+
+## Reason
+
+An svg icon or a product photo a section imports, and a webfont a package's stylesheet
+pulls in, both ship to the same page load as the section's own code and CSS — they are
+not free just because they never appear in a byte-budget an author is used to watching.
+
+Fonts are the sharpest case. A `url()`-referenced webfont used to inline as part of the
+compiled stylesheet, which made a large font look like a CSS problem: trimming your own
+rules never fixed it, because the bytes were never your CSS to begin with. This rule
+separates that weight into its own budget — a font, an icon, or an image is measured as
+what it is, and the stylesheet budget ([`size-section-css`](size-section-css.md)) is left
+to measure only what it actually contains.
+
+## Fix
+
+Two moves, in order of how often they work:
+
+1. **Shrink or subset the asset.** A full variable font family, shipped for three
+   weights actually used, is the usual cause — subset it to the characters and weights
+   the section renders. An unoptimized PNG is the other common case — recompress it, or
+   switch to a format built for the content (`webp`/`avif` for photos, `svg` for icons).
+2. **Drop assets the section does not use.** A copied-in icon set or a leftover preview
+   image that never renders still ships its bytes — delete what the section does not
+   reference.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+import "brandfont/css"; // ← ships the package's full variable font family
+
+export default function Renderer() {
+  return <h1 style={{ fontFamily: "BrandFont" }}>Welcome home</h1>;
+}
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+import heroIcon from "./assets/hero-icon.svg"; // ← a small, single-purpose asset
+
+export default function Renderer() {
+  // Uses a font the template's theme already declares (`--tr-font-<name>`),
+  // which costs nothing because it is already loaded — no package font import.
+  return (
+    <h1 className="tr-font-display">
+      <img src={heroIcon} alt="" /> Welcome home
+    </h1>
+  );
+}
+```
+
+## See also
+
+- [`size-section-css`](size-section-css.md) — the stylesheet budget this rule was split
+  out of; a `url()`-referenced font now counts here, not there.
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same idea applied to the
+  section's JavaScript.
+- [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads,
+  which cost you nothing to reuse.

package/docs/rules/size-island-bundle.md

@@ -0,0 +1,123 @@
+---
+purpose: The template-kit/size-island-bundle authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-renderer-bundle.md, size-section-css.md, server-vs-client.md]
+updated: 2026-07-15
+---
+# template-kit/size-island-bundle
+
+> Each island's browser bundle must be **≤ 50 KB gzip**. The budget is not
+> author-overridable, and it applies per island, not per section.
+
+## Rule
+
+An island — a component whose file opens with the `"use client"` directive (see
+[Server vs client](server-vs-client.md)) — ships to the browser as its own bundle,
+separate from the section's server-rendered HTML. Each island is bundled with esbuild
+and minified, with **React treated as external** (the page's runtime chunk supplies it
+once, shared by every island on the page, and is not counted against any one of them).
+The gzipped result must be **50 KB or less**.
+
+A section can have more than one island. The budget is checked **per island**: a section
+with three islands each at 40 KB passes; a section with one island at 60 KB fails, even
+though the same section's other files are small.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A template workspace cannot raise it, and there is no per-island
+exemption.
+
+## Reason
+
+An island is the part of the page that has to work on a phone before the visitor does
+anything — a carousel, a filter, a form. Every one of its bytes is downloaded, parsed,
+and executed on the client, on top of whatever the page's shared runtime already costs.
+Unlike the section's server-rendered markup, which the browser only has to paint, an
+island's code has to run.
+
+The number is set to be generous, so it does not fight ordinary authoring — a real
+interactive widget fits comfortably inside it. You hit the budget when something
+**runaway** gets pulled into the client bundle:
+
+- **a whole UI or icon library imported for one component**, which drags every export
+  into the bundle so the island can use a handful of them;
+- **a heavy dependency that belongs on the server**, ported into the island because it
+  was easiest to reach for where the code was being written, not because the browser
+  needs it.
+
+That is the shape of essentially every violation: not an island that grew, but a single
+import that was more expensive than it looked.
+
+## Fix
+
+Find the import that is not paying for itself, or narrow what ships to the browser at
+all.
+
+- **Import named symbols, never a namespace.** `import { ArrowRight } from "…"` is
+  tree-shakeable; `import * as Icons from "…"` is not — a namespace object has to contain
+  everything, so nothing can be dropped.
+- **Prefer the package's narrow entry** if it offers one, instead of its default
+  "everything" bundle.
+- **Move what doesn't need to be interactive out of the island.** If only a small part of
+  a component actually needs client-side behavior — an expand/collapse toggle inside an
+  otherwise static block — split the interactive part into its own small island and leave
+  the rest server-rendered. Server-rendered markup costs nothing against this budget.
+- **Hand-write the residue.** If you use one function out of a large utility package, copy
+  the function instead of importing the package for it.
+
+### Before
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import * as Icons from "lucide-react"; // ← the whole set: every icon, in this island's bundle
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <Icons.ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <Icons.ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react"; // ← two icons, and the bundler can drop the rest
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+## See also
+
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
+  server-rendered bundle.
+- [`size-section-css`](size-section-css.md) — the same budget on the section's stylesheet.
+- [Server vs client](server-vs-client.md) — what makes a file an island in the first
+  place.

package/docs/rules/size-section-css.md

@@ -1,8 +1,8 @@
 ---
 purpose: The template-kit/size-section-css authoring rule — what it enforces, why, and how to fix it.
 status: living
-related: [INDEX.md, size-renderer-bundle.md, ../theme-and-css.md]
-updated: 2026-07-14
+related: [INDEX.md, size-renderer-bundle.md, size-assets.md, ../theme-and-css.md]
+updated: 2026-07-15
 ---
 # template-kit/size-section-css
 
@@ -16,7 +16,7 @@ everything that lands in the layer:
 
 - the section's hand-written CSS, and
 - **every package stylesheet its module graph imports** — the `import "swiper/css"` in a
-  component, an island, or a marked enhancer.
+  component or an island.
 
 The budget is **visible in `template-kit check`'s configuration and is not
 author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
@@ -29,14 +29,15 @@ CSS blocks the first paint.
 
 "Including package CSS" is not a technicality; it is the failure this rule exists to catch.
 Your own stylesheet is almost never the problem — it is a few kilobytes of overrides. The
-package's is. And the reason it is invisible to you is the mechanism: a package stylesheet's
-`url()` references — its icon sprites, its webfont — are **inlined as `data:` URIs** into the
-compiled stylesheet. A 300 KB font file arrives in your published CSS without you ever
-having seen a 300 KB file. Nothing in your source looks large. Nothing in the package's
-`dist` listing looks alarming. The compiled layer is 400 KB.
+package's is. A one-line `import "some-ui/dist.css"` can drag in thousands of rules for
+components you never render — resets, theme variants, every widget's styles — and they all
+land in your compiled layer. Nothing in your source looks large; the compiled layer is
+400 KB.
 
 So the number this check reports is frequently the first time anyone finds out what a
-one-line CSS import actually cost.
+one-line CSS import actually cost. (What this budget does **not** count is asset bytes: a
+`url()`-referenced webfont or icon file resolves to a cached URL and is weighed separately —
+see [`size-assets`](size-assets.md).)
 
 ## Fix
 
@@ -45,10 +46,11 @@ Three moves, in order of how often they work:
 1. **Import the slimmest entry the package offers.** Most CSS-shipping packages have a core
    stylesheet plus opt-in modules, *and* a fat "everything" bundle that is the one you get
    from copying the quickstart. Take the core, plus only the modules you use.
-2. **Cut the webfont.** If the package's stylesheet drags in a font for its icons, and you
-   are using three of those icons, replace them with inline SVG — or with a family the
-   template's theme already declares in `fonts` (`--tr-font-<name>`), which costs nothing
-   because it is already loaded.
+2. **Drop the icon font.** If the package's stylesheet declares an icon font and you use
+   three of its glyphs, replace them with inline SVG — or with a family the template's theme
+   already declares in `fonts` (`--tr-font-<name>`), which costs nothing because it is
+   already loaded. (The font *file* is weighed under [`size-assets`](size-assets.md), but its
+   `@font-face` rules and every `.icon-*` class still land in this layer.)
 3. **Drop the package and hand-write the residue.** If you use one component from a large
    widget library, its stylesheet is paying for components you never render.
 
@@ -83,12 +85,15 @@ export default function Carousel({ slides }: { slides: { id: string; url: string
 ```
 
 The arrows and dots that came from the bundle's icon font are drawn as inline SVG in the
-component instead, so nothing pulls a webfont into the layer.
+component instead, so the layer no longer carries that font's `@font-face` and icon-class
+rules (and the font file no longer counts against [`size-assets`](size-assets.md) either).
 
 ## See also
 
 - [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
   JavaScript.
+- [`size-assets`](size-assets.md) — the separate budget on the static asset *files*
+  (fonts, images) a stylesheet or component references.
 - [`no-bare-css-import`](no-bare-css-import.md) — why a package's stylesheet is imported from
   code and never `@import`ed from CSS.
 - [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads, which

package/docs/schema-system.md

@@ -1,8 +1,8 @@
 ---
 purpose: The section authoring contract — schema.ts, fill-spec.ts, fixtures.ts, and the closed source/transform vocabulary.
 status: living
-related: [primitives.md, theme-and-css.md]
-updated: 2026-07-14
+related: [primitives.md, theme-and-css.md, vocabulary.md]
+updated: 2026-07-16
 ---
 # The schema system
 
@@ -32,22 +32,17 @@ from. Without it, `SectionProps` cannot tell a required slot from an optional on
 and your renderer props collapse to a useless widened shape.
 
 ```ts
-import { direct, type FrameConfig, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
-
-export const HERO_FRAME = {
-  breakpoint: 425,
-  desktop: { aspect: 5 / 3 },
-} as const satisfies FrameConfig;
+import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
 
 export const schema = {
   meta: { displayName: "Hero" },
   slots: {
-    headline: { type: "text", size: "medium", required: true, produced_by: "headline_text" },
-    listing_status: { type: "select", required: false, source: direct("listing_intent") },
-    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", frame: HERO_FRAME },
+    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", crop: { mode: "locked", aspect: 16 / 9 } },
+    headline: { type: "text", size: "medium", required: true, source: direct("address") },
+    blurb: { type: "text", size: "long", required: true, produced_by: "blurb_text" },
   },
   options: {
-    align: { type: "enum", values: ["left", "center"], default: "left" },
+    align: { type: "enum", values: ["left", "center"], default: "center" },
   },
 } as const satisfies SectionSchemaShape;
 
@@ -65,14 +60,20 @@ binds it to a computed transform. Both take names from a **closed vocabulary**,
 a typo is a compile error at the call site — not a runtime surprise:
 
 ```ts
-source: direct("listing_intent")   // ✅
-source: direct("listing_intentt")  // ✗ compile error: not a SOURCE_FIELDS key
+source: direct("address")   // ✅
+source: direct("addresss")  // ✗ compile error: not a SOURCE_FIELDS key
 ```
 
-The vocabulary is the kit's, not yours. Read it off the exported tables —
-`SOURCE_FIELDS` (facts `direct()` accepts), `TRANSFORMS` (`derived()`), and
-`SLOT_TYPE_DESCRIPTORS` (the slot types) — or let your editor autocomplete it.
-Adding to it is a kit release, not a change you can make in a template.
+The vocabulary is the kit's, not yours. Adding to it is a kit release, not a
+change you can make in a template. See [the closed vocabulary](vocabulary.md)
+for the sets and when to pick each; your editor autocompletes the exact fields.
+
+A `select` slot binds the same way as any other type — here fact-bound rather
+than AI-produced, with `values` declaring the closed set the fact resolves to:
+
+```ts
+listing_status: { type: "select", required: false, source: direct("listing_intent"), values: ["for_sale", "for_rent"] },
+```
 
 ### Grouping slots into one editor card
 
@@ -104,7 +105,6 @@ import type { Props } from "./schema.js";
 
 export default function Hero({ slots, options, nav }: Props) {
   // headline is `string` — the schema says required: true
-  // listing_status is `string | null` — required: false
   // options.align is `"left" | "center"` — the enum's declared values
   return (
     <Section id={nav.selfAnchor}>
@@ -153,12 +153,12 @@ export const fillSpec = {
   decisions: [
     { id: "hero_image_assign", type: "image-assign", produces: ["hero_image"], tag_query: "category:exterior" },
     {
-      id: "headline_text",
+      id: "blurb_text",
       type: "text-block",
-      produces: ["headline"],
-      length_cap: 60,
-      structure: "single_sentence",
-      voice_prompt: "Confident premium-listing voice. Title Case.",
+      produces: ["blurb"],
+      length_cap: 400,
+      structure: "paragraph",
+      voice_prompt: "Warm, concrete paragraph a buyer would want to read.",
     },
   ],
 } as const satisfies FillSpecShape;
@@ -177,14 +177,14 @@ import type { FixtureModule } from "@homepages/template-kit";
 const fixtures: FixtureModule = {
   base: {
     slots: {
-      headline: "A mansard Victorian in the heart of Jamaica Plain",
-      listing_status: "for_sale",
+      headline: "101 Queensway, Jamaica Plain, MA 02130",
       hero_image: { photo_id: "p1", url: "https://example.com/a.jpg", alt: "Front elevation" },
+      blurb: "A bright corner home moments from the Emerald Necklace.",
     },
-    options: { align: "left" },
+    options: { align: "center" },
   },
   states: {
-    centered: { label: "Centered", options: { align: "center" } },
+    left: { label: "Left-aligned", options: { align: "left" } },
   },
 };