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.

​
Core Concepts

Agentic Content Infrastructure (ACI) has a small number of core concepts. Understanding these gives you the vocabulary to reason about everything else in the platform.

​
Content as Versions

In ACI, content is a version history. Every save creates an immutable snapshot. Every snapshot is deduplicated by content: identical content always produces the same fingerprint. Nothing is overwritten. Nothing is lost. You don’t need to know Git to use ACI. Editors and marketers work through a visual interface, and history, workspaces, and rollback work automatically underneath. AI agents, on the other hand, are naturally fluent with files, JSON, and Git-style versioning. ACI’s model plays directly to their strengths, letting them operate with familiar tooling instead of learning a proprietary API.

​
Workspaces

A workspace is a named pointer to a content version. Main is the canonical version of your content, the trunk that all workspaces branch from and merge back to. Merging to main does not automatically make content live; publishing is a separate, explicit step. When an editor or agent starts working, they get a draft workspace, a lightweight copy of main that they can modify freely. Workspaces are cheap. You can have hundreds of them running simultaneously without any performance impact. When the work is ready, the workspace is merged to main. If main has moved since the workspace was created (because someone else merged), ACI updates the workspace with the latest content from main, applying the new changes on top of the current state. If the same content was modified in both places, ACI surfaces the conflict explicitly.

​
The Content Compiler

ACI validates and pre-processes everything before it reaches users. The compiler takes two inputs:
  1. A content snapshot: the saved state of all content in a workspace
  2. A code manifest: the component registry from your frontend project
And produces three outputs:
  1. Validated payloads: self-contained JSON for each page, with all references resolved
  2. Route table: a mapping of every URL path to its content
  3. Dependency graph: a map of which content affects which pages
The compiler always produces the same outputs from the same inputs. This makes builds reproducible, cacheable, and debuggable.

​
The Frontend Contract

ACI doesn’t own your frontend code. It integrates with it through a lightweight contract. Your project exposes three things:
WhatHowPurpose
Configuration.aci.yamlTells ACI your framework, component locations, and capabilities
Component registryregistry.tsMaps content types (“Hero”, “ProductCard”) to your actual components with schemas
Render functionrenderPage.tsACI calls this with content, your code returns HTML
ACI builds your project into a code capsule, a compiled, portable artifact that can render any page when given a content payload. The capsule is immutable and versioned independently from content.
The same code capsule serves preview, staging, and production. There is no “preview build” vs “production build”. The only difference is which content it renders.

​
Atomic Publishing

Publishing in ACI is a two-step process:
  1. Stage: render all affected pages and upload them alongside the current live site
  2. Activate: flip a single pointer to switch traffic to the new release
This means your site is always in a consistent state. Users never see a mix of old and new content. And rollback is just flipping the pointer back: no rebuild, no re-upload, instant.

​
Agent Principals

In ACI, an AI agent is not a feature. It is an operator with its own identity. Every agent authenticates as a principal, just like a human user. It gets its own draft workspace, makes changes through the same API, and its work goes through the same validation pipeline. The audit trail records which agent made which change, when, and on whose behalf. This means governance works the same regardless of whether the operator is a person or an agent. Approval workflows, validation rules, and rollback policies don’t need separate “AI modes.”

Human Operator

Authenticates via SSO. Edits through the visual interface. Changes are saved to a workspace, validated, and merged to main.

Agent Operator

Authenticates via API key. Edits through the CLI or API. Changes are saved to a draft workspace, validated, and merged through the same pipeline and rules.

​
Pre-Compiled Personalization

ACI handles personalization at build time, not at request time. Instead of a client-side engine assembling pages on the fly, the content compiler produces multiple variants of each page, one per audience segment, locale, or campaign. Every variant is a pre-rendered, static artifact. At the edge, a lightweight router reads a cookie or header to determine the visitor’s segment and serves the right variant. No decision service. No runtime latency. No cache-busting. Serving a personalized page is as fast as serving a static page, because it is a static page. This model pairs naturally with AI agents. An agent can generate dozens of variants per page covering long-tail segments that would be impractical to manage by hand. All variants go through the same validation pipeline and are published as part of the same atomic release.

​
Content Types and Schemas

Every content document in ACI has a content type, a schema that defines its structure. A HeroSection has a headline, subtext, image, and CTA. A ProductCard has a name, price, description, and thumbnail. Schemas serve two purposes:
  1. Editor guidance: the authoring interface knows what fields to show and how to validate input
  2. Compiler enforcement: the content compiler rejects any document that doesn’t match its schema before it can be published
Schemas are defined in your frontend code as part of the component registry. This means the people who build the components also define what content those components accept. No drift between what the CMS allows and what the code expects.
Next: Why Gradial ACI →