@homepages/create-workspace 0.8.0

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// `npm create @homepages/workspace <name>` — stamp a workspace container: shared
+// root context + one working starter template, then install and git-init.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { stampTree } from "./stamp.js";
+const ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "scaffold");
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+export async function scaffoldWorkspace(name, targetDir, opts) {
+    await mkdir(targetDir, { recursive: true });
+    await stampTree(join(ASSETS, "workspace"), targetDir, {
+        WORKSPACE_NAME: name,
+        KIT_VERSION: opts.kitVersion,
+    });
+    await stampTree(join(ASSETS, "template"), join(targetDir, "templates", "starter"), {
+        TEMPLATE_KEY: "starter",
+        TEMPLATE_NAME: "Starter",
+    });
+    if (opts.git !== false)
+        execFileSync("git", ["init", "-q"], { cwd: targetDir, stdio: "inherit" });
+    if (opts.install !== false)
+        execFileSync("npm", ["install"], { cwd: targetDir, stdio: "inherit" });
+}
+/**
+ * The kit version to caret-pin: this scaffolder is published version-synced
+ * with the kit, so its own `version` IS the kit version. Read at runtime
+ * (rather than a static JSON import) because `../package.json` sits outside
+ * `rootDir: "src"` and trips TS6059 under a static import.
+ */
+function kitVersion() {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+async function promptName() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question("Workspace name: ")).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function main() {
+    const arg = process.argv[2];
+    const name = arg ?? (await promptName());
+    if (!NAME_RE.test(name)) {
+        process.stderr.write(`create-workspace: name must be kebab-case (${NAME_RE.source}). Got: ${name}\n`);
+        return 1;
+    }
+    const targetDir = resolve(process.cwd(), name);
+    if (existsSync(targetDir)) {
+        process.stderr.write(`create-workspace: ${name}/ already exists.\n`);
+        return 1;
+    }
+    await scaffoldWorkspace(name, targetDir, { kitVersion: kitVersion() });
+    process.stdout.write(`\nCreated ${name}/\n\n` +
+        `  cd ${name}\n` +
+        `  npm run dev        # preview the starter (the island hydrates)\n` +
+        `  npm run check      # typecheck + lint + validate\n` +
+        `  npx template-kit new <name>   # add another template\n\n` +
+        `Read templates/starter/sections/hero/ — it teaches the whole contract.\n`);
+    return 0;
+}
+// Only run main() when invoked as the bin, not when imported by a test.
+//
+// realpath argv[1] before comparing: npm installs a bin as a SYMLINK in
+// node_modules/.bin/, so `npm create @homepages/workspace` invokes the link while
+// import.meta.url is the real dist/index.js. Comparing them unresolved makes this
+// guard silently false on the only path that matters — the command exits 0 having
+// done nothing. src/bin-entry.test.ts runs the bin through a symlink to hold this.
+const invokedAs = process.argv[1];
+if (invokedAs && fileURLToPath(import.meta.url) === realpathSync(resolve(invokedAs))) {
+    process.exit(await main());
+}

package/dist/stamp.js

