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 for the mental model and Schema system for the four files in depth.

Create your workspace

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 for what a workspace, template, and section are.

See it render

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 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:

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

Make one edit

Open templates/starter/sections/hero/fixtures.ts and change the headline value under base:

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

npm run check

✓ starter
check passed

A green check is the acceptance gate — see Check 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.