@homepages/template-kit 0.0.1 → 0.2.0

package/dist/schema/section-schema.js

@@ -0,0 +1,72 @@
+import { CONTENT_SLOT_TYPES, REFERRAL_FIELDS, REF_SLOT_TYPES, SLOT_TYPES } from "../contracts/slot-catalog.js";
+import { ContentSlot, SlotDef, defaultForSlotType } from "./slot-types.js";
+import { derived, direct } from "./source.js";
+import { z } from "zod";
+
+//#region src/schema/section-schema.ts
+const optionAuthorityShape = {
+	user_editable: z.boolean().default(false),
+	template_overridable: z.boolean().default(false),
+	planner_settable: z.boolean().default(false),
+	affects_decisions: z.array(z.string()).default([]),
+	affects_slots: z.array(z.string()).default([])
+};
+const OptionEnum = z.object({
+	type: z.literal("enum"),
+	values: z.array(z.string()).min(1),
+	default: z.string(),
+	...optionAuthorityShape
+}).strict();
+const OptionBool = z.object({
+	type: z.literal("bool"),
+	default: z.boolean(),
+	...optionAuthorityShape
+}).strict();
+const OptionInt = z.object({
+	type: z.literal("int"),
+	default: z.number().int(),
+	min: z.number().int().optional(),
+	max: z.number().int().optional(),
+	...optionAuthorityShape
+}).strict();
+const OptionString = z.object({
+	type: z.literal("string"),
+	default: z.string(),
+	...optionAuthorityShape
+}).strict();
+const OptionJson = z.object({
+	type: z.literal("json"),
+	default: z.unknown(),
+	...optionAuthorityShape
+}).strict();
+const OptionDef = z.discriminatedUnion("type", [
+	OptionEnum,
+	OptionBool,
+	OptionInt,
+	OptionString,
+	OptionJson
+]);
+const SlotGroupDef = z.object({
+	id: z.string(),
+	label: z.string(),
+	members: z.array(z.union([z.string(), z.tuple([z.string(), z.string()])])).min(1)
+}).strict();
+const SectionMeta = z.object({
+	displayName: z.string().min(1),
+	anchor: z.string().min(1).optional(),
+	groups: z.array(SlotGroupDef).optional(),
+	variants: z.record(z.string().min(1), z.object({
+		cases: z.array(z.string().min(1)).min(1),
+		default: z.string().min(1),
+		select: z.custom((v) => typeof v === "function", { message: "variant axis `select` must be a function" })
+	}).strict()).optional()
+}).strict();
+const SectionSchema = z.object({
+	meta: SectionMeta,
+	slots: z.record(z.string(), SlotDef),
+	options: z.record(z.string(), OptionDef).default({}),
+	slot_order: z.array(z.string()).optional()
+}).strict();
+
+//#endregion
+export { CONTENT_SLOT_TYPES, ContentSlot, OptionDef, REFERRAL_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SectionMeta, SectionSchema, SlotDef, SlotGroupDef, defaultForSlotType, derived, direct };

package/dist/schema/slot-types.d.ts