@@ -0,0 +1,49 @@
+// Twin of packages/template-kit/src/cli/new/emit.ts — keep behavior identical.
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const RENAME = {
+    "_gitignore": ".gitignore",
+    "_package.json": "package.json",
+    "_manifest.json": "manifest.json",
+    "_Renderer.tsx": "Renderer.tsx",
+    "_schema.ts": "schema.ts",
+    "_fill-spec.ts": "fill-spec.ts",
+    "_fixtures.ts": "fixtures.ts",
+};
+function substitute(body, tokens) {
+    return body.replace(/\{\{(\w+)\}\}/g, (_m, key) => {
+        const value = tokens[key];
+        if (value === undefined)
+            throw new Error(`scaffold: no value for token {{${key}}}`);
+        return value;
+    });
+}
+async function walk(dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walk(full)));
+        else
+            out.push(full);
+    }
+    return out;
+}
+/** Emit `srcDir` into `destDir`; returns dest-relative paths written. */
+export async function stampTree(srcDir, destDir, tokens) {
+    const files = await walk(srcDir);
+    const written = [];
+    for (const file of files) {
+        const rel = relative(srcDir, file);
+        const parts = rel.split("/");
+        const base = parts[parts.length - 1];
+        parts[parts.length - 1] = RENAME[base] ?? base;
+        const destRel = parts.join("/");
+        const destPath = join(destDir, destRel);
+        await mkdir(join(destPath, ".."), { recursive: true });
+        const body = substitute(await readFile(file, "utf8"), tokens);
+        await writeFile(destPath, body, "utf8");
+        written.push(destRel);
+    }
+    return written;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@homepages/create-workspace",
+  "version": "0.8.0",
+  "description": "Scaffold a HomePages template workspace.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "create-workspace": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "scaffold"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "check": "npm run typecheck && npm run build && npm run test"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/scaffold/section/_Renderer.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema";
+
+// {{SECTION_DISPLAY}} — a pure, server-rendered function of its props. Wrap
+// every editable slot in <Slot id="…"> so the editor can resolve clicks. For
+// interactivity, add a "use client" island file beside this one.
+export default function {{SECTION_PASCAL}}Renderer({ slots, nav }: Props): ReactNode {
+  return (
+    <Section id={nav.selfAnchor} className="bg-background text-ink">
+      <div className="mx-auto max-w-3xl px-6 py-12">
+        <Slot id="headline" textLeaf>
+          <h2 className="text-2xl font-semibold">{slots.headline}</h2>
+        </Slot>
+      </div>
+    </Section>
+  );
+}

package/scaffold/section/_fill-spec.ts

@@ -0,0 +1,18 @@
+import type { FillSpecShape } from "@homepages/template-kit";
+
+// Decision ids must match the `produced_by` references in schema.ts.
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    {
+      id: "headline_text",
+      type: "text-block",
+      produces: ["headline"],
+      length_cap: 80,
+      structure: "single_sentence",
+      perspective: "third",
+      voice_prompt: "Write a short, confident heading for this section.",
+      content_prompt: "Anchor the section's purpose in one sentence.",
+    },
+  ],
+} as const satisfies FillSpecShape;

package/scaffold/section/_fixtures.ts

@@ -0,0 +1,13 @@
+import type { FixtureModule } from "@homepages/template-kit";
+
+// Base content only. Nullability coverage is derived from schema.ts. Add a
+// `states` entry for a designed content-length or cardinality branch.
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: "A typical headline that reads well in a short line",
+    },
+  },
+};
+
+export default fixtures;

package/scaffold/section/_schema.ts

@@ -0,0 +1,24 @@
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+// Replace the slots/options with the real shape this section needs. Every
+// editable slot declares either a `source` (baked from the property graph via
+// `direct(...)`/`derived(...)`) or a `produced_by` naming a decision in
+// fill-spec.ts.
+export const schema = {
+  meta: {
+    displayName: "{{SECTION_DISPLAY}}",
+  },
+  slots: {
+    headline: {
+      type: "text",
+      size: "medium",
+      editable_by_user: true,
+      required: true,
+      produced_by: "headline_text",
+      display_name: "Headline",
+    },
+  },
+} as const satisfies SectionSchemaShape;
+
+// Renderer prop type — derived from `schema`; do not hand-write it.
+export type Props = SectionProps<typeof schema>;

package/scaffold/template/_manifest.json

@@ -0,0 +1,9 @@
+{
+  "key": "{{TEMPLATE_KEY}}",
+  "name": "{{TEMPLATE_NAME}}",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}

package/scaffold/template/sections/hero/ExpandableText.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { type ReactNode, useState } from "react";
+
+import type { IslandEditorOptions } from "@homepages/template-kit";
+
+// A "use client" island: interactive, hydrated in the browser as its own React
+// root. State, effects, and event handlers are fine here (they are NOT in a
+// Renderer). Its props cross the server→browser boundary as JSON, so they must
+// be strictly serializable — here, two strings and a number.
+export default function ExpandableText({
+  text,
+  collapsedChars,
+  moreLabel,
+}: {
+  text: string;
+  collapsedChars: number;
+  moreLabel: string;
+}): ReactNode {
+  const [open, setOpen] = useState(false);
+  const isLong = text.length > collapsedChars;
+  const shown = open || !isLong ? text : `${text.slice(0, collapsedChars).trimEnd()}…`;
+  return (
+    <p className="text-base leading-relaxed text-ink/80">
+      {shown}
+      {isLong ? (
+        <button
+          type="button"
+          data-testid="expand-toggle"
+          className="ml-2 font-medium text-accent underline"
+          onClick={() => setOpen((v) => !v)}
+        >
+          {open ? "Show less" : moreLabel}
+        </button>
+      ) : null}
+    </p>
+  );
+}
+
+// Optional: how this island behaves inside the editor canvas. Omit `editor`
+// entirely and the island renders as static markup in the editor (right for
+// most). Here we hydrate it live so the toggle works while editing.
+export const editor: IslandEditorOptions = {
+  live: true,
+};

