@sudajs/cli 0.18.9 → 0.18.11

package/templates/theme/AGENTS.md

@@ -1,1197 +1,198 @@
 # Suda Theme Agent Guide
 
-This directory is a standalone Vite + React + Tailwind Suda theme generated by `suda theme init`.
-
-Your job in a theme project is to create a complete, publishable theme with theme-specific components, realistic starter pages, scoped styling, assets, and AI metadata. Do not build starter pages by assembling generic engine components. Suda adds those blocks automatically so users and AI can create supplemental content pages after the theme is installed.
-
-## Component naming and editor organization
-
-Use the clean Puck Cloud component naming style as a reference for
-editor-facing section names and public component keys. Do not copy its component
-list 1:1; learn the style: names should be short, concrete, and easy to infer
-from the editor without opening the component.
-
-- Group components by page role when `pageConfig.categories` is used. Category
-  `title` values must use `t(...)`, the same as component and field labels.
-  Keep the translated text short and task-oriented, such as `Introduction`,
-  `Content`, `Social Proof`, `Business`, `CMS`, and `Layout`, ordered roughly
-  by where those sections appear in a page.
-- Name components with concise PascalCase nouns that describe the visitor-facing
-  pattern. For example, `ArticleCard` should clearly suggest an article preview
-  card, `FeatureCards` should suggest a group of feature cards, and `ContactUs`
-  should suggest a contact section. Use names that fit the theme's actual
-  sections rather than forcing a fixed list.
-- Avoid theme names, implementation details, and filler suffixes such as
-  `Section`, `Component`, `Block`, `New`, or `Custom` unless the word is part
-  of the public pattern users recognize.
-- When a theme needs multiple components with the same broad purpose, prefer a
-  friendly semantic variant name that tells editors what is different at a
-  glance. Use the content, media, layout, density, or page job as the
-  differentiator, such as `HeroImage`, `HeroVideo`, `MediaHero`,
-  `FeatureCards`, `FeatureList`, `PricingTable`, `PricingCards`,
-  `TestimonialsCarousel`, or `TestimonialsGrid`.
-- Use numbered variants only as a fallback when the variants genuinely share
-  the same purpose and no concise semantic name would make the difference
-  clearer. In that case keep the base name and append a numbered variant to the
-  public key and editor label, for example `FeatureCards-1`,
-  `FeatureCards-2`, `Hero-1`, `Hero-2`, `Cta-1`, or `Cta-2`. Treat `-1` as the
-  primary or most generally useful option, and use later numbers for variants
-  with a clearly different visual rhythm, content density, or business
-  emphasis.
-- Explain the difference between semantic or numbered variants in
-  `ai.instructions` and placement guidance so AI chooses the right one instead
-  of treating them as interchangeable duplicates.
-- Keep instance ids separate from component type names. `content[].type` must
-  match the public component key, while `content[].props.id` remains a stable
-  unique instance id for that concrete page item.
-
-## Theme-building workflow
-
-When you add or change a section, complete the whole theme authoring loop in
-one pass:
-
-1. Define the props type. Use serializable values only. Use `Slot` only for
-   props that are backed by `blockSlots`.
-2. Export a `SudaComponentConfig<Props>` with `label`, `ai.instructions`,
-   `fields`, optional `blockSlots`, `defaultProps`, and `render`.
-3. Keep `fields` and `defaultProps` aligned. Every normal field should have a
-   sensible value in `defaultProps`; do not put block-slot props in
-   `defaultProps`. Do not put `id` in component `defaultProps`; `id` belongs
-   only to concrete top-level page/layout content items.
-4. Add every editor-facing label key to `src/locales/en.json` when you add the
-   component, field, option, or local block.
-5. Register the component in `src/config.ts` under `pageConfig.components`.
-   Register only shared chrome components such as `Header`, `Footer`, and
-   `PageOutlet` under `layoutConfig.components`.
-6. Use the component in starter pages and CMS templates with public component
-   keys from `pageConfig.components`.
-7. Wrap authored page data with `defineSudaPageData(pageConfig, data)` whenever
-   practical so TypeScript checks top-level component types and block-slot
-   nested `type` values.
-8. Run `pnpm typecheck`, `pnpm lint`, `pnpm build`, and `pnpm validate` before
-   handoff.
-
-Rendering fallback rule:
-
-- Defaults belong in `defaultProps`, starter page data, or CMS template data.
-  During render, read values directly from props. Do not add fallback display
-  values with `||`, `??`, or ternaries unless the fallback is truly required for
-  runtime safety.
-- This is wrong because render invents content that is not in props:
-
-```tsx
-<div>{props.title || "title"}</div>
-```
-
-- This is correct because render only displays the authored prop value:
-
-```tsx
-<div>{props.title}</div>
-```
-
-- Conditional rendering is fine when absence intentionally removes optional UI,
-  such as hiding an optional image, button, or eyebrow. Do not use conditional
-  rendering to substitute placeholder copy, labels, links, or menu items.
-
-Configure ordinary fields like this:
-
-```ts
-type HeroProps = {
-  eyebrow?: string;
-  title?: string;
-  body?: string;
-  align?: "left" | "center";
-  featured?: boolean;
-};
-
-export const Hero: SudaComponentConfig<HeroProps> = {
-  label: t("sections.hero.label"),
-  ai: {
-    instructions:
-      "Landing page hero section. Configure concise copy and a layout choice.",
-  },
-  fields: {
-    eyebrow: { type: "text", label: t("sections.hero.fields.eyebrow") },
-    title: { type: "text", label: t("sections.hero.fields.title") },
-    body: { type: "textarea", label: t("sections.hero.fields.body") },
-    align: {
-      type: "select",
-      label: t("sections.hero.fields.align"),
-      options: [
-        { label: t("common.options.left"), value: "left" },
-        { label: t("common.options.center"), value: "center" },
-      ],
-    },
-    featured: { type: "checkbox", label: t("sections.hero.fields.featured") },
-  },
-  defaultProps: {
-    eyebrow: "New",
-    title: "Welcome",
-    body: "Describe the main offer in one or two sentences.",
-    align: "left",
-    featured: true,
-  },
-  render: ({ eyebrow, title, body, align, featured }) => (
-    <section data-align={align} data-featured={featured ? "true" : "false"}>
-      {eyebrow ? <p>{eyebrow}</p> : null}
-      <h1>{title}</h1>
-      {body ? <p>{body}</p> : null}
-    </section>
-  ),
-};
-```
-
-Use normal fields for scalar section settings such as text, textarea, number,
-range, checkbox, select/radio options, media, URL, icon, color, object, and
-array values. Put those field values in the host component's `defaultProps`.
-Use `blockSlots` only when the section owns nested local blocks that editors
-and AI should add, remove, or reorder independently.
-
-Field source of truth:
-
-- Use TypeScript, not a hand-written runtime schema. Type props first, then let
-  `SudaComponentConfig<Props>`, `SudaFields<Props>`, `SudaField`, and
-  `defineSudaPageData(pageConfig, data)` catch mismatches.
-- There is no theme-authored zod schema for fields. Do not invent one in the
-  theme. Run `pnpm typecheck` and `pnpm validate` instead.
-- Every field entry needs a `type`. Add a localized `label` for every
-  editor-facing field.
-- Put a matching serializable value in `defaultProps` for every normal field.
-  Optional props can still have defaults; defaults make editor insertion and AI
-  generation reliable.
-- Use `description`, `placeholder`, and `visibleIf` only when they help the
-  editor or AI choose the right value.
-- Suda extended field types are `url`, `icon`, `color`,
-  `range`, `spacing`, `media`, `image`, `video`, and `posts`. These are valid
-  in `fields` and are normalized by `@sudajs/theme-engine`.
-
-## Navigation and footer menus
-
-Navigation and footer menus must be typed arrays. Do not use the legacy menu
-field type, multiline text areas, or newline-delimited strings to model menus.
-Every link destination must use a `url` field type, never a plain `text` field.
-The `fields`, TypeScript props, and `defaultProps` data structures must match
-exactly.
-
-Navigation supports at most two levels:
-
-- `navItems[]`
-- `navItems[].submenu[]`
-
-Submenu items may contain only text and link fields. Do not add another nested
-submenu field inside `navItems[].submenu[]`; the field shape must make third
-levels impossible. An empty `submenu` array means the item is an ordinary
-top-level link.
-
-The simplest Navigation field shape is:
-
-```ts
-type NavSubItem = {
-  label: string;
-  href: string;
-};
-
-type NavItem = {
-  label: string;
-  href: string;
-  submenu: NavSubItem[];
-};
-
-const navItemsField = {
-  type: "array",
-  label: t("common.fields.navigationItems"),
-  getItemSummary: (item: NavItem) => item.label || "Navigation item",
-  defaultItemProps: {
-    label: "Home",
-    href: "/",
-    submenu: [],
-  },
-  arrayFields: {
-    label: {
-      type: "text",
-      label: t("common.fields.label"),
-    },
-    href: {
-      type: "url",
-      label: t("common.fields.link"),
-    },
-    submenu: {
-      type: "array",
-      label: t("common.fields.submenu"),
-      getItemSummary: (item: NavSubItem) => item.label || "Submenu item",
-      arrayFields: {
-        label: {
-          type: "text",
-          label: t("common.fields.label"),
-        },
-        href: {
-          type: "url",
-          label: t("common.fields.link"),
-        },
-      },
-    },
-  },
-};
-
-const defaultNavItems: NavItem[] = [
-  {
-    label: "Home",
-    href: "/",
-    submenu: [],
-  },
-  {
-    label: "Company",
-    href: "/company",
-    submenu: [
-      {
-        label: "About",
-        href: "/about",
-      },
-    ],
-  },
-];
-```
-
-Footer grouped menus use two array levels:
-
-- `columns[]`
-- `columns[].links[]`
-
-Use this prop shape and mirror it exactly in the field config and defaults:
-
-```ts
-type FooterColumn = {
-  title: string;
-  links: {
-    text: string;
-    url: string;
-  }[];
-};
-
-const footerColumnsField = {
-  type: "array",
-  label: t("common.fields.columns"),
-  getItemSummary: (item: FooterColumn) => item.title || "Footer column",
-  defaultItemProps: {
-    title: "Company",
-    links: [{ text: "About", url: "/about" }],
-  },
-  arrayFields: {
-    title: {
-      type: "text",
-      label: t("common.fields.title"),
-    },
-    links: {
-      type: "array",
-      label: t("common.fields.links"),
-      getItemSummary: (item: FooterColumn["links"][number]) => item.text || "Footer link",
-      defaultItemProps: {
-        text: "About",
-        url: "/about",
-      },
-      arrayFields: {
-        text: {
-          type: "text",
-          label: t("common.fields.label"),
-        },
-        url: {
-          type: "url",
-          label: t("common.fields.link"),
-        },
-      },
-    },
-  },
-};
-```
-
-Use these field patterns:
-
-```ts
-fields: {
-  // Plain copy
-  title: { type: "text", label: t("common.fields.title") },
-  body: { type: "textarea", label: t("common.fields.description") },
-  richBody: { type: "richtext", label: t("common.fields.content") },
-
-  // Numbers and booleans
-  columns: { type: "number", label: t("common.fields.columns") },
-  featured: { type: "checkbox", label: t("common.fields.featured") },
-  opacity: {
-    type: "range",
-    label: t("common.fields.opacity"),
-    min: 0,
-    max: 100,
-    step: 5,
-    unit: "%",
-  },
-
-  // Choices: always provide options with localized labels and serializable values.
-  align: {
-    type: "radio",
-    label: t("common.fields.align"),
-    options: [
-      { label: t("common.options.left"), value: "left" },
-      { label: t("common.options.center"), value: "center" },
-    ],
-  },
-  tone: {
-    type: "select",
-    label: t("common.fields.tone"),
-    options: [
-      { label: t("common.options.light"), value: "light" },
-      { label: t("common.options.dark"), value: "dark" },
-    ],
-  },
-
-  // Suda extended fields
-  href: { type: "url", label: t("common.fields.link") },
-  image: { type: "image", label: t("common.fields.image") },
-  video: { type: "video", label: t("common.fields.video") },
-  download: { type: "media", kind: "file", label: t("common.fields.file") },
-  icon: { type: "icon", label: t("common.fields.icon") },
-  accentColor: { type: "color", label: t("common.fields.color") },
-  spacing: { type: "spacing", label: t("common.fields.spacing") },
-
-  // Dynamic post lists. Use this only on page sections that intentionally
-  // render post resources, not on fixed CMS main sections.
-  postList: { type: "posts", label: t("common.fields.posts") },
-
-  // Objects and arrays need nested typed fields.
-  badge: {
-    type: "object",
-    label: t("common.fields.badge"),
-    objectFields: {
-      label: { type: "text", label: t("common.fields.label") },
-      tone: { type: "text", label: t("common.fields.tone") },
-    },
-  },
-  cards: {
-    type: "array",
-    label: t("common.fields.cards"),
-    getItemSummary: (item) => item.title || "Card",
-    defaultItemProps: { title: "Card title", body: "Card body" },
-    arrayFields: {
-      title: { type: "text", label: t("common.fields.title") },
-      body: { type: "textarea", label: t("common.fields.description") },
-      href: { type: "url", label: t("common.fields.link") },
-    },
-  },
-}
-```
-
-Match those fields with defaults:
-
-```ts
-defaultProps: {
-  title: "Welcome",
-  body: "Describe the offer.",
-  richBody: "<p>Long-form content.</p>",
-  columns: 3,
-  featured: true,
-  opacity: 80,
-  align: "left",
-  tone: "light",
-  href: "/contact",
-  image: themeAsset("assets/hero.jpg"),
-  video: "",
-  download: "",
-  icon: "sparkles",
-  accentColor: "#2563eb",
-  spacing: "md",
-  postList: { strategy: "featured", limit: 3 },
-  badge: { label: "New", tone: "primary" },
-  cards: [{ title: "Fast setup", body: "Launch quickly.", href: "/features" }],
-}
-```
-
-Starter page and CMS template data must use this shape:
-
-```ts
-defineSudaPageData(pageConfig, {
-  root: { props: {} },
-  content: [
-    {
-      type: "Hero",
-      props: {
-        id: "Hero-1",
-        title: "Welcome",
-        actions: [
-          {
-            type: "button",
-            props: { label: "Contact us", href: "/contact" },
-          },
-        ],
-      },
-    },
-  ],
-});
-```
-
-Top-level `content[].type` must be a key registered in `pageConfig.components`.
-Top-level `content[].props.id` is required in starter pages, CMS templates, and
-layout data. Do not put `id` in component `defaultProps`, local block
-`defaultProps`, `defaultBlocks`, or block-slot nested items.
-Nested block-slot items must use short local block kind names such as
-`"button"`, `"copy"`, or `"cards"`. Never write
-`__suda_local_block__/...` in source templates, starter pages, CMS templates,
-or AI examples.
-
-## Theme contract
-
-- Keep `renderMode: "ssr"` in `src/manifest.ts`.
-- Keep source entries at `src/index.tsx` and `src/styles.css`. The CLI owns and generates `dist/runtime.client.js`; do not add `src/runtime.client.ts(x)`.
-- If the theme needs browser-only setup, export `clientHooks` from `src/client.ts`. Do not export theme configuration from that file.
-- Export a complete `ThemeModule` from `src/index.tsx`: `manifest`, `pageConfig`, `layoutConfig`, `defaultLayout`, `starterPages`, and `cmsTemplates`.
-- Starter page slugs preview at site-like root routes in `suda theme dev`: `index` is `/index`, `contact-us` is `/contact-us`. Do not use `/pages/...` as a preview route prefix.
-- Keep `pageConfig` focused on page content sections. Keep `layoutConfig` focused on shared site chrome such as root, header, page outlet, and footer.
-- Do not edit generated files under `dist/`; run `pnpm build` to regenerate them.
-- React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers. Do not bundle private copies into the theme runtime.
-- Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
-
-### Public site language list
-
-Read public-site language switch targets with `getSiteLocale(puck?.metadata)`
-from `@sudajs/theme-engine/runtime`. Render the host-provided `label` and link
-to the host-provided `href`; do not derive a language name or construct a locale
-URL in theme code.
-
-```tsx
-const siteLocale = getSiteLocale(puck?.metadata);
-
-{
-  siteLocale?.locales.map((item) => (
-    <a key={item.locale} href={item.href} lang={item.locale}>
-      {item.label}
-    </a>
-  ));
-}
-```
-
-## Puck editor CSS isolation
-
-Puck renders the editable preview in a same-origin iframe. The outer
-`#puck-canvas-root` and `#preview-frame` may be only one viewport tall; the
-full page must scroll inside the iframe. Theme CSS must not collapse or disable
-that iframe document.
-
-- In editor mode, make the theme root content-height driven. A root marker such
-  as `[data-suda-editor="true"]` should use `height: auto`,
-  `min-height: 100vh`, and `overflow: visible` unless the theme has a stronger
-  reason not to.
-- If the theme root is rendered inside Puck's `#frame-root`, ensure
-  `#frame-root` can grow with content in editor mode. Do not leave it stuck at
-  a collapsed height when it contains the theme root.
-- Root `[data-puck-dropzone]` wrappers must be able to grow with page content.
-  Avoid forcing `height: 100%` on the root DropZone when that turns the page
-  into a single viewport-height box.
-- Keep public-site resets from leaking into Puck behavior. Be very careful with
-  global `html`, `body`, `iframe`, `.hidden`, `img`, `button`, `input`, and
-  Tailwind preflight rules; they can hide editor wrappers, change intrinsic
-  media sizing, or break iframe scrolling.
-- When importing third-party CSS, add editor-scoped overrides under the theme
-  root marker instead of changing public runtime behavior globally.
-- Verify the editor canvas by scrolling through every starter page. Components
-  must be visible and reachable without selecting them from the outline first.
-
-## CMS and starter templates
-
-Suda CMS is a built-in fixed post system. Themes must provide exactly these
-four CMS templates through `cmsTemplates`:
-
-- `posts`: post list template for `/posts`
-- `post`: post detail template for `/posts/:slug`
-- `tags`: tag/category list template for `/tags`
-- `tag`: posts filtered by one tag for `/tags/:slug`
-
-Each `cmsTemplates` value must be an object with `{ title: string; data:
-PageData }`. Do not point a key directly at raw `PageData`, and do not use
-intersection types such as `ThemeModule & { cmsTemplates:
-Record<string, PageData> }` to bypass the current contract.
-
-```ts
-export const cmsTemplates: ThemeCmsTemplates = {
-  posts: { title: "Posts", data: postIndexTemplate },
-  post: { title: "Post", data: postDetailTemplate },
-  tags: { title: "Tags", data: tagIndexTemplate },
-  tag: { title: "Tag", data: tagDetailTemplate },
-};
-```
-
-Do not create Shopify-style template variants such as `post.default`,
-`post.modern`, or `posts.magazine`. Do not add arbitrary collection/content
-types or manual data-source binding contracts. Keep CMS-only sections limited
-to the CMS templates where they belong.
-
-Create CMS template main sections like this:
-
-- `MainPosts`: place only on `posts` and optionally `tag` templates with
-  `placement: { cmsTemplates: ["posts", "tag"] }`; render `cms.posts`
-  directly and use `cms.pagination` for pagination controls. Use
-  `cms.currentTag` when a tag filter is active.
-- `MainPost`: place only on the `post` template; render the current article
-  when `cms.type === "post"`.
-- `MainTags`: place only on the `tags` template; render tag/category cards
-  when `cms.type === "tags"`.
-- `MainTagPosts` can be a separate tag-page list section, or `MainPosts` can
-  handle both `posts` and `tag` contexts. Choose the clearer API for the theme.
-
-In CMS template main sections, call `getCmsContent(puck?.metadata)` and render
-the matching CMS data. Do not add `type: "posts"` fields to those sections.
-
-For pagination controls, use `cms.pagination.page`,
-`cms.pagination.totalPages`, `cms.pagination.hasPreviousPage`, and
-`cms.pagination.hasNextPage` to decide what to show. Do not hand-build
-pagination query strings. Import `cmsPaginationUrl` from
-`@sudajs/theme-engine/runtime` and call
-`cmsPaginationUrl(cms.pagination, targetPage)` for numbered links so existing
-filter/search parameters stay in the URL. Use `cms.pagination.previousUrl` and
-`cms.pagination.nextUrl` for previous/next buttons when present.
-
-Themes must also provide at least one reusable ordinary-page post section, for
-example `FeaturedPosts`, `LatestPosts`, or `TopicPosts`. Use it for homepage
-insights, featured articles, case studies, news teasers, or tag-filtered post
-groups on ordinary pages.
-
-Define that section with exactly one top-level `type: "posts"` field and a
-default query on the same prop:
-
-```tsx
-fields: {
-  postList: { type: "posts" },
-},
-defaultProps: {
-  postList: { strategy: "featured", limit: 3 },
-},
-```
-
-Supported strategies are `latest`, `featured`, `by_tag`, and `manual`. Manual
-queries store only `items` and must not include `limit`. Runtime post resources
-are keyed as `${props.id}.${fieldKey}` with both parts URL-encoded by the
-platform. In the section render function, call
-`getPostResource(puck?.metadata, { componentId: props.id, fieldKey: "postList" })`
-with the exact posts field key. Never import Prisma, call platform APIs, or
-query the database from theme code.
-
-When rendering posts returned by `getPostResource`, build links from the
-platform-provided `post.url` first. If it is missing, derive the URL only from
-`post.slug` as `/posts/${encodeURIComponent(post.slug)}`; if neither exists,
-use `#`. Do not guess alternate fields such as `href`, `path`, `permalink`,
-`postUrl`, or `canonicalUrl`.
-
-Do not add `resourceQuery: { type: "posts" }` or
-`resource_query: { type: "posts" }`. Do not assume the field must be named
-`query`. A section may have only one top-level posts field; do not nest posts
-fields inside `object`, `array`, native slots, or `blockSlots`.
-
-Starter pages must include one home/index page with `isHome: true`. Recommended
-starter pages include `index`, `about-us`, `contact-us`, `services`, and `team`.
-Those recommended pages are not hard requirements, but a publishable theme
-should usually include several realistic pages so AI site generation has a rich
-reference set.
-
-Treat repetition as a design and business judgment, not a fixed rule. Let the
-site strategy decide where pages should share patterns and where they should
-diverge. Reusing strong sections across starter pages is often right: CTA,
-contact, booking, newsletter, download, and other conversion sections may appear
-repeatedly when they help visitors move forward. Avoid only mechanical
-copy-paste that makes different pages feel interchangeable. When useful, give
-each page its own purpose, angle, proof points, media, or ordering, while
-keeping repeated business-driving sections where they serve the user journey.
-Richer starter pages make the theme easier for AI to adapt without making users
-learn CMS/template mechanics.
-
-## Editor i18n and locales
-
-Theme editor labels are localized by the host editor. Use the template's
-`src/i18n.ts` helper for every component label, field label, option label, and
-other editor-facing configuration string.
-
-- Import `t` from `./i18n.js` in files that define `pageConfig`, `layoutConfig`,
-  categories, fields, options, or local blocks.
-- Write labels as stable dot-path keys, for example
-  `label: t("sections.hero.fields.title")`, not hardcoded strings.
-- Add every key used with `t(...)` to `src/locales/en.json`. This file is the
-  required reference locale for theme validation.
-- Keep locale values as nested JSON objects whose leaves are strings. Arrays,
-  numbers, booleans, and null are invalid locale values.
-- When adding another locale such as `src/locales/zh-CN.json`, keep its leaf key
-  set exactly aligned with `src/locales/en.json`; missing or extra keys fail
-  `suda theme validate`, `suda theme check`, `pnpm build`, and publish.
-- The CLI copies `src/locales/*.json` into `dist/locales/` during build. Files
-  named `<locale>.json` are editor messages; files named
-  `<locale>.content.json` are starter preview content messages. Do not
-  edit `dist/locales/` directly.
-- If an installed legacy theme is missing locale files, the editor falls back to
-  showing translation keys instead of crashing. New themes must still pass
-  locale validation before publishing.
-- Keep editor `t(...)` out of actual page content, starter page copy, default
-  prop values, and public-site text. Starter preview copy may instead use the
-  separate `t` exported by `src/preview-i18n.ts`; direct strings remain valid
-  and editor-saved values are always plain strings.
-
-## Starter preview content locales
-
-Use `src/preview-i18n.ts` only inside starter page templates for user-visible
-content such as page titles, headings, descriptions, list copy, and button
-labels. Keep URLs, slugs, IDs, component types, and asset paths as direct
-strings. Do not use preview translations in component labels, fields, default
-props, layout configuration, or CMS templates.
-
-- `src/locales/en.content.json` is the required default content locale whenever
-  `manifest.previewLocales` is declared.
-- Add every supported locale to `manifest.previewLocales`, including `en`, and
-  create the matching `src/locales/<locale>.content.json` file.
-- Every content locale file must have exactly the same string leaf keys as
-  `en.content.json`; undeclared, missing, extra, or partial locale files fail
-  validation and publishing.
-
-Example:
-
-```tsx
-import { t } from "./i18n.js";
-
-export const Hero: SudaComponentConfig<HeroProps> = {
-  label: t("sections.hero.label"),
-  fields: {
-    title: { type: "text", label: t("sections.hero.fields.title") },
-    tone: {
-      type: "radio",
-      label: t("sections.hero.fields.tone"),
-      options: [
-        { label: t("sections.hero.fields.toneWarm"), value: "warm" },
-        { label: t("sections.hero.fields.toneSharp"), value: "sharp" },
-      ],
-    },
-  },
-};
-```
-
-## Component strategy
-
-- Create theme-specific components and sections first. Every page component should express this theme's brand, industry, visual rhythm, and content model.
-- Do not register `createEngineComponents()`, `createBaseBlocks()`, or `createContainers()` in `pageConfig.components` when creating a theme. Suda automatically adds the platform base content blocks (`Text`, `Heading`, `RichText`, `Markdown`, `Image`, `Button`, and `Spacer`) to every page config. Use the single `Markdown` block for standalone long-form pages such as privacy policies, terms, legal notices, documentation, or guides that should not appear in CMS posts. Generic blocks supplement theme-specific sections; they are not the foundation of starter templates.
-- Prefer purpose-built sections such as hero, services, product highlights, feature comparisons, gallery, process, pricing, testimonial, FAQ, article list, contact, and CTA when the theme needs those patterns.
-- Keep section APIs semantic. Expose props that describe content and editor decisions, not implementation details.
-- Keep `fields`, `defaultProps`, and `render` in sync. Every editor field should have a sensible default, and render functions should tolerate omitted optional values.
-- Put editor controls in props when they change rendering, for example `showLogo`, `mediaPosition`, `tone`, or `columns`; pair dependent controls with `visibleIf` rather than hiding logic only in JSX.
-
-## Layout and slot rules
-
-- Page-level sections and components must not declare native Puck `slot` fields. Do not write `fields: { content: { type: "slot" } }` in page components.
-- Native Puck slots are reserved for Suda-provided layout/container primitives and theme layout components. The normal template pattern is the one in `src/layout.tsx`: `rootConfig` renders `children`, `PageOutlet` renders `getPageSlot(puck?.metadata)`, and `Header` / `Footer` surround that outlet in `defaultLayout`.
-- Do not add arbitrary nested page composition through native slots. It makes AI-generated pages unpredictable and hard to validate.
-- If a page section needs controlled nested content, use Suda `blockSlots`, not a hand-written Puck slot field. `blockSlots` lets the theme define exactly which local block kinds are allowed inside that section.
-- Do not use legacy DropZone or `zones` patterns.
-
-## Puck Editor Compatibility Contract
-
-Every public page and layout component must render consistently in the public
-site, the Puck Editor iframe, and editor preview mode. Build this compatibility
-in when creating the theme; do not wait for an editor-only positioning bug.
-
-### Puck mutates the real component root
-
-In edit mode Puck may attach selection and drag attributes and an inline
-position directly to the first real DOM element returned by a component:
-
-```ts
-el.setAttribute("data-puck-component", id);
-el.setAttribute("data-puck-dnd", id);
-el.style.position = "relative";
-```
-
-- Never assume `[data-puck-component]` is an external wrapper. It may be the
-  component's own `<nav>`, `<header>`, `<section>`, or `<footer>`.
-- `:has(.component-root)` does not match an element that is itself
-  `.component-root`. When both DOM shapes are possible, cover both explicitly:
-
-```css
-.component-root[data-puck-component],
-[data-puck-component]:has(.component-root) {
-  /* compatibility override */
-}
-```
-
-- Puck's inline `position: relative` beats ordinary theme CSS. A component
-  whose real root must remain `sticky`, `fixed`, or `absolute` in the editor
-  needs a specific editor-scoped rule with `!important`.
-- Never apply `position: relative !important` to every editor component. That
-  destroys navigation, overlays, and floating controls.
-
-### Stable component roots
-
-- Every public page and layout component should return one stable, semantic,
-  real DOM root. Prefer `<header>` or `<nav>` for navigation, `<footer>` for the
-  footer, and `<section>` or an explicit container for ordinary sections.
-- Do not use a Fragment as the root of a component that controls positioning,
-  margin, size, stacking, background, or editor selection. Do not depend on
-  Puck to wrap a Fragment.
-- Do not use `display: contents` on a root that needs margin, padding,
-  positioning, sticky/fixed behavior, `z-index`, background, or a selection
-  outline.
-- `PageOutlet` must render a real DOM element when it needs negative margin,
-  overlap, positioning, or sizing.
-
-### Explicit editor scope
-
-The layout root must derive editor state from
-`puck?.metadata?.isEditor === true` and expose a stable marker:
-
-```tsx
-<div className="theme-root" data-suda-editor={isEditor ? "true" : undefined}>
-  {children}
-</div>
-```
-
-Keep every editor-only compatibility rule below
-`.theme-root[data-suda-editor="true"]`. Do not globally override `.navbar`,
-`.section`, or `[data-puck-component]`, change the public-site layout to repair
-the editor, use vague selectors that affect unrelated components, or edit
-third-party minified CSS. Put compatibility overrides in the theme's scoped
-`src/styles.css`.
-
-When the component itself may be the Puck root or may sit inside one, write and
-test both selectors. Keep later rules from overriding the correction:
-
-```css
-.theme-root[data-suda-editor="true"] .theme-navigation[data-puck-component],
-.theme-root[data-suda-editor="true"]
-  [data-puck-component]:has(.theme-navigation)
-  .theme-navigation {
-  position: sticky !important;
-  top: 0;
-  z-index: 30;
-}
-```
-
-### Sticky and fixed positioning
-
-Before implementing Header, announcement bar, floating CTA, or any
-sticky/fixed component, verify all of the following:
-
-- whether Puck writes `position: relative` on the actual positioned root;
-- which element really scrolls in the site and in the editor iframe;
-- that the sticky element is inside the intended scroll container;
-- whether any ancestor has `overflow: hidden`, `auto`, `scroll`, or `clip`, or
-  has `transform`, `filter`, `perspective`, or `contain`;
-- that the sticky parent is taller than the sticky element where required;
-- that `top` and `z-index` are explicit; and
-- that iframe scrolling and the outer editor canvas do not use incompatible
-  coordinate systems.
-
-For a layout Header, prefer putting sticky behavior on the Header's real root.
-If that root receives `data-puck-component`, override Puck's inline position on
-that same node. Do not force the Header root to `relative !important` and then
-expect a parent sticky rule to work. Site and editor may use different
-positioning strategies only when their visual result remains equivalent.
-
-### Transparent navigation is state plus layout
-
-Transparent navigation must coordinate all of these concerns, not merely set
-`background: transparent`:
-
-- transparent background and removed shadow;
-- logo, menu text, and button color changes;
-- Hero or `PageOutlet` overlap beneath the Header;
-- restoration of the solid state after the scroll threshold;
-- Puck's root-node positioning mutation in the editor; and
-- identical SSR-first-frame and hydrated state.
-
-Never render a white logo/text state above an accidentally white navigation
-background. Prefer React Context for a page's transparent-navigation request,
-an SSR-readable DOM marker for the first-frame fallback, and a real
-`PageOutlet` element with negative margin in the editor. The public site may use
-a spacer or equivalent layout strategy. Keep shared measurements in CSS
-variables, for example `--theme-navigation-height: 4.6rem`.
-
-### Editor scroll detection
-
-Do not rely only on `window.scrollY` or a `window` scroll listener. The active
-scroll source may be `document.scrollingElement`, the iframe document, or an
-inner `overflow: auto/scroll` container, and `scroll` does not bubble.
-
-- Find the nearest scrollable ancestor for each navigation instance and read
-  that element's own `scrollTop`.
-- Listen on the document with
-  `document.addEventListener("scroll", handler, { capture: true, passive: true })`
-  and keep a window listener for public-site compatibility.
-- Do not assume editor and site share the same scrolling element.
-
-### React and editor runtime lifecycle
-
-Runtime code must tolerate editor remounts, live prop changes, HMR, frequent
-`MutationObserver` callbacks, React Strict Mode effect replay, and loading after
-`DOMContentLoaded` has already fired.
-
-- Make event binding and initialization idempotent.
-- Observe components inserted later and relevant attribute changes.
-- Do not use a permanent `window.__xxxBound` flag that prevents required HMR
-  reinitialization.
-- Clean up component effects, observers, and listeners.
-- Keep SSR markers and client state synchronized instead of letting them fight.
-
-### Puck interaction styles
-
-Assume edit mode may apply rules equivalent to:
-
-```css
-[data-puck-component] * {
-  pointer-events: none;
-  user-select: none;
-}
-
-[data-puck-component] {
-  pointer-events: auto !important;
-}
-```
-
-An unclickable link, dropdown, carousel, or button in edit mode is not by
-itself a theme interaction bug. Distinguish edit mode from preview mode. Never
-globally restore descendant pointer events because that breaks selection and
-dragging; test visitor interactions in editor preview and the public site.
-
-### Layout ownership
-
-- Keep only `Header`, `PageOutlet`, `Footer`, and necessary global chrome such
-  as an announcement bar in `layoutConfig`.
-- Render Header and Footer exactly once per page from the layout. Do not repeat
-  them in starter pages.
-- If Footer or Header moves from page sections into the layout, remove duplicate
-  entries from `starterPages`, `cmsTemplates`, `pageConfig.categories`, and AI
-  examples.
-- Give Header, `PageOutlet`, and Footer stable `props.id` values, with
-  `PageOutlet` between Header and Footer.
-- Read platform white-label, ICP, and other footer metadata from runtime
-  metadata; do not persist it as duplicated static component data.
-
-### Vendor CSS
-
-Do not modify original third-party minified CSS unless the task explicitly
-requires a maintained vendor patch. Use precise selectors in the theme's own
-scoped `src/styles.css`. If a vendor file truly must change, document the
-reproducible problem and why an override cannot solve it.
-
-### New-theme completion checklist
-
-When creating a theme, complete all of these in the initial implementation:
-
-- editor root marker and stable real roots;
-- layout-owned Header / `PageOutlet` / Footer with stable ids;
-- Header sticky compatibility in the editor;
-- transparent navigation in editor and site modes;
-- scrollable-ancestor detection and an SSR state marker;
-- idempotent runtime setup and cleanup;
-- real-element `PageOutlet` overlap behavior;
-- responsive viewport behavior; and
-- editor preview versus public-site comparison.
-
-### Required regression matrix
-
-Whenever Header, transparent navigation, sticky/fixed positioning,
-`PageOutlet`, Footer, carousel, dropdown/mobile menu, or a `100vh` Hero changes,
-verify:
-
-- public-site SSR first frame and post-hydration state;
-- editor desktop, tablet, and mobile viewports;
-- editor edit mode and preview mode;
-- initial top state and state after crossing the scroll threshold;
-- state after HMR and live prop updates;
-- exactly one Header and one Footer; and
-- intact Puck selection and drag behavior.
-
-### Debugging order
-
-When editor and site differ, inspect in this order before changing CSS:
-
-1. The component's actual root node.
-2. The element that received `data-puck-component`.
-3. Inline styles written on that element.
-4. Computed `position`, `background`, `z-index`, and ancestor `overflow`.
-5. The real scrolling element and its `scrollTop`.
-6. Iframe versus outer-canvas coordinate systems.
-7. Whether the theme runtime initialized.
-8. Transparent-state Context and DOM markers.
-9. Stylesheet load and cascade order.
-
-Do not guess selectors repeatedly before confirming the DOM and computed style.
-
-## Design system rules
-
-Build every theme from one theme-level design system. Do not let each section,
-CMS template, block slot, or starter page invent its own colors, type scale,
-radius, shadows, or spacing.
-
-- Define the editable theme system once in `src/manifest.ts` as
-  `sourceManifest.designSystem`. Include `version`, `defaultPresetId`, and
-  named `presets` with complete token sets.
-- Use stable token names from the engine contract. At minimum, provide the
-  color tokens the theme renders (`background`, `foreground`, `primary`,
-  `primaryForeground`, `secondary`, `secondaryForeground`, `accent`,
-  `accentForeground`, `muted`, `mutedForeground`) and the radius tokens the CSS
-  consumes (`card`, `button`, `input`). Do not invent platform-facing token
-  keys without checking the generated types first.
-- Expose the design system at the layout root only, for example:
-  ```ts
-  designSystem: designSystemField(t("common.fields.designSystem"), sourceManifest.designSystem);
-  ```
-  Use `createThemeDesignDefault(sourceManifest.designSystem)` in
-  `ROOT_DEFAULTS`.
-- In the root render, resolve the value once with
-  `resolveThemeDesignTokens(sourceManifest.designSystem, props.designSystem)`
-  and apply `createThemeDesignCssVariables(tokens)` to the theme root element.
-  Components should consume CSS variables; they should not resolve design
-  presets themselves.
-- Pure Tailwind themes should map Suda tokens only through `@theme inline`, then
-  consume utilities such as `bg-primary`, `text-primary-foreground`, and
-  `rounded-card`. The `inline` keyword is required so generated utilities read
-  `--suda-*` on the rendered theme root instead of resolving a `--color-*`
-  alias on `:root`.
-- Hand-written CSS classes must consume `--suda-*` directly. Do not use
-  `var(--color-primary)`, `var(--color-background)`, `var(--radius-card)`, or
-  another Suda-backed alias declared by `@theme inline`; those compiler aliases
-  live on `:root` while Suda injects editable tokens on the descendant theme
-  root in production.
-- When hand-written CSS needs a derived value, declare a theme-prefixed custom
-  property on the theme root and consume that property, for example:
-  ```css
-  .my-theme-root {
-    --my-theme-primary-hover: color-mix(in srgb, var(--suda-color-primary) 84%, black);
-  }
-  .my-theme-button:hover {
-    background: var(--my-theme-primary-hover);
-  }
-  ```
-  `suda theme check`, build, and publish reject hand-written consumption of
-  Suda-backed `@theme inline` aliases.
-- Keep typography and spacing scales centralized in `src/styles.css`. Define
-  reusable classes or variables for containers, section padding, headings,
-  eyebrow text, body copy, cards, buttons, inputs, and media frames. Reuse those
-  classes instead of writing new one-off Tailwind values in every section.
-- Section props may expose semantic choices such as `tone`, `variant`,
-  `columns`, `mediaPosition`, `showImage`, or `spacing`. Map those choices to
-  the existing design tokens and shared CSS classes.
-- Do not add raw `color`, typography, `spacing`, `radius`, or `shadow` fields to a
-  section just because the CSS has a value. Expose a design token field only
-  when the user should intentionally customize that value per component
-  instance. Otherwise, keep the value in the theme CSS.
-- Use `color` and `spacing` field types only for real editor-facing
-  design controls. Use `select`/`radio` for named variants that are already
-  part of the theme design system.
-- Local blocks inside `blockSlots` inherit the host section's design system.
-  Local block fields should edit content or semantic variants, not define their
-  own palette, type scale, radius, shadows, or spacing.
-- CMS main sections (`MainPosts`, `MainPost`, `MainTags`, `MainTagPosts`) and
-  ordinary post-resource sections must use the same containers, heading scale,
-  card style, media ratio, pagination style, and empty/loading states as the
-  rest of the theme.
-- Starter pages must demonstrate the same design system across different page
-  types. Vary content, order, media, and semantic variants; do not hardcode
-  unrelated colors, spacing, rounded corners, or shadows in starter page data to
-  make pages look different.
-- When adding a new section, first choose the existing container, heading,
-  button, card, form, and media patterns it should reuse. Add a new CSS utility
-  or token only when multiple sections will use it or the theme needs a new
-  named pattern.
-- Keep preview screenshots, default props, starter pages, CMS templates, and
-  AI examples aligned with the same token presets. The default preset should
-  look publishable without manual editor tweaks.
-
-## Styling and assets
-
-- Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and `@source "./**/*.{ts,tsx}";`.
-- Theme-local assets live in top-level `assets/`; the CLI copies them to `dist/assets/` during build.
-- Import `themeAsset` from `./theme-asset.js` and use `themeAsset("assets/...")` for every theme-bundled asset in default props, starter pages, CMS templates, and AI examples.
-- Do not hand-write `themes/<themeKey>/<version>/...` paths and do not import theme-local images from React code. Full external URLs are allowed, for example CDN URLs such as jsDelivr.
-- Use `resolveAsset(puck?.metadata, value)` from `@sudajs/theme-engine/runtime` before rendering user-selected media fields.
-- Scope theme CSS with the generated theme key classes. Avoid global resets that could affect the host editor or other themes.
-- Preview screenshots are required at `assets/preview/desktop.png`, `assets/preview/tablet.png`, and `assets/preview/mobile.png`; run `suda theme capture` to generate them.
-- Customize `vite.config.ts`, `postcss.config.mjs`, and `src/styles.css` only when the theme needs it.
-
-## Field authoring rules
-
-Use the most specific field type available. A generic `text` field may pass typecheck, but it is wrong when a semantic Suda field exists.
-
-- Always use `url` for links and routes, including anchors, `mailto:` links, and external URLs. Do not use `text` for href-like props.
-- Use `image` for images, `video` for videos, and `media` only when the same prop intentionally accepts mixed media.
-- Use `color` for color values, `icon` for icon names, `range` for bounded numbers, and `spacing` for spacing tokens.
-- Use `select` for typography choices and `array`/`object` fields for navigation lists.
-- Use `select` or `radio` for fixed choices. Keep option values stable, short, and serializable.
-- Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
-- Use `textarea` for multi-sentence copy. Use `text` only for short labels, headings, slugs, names, or plain strings that are not URLs, media, colors, icons, typography choices, or navigation lists.
-- Use `t(...)` for every editor-facing `label` in components, fields, nested
-  `arrayFields` / `object.fields`, local blocks, and option lists. Add matching
-  keys to `src/locales/en.json` at the same time.
-- For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
-- Use `visibleIf: ({ props }, { fields }) => boolean` for synchronous field visibility that depends on sibling props or resolved fields. Keep it pure and fast.
-- Use Puck `resolveFields` only for heavier dynamic field changes that cannot be expressed with `visibleIf`.
-- Add field-level `ai.instructions`, `ai.required`, `ai.exclude`, `ai.stream`, or `ai.bind` when a prop needs generation guidance beyond its label and type. Use `ai.stream: false` for atomic values such as URLs that should not stream partially.
-
-## Contact form contract
-
-Themes must render the host-provided contact form from `metadata.contactForm`
-when they offer a contact section. The platform owns field metadata,
-validation, submissions, notifications, webhooks, permissions, and limits; the
-theme owns the public UI only.
-
-- Read the form through `getContactForm(puck?.metadata)` from
-  `@sudajs/theme-engine/runtime`.
-- `suda theme dev` passes a default contact form through `metadata.contactForm`
-  so contact sections can be developed and previewed locally without a project.
-- If there is no valid, enabled form configuration, render nothing for the form
-  area; do not show a public "contact form unavailable" fallback panel.
-- Style all five supported field types: `text`, `textarea`, `checkbox`,
-  `radio`, and `select`.
-- Style labels, inputs, submit button, success state, validation errors, and
-  responsive layout in the theme's visual language.
-- Only render placeholders supplied by the form setting. Do not invent default
-  placeholder text for any field type, including the empty option in `select`.
-- Submit to `contactForm.endpoint` with the field values; never hardcode
-  notification channels, webhook URLs, ICP records, or white-label branding in
-  the contact section.
-- Include hidden platform fields, including the honeypot field
-  `name={contactForm.honeypotField}`, as bare `<input type="hidden" />`
-  elements. Do not wrap any hidden field in an element, label, layout row, grid
-  item, or visual field component; future hidden tokens must follow the same
-  rule so they cannot disturb the theme's form layout.
-- Keep contact form layout accessible: every field has a label, keyboard focus
-  is visible, checkbox/radio options are grouped clearly, and error messages
-  are readable on mobile.
-
-## AI metadata
-
-Every page component and layout component must declare useful `ai.instructions`. Missing component-level instructions fail `suda theme check` and block publish.
-
-Good component instructions explain:
-
-- Purpose: what content or business role the component serves.
-- Use when / avoid when: how AI should choose this component instead of a similar one.
-- Placement: where it normally belongs in a page.
-- Frequency: whether it should appear once, multiple times, or only near another section.
-- Composition: required neighboring content or local blocks, when relevant.
-
-- For icons, expose props with `{ type: "icon" }`, type values as `SudaIconName`, and render them with `SudaIcon` from `@sudajs/theme-engine/icons`. Store canonical Lucide names such as `"rocket"` or `"mouse-pointer-click"` (not `"lucide-rocket"`), or namespaced Simple Icons brand names such as `"simple-icons:github"`. Do not keep theme-local icon maps, emoji/icon switch statements, or custom SVG icon registries unless the theme truly needs a bespoke graphic.
-- Add optional field-level `ai.instructions`, `ai.required`, or `ai.exclude` when a prop needs generation guidance beyond its label and type.
-- Use `ai.exclude: true` only for structural or editor-only components, and still provide instructions explaining why AI must not generate them. `PageOutlet` is the standard example.
-
-## Block slot authoring rules
-
-Use `blockSlots` when a section owns controlled local content such as hero
-actions, pricing cards, feature rows, stats, timeline items, or contact
-methods. Keep ordinary section props in `fields`.
-
-- Type the slot prop as Puck `Slot` and declare `blockSlots` with the same prop key.
-- Do not create a native `fields.<key>.type = "slot"` in page components.
-- Define local block kinds under `blockSlots.<slotName>.blocks`.
-- Give every local block `label`, useful fields, `defaultProps`, `render`, and
-  optional `ai.instructions` when the block needs generation guidance.
-- Keep local blocks specific to the owning section. They are not reusable global page components.
-- Do not add nested `blockSlots` to local blocks. Block slots are one level deep in the theme authoring API.
-- Do not put the slot prop in the host component's `defaultProps`; use `defaultBlocks` on the slot instead.
-- Do not hand-write `id` in local block `defaultProps`, `defaultBlocks[].props`, or starter page nested block props. The editor/runtime owns block ids.
-- In authored page data, starter pages, CMS templates, and AI examples, nested block-slot items must use the short local block kind as `type`, exactly matching a key in `blockSlots.<slotName>.blocks`. Never write internal local block types such as `__suda_local_block__/Hero/actions/button`; `@sudajs/theme-engine` generates those only for Puck internals.
-
-Example:
+This repository is a standalone Vite + React + Tailwind Suda theme generated by
+`suda theme init`. Build a complete, publishable theme with theme-specific
+sections, realistic templates, scoped styling, assets, and AI metadata.
+
+## Required reading
+
+Read this file before every task. Then read the matching focused guide before
+editing that area. These guides are part of the contract, not optional
+background:
+
+| Task                                                                                                          | Required guide                               |
+| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Sections, fields, defaults, menus, icons, AI metadata, or block slots                                         | `docs/agent-guides/component-authoring.md`   |
+| CMS, posts, starter pages, page data, or locales                                                              | `docs/agent-guides/templates-and-locales.md` |
+| Header, Footer, PageOutlet, sticky/fixed UI, transparent navigation, carousel, editor CSS, or client behavior | `docs/agent-guides/editor-compatibility.md`  |
+| Theme contract, layout, design tokens, CSS, assets, or contact forms                                          | `docs/agent-guides/design-and-runtime.md`    |
+
+Read every guide that applies when a change crosses concerns. Follow the
+generated types and installed package APIs when they are more specific than an
+example. Do not guess contracts from memory.
+
+## Non-negotiable rules
+
+- Keep `renderMode: "ssr"` and export a complete `ThemeModule` from
+  `src/index.tsx`: `manifest`, `pageConfig`, `layoutConfig`, `defaultLayout`,
+  `starterPages`, and `cmsTemplates`.
+- Keep page sections in `pageConfig` and shared chrome in `layoutConfig`.
+  Header and Footer render exactly once from the layout, with `PageOutlet`
+  between them.
+- Create theme-specific sections. Do not register `createEngineComponents()`,
+  `createBaseBlocks()`, or `createContainers()` as the theme's page sections.
+  Suda adds its generic content blocks separately.
+- Keep persisted props JSON-serializable. Never store functions, React nodes,
+  class instances, media database ids, or absolute local filesystem paths.
+- All normal field and prop defaults belong only in component `defaultProps`.
+  Never invent display defaults inside render code with `||`, `??`, a ternary,
+  a default function parameter, or a destructuring default.
+- Every editor-facing label must use `t(...)` and exist in
+  `src/locales/en.json`. Public content and `defaultProps` must not use the
+  editor translation helper.
+- Every page and layout component must declare useful `ai.instructions`.
+- Top-level page data types must be public keys from `pageConfig.components`,
+  and every top-level item must have a stable `props.id`.
+- Block-slot items use short local kinds such as `"button"`; never author
+  `__suda_local_block__/...` types or local-block ids.
+- Theme assets use `themeAsset("assets/...")` in authored data and
+  `resolveAsset(...)` when rendering editable media. Never hand-write published
+  theme asset URLs.
+- Keep theme CSS scoped. Do not use global resets or vendor edits that can
+  damage the Puck editor.
+- Do not edit `dist/`; regenerate it through the build.
+
+## Project structure
+
+Keep every page section in its own `.tsx` file. Do not collect multiple section
+configs and render implementations in a single `sections.tsx`, `config.tsx`, or
+other large module. Use kebab-case names and a small `src/sections/index.ts` to
+export configs or assemble the registry.
+
+```txt
+src/
+  sections/
+    hero.tsx
+    booking.tsx
+    values.tsx
+    faq-directory.tsx
+    review-marquee.tsx
+    index.ts
+```
+
+Keep section-specific prop types and tightly coupled helpers with their section.
+Extract shared code only when multiple sections genuinely reuse it.
+
+## Component fundamentals
+
+- Name public component keys with concise PascalCase visitor-facing patterns,
+  such as `HeroImage`, `FeatureCards`, or `TestimonialsCarousel`. Avoid theme
+  names and filler suffixes such as `Section`, `Component`, `New`, or `Custom`.
+- Prefer semantic variant names. Use numbered variants only when the variants
+  truly share a purpose and no concise name describes the difference.
+- Keep `fields`, TypeScript props, `defaultProps`, and `render` aligned. Every
+  normal field needs a sensible serializable default.
+- Use the most specific field: `url`, `image`, `video`, `media`, `icon`,
+  `color`, `range`, `spacing`, `posts`, `select`, `radio`, `array`, or `object`.
+  Do not model structured or semantic values as generic text.
+- Use `visibleIf` for synchronous sibling-dependent visibility. Use
+  `resolveFields` only when `visibleIf` cannot express the behavior.
+- Expose a `columns` prop for multi-column grids and lists.
+- Use ordinary fields for scalar and structured props. Use `blockSlots` only
+  for controlled nested items editors and AI may add, remove, or reorder.
+- Native Puck slots are reserved for layout/container primitives. Page sections
+  must not declare native `slot` fields, legacy DropZones, or `zones`.
+
+Default ownership is strict:
 
 ```tsx
-import type { Slot } from "@puckeditor/core";
-import type { SudaComponentConfig } from "@sudajs/theme-engine";
-
-import { t } from "./i18n.js";
-
-type HeroProps = {
-  title?: string;
-  actions?: Slot;
-};
-
-export const Hero: SudaComponentConfig<HeroProps> = {
-  label: t("sections.hero.label"),
-  ai: {
-    instructions:
-      "Primary page introduction for landing pages. Use once near the top with one or two local action blocks.",
-  },
-  fields: {
-    title: { type: "text", label: t("sections.hero.fields.title") },
-  },
-  blockSlots: {
-    actions: {
-      label: t("sections.hero.blocks.actions"),
-      blocks: {
-        button: {
-          label: t("sections.hero.blocks.button"),
-          ai: {
-            instructions:
-              "Primary or secondary hero action. Use one or two buttons with clear labels and valid links.",
-          },
-          fields: {
-            label: { type: "text", label: t("sections.hero.blocks.buttonLabel") },
-            href: { type: "url", label: t("sections.hero.blocks.buttonHref") },
-          },
-          defaultProps: {
-            label: "Get started",
-            href: "/contact",
-          },
-          render: ({ label, href }) => <a href={href}>{label}</a>,
-        },
-      },
-      defaultBlocks: [{ kind: "button" }],
-    },
-  },
-  defaultProps: {
-    title: "Build with SudaCloud",
-  },
-  render: ({ title, actions: Actions }) => (
-    <section>
-      <h1>{title}</h1>
-      <Actions />
-    </section>
-  ),
+// Wrong: render invents content.
+<div>{val || "defaultValue"}</div>;
+
+// Correct: defaultProps owns the default.
+export const Example: SudaComponentConfig<ExampleProps> = {
+  fields: { val: { type: "text", label: t("sections.example.fields.val") } },
+  defaultProps: { val: "defaultValue" },
+  render: ({ val }) => <div>{val}</div>,
 };
 ```
 
