Skip to main content

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.

​
How Gradial ACI Works

Agentic Content Infrastructure (ACI) is a pipeline. Content goes in one end, authored by humans or agents. Validated, compiled, rendered pages come out the other. Every step is observable, reversible, and repeatable. This page walks through the system by following content through its lifecycle.

​
The Three Phases

Every piece of content moves through three phases: author, compile, deliver. These phases are decoupled. An editor can save content without triggering a publish. A developer can push new code without rebuilding all content. ACI only brings them together when you explicitly choose to publish.

​
Phase 1: Author

Content lives as JSON files in cloud storage. When an editor or agent makes a change, ACI does not overwrite the existing file. It creates a new version, an immutable snapshot of the content tree at that moment.
Every editing session happens in a workspace. Editors and agents work in draft workspaces, isolated copies where changes can be made, previewed, and discarded without risk.When the work is ready, the workspace is merged to main through ACI’s validation pipeline. If there are conflicts (two people edited the same page), ACI surfaces them explicitly. No silent overwrites. Merging to main does not make content live; publishing is a separate, explicit step.
Every save produces a version. Every version records who made the change, what changed, and when. Versions are deduplicated by content: identical content always produces the same fingerprint. This means ACI can save storage and detect when a “change” is actually a no-op.The full history is preserved in cloud storage. You can inspect any past version, compare any two versions, or roll back to any point in time.
Multiple workspaces can exist simultaneously. An editor working on a spring campaign and an agent optimizing product pages operate in parallel without interference. Publishing is explicit and validated.

​
Phase 2: Compile

Before content can be published, it passes through the content compiler. The compiler always produces the same output from the same input. It takes a frozen content snapshot and the code manifest from your frontend, and produces validated, self-contained payloads.

Schema Validation

Every content document is checked against the schema defined by its component. A Hero component expects a headline, subtext, and image. If the content doesn’t match, the compiler catches it, not your users.

Reference Resolution

Content documents reference each other. A page includes a hero fragment, which references an image asset. The compiler resolves every reference into a self-contained payload. Broken references are caught at compile time.

Dependency Graph

The compiler maps which content documents affect which pages. When a shared footer fragment changes, ACI knows exactly which pages need to be re-rendered, and which don’t.

Route Table

The compiler builds a mapping of URL paths to content payloads. Every route on your site is a known, validated entry in this table.
ACI validates the entire site, including all references, all routes, and all schemas, before anything goes live. Validation happens across the full dependency graph, not just individual content entries.

​
Phase 3: Deliver

Publishing in ACI is a two-step process: stage, then activate. Staging renders all affected pages into static artifacts. For static pages, this means full HTML. For dynamic pages, this means compiled JSON payloads that your frontend hydrates at request time. All artifacts are uploaded to the CDN alongside your current live site. Nothing changes yet. Activation flips a single pointer. One moment your CDN serves the old release. The next moment it serves the new one. There is no partial state. No “some pages updated, some didn’t.” The transition is atomic. Rollback is the same operation: flip the pointer back to the previous release. No rebuild. No re-upload. Instant.

​
Your Code, Your Framework

ACI does not own your frontend. Your website code lives in your Git repository, written in the framework you choose: Astro, Next.js, or SvelteKit. You connect your project to ACI through a lightweight frontend contract:
  1. A config file (.aci.yaml) that tells ACI what framework you use and where your components are.
  2. A component registry that maps CMS content types to your actual components.
  3. A render function that ACI calls to produce HTML.
ACI builds your code into a portable capsule, a self-contained artifact that can render any page when given content. The same capsule serves preview, staging, and production.
Your frontend code is never locked in. The contract is a thin adapter. If you switch from Astro to Next.js, you write a new adapter. ACI’s content, validation, and publishing pipeline stays the same.

​
What Happens When…

The editor saves the change in their workspace. ACI creates a new version. The editor previews the page instantly, using the current production code with their updated content. When they’re satisfied, they merge to main. From there, the team can publish: the compiler validates the change, finds that only one page is affected (via the dependency graph), re-renders that single page, stages it, and goes live.Total time from save to live: seconds, not minutes.
The developer pushes to their Git repo. ACI detects the change, builds a new code capsule, and extracts the updated component manifest. Since the code has changed, ACI re-renders the entire site against the new capsule to guarantee every page is consistent. All pages are staged together and go live as a single atomic flip.
A developer updates a component schema, say, adding a required field to the Hero component. ACI links the new code artifact to a workspace and runs the compiler. The compiler reports every page that violates the new schema, with exact file paths and field names.From here, Gradial’s agent layer can spin up parallel threads to draft fixes across all affected pages. Stakeholders review and approve the changes. When ready, the workspace merges both the code update and all content fixes to main as a single atomic change. No half-migrated state, no broken pages.
The agent opens a draft workspace. It writes 50 content documents, one per product. The compiler validates all 50 against the ProductPage schema. The agent previews a sample to verify the output. When merged to main, the team can publish: ACI stages and renders all 50 pages in parallel and delivers them as a single atomic release.
A publish goes live and the team notices a problem. Someone flips back to the previous release. One pointer change, instant. The broken release is still there for investigation, but no user sees it. The team fixes the content in a workspace, re-compiles, re-stages, and publishes again.
Next: Core Concepts →