@gradial/aci 0.1.52-rc.8 → 0.1.52

package/templates/common/.agents/skills/authoring/SKILL.md

@@ -14,7 +14,9 @@ description: Author content and build components for ACI sites. Use when creatin
 | `.content/config/site.json` | Site metadata, SEO defaults |
 | `.content/config/robots.txt` | Authored crawler rules; publish bundles this file verbatim as `assets/robots.txt` when present |
 | `.content/pages/{slug}/_index.json` | Page content (slug maps to route) |
-| `.content/fragments/{id}/_index.json` | Shared fragments (navbar, footer — used by layout defaults) |
+| `.content/fragments/{id}/_index.json` | Shared fragments (navbar, footer — usable by template defaults) |
+| `.content/templates/{name}.json` | Page templates and global policies: the composition guardrails every page and variant must satisfy (see Page Templates) |
+| `.content/overlays/{dimension}/{value}/pages/{slug}/_index.json` | Page overlays: keyed patches that personalize a page for an audience, locale, or experiment arm |
 | `.aci/schemas/page.schema.json` | Page validation schema (auto-generated from contracts) |
 
 ### Page Structure
@@ -26,20 +28,35 @@ Every page JSON requires:
   "$type": "page",
   "id": "unique-page-id",
   "status": "published",
