@gradial/aci 0.1.53-rc.1 → 0.1.53-rc.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### Added
+
+- Page `metadata.robots` accepts boolean `index` and `follow` directives.
+  Next and Astro emit the corresponding HTML tag. Publish excludes pages with
+  `index: false` from the release sitemap.
+
+### Migration required
+
+- Existing Astro sites must install `@gradial/aci/astro/Head` and pass resolved
+  metadata as one object through their route and layout. Next sites must upgrade
+  the SDK and rebuild. See [page metadata migration](./migrations/page-metadata-head.md).
+  Packed starter HTML checks in `make test-frontend-contract` verify the tags.
+  Sitemap exclusion can precede an SDK upgrade. Inspect the rendered preview
+  before telling an author that `noindex` is present. No platform test currently
+  enforces that check on older site builds.
+
 ### Changed
 
 - Immutable code builds (`ACI_CODE_ARTIFACT_BUILD=1`) no longer read or compile

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.53-rc.1` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.53-rc.2` 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.53-rc.1 zod@^4
+npm install @gradial/aci@0.1.53-rc.2 zod@^4
 ```
 
 ## Root Import
@@ -137,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.1 init my-site --template next-starter
+npx @gradial/aci@0.1.53-rc.2 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.1 init --list
+npx @gradial/aci@0.1.53-rc.2 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/cli/compile-registry.mjs

@@ -503,6 +503,14 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
                     title: { type: 'string', minLength: 1 },
                     description: { type: 'string' },
                     canonical: { type: 'string' },
+                    robots: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            index: { type: 'boolean' },
+                            follow: { type: 'boolean' },
+                        },
+                    },
                 },
             },
             regions: {

package/dist/content/provider.d.ts

@@ -1,4 +1,4 @@
-import type { KernelPage, KernelRouteMetadata, KernelSiteConfig, RenderInput } from './types.js';
+import type { KernelPage, KernelPageRobots, KernelRouteMetadata, KernelSiteConfig, RenderInput } from './types.js';
 export interface RouteEntry {
     slug: string;
     path: string;
@@ -78,3 +78,9 @@ export interface RenderInputOptions {
 }
 export declare function loadRenderInput(provider: ContentProvider, route: string | undefined, options: RenderInputOptions): Promise<RenderInput>;
 export declare function routeMetadataForContent(siteConfig: KernelSiteConfig, page: KernelPage | null): KernelRouteMetadata;
+/**
+ * Serializes page robots directives to a `<meta name="robots">` content
+ * value, matching what Next.js emits for the same object. Returns '' when
+ * no directive is set, so templates can skip the tag.
+ */
+export declare function robotsMetaContent(robots: KernelPageRobots | undefined): string;

package/dist/content/provider.js

@@ -53,6 +53,33 @@ export function routeMetadataForContent(siteConfig, page) {
         title,
         description,
         canonical: page?.metadata?.canonical,
+        robots: pageRobots(page?.metadata?.robots),
         siteName: siteConfig.seo?.siteName || siteConfig.title
     };
 }
+function pageRobots(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const { index, follow } = value;
+    const robots = {};
+    if (typeof index === 'boolean')
+        robots.index = index;
+    if (typeof follow === 'boolean')
+        robots.follow = follow;
+    return robots.index === undefined && robots.follow === undefined ? undefined : robots;
+}
+/**
+ * Serializes page robots directives to a `<meta name="robots">` content
+ * value, matching what Next.js emits for the same object. Returns '' when
+ * no directive is set, so templates can skip the tag.
+ */
+export function robotsMetaContent(robots) {
+    if (!robots)
+        return '';
+    const directives = [];
+    if (robots.index !== undefined)
+        directives.push(robots.index ? 'index' : 'noindex');
+    if (robots.follow !== undefined)
+        directives.push(robots.follow ? 'follow' : 'nofollow');
+    return directives.join(', ');
+}

package/dist/content/types.d.ts

@@ -37,10 +37,20 @@ export interface SiteFooter {
 }
 export type KernelFooterGroup = FooterGroup;
 export type KernelFooterColumn = FooterColumn;
+/**
+ * Page-level search engine directives. `index: false` renders `noindex` and
+ * drops the page from the release sitemap; `follow: false` renders
+ * `nofollow`. Absent keys emit nothing (crawler default: index, follow).
+ */
+export interface KernelPageRobots {
+    index?: boolean;
+    follow?: boolean;
+}
 export interface KernelPageSeo {
     title?: string;
     description?: string;
     canonical?: string;
+    robots?: KernelPageRobots;
 }
 export interface KernelPageBlock {
     $type: 'component';
@@ -108,6 +118,7 @@ export interface KernelRouteMetadata {
     title: string;
     description: string;
     canonical?: string;
+    robots?: KernelPageRobots;
     siteName: string;
 }
 export interface RenderInput<TPage extends KernelPage = KernelPage, TSiteConfig extends KernelSiteConfig = KernelSiteConfig> {

package/dist/next/page.js

@@ -57,6 +57,7 @@ export function createPage(registry, options) {
             title: meta.title,
             description: meta.description,
             alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
+            robots: meta.robots,
             openGraph: {
                 title: meta.title,
                 description: meta.description,

package/migrations/page-metadata-head.md

@@ -0,0 +1,38 @@
+# Page metadata and crawler directives
+
+Upgrade and rebuild each site before using `metadata.robots`. Backend sitemap
+exclusion does not prove that a site emits the HTML directive.
+
+## Astro integration
+
+Install the SDK-owned head component once. Future metadata fields then follow
+SDK upgrades through the same object.
+
+1. Import `Head` from `@gradial/aci/astro/Head` in the site layout.
+2. Replace individual metadata props with `meta: KernelRouteMetadata` from `@gradial/aci/content`.
+3. Render `<Head meta={meta} />` inside `<head>`.
+4. Remove the layout's title, description, canonical, robots, and Open Graph tags that `Head` now owns.
+5. Pass `meta={data.meta}` from the catch-all route.
+6. Pass `meta={errorPage.meta}` from the 404 and 500 seats.
+7. Keep site-owned charset, viewport, icons, scripts, and custom head tags.
+
+Use `packages/sdk/templates/astro/template/src/` as the integration reference.
+`getPageData` returns the complete resolved metadata object. No separate robots
+prop or serialized robots string is needed.
+
+## Verify the rendered output
+
+Verify the directive on the site build that will serve the content. This is a
+release check, not a claim that a search engine has removed a URL.
+
+1. Author `"metadata": { "robots": { "index": false, "follow": false } }` on a test page.
+2. Build the site and publish the test content.
+3. Check that the rendered preview has one robots tag containing `noindex, nofollow`.
+4. Check that the release sitemap excludes that page and retains an indexable control page.
+5. Check that robots.txt permits fetching the test page so crawlers can read its tag.
+6. Repeat against the active release after activation.
+
+`make test-frontend-contract` checks rendered HTML from packed Next and Astro
+starters. It does not certify a customer's older SDK or copied layout.
+Authoring integrations must inspect rendered preview HTML before claiming the
+directive is present. The companion Grady change must preserve this requirement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.53-rc.1",
+  "version": "0.1.53-rc.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -103,6 +103,9 @@
     "./astro/ConsentBanner": {
       "import": "./src/astro/ConsentBanner.astro"
     },
+    "./astro/Head": {
+      "import": "./src/astro/Head.astro"
+    },
     "./consent-banner": {
       "types": "./dist/consent-banner/index.d.ts",
       "import": "./dist/consent-banner/index.js"
@@ -160,11 +163,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.1",
-    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.1",
-    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.1",
-    "@gradial/aci-cli-linux-x64": "0.1.53-rc.1",
-    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.1",
-    "@gradial/aci-cli-win32-x64": "0.1.53-rc.1"
+    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.2",
+    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.2",
+    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.2",
+    "@gradial/aci-cli-linux-x64": "0.1.53-rc.2",
+    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.2",
+    "@gradial/aci-cli-win32-x64": "0.1.53-rc.2"
   }
 }

package/src/astro/Head.astro

@@ -0,0 +1,18 @@
+---
+import { robotsMetaContent, type KernelRouteMetadata } from '@gradial/aci/content';
+
+interface Props {
+  meta: KernelRouteMetadata;
+}
+
+const { meta } = Astro.props;
+const robots = robotsMetaContent(meta.robots);
+---
+
+<title>{meta.title}</title>
+<meta name="description" content={meta.description} />
+{meta.canonical ? <link rel="canonical" href={meta.canonical} /> : null}
+{robots ? <meta name="robots" content={robots} /> : null}
+<meta property="og:title" content={meta.title} />
+<meta property="og:description" content={meta.description} />
+<meta property="og:site_name" content={meta.siteName} />

package/src/cli/compile-registry.mjs

@@ -496,6 +496,14 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
           title: { type: 'string', minLength: 1 },
           description: { type: 'string' },
           canonical: { type: 'string' },
+          robots: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              index: { type: 'boolean' },
+              follow: { type: 'boolean' },
+            },
+          },
         },
       },
       regions: {

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

@@ -1,11 +1,10 @@
 ---
 import '../design-system/styles.css';
+import Head from '@gradial/aci/astro/Head';
+import type { KernelRouteMetadata } from '@gradial/aci/content';
 
 interface Props {
-  title: string;
-  description: string;
-  canonical?: string;
-  siteName?: string;
+  meta: KernelRouteMetadata;
   /**
    * Pre-rendered Gradial collect script tag (collectScriptTagHTML from
    * '@gradial/aci/astro'). Empty string / undefined = personalization
@@ -17,7 +16,7 @@ interface Props {
   assignmentsTag?: string;
 }
 
-const { title, description, canonical, siteName = 'Gradial', collectTag, assignmentsTag } = Astro.props;
+const { meta, collectTag, assignmentsTag } = Astro.props;
 ---
 
 <!doctype html>
@@ -25,13 +24,8 @@ const { title, description, canonical, siteName = 'Gradial', collectTag, assignm
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>{title}</title>
     <link rel="icon" type="image/png" href="/assets/bare-metal-logo.png" />
-    <meta name="description" content={description} />
-    {canonical ? <link rel="canonical" href={canonical} /> : null}
-    <meta property="og:title" content={title} />
-    <meta property="og:description" content={description} />
-    <meta property="og:site_name" content={siteName} />
+    <Head meta={meta} />
     {collectTag ? <Fragment set:html={collectTag} /> : null}
     {assignmentsTag ? <Fragment set:html={assignmentsTag} /> : null}
   </head>

package/templates/astro/template/src/pages/404.astro

@@ -17,10 +17,7 @@ const renderChildren = createRenderChildren(registry);
 ---
 
 <SiteLayout
-  title={errorPage.meta.title}
-  description={errorPage.meta.description}
-  canonical={errorPage.meta.canonical}
-  siteName={errorPage.meta.siteName}
+  meta={errorPage.meta}
 >
   {data ? (
     data.layout.slots.map((slot) => {

package/templates/astro/template/src/pages/500.astro

@@ -16,10 +16,7 @@ const renderChildren = createRenderChildren(registry);
 ---
 
 <SiteLayout
-  title={errorPage.meta.title}
-  description={errorPage.meta.description}
-  canonical={errorPage.meta.canonical}
-  siteName={errorPage.meta.siteName}
+  meta={errorPage.meta}
 >
   {data ? (
     data.layout.slots.map((slot) => {

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

@@ -25,10 +25,7 @@ const renderChildren = createRenderChildren(registry);
 ---
 
 <SiteLayout
-  title={data.meta.title}
-  description={data.meta.description}
-  canonical={data.meta.canonical}
-  siteName={data.meta.siteName}
+  meta={data.meta}
   collectTag={data.collectTag}
   assignmentsTag={data.assignmentsTag}
 >

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

@@ -58,6 +58,36 @@ Base page fields are SDK-owned and included in the generated
 governs an interior page (see Page Templates); pages under a route a
 template covers omit it.
 
+#### Search engine indexing
+
+`metadata.robots` requests crawler indexing behavior. An upgraded site renders a
+`<meta name="robots">` tag in the page head:
+
+```json
+{
+  "metadata": {
+    "title": "Private Campaign Page",
+    "robots": { "index": false, "follow": false }
+  }
+}
+```
+
+- **`index: false`** — renders `noindex` and excludes the page from `sitemap.xml`.
+- **`follow: false`** — renders `nofollow`. Crawlers do not follow the page's
+  links.
+- **Omit a key** — no directive for it. Crawlers default to index, follow.
+
+Verify the rendered preview HTML before claiming the directive is present.
+Next sites need an SDK upgrade and rebuild. Existing Astro sites also need
+the SDK-owned `@gradial/aci/astro/Head` integration. Sitemap exclusion alone
+does not prove that the page emits `noindex`. Search removal depends on a
+later crawl and is not immediate.
+
+Use `index: false` for temporary campaign pages, event landing pages, and
+thank-you pages. Do not also block the path in `robots.txt`: a crawler that
+cannot fetch the page never sees the `noindex` tag, and the URL can stay in
+search results.
+
 #### Sitemap visibility
 
 `metadata.sitemap.visible` controls whether the page appears in the generated
@@ -77,10 +107,10 @@ template covers omit it.
 }
 ```
 
-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).
+Use `false` only for pages that may appear in search results but should not
+be listed in the sitemap, or for pages already blocked by `robots.txt`. To keep
+a page out of search results, use `metadata.robots` instead — it excludes the
+page from the sitemap too.
 
 This does **not** add a `noindex` meta tag — it only controls sitemap inclusion.
 

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

@@ -143,6 +143,7 @@ const renderChildren = createRenderChildren(registry);
   title={data.meta.title}
   description={data.meta.description}
   canonical={data.meta.canonical}
+  robots={data.robotsContent}
   siteName={data.meta.siteName}
   collectTag={data.collectTag}
 >