> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an Astro site, edit typed content locally, and verify your first ACI build.

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.

<Info>
  Access: Must be enabled for your organization. Contact your Gradial team to get access.
</Info>

## 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:

```bash theme={null}
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.

<Tip>
  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.
</Tip>

## 2. Start the site

```bash theme={null}
npm run dev
```

Open [http://localhost:4321](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:

```txt theme={null}
.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:

1. A page document names a component and supplies its props.
2. A component contract validates those props.
3. 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:

```json theme={null}
{
  "$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:

```bash theme={null}
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.

<Note>
  `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.
</Note>

## 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:

```json theme={null}
{
  "$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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Frontend contract" icon="file-code" href="/aci/developers/frontend-contract">
    Learn how configuration, contracts, runtime components, and the registry fit together.
  </Card>

  <Card title="Framework guides" icon="layer-group" href="/aci/developers/framework-guides">
    Compare the Astro and Next.js integrations.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/aci/developers/cli-reference">
    Work with local content, branches, promotion, and releases.
  </Card>

  <Card title="Agent-ready projects" icon="robot" href="/aci/architecture/agent-native-design">
    See how repository guidance helps people and coding agents follow the same workflow.
  </Card>
</CardGroup>

***

*Next: [Frontend contract →](/aci/developers/frontend-contract)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.