package/scaffold/template/sections/hero/Renderer.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+
+import { Image, Section, Slot } from "@homepages/template-kit";
+
+import { Feature } from "./components/Feature";
+import ExpandableText from "./ExpandableText";
+import type { Props } from "./schema";
+
+// Hero — a pure server-rendered function of its props: no fetches, no globals,
+// no state. Every editable slot's outer DOM is wrapped in <Slot id="…"> (or a
+// primitive with slotId="…") so the editor can map a click back to the slot.
+// The one interactive part is the <ExpandableText> island.
+export default function HeroRenderer({ slots, options, nav }: Props): ReactNode {
+  const align = options.align === "left" ? "items-start text-left" : "items-center text-center";
+  return (
+    <Section id={nav.selfAnchor} className="bg-background text-ink">
+      <Image
+        slotId="hero_image"
+        src={slots.hero_image.url}
+        responsive={slots.hero_image.responsive}
+        alt={slots.hero_image.alt}
+        loading="eager"
+        className="w-full"
+      />
+      <div className={`mx-auto flex max-w-3xl flex-col gap-4 px-6 py-12 ${align}`}>
+        <Slot id="headline" textLeaf>
+          <h1 className="text-3xl font-semibold">{slots.headline}</h1>
+        </Slot>
+        <Slot id="blurb">
+          {/* The island receives JSON-serializable props only. */}
+          <ExpandableText text={slots.blurb} collapsedChars={140} moreLabel="Read more" />
+        </Slot>
+        <div className="mt-2 grid w-full grid-cols-2 gap-3">
+          <Feature label="Status" value="For sale" />
+          <Feature label="Type" value="Single-family" />
+        </div>
+      </div>
+    </Section>
+  );
+}

package/scaffold/template/sections/hero/components/Feature.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+
+// A nested server component. Proof that a section folder is free-form: only the
+// four contract files (Renderer/schema/fill-spec/fixtures) are reserved — a
+// components/ dir (or hooks/, utils/, any nesting) is yours to organize. This
+// renders as static HTML and ships zero JavaScript.
+export function Feature({ label, value }: { label: string; value: string }): ReactNode {
+  return (
+    <div className="rounded-lg border border-ink/10 p-4">
+      <div className="text-sm text-ink/60">{label}</div>
+      <div className="text-lg font-semibold text-ink">{value}</div>
+    </div>
+  );
+}

package/scaffold/template/sections/hero/fill-spec.ts

@@ -0,0 +1,29 @@
+import type { FillSpecShape } from "@homepages/template-kit";
+
+// The fill spec drives the AI fill. `headline` is a direct-source slot
+// (SOURCE_FIELDS "address") baked by the engine — it needs no decision here.
+// `hero_image` and `blurb` each name a decision whose id matches their
+// `produced_by` in schema.ts.
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    {
+      id: "hero_image_assign",
+      type: "image-assign",
+      produces: ["hero_image"],
+      tag_query: "category:exterior",
+      selection_prompt: "Pick a clear, well-lit exterior shot of the property.",
+    },
+    {
+      id: "blurb_text",
+      type: "text-block",
+      produces: ["blurb"],
+      length_cap: 400,
+      // `structure` enum is single_sentence | paragraph | bullet_list — not "single_paragraph".
+      structure: "paragraph",
+      perspective: "third",
+      voice_prompt: "Write a warm, concrete paragraph a buyer would want to read.",
+      content_prompt: "Describe what makes this home appealing in 2–4 sentences.",
+    },
+  ],
+} as const satisfies FillSpecShape;