@@ -0,0 +1,117 @@
+import { SlotType } from "../contracts/slot-catalog.js";
+import { z } from "zod";
+//#region src/schema/slot-types.d.ts
+type SlotTypeDescriptor = {
+  shape: z.ZodRawShape;
+  default: () => unknown;
+};
+declare const SLOT_TYPE_DESCRIPTORS: Record<SlotType, SlotTypeDescriptor>;
+declare const SlotDef: z.ZodType<Slot>;
+declare function slotDefTypes(): SlotType[];
+declare const ContentSlot: z.ZodObject<{
+  type: z.ZodEnum<["text", "number", "select", "image", "image_collection", "list", "object_list", "poi_list", "url"]>;
+  editable_by_user: z.ZodDefault<z.ZodBoolean>;
+  required: z.ZodDefault<z.ZodBoolean>;
+  produced_by: z.ZodOptional<z.ZodString>;
+  min: z.ZodOptional<z.ZodNumber>;
+  max: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+  type: "number" | "select" | "text" | "image" | "image_collection" | "list" | "object_list" | "poi_list" | "url";
+  required: boolean;
+  editable_by_user: boolean;
+  min?: number | undefined;
+  max?: number | undefined;
+  produced_by?: string | undefined;
+}, {
+  type: "number" | "select" | "text" | "image" | "image_collection" | "list" | "object_list" | "poi_list" | "url";
+  min?: number | undefined;
+  max?: number | undefined;
+  required?: boolean | undefined;
+  editable_by_user?: boolean | undefined;
+  produced_by?: string | undefined;
+}>;
+type SlotBase = {
+  required?: boolean;
+  editable_by_user?: boolean;
+  produced_by?: string;
+  source?: {
+    kind: string;
+    field?: string;
+    transform?: string;
+  };
+  display_name?: string;
+  placeholder?: string;
+  variant?: {
+    axis: string;
+    cases: readonly string[];
+  };
+};
+type TextSlot = SlotBase & {
+  type: "text";
+  size?: string;
+  format?: unknown;
+  length_cap?: number;
+};
+type NumberSlot = SlotBase & {
+  type: "number";
+  prefix?: string;
+  suffix?: string;
+  thousands_sep?: boolean;
+  decimals?: boolean;
+  max_digits?: number;
+  format?: unknown;
+};
+type SelectSlot = SlotBase & {
+  type: "select";
+  values?: string[];
+  options?: {
+    source: string;
+  };
+  catalog?: unknown;
+  creatable?: boolean;
+  fallback_icon?: string;
+  assigns?: Record<string, string>;
+};
+type ImageSlot = SlotBase & {
+  type: "image";
+  min?: number;
+  max?: number;
+  source_filter?: string;
+  recrop?: boolean;
+  crop?: unknown;
+  frame?: unknown;
+};
+type ImageCollectionSlot = SlotBase & {
+  type: "image_collection";
+  min?: number;
+  max?: number;
+  crop?: unknown;
+  frame?: unknown;
+};
+type ListSlot = SlotBase & {
+  type: "list";
+  min?: number;
+  max?: number;
+  element?: Slot;
+};
+type PoiListSlot = SlotBase & {
+  type: "poi_list";
+  min?: number;
+  max?: number;
+};
+type UrlSlot = SlotBase & {
+  type: "url";
+};
+type ObjectListSlot = SlotBase & {
+  type: "object_list";
+  min?: number;
+  max?: number;
+  item?: Record<string, Slot>;
+  source_title_field?: string;
+  item_order?: string[];
+  item_layout?: (string | [string, string])[];
+};
+type Slot = TextSlot | NumberSlot | SelectSlot | ImageSlot | ImageCollectionSlot | ListSlot | PoiListSlot | UrlSlot | ObjectListSlot;
+declare function defaultForSlotType(type: string): unknown;
+//#endregion
+export { ContentSlot, SLOT_TYPE_DESCRIPTORS, Slot, SlotDef, defaultForSlotType, slotDefTypes };

package/dist/schema/slot-types.js

