@gradial/aci 0.1.31 → 0.1.34

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.31",
+  "version": "0.1.34",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "bin/aci.js",
-    "bin/aci-*",
     "src/cli/*.mjs",
     "src/types/*.ts",
     "templates/common",
@@ -83,8 +82,20 @@
       "types": "./dist/astro/index.d.ts",
       "import": "./dist/astro/index.js",
       "default": "./dist/astro/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/conformance/index.d.ts",
+      "import": "./dist/testing/conformance/index.js"
     }
   },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
+    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
+    "compile-registry": "tsx src/cli/compile-registry.mjs",
+    "prepack": "npm run generate-starters && npm run build && node scripts/ensure-bin-modes.mjs"
+  },
   "dependencies": {
     "markdown-it": "^14.1.0",
     "sanitize-html": "^2.13.1",
@@ -112,19 +123,23 @@
     }
   },
   "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^24.10.1",
     "@types/react": "^19.0.0",
-    "@types/markdown-it": "^14.1.2",
     "@types/sanitize-html": "^2.16.0",
     "@types/ws": "^8.18.0",
+    "jsdom": "^29.1.1",
+    "next": "^15.5.19",
     "tsx": "^4.20.0",
     "typescript": "^5.9.3",
     "zod": "^4.0.0"
   },
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
-    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
-    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
-    "compile-registry": "tsx src/cli/compile-registry.mjs"
+  "optionalDependencies": {
+    "@gradial/aci-cli-darwin-arm64": "0.1.34",
+    "@gradial/aci-cli-darwin-x64": "0.1.34",
+    "@gradial/aci-cli-linux-arm64": "0.1.34",
+    "@gradial/aci-cli-linux-x64": "0.1.34",
+    "@gradial/aci-cli-win32-arm64": "0.1.34",
+    "@gradial/aci-cli-win32-x64": "0.1.34"
   }
-}
+}

package/src/cli/materialize-template.mjs