package/scaffold/template/sections/hero/fixtures.ts

@@ -0,0 +1,41 @@
+import type { FixtureModule } from "@homepages/template-kit";
+import { luxuryMultiUnit, mkResponsive } from "@homepages/template-kit/fixtures";
+
+// Base content the section is designed for. Nullability coverage (each optional
+// slot rendered empty) is derived automatically from schema.ts — no fixture
+// needed for it. Add a `states` entry only for a designed scenario that
+// combines overrides at once (a content-length or option branch the section
+// renders differently).
+const heroImage = luxuryMultiUnit.photos[19]!; // exterior facade shot
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: luxuryMultiUnit.facts.address.display,
+      hero_image: {
+        photo_id: heroImage.id,
+        url: heroImage.url,
+        alt: heroImage.alt,
+        // Height set to a 16:9 ratio to match the slot's locked crop.
+        responsive: mkResponsive(heroImage.url, 2048, 1152),
+      },
+      blurb: "A 12-unit mansard Victorian in Jamaica Plain, moments from the Emerald Necklace.",
+    },
+    options: { align: "center" },
+  },
+  states: {
+    // Left-aligned layout branch (option override).
+    left: { options: { align: "left" } },
+    // Long-blurb branch: exercises the island's expand/collapse path.
+    "long-blurb": {
+      slots: {
+        blurb:
+          "A 12-unit mansard Victorian in Jamaica Plain, with a terrazzo lobby, an " +
+          "on-site gym, quartz kitchens throughout, and a top-floor penthouse with a " +
+          "private rooftop terrace and skyline views — all moments from the Emerald Necklace.",
+      },
+    },
+  },
+};
+
+export default fixtures;

package/scaffold/template/sections/hero/schema.ts

@@ -0,0 +1,60 @@
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+import { direct } from "@homepages/template-kit";
+
+// Hero — the starter section. It exercises the whole authoring contract in one
+// place so the first section you read teaches the shape:
+//
+//   Slots (editable content, declared here in the order the Renderer paints
+//   them — the sidebar-order check enforces that the two agree):
+//     hero_image  image, AI-assigned from the property's photos; `crop` tells
+//                 the editor's cropper to keep a locked 16:9 frame.
+//     headline    text,  fact-bound with direct("address") — seeded verbatim
+//                 from the property, no model call.
+//     blurb       text,  AI-written; the island below makes it expandable.
+//
+//   Options (behavioral, not editable content):
+//     align       where the text column sits — "center" (default) or "left".
+//
+// Every editable slot either declares a `source` (baked from the property
+// graph) or a `produced_by` that names a decision in fill-spec.ts.
+export const schema = {
+  meta: {
+    displayName: "Hero",
+  },
+  slots: {
+    hero_image: {
+      type: "image",
+      editable_by_user: true,
+      required: true,
+      produced_by: "hero_image_assign",
+      display_name: "Hero image",
+      // The editor's cropper keeps a locked 16:9 frame; the pill reads "16:9".
+      crop: { mode: "locked", aspect: 16 / 9, aspectLabel: "16:9" },
+    },
+    headline: {
+      type: "text",
+      size: "medium",
+      editable_by_user: true,
+      required: true,
+      source: direct("address"),
+      display_name: "Headline",
+    },
+    blurb: {
+      type: "text",
+      size: "long",
+      editable_by_user: true,
+      required: true,
+      produced_by: "blurb_text",
+      display_name: "Blurb",
+    },
+  },
+  options: {
+    // An enum option: its value type is the union of `values`. Read it in the
+    // Renderer as `options.align` — never hand-write the props type.
+    align: { type: "enum", values: ["center", "left"], default: "center" },
+  },
+} as const satisfies SectionSchemaShape;
+
+// Renderer prop type — derived from `schema`. Do not hand-write a separate type;
+// the props-from-schema lint rule enforces this.
+export type Props = SectionProps<typeof schema>;

package/scaffold/template/theme.css