@@ -0,0 +1,181 @@
+import { CONTENT_SLOT_TYPES, SLOT_TYPES } from "../contracts/slot-catalog.js";
+import { z } from "zod";
+
+//#region src/schema/slot-types.ts
+const slotHeadShape = {
+	editable_by_user: z.boolean().default(false),
+	required: z.boolean().default(false),
+	produced_by: z.string().optional()
+};
+const cropConfigShape = { crop: z.object({
+	mode: z.enum(["locked", "free"]),
+	aspect: z.number().positive().optional(),
+	aspectLabel: z.string().optional()
+}).strict().refine((c) => c.mode !== "locked" || c.aspect != null, { message: "locked crop requires an aspect" }).optional() };
+const frameConfigShape = { frame: z.object({
+	breakpoint: z.union([
+		z.literal(350),
+		z.literal(390),
+		z.literal(425),
+		z.literal(512),
+		z.literal(768),
+		z.literal(1024),
+		z.literal(1440),
+		z.literal(1920)
+	]),
+	desktop: z.object({
+		aspect: z.number().positive(),
+		nominal: z.boolean().optional()
+	}).strict(),
+	mobile: z.object({
+		aspect: z.number().positive(),
+		nominal: z.boolean().optional()
+	}).strict().optional()
+}).strict().optional() };
+const slotMetadataShape = {
+	display_name: z.string().optional(),
+	placeholder: z.string().optional(),
+	variant: z.object({
+		axis: z.string().min(1),
+		cases: z.array(z.string().min(1)).min(1)
+	}).strict().optional(),
+	source: z.discriminatedUnion("kind", [
+		z.object({ kind: z.literal("authored") }),
+		z.object({
+			kind: z.literal("direct"),
+			field: z.string()
+		}).strict(),
+		z.object({
+			kind: z.literal("derived"),
+			transform: z.string()
+		}).strict()
+	]).optional()
+};
+const FormatRef = z.union([z.string(), z.object({ fn: z.string() }).passthrough()]);
+const SLOT_TYPE_DESCRIPTORS = {
+	text: {
+		shape: {
+			size: z.enum([
+				"short",
+				"medium",
+				"long"
+			]).optional(),
+			format: FormatRef.optional(),
+			length_cap: z.number().int().positive().optional()
+		},
+		default: () => ""
+	},
+	number: {
+		shape: {
+			prefix: z.string().optional(),
+			suffix: z.string().optional(),
+			thousands_sep: z.boolean().optional(),
+			decimals: z.boolean().optional(),
+			max_digits: z.number().int().positive().optional(),
+			format: FormatRef.optional()
+		},
+		default: () => null
+	},
+	select: {
+		shape: {
+			values: z.array(z.string()).optional(),
+			options: z.object({ source: z.string() }).strict().optional(),
+			catalog: z.unknown().optional(),
+			creatable: z.boolean().optional(),
+			fallback_icon: z.string().optional(),
+			assigns: z.record(z.string(), z.string()).optional()
+		},
+		default: () => null
+	},
+	image: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional(),
+			source_filter: z.string().optional(),
+			recrop: z.boolean().optional(),
+			...cropConfigShape,
+			...frameConfigShape
+		},
+		default: () => ({
+			url: "",
+			alt: ""
+		})
+	},
+	image_collection: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional(),
+			...cropConfigShape,
+			...frameConfigShape
+		},
+		default: () => []
+	},
+	list: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional(),
+			element: z.lazy(() => SlotDef).optional()
+		},
+		default: () => []
+	},
+	poi_list: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional()
+		},
+		default: () => []
+	},
+	url: {
+		shape: {},
+		default: () => ""
+	},
+	object_list: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional(),
+			item: z.record(z.string(), z.lazy(() => SlotDef)).optional(),
+			source_title_field: z.string().optional(),
+			item_order: z.array(z.string()).optional(),
+			item_layout: z.array(z.union([z.string(), z.tuple([z.string(), z.string()])])).optional()
+		},
+		default: () => []
+	}
+};
+function slotMember(type, shape) {
+	return z.object({
+		type: z.literal(type),
+		...slotHeadShape,
+		...shape,
+		...slotMetadataShape
+	}).strict();
+}
+const SLOT_DEF_MEMBERS = [
+	slotMember("text", SLOT_TYPE_DESCRIPTORS.text.shape),
+	slotMember("number", SLOT_TYPE_DESCRIPTORS.number.shape),
+	slotMember("select", SLOT_TYPE_DESCRIPTORS.select.shape),
+	slotMember("image", SLOT_TYPE_DESCRIPTORS.image.shape),
+	slotMember("image_collection", SLOT_TYPE_DESCRIPTORS.image_collection.shape),
+	slotMember("list", SLOT_TYPE_DESCRIPTORS.list.shape),
+	slotMember("poi_list", SLOT_TYPE_DESCRIPTORS.poi_list.shape),
+	slotMember("url", SLOT_TYPE_DESCRIPTORS.url.shape),
+	slotMember("object_list", SLOT_TYPE_DESCRIPTORS.object_list.shape)
+];
+const SlotDef = z.discriminatedUnion("type", [...SLOT_DEF_MEMBERS]);
+function slotDefTypes() {
+	return SLOT_DEF_MEMBERS.map((m) => m.shape.type.value);
+}
+const ContentSlot = z.object({
+	type: z.enum(CONTENT_SLOT_TYPES),
+	editable_by_user: z.boolean().default(false),
+	required: z.boolean().default(false),
+	produced_by: z.string().optional(),
+	min: z.number().int().nonnegative().optional(),
+	max: z.number().int().positive().optional()
+}).strict();
+function defaultForSlotType(type) {
+	if (!SLOT_TYPES.includes(type)) return null;
+	return SLOT_TYPE_DESCRIPTORS[type].default();
+}
+
+//#endregion
+export { ContentSlot, SLOT_TYPE_DESCRIPTORS, SlotDef, defaultForSlotType, slotDefTypes };

