@gradial/aci 0.1.26 → 0.1.28

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.21` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.27` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.21 zod@^4
+npm install @gradial/aci@0.1.27 zod@^4
 ```
 
 ## Root Import
@@ -44,10 +44,27 @@ Next integration helpers live under explicit Next subpaths:
 
 ```ts
 import { createPage, withAci } from '@gradial/aci/next';
-import { createMiddleware } from '@gradial/aci/next/middleware';
+import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 import { DevRefresh } from '@gradial/aci/next/dev-refresh';
 ```
 
+Use `ACI_SITE_ID` for the deployed site identity. Passing `siteId` to
+`createGradialMiddleware()` is still supported, but the default template relies
+on the environment so server and middleware resolution behave the same way.
+
+Middleware release-scopes document routes by default, including files such as
+`/robots.txt` and `/sitemap.xml`. Next internals, API routes, `favicon.ico`,
+public files discovered from `public/`, and `/gradial/assets/*` are left to
+Next. App-owned routes can opt out through `next.config`:
+
+```js
+import { withAci } from '@gradial/aci/next/config';
+
+export default withAci(nextConfig, {
+  passthroughRoutes: ['/healthz', '/checkout/:path*'],
+});
+```
+
 Astro public subpath is `@gradial/aci/astro`.
 
 ## Server-Side Content Providers
@@ -68,13 +85,13 @@ go through an app-owned HTTP endpoint backed server-side by a `ContentProvider`.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.21 init my-site --template next-starter
+npx @gradial/aci@0.1.27 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.21 init --list
+npx @gradial/aci@0.1.27 init --list
 ```
 
 ## Verify Locally

package/dist/next/asset-route.js

@@ -8,9 +8,9 @@ export async function GET(_request, { params }) {
     if (assetPath === '/') {
         return new Response('asset not found', { status: 404 });
     }
-    if (process.env.ACI_CONTENT_PROVIDER === 'file') {
-        const provider = new FileContentProvider();
-        return provider.fetchRaw(assetPath);
+    const local = await localAssetResponse(assetPath);
+    if (local) {
+        return local;
     }
     try {
         const releaseId = await resolveReleaseId();
@@ -20,3 +20,16 @@ export async function GET(_request, { params }) {
         return new Response('asset not found', { status: 404 });
     }
 }
+async function localAssetResponse(assetPath) {
+    const localRoot = process.env.ACI_LOCAL_ASSET_ROOT;
+    if (localRoot) {
+        const response = await new FileContentProvider(localRoot).fetchRaw(assetPath);
+        if (response.ok)
+            return response;
+    }
+    if (process.env.ACI_CONTENT_PROVIDER !== 'file') {
+        return null;
+    }
+    const response = await new FileContentProvider().fetchRaw(assetPath);
+    return response.ok ? response : null;
+}

package/dist/next/config.d.ts

@@ -2,5 +2,13 @@ import type { NextConfig } from 'next';
 export interface WithAciOptions {
     /** Asset rewrite prefix. Defaults to '/.gradial-dam' */
     assetPrefix?: string;
+    /**
+     * Customer-owned routes that ACI middleware should leave to Next.
+     *
+     * Use exact paths such as '/healthz' or simple Next-style catch-alls such as
+     * '/checkout/:path*'. CMS document routes such as '/robots.txt' and
+     * '/sitemap.xml' should be omitted so they stay release-scoped.
+     */
+    passthroughRoutes?: string[];
 }
 export declare function withAci(nextConfig?: NextConfig, options?: WithAciOptions): NextConfig;

package/dist/next/config.js

@@ -5,6 +5,7 @@ import { createContentWatchWebpackPlugin } from './content-watch.js';
 const require = createRequire(import.meta.url);
 export function withAci(nextConfig = {}, options = {}) {
     const publicPaths = collectPublicPaths(join(process.cwd(), 'public'));
+    const passthroughRoutes = normalizePassthroughRoutes(options.passthroughRoutes ?? []);
     const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const userRewrites = nextConfig.rewrites;
     const userHeaders = nextConfig.headers;
@@ -62,6 +63,7 @@ export function withAci(nextConfig = {}, options = {}) {
             const webpack = require('webpack');
             config.plugins.push(new webpack.DefinePlugin({
                 '__ACI_PUBLIC_PATHS__': JSON.stringify(publicPaths),
+                '__ACI_PASSTHROUGH_ROUTES__': JSON.stringify(passthroughRoutes),
             }));
             return typeof userWebpack === 'function'
                 ? userWebpack(config, context)
@@ -69,6 +71,25 @@ export function withAci(nextConfig = {}, options = {}) {
         },
     };
 }
