StaticOwl documentation

A graph-native CMS that compiles content into static sites — and into social posts, flyers, signs, QR codes, and emails. One source, every channel. Versioned, replayable, audit-grade.

The thesis: Content is source code. Your site is a compiled artifact. Deploys are pointer flips. Once that's true, A/B testing, drip publishing, replay, and audit-grade compliance fall out as variations on the same primitive.

Where to start

Documentation map

Concepts

• Architecture — data model, request lifecycle, deploy pipeline, multi-tenant story, the bitemporal graph layer, the manifest-pointer architecture
• Positioning — what we are, what we're not, three deployment modes, the architectural moat

Reference

• HTTP API — every /api/* endpoint with auth, request/response shapes, status codes
• MCP servers — the CMS gcms-mcp + the underlying engine MCP, tool inventories, Claude Desktop wiring
• Deploy targets — static-paths, manifest-pointer, github, both — env vars + behavior

Features

• Features overview — Releases, Reviews, A/B testing, Drip publishing, Multi-output, GitHub mirror, Replay, Rollback
• AI capabilities — Voice profile, document import, visual edit, bulk rewrite, Site Health, AI pricing model
• Lifecycle hooks — onSave, beforeRender, onPublish, sandboxing, examples

Operations

• Operations — env vars, secrets, deploy scripts, monitoring, troubleshooting

Architecture decision records

• ADRs — major architectural decisions with rationale (Deployment fact model, Versionable scope, Atomic releases, …)

Core concepts (one-line each)

• Site — a tenant boundary. Every content node, template, type, route belongs to one site. Multi-tenant isolation lives here.
• Versionable — anything that can be bundled into a Release: content, templates, types, routes, theme, settings, widgets, assets.
• Release — an immutable bundle of Versionable versions. "What did we plan to ship?"
• Deployment — a fact pointing a Release at an environment with a validFrom timestamp. "What actually shipped, where, and when?"
• Review — an approval/finding gate on a Release. Kinds: ai, automated, manual, compliance. Blocking findings prevent deploy.
• Manifest — the publishing layer: a sharded map from public path to artifact hash. Atomic blue/green via single-write pointer flip.
• Replay — the canonical query: Site(env, time) returns the exact bytes that were live at that point in time.

These six primitives explain almost everything else the system does.

The architectural promise (one sentence)

Every state of your site is a fact in an append-only graph; every output channel is the same Release compiled differently; every deploy is a pointer flip; every past day is a query.

If that sentence is true, the rest of the docs explain mechanics.

Project layout

cms/
├── docs/                          ← you are here
├── packages/
│   ├── core/                      ← types, services, graph client
│   ├── server/                    ← Express HTTP API + admin
│   ├── build/                     ← compile + render + impact analysis
│   ├── cli/                       ← `cms` command
│   ├── mcp/                       ← @staticowl/mcp (gcms-mcp binary)
│   ├── ui/                        ← legacy admin UI
│   └── ui-next/                   ← current admin UI
├── tests/
│   └── e2e/                       ← Playwright tests
├── marketing/                     ← staticowl.com static site
└── ops/                           ← Lambda@Edge, CloudFront, etc.

Versioning + status

This is a 0.x product in early access. APIs may change between minor versions. Breaking changes are called out in CHANGELOG.md (when present) and in ADRs. Major capabilities ship behind kill-switch env vars (STATICOWL_DEPLOYMENT_MODEL, STATICOWL_DEPLOY_TARGET) so operators can roll forward / back per-tenant.

Contributing

This documentation is part of the codebase. Edits land via PR like any other change. Tests for everything documented here run on npm test (unit) and npm run test:e2e (browser); see tests/e2e/README.md.