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.

​
Content Versioning

Agentic Content Infrastructure (ACI) stores content using a version-based model inspired by Git. Instead of mutable database rows, content exists as immutable, deduplicated objects in blob storage. Every change creates a new version. Every version is permanent. This gives you full history, parallel workspaces, concurrent editing, and instant rollback, not as add-on features, but as properties of the storage model itself.

​
The Object Model

ACI’s content store has three types of objects:

Content Objects (Blobs)

The actual content. Each content object (called a blob internally) is a JSON document: a page, a fragment, or a config file. Content objects are stored by fingerprint: the hash of the content is the storage key. Identical content is stored exactly once.

Directory Listings (Trees)

The structure of your content. A directory listing (called a tree internally) maps paths (like /pages/home.json) to content object hashes. Directory listings are also stored by fingerprint: the same set of files always produces the same hash.

Versions (Commits)

Snapshots in time. A version (called a commit internally) points to a directory listing (the full state of content at that moment), a parent version (the previous state), the author, and a timestamp. Versions are immutable once created.
Named pointers (called refs internally) are the only mutable objects. A named pointer points to a version, like main pointing to the latest canonical version. Updating a pointer is a safe update: it only succeeds if the pointer still points to the expected version. This prevents lost updates when two writers try to advance the same pointer simultaneously.

​
Workspaces

A workspace is a named pointer. The main pointer represents 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 to your site is a separate step. Everything else is a workspace for in-progress work. When an editor or agent starts working, ACI creates a draft workspace, a lightweight pointer that starts at the current version of main. The editor makes changes in their workspace. Each save creates a new version in that workspace. Main is unaffected. Workspaces are cheap. Creating one is a single pointer write. You can have hundreds of active workspaces without any storage or performance overhead, since each workspace only stores the versions that differ from main.

​
Publishing and Conflict Resolution

When a workspace is ready to merge to main, ACI follows a specific process:
1

Sync with Latest

If main has moved since the workspace was created, ACI updates the workspace with the latest content from main, replaying the workspace’s changes on top of the current main. This ensures the workspace is up to date.
2

Conflict Detection

If the same content path was modified in both the workspace and main, ACI raises an explicit conflict. No silent overwrites. The editor or agent must resolve each conflict before proceeding.
3

Validation

The content compiler runs against the combined result. All schemas validated, all references resolved, all routes confirmed. If validation fails, the promotion is rejected with specific errors.
4

Clean Publish

The changes land as a single clean update on main. The workspace pointer is deleted. The merge is complete.
This approach keeps the main history clean and auditable. Each merge is one version with a clear description of what changed and who did it, whether that’s a human editor or an AI agent.

​
Blob Storage as Source of Truth

All objects (content objects, directory listings, versions, and named pointers) live in your blob storage bucket. This is the canonical source of truth. ACI maintains internal caches, indexes, and projections for fast lookups, reference resolution, and avoiding expensive recomputation, but they are all derived and always rebuildable from your storage. This means:
  • Durability: Your cloud provider’s storage durability protects your content history
  • Inspectability: You can browse your content store with standard cloud storage tools
  • Portability: Your content is not trapped in a proprietary database format
  • Recovery: If any index or projection is lost, ACI rebuilds it by replaying the version history from your bucket. Anything the server computes could also be derived from a full scan of storage; the indexes just make it fast
The storage bucket lives in your cloud account. Gradial does not host or control your content data. You set the retention policies. You manage the backups. You own the encryption keys.

​
Fingerprint-Based Storage

Every object in ACI is stored by the hash (fingerprint) of its content. This is the same principle behind Git and IPFS, and it provides several guarantees:
  • Deduplication: If two pages share the same hero fragment, that fragment is stored once
  • Integrity: Corruption is detectable because the fingerprint won’t match the content
  • Caching: Identical content across releases doesn’t need to be re-rendered
  • Predictability: Same content, same manifest, same compilation output, always

​
Real Git Workspaces

This is one of ACI’s most distinctive capabilities. Agents and developers don’t just get an “API that looks like Git.” They get a real .git repository with real versions, real diffs, real history, and full compatibility with standard Git tooling. ACI projects content from its versioning engine into a real Git workspace. The agent sees a directory with files, runs git diff, makes changes, and saves them, exactly the way any developer or AI coding assistant already works.

​
Path-Scoped Sparse Checkouts

Workspaces are scoped to the paths the agent needs. An agent optimizing product pages doesn’t receive the entire content library. Instead, it gets a sparse checkout containing only the relevant files and their dependencies. The workspace includes:
  • The specific content files the agent needs
  • Shared fragments referenced by those files
  • The full version history for those paths (not the entire repo’s history)
  • A work workspace for the agent’s edits, based on the current engine state

​
On-Demand Hydration

If an agent discovers it needs a file that wasn’t in the original checkout, ACI hydrates the workspace, adding the file and its scoped history without disrupting the agent’s in-progress work. 
# Agent is working and realizes it needs the nav config
aci workspace hydrate /config/navigation.json

# The file appears in the workspace with its history
# Agent's uncommitted work is preserved
git diff   # still shows the agent's changes
This means agents never need to know the full content tree upfront. They start with what they need and expand on demand.

​
Submit Back to ACI

When the agent’s work is done, changes flow back through the ACI control plane: 
# Agent commits their changes locally
git add pages/products/shoe-123.json
git commit -m "Optimize product description for SEO"

# Submit back to ACI
aci workspace submit
ACI compiles the Git diff into engine changes, validates them through the content compiler, and saves them to the agent’s engine workspace. The same validation pipeline, the same audit trail, the same publishing workflow, regardless of whether the changes came through the API, CLI, or a Git workspace.
The Git workspace is a derived projection: it looks and behaves like a real Git repo because it is one. But the source of truth always lives in your blob storage. The workspace is disposable and rebuildable. This means developers can use any Git-compatible tool (VS Code, GitHub Desktop, git CLI) and AI agents can operate through coding assistants or the Gradial agent platform. ACI treats all of them as first-class interfaces.

​
Why This Matters for AI Agents

AI coding assistants already know how to work with files and Git. They don’t need to learn a proprietary content API. With ACI workspaces:
  • File system as interface: agents read and write JSON files, the most natural data format for LLMs
  • Git as workflow: create a workspace, save versions, diff, and publish. Agents already understand these operations
  • Scoped context: sparse checkouts keep the agent’s context window focused on relevant content
  • Safe isolation: the workspace is separate from production; live content is untouched until publishing
Next: The Pre-Compile Pipeline →