+function normalizePassthroughRoutes(routes) {
+    const out = [];
+    const seen = new Set();
+    for (const route of routes) {
+        const clean = normalizeRoutePattern(route);
+        if (!clean || seen.has(clean))
+            continue;
+        seen.add(clean);
+        out.push(clean);
+    }
+    return out;
+}
+function normalizeRoutePattern(route) {
+    const trimmed = route.trim();
+    if (!trimmed)
+        return '';
+    const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return withSlash.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+}
 function collectPublicPaths(publicDir) {
     if (!existsSync(publicDir))
         return [];

package/dist/next/index.d.ts

@@ -2,3 +2,5 @@ export { DevRefresh, type DevRefreshProps } from './dev-refresh.js';
 export { withAci, type WithAciOptions } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage, type CreatePageOptions, type SlotPropsFn } from './page.js';
+export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
+export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';

package/dist/next/index.js

@@ -2,3 +2,5 @@ export { DevRefresh } from './dev-refresh.js';
 export { withAci } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage } from './page.js';
+export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
+export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';

package/dist/next/middleware.js

@@ -3,6 +3,7 @@ import { getUncachedEdgeConfigValue } from './edge-config.js';
 import { PREVIEW_TOKEN_COOKIE, PREVIEW_RELEASE_COOKIE, extractPreviewToken, resolvePreviewContext, createPreviewCookies, previewSignKey, } from '../preview/core.js';
 const RELEASE_SCOPED_PREFIX = '/__r';
 const PUBLIC_PATHS = new Set(typeof __ACI_PUBLIC_PATHS__ !== 'undefined' ? __ACI_PUBLIC_PATHS__ : []);