@@ -0,0 +1,24 @@
+/* Generated by `template-kit theme` from theme.ts — do not edit.
+   Re-run `template-kit theme` after changing theme.ts. */
+@theme inline {
+  --color-accent: var(--tr-color-accent);
+  --color-background: var(--tr-color-background);
+  --color-ink: var(--tr-color-ink);
+  --font-body: var(--tr-font-body);
+  --text-base: var(--tr-text-base);
+}
+
+:root {
+  --tr-color-accent: #2f6df6;
+  --tr-color-background: #ffffff;
+  --tr-color-ink: #1a1d21;
+  --tr-font-body: system-ui, -apple-system, sans-serif;
+  --tr-text-base: 1rem;
+}
+
+body {
+  font-family: var(--tr-font-body);
+  color: var(--tr-color-ink);
+  background: var(--tr-color-background);
+  font-size: var(--tr-text-base);
+}

package/scaffold/template/theme.ts

@@ -0,0 +1,27 @@
+import type { TokenTheme } from "@homepages/template-kit";
+
+// A template's design tokens. `template-kit theme` compiles this to theme.css;
+// `template-kit dev` reads it directly. The `document` refs must name declared
+// tokens (color/background → colors, font → fonts, fontSize → type).
+export const theme: TokenTheme = {
+  colors: {
+    ink: "#1a1d21",
+    background: "#ffffff",
+    accent: "#2f6df6",
+  },
+  fonts: {
+    body: "system-ui, -apple-system, sans-serif",
+  },
+  type: {
+    base: "1rem",
+  },
+  radii: {},
+  shadows: {},
+  layout: {},
+  document: {
+    font: "body",
+    color: "ink",
+    background: "background",
+    fontSize: "base",
+  },
+};

package/scaffold/workspace/AGENTS.md

@@ -0,0 +1,45 @@
+<!-- Tool-agnostic mirror of CLAUDE.md — keep the two in sync. -->
+
+# {{WORKSPACE_NAME}} — agent guide
+
+You are authoring HomePages marketing-section templates in this workspace.
+
+## First 30 seconds
+
+- **Templates live in `templates/`.** Each is a plain folder — not an npm package.
+  Add one with `npx template-kit new <name>`; add a section with
+  `npx template-kit new-section <name>`.
+- **One kit, one version.** `@homepages/template-kit` is the only toolchain
+  dependency; every template shares it. Do not add per-template `package.json`,
+  `tsconfig`, or `eslint` files — there is exactly one of each, at this root.
+- **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
+  (`llms.txt` is the router). Read it before authoring; do not guess the contract.
+
+## The section contract (reserved files)
+
+A section is `templates/<t>/sections/<name>/` with four reserved files:
+`Renderer.tsx` (server component — pure, ships no JS), `schema.ts` (slots +
+options), `fill-spec.ts` (the AI fill spec), `fixtures.ts` (preview content).
+Plus template-level `manifest.json` (reserved) and `theme.ts` → `theme.css`
+(generated). Everything else in a section folder — `components/`, hooks, utils,
+islands — is yours to organize.
+
+## Server vs. client
+
+- A `Renderer.tsx` (and any component it imports without `"use client"`) is a
+  **server component**: a pure function of props. No state, effects, event
+  handlers, browser APIs, `Date.now()`, or randomness.
+- For interactivity, write a **`"use client"` island**: an ordinary React
+  component marked `"use client"`, default-exported, one per file. State,
+  effects, and handlers are fine. Its props from the Renderer must be
+  JSON-serializable (no functions/Dates/class instances).
+
+## Command loop
+
+- `npm run dev [-- <template>]` — live preview (islands hydrate)
+- `npm run check [-- <template>|-- --all]` — typecheck + lint + validate
+- `npm run pack -- <template>` — build the submission zip
+- `npx template-kit theme <template>` — regenerate `theme.css` after editing tokens
+
+Read the starter section (`templates/starter/sections/hero/`) — it is a working,
+annotated example of the whole contract.

package/scaffold/workspace/CLAUDE.md

