Quickstart - Gradial Docs

In this guide, you’ll create a Gradial ACI (Agentic Content Infrastructure) Astro site with sample content, run it locally, make a safe content change, and verify the project before you commit.

Access: Must be enabled for your organization. Contact your Gradial team to get access.

Prerequisites

Node.js 22 or later
npm 10 or later
A terminal and code editor

1. Create the starter

Run the ACI initializer with the Astro starter and sample content:

npx @gradial/aci init my-site --template astro-starter --with-starter-content
cd my-site
npm install

Astro is the standard starting point for new ACI sites. The sample content gives you working pages, contracts, components, and tests to explore.

Run npx @gradial/aci init --list to see the currently available starters. Use the Next.js starter when your site needs the Next.js ecosystem or its server-rendering model.

2. Start the site

npm run dev

Open http://localhost:4321. The development server compiles content on startup, watches .content/ for changes, and refreshes the browser as you work.

3. Tour the project

The starter keeps authored content, compile-time contracts, and runtime components in clear locations:

.aci.yaml                         Site and framework configuration
.content/                         Authored JSON content
  config/site.json               Site-wide settings
  pages/**/_index.json           Pages
  fragments/**/_index.json       Reusable content
src/cms/contracts/components/    Component IDs and Zod prop schemas
src/cms/contracts/layouts/       Layout slots and defaults
src/cms/registry.ts              Contract-to-component mappings
src/components/                  Runtime Astro components
src/design-system/               Design tokens and global styles
.agents/                          Repository guidance for people and agents
.aci/                             Generated output; do not edit directly

Three pieces work together:

A page document names a component and supplies its props.
A component contract validates those props.
The registry maps the contract to the Astro component that renders it.

4. Make your first content change

Open .content/pages/home/_index.json and find the block whose id is hero. Change its headline while leaving the component ID and the other props in place:

{
  "$type": "component",
  "id": "hero",
  "component": "home_hero",
  "props": {
    "eyebrow": "Global satellite internet",
    "headline": "Connect from anywhere on Earth — right on schedule.",
    "description": "Meridian delivers low-latency broadband to homes, businesses, and remote operations in over 40 countries. No ground infrastructure required.",
    "ctaLabel": "Explore plans",
    "ctaHref": "/plans/",
    "image": {
      "$type": "dam.assetRef",
      "assetId": "ast_site_home_hero",
      "alt": "Light abstract hero background with satellite constellation"
    }
  }
}

Save the file and return to the browser. The development server recompiles the content and displays the update. The stable block id matters. ACI uses it to address that block across edits and personalized experiences. Keep an existing ID when you are updating the same block; use a new, unique ID when you add a different block.

5. Run the checks

Before you commit, compile the content and run the starter’s verification commands:

npm run content:compile
npm run typecheck
npm test
npm run build

These commands catch malformed content, props that do not match a component contract, TypeScript errors, conformance failures, and production build problems.

npm run dev already compiles and watches content for local development. Run npm run content:compile when you want a one-time compile, such as in CI or before a separate framework command.

How page files map to routes

Pages live under .content/pages/:

Content file	Route
`.content/pages/home/_index.json`	`/`
`.content/pages/about/_index.json`	`/about/`
`.content/pages/products/widget/_index.json`	`/products/widget/`

A page document identifies its layout and fills the layout’s named regions:

{
  "$type": "page",
  "id": "about",
  "status": "published",
  "layout": "default",
  "metadata": {
    "title": "About us",
    "description": "Learn more about our team."
  },
  "regions": {
    "main": [
      {
        "$type": "component",
        "id": "about-hero",
        "component": "home_hero",
        "props": {
          "eyebrow": "About us",
          "headline": "Meet the team behind the work.",
          "description": "We help teams build dependable content operations.",
          "ctaLabel": "Contact us",
          "ctaHref": "/contact/"
        }
      }
    ]
  }
}

The component value must match a registered contract ID. Its props must satisfy that contract’s Zod schema.

Common issues

The CLI is not available

Install the starter dependencies first:

npm install
npm exec -- aci --help

Project scripts are the preferred interface for routine local work because they use the SDK version declared by the starter.

A content change does not appear

Check that:

the JSON file was saved;
the terminal running npm run dev has no compile error;
the page file is under .content/pages/; and
the block’s component value matches a contract exported by the component contract registry.

If needed, stop and restart npm run dev, then run npm run content:compile to see the validation output directly.

Content compilation fails

Read the first reported file path and field error. Common causes are invalid JSON, a missing required prop, an unknown component ID, or a region that is not declared by the selected layout.

Next steps

Frontend contract

Learn how configuration, contracts, runtime components, and the registry fit together.

Framework guides

Compare the Astro and Next.js integrations.

CLI reference

Work with local content, branches, promotion, and releases.

Agent-ready projects

See how repository guidance helps people and coding agents follow the same workflow.

Next: Frontend contract →

​Prerequisites

​1. Create the starter

​2. Start the site

​3. Tour the project

​4. Make your first content change

​5. Run the checks

​How page files map to routes

​Common issues

​The CLI is not available

​A content change does not appear

​Content compilation fails

​Next steps

Frontend contract

Framework guides

CLI reference

Agent-ready projects

Prerequisites

1. Create the starter

2. Start the site

3. Tour the project

4. Make your first content change

5. Run the checks

How page files map to routes

Common issues

The CLI is not available

A content change does not appear

Content compilation fails

Next steps