+const PASSTHROUGH_ROUTES = (typeof __ACI_PASSTHROUGH_ROUTES__ !== 'undefined' ? __ACI_PASSTHROUGH_ROUTES__ : []);
 export function createGradialMiddleware(config = {}) {
     return async function middleware(request) {
         const url = request.nextUrl;
@@ -17,6 +18,9 @@ export function createGradialMiddleware(config = {}) {
         if (PUBLIC_PATHS.has(url.pathname)) {
             return NextResponse.next();
         }
+        if (isPassthroughRoute(url.pathname)) {
+            return NextResponse.next();
+        }
         // Block direct access to /__r/... — only middleware rewrites may use it.
         if (isReleaseScopedPath(url.pathname, RELEASE_SCOPED_PREFIX)) {
             return new Response('not found', {
@@ -32,6 +36,12 @@ export function createGradialMiddleware(config = {}) {
             if (process.env.ACI_CONTENT_PROVIDER === 'file') {
                 return NextResponse.next();
             }
+            if (!siteIdForConfig(config)) {
+                return new Response('ACI site id is not configured', {
+                    status: 500,
+                    headers: { 'Cache-Control': 'private, no-store' },
+                });
+            }
             return new Response('no active release', {
                 status: 503,
                 headers: { 'Cache-Control': 'private, no-store' },
@@ -123,7 +133,7 @@ async function resolvePreviewFromRequest(request, config) {
         console.warn('[aci/mw] GRADIAL_PREVIEW_SIGN_KEY not set — preview tokens will be ignored');
         return null;
     }
-    return await resolvePreviewContext({ token, siteId: config.siteId || '', signKey });
+    return await resolvePreviewContext({ token, siteId: siteIdForConfig(config), signKey });
 }
 function cookieMap(cookies) {
     const map = new Map();
@@ -134,19 +144,23 @@ function cookieMap(cookies) {
 }
 async function activeReleaseFromEdgeConfig(config) {
     const edgeConfig = config.edgeConfig || process.env.EDGE_CONFIG || '';
-    if (!edgeConfig || !config.siteId)
+    const siteId = siteIdForConfig(config);
+    if (!edgeConfig || !siteId)
         return '';
-    const active = await activeReleasePointer(edgeConfig, config.siteId);
+    const active = await activeReleasePointer(edgeConfig, siteId);
     if (!active.releaseId)
         return '';
     const deploymentId = config.deploymentId || process.env.VERCEL_DEPLOYMENT_ID || '';
     if (!deploymentId)
         return active.releaseId;
-    const compatibility = await getEdgeConfigJSON(edgeConfig, deploymentCompatibilityKey(config.siteId, deploymentId));
+    const compatibility = await getEdgeConfigJSON(edgeConfig, deploymentCompatibilityKey(siteId, deploymentId));
     if (!compatibility)
         return active.releaseId;
     return clampRelease(active.releaseId, active.sequence || 0, compatibility);
 }
+function siteIdForConfig(config) {
+    return config.siteId || process.env.ACI_SITE_ID || '';
+}
 async function getEdgeConfigJSON(edgeConfig, key) {
     const value = await getEdgeConfigValue(edgeConfig, key);
     if (!value)
@@ -202,6 +216,31 @@ function clampRelease(activeReleaseId, activeSequence, compatibility) {
 function edgeKeySegment(value) {
     return value.replace(/[^A-Za-z0-9_-]/g, '_');
 }
+function isPassthroughRoute(pathname) {
+    return PASSTHROUGH_ROUTES.some((route) => routeMatches(pathname, route));
+}
+function routeMatches(pathname, route) {
+    const cleanPath = normalizeRoutePath(pathname);
+    const cleanRoute = normalizeRoutePath(route);
+    if (!cleanRoute)
+        return false;
+    if (cleanRoute.endsWith('/:path*')) {
+        const prefix = cleanRoute.slice(0, -'/:path*'.length) || '/';
+        return cleanPath === prefix || cleanPath.startsWith(`${prefix}/`);
+    }
+    if (cleanRoute.endsWith('/*')) {
+        const prefix = cleanRoute.slice(0, -'/*'.length) || '/';
+        return cleanPath === prefix || cleanPath.startsWith(`${prefix}/`);
+    }
+    return cleanPath === cleanRoute;
+}
+function normalizeRoutePath(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return '';
+    const pathname = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return pathname.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+}
 export const config = {
-    matcher: ['/((?!_next/).*)'],
+    matcher: ['/((?!_next(?:/|$)|api(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)'],
 };

package/dist/providers/file.js

@@ -60,7 +60,14 @@ export class FileContentProvider {
         }
     }
     async manifest() {
-        this.#manifest ??= this.readJSON('manifest.json');
+        this.#manifest ??= this.readJSON('manifest.json').catch(() => ({
+            manifestVersion: '0',
+            buildDigest: '',
+            siteConfigRef: '',
+            routes: {},
+            fragments: {},
+            layouts: {},
+        }));
         return await this.#manifest;
     }
     async fetchRaw(key) {

package/dist/types/data.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export type TaxonomyAssignments = Record<string, string[]>;
 type InferDataProps<TSchema> = TSchema extends z.ZodType<infer T> ? T : Record<string, unknown>;
 export interface DataModelDefinition<TSchema = unknown, TType extends string = string> {
     type: TType;
@@ -11,6 +12,7 @@ export interface DataModelContract<TSchema = unknown, TType extends string = str
 export interface DataEntry<TProps = Record<string, unknown>, TType extends string = string> {
     $type: TType;
     props: TProps;
+    taxonomy?: TaxonomyAssignments;
 }
 export type InferDataModelProps<TContract> = TContract extends DataModelContract<infer TSchema, string> ? InferDataProps<TSchema> : Record<string, unknown>;
 export type InferDataModelType<TContract> = TContract extends DataModelContract<unknown, infer TType> ? TType : string;

package/dist/types/page.d.ts

@@ -1,9 +1,11 @@
 import type { VaryDimension } from './render-mode.js';
+import type { TaxonomyAssignments } from './data.js';
 export interface PageDocument {
     path: string;
     layout: string;
     locale: string;
     metadata: PageMetadata;
+    taxonomy?: TaxonomyAssignments;
     regions: Record<string, RegionNode>;
 }
 export interface PageMetadata {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -74,6 +74,11 @@
       "types": "./dist/next/dev-refresh.d.ts",
       "import": "./dist/next/dev-refresh.js"
     },
+    "./next/server": {
+      "types": "./dist/next/server.d.ts",
+      "import": "./dist/next/server.js",
+      "default": "./dist/next/server.js"
+    },
     "./astro": {
       "types": "./dist/astro/index.d.ts",
       "import": "./dist/astro/index.js",

package/src/types/data.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+export type TaxonomyAssignments = Record<string, string[]>;
+
 type InferDataProps<TSchema> = TSchema extends z.ZodType<infer T>
   ? T
   : Record<string, unknown>;
@@ -19,6 +21,7 @@ export interface DataModelContract<TSchema = unknown, TType extends string = str
 export interface DataEntry<TProps = Record<string, unknown>, TType extends string = string> {
   $type: TType;
   props: TProps;
+  taxonomy?: TaxonomyAssignments;
 }
 
 export type InferDataModelProps<TContract> = TContract extends DataModelContract<infer TSchema, string>

package/src/types/page.ts

@@ -1,10 +1,12 @@
 import type { VaryDimension } from './render-mode.js';
+import type { TaxonomyAssignments } from './data.js';
 
 export interface PageDocument {
   path: string;
   layout: string;
   locale: string;
   metadata: PageMetadata;
+  taxonomy?: TaxonomyAssignments;
   regions: Record<string, RegionNode>;
 }
 

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

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@astrojs/node": "^10.1.4",
-    "@gradial/aci": "0.1.23",
+    "@gradial/aci": "{{aciVersion}}",
     "astro": "^6.1.9",
     "zod": "^4.0.0"
   },

package/templates/common/.agents/AGENTS.md

@@ -22,6 +22,11 @@ Skills live in `.agents/skills/`. Each has a `SKILL.md` entry point and
 - Registry lives in `src/cms/registry.ts` (`createRegistry` with `[contract, component]` tuples).
 - Compiled output goes to `.aci/compiled/` (generated, not checked in).
 - Framework integration via `withAci()` in the framework config.
+- Next.js server functions from `@gradial/aci/next` — use `getSiteConfig()`, `getPage()`, `getFragment()` instead of importing `FileContentProvider` or `S3ContentProvider` directly.
+- Rich text from `@gradial/aci/react` — use `RichText` component, never raw `marked`/`dangerouslySetInnerHTML`.
+- Images from `@gradial/aci` — use `imageAttrs()` or SDK components, never manual `srcSet` construction.
+- Block slots use `blockRefArray()` in contracts and `renderChildren` in components — never hardcoded component name matching.
+- No `as any` casts — use `ContentProps` from contracts.
 - Supported frameworks: Astro and Next.js (SvelteKit removed).
 
 ## Commands

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

@@ -588,3 +588,34 @@ chrome-specific override scopes, and token creation workflow.
 Read `references/repo-structure.md` for the full annotated directory
 layout, framework-specific paths, naming conventions, and generated
 files list.
+
+## Deep Dive: SDK Server Functions
+
+Read `references/sdk-server-functions.md` for `@gradial/aci/next`
+server-side functions (`createPage`, `getSiteConfig`, `getFragment`,
+etc.), the three-tier content resolution chain, and the critical rule
+against importing `FileContentProvider` or `S3ContentProvider`
+directly in app code.
+
+## Deep Dive: Block Slots
+
+Read `references/block-slots.md` for `blockRefArray()` in contracts,
+`renderChildren` in components, and the rules for nested block
+rendering without hardcoded component name matching.
+
+## Deep Dive: Rich Text
+
+Read `references/rich-text.md` for the SDK `RichText` component from
+`@gradial/aci/react`, sanitization policy, and why you should never
+use `marked` or `dangerouslySetInnerHTML` directly.
+
+## Deep Dive: Asset Rendering
+
+Read `references/asset-rendering.md` for `imageAttrs()`, `Picture`,
+`Image`, `Media` components, and CSS background image patterns.
+
+## Deep Dive: Type Safety
+
+Read `references/type-safety.md` for `ContentProps` from contracts,
+`as any` prohibition, CSS custom property typing, site config
+generics, and block slot type imports.

package/templates/common/.agents/skills/authoring/references/asset-rendering.md

@@ -0,0 +1,110 @@
+# Asset Rendering Reference
+
+## Rules
+
+- **NEVER** construct `<img>` tags manually with `src`/`srcSet` from
+  image sources.
+- **ALWAYS** use the SDK's `imageAttrs()` function from `@gradial/aci`
+  or the `Image`/`Picture` component from `@gradial/aci/react`.
+- **NEVER** duplicate the `Image` type locally — always import from
+  `@gradial/aci`.
+
+## SDK Exports
+
+### From `@gradial/aci`
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `Image` | type | The DAM-backed image type (`$type`, `assetId`, `versionId`, `alt`, `sources`) |
+| `ImageSource` | type | A single responsive derivative (`src`, `width`, `height`, `type`) |
+| `imageAttrs(image, overrides?)` | function | Returns a complete attributes object for `<img>` |
+| `primaryImageSource(image)` | function | Picks the largest-width source from an image |
+| `ImageSchema` | Zod schema | Schema for image fields in contracts |
+
+### From `@gradial/aci/react`
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `Image` | component | Renders an `Image` as `<img>` with computed attrs |
+| `Picture` | component | Renders an `Image` as responsive `<img>` (delegates to `imageAttrs()`) |
+| `Media` | component | Renders media assets (images, videos) with type detection |
+
+## imageAttrs()
+
+`imageAttrs(image, overrides?)` returns a complete attributes object
+including `src`, `alt`, `width`, `height`, `srcSet`, `sizes`, `loading`,
+and `decoding`. Spread the result into a native `<img>` element:
+
+```tsx
+import { imageAttrs, type Image } from '@gradial/aci';
+
+export function HeroImage({ image }: { image: Image }) {
+  return <img {...imageAttrs(image)} />;
+}
+```
+
+Override specific attributes by passing a second argument:
+
+```tsx
+<img {...imageAttrs(image, { loading: 'eager' })} />
+```
+
+## SDK Components
+
+```tsx
+import { Picture, Image } from '@gradial/aci/react';
+
+// Picture: delegates to imageAttrs() internally
+<Picture image={image} />
+
+// Image: same behavior, accepts image or value prop
+<Image image={image} />
+```
+
+Both components call `imageAttrs()` internally and spread the result
+into a native `<img>` element.
+
+## CSS Background Images
+
+For CSS background images, use `primaryImageSource()` to get the URL:
+
+```tsx
+import { primaryImageSource } from '@gradial/aci';
+
+export function HeroBackground({ image }: { image: Image }) {
+  const src = primaryImageSource(image).src;
+  return (
+    <div style={{ backgroundImage: `url(${src})` } as React.CSSProperties} />
+  );
+}
+```
+
+## In Contracts
+
+Use `ImageSchema` for DAM-managed image fields:
+
+```ts
+import { ImageSchema, defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  image: ImageSchema,
+  cards: z.array(z.object({
+    image: ImageSchema.optional(),
+  })),
+});
+```
+
+Declare `imageSlots` matching every `ImageSchema` field, including
+nested dot paths like `cards.image`. See
+`references/image-assets.md` for full image slot configuration.
+
+## Anti-Patterns
+
+- Manually building `srcSet` strings from `image.sources` — use
+  `imageAttrs()` instead
+- Constructing `<img src={image.sources[0].src} />` — use `imageAttrs()`
+  or SDK components
+- Duplicating the `Image` type locally — import from `@gradial/aci`
+- Ignoring `width`/`height` — `imageAttrs()` includes them to prevent
+  layout shift

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

@@ -0,0 +1,140 @@
+# Block Slots Reference
+
+## What Block Slots Are
+
+Container components (like `container` and `grid_column`) can render
+child blocks. The SDK detects block slots from contracts and injects a
+`renderChildren` callback into the component props at render time.
+
+This lets editors nest blocks inside other blocks in content JSON, and
+the SDK resolves the child components through the registry — no
+hardcoded component name matching needed.
+
+## Defining Block Slots in Contracts
+
+Use `blockRefArray()` from `@gradial/aci` in the contract's Zod schema
+to declare a block slot field. The compiler scans the schema for
+`blockRefArray` and `blockRef` fields and auto-discovers block slots —
+no separate `slots` or `blockSlots` declaration needed.
+
+```ts
+import { blockRefArray, defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+import { calloutContract } from './callout.contract';
+import { headingContract } from './heading.contract';
+
+export const schema = z.object({
+  theme: z.enum(['auto', 'light', 'dark']).optional(),
+  className: z.string().optional(),
+  blocks: blockRefArray([calloutContract, headingContract]).optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const containerContract = defineComponentContract({
+  id: 'container',
+  props: schema,
+});
+```
+
+`blockRefArray()` takes an array of allowed contracts — only those block
+types can be placed in the slot. This flows into the generated JSON
+schema, so the content validator enforces the allowlist at build time.
+
+For a single (non-array) block slot, use `blockRef(contracts)` instead:
+
+```ts
+import { blockRef, defineComponentContract } from '@gradial/aci';
+import { headingContract } from './heading.contract';
+
+export const schema = z.object({
+  heading: blockRef([headingContract]).optional(),
+});
+```
+
+## Using renderChildren in Components
+
+The SDK's render system checks `entry.contract.blockSlots` and, if
+present, injects a `renderChildren` callback into the component props.
+This callback resolves child blocks through the registry.
+
+```tsx
+import type { BlockRef, ReactElement } from '@gradial/aci';
+import type { RenderChildren } from '@gradial/aci/react';
+import type { ContentProps } from '@/cms/contracts/components/container.contract';
+
+export async function ContainerSection({
+  theme = 'auto',
+  className = '',
+  blocks = [],
+  renderChildren,
+}: ContentProps & { renderChildren?: RenderChildren<readonly BlockRef[]> }) {
+  const rendered = blocks.length && renderChildren
+    ? await renderChildren(blocks)
+    : null;
+
+  return (
+    <section className={`theme-${theme} py-[var(--spacing-section-y)] ${className}`}>
+      <div className="flex flex-col gap-6">
+        {rendered}
+      </div>
+    </section>
+  );
+}
+```
+
+The `RenderChildren` type is exported from `@gradial/aci/react`:
+
+```ts
+type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<ReactElement[]>;
+```
+
+## Rules
+
+- **Never hardcode component name matching.** No switch statements on
+  `block.component`. Always use `renderChildren` from the SDK — it uses
+  the registry to resolve components.
+- **Always use `blockRefArray()` in contracts** to declare block slot
+  fields. The compiler auto-discovers them from the Zod schema.
+- **Atomic block contracts must be registered** in the registry with
+  their components. `renderChildren` resolves child blocks through the
+  same registry used for top-level blocks.
+- **`blockRefArray()` takes an array of allowed contracts** — only
+  those block types can be placed in the slot. This is enforced at
+  content validation time.
+- **`renderChildren` is optional** — always guard with a conditional
+  (`blocks.length && renderChildren ? await renderChildren(blocks) : null`)
+  so the component works in isolation (e.g., Storybook).
+- **Nested blocks live inside `props`**, not in a sibling `slots` field.
+  The content JSON places child blocks directly in the prop value
+  matching the `blockRefArray` field name.
+
+## Content JSON Example
+
+```json
+{
+  "id": "cta-section",
+  "component": "container",
+  "props": {
+    "theme": "dark",
+    "blocks": [
+      {
+        "id": "primary-cta",
+        "component": "callout",
+        "props": {
+          "headline": "Get started today",
+          "body": "Ship content updates in minutes."
+        }
+      },
+      {
+        "id": "heading",
+        "component": "heading",
+        "props": {
+          "text": "Why teams choose us",
+          "level": 2
+        }
+      }
+    ]
+  }
+}
+```

package/templates/common/.agents/skills/authoring/references/rich-text.md

@@ -0,0 +1,75 @@
+# Rich Text Reference
+
+## Rules
+
+- **NEVER** use `marked`, `markdown-it`, or `dangerouslySetInnerHTML`
+  directly in component code.
+- **ALWAYS** use the SDK's `RichText` component from `@gradial/aci/react`.
+
+The SDK `RichText` component uses `sanitize-html` with an explicit
+allowlist. It renders markdown via `markdown-it` (with `html: false` to
+prevent raw HTML in markdown) and then sanitizes the output. Links get
+`rel="noopener noreferrer"` automatically.
+
+## Usage
+
+```tsx
+import { RichText } from '@gradial/aci/react';
+
+export function ArticleBody({ body }: { body: string }) {
+  return <RichText value={body} />;
+}
+```
+
+The `value` prop accepts:
+
+- **`string`** — treated as markdown and rendered to HTML
+- **`RichTextValue`** object — `{ format: 'markdown', markdown: '...' }`
+  or `{ format: 'html', html: '...' }`
+
+When a string is passed, the component wraps it as
+`{ format: 'markdown', markdown: value }` internally.
+
+## In Contracts
+
+Use `RichTextValueSchema` for typed rich text fields:
+
+```ts
+import { RichTextValueSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  body: RichTextValueSchema.optional(),
+});
+```
+
+Or accept a plain string:
+
+```ts
+export const schema = z.object({
+  body: z.string().optional(),
+});
+```
+
+Both forms work with the `RichText` component — it accepts
+`RichTextValue | string`.
+
+## Sanitization Policy
+
+The SDK allowlist includes:
+
+- Standard formatting tags: `p`, `br`, `strong`, `em`, `ul`, `ol`, `li`,
+  `code`, `pre`, `blockquote`, `h1`–`h6`, `img`
+- Links (`a`) with `href`, `name`, `target`, `rel` attributes
+- Images (`img`) with `src`, `alt`, `width`, `height`, `loading`
+  attributes
+
+Raw HTML in markdown input is rejected by `markdown-it`'s `html: false`
+setting. HTML format values are sanitized by `sanitize-html`.
+
+## Anti-Patterns
+
+- Importing `marked` or `markdown-it` directly — the SDK already
+  handles this with proper sanitization
+- Using `dangerouslySetInnerHTML` with unsanitized content
+- Writing a custom markdown-to-HTML pipeline in component code

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

@@ -0,0 +1,192 @@
+# SDK Server Functions Reference
+
+## `@gradial/aci/next` Exports
+
+The SDK provides server-side functions that handle content resolution
+across preview, local file, and deployed S3 modes. **Always use these
+functions instead of directly importing `FileContentProvider` or
+`S3ContentProvider`.** The SDK handles the resolution chain automatically.
+
+### `createPage(registry)`
+
+The catch-all route handler for Next.js App Router. Owns param
+normalization, content loading via render input, metadata generation,
+`notFound` handling, layout resolution, and block rendering via the
+registry.
+
+```tsx
+// src/app/[[...slug]]/page.tsx
+import { createPage } from '@gradial/aci/next';
+import { registry } from '@/cms/registry';
+
+const page = createPage(registry);
+export const dynamic = 'force-dynamic';
+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. The `main` slot is wrapped in `<main>`; other slots render as
+fragments.
+
+### `withAci(nextConfig, options?)`
+
+Next.js config wrapper. Sets up asset rewrites (`.gradial-dam` prefix)
+and dev-mode content watch via webpack plugin.
+
+```ts
+// next.config.ts
+import { withAci } from '@gradial/aci/next';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = { reactStrictMode: true };
+export default withAci(nextConfig);
+```
+
+### `getSiteConfig<T>()`
+
+Loads the site configuration. Checks the render input header first
+(preview mode), then falls back to file or S3 provider. **MUST be used
+in `layout.tsx` instead of `new FileContentProvider()`.**
+
+```tsx
+import { getSiteConfig } from '@gradial/aci/next';
+
+const siteConfig = await getSiteConfig<MySiteConfig>();
+```
+
+Generic: pass your site config interface for typed access:
+`getSiteConfig<SiteConfig>()`.
+
+### `getFragment(name)`
+
+Loads a fragment by name. Checks render input first (preview mode), then
+provider fallback.
+
+### `getLayout(name)`
+
+Loads a layout by name. Checks render input first (preview mode), then
+provider fallback.
+
+### `getPage(route)`
+
+Loads page content for a specific route. Checks render input first
+(preview mode), then provider fallback.
+
+### `getRenderInput(route)`
+
+Loads the full render input (page + siteConfig + domain + locale). Used
+internally by `createPage`. Available for custom server composition when
+you need the full render context.
+
+### `routeFromNextParams(params)`
+
+Normalizes Next.js catch-all params (`{ slug?: string[] }`) into a route
+string. Handles `Promise`-wrapped params from Next.js 15+.
+
+### `isPreviewMode()`
+
+Async function returning the preview release ID string when in preview
+mode, or an empty string when not. Use as a truthy check:
+
+```tsx
+const previewRelease = await isPreviewMode();
+if (previewRelease) { /* preview-specific logic */ }
+```
+
+### `DevRefresh`
+
+React component for dev-mode content refresh. Connects to the SDK's
+content watch WebSocket and triggers a page reload when compiled content
+changes. Add to the root layout:
+
+```tsx
+import { DevRefresh } from '@gradial/aci/next';
+
+// In layout body:
+<DevRefresh />
+```
+
+Only active in development (`NODE_ENV !== 'production'`). Renders `null`
+in production.
+
+### Error Classes
+
+| Class | Thrown When |
+|-------|-------------|
+| `PageNotFoundError` | Page not found for a route |
+| `FragmentNotFoundError` | Fragment not found by name |
+| `LayoutNotFoundError` | Layout not found by name |
+
+`createPage` catches `PageNotFoundError` and calls `notFound()`
+automatically.
+
+## Three-Tier Content Resolution
+
+Every SDK server function follows the same resolution chain:
+
+### Tier 1: Render Input (Preview Mode)
+
+When the Go harness sends a render request, it sets the
+`x-gradial-render-input-id` header. The SDK checks the
+`pendingRenderInputs` in-process map for a matching render input and
+returns page data directly from the Go harness's render payload. This
+is how preview works — the harness pushes content into the Next.js
+process without touching S3 or disk.
+
+### Tier 2: File Provider (`ACI_CONTENT_PROVIDER=file`)
+
+When the `ACI_CONTENT_PROVIDER` environment variable is set to `file`,
+the SDK reads compiled content from `.aci/compiled/` on disk. This is
+the local development path. Also used as a fallback in preview mode when
+no render input header is present.
+
+### Tier 3: S3 Provider (Deployed SSR)
+
+When neither render input nor file provider is active, the SDK reads
+from S3. The release ID is resolved from (in order):
+
+1. `x-gradial-release-id` header (set by middleware)
+2. `ACI_RELEASE_ID` environment variable
+3. Vercel Edge Config active release pointer
+
+## Critical Rule
+
+**NEVER import `FileContentProvider` or `S3ContentProvider` directly in
+app code.** Always use `getPage()`, `getSiteConfig()`, `getFragment()`,
+`getLayout()`, or `getRenderInput()` from `@gradial/aci/next`. The SDK
+handles the resolution chain automatically.
+
+The only exception is the asset route handler
+(`src/app/gradial/assets/[releaseId]/[...path]/route.ts`), which directly
+uses `FileContentProvider` for local asset serving and
+`getReleaseAssetResponse` for S3 assets.
+
+## Layout.tsx Pattern
+
+```tsx
+import { DevRefresh, getSiteConfig } from '@gradial/aci/next';
+
+export default async function Layout({ children }: { children: ReactNode }) {
+  const siteConfig = await getSiteConfig<SiteConfig>().catch(() => null);
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <DevRefresh />
+      </body>
+    </html>
+  );
+}
+```
+
+Chrome (Header/Footer) is CMS-managed via layout fragment defaults and
+rendered by `createPage` through the registry. The `layout.tsx` file
+should be minimal — import CSS, optionally load site config for
+metadata/fonts, and render `<DevRefresh />`.
+
+For sites that need site config in the layout (e.g., for fonts or
+metadata), use `getSiteConfig<SiteConfig>()` with a `.catch(() => null)`
+fallback so the layout doesn't crash if content isn't available during
+build.

package/templates/common/.agents/skills/authoring/references/type-safety.md

@@ -0,0 +1,141 @@
+# Type Safety Reference
+
+## ContentProps from Contracts
+
+Contracts export `ContentProps = z.infer<typeof schema>`. Use this type
+in runtime components for prop typing:
+
+```ts
+// src/cms/contracts/components/hero.contract.ts
+import { defineComponentContract, ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  headline: z.string().min(1),
+  image: ImageSchema,
+  ctaLabel: z.string().optional(),
+  ctaHref: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const heroContract = defineComponentContract({
+  id: 'hero',
+  props: schema,
+});
+```
+
+```tsx
+// src/components/sections/Hero.tsx
+import type { ContentProps } from '@/cms/contracts/components/hero.contract';
+
+type HeroProps = ContentProps & { className?: string };
+
+export function Hero({ headline, image, ctaLabel, ctaHref, className }: HeroProps) {
+  // ...
+}
+```
+
+## Rules
+
+### No `as any` casts
+
+**NEVER** use `as any` or `as any[]` casts in component code. If the
+type doesn't fit, fix the contract schema.
+
+```tsx
+// BAD
+const items = props.items as any[];
+
+// GOOD — fix the schema to match the actual shape
+export const schema = z.object({
+  items: z.array(z.object({
+    title: z.string(),
+    description: z.string(),
+  })),
+});
+```
+
+### No passthrough schemas
+
+Contracts must define proper schemas. Do not use
+`z.object({}).passthrough()` or `z.record(z.any())`:
+
+```ts
+// BAD — hides type errors and allows any content
+export const schema = z.object({}).passthrough();
+export const schema = z.record(z.any());
+
+// GOOD — explicit fields
+export const schema = z.object({
+  headline: z.string(),
+  items: z.array(z.object({ title: z.string() })),
+});
+```
+
+### CSS custom properties
+
+For React `style` props with CSS custom properties, use
+`as React.CSSProperties` (not `as any`):
+
+```tsx
+// BAD
+<div style={{ '--accent': 'red' } as any} />
+
+// GOOD
+<div style={{ '--accent': 'red' } as React.CSSProperties} />
+```
+
+### Image type
+
+Use the `Image` type from `@gradial/aci` for image props. Never
+duplicate the type locally:
+
+```tsx
+// BAD — local duplicate
+interface Image { src: string; alt: string; }
+
+// GOOD — import from SDK
+import type { Image } from '@gradial/aci';
+```
+
+### Site config
+
+Define a `SiteConfig` interface and pass it to `getSiteConfig()`:
+
+```tsx
+import { getSiteConfig } from '@gradial/aci/next';
+
+interface SiteConfig {
+  title: string;
+  domain: string;
+  defaultLocale: string;
+  navigation: NavItem[];
+  footer: FooterConfig;
+}
+
+const config = await getSiteConfig<SiteConfig>();
+// config is typed as SiteConfig
+```
+
+### Block slot types
+
+Use `RenderChildren` from `@gradial/aci/react` and `BlockRef` from
+`@gradial/aci` for block slot component props:
+
+```tsx
+import type { BlockRef } from '@gradial/aci';
+import type { RenderChildren } from '@gradial/aci/react';
+import type { ContentProps } from '@/cms/contracts/components/container.contract';
+
+export async function ContainerSection({
+  blocks = [],
+  renderChildren,
+}: ContentProps & {
+  renderChildren?: RenderChildren<readonly BlockRef[]>;
+}) {
+  // ...
+}
+```
+
+See `references/block-slots.md` for the full block slot pattern.

package/templates/nextjs/template/package.json.tmpl

@@ -17,7 +17,7 @@
     "build:storybook": "storybook build"
   },
   "dependencies": {
-    "@gradial/aci": "0.1.23",
+    "@gradial/aci": "{{aciVersion}}",
     "next": "^15.1.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/nextjs/template/src/middleware.ts

@@ -1,4 +1,7 @@
 import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 
 export default createGradialMiddleware();
-export { config } from '@gradial/aci/next/middleware';
+
+export const config = {
+  matcher: ['/((?!_next(?:/|$)|api(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)'],
+};