package/dist/schema/source.d.ts

@@ -0,0 +1,13 @@
+import { SourceFieldName } from "../contracts/slot-catalog.js";
+import { TransformName } from "../contracts/transforms.js";
+//#region src/schema/source.d.ts
+declare const direct: (field: SourceFieldName) => {
+  kind: "direct";
+  field: SourceFieldName;
+};
+declare const derived: (transform: TransformName) => {
+  kind: "derived";
+  transform: TransformName;
+};
+//#endregion
+export { derived, direct };

package/dist/schema/source.js

@@ -0,0 +1,12 @@
+//#region src/schema/source.ts
+const direct = (field) => ({
+	kind: "direct",
+	field
+});
+const derived = (transform) => ({
+	kind: "derived",
+	transform
+});
+
+//#endregion
+export { derived, direct };

package/dist/schema/synthesize-nullable.d.ts

@@ -0,0 +1,18 @@
+import "./fixture-schema.js";
+//#region src/schema/synthesize-nullable.d.ts
+type VariantAxes = Record<string, {
+  cases: string[];
+  default: string;
+}>;
+type SchemaForSynth = {
+  slots: Record<string, {
+    type: string;
+    required?: boolean;
+  }>;
+  meta?: {
+    variants?: VariantAxes | undefined;
+  } | undefined;
+  variants?: VariantAxes | undefined;
+};
+//#endregion
+export { SchemaForSynth };

package/dist/schema/synthesize-nullable.js