-  "layout": "default",
+  "template": "standard",
   "metadata": {
     "title": "Page Title",
     "description": "Meta description",
     "sitemap": { "visible": true }
   },
   "regions": {
-    "main": []
+    "main": [
+      {
+        "$type": "component",
+        "id": "page-hero",
+        "component": "home_hero",
+        "props": {
+          "eyebrow": "Eyebrow",
+          "headline": "Page headline",
+          "description": "One sentence that says what this page is for.",
+          "ctaLabel": "Back to home",
+          "ctaHref": "/"
+        }
+      }
+    ]
   }
 }
 ```
 
 Base page fields are SDK-owned and included in the generated
-`.aci/schemas/page.schema.json`.
+`.aci/schemas/page.schema.json`. `template` names the page template that
+governs an interior page (see Page Templates); pages under a route a
+template covers omit it.
 
 #### Sitemap visibility
 
@@ -67,10 +84,9 @@ the intent clear in content).
 
 This does **not** add a `noindex` meta tag — it only controls sitemap inclusion.
 
-The `layout` field is required — it determines which slots the page can
-fill. The `default` layout provides `header`/`main`/`footer` slots with
-fragment defaults for chrome (navbar, footer). Pages typically only fill
-`regions.main`; chrome comes from the layout's fragment defaults.
+The bound template determines which regions the page can fill. A template may
+provide `header` and `footer` fragment defaults, so pages typically author only
+`regions.main`. There is no authored `layout` field or code layout registry.
 
 ### Route Mapping
 
@@ -78,19 +94,173 @@ Pages map to URL routes by their folder path under `/pages/`:
 
 | Page Path | Route |
 |-----------|-------|
-| `/pages/home/_index.json` | `/` |
+| `/pages/_index.json` | `/` |
 | `/pages/about/_index.json` | `/about` |
 | `/pages/products/_index.json` | `/products` |
 | `/pages/products/shoes/_index.json` | `/products/shoes` |
 
-The `home` slug is special-cased to route `/`. All other slugs map directly.
+The empty slug is the site root. Every named folder maps directly, including
+`/pages/home/_index.json` at `/home`.
+
+### Page Templates and Global Policies
+
+Composition guardrails live in `.content/templates/<name>.json`. They are
+content, owned by whoever holds policy authority on `/templates/`, and every
+page **and every personalized variant of it** must satisfy them before a
+release can be published. Read the governing template before composing a
+page: a write that breaks a guardrail is refused when you make it, with 422
+`<lane>.template_invalid` and a `template/*` diagnostic naming the exact
+block.
+
+**How to read a refusal.** Each entry under `details.diagnostics` carries the
+rule id, the document and JSON pointer to fix (`documentRef`, `jsonPointer`),
+and in `details`: `template` (the governing document), `variant` (empty for
+the base page), `expected` and `found`, and `trigger` — which paths of your
+own batch caused the check. The list is capped at 100; `details.diagnosticCount`
+is the real total. You are refused only for what your batch breaks: a page
+that already failed before your write never blocks you, and fixing it is
+someone with authority over `/pages/`.
+
+**Check before you write.** `POST /v1/content/validate` takes the same
+`changes` body as a branch write and returns the same verdict without
+committing anything — use it to try a composition or a template edit.
+`aci validate` runs the same evaluator over a local tree, and `POST
+/v1/branches/{name}/coherence/check` over a branch. A promote to `live` is
+judged the same way against `live`: a page must travel with the template it
+needs, so widen the promote set when `template/not-found` comes back.
+
+**Publish is still the guarantee.** A write is judged for the variant its own
+path names. Two overlays that are each valid but violate together under a
+wider variant are caught by the release preflight, which refuses the publish
+with `publish.template_invalid` naming that variant; fix either overlay.
+
+Two kinds of document, told apart by `$type`; the file stem is the name:
+
+| Document | Kind | What it says |
+|----------|------|--------------|
+| `site.json` | `globalPolicy` | Applies to every page: `counts` (per-component `min`/`max` over the effective page, including nested blocks and rendered fragment placements). A `pageTemplate` may carry `counts` too, scoped to the pages it governs. |
+| `home.json` | `pageTemplate` | Covers `routes: ["/"]`: `main` is exactly home_hero, feature_grid, personalization_choice, stats_bar, container, in that order. |
+| `standard.json` | `pageTemplate` | Declared by interior pages: `main` starts with a home_hero, then `closed: false` admits anything after it. |
+| `error.json` | `pageTemplate` | Covers `/404` and `/error`: a single home_hero. |
+
+**Which template governs a page.** A page under a route a template's
+`routes` covers is governed by that template and needs no declaration
+(`/`, `/404`, `/error` in the starter). Every other page declares its
+template with a root `"template": "<name>"` (the starter's `/about`
+declares `standard`). An undeclared, uncovered page produces `template/unbound`
+even without a global policy. Write/probe and promote gates refuse newly
+introduced violations; publish refuses every unbound page. Route patterns are public
+routes; a trailing `/*` covers every deeper route. A declaration on a
+covered page must name the covering template.
+
+**Steps.** A region rule is an ordered `sequence` of steps. Each step names
+the inline `component`(s) it accepts, or the shared `fragment` ids
+(`"fragment": ["faq-block"]`, or `"fragment": "*"` for any fragment no other
+step names), or both, with `min`/`max` occurrences (default exactly one).
+A step listing several components accepts any of them in any order up to
+`max`. `closed: true` (the default) means nothing may follow the last step.
+Template steps must be unambiguous: two adjacent optional steps may not
+accept the same component. Only the keys shown here are accepted — a
+misspelled key is refused as `template/invalid`, so a guardrail can never
+switch itself off silently. A step may declare `"lock": "structure"`: variants
+may change props, but must preserve the complete step assignment (ids,
+components, order, fragment references, and nested block structure). Nested
+blocks inside each locked top-level block need non-empty, distinct ids. The
+comparison baseline includes the default-locale overlay; the home hero is locked.
+
+A template that exercises the grammar, for an interior article page that
+declares it with `"template": "article"`:
+
+```json
+{
+  "$type": "pageTemplate",
+  "name": "article",
+  "description": "A hero, one to six body sections, then an optional shared promo.",
+  "regions": [
+    {
+      "name": "main",
+      "closed": false,
+      "sequence": [
+        { "id": "hero", "component": "home_hero" },
+        { "id": "body", "component": ["feature_grid", "stats_bar", "container"], "min": 1, "max": 6 },
+        { "id": "promo", "fragment": "*", "min": 0 }
+      ]
+    }
+  ],
+  "counts": [{ "component": "stats_bar", "max": 1 }]
+}
+```
+
+**Shared fragments.** Sequence steps match a reference by its fragment id.
+Counts include its rendered component tree once per placement. A structure lock
+also protects that tree: fragment overlays may personalize props but cannot
+swap components or rendered block identities. Fragment edits and overlays
+revalidate referencing pages. Refusals name the source fragment or overlay and
+the page placement (`details.page`, `referencePointer`).
+
+**Defaults count when rendered.** Template default fragments fill an absent or
+empty region. They participate in sequence rules, counts, structure locks, and
+component validation just like explicit placements. A populated page region
+replaces its defaults; the unused defaults are not counted.
+
+**Nested rules belong to component contracts today.** Templates match the
+region's top-level sequence; they do not define a grammar inside a container's
+props. Give a page type its own contract, for example `blog_body` with
+`content: blockRefArray([featureCardContract, statsBarContract])`, and bind it to
+the existing `ContainerSection` renderer. A blog template step names `blog_body`;
+the compiled component contract limits its nested children. Register that
+contract in both the compile-time contracts list and runtime registry. Compile
+and publish enforce component schemas in addition to template rules; the
+template evaluator itself does not read contracts. Never hand-edit `/patterns/`.
+Nested step grammars remain deferred; use this contract pattern for allowed
+child types, not for arbitrary nested ordering rules.
+
+**Overlays keep the page's shape.** A page overlay personalizes a page with
+keyed patches — an object under `regions.<region>` keyed by block `id`
+that changes props:
+
+```json
+{
+  "$type": "page-overlay",
+  "regions": {
+    "main": {
+      "personalization-choice": {
+        "props": { "title": "Red preference active" }
+      }
+    }
+  }
+}
+```
+
+An overlay may not carry a root `template` key (the binding comes from
+route coverage and the base page; `template/binding-immutable`). Changing a
+block's `component` or replacing a region with an array is legal only when
+the result still satisfies the template — a swap the template does not
+allow is refused naming the overlay and the variant.
+
+**Reading a refusal.** Every `template/*` diagnostic carries `documentRef`
+and `jsonPointer` (the overlay that patched the failing block, else the
+page, and the block), and `details` with the governing `template`, its
+`description`, the `step`, `expected` (the tokens the step accepts, as
+`component:<name>` / `fragment:<id>`), `found`, `resolvedPointer` (the
+location in the composed variant), `variant` (the dimension key, empty for
+the base), and `overlays` (every overlay the variant applied, in order). `template/sequence` is a block in
+the wrong place; `template/too-few` is a missing mandatory step;
+`template/count` is a policy bound exceeded; `template/mismatch`,
+`template/unbound`, and `template/not-found` are binding problems.
+`template/locked-changed` means a locked step changed structure: preserve ids
+and use a keyed props patch. `template/locked-missing` identifies a removed
+locked token. `template/base-invalid` requires repairing the base page before
+its variants can pass release validation. Fix the
+page or overlay the diagnostic names, or, with policy authority, loosen the
+template and republish.
 
 ### Content Rules
 
 - Never hard-code content inside component code. All content lives in JSON.
 - Migrate copy verbatim. Do not paraphrase, summarize, or invent.
 - Global elements (header, footer, nav) are CMS-managed fragments in
-  `.content/fragments/`, rendered via layout fragment defaults. They are
+  `.content/fragments/`, rendered via template fragment defaults. They are
   not hardcoded in framework layout files.
 - Use `$ref:` prefixes for cross-references between content documents.
 
@@ -259,7 +429,7 @@ Sites bind their error pages in `site.json` via `errorPages`:
 
 - Each binding is a route path resolving to an **ordinary content page**
   (`.content/pages/404/_index.json`, `.content/pages/error/_index.json`) —
-  authored with normal layouts and components like any other page.
+  authored with normal templates and components like any other page.
   `notFound` serves unknown routes with HTTP 404; `catchAll` serves
   application errors (500-class).
 - Error pages stay out of discovery: set `metadata.sitemap.visible: false`
@@ -486,7 +656,7 @@ framework.
 #### 5. Add content
 
 ```json
-// .content/pages/home/_index.json (inside regions.main)
+// .content/pages/_index.json (inside regions.main)
 {
   "$type": "component",
   "id": "features",
@@ -551,39 +721,21 @@ type Props = ContentProps & { className?: string };
    runtime components — they are the wiring point.
 4. Use `@gradial/aci` as the SDK package. Do not use `@baremetal/runtime`.
 
-### Layout Contracts
+### Template Composition
 
-Layouts define page-level slot structure and optional fragment defaults
-for chrome. Use `defineLayoutContract`, `slot()`, and `fragmentDefault()`
-from the SDK:
-
-```ts
-// src/cms/contracts/layouts/index.ts
-import { defineLayoutContract, slot, fragmentDefault } from '@gradial/aci';
-
-export default [
-  defineLayoutContract({
-    name: 'default',
-    slots: [
-      slot('header'),         // filled by fragment default
-      slot('main', true),     // filled by page regions (required)
-      slot('footer'),         // filled by fragment default
-    ],
-    defaults: {
-      header: fragmentDefault('navbar'),
-      footer: fragmentDefault('site-footer'),
-    },
-  }),
-];
-```
+Templates under `.content/templates/<name>.json` define ordered regions,
+placement policy, requiredness, and optional fragment defaults. They are the
+only authored page-composition contract; do not create a TypeScript layout
+contract or add `layoutRegistry` to `.aci.yaml`.
 
 Fragment content lives in `.content/fragments/{id}/_index.json` and retains
-the resource envelope `"$type": "fragment"` while declaring `component` +
-`props`. Chrome components (Header, Footer) are registered in the registry
+the resource envelope `"$type": "fragment"`; its `block` declares
+`"$type": "component"`, `component`, and `props`. Place a shared fragment in
+a page region with `"$fragment:<id>"` or use it as a template default. Chrome components (Header, Footer) are registered in the registry
 alongside page components.
 
-The `layout` field in page JSON is **required** — there is no implicit
-default. Every page must declare which layout it uses.
+Bind each page with `template`, unless route configuration supplies the
+template binding.
 
 ## Component Tiers
 
@@ -693,7 +845,7 @@ slot configuration, nested dot paths, and runtime image rendering rules.
 
 Read `references/contracts.md` for the full contract file structure,
 `defineComponentContract` API, `.aci.yaml` config reference, plain
-layout contract objects, and contract barrel patterns.
+template documents and component contract barrel patterns.
 
 ## Deep Dive: Design System
 

package/templates/common/.agents/skills/authoring/references/block-registry.md

@@ -3,6 +3,21 @@
 The component registry maps contract names to runtime components. It is built
 using `createRegistry` from `@gradial/aci` with raw `[contract, component]` tuples.
 
+Every registered component must extend `RootIdentityProps` (exported from
+`@gradial/aci`) and spread the rest of its props onto its root element. The
+renderer passes `data-aci-block` and `data-aci-component` to every block so
+analytics can join events to content; a component that does not declare the
+type fails `createRegistry` typecheck with
+`<id>: props type must extend RootIdentityProps from @gradial/aci`, and one
+that does not spread fails the `rootIdentity` conformance check under
+`npm test`.
+
+```tsx
+export function StatsBar({ stats = [], ...root }: ContentProps & RootIdentityProps) {
+  return <section {...root} className="…">…</section>;
+}
+```
+
 The tuple form provides **type-level validation** — the component must accept
 at least the props derived from the contract's Zod schema. If you register a
 component with the wrong prop type, TypeScript will fail at the call site.
@@ -51,7 +66,7 @@ the compiler invokes this route with an isolated render input; hosted CMS
 traffic is served from the resulting immutable HTML and does not enter Next.
 
 Chrome (Header/Footer) is **not** in `layout.tsx`. It is CMS-managed via
-layout fragment defaults. The `layout.tsx` file is minimal and includes
+template fragment defaults. The `layout.tsx` file is minimal and includes
 `<DevRefresh />`:
 
 ```tsx
@@ -83,8 +98,9 @@ export const generateMetadata = page.generateMetadata;
 export default page.default;
 ```
 
-`createPage` loads the page's layout, resolves all slots (filling from page
-regions or layout fragment defaults), and renders blocks via the registry.
+`createPage` loads the compiler's template-derived render envelope, resolves
+all regions (filling from page regions or template fragment defaults), and
+renders blocks via the registry.
 The `main` slot is wrapped in `<main>`; other slots render as fragments.
 
 ## Custom Server Composition

package/templates/common/.agents/skills/authoring/references/contracts.md

@@ -59,43 +59,23 @@ import { buttonContract } from './button.contract';
 export default [heroContract, buttonContract];
 ```
 
-## Layout Contract API
+## Template Composition
 
-Use `defineLayoutContract`, `slot()`, and `fragmentDefault()` from the SDK:
-
-```ts
-// src/cms/contracts/layouts/index.ts
-import { defineLayoutContract, slot, fragmentDefault } from '@gradial/aci';
-
-export default [
-  defineLayoutContract({
-    name: 'marketing',
-    slots: [
-      slot('header'),
-      slot('main', true),
-      slot('footer'),
-    ],
-    defaults: {
-      header: fragmentDefault('site-header'),
-      footer: fragmentDefault('site-footer'),
-    },
-  }),
-];
-```
-
-Content pages reference layouts by name:
+Templates under `.content/templates/<name>.json` are the sole authored
+page-composition contract. Content pages reference templates by name:
 
 ```json
 {
-  "layout": "marketing",
+  "template": "marketing",
   "regions": {
     "main": [...]
   }
 }
 ```
 
-The `header` and `footer` slots are filled automatically by fragment defaults
-when the page doesn't provide blocks for them.
+Templates define ordered regions, placement policy, requiredness, and defaults.
+The `header` and `footer` regions can be filled automatically by fragment
+defaults when the page does not provide blocks for them.
 
 ## Multiple Runtime Mappings
 
@@ -119,7 +99,6 @@ source:
   publicDir: "public"  # Astro only
 
 componentRegistry: ./src/cms/contracts/components/index.ts
-layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
 # Optional for custom renderers; Astro/Next use framework conventions.
 # rendererEntry: ./src/cms/renderer.ts
@@ -145,7 +124,6 @@ rendererProtocol: stdio-json
 | `source.outDir` | Build output directory (Astro) |
 | `source.publicDir` | Public assets directory (Astro) |
 | `componentRegistry` | Path to component contract barrel |
-| `layoutRegistry` | Path to layout contract barrel |
 | `rendererEntry` | Optional renderer entry override; omit for framework conventions |
 | `routes.cmsManaged` | Catch-all route pattern for CMS pages |
 | `rendererProtocol` | Renderer communication protocol |
@@ -159,7 +137,8 @@ rendererProtocol: stdio-json
 
 ### Rules
 
-- `componentRegistry` and `layoutRegistry` point to contract-only modules.
+- `componentRegistry` points to a contract-only module. Do not add
+  `layoutRegistry`; page composition lives in `.content/templates`.
 - No secrets in `.aci.yaml`, docs, fixtures, or generated files.
 - The `cmsManaged` route pattern should match the filesystem: use `/[[...slug]]`
   (optional catch-all) for Next.js repos so local `/` arrives with an empty

package/templates/common/.agents/skills/authoring/references/repo-structure.md

@@ -27,8 +27,11 @@ tsconfig.json                    TypeScript config
     home/_index.json             Homepage (route /)
     about/_index.json            About page (route /about) (starter content only)
   fragments/
-    navbar/_index.json           Navbar fragment (layout default)
-    site-footer/_index.json      Footer fragment (layout default)
+    navbar/_index.json           Navbar fragment (template default)
+    site-footer/_index.json      Footer fragment (template default)
+  templates/
+    home.json                    Page composition contract
+    standard.json                Page composition contract
 src/
   cms/
     contracts/
@@ -42,8 +45,6 @@ src/
         siteNavigation.contract.ts  Site navigation contract (starter content only)
         siteFooter.contract.ts   Site footer contract (starter content only)
         index.ts                 Component contract barrel
-      layouts/
-        index.ts                 Layout contract barrel (plain objects)
     registry.ts                  Component registry — createRegistry([contract, component] tuples)
   components/
     elements/                    Small reusable components + atomic content blocks

package/templates/common/.agents/skills/authoring/references/sdk-server-functions.md

@@ -30,8 +30,8 @@ export const generateMetadata = page.generateMetadata;
 export default page.default;
 ```
 
-`createPage` loads the page's layout, resolves all slots (filling from
-page regions or layout fragment defaults), and renders blocks via the
+`createPage` loads the compiler's template-derived render envelope, resolves
+all regions (filling from page regions or template fragment defaults), and renders blocks via the
 registry. The `main` slot is wrapped in `<main>`; other slots render as
 fragments.
 
@@ -177,7 +177,7 @@ and shared across all releases.
 
 The root layout is minimal: import CSS, optionally load site config, and
 include `<DevRefresh />`. Chrome (Header/Footer) is **not** in layout.tsx —
-it is CMS-managed via layout fragment defaults and rendered by `createPage`.
+it is CMS-managed via template fragment defaults and rendered by `createPage`.
 
 ```tsx
 import { DevRefresh, getSiteConfig } from '@gradial/aci/next';