-Starter page data should use the public host component type and a standard array on the block-slot prop. Use local block `kind` values as nested `type` values; for the example above, `actions[].type` can only be `"button"`.
-
-```ts
-{
-  type: "Hero",
-  props: {
-    id: "Hero-1",
-    title: "Welcome",
-    actions: [
-      {
-        type: "button",
-        props: {
-          label: "Contact us",
-          href: "/contact",
-        },
-      },
-    ],
-  },
-}
-```
-
-## Starter pages
-
-- Provide realistic starter pages in `src/templates.ts`; do not ship placeholder-only pages.
-- Every starter page is Puck `Data` with `root: { props: {} }` and `content: [...]`.
-- Each top-level component instance in starter page `content` must include a stable `props.id`.
-- Use only components registered in `pageConfig.components` for top-level page content.
-- For any `blockSlots` prop, use only short local block kinds as nested `type` values, never `__suda_local_block__/...` internal types.
-- Do not put local block `id` values in starter pages. Only top-level page components need `props.id`.
-- Where practical, wrap authored data with `defineSudaPageData(pageConfig, data)` so TypeScript checks top-level component keys and block-slot nested `type` values.
-- Match starter page content to the theme's intended audience and category. The home page should show the theme's best composition, not just every component in order.
-- Use `themeAsset("assets/...")` for bundled starter media; never hand-write generated theme asset paths.
-
-## Commands
+Conditional rendering is valid when absence intentionally removes optional UI;
+it must not substitute placeholder copy, labels, links, icons, or menu items.
+
+## Icons
+
+- Fixed icons are acceptable for interaction and UI-state semantics such as
+  menu, close, previous/next, expand/collapse, and loading controls.
+- Content icons such as feature, service, contact-method, and social-brand
+  icons are props. Expose `{ type: "icon" }`, type values as `SudaIconName`,
+  set initial selections in `defaultProps`, and render them with `SudaIcon` from
+  `@sudajs/theme-engine/icons`. Do not hardcode content icons in `render`.
+- Use canonical Lucide names such as `"rocket"` and namespaced Simple Icons
+  names such as `"simple-icons:github"`. The theme engine supports both; do not
+  add another icon library unless neither can represent a required icon.
+
+## Page data fundamentals
+
+- Wrap hand-authored page data with `defineSudaPageData(pageConfig, data)` when
+  practical so TypeScript checks public component keys and block-slot kinds.
+- Starter pages live in `src/templates.ts`, use `root: { props: {} }`, contain
+  realistic content, and include one home page with `isHome: true`.
+- Provide exactly the four CMS templates `posts`, `post`, `tags`, and `tag` as
+  `{ title, data }` entries. Do not invent CMS template variants.
+- CMS-only main sections read `getCmsContent(puck?.metadata)`. Ordinary page
+  post sections use one top-level `posts` field and `getPostResource(...)`.
+- Starter page slugs preview at root-like routes such as `/index` and
+  `/contact-us`; never use `/pages/...` as a preview prefix.
+
+## Editor and runtime fundamentals
+
+- Components return one stable semantic real DOM root when positioning,
+  selection, spacing, or background matters. Do not rely on a Fragment or
+  `display: contents` for such roots.
+- Derive editor state from `puck?.metadata?.isEditor === true`, expose a stable
+  theme-root marker, and scope editor fixes below it.
+- Puck may place `data-puck-component` and inline `position: relative` on the
+  component's actual root. Account for that before implementing sticky, fixed,
+  absolute, overlap, or transparent navigation behavior.
+- Do not restore pointer events globally in edit mode. Test interactions in
+  editor preview and on the public site.
+- Browser setup belongs in an optional `clientHooks` export from
+  `src/client.ts`. Do not create `src/runtime.client.ts(x)`; the CLI owns the
+  generated runtime.
+
+## Design and assets
+
+- Define one editable design system in `sourceManifest.designSystem`, expose it
+  at the layout root, resolve it once there, and render components through the
+  resulting `--suda-*` CSS variables.
+- Tailwind token mappings use `@theme inline`. Hand-written CSS consumes
+  `--suda-*` variables directly, not `--color-*` or `--radius-*` aliases.
+- Keep typography, spacing, containers, buttons, cards, forms, and media frames
+  consistent across ordinary sections, CMS sections, and starter pages.
+- Theme-local assets live under top-level `assets/`. Required preview images are
+  `assets/preview/desktop.png`, `tablet.png`, and `mobile.png`.
+- Contact sections render host-provided `metadata.contactForm`; the platform
+  owns configuration, validation, submission, notifications, and limits.
+
+## Workflow
+
+Before editing:
+
+1. Read the required focused guide(s).
+2. Inspect the existing source, generated types, and established theme helpers.
+3. Identify every affected contract: fields/defaults/render, locales, page data,
+   assets, editor behavior, and templates.
+
+When adding or changing a section:
+
+1. Define serializable props in its dedicated `.tsx` file.
+2. Add `label`, useful `ai.instructions`, typed `fields`, optional
+   `blockSlots`, `defaultProps`, and `render`.
+3. Add all editor label keys to `src/locales/en.json`.
+4. Register it in `pageConfig` and the appropriate translated category.
+5. Add realistic usage to starter pages or CMS templates where appropriate.
+6. Verify public rendering plus editor desktop, tablet, and mobile behavior.
+
+Before handoff:
 
 ```bash
-pnpm install
 pnpm lint
 pnpm typecheck
-pnpm format
-pnpm dev       # Vite-powered local preview
-pnpm build     # Vite build + Suda artifact finalize + AI metadata check
+pnpm build
 pnpm validate
 suda theme check
 ```
 
-Before publishing or handing off a finished theme, run `pnpm typecheck`, `pnpm lint`, `pnpm build`, and `pnpm validate`. Use `suda theme check` when iterating on AI metadata.
+Run `suda theme capture` when visuals change. Do not use removed skip flags or
+bypass build, validation, AI metadata, locale, or screenshot checks.