@@ -0,0 +1,47 @@
+import { resolveBaseVariants } from "./fixture-schema.js";
+
+//#region src/schema/synthesize-nullable.ts
+const LIST_TYPES = /* @__PURE__ */ new Set([
+	"list",
+	"poi_list",
+	"image_collection",
+	"object_list"
+]);
+function emptyValueFor(type) {
+	return LIST_TYPES.has(type) ? [] : null;
+}
+function isAlreadyEmpty(value, type) {
+	return LIST_TYPES.has(type) ? Array.isArray(value) && value.length === 0 : value === null || value === void 0;
+}
+function synthesizeNullableFixtures(schema, module, selfAnchor) {
+	const baseSlots = module.base.slots;
+	const baseOptions = module.base.options ?? {};
+	const baseAnchors = module.base.anchors ?? {};
+	const baseVariants = resolveBaseVariants(schema, module);
+	const out = [];
+	for (const [slotKey, slotDef] of Object.entries(schema.slots)) {
+		if (slotDef.required) continue;
+		if (isAlreadyEmpty(baseSlots[slotKey], slotDef.type)) continue;
+		const empty = emptyValueFor(slotDef.type);
+		out.push({
+			id: `null_${slotKey}`,
+			label: `${slotKey} = ${Array.isArray(empty) ? "empty" : "null"}`,
+			props: {
+				slots: {
+					...baseSlots,
+					[slotKey]: empty
+				},
+				options: { ...baseOptions },
+				nav: {
+					selfAnchor,
+					anchors: { ...baseAnchors }
+				},
+				variants: { ...baseVariants }
+			}
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { synthesizeNullableFixtures };

package/dist/styles.css

@@ -1,16 +1,138 @@
 /*
  * @homepages/template-kit — theme tokens + kit source registration.
  *
- * Consumers import this AFTER `@import "tailwindcss";` in their own entry.
- * This file must NOT import Tailwind itself: two imports in one graph
- * double-emit preflight.
+ * Import this AFTER `@import "tailwindcss";` in your own CSS entry:
  *
- * The @source below is resolved relative to THIS FILE'S SHIPPED LOCATION
- * (dist/styles.css), registering the kit's compiled JS for class scanning.
- * It also overrides Tailwind's default node_modules exclusion.
+ *   @import "tailwindcss";
+ *   @import "@homepages/template-kit/styles.css";
+ *
+ * This file must NOT import Tailwind itself. Exactly one `@import "tailwindcss"` may
+ * exist per build graph — your entry owns it. Two double-emit Tailwind's preflight
+ * reset (box-sizing declared twice, ~4 KB of duplicate base layer).
+ *
+ * The @source below resolves relative to THIS FILE'S SHIPPED LOCATION (dist/styles.css),
+ * registering the kit's compiled JS for class scanning — that is how the utility classes
+ * baked into the kit's primitives reach your compiled CSS. It also overrides Tailwind's
+ * default exclusion of node_modules.
+ *
+ * It is scoped to `primitives/` because those are the ONLY shipped modules that emit
+ * markup. Tailwind's scanner is a plain candidate-extractor — it cannot tell code from a
+ * comment — and the kit ships unminified (deliberately: it keeps these class-name string
+ * literals scannable). Pointed at all of dist/, it therefore compiled prose out of the
+ * CLI's and the ESLint preset's doc comments into every consumer's stylesheet: 8 dead
+ * utilities and 19 stray @property registrations, ~2.5 KB. If a primitive ever moves out
+ * of primitives/, widen this — an unstyled <Image> in every template is the failure mode,
+ * and scripts/verify-consumer.mjs is what catches it.
+ *
+ * The @theme block aliases Tailwind's utility namespace onto the `--tr-*` custom
+ * properties your template's theme.ts supplies (`text-ink` → `var(--tr-color-ink)`).
+ * The aliases are the cross-template contract; the values behind them are yours.
  */
-@source "./**/*.js";
+@source "./primitives/**/*.js";
+
+@theme inline {
+  /* ---------- Colors (alias to the --tr-color-* values a theme.ts supplies) ---------- */
+  --color-ink:           var(--tr-color-ink);
+  --color-ink-soft:      var(--tr-color-ink-soft);
+  --color-ink-mute:      var(--tr-color-ink-mute);
+  --color-background:    var(--tr-color-background);
+  --color-surface:       var(--tr-color-surface);
+  --color-surface-alt:   var(--tr-color-surface-alt);
+  --color-border:        var(--tr-color-border);
+  --color-border-strong: var(--tr-color-border-strong);
+  --color-accent:        var(--tr-color-accent);
+  --color-accent-strong: var(--tr-color-accent-strong);
+  --color-accent-contrast: var(--tr-color-accent-contrast);
+  --color-primary:         var(--tr-color-primary);
+  --color-primary-fg:      var(--tr-color-primary-fg);
+  --color-primary-darker:  var(--tr-color-primary-darker);
+  --color-overlay:        var(--tr-color-overlay);
+  --color-overlay-strong: var(--tr-color-overlay-strong);
+  --color-overlay-light:  var(--tr-color-overlay-light);
+  --color-footer-bg:      var(--tr-color-footer-bg);
+  --color-footer-fg:      var(--tr-color-footer-fg);
+  --color-footer-fg-mute: var(--tr-color-footer-fg-mute);
+  --color-footer-divider: var(--tr-color-footer-divider);
+
+  /* Decorative brand swatches — the open `palette` escape hatch in TokenTheme.
+   * A theme that omits one leaves its utility resolving to an unset custom
+   * property; only reach for these when a semantic role genuinely doesn't fit. */
+  --color-yellow-deep:  var(--tr-color-yellow-deep);
+  --color-yellow-200:   var(--tr-color-yellow-200);
+  --color-yellow-100:   var(--tr-color-yellow-100);
+  --color-brown:        var(--tr-color-brown);
+  --color-green:        var(--tr-color-green);
+  --color-blue:         var(--tr-color-blue);
+  --color-rule:         var(--tr-color-rule);
+  --color-gray-light:   var(--tr-color-gray-light);
+  --color-team-gold:   var(--tr-color-team-gold);
+  --color-mute:         var(--tr-color-mute);
+  --color-scrim:        var(--tr-color-scrim);
+  --color-footer-line:  var(--tr-color-footer-line);
+  --color-footer-mute:  var(--tr-color-footer-mute);
+  --color-divider-40:   var(--tr-color-divider-40);
+  --color-contact-deep: var(--tr-color-contact-deep);
+  --color-header-deep:  var(--tr-color-header-deep);
+
+  /* ---------- Fonts ---------- */
+  --font-sans:    var(--tr-font-sans);
+  --font-display: var(--tr-font-sans);
+  --font-serif:   var(--tr-font-serif);
+  --font-num:     var(--tr-font-num);
+  --font-label:   var(--tr-font-label);
+
+  /* ---------- Type scale (mobile baseline; layer up with md:/lg:) ---------- */
+  --text-xs:      var(--tr-text-xs);
+  --text-sm:      var(--tr-text-sm);
+  --text-base:    var(--tr-text-base);
+  --text-lg:      var(--tr-text-lg);
+  --text-xl:      var(--tr-text-xl);
+  --text-2xl:     var(--tr-text-2xl);
+  --text-3xl:     var(--tr-text-3xl);
+  --text-4xl:     var(--tr-text-4xl);
+  --text-5xl:     var(--tr-text-5xl);
+  --text-display: var(--tr-text-display);
+
+  /* ---------- Spacing (Tailwind's own scale — no custom aliases) ---------- */
+  --spacing: 0.25rem;  /* v4 base unit; Tailwind multiplies (e.g. p-4 = 1rem) */
+
+  /* ---------- Radii ---------- */
+  --radius-sm:   var(--tr-radius-sm);
+  --radius-md:   var(--tr-radius-md);
+  --radius-lg:   var(--tr-radius-lg);
+  --radius-full: var(--tr-radius-full);
+
+  /* ---------- Shadows ---------- */
+  --shadow-sm: var(--tr-shadow-sm);
+  --shadow-md: var(--tr-shadow-md);
+  --shadow-lg: var(--tr-shadow-lg);
+
+  /* ---------- Motion ---------- */
+  --default-transition-duration: var(--tr-duration-fast);
+  --default-transition-timing-function: var(--tr-ease);
 
-@theme {
-  --color-kit-smoke: oklch(0.55 0.2 275);
+  /* ---------- Canonical breakpoint ladder ----------
+   * Eight canonical widths — the same set the preview grid and the screenshot
+   * harness verify a section against (VERIFICATION_WIDTHS is the matching TS
+   * constant). 350 is the mobile-first BASE (no prefix); the other seven are
+   * named breakpoints:
+   *
+   *   bp390 (390) · bp425 (425) · bp512 (512) · md (768) · lg (1024)
+   *   · bp1440 (1440) · bp1920 (1920)
+   *
+   * `md` and `lg` keep Tailwind's own names and values. The off-ladder defaults
+   * (sm/xl/2xl) are reset to `initial` so a section cannot come to depend on a
+   * width nobody screenshots. A swap-heavy section may still reach for a raw
+   * `@media` micro-breakpoint at an off-ladder width (e.g. 640 / 769).
+   */
+  --breakpoint-sm:    initial;
+  --breakpoint-bp390:  390px;
+  --breakpoint-bp425:  425px;
+  --breakpoint-bp512:  512px;
+  --breakpoint-md:     768px;
+  --breakpoint-lg:    1024px;
+  --breakpoint-bp1440: 1440px;
+  --breakpoint-bp1920: 1920px;
+  --breakpoint-xl:    initial;
+  --breakpoint-2xl:   initial;
 }

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-13
+updated: 2026-07-14
 ---
 # template-kit docs — router
 
@@ -11,9 +11,12 @@ This tree **ships in the npm tarball** (`docs/` is listed in `package.json`'s
 LLM agents, reading it from inside `node_modules`. Keep it free of internal-only
 detail.
 
-Cross-service contracts, product, and data model live in `../../docs/` (umbrella)
-and are not shipped.
-
 | Doc | What it covers | Read when you're touching... |
 |---|---|---|
 | `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 |
+| `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
+| `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme`, 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: zero-config setup and its glob scope | wiring up lint in a template workspace |
+| `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 |