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

> Get a local ACI starter running, edit JSON content, validate it, and build the site.

This guide takes you from a fresh ACI starter to a working local site. You'll install dependencies, verify the frontend contract, edit content as plain JSON, validate it, and render it through your own framework, the whole loop, end to end. It runs entirely on your machine.

<Info>
  ACI is currently available to **design partners**. This quickstart works locally and does not require production cloud access. [Request access →](https://www.gradial.com/request-demo) for production onboarding.
</Info>

## Prerequisites

* **Node.js 20.19+** and npm
* An ACI starter repo provided by Gradial
* A terminal and text editor

## Step 1: Install Dependencies

Clone the starter repo you were given, then install dependencies from the starter root:

```bash theme={null}
npm install
```

The current Astro starter has this shape:

```txt theme={null}
.aci.yaml                         # ACI site contract
.content/                         # Editable source content
.content/config/site.json          # Site configuration
.content/pages/**/_index.json      # Page documents
src/cms/contracts/components/      # Component names, Zod schemas, render modes
src/cms/contracts/layouts/         # Layout slot contracts
src/cms/renderer.ts                # Renderer capsule entrypoint
src/components/                    # Runtime framework components
```

## Step 2: Verify the ACI Contract

Run the doctor command:

```bash theme={null}
npm run aci:doctor
```

`doctor` checks `.aci.yaml`, the `@gradial/aci` package, registry paths, renderer entry, Node/npm availability, and framework-specific requirements.

## Step 3: Compile Contracts and Content

Compile the component and layout contracts:

```bash theme={null}
npm run aci:compile
```

Then compile and validate source content:

```bash theme={null}
npm run aci:validate
```

In the current starter, `aci:validate` compiles `.content/` into `.aci/compiled`. The framework build reads the compiled content from that generated directory.

## Step 4: Build and Run

Build the framework site:

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

Start local development:

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

Open the local URL printed by your framework dev server.

## Step 5: Edit Content

Open the homepage content:

```bash theme={null}
code .content/pages/home/_index.json
```

Find a block in `regions.main` and change a field:

```json theme={null}
{
  "id": "hero",
  "component": "home_hero",
  "props": {
    "headline": "Your New Headline Here"
  }
}
```

Save the file, then run:

```bash theme={null}
npm run aci:validate
npm run build
```

Refresh your local site and your change is live. That `validate → build` loop is the same safety path content takes all the way to production: every edit is checked against your component schemas before it renders.

<Tip>
  Keep `npm run dev` running in one terminal and edit content in another. Re-run `npm run aci:validate` after a content change to recompile `.aci/compiled`, then refresh.
</Tip>

## Content Shape

ACI page content is JSON:

```json theme={null}
{
  "$type": "page",
  "id": "home",
  "status": "published",
  "layout": "marketing",
  "renderMode": "static",
  "metadata": {
    "title": "Page Title",
    "description": "SEO description"
  },
  "regions": {
    "main": [
      {
        "id": "hero",
        "component": "home_hero",
        "props": {
          "headline": "Welcome"
        }
      }
    ]
  }
}
```

* **`$type`**: `"page"` for page documents
* **`layout`**: Which layout contract to use
* **`renderMode`**: How the page should be rendered, such as `"static"`
* **`metadata`**: SEO and page-level data
* **`regions`**: Named layout regions containing blocks
* **`component`**: The registered component contract name
* **`props`**: Data validated against that component's Zod schema

## Component Contracts

Component contracts live under `src/cms/contracts/components/` and should not import runtime components, CSS, browser APIs, or framework-only modules.

```ts theme={null}
import { defineComponentContract } from '@gradial/aci';
import { z } from 'zod';

export const homeHeroContract = defineComponentContract({
  name: 'home_hero',
  schema: z.object({
    headline: z.string().min(1),
    description: z.string().optional(),
    ctaLabel: z.string().min(1),
    ctaHref: z.string().min(1)
  }),
  renderModes: { canStatic: true, canSSR: true, canClientIsland: false }
});
```

Runtime components are wired separately by the starter's render code. This separation keeps ACI's compiler deterministic and avoids pulling framework runtime code into schema extraction.

## Common Tasks

### Add a New Page

Create a page folder and `_index.json`:

```bash theme={null}
mkdir -p .content/pages/about
```

```json theme={null}
{
  "$type": "page",
  "id": "about",
  "status": "published",
  "layout": "marketing",
  "renderMode": "static",
  "metadata": {
    "title": "About Us",
    "description": "Learn about our company"
  },
  "regions": {
    "main": [
      {
        "id": "hero",
        "component": "home_hero",
        "props": {
          "headline": "About Us",
          "description": "We build great products.",
          "ctaLabel": "Contact us",
          "ctaHref": "/contact"
        }
      }
    ]
  }
}
```

Then run:

```bash theme={null}
npm run aci:validate
npm run build
```

### Validate Before Committing

```bash theme={null}
npm run aci:doctor
npm run aci:compile
npm run aci:validate
npm run typecheck
npm run build
```

### Use the CLI Directly

Starter scripts usually wrap the CLI for you. The direct equivalents are:

```bash theme={null}
aci build --compile-only
aci build --skip-code --content ./.content --out ./.aci/compiled
aci build --content ./.content
aci doctor
aci dev
```

## Troubleshooting

### ACI command not found

Most starters install `@gradial/aci` locally. Use the starter's `npm run aci:*` scripts, or run the local binary with:

```bash theme={null}
npx aci --help
```

### Content changes are not showing

1. Save the JSON file.
2. Re-run `npm run aci:validate`.
3. Re-run `npm run build` if your framework reads from `.aci/compiled`.
4. Check for JSON syntax or schema validation errors.

### Component not found

The `component` value in content JSON must match a contract exported from `src/cms/contracts/components/index.ts`.

## What's Next

<CardGroup cols={2}>
  <Card title="The Frontend Contract" icon="file-code" href="/aci/developers/frontend-contract">
    Go deeper on `.aci.yaml`, component and layout contracts, and the renderer entrypoint that connects your site to ACI.
  </Card>

  <Card title="Framework Guides" icon="layer-group" href="/aci/developers/framework-guides">
    Set up Astro, Next.js, or SvelteKit against the same contract.
  </Card>

  <Card title="Add Components" icon="cubes" href="/aci/developers/frontend-contract">
    Define your own components with Zod schemas, render modes, and image slots.
  </Card>

  <Card title="Explore the CLI" icon="terminal" href="/aci/developers/cli-reference">
    Master the commands for building, validating, syncing content, and managing branches.
  </Card>
</CardGroup>

***

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