@@ -0,0 +1,133 @@
+// Single assembly path for scaffolding a site from the SDK templates.
+//
+// Both `scripts/generate-starters.ts` (repo codegen for starters/*) and
+// `aci init` (bin/aci.js, customer scaffolding from the published package)
+// call materializeTemplate so the two outputs can never drift.
+// Spec: specs/features/starter-fresh-clone-dx (D-1).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const EXCLUDE_PATTERNS = [
+  /node_modules/,
+  /\.DS_Store$/,
+  /package-lock\.json$/,
+  /\.git$/,
+  /storybook-static/,
+  /starter-content/,
+];
+
+const COMMON_DIRS = ['.aci', '.agents', '.content', 'eslint-rules'];
+const COMMON_ROOT_FILES = ['.nvmrc'];
+
+// Per-framework values rendered into shared templates (e.g. README.md.tmpl).
+// Derived here so `aci init` and `generate-starters` can never disagree.
+const FRAMEWORK_VARS = {
+  nextjs: { devUrl: 'http://localhost:3000', frameworkName: 'Next.js' },
+  astro: { devUrl: 'http://localhost:4321', frameworkName: 'Astro' },
+};
+
+// Exclusions match paths RELATIVE to the copy root: the SDK itself is often
+// installed under a node_modules/ directory (npm install, the npx cache), so
+// matching absolute paths would exclude every template file.
+function shouldExclude(relPath) {
+  return EXCLUDE_PATTERNS.some((pattern) => pattern.test(relPath));
+}
+
+function copyDirSync(src, dest, root = src) {
+  if (!fs.existsSync(src)) return;
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (shouldExclude(path.relative(root, srcPath))) continue;
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDirSync(srcPath, destPath, root);
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function renderTmplFiles(dir, vars, root = dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (shouldExclude(path.relative(root, fullPath))) continue;
+    if (entry.isDirectory()) {
+      renderTmplFiles(fullPath, vars, root);
+    } else if (entry.name.endsWith('.tmpl')) {
+      let content = fs.readFileSync(fullPath, 'utf8');
+      for (const [key, value] of Object.entries(vars)) {
+        // Function replacement so `$` sequences in values (site names are
+        // user-controlled) are inserted literally, not as $-patterns.
+        content = content.replaceAll(`{{${key}}}`, () => value);
+      }
+      fs.writeFileSync(fullPath.replace(/\.tmpl$/, ''), content);
+      fs.unlinkSync(fullPath);
+    }
+  }
+}
+
+/**
+ * Assemble a complete site tree from the SDK templates.
+ *
+ * @param {object} opts
+ * @param {string} opts.templatesDir  absolute path to the templates root
+ * @param {string} opts.framework     'nextjs' | 'astro'
+ * @param {string} opts.destDir       absolute destination (created if missing)
+ * @param {{siteName: string, version: string, aciVersion: string}} opts.vars
+ */
+export function materializeTemplate({ templatesDir, framework, destDir, vars }) {
+  const commonDir = path.join(templatesDir, 'common');
+  const templateDir = path.join(templatesDir, framework, 'template');
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`unknown framework template: ${templateDir}`);
+  }
+  for (const key of ['siteName', 'version', 'aciVersion']) {
+    if (!vars[key]) throw new Error(`materializeTemplate: vars.${key} is required`);
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const dir of COMMON_DIRS) {
+    copyDirSync(path.join(commonDir, dir), path.join(destDir, dir));
+  }
+  for (const file of COMMON_ROOT_FILES) {
+    const src = path.join(commonDir, file);
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(destDir, file));
+  }
+  copyDirSync(path.join(commonDir, 'public', 'assets'), path.join(destDir, 'public', 'assets'));
+  const readmeTmpl = path.join(commonDir, 'README.md.tmpl');
+  if (fs.existsSync(readmeTmpl)) {
+    fs.copyFileSync(readmeTmpl, path.join(destDir, 'README.md.tmpl'));
+  }
+
+  copyDirSync(templateDir, destDir);
+
+  // Shared sources overwrite any framework-template copies so contracts and
+  // design tokens can only come from templates/common.
+  copyDirSync(
+    path.join(commonDir, 'contracts', 'components'),
+    path.join(destDir, 'src', 'cms', 'contracts', 'components'),
+  );
+  copyDirSync(
+    path.join(commonDir, 'design-system', 'tokens'),
+    path.join(destDir, 'src', 'design-system', 'tokens'),
+  );
+  const stylesSrc = path.join(commonDir, 'design-system', 'styles.css');
+  if (fs.existsSync(stylesSrc)) {
+    fs.mkdirSync(path.join(destDir, 'src', 'design-system'), { recursive: true });
+    fs.copyFileSync(stylesSrc, path.join(destDir, 'src', 'design-system', 'styles.css'));
+  }
+
+  // npm pack drops `.gitignore` files from the published templates, so the
+  // framework templates ship `gitignore` and it is renamed on materialize.
+  const gitignore = path.join(destDir, 'gitignore');
+  if (fs.existsSync(gitignore)) {
+    fs.renameSync(gitignore, path.join(destDir, '.gitignore'));
+  }
+
+  renderTmplFiles(destDir, { ...FRAMEWORK_VARS[framework], ...vars });
+}

package/src/cli/verify-next-cdn-routes.mjs

@@ -31,20 +31,6 @@ function checkMissing(label, relativePath, message) {
   checks.push(`✓ ${label}`);
 }
 
-function checkOptionalFile(label, relativePath, validate, message) {
-  const fullPath = path.join(projectRoot, relativePath);
-  if (!fs.existsSync(fullPath)) {
-    checks.push(`- ${label}: ${relativePath} not found (optional)`);
-    return;
-  }
-  const content = fs.readFileSync(fullPath, 'utf-8');
-  if (!validate(content)) {
-    checks.push(`✗ ${label}: ${message}`);
-    return;
-  }
-  checks.push(`✓ ${label}`);
-}
-
 checkFile(
   'middleware is configured',
   'src/middleware.ts',
@@ -60,17 +46,22 @@ checkFile(
   'Expected catch-all page to use createPage() from the SDK.',
 );
 
-checkFile(
-  'public asset route exists',
+checkMissing(
+  'legacy required catch-all is removed',
+  'src/app/[...slug]/page.tsx',
+  'Use src/app/[[...slug]]/page.tsx (optional catch-all). The required [...slug] form breaks file-provider local dev where "/" arrives with an empty slug.',
+);
+
+checkMissing(
+  'legacy app-level asset route is removed',
   'src/app/gradial/assets/[...path]/route.ts',
-  (content) => content.includes('@gradial/aci/next/asset-route'),
-  'Expected public asset route to re-export @gradial/aci/next/asset-route.',
+  'Assets are served via URL rewrites in withAci(), not an app-level route.',
 );
 
 checkMissing(
   'legacy release-scoped asset route is removed',
   'src/app/gradial/assets/[releaseId]/[...path]/route.ts',
-  'Use src/app/gradial/assets/[...path]/route.ts instead. Assets are now public, not release-scoped.',
+  'Assets are served via URL rewrites in withAci(), not an app-level route.',
 );
 
 checkMissing(

package/templates/astro/starter-content/src/cms/contracts/components/button.contract.ts

@@ -0,0 +1,19 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  label: z.string().min(1),
+  href: z.string().min(1),
+  variant: z.enum(['primary', 'secondary', 'outline', 'tertiary']).optional(),
+  newWindow: z.boolean().optional(),
+  icon: z.string().optional(),
+  iconPosition: z.enum(['before', 'after']).optional(),
+  className: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const buttonContract = defineComponentContract({
+  id: 'button',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/contracts/components/container.contract.ts

@@ -0,0 +1,19 @@
+import { defineComponentContract, blockRefArray } from '@gradial/aci';
+import { z } from 'zod';
+import { buttonContract } from './button.contract';
+import { featureGridContract } from './featureGrid.contract';
+import { featureCardContract } from './featureCard.contract';
+import { statsBarContract } from './statsBar.contract';
+
+export const schema = z.object({
+  theme: z.enum(['auto', 'light', 'dark']).optional(),
+  className: z.string().optional(),
+  content: blockRefArray([buttonContract, featureGridContract, featureCardContract, statsBarContract]).optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const containerContract = defineComponentContract({
+  id: 'container',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/contracts/components/featureCard.contract.ts

@@ -0,0 +1,15 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  icon: z.string().optional(),
+  title: z.string().min(1),
+  description: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const featureCardContract = defineComponentContract({
+  id: 'feature_card',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/contracts/components/featureGrid.contract.ts

@@ -0,0 +1,16 @@
+import { defineComponentContract, blockRefArray } from '@gradial/aci';
+import { z } from 'zod';
+import { featureCardContract } from './featureCard.contract';
+
+export const schema = z.object({
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  features: blockRefArray([featureCardContract]).optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const featureGridContract = defineComponentContract({
+  id: 'feature_grid',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/contracts/components/homeHero.contract.ts

@@ -0,0 +1,36 @@
+import { defineComponentContract, ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  eyebrow: z.string().optional(),
+  headline: z.string().min(1),
+  description: z.string().optional(),
+  ctaLabel: z.string().min(1),
+  ctaHref: z.string().min(1),
+  image: ImageSchema.optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const homeHeroContract = defineComponentContract({
+  id: 'home_hero',
+  props: schema,
+  imageSlots: {
+    image: {
+      formats: ['image/avif', 'image/webp', 'image/jpeg'],
+      sizes: '100vw',
+      outputs: [
+        {
+          aspectRatio: '16:9',
+          widths: [768, 1280, 1920],
+          media: '(min-width: 768px)',
+        },
+        {
+          aspectRatio: '3:4',
+          widths: [480, 720, 960],
+          media: '(max-width: 767px)',
+        },
+      ],
+    },
+  },
+});

package/templates/astro/starter-content/src/cms/contracts/components/index.ts

@@ -0,0 +1,21 @@
+import { buttonContract } from './button.contract';
+import { containerContract } from './container.contract';
+import { featureCardContract } from './featureCard.contract';
+import { featureGridContract } from './featureGrid.contract';
+import { homeHeroContract } from './homeHero.contract';
+import { siteNavigationContract } from './siteNavigation.contract';
+import { siteFooterContract } from './siteFooter.contract';
+import { statsBarContract } from './statsBar.contract';
+
+const componentContracts = [
+  homeHeroContract,
+  containerContract,
+  buttonContract,
+  siteNavigationContract,
+  siteFooterContract,
+  featureGridContract,
+  featureCardContract,
+  statsBarContract,
+];
+
+export default componentContracts;

package/templates/astro/starter-content/src/cms/contracts/components/statsBar.contract.ts

@@ -0,0 +1,19 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+const statSchema = z.object({
+  label: z.string().min(1),
+  value: z.string().min(1),
+  suffix: z.string().optional(),
+});
+
+export const schema = z.object({
+  stats: z.array(statSchema).min(1),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const statsBarContract = defineComponentContract({
+  id: 'stats_bar',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/registry.ts

@@ -0,0 +1,28 @@
+import { createRegistry } from '@gradial/aci';
+import { homeHeroContract } from './contracts/components/homeHero.contract';
+import { containerContract } from './contracts/components/container.contract';
+import { buttonContract } from './contracts/components/button.contract';
+import { siteNavigationContract } from './contracts/components/siteNavigation.contract';
+import { siteFooterContract } from './contracts/components/siteFooter.contract';
+import { featureGridContract } from './contracts/components/featureGrid.contract';
+import { featureCardContract } from './contracts/components/featureCard.contract';
+import { statsBarContract } from './contracts/components/statsBar.contract';
+import HomeHero from '../components/sections/HomeHero.astro';
+import ContainerSection from '../components/sections/ContainerSection.astro';
+import ButtonBlock from '../components/elements/ButtonBlock.astro';
+import Header from '../components/chrome/Header.astro';
+import Footer from '../components/chrome/Footer.astro';
+import FeatureGrid from '../components/sections/FeatureGrid.astro';
+import FeatureCard from '../components/sections/FeatureCard.astro';
+import StatsBar from '../components/sections/StatsBar.astro';
+
+export const registry = createRegistry([
+  [homeHeroContract, HomeHero],
+  [containerContract, ContainerSection],
+  [buttonContract, ButtonBlock],
+  [siteNavigationContract, Header],
+  [siteFooterContract, Footer],
+  [featureGridContract, FeatureGrid],
+  [featureCardContract, FeatureCard],
+  [statsBarContract, StatsBar],
+]);

package/templates/astro/template/{.aci.yaml → .aci.yaml.tmpl}

@@ -1,5 +1,5 @@
 version: "1"
-siteId: "site_astro"
+siteId: "{{siteName}}"
 domain: "meridian.local"
 framework: astro
 

package/templates/astro/template/README.md.tmpl

@@ -0,0 +1,53 @@
+# {{siteName}}
+
+An Astro site powered by [ACI](https://docs.gradial.com/aci) (Agentic Content Infrastructure).
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+The dev server starts at `http://localhost:4321`. Content changes in `.content/`
+are picked up automatically via the ACI integration in `astro.config.mjs`.
+
+## Adding Your First Component
+
+See `.agents/skills/authoring/SKILL.md` for a step-by-step guide to:
+1. Define a component contract in `src/cms/contracts/components/`
+2. Build the Astro component in `src/components/`
+3. Register it in `src/cms/registry.ts`
+4. Add content to `.content/pages/`
+
+## Skills
+
+| Skill | When to read |
+|-------|-------------|
+| [aci](.agents/skills/aci/SKILL.md) | Architecture, commands, testing, troubleshooting |
+| [authoring](.agents/skills/authoring/SKILL.md) | Creating content, building components, design tokens |
+| [migration](.agents/skills/migration/SKILL.md) | Migrating an existing site into ACI |
+
+## Commands
+
+```bash
+npm run dev              # Start Astro dev server (auto-compiles content)
+npm run build            # Production build
+npm run preview          # Preview production build locally
+npm run typecheck        # TypeScript type checking
+npm test                 # Run conformance tests
+npm run content:compile  # Compile content into .aci/compiled/
+```
+
+## Project Structure
+
+```
+.aci.yaml              ACI config (siteId, framework, routes)
+.content/              Content source (JSON pages, config, fragments)
+src/cms/               Contracts and component registry
+src/components/        Runtime Astro components
+src/design-system/     Design tokens and global styles
+src/pages/             Astro file-based routing
+src/layouts/           Page layout wrappers
+.agents/skills/        Skills for humans and agents
+```

package/templates/astro/template/gitignore

@@ -0,0 +1,12 @@
+/dist/
+/node_modules/
+/.astro/
+/.aci/compiled/
+/.baremetal/
+storybook-static/
+*.log
+.env
+.DS_Store
+test-screenshot.png
+pnpm-lock.yaml
+pnpm-workspace.yaml

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

@@ -8,13 +8,15 @@
     "build": "astro build",
     "preview": "ACI_CONTENT_ROOT=./.aci/compiled astro preview --host 0.0.0.0",
     "typecheck": "ACI_CONTENT_ROOT=./.aci/compiled astro check --tsconfig ./tsconfig.json",
-    "aci:compile": "node ./node_modules/@gradial/aci/bin/aci.js content compile --content ./.content --out ./.aci",
+    "test": "node --import tsx --test tests/**/*.test.ts",
     "content:compile": "node ./node_modules/@gradial/aci/bin/aci.js content compile --content ./.content --out ./.aci/compiled",
-    "aci:doctor": "node ./node_modules/@gradial/aci/bin/aci.js doctor",
-    "aci:validate": "node ./node_modules/@gradial/aci/bin/aci.js doctor",
     "storybook": "storybook dev -p 6006",
     "build:storybook": "storybook build"
   },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
   "dependencies": {
     "@astrojs/node": "^10.1.4",
     "@gradial/aci": "{{aciVersion}}",

package/templates/astro/template/src/cms/contracts/components/index.ts

@@ -0,0 +1,3 @@
+const componentContracts: readonly unknown[] = [];
+
+export default componentContracts;

package/templates/astro/template/src/cms/registry.ts

@@ -1,28 +1,5 @@
 import { createRegistry } from '@gradial/aci';
-import { homeHeroContract } from './contracts/components/homeHero.contract';
-import { containerContract } from './contracts/components/container.contract';
-import { buttonContract } from './contracts/components/button.contract';
-import { siteNavigationContract } from './contracts/components/siteNavigation.contract';
-import { siteFooterContract } from './contracts/components/siteFooter.contract';
-import { featureGridContract } from './contracts/components/featureGrid.contract';
-import { featureCardContract } from './contracts/components/featureCard.contract';
-import { statsBarContract } from './contracts/components/statsBar.contract';
-import HomeHero from '../components/sections/HomeHero.astro';
-import ContainerSection from '../components/sections/ContainerSection.astro';
-import ButtonBlock from '../components/elements/ButtonBlock.astro';
-import Header from '../components/chrome/Header.astro';
-import Footer from '../components/chrome/Footer.astro';
-import FeatureGrid from '../components/sections/FeatureGrid.astro';
-import FeatureCard from '../components/sections/FeatureCard.astro';
-import StatsBar from '../components/sections/StatsBar.astro';
 
-export const registry = createRegistry([
-  [homeHeroContract, HomeHero],
-  [containerContract, ContainerSection],
-  [buttonContract, ButtonBlock],
-  [siteNavigationContract, Header],
-  [siteFooterContract, Footer],
-  [featureGridContract, FeatureGrid],
-  [featureCardContract, FeatureCard],
-  [statsBarContract, StatsBar],
-]);
+// Register your [contract, component] pairs here.
+// See .agents/skills/authoring/SKILL.md for how to add components.
+export const registry = createRegistry([]);

package/templates/astro/template/src/pages/[...slug].astro

@@ -1,47 +1,25 @@
 ---
-import { getGradialStaticPaths, getPageRuntimeRenderInput, createRenderChildren, collectScriptTagHTML } from '@gradial/aci/astro';
-import { normalizeRoute, routeMetadataForContent, resolveSlots } from '@gradial/aci/content';
-import { FileContentProvider } from '@gradial/aci/providers/file';
-import type { KernelPage, KernelSiteConfig, LayoutEntry, FragmentData } from '@gradial/aci/content';
+import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
 import { registry } from '../cms/registry';
 import SiteLayout from '../layouts/SiteLayout.astro';
 
 export const getStaticPaths = getGradialStaticPaths;
 
-const route = normalizeRoute(Astro.params.slug ? `/${Astro.params.slug}` : '/');
-const runtimeInput = getPageRuntimeRenderInput(Astro.request);
-let siteConfig: KernelSiteConfig;
-let page: KernelPage;
-let provider: FileContentProvider;
-if (runtimeInput) {
-  siteConfig = runtimeInput.siteConfig as KernelSiteConfig;
-  page = runtimeInput.page as KernelPage;
-} else {
-  provider = new FileContentProvider();
-  [siteConfig, page] = await Promise.all([
-    provider.getSiteConfig<KernelSiteConfig>(),
-    provider.getPage<KernelPage>(route),
-  ]);
-}
-
-const meta = routeMetadataForContent(siteConfig, page);
-const layout = (runtimeInput?.layouts?.[page.layout] ?? await (provider ?? new FileContentProvider()).getLayout<LayoutEntry>(page.layout)) as LayoutEntry;
-const resolvedSlots = await resolveSlots(
-  layout,
-  page?.regions || {},
-  async (id) => {
-    if (runtimeInput?.fragments?.[id]) return runtimeInput.fragments[id] as FragmentData;
-    return await (provider ?? new FileContentProvider()).getFragment<FragmentData>(id);
-  }
-);
-
+// SDK owns route normalization, content loading, metadata, layout/slot
+// resolution, and collect-tag emission. No FileContentProvider imports.
+const data = await getPageData(Astro);
 const renderChildren = createRenderChildren(registry);
-const collectTag = collectScriptTagHTML(siteConfig);
 ---
 
-<SiteLayout title={meta.title} description={meta.description} canonical={meta.canonical} siteName={meta.siteName} collectTag={collectTag}>
-  {layout.slots.map((slot) => {
-    const blocks = resolvedSlots[slot.name];
+<SiteLayout
+  title={data.meta.title}
+  description={data.meta.description}
+  canonical={data.meta.canonical}
+  siteName={data.meta.siteName}
+  collectTag={data.collectTag}
+>
+  {data.layout.slots.map((slot) => {
+    const blocks = data.slots[slot.name];
     if (!blocks?.length) return null;
     const rendered = renderChildren(blocks);
     if (slot.name === 'main') {

package/templates/astro/template/tests/conformance.test.ts.tmpl

@@ -0,0 +1,12 @@
+/**
+ * ACI Conformance Tests
+ *
+ * Validates that the site conforms to canonical ACI integration patterns.
+ * See https://docs.gradial.com/aci/testing for details.
+ */
+import { conformancePreset } from '@gradial/aci/testing';
+
+conformancePreset({
+  framework: 'astro',
+  siteId: '{{siteName}}',
+});

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

@@ -33,10 +33,8 @@ Skills live in `.agents/skills/`. Each has a `SKILL.md` entry point and
 
 ```bash
 npm install
-npm run dev              # Start dev server
-npm run aci:validate     # Validate content
-npm run aci:compile      # Compile contracts
-npm run content:compile  # Compile content
+npm run dev              # Start dev server (compiles content on startup)
+npm run content:compile  # Compile content from .content/ into .aci/
 npm run build            # Framework build
-npm run aci:doctor       # Health check
+npm test                 # Conformance tests
 ```