@gradial/aci 0.1.52-rc.8 → 0.1.52

package/src/cli/compile-registry.mjs

@@ -32,13 +32,15 @@ if (isMainModule()) {
 }
 
 async function compileRegistry(options) {
-  const required = ['components', 'layouts', 'output'];
+  if (options.layouts) {
+    throw new Error('--layouts is retired; author page composition under /templates instead');
+  }
+  const required = ['components', 'output'];
   for (const key of required) {
     if (!options[key]) throw new Error(`missing --${key}`);
   }
 
   const components = await loadDefaultArray(options.components, 'component registry');
-  const layouts = await loadDefaultArray(options.layouts, 'layout registry');
   const dataModels = options.data
     ? await loadDefaultArray(options.data, 'data model registry')
     : [];
@@ -68,9 +70,6 @@ async function compileRegistry(options) {
     });
   }
 
-  const seenLayouts = new Set();
-  const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
-
   const seenDataModels = new Set();
   const dataModelEntries = [];
   if (dataModels.length > 0) {
@@ -104,7 +103,6 @@ async function compileRegistry(options) {
     manifestVersion: '1',
     generatedAt: new Date().toISOString(),
     components: componentEntries,
-    layouts: layoutEntries,
     dataModels: dataModelEntries,
   };
   const registryPath = path.join(outDir, 'registry.json');
@@ -118,7 +116,7 @@ async function compileRegistry(options) {
 
 async function loadDefaultArray(modulePath, label) {
   const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
-  const value = mod.default ?? mod.registry ?? mod.components ?? mod.layouts ?? mod.dataModels;
+  const value = mod.default ?? mod.registry ?? mod.components ?? mod.dataModels;
   if (!Array.isArray(value)) throw new Error(`${label} must export an array`);
   return value;
 }
@@ -390,27 +388,6 @@ function unwrapSchema(schema) {
   return current;
 }
 
-function validateLayout(layout, index, seen) {
-  if (!layout || typeof layout !== 'object') throw new Error(`layouts[${index}] must be an object`);
-  if (!layout.name) throw new Error(`layouts[${index}].name is required`);
-  if (seen.has(layout.name)) throw new Error(`duplicate layout name ${layout.name}`);
-  seen.add(layout.name);
-  if (!Array.isArray(layout.slots)) throw new Error(`layouts[${index}].slots must be an array`);
-  const slots = [];
-  const seenSlots = new Set();
-  for (const [slotIndex, slot] of layout.slots.entries()) {
-    if (!slot?.name) throw new Error(`layouts[${index}].slots[${slotIndex}].name is required`);
-    if (seenSlots.has(slot.name)) throw new Error(`duplicate slot name ${slot.name} in layout ${layout.name}`);
-    seenSlots.add(slot.name);
-    slots.push({ name: slot.name, required: Boolean(slot.required) });
-  }
-  const entry = { name: layout.name, slots };
-  if (layout.defaults && typeof layout.defaults === 'object') {
-    entry.defaults = layout.defaults;
-  }
-  return entry;
-}
-
 function compileSchema(schema, name) {
   const toJSONSchema = z.toJSONSchema;
   if (typeof toJSONSchema !== 'function') {
@@ -505,13 +482,12 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
     $id: 'https://baremetal.local/schemas/page.schema.json',
     title: 'bare-metal Page',
     type: 'object',
-    required: ['$type', 'id', 'status', 'layout', 'metadata', 'regions'],
+    required: ['$type', 'id', 'status', 'metadata', 'regions'],
     additionalProperties: true,
     properties: {
       $type: { const: 'page' },
       id: { type: 'string', minLength: 1 },
       status: { type: 'string', minLength: 1 },
-      layout: { type: 'string', minLength: 1 },
       metadata: {
         type: 'object',
         required: ['title'],

package/src/cli/mintlify-render.mjs

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { loadCompiledMintlifySource, materializeMintlifySite } from '../../dist/mintlify/index.js';
+
+const [sourceArg, compiledArg, outputArg] = process.argv.slice(2);
+if (!sourceArg || !compiledArg || !outputArg) {
+  throw new Error('Mintlify renderer requires content, compiled, and output directories');
+}
+const source = await loadCompiledMintlifySource(path.resolve(sourceArg), path.resolve(compiledArg));
+await materializeMintlifySite({ ...source, outputDir: path.resolve(outputArg) });

package/src/types/block-ref.test.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 import { compileSchema } from '../compiler/zod-to-jsonschema.js';
 import { defineComponentContract } from '../define-component.js';
-import { blockRefArray } from './block-ref.js';
+import { blockRef, blockRefArray } from './block-ref.js';
 
 const childContract = defineComponentContract({
   id: 'child',
@@ -43,3 +43,18 @@ test('compiled block-reference schema exposes the component discriminator', () =
   assert.equal(compiled.items?.required?.includes('$type'), true);
   assert.equal(compiled.items?.additionalProperties, false);
 });
+
+
+test('block-reference contracts enforce allowed child IDs at runtime and in compiled schemas', () => {
+  const other = defineComponentContract({ id: 'other', props: z.object({}) });
+  const allowed = { $type: 'component', id: 'child-1', component: 'child', props: { label: 'Hello' } };
+  const disallowed = { ...allowed, component: 'button' };
+  for (const multiple of [false, true]) {
+    const schema = multiple ? blockRefArray([childContract, other]) : blockRef([childContract, other]);
+    assert.equal(schema.safeParse(multiple ? [allowed] : allowed).success, true);
+    assert.equal(schema.safeParse(multiple ? [disallowed] : disallowed).success, false, 'a nested component outside the contract must be refused');
+    const compiled = compileSchema(schema) as any;
+    const block = multiple ? compiled.items : compiled;
+    assert.deepEqual(block.properties.component.enum, ['child', 'other'], 'published JSON Schema must enforce the same finite child set');
+  }
+});

package/src/types/block-ref.ts

@@ -50,7 +50,7 @@ export function blockRefArray<const T extends readonly ComponentContract[]>(
   contracts: T,
 ): z.ZodArray<z.ZodType<BlockRefUnion<T>>> {
   return attachMeta(
-    z.array(blockRefBase) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
+    z.array(blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) })) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
     contracts.map((c) => c.id),
     true,
   );
@@ -60,7 +60,7 @@ export function blockRef<const T extends readonly ComponentContract[]>(
   contracts: T,
 ): z.ZodType<BlockRefUnion<T>> {
   return attachMeta(
-    blockRefBase as unknown as z.ZodType<BlockRefUnion<T>>,
+    blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) }) as unknown as z.ZodType<BlockRefUnion<T>>,
     contracts.map((c) => c.id),
     false,
   );

package/src/types/component.ts

@@ -23,6 +23,16 @@ export interface ComponentValidationIssue {
   severity?: 'error' | 'warning';
 }
 
+/**
+ * Root identity props the SDK renderers inject into every page and fragment
+ * block (sdk I-19, ADR 0051). A component spreads them onto its own root
+ * element; the starter conformance test fails a component that drops them.
+ */
+export interface RootIdentityProps {
+  'data-aci-block'?: string;
+  'data-aci-component'?: string;
+}
+
 export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
   id: TId;
   displayName?: string;

package/src/types/config.ts

@@ -9,7 +9,6 @@ export interface Config {
   };
   componentRegistry: string;
   dataRegistry?: string;
-  layoutRegistry: string;
   routes: RouteConfig;
   dam?: DAMConfig;
   externalDependencies?: ExternalDependency[];

package/src/types/index.ts

@@ -1,7 +1,6 @@
 export * from './config.js';
 export * from './component.js';
 export * from './data.js';
-export * from './layout.js';
 export * from './page.js';
 export * from './rich-text.js';
 export * from './image.js';

package/src/types/page.ts

@@ -34,5 +34,4 @@ export interface BlockNode {
 export interface FragmentRefNode {
   kind: 'fragment-ref';
   fragmentId: string;
-  inline: boolean;
 }

package/templates/astro/starter-content/src/components/chrome/Footer.astro

@@ -1,5 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import Logo from '../elements/Logo.astro';
 
 interface FooterLink {
@@ -21,7 +22,7 @@ interface FooterColumn {
   links?: FooterLink[];
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -38,7 +39,8 @@ const {
   social = [],
   columns = [],
   legalLinks = [],
-  copyright = ''
+  copyright = '',
+  ...root
 } = Astro.props;
 
 function columnGroups(column: FooterColumn): FooterGroup[] {
@@ -54,7 +56,7 @@ function columnGroups(column: FooterColumn): FooterGroup[] {
 }
 ---
 
-<footer class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
+<footer {...root} class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
   <Container className="py-[var(--spacing-footer-y)]">
     <div class="grid gap-12 pb-24 md:grid-cols-[var(--footer-grid-columns)] lg:gap-24">
       <a href={brandHref} class="self-start">

package/templates/astro/starter-content/src/components/chrome/Header.astro

@@ -1,5 +1,6 @@
 ---
 import Button from '../elements/Button.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import Container from '../elements/Container.astro';
 import Icon from '../elements/Icon.astro';
 import Logo from '../elements/Logo.astro';
@@ -14,7 +15,7 @@ interface UtilityItem extends NavItem {
   variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -27,11 +28,12 @@ const {
   brandLabel = 'Gradial',
   brandLogo = null,
   navigation = [],
-  utilities = []
+  utilities = [],
+  ...root
 } = Astro.props;
 ---
 
-<header class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
+<header {...root} class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
   <a
     href="#content-main"
     class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-10 focus:rounded-button focus:bg-white focus:px-4 focus:py-2 focus:text-black"

package/templates/astro/starter-content/src/components/elements/Button.astro

@@ -1,5 +1,7 @@
 ---
-interface Props {
+import type { RootIdentityProps } from '@gradial/aci';
+
+interface Props extends RootIdentityProps {
   href: string;
   variant?: 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
   className?: string;
@@ -7,7 +9,7 @@ interface Props {
   rel?: string;
 }
 
-const { href, variant = 'primary', className = '', target, rel } = Astro.props;
+const { href, variant = 'primary', className = '', target, rel, ...root } = Astro.props;
 
 const variantTokens = {
   primary: {
@@ -41,6 +43,7 @@ const tokenStyle = `background-color: ${variantTokens.background}; border-color:
 ---
 
 <a
+  {...root}
   class={`inline-flex min-h-10 items-center justify-center rounded-button border px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] [font-family:var(--font-family-base)] text-[length:var(--text-button)] font-[var(--font-weight-semibold)] leading-button transition duration-200 hover:opacity-85 ${className}`}
   href={href}
   target={target}

package/templates/astro/starter-content/src/components/elements/ButtonBlock.astro

@@ -1,9 +1,10 @@
 ---
 import Button from '../elements/Button.astro';
 import Icon from '../elements/Icon.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/button.contract';
 
-type Props = ContentProps;
+type Props = ContentProps & RootIdentityProps;
 
 const {
   label,
@@ -12,13 +13,14 @@ const {
   newWindow = false,
   icon = '',
   iconPosition = 'before',
-  className = ''
+  className = '',
+  ...root
 } = Astro.props;
 const target = newWindow ? '_blank' : undefined;
 const rel = newWindow ? 'noreferrer' : undefined;
 ---
 
-<Button {href} {variant} {target} {rel} {className}>
+<Button {href} {variant} {target} {rel} {className} {...root}>
   {icon && iconPosition === 'before' ? <Icon name={icon} className="mr-2 size-4" /> : null}
   <span>{label}</span>
   {icon && iconPosition === 'after' ? <Icon name={icon} className="ml-2 size-4" /> : null}

package/templates/astro/starter-content/src/components/sections/ContainerSection.astro

@@ -1,15 +1,16 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props {
+interface Props extends RootIdentityProps {
   theme?: 'auto' | 'light' | 'dark';
   className?: string;
   content?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { theme = 'auto', className = '', content, renderChildren } = Astro.props;
+const { theme = 'auto', className = '', content, renderChildren, ...root } = Astro.props;
 const children: RenderableBlock[] = content && renderChildren ? renderChildren(content) : [];
 const buttonCount = content?.filter((b: any) => b.component === 'button').length ?? 0;
 const layout = buttonCount === 1
@@ -17,7 +18,7 @@ const layout = buttonCount === 1
   : 'flex-col items-center sm:flex-row sm:justify-center sm:gap-4';
 ---
 
-<section class={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`}>
+<section {...root} class={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`}>
   {theme === 'dark' ? (
     <div class="pointer-events-none absolute inset-0 bg-[image:var(--gradient-hero-base)] opacity-30"></div>
   ) : null}

package/templates/astro/starter-content/src/components/sections/FeatureCard.astro

@@ -1,16 +1,17 @@
 ---
 import Icon from '../elements/Icon.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 
-interface Props {
+interface Props extends RootIdentityProps {
   icon?: string;
   title: string;
   description?: string;
 }
 
-const { icon = '', title = '', description = '' } = Astro.props;
+const { icon = '', title = '', description = '', ...root } = Astro.props;
 ---
 
-<div class="rounded-card border border-[var(--color-edge-space)] bg-[var(--color-space-surface)] p-[var(--spacing-card)] transition-all duration-[var(--transition-duration-fast)] hover:border-[var(--color-edge-space-strong)] hover:bg-[var(--color-space-raised)] hover:shadow-[var(--shadow-card-default)]">
+<div {...root} class="rounded-card border border-[var(--color-edge-space)] bg-[var(--color-space-surface)] p-[var(--spacing-card)] transition-all duration-[var(--transition-duration-fast)] hover:border-[var(--color-edge-space-strong)] hover:bg-[var(--color-space-raised)] hover:shadow-[var(--shadow-card-default)]">
   {icon ? (
     <div class="mb-6 flex h-12 w-12 items-center justify-center rounded-button bg-[color-mix(in_srgb,var(--color-brand-blue)_12%,transparent)] text-[var(--color-brand-blue-light)]">
       <Icon name={icon} className="h-6 w-6" />

package/templates/astro/starter-content/src/components/sections/FeatureGrid.astro

@@ -1,21 +1,22 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props {
+interface Props extends RootIdentityProps {
   title?: string;
   subtitle?: string;
   features?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { title = '', subtitle = '', features, renderChildren } = Astro.props;
+const { title = '', subtitle = '', features, renderChildren, ...root } = Astro.props;
 const children: RenderableBlock[] = features && renderChildren ? renderChildren(features) : [];
 const count = features?.length ?? 0;
 const cols = count <= 2 ? 'sm:grid-cols-2' : 'sm:grid-cols-2 lg:grid-cols-3';
 ---
 
-<section class="theme-dark py-[var(--spacing-section-y)] bg-[var(--color-space-deep)]">
+<section {...root} class="theme-dark py-[var(--spacing-section-y)] bg-[var(--color-space-deep)]">
   <Container>
     <div class="mb-12 max-w-[var(--max-width-container-narrow)]">
       {title ? (

package/templates/astro/starter-content/src/components/sections/HomeHero.astro

@@ -1,9 +1,9 @@
 ---
 import Button from '../elements/Button.astro';
 import Container from '../elements/Container.astro';
-import { imageAttrs, type Image } from '@gradial/aci';
+import { imageAttrs, type Image, type RootIdentityProps } from '@gradial/aci';
 
-interface Props {
+interface Props extends RootIdentityProps {
   eyebrow?: string;
   headline: string;
   description?: string;
@@ -18,7 +18,8 @@ const {
   description = '',
   ctaLabel,
   ctaHref,
-  image
+  image,
+  ...root
 } = Astro.props;
 
 const imgAttrs = image ? imageAttrs(image, {
@@ -29,6 +30,7 @@ const imgAttrs = image ? imageAttrs(image, {
 ---
 
 <section
+  {...root}
   class="theme-dark relative min-h-[var(--height-hero-min)] overflow-hidden bg-black text-fg"
   aria-label={image?.alt || headline}
 >

package/templates/astro/starter-content/src/components/sections/PersonalizationChoice.astro

@@ -1,12 +1,13 @@
 ---
+import type { RootIdentityProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/personalizationChoice.contract';
 
-type Props = ContentProps;
+type Props = ContentProps & RootIdentityProps;
 
-const { title, description, redLabel, blueLabel, refreshLabel } = Astro.props;
+const { title, description, redLabel, blueLabel, refreshLabel, ...root } = Astro.props;
 ---
 
-<section class="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]">
+<section {...root} class="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]">
   <div class="mx-auto max-w-[var(--layout-content-max)] px-[var(--layout-gutter)] text-center">
     <h2 class="text-[length:var(--text-h2)] font-[var(--font-weight-semibold)] text-[var(--color-fg)]">{title}</h2>
     {description ? <p class="mx-auto mt-3 max-w-2xl text-[var(--color-fg-muted)]">{description}</p> : null}

package/templates/astro/starter-content/src/components/sections/StatsBar.astro

@@ -1,5 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 
 interface Stat {
   label: string;
@@ -7,14 +8,14 @@ interface Stat {
   suffix?: string;
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   stats?: Stat[];
 }
 
-const { stats = [] } = Astro.props;
+const { stats = [], ...root } = Astro.props;
 ---
 
-<section class="theme-dark border-y border-[var(--color-edge-space)] bg-[var(--color-space-surface)] py-[var(--spacing-section-y)]">
+<section {...root} class="theme-dark border-y border-[var(--color-edge-space)] bg-[var(--color-space-surface)] py-[var(--spacing-section-y)]">
   <Container>
     <div class="grid gap-8 sm:grid-cols-2 lg:grid-cols-4">
       {stats.map((stat) => (

package/templates/astro/starter-content/src/fixtures/sections.ts

@@ -25,7 +25,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
         ctaHref: '/docs',
         image: {
           $type: 'gradial.image',
-          assetId: 'fixture_seattle',
+          assetId: '3Ih26etWBTYfnAd0EjD0pP2h902',
           versionId: 'v0001',
           alt: 'Seattle skyline at dusk',
           sources: [

package/templates/astro/starter-content/src/stories/CompositionStoryFrame.astro

@@ -1,6 +1,7 @@
 ---
 import type { KernelPageBlock } from '@gradial/aci/content';
-import ContainerSection from '../components/sections/ContainerSection.astro';
+import { createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
 
 interface Props {
   block: KernelPageBlock;
@@ -8,8 +9,12 @@ interface Props {
 }
 
 const { block, direction = 'ltr' } = Astro.props;
+// Stories render through the same seam as pages so the frame carries the
+// block's root identity (sdk I-19, ADR 0051).
+const [child] = createRenderChildren(registry)([block]);
+const Comp = child.Component as any;
 ---
 
 <div dir={direction}>
-  {block.component === 'container' ? <ContainerSection {...block.props} /> : null}
+  {Comp ? <Comp {...child.props} /> : null}
 </div>

package/templates/astro/template/.aci.yaml.tmpl

@@ -9,7 +9,6 @@ source:
   publicDir: "public"
 
 componentRegistry: ./src/cms/contracts/components/index.ts
-layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
 routes:
   cmsManaged: "/[...slug]"

package/templates/astro/template/package.json.tmpl

@@ -14,7 +14,7 @@
     "build:storybook": "storybook build"
   },
   "engines": {
-    "node": ">=22",
+    "node": ">=24",
     "npm": ">=10"
   },
   "dependencies": {
@@ -31,9 +31,9 @@
     "tsx": "^4.20.0",
     "typescript": "5.9.3",
     "vite": "^7.2.7",
-    "storybook": "^10.0.0",
-    "@storybook-astro/framework": "^1.6.0",
-    "@storybook/addon-docs": "^10.0.0",
-    "@storybook/builder-vite": "^10.0.0"
+    "storybook": "10.5.10",
+    "@storybook-astro/framework": "1.11.0",
+    "@storybook/addon-docs": "10.5.10",
+    "@storybook/builder-vite": "10.5.10"
   }
 }

package/templates/astro/template/src/layouts/SiteLayout.astro

@@ -48,8 +48,8 @@ const { title, description, canonical, siteName = 'Gradial', collectTag, assignm
       // island (@astrojs/react + @c15t/react) or any setup built on
       // c15t's createConsentManagerStore; this bridge picks it up either
       // way. Without a c15t setup the poll gives up silently and only the
-      // JS consent API (aci('consent', …) under the manual preset) writes
-      // envelopes.
+      // JS consent API (aci('consent', …)) writes envelopes — it is live
+      // under every preset, including c15t.
       //
       // Consents are mirrored only after a real visitor decision
       // (consentInfo set), never for pre-decision defaults, so the SDK

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

@@ -152,6 +152,56 @@ Optional (disabled by default):
 
 ## Troubleshooting
 
+### Deploying a starter to a hosted Vercel tenant
+
+Run the CLI from the starter repository root (where `.aci.yaml` lives), or
+pass `--site-dir .` from that directory. Do not pass an absolute site path
+from another working directory: older CLI versions can serialize it as a
+`../../../tmp/...` source folder, which makes the server-side build fail with
+a generic HTTP 500. The source ref must also be a pushed, cloneable branch;
+`ref: HEAD` from a detached worktree is not cloneable by the build service.
+
+The hosted publish sequence is:
+
+1. `GRADIAL_CODE_SOURCE_TOKEN="$(gh auth token)" aci code-build --site-dir . --branch <test-branch> ...`
+2. `aci branch land <test-branch>` to move the artifact link to `main`.
+3. Promote `/config/site.json` and the content paths needed by the release.
+4. Run `aci release publish --activate ...`.
+
+Match the tenant rendering mode to the starter's actual route capability. A
+Next starter with `dynamicParams = false` and no release-scoped runtime route
+is an SSG starter and must use `rendering.mode = "ssg"`; `ssr` is only valid
+when the frontend can resolve arbitrary host release routes at request time.
+A mismatch can build successfully but then fail SSG rendering or return a
+live Next 404 after the host rewrites a CMS page.
+
+Injected platform functions must be dependency-closed inside their own
+`.vercel/output/functions/<name>.func` mount. A prebuilt Vercel deploy does not
+install a function-local `package.json` after upload. Native dependencies such
+as `sharp` therefore belong to the host-function artifact, built for Vercel's
+Linux/x64 runtime and injected beside the handler; never add them to the
+starter's `package.json` merely to make a platform function resolve.
+
+Publish validates `refs/heads/live`, not only `main`. If `main` deletes a
+stale incompatible page or fragment that was previously promoted, promote
+that same path from `main` with `aci promote --path ... --yes`; because the
+source path is absent, the promote records a delete on `live`. This is the
+API-safe way to remove old live content—direct writes to `live` are forbidden.
+
+The same rule applies to breaking DAM identifier changes: every
+`dam.assetRef` in `live` is resolved during publish, so one legacy identifier
+blocks the release. Update the reference on a candidate branch through
+`aci content push`, land it, and promote that exact content path before
+publishing again. Do not weaken identifier validation or reactivate an old
+release to bypass the content migration.
+
+Legacy assets themselves are replaced through the product API, not rewritten
+in storage: download or retain the needed source bytes, upload them again so
+DAM creates fresh canonical IDs, approve them, replace every content reference,
+then land, promote, and publish the affected paths. This is the supported
+breaking cutover for pre-public tenants; there is no `ast_` alias or bulk
+object-store migration path.
+
 ### "Unknown component" error during content compile
 
 The content JSON references a `component` name that is not in the contract
@@ -194,10 +244,10 @@ If a value doesn't survive the round-trip, check:
 |------|---------|
 | `.aci.yaml` | ACI config: contract paths, framework, routes, capabilities |
 | `src/cms/contracts/components/index.ts` | Component contract barrel |
-| `src/cms/contracts/layouts/index.ts` | Layout contract barrel |
 | `src/cms/registry.ts` | Component registry (`createRegistry` with `[contract, component]` tuples) |
 | `src/components/` | Runtime component implementations |
 | `src/design-system/` | Design tokens and global styles |
+| `.content/templates/` | Page composition contracts |
 | `.content/` | Local content for development |
 
 ## Deep Dive: Authoring
@@ -209,3 +259,10 @@ development, design tokens, and the full contract/runtime split.
 
 Read `.agents/skills/migration/SKILL.md` for reverse-engineering a live
 site or design into ACI.
+
+## Deep Dive: DAM Delivery
+
+Read `.agents/skills/dam-delivery/SKILL.md` for public DAM asset links
+(`/dam/{assetId}`): how to shape an image with the `w`, `h`, `fit`, `fm`,
+`q` query, what makes a link serve or stop serving, and when to use a
+link instead of a pre-baked derivative.