@@ -0,0 +1,43 @@
+# {{WORKSPACE_NAME}} — agent guide
+
+You are authoring HomePages marketing-section templates in this workspace.
+
+## First 30 seconds
+
+- **Templates live in `templates/`.** Each is a plain folder — not an npm package.
+  Add one with `npx template-kit new <name>`; add a section with
+  `npx template-kit new-section <name>`.
+- **One kit, one version.** `@homepages/template-kit` is the only toolchain
+  dependency; every template shares it. Do not add per-template `package.json`,
+  `tsconfig`, or `eslint` files — there is exactly one of each, at this root.
+- **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
+  (`llms.txt` is the router). Read it before authoring; do not guess the contract.
+
+## The section contract (reserved files)
+
+A section is `templates/<t>/sections/<name>/` with four reserved files:
+`Renderer.tsx` (server component — pure, ships no JS), `schema.ts` (slots +
+options), `fill-spec.ts` (the AI fill spec), `fixtures.ts` (preview content).
+Plus template-level `manifest.json` (reserved) and `theme.ts` → `theme.css`
+(generated). Everything else in a section folder — `components/`, hooks, utils,
+islands — is yours to organize.
+
+## Server vs. client
+
+- A `Renderer.tsx` (and any component it imports without `"use client"`) is a
+  **server component**: a pure function of props. No state, effects, event
+  handlers, browser APIs, `Date.now()`, or randomness.
+- For interactivity, write a **`"use client"` island**: an ordinary React
+  component marked `"use client"`, default-exported, one per file. State,
+  effects, and handlers are fine. Its props from the Renderer must be
+  JSON-serializable (no functions/Dates/class instances).
+
+## Command loop
+
+- `npm run dev [-- <template>]` — live preview (islands hydrate)
+- `npm run check [-- <template>|-- --all]` — typecheck + lint + validate
+- `npm run pack -- <template>` — build the submission zip
+- `npx template-kit theme <template>` — regenerate `theme.css` after editing tokens
+
+Read the starter section (`templates/starter/sections/hero/`) — it is a working,
+annotated example of the whole contract.

package/scaffold/workspace/README.md

@@ -0,0 +1,40 @@
+# {{WORKSPACE_NAME}}
+
+A HomePages template workspace. Templates live in `templates/`. The kit toolchain
+is one dependency (`@homepages/template-kit`) shared by every template here.
+
+## Commands
+
+- `npm run dev` — preview a template (`npm run dev -- <template>` to pick one)
+- `npm run check` — typecheck, lint, and validate (`-- --all` for every template)
+- `npm run pack` — build a template's submission zip (`npm run pack -- <template>`)
+- `npx template-kit new <name>` — add another template
+- `npx template-kit new-section <name>` — add a section to a template
+- `npx template-kit theme <template>` — regenerate `theme.css` after editing `theme.ts`
+
+## Project structure
+
+Like a Next.js `app/`, `templates/` holds your authored units. A **section** is a
+folder of reserved "special files" plus anything else you want beside them.
+
+```
+templates/<template>/
+  manifest.json          # reserved — composition of section instances
+  theme.ts               # reserved — design tokens
+  theme.css              # generated from theme.ts (do not edit)
+  sections/<name>/
+    Renderer.tsx         # reserved — server component (ships no JS)
+    schema.ts            # reserved — slots + options
+    fill-spec.ts         # reserved — the AI fill spec
+    fixtures.ts          # reserved — preview content
+    components/          # yours — free-form colocated components
+    <Anything>.tsx       # yours — a "use client" island, utils, hooks, …
+```
+
+**Reserved** files are the contract `check` enforces. **Everything else is yours** —
+add colocated components, your own `docs/`, extra tooling, CI, more npm scripts.
+
+## Docs
+
+The full authoring guide ships inside the kit:
+`node_modules/@homepages/template-kit/guide/` (start at `INDEX.md` / `llms.txt`).

package/scaffold/workspace/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.tk-dev-cache/
+templates/**/theme.css.map
+*.log

package/scaffold/workspace/_package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{WORKSPACE_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "template-kit dev",
+    "check": "template-kit check",
+    "pack": "template-kit pack"
+  },
+  "dependencies": {
+    "@homepages/template-kit": "^{{KIT_VERSION}}",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "esbuild": "^0.28.1",
+    "eslint": "^9.39.4",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.5"
+  }
+}

package/scaffold/workspace/eslint.config.mjs

@@ -0,0 +1,3 @@
+import kit from "@homepages/template-kit/eslint";
+
+export default kit;

package/scaffold/workspace/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@homepages/template-kit/tsconfig",
+  "include": ["templates/**/*.ts", "templates/**/*.tsx"]
+}