@gradial/aci 0.1.44 → 0.1.45

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.45 - 2026-07-29
+
+### Fixed
+
+- Require the explicit `$type: "component"` discriminator for top-level and
+  nested component blocks across schema generation, content validation, and
+  rendering.
+- Execute the registry compiler and content validator correctly through
+  package-manager symlinks while keeping their reusable functions importable.
+
 ## 0.1.44 - 2026-07-28
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.44` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.45` 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.44 zod@^4
+npm install @gradial/aci@0.1.45 zod@^4
 ```
 
 ## Root Import
@@ -85,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.44 init my-site --template next-starter
+npx @gradial/aci@0.1.45 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.44 init --list
+npx @gradial/aci@0.1.45 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/cli/compile-registry.d.mts

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-export {};
+export function compileRegistry(options: any): Promise<{
+    registry: string;
+    schemas: string[];
+}>;
+export function generatePageSchema(schemaDir: any, componentEntries: any, outDir: any): Promise<string>;

package/dist/cli/compile-registry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -18,14 +19,16 @@ try {
         globalThis.React = React;
 }
 catch { /* react not available — component files without JSX will still work */ }
-const args = parseArgs(process.argv.slice(2));
-try {
-    const result = await compileRegistry(args);
-    console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
-}
-catch (error) {
-    console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
-    process.exitCode = 1;
+if (isMainModule()) {
+    const args = parseArgs(process.argv.slice(2));
+    try {
+        const result = await compileRegistry(args);
+        console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+    }
+    catch (error) {
+        console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+        process.exitCode = 1;
+    }
 }
 async function compileRegistry(options) {
     const required = ['components', 'layouts', 'output'];
@@ -440,9 +443,10 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
     const defs = {
         baseBlock: {
             type: 'object',
-            required: ['id', 'component', 'props'],
+            required: ['$type', 'id', 'component', 'props'],
             additionalProperties: true,
             properties: {
+                $type: { const: 'component' },
                 id: { type: 'string', minLength: 1 },
                 component: { type: 'string' },
                 props: { type: 'object' },
@@ -757,3 +761,14 @@ function parseArgs(argv) {
     }
     return out;
 }
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+    }
+    catch {
+        return false;
+    }
+}
+export { compileRegistry, generatePageSchema };

package/dist/cli/validate-content.d.mts

@@ -1,2 +1,32 @@
 #!/usr/bin/env node
-export {};
+export function validateContent(options: any): Promise<{
+    warnings?: any[] | undefined;
+    success: boolean;
+    pagesValidated: number;
+    blocksValidated: number;
+    errors: ({
+        page: string;
+        message: string;
+        fragment?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        message: string;
+        page?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        message: string;
+        page?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        path: any;
+        message: any;
+        page?: undefined;
+    })[];
+}>;

package/dist/cli/validate-content.mjs

@@ -19,21 +19,25 @@
  * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
  * imports needed, same schemas usable by Go backend or other tools.
  */
+import { realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-const args = parseArgs(process.argv.slice(2));
-try {
-    const result = await validateContent(args);
-    console.log(JSON.stringify(result, null, 2));
-    if (!result.success)
+import { fileURLToPath } from 'node:url';
+if (isMainModule()) {
+    const args = parseArgs(process.argv.slice(2));
+    try {
+        const result = await validateContent(args);
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        console.error(JSON.stringify({
+            success: false,
+            errors: [{ message: String(error?.message ?? error) }],
+        }, null, 2));
         process.exitCode = 1;
-}
-catch (error) {
-    console.error(JSON.stringify({
-        success: false,
-        errors: [{ message: String(error?.message ?? error) }],
-    }, null, 2));
-    process.exitCode = 1;
+    }
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -86,6 +90,22 @@ async function validateContent(options) {
         const blocks = collectBlocks(pageData);
         for (const block of blocks) {
             blocksValidated++;
+            if (!block || typeof block !== 'object') {
+                collector.push({
+                    page: relativePath,
+                    blockId: '<unknown>',
+                    message: 'page region entry must be a component block',
+                });
+                continue;
+            }
+            if (block.$type !== 'component') {
+                collector.push({
+                    page: relativePath,
+                    blockId: block.id ?? '<unknown>',
+                    path: '$type',
+                    message: 'block "$type" must be "component"',
+                });
+            }
             if (!block.component) {
                 collector.push({
                     page: relativePath,
@@ -348,6 +368,13 @@ function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props
                 issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
                 continue;
             }
+            if (nestedBlock.$type !== 'component') {
+                issues.push({
+                    path: `${nestedPath}.$type`,
+                    message: `${parentBlock.component}: block ref child "$type" must be "component"`,
+                });
+                continue;
+            }
             if (!componentMap.has(nestedBlock.component)) {
                 issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
                 continue;
@@ -424,3 +451,14 @@ function parseArgs(argv) {
     }
     return out;
 }
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+    }
+    catch {
+        return false;
+    }
+}
+export { validateContent };

package/dist/content/resolve-slots.js

@@ -12,6 +12,7 @@ export async function resolveSlots(layout, pageRegions, getFragment) {
             for (const ref of defaults) {
                 const fragment = await getFragment(ref.fragmentId);
                 blocks.push({
+                    $type: 'component',
                     id: fragment.id,
                     component: fragment.component,
                     props: fragment.props || {},

package/dist/content/types.d.ts

@@ -42,11 +42,13 @@ export interface KernelPageSeo {
     canonical?: string;
 }
 export interface KernelPageBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;
 }
 export interface KernelAtomicBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;

package/dist/types/block-ref.d.ts

@@ -5,6 +5,7 @@ export interface BlockRefMeta {
     multiple: boolean;
 }
 declare const blockRefBase: z.ZodObject<{
+    $type: z.ZodLiteral<"component">;
     id: z.ZodString;
     component: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -12,6 +13,7 @@ declare const blockRefBase: z.ZodObject<{
 type InferContractProps<T> = T extends ComponentContract<string, infer Schema> ? Schema extends z.ZodType<infer P> ? P : Record<string, unknown> : Record<string, unknown>;
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 export type BlockRefEntry<T extends ComponentContract> = {
+    $type: 'component';
     id: string;
     component: InferContractId<T>;
     props: InferContractProps<T>;

package/dist/types/block-ref.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 const BLOCK_REF_KEY = '_gradialBlockRef';
 const blockRefBase = z.object({
+    $type: z.literal('component'),
     id: z.string().min(1),
     component: z.string().min(1),
     props: z.record(z.string(), z.unknown()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -164,11 +164,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.44",
-    "@gradial/aci-cli-darwin-x64": "0.1.44",
-    "@gradial/aci-cli-linux-arm64": "0.1.44",
-    "@gradial/aci-cli-linux-x64": "0.1.44",
-    "@gradial/aci-cli-win32-arm64": "0.1.44",
-    "@gradial/aci-cli-win32-x64": "0.1.44"
+    "@gradial/aci-cli-darwin-arm64": "0.1.45",
+    "@gradial/aci-cli-darwin-x64": "0.1.45",
+    "@gradial/aci-cli-linux-arm64": "0.1.45",
+    "@gradial/aci-cli-linux-x64": "0.1.45",
+    "@gradial/aci-cli-win32-arm64": "0.1.45",
+    "@gradial/aci-cli-win32-x64": "0.1.45"
   }
 }

package/src/cli/compile-registry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -19,14 +20,15 @@ try {
   if (!globalThis.React) globalThis.React = React;
 } catch { /* react not available — component files without JSX will still work */ }
 
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await compileRegistry(args);
-  console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
-} catch (error) {
-  console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
-  process.exitCode = 1;
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await compileRegistry(args);
+    console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 async function compileRegistry(options) {
@@ -430,9 +432,10 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   const defs = {
     baseBlock: {
       type: 'object',
-      required: ['id', 'component', 'props'],
+      required: ['$type', 'id', 'component', 'props'],
       additionalProperties: true,
       properties: {
+        $type: { const: 'component' },
         id: { type: 'string', minLength: 1 },
         component: { type: 'string' },
         props: { type: 'object' },
@@ -741,3 +744,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { compileRegistry, generatePageSchema };

package/src/cli/validate-content.mjs

@@ -19,21 +19,24 @@
  * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
  * imports needed, same schemas usable by Go backend or other tools.
  */
+import { realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await validateContent(args);
-  console.log(JSON.stringify(result, null, 2));
-  if (!result.success) process.exitCode = 1;
-} catch (error) {
-  console.error(JSON.stringify({
-    success: false,
-    errors: [{ message: String(error?.message ?? error) }],
-  }, null, 2));
-  process.exitCode = 1;
+import { fileURLToPath } from 'node:url';
+
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await validateContent(args);
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.success) process.exitCode = 1;
+  } catch (error) {
+    console.error(JSON.stringify({
+      success: false,
+      errors: [{ message: String(error?.message ?? error) }],
+    }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -95,6 +98,24 @@ async function validateContent(options) {
     for (const block of blocks) {
       blocksValidated++;
 
+      if (!block || typeof block !== 'object') {
+        collector.push({
+          page: relativePath,
+          blockId: '<unknown>',
+          message: 'page region entry must be a component block',
+        });
+        continue;
+      }
+
+      if (block.$type !== 'component') {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          path: '$type',
+          message: 'block "$type" must be "component"',
+        });
+      }
+
       if (!block.component) {
         collector.push({
           page: relativePath,
@@ -380,6 +401,13 @@ function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props
         issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
+      if (nestedBlock.$type !== 'component') {
+        issues.push({
+          path: `${nestedPath}.$type`,
+          message: `${parentBlock.component}: block ref child "$type" must be "component"`,
+        });
+        continue;
+      }
 
       if (!componentMap.has(nestedBlock.component)) {
         issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
@@ -450,3 +478,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { validateContent };

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

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { z } from 'zod';
+
+import { compileSchema } from '../compiler/zod-to-jsonschema.js';
+import { defineComponentContract } from '../define-component.js';
+import { blockRefArray } from './block-ref.js';
+
+const childContract = defineComponentContract({
+  id: 'child',
+  props: z.object({
+    label: z.string(),
+  }),
+});
+
+test('block references require and accept the component discriminator', () => {
+  const schema = blockRefArray([childContract]);
+  const typed = {
+    $type: 'component',
+    id: 'child-1',
+    component: 'child',
+    props: { label: 'Hello' },
+  };
+
+  assert.equal(schema.safeParse([typed]).success, true);
+  assert.equal(schema.safeParse([{
+    id: typed.id,
+    component: typed.component,
+    props: typed.props,
+  }]).success, false);
+});
+
+test('compiled block-reference schema exposes the component discriminator', () => {
+  const compiled = compileSchema(blockRefArray([childContract])) as {
+    items?: {
+      properties?: Record<string, { const?: string }>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+  };
+
+  assert.equal(compiled.items?.properties?.$type?.const, 'component');
+  assert.equal(compiled.items?.required?.includes('$type'), true);
+  assert.equal(compiled.items?.additionalProperties, false);
+});

package/src/types/block-ref.ts

@@ -9,6 +9,7 @@ export interface BlockRefMeta {
 }
 
 const blockRefBase = z.object({
+  $type: z.literal('component'),
   id: z.string().min(1),
   component: z.string().min(1),
   props: z.record(z.string(), z.unknown()),
@@ -21,6 +22,7 @@ type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 
 export type BlockRefEntry<T extends ComponentContract> = {
+  $type: 'component';
   id: string;
   component: InferContractId<T>;
   props: InferContractProps<T>;

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

@@ -13,17 +13,18 @@ export const atomicBlockStoryFixtures: AtomicBlockStoryFixture[] = [
     storybookId: 'core-atomic-blocks-button--variants',
     title: 'Button / All Variants',
     block: {
+      $type: 'component',
       id: 'fixture-button-variants',
       component: 'container',
       props: {
         theme: 'auto',
         blocks: [
-          { id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
-          { id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
-          { id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
-          { id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
-          { id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
-          { id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
+          { $type: 'component', id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
+          { $type: 'component', id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
+          { $type: 'component', id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
+          { $type: 'component', id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
+          { $type: 'component', id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
         ]
       }
     }

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

@@ -14,14 +14,15 @@ export const compositionStoryFixtures: CompositionStoryFixture[] = [
     storybookId: 'composition-container--buttons',
     title: 'Container / Buttons',
     block: {
+      $type: 'component',
       id: 'fixture-container-buttons',
       component: 'container',
       props: {
         theme: 'auto',
         className: 'space-y-4',
         blocks: [
-          { id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
-          { id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
+          { $type: 'component', id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
         ]
       }
     }

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

@@ -14,6 +14,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
     storybookId: 'sections-home-hero--default',
     title: 'Home Hero',
     block: {
+      $type: 'component',
       id: 'fixture-home-hero',
       component: 'home_hero',
       props: {
@@ -22,7 +23,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
         description: 'One content model, three renderers. Build once in Next.js, Astro, and SvelteKit—then prove parity with shared fixtures.',
         ctaLabel: 'Get started',
         ctaHref: '/docs',
-          image: {
+        image: {
           $type: 'gradial.image',
           assetId: 'fixture_seattle',
           versionId: 'v0001',

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

@@ -98,6 +98,7 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 
 ```json
 {
+  "$type": "component",
   "id": "hero-section",
   "component": "home_hero",
   "props": {
@@ -109,6 +110,7 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 ```
 
 - `component` must match a contract `id` exactly.
+- Every embedded block must declare `"$type": "component"`.
 - `props` must validate against the contract's Zod schema.
 - `id` is unique within the page.
 
@@ -141,12 +143,14 @@ export const containerContract = defineComponentContract({
 **Content JSON:**
 ```json
 {
+  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "className": "space-y-4",
     "content": [
       {
+        "$type": "component",
         "id": "primary-cta",
         "component": "button",
         "props": {
@@ -156,6 +160,7 @@ export const containerContract = defineComponentContract({
         }
       },
       {
+        "$type": "component",
         "id": "secondary-cta",
         "component": "button",
         "props": {
@@ -182,6 +187,7 @@ The `button` component is a common atomic block:
 
 ```json
 {
+  "$type": "component",
   "id": "cta-button",
   "component": "button",
   "props": {
@@ -411,6 +417,7 @@ framework.
 ```json
 // .content/pages/home/_index.json (inside regions.main)
 {
+  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -499,9 +506,10 @@ export default [
 ];
 ```
 
-Fragment content lives in `.content/fragments/{id}/_index.json` and has
-a `component` + `props` just like page blocks. Chrome components (Header,
-Footer) are registered in the registry alongside page components.
+Fragment content lives in `.content/fragments/{id}/_index.json` and retains
+the resource envelope `"$type": "fragment"` while declaring `component` +
+`props`. Chrome components (Header, Footer) are registered in the registry
+alongside page components.
 
 The `layout` field in page JSON is **required** — there is no implicit
 default. Every page must declare which layout it uses.

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

@@ -113,12 +113,14 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
 
 ```json
 {
+  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "theme": "dark",
     "blocks": [
       {
+        "$type": "component",
         "id": "primary-cta",
         "component": "callout",
         "props": {
@@ -127,6 +129,7 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
         }
       },
       {
+        "$type": "component",
         "id": "heading",
         "component": "heading",
         "props": {

package/templates/common/.content/pages/home/_index.json

@@ -11,6 +11,7 @@
   "regions": {
     "main": [
       {
+        "$type": "component",
         "id": "hero",
         "component": "home_hero",
         "props": {
@@ -27,6 +28,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "why-meridian",
         "component": "feature_grid",
         "props": {
@@ -34,6 +36,7 @@
           "subtitle": "Engineered for the edges of the world.",
           "features": [
             {
+              "$type": "component",
               "id": "global-coverage",
               "component": "feature_card",
               "props": {
@@ -43,6 +46,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "low-latency",
               "component": "feature_card",
               "props": {
@@ -52,6 +56,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "easy-setup",
               "component": "feature_card",
               "props": {
@@ -64,6 +69,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "personalization-choice",
         "component": "personalization_choice",
         "props": {
@@ -75,6 +81,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "stats",
         "component": "stats_bar",
         "props": {
@@ -87,6 +94,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "cta",
         "component": "container",
         "props": {
@@ -94,6 +102,7 @@
           "className": "items-center justify-center text-center",
           "content": [
             {
+              "$type": "component",
               "id": "cta-primary",
               "component": "button",
               "props": {
@@ -105,6 +114,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "cta-secondary",
               "component": "button",
               "props": {

package/templates/common/starter-content/.content/pages/about/_index.json

@@ -11,6 +11,7 @@
   "regions": {
     "main": [
       {
+        "$type": "component",
         "id": "about-hero",
         "component": "home_hero",
         "props": {
@@ -27,12 +28,14 @@
         }
       },
       {
+        "$type": "component",
         "id": "about-actions",
         "component": "container",
         "props": {
           "className": "items-center justify-center text-center",
           "content": [
             {
+              "$type": "component",
               "id": "home-link",
               "component": "button",
               "props": {

package/templates/common/starter-content/.content/pages/home/_index.json

@@ -11,6 +11,7 @@
   "regions": {
     "main": [
       {
+        "$type": "component",
         "id": "hero",
         "component": "home_hero",
         "props": {
@@ -27,6 +28,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "why-meridian",
         "component": "feature_grid",
         "props": {
@@ -34,6 +36,7 @@
           "subtitle": "Engineered for the edges of the world.",
           "features": [
             {
+              "$type": "component",
               "id": "global-coverage",
               "component": "feature_card",
               "props": {
@@ -43,6 +46,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "low-latency",
               "component": "feature_card",
               "props": {
@@ -52,6 +56,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "easy-setup",
               "component": "feature_card",
               "props": {
@@ -64,6 +69,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "stats",
         "component": "stats_bar",
         "props": {
@@ -76,6 +82,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "cta",
         "component": "container",
         "props": {
@@ -83,6 +90,7 @@
           "className": "items-center justify-center text-center",
           "content": [
             {
+              "$type": "component",
               "id": "cta-primary",
               "component": "button",
               "props": {
@@ -94,6 +102,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "cta-secondary",
               "component": "button",
               "props": {