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.
The Pre-Compile Pipeline
The content compiler is the core of Agentic Content Infrastructure’s (ACI) safety model. It ensures that nothing reaches your users, not a single page, without being validated against your component schemas, having all references resolved, and being compiled into a self-contained, renderable payload. But validation doesn’t wait for publish. ACI pushes feedback as early as possible: synchronous warnings on every write, lint APIs agents can call at any time, and workspace-level compilation before publishing. The full compile at publish time is the final gate, not the first time you find out something is wrong. This is ACI’s central thesis: everything is validated and prepared before it goes live.Shift-Left Validation
ACI pushes validation as far left as possible. The full compiler runs at publish time as the final gate, but validation starts much earlier:Write-Time Warnings
When an agent or editor saves a content document, ACI returns synchronous validation warnings on the write response. Schema violations, type mismatches, missing required fields, all surfaced immediately, not at publish time.
Lint & Typecheck APIs
Agents can call dedicated lint and typecheck endpoints against their workspace at any time. Check a single file, a directory, or the entire workspace. Get structured diagnostics with file paths, field names, and suggested fixes, designed for agents to consume and act on programmatically.
Workspace Compilation
Run the full compiler against a workspace before publishing. Catch reference errors, dependency issues, and cross-document problems while the work is still in progress, without affecting production.
Publish Gate
The final compile at publish time is the hard gate. Nothing reaches users unless the full pipeline passes. But by this point, most issues have already been caught and fixed.
| Concern | How ACI Handles It |
|---|---|
| Validation | Write-time warnings + lint APIs + full compile |
| Broken references | Write-time warning, blocked at publish |
| Missing translations | Flagged with specific paths at lint time |
| Schema mismatch | Synchronous warning on save |
| Unknown routes | Caught at compile time |
| Agent feedback loop | Structured diagnostics on every write |
The Compiler Pipeline
The compiler takes two inputs, a content snapshot (a specific version) and a code manifest (from your frontend build), and runs a predictable pipeline:1. Schema Validation
1. Schema Validation
Every content document is validated against the schema defined by its component type in the code manifest. A
HeroSection expects headline (string), subtext (string), image (asset reference), and cta (link). If any field is missing, has the wrong type, or contains an unexpected value, the compiler reports the exact path, field, and error.This catches problems that per-field validation at save time cannot, like a component schema changing in a new code version while existing content still references the old structure.2. Reference Resolution
2. Reference Resolution
Content documents reference each other. A page includes a hero fragment, which references an image asset, which might have locale-specific variants. The compiler resolves every
$ref link into a self-contained payload.If a reference points to a document that doesn’t exist, the compiler fails with a clear error: “Page /pages/home.json references fragment /content/hero.json which does not exist in this snapshot.”The output is a fully denormalized payload per route with no runtime reference resolution needed.3. Overlay Application
3. Overlay Application
Content can have locale-specific and audience-specific overlays. The English version of a hero might have different copy than the French version. The compiler applies these overlays to produce variant payloads.Overlays follow a fallback graph: if
fr-CA doesn’t have a specific override, it falls back to fr, then to the base content. The compiler resolves the full chain and produces one concrete payload per variant.4. Route Building
4. Route Building
The compiler builds a complete mapping of URL paths to content payloads. Every route on your site is an explicit, validated entry. There are no “discovered at runtime” routes. If a path isn’t in the route table, it doesn’t exist.This means ACI always knows exactly how many pages your site has, what URLs they live at, and what content they contain.
5. Dependency Graph
5. Dependency Graph
The compiler builds a graph of which content documents affect which routes. If a shared footer fragment is used by 500 pages, the graph records that dependency.This is what makes incremental publishing possible. When the footer changes, ACI queries the graph to find exactly which 500 pages need re-rendering, and ignores the other 49,500.
6. Payload Hashing
6. Payload Hashing
Every compiled payload is stored by its fingerprint. If a page’s content hasn’t changed since the last publish, the fingerprint is identical and ACI skips re-rendering it. This makes republishing fast even for large sites, since only genuinely changed pages are processed.
Predictable Output Guarantee
The compiler always produces the same output from the same inputs. Given the same content snapshot and the same code manifest, you always get the same payloads, the same route table, the same dependency graph, and the same hashes. This guarantee means:- Reproducible builds: You can re-compile any historical snapshot and get the same result
- Safe caching: Cached compilation results are always valid for their inputs
- Debuggable failures: If a compile fails, you can reproduce it exactly with the same inputs
- Parallel execution: Multiple compiles can run simultaneously without interfering with each other
Schema Evolution
Because ACI controls the full pipeline from content to publish, it handles schema changes as a structured, validated process. When a component schema changes in your frontend code (say aHeroSection gains a new required field badge), ACI knows about the change through the updated code manifest. The compiler can:
- Identify every content document that uses the old schema version
- Report which documents need updating before the new code can be published
- Validate that updated documents are compatible with both old and new code versions during the transition
The Contract Change Workflow
Because ACI owns both sides of the content-to-code boundary, schema changes follow a structured workflow:- A developer creates a workspace with the updated component schema
- ACI links the new code workspace with the existing content and runs the compiler
- The compiler reports every page that violates the new schema
- A Gradial agent sees the violations and drafts fixes across all affected pages
- A human reviews and approves the agent’s changes
- The new code artifact and all content updates are merged to main as a single atomic transaction
ACI validates at compile time, not at the moment of editing, so required fields work naturally. Authors can fill in components incrementally during editing, and the compiler catches any missing required fields before publish.
Next: Publishing & Releases →