@gradial/aci 0.1.30 → 0.1.33

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

@@ -5,6 +5,31 @@ description: Onboarding, running builds, validating, and troubleshooting ACI sit
 
 # ACI — Onboarding and Troubleshooting
 
+## Creating a New Site
+
+```bash
+# Scaffold-only (default) — golden-path skeleton, no demo content
+# Astro is standard for new customer sites
+aci init my-site --template astro-starter
+
+# Next.js is for specific SSR properties
+aci init my-site --template next-starter
+
+# With demo content, components, and stories
+aci init my-site --template astro-starter --with-starter-content
+
+# List available templates
+aci init --list
+```
+
+The **scaffold** is the new-customer entry point: config, framework wiring,
+page route, empty registry, design system, and agent skills. Add your own
+contracts and components from here.
+
+The **--with-starter-content** flag overlays demo material on top of the
+scaffold: `.content/` fixtures, demo components (sections, elements, chrome),
+a full registry, stories, and fixtures.
+
 ## How ACI Works
 
 ```
@@ -41,8 +66,11 @@ Each framework uses a packaged SDK adapter for ACI dev/build behavior:
 - **Next.js**: `withAci()` in `next.config.ts`
 
 These adapters own canonical ACI behavior: content watch/reload, local DAM
-derivative serving at `/.gradial-dam/*`, and asset path rewrites. Do not
-copy site-local middleware for these concerns.
+derivative serving at `/.gradial-dam/*`, asset path rewrites, output mode,
+outputFileTracingRoot, base-path/build-mode/dist-dir env injection, CDN
+headers, and content-watch plugin. Repos should pass an empty `withAci()`
+call and rely on SDK defaults. Use `passthroughRoutes` only for
+site-specific non-CMS routes.
 
 Only Next.js and Astro are supported. SvelteKit support has been removed.
 
@@ -52,14 +80,11 @@ All commands run from the site directory (where `.aci.yaml` lives).
 
 | Command | Purpose |
 |---------|---------|
-| `npm run aci:compile` | Compile contract registry. Run after changing contracts. |
-| `npm run content:compile` | Compile content from `.content/` into `.aci/compiled/`. |
-| `npm run aci:validate` | Validate content against schemas without building. |
-| `npm run aci:doctor` | Check project health: config, content, schemas, routes. |
-| `npm run aci:build` | Full build: contracts + content + framework. |
+| `npm run dev` | Start dev server with content hot-reload (auto-compiles content). |
+| `npm run build` | Framework production build. |
 | `npm run typecheck` | TypeScript type checking. |
-| `npm run build` | Framework build. |
-| `npm run dev` | Start dev server with content hot-reload. |
+| `npm test` | Run conformance tests. |
+| `npm run content:compile` | Compile content from `.content/` into `.aci/compiled/`. Standard: `aci content compile --content .content --out .aci/compiled` |
 
 ## Development Workflow
 
@@ -67,39 +92,63 @@ All commands run from the site directory (where `.aci.yaml` lives).
 
 ```bash
 npm install
-npm run aci:compile
 npm run dev
 ```
 
+The dev server compiles content on startup — no manual compile needed.
+
 The dev server watches for content changes and re-compiles automatically
 via the framework's ACI adapter. Edit `.content/` files and see changes
-in the browser.
+in the browser. No manual compile step needed before `dev`.
 
 ### Full local build
 
 ```bash
-npm run aci:compile
 npm run content:compile
 npm run typecheck
-npm run build
 ```
 
 ### Content editing loop
 
 1. Edit `.content/pages/{slug}/_index.json` or `.content/config/site.json`.
-2. Run `npm run aci:validate` to check content is valid.
-3. Run `npm run content:compile` to compile content.
-4. Run `npm run build` to build the site.
-5. Check the output for your changes.
+2. Run `npm run content:compile` to compile content.
+3. Run `npm run build` to build the site.
+4. Check the output for your changes.
 
 ## Test Order (Fastest to Slowest)
 
-1. `npm run aci:validate` — content validation
-2. `npm run aci:compile` — contract compile
-3. `npm run typecheck` — TypeScript
-4. `npm run content:compile` — content compile
-5. `npm run build` — framework build
-6. `npm run build:storybook` — Storybook (if configured)
+1. `npm run typecheck` — TypeScript
+2. `npm test` — conformance tests
+3. `npm run content:compile` — content compile
+4. `npm run build` — framework build
+5. `npm run build:storybook` — Storybook (if configured)
+
+## Conformance Checks
+
+Repos run conformance tests in CI using the `@gradial/aci/testing` preset:
+
+```ts
+import { conformancePreset } from '@gradial/aci/testing';
+
+conformancePreset({
+  framework: 'next',
+  siteId: 'your-tenant-id',
+});
+```
+
+Default checks validate:
+- `config` -- `withAci()` present in config
+- `registry` -- `createRegistry()` usage (no hand-rolled maps)
+- `pageEntry` -- `createPage(registry)` usage in catch-all route
+- `middleware` -- `createGradialMiddleware({ siteId })` with correct siteId
+- `noFileContentProvider` -- no direct `FileContentProvider` imports in app code
+- `noCustomContent` -- no `src/lib/content.ts` shim
+- `noLegacyAssetRoute` -- no `[releaseId]` segment in asset route path
+- `sdkVersion` -- SDK version compatibility
+
+Optional (disabled by default):
+- `buildSucceeds` -- full build completes
+- `contentCompile` -- content compilation succeeds
 
 ## Troubleshooting
 

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

@@ -12,6 +12,7 @@ description: Author content and build components for ACI sites. Use when creatin
 | Path | Purpose |
 |------|---------|
 | `.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) |
 | `.aci/schemas/page.schema.json` | Page validation schema (auto-generated from contracts) |
@@ -28,7 +29,8 @@ Every page JSON requires:
   "layout": "default",
   "metadata": {
     "title": "Page Title",
-    "description": "Meta description"
+    "description": "Meta description",
+    "sitemap": { "visible": true }
   },
   "regions": {
     "main": []
@@ -36,6 +38,35 @@ Every page JSON requires:
 }
 ```
 
+Base page fields are SDK-owned and included in the generated
+`.aci/schemas/page.schema.json`.
+
+#### Sitemap visibility
+
+`metadata.sitemap.visible` controls whether the page appears in the generated
+`sitemap.xml` release artifact:
+
+- **Omit or `true`** (default) — the page is included in the sitemap when other
+  filters allow it (published status, robots.txt rules).
+- **`false`** — the page is excluded from the sitemap. The page still renders
+  normally; only its sitemap presence changes.
+
+```json
+{
+  "metadata": {
+    "title": "Private Campaign Page",
+    "sitemap": { "visible": false }
+  }
+}
+```
+
+Use `false` for pages that should publish but stay out of search engine
+discovery: temporary campaign pages, event-specific landing pages, staging
+pages, or pages already blocked by `robots.txt` (setting it explicitly makes
+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
@@ -400,8 +431,7 @@ framework.
 #### 6. Verify
 
 ```bash
-npm run aci:compile     # Contract compiles
-npm run aci:validate    # Content validates
+npm run aci:compile     # Contracts + content compile
 npm run typecheck       # Types check
 npm run build           # Framework builds
 ```
@@ -446,24 +476,26 @@ type Props = ContentProps & { className?: string };
 ### Layout Contracts
 
 Layouts define page-level slot structure and optional fragment defaults
-for chrome. Fragment defaults let CMS-managed fragments (navbar, footer)
-fill slots automatically when the page doesn't provide blocks for them:
+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: [
-      { name: 'header', required: false }, // filled by fragment default
-      { name: 'main', required: true },    // filled by page regions
-      { name: 'footer', required: false }, // filled by fragment default
+      slot('header'),         // filled by fragment default
+      slot('main', true),     // filled by page regions (required)
+      slot('footer'),         // filled by fragment default
     ],
     defaults: {
-      header: [{ kind: 'fragment-ref', fragmentId: 'navbar', inline: true }],
-      footer: [{ kind: 'fragment-ref', fragmentId: 'site-footer', inline: true }],
+      header: fragmentDefault('navbar'),
+      footer: fragmentDefault('site-footer'),
     },
-  },
+  }),
 ];
 ```
 
@@ -553,14 +585,21 @@ Three theme classes control semantic token resolution:
 
 ## Storybook
 
-Every ACI frontend repo should have Storybook configured. Stories live
-under `src/stories/` and follow the framework's Storybook setup.
+Every ACI frontend repo should have Storybook configured. Use **Storybook 10+**
+with the framework-specific adapter:
+
+- **Next.js**: `@storybook/nextjs-vite`
+- **Astro**: `@storybook-astro/framework`
+
+Stories live under `src/stories/` and follow the framework's Storybook setup.
 
 ```bash
 npm run storybook         # Dev mode
 npm run build:storybook   # Build all stories
 ```
 
+All repos should converge on Storybook 10. Repos on Storybook 9 should upgrade.
+
 ## Deep Dive: Component Registry
 
 Read `references/block-registry.md` for the `createRegistry` pattern,

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

@@ -45,18 +45,31 @@ The SDK provides `createPage(registry)` which owns param normalization, content
 loading, layout resolution, metadata generation, notFound handling, slot
 resolution (including fragment defaults), and block rendering.
 
+Path shape: `/__r/{releaseId}/routes/{...slug}`. The SDK extracts releaseId
+internally; middleware rewrites public URLs to `/__r/{releaseId}/routes/{path}`
+for the app-level route. The `routes` namespace leaves room for future siblings
+under the release prefix. The filesystem uses an **optional catch-all** `[[...slug]]`
+(not required `[...slug]`). Production middleware always rewrites to
+`/__r/{releaseId}/routes/{path}`, but file-provider local dev passes requests
+unrewritten so `/` arrives with an empty slug.
+
 Chrome (Header/Footer) is **not** in `layout.tsx`. It is CMS-managed via
-layout fragment defaults. The `layout.tsx` file is minimal:
+layout fragment defaults. The `layout.tsx` file is minimal and includes
+`<DevRefresh />`:
 
 ```tsx
 // src/app/layout.tsx — minimal, no chrome
 import type { ReactNode } from 'react';
+import { DevRefresh } from '@gradial/aci/next';
 import '@/design-system/styles.css';
 
 export default function Layout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body>
+        {children}
+        <DevRefresh />
+      </body>
     </html>
   );
 }
@@ -95,23 +108,83 @@ an app-owned HTTP endpoint backed by a server-side `ContentProvider`.
 
 ## Astro Pattern
 
-Astro uses a catch-all route and renders via the shared registry:
+The SDK provides `getPageData(Astro)` as the Astro equivalent of Next.js
+`createPage`. It encapsulates route normalization, content resolution (preview
+render input vs FileContentProvider), metadata derivation, layout resolution,
+slot filling, and collect-tag emission into a single call.
 
 ```astro
 ---
 // src/pages/[...slug].astro
-import { createPage } from '@gradial/aci/astro/page';
-import { registry } from '@/cms/registry';
+import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
 
-const page = createPage(registry);
-export const getStaticPaths = page.getStaticPaths;
-export default page.default;
+export const getStaticPaths = getGradialStaticPaths;
+
+const data = await getPageData(Astro);
+const renderChildren = createRenderChildren(registry);
 ---
+
+<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') {
+      return (
+        <main id="content-main">
+          {rendered.map((child) => {
+            const Comp = child.Component;
+            return Comp ? <Comp {...child.props} /> : null;
+          })}
+        </main>
+      );
+    }
+    return rendered.map((child) => {
+      const Comp = child.Component;
+      return Comp ? <Comp {...child.props} /> : null;
+    });
+  })}
+</SiteLayout>
 ```
 
-The `createPage` helper owns param normalization, content loading, layout
-resolution, metadata generation, notFound handling, slot resolution
-(including fragment defaults), and block rendering.
+`getPageData()` returns a `PageData` object with `{ route, siteConfig, page,
+meta, layout, slots, collectTag }`. The page template receives typed data
+and only needs to iterate slots and render blocks via the registry.
+
+For DAM asset URLs, use `damAssetUrl()`:
+
+```astro
+---
+import { damAssetUrl } from '@gradial/aci/astro';
+---
+<img src={damAssetUrl('images/hero.webp')} alt="Hero" />
+```
+
+### Astro Asset Serving
+
+**DAM assets are content-addressed and globally shared.**
+
+DAM derivative assets (processed images, optimized media) are staged ONCE at the
+hosting bucket's global `.gradial-dam/` location. The content-addressed filenames
+contain hashes, so each unique asset is written only once and shared across all
+releases.
+
+The CloudFront function rewrites `/.gradial-dam/*` requests to the global
+`{keyPrefix}/.gradial-dam/*` S3 path with no release lookup. These assets are
+served with immutable caching (`max-age=31536000`) because the filenames contain
+content hashes.
+
+No separate CloudFront origin behavior is needed — the existing CloudFront
+function in `infra/modules/hosting-cloudfront-site/function.js.tftpl` handles
+the rewrite automatically.
 
 ### Astro-Specific Paths
 
@@ -119,26 +192,47 @@ resolution, metadata generation, notFound handling, slot resolution
 |---------|------|
 | Routes | `src/pages/[...slug].astro` |
 | Layout | `src/layouts/SiteLayout.astro` |
-| Config | `astro.config.mjs` with `withAci()` |
+| Config | `astro.config.mjs` with bare `withAci()` |
 | Registry | `src/cms/registry.ts` (shared) |
 | Storybook | `.storybook/main.ts`, `.storybook/preview.ts` |
+| Assets | CloudFront function rewrite (automatic, no infrastructure changes needed) |
 
 ## Middleware
 
+Middleware requires explicit `siteId`. The SDK exports a canonical matcher that
+repos re-export:
+
 ```ts
 // src/middleware.ts
-import { createMiddleware } from '@gradial/aci/next/middleware';
-export default createMiddleware();
+import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 export { config } from '@gradial/aci/next/middleware';
+export default createGradialMiddleware({ siteId: 'your-tenant-id' });
 ```
 
+The middleware rewrites public URLs to `/__r/{releaseId}/routes/{path}` for
+the app-level route. The SDK extracts releaseId internally.
+
 ## Asset Routes
 
+**Preferred: NO app-level asset route.** Assets are served via URL rewrite
+(Next.js `withAci()`) or CloudFront function rewrite (Astro/CloudFront) directly
+to S3.
+
+DAM derivative assets are content-addressed and globally shared — staged once at
+`{keyPrefix}/.gradial-dam/` and shared across all releases. The SDK's `withAci()`
+already injects a `/.gradial-dam/:path*` rewrite. For CloudFront, the existing
+CloudFront function handles the rewrite automatically.
+
+For transitional compatibility, the SDK still exports an asset route handler:
+
 ```ts
-// src/app/gradial/assets/[releaseId]/[...path]/route.ts
+// src/app/gradial/assets/[...path]/route.ts (transitional)
 export { GET, runtime, dynamic } from '@gradial/aci/next/asset-route';
 ```
 
+**Note**: Asset URLs do NOT include `[releaseId]` in the path. DAM assets are
+globally scoped and content-addressed via filename hashes.
+
 ## Anti-Patterns
 
 - `Record<string, any>` or `Record<string, ComponentType<any>>` — hides type errors

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

@@ -61,15 +61,25 @@ export default [heroContract, buttonContract];
 
 ## Layout Contract API
 
+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: [
-      { name: 'main', required: true },
-      { name: 'footer', required: false },
+      slot('header'),
+      slot('main', true),
+      slot('footer'),
     ],
-  },
+    defaults: {
+      header: fragmentDefault('site-header'),
+      footer: fragmentDefault('site-footer'),
+    },
+  }),
 ];
 ```
 
@@ -79,12 +89,14 @@ Content pages reference layouts by name:
 {
   "layout": "marketing",
   "regions": {
-    "main": [...],
-    "footer": [...]
+    "main": [...]
   }
 }
 ```
 
+The `header` and `footer` slots are filled automatically by fragment defaults
+when the page doesn't provide blocks for them.
+
 ## Multiple Runtime Mappings
 
 One runtime component may implement multiple contract names. Define
@@ -117,7 +129,7 @@ capabilities:
   fragmentRender: true
 
 routes:
-  cmsManaged: "/[...slug]"
+  cmsManaged: "/[[...slug]]"
   frameworkOwned:
     - "/api/*"
     - "/_next/*"       # Next.js
@@ -151,3 +163,7 @@ rendererProtocol: stdio-json
 
 - `componentRegistry` and `layoutRegistry` point to contract-only modules.
 - 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. Production middleware always rewrites
+  to `/__r/{releaseId}/routes/{path}` so slug is non-empty, but file-provider
+  local dev passes requests unrewritten so `/` arrives with an empty slug.

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

@@ -1,7 +1,21 @@
 # Repository Structure Reference
 
+## Generation Modes
+
+The `aci init` command generates sites in two modes:
+
+| Mode | Command | What you get |
+|------|---------|-------------|
+| **Scaffold** (default) | `aci init my-site --template next-starter` | Golden-path skeleton: config, framework wiring, page route, empty registry, design system, agent skills. No demo content or components. This is the starting point for a new customer. |
+| **With starter content** | `aci init my-site --template next-starter --with-starter-content` | Scaffold + demo content (`.content/`), demo components (sections, elements, chrome), full registry, stories, and fixtures. Use for demos or learning. |
+
+Available templates: `next-starter`, `astro-starter`.
+
 ## Directory Layout
 
+The scaffold generates the structure below. Items marked **(starter content only)** are
+only present when `--with-starter-content` is used.
+
 ```
 .aci.yaml                        ACI config: contract paths, framework, routes
 package.json                     Dependencies and scripts
@@ -11,7 +25,7 @@ tsconfig.json                    TypeScript config
     site.json                    Site metadata, navigation, footer, branding, SEO
   pages/
     home/_index.json             Homepage (route /)
-    about/_index.json            About page (route /about)
+    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)
@@ -19,14 +33,14 @@ src/
   cms/
     contracts/
       components/                Component contracts (framework-agnostic)
-        homeHero.contract.ts     Hero section contract
-        button.contract.ts       Button block contract
-        container.contract.ts    Container (nested blocks) contract
-        featureGrid.contract.ts  Feature grid contract
-        featureCard.contract.ts  Feature card contract
-        statsBar.contract.ts     Stats bar contract
-        siteNavigation.contract.ts  Site navigation contract
-        siteFooter.contract.ts   Site footer contract
+        homeHero.contract.ts     Hero section contract (starter content only)
+        button.contract.ts       Button block contract (starter content only)
+        container.contract.ts    Container (nested blocks) contract (starter content only)
+        featureGrid.contract.ts  Feature grid contract (starter content only)
+        featureCard.contract.ts  Feature card contract (starter content only)
+        statsBar.contract.ts     Stats bar contract (starter content only)
+        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)
@@ -55,7 +69,7 @@ src/
       index.css                  Barrel import for all token files
   app/                           Framework routes (Next.js App Router)
     layout.tsx                   Root layout (minimal, imports CSS only)
-    [[...slug]]/page.tsx         Optional catch-all for all CMS pages
+    [[...slug]]/page.tsx          Optional catch-all for all CMS pages
   pages/                         Framework routes (Astro file-based routing)
     [...slug].astro              Catch-all for all CMS pages
   layouts/                       Page layout wrappers (framework-specific)
@@ -87,11 +101,11 @@ Only Next.js and Astro are supported. SvelteKit support has been removed.
 | Concern | Path |
 |---------|------|
 | Routes | `src/app/[[...slug]]/page.tsx` (optional catch-all, `force-dynamic`) |
-| Root layout | `src/app/layout.tsx` (minimal — imports CSS, no chrome) |
-| Config | `next.config.ts` with `withAci()` |
+| Root layout | `src/app/layout.tsx` (minimal — imports CSS, includes `<DevRefresh />`, no chrome) |
+| Config | `next.config.ts` with bare `withAci()` |
 | Registry | `src/cms/registry.ts` (shared, `createRegistry` with `[contract, component]` tuples) |
-| Middleware | `src/middleware.ts` |
-| Asset routes | `src/app/gradial/assets/[releaseId]/[...path]/route.ts` |
+| Middleware | `src/middleware.ts` with `createGradialMiddleware({ siteId })` and SDK-exported matcher |
+| Asset route | `src/app/gradial/assets/[...path]/route.ts` — thin SDK re-export from `@gradial/aci/next/asset-route`. Serves CMS documents (robots.txt, sitemap.xml) via withAci rewrites and local-dev DAM assets. Hand-rolled asset routes and the legacy release-scoped `[releaseId]/[...path]` variant are banned. Astro has no route (CDN/global path). |
 
 ### Astro
 
@@ -145,13 +159,15 @@ Standard scripts across all frameworks:
     "dev": "...",
     "build": "...",
     "typecheck": "...",
-    "aci:compile": "aci build --compile-only",
-    "content:compile": "aci build --skip-code --content ./.content --out ./.aci/compiled",
-    "aci:build": "aci build --content ./.content",
-    "aci:doctor": "aci doctor",
-    "aci:validate": "aci build --validate-only"
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "content:compile": "aci content compile --content .content --out .aci/compiled"
   }
 }
 ```
 
+The `dev` command auto-compiles content; no manual compile step is needed
+before starting the dev server.
+
 Customer repos use `npm` as the package manager. The monorepo uses `pnpm`.
+
+**Note**: `aci doctor` has been removed. Use the `@gradial/aci/testing` conformance preset in CI instead.