Architecture

The agent at the center#

You run two processes locally:

• Claude Code Desktop — the agent and your editing surface. Holds the embedded preview pane, knows the project's .claude/skills/, reads and writes files directly.
• Next.js dev server — runs app/, serves the site at http://localhost:3000, hosts the agntcms admin and inline-edit HTTP endpoints under app/api/agntcms/<...>.dev.ts.

They share one thing: the project directory on disk. Everything the agent does is a file edit (Read, Write, Edit); everything the inline-edit UI does is an HTTP call to one of the framework endpoints (draft create, draft publish, replace section, issue preview token, upload asset). The Next.js dev server picks up file changes and refreshes the preview; the agent picks up UI-initiated edits the next time it reads a file.

That is the whole loop. No message bus, no plugin runtime, no dedicated channel server — just two processes sharing a directory.

Production#

Compare the centers. In dev, two processes share a working tree. In production there is one — Next.js — and no agent. A visitor opens a page, Next.js reads content/pages/*.json and renders it. No admin, no inline-edit UI, no agent, no runtime dependency on Claude.

The technical mechanism: every admin, agent, and inline-edit route carries a .dev.ts suffix (for example, app/api/agntcms/[...path]/route.dev.ts). Next.js compiles those routes only when pageExtensions includes .dev.ts — true under pnpm dev, false under next build. The admin code does not exist in the production bundle.

Where things live#

• Content — JSON files under content/. Drafts in content/drafts/, published pages in content/pages/, version history in content/history/, site-wide blocks in content/globals/ (with their own content/history-globals/).
• Assets — public/assets/<sha256>.<ext>. Content-addressed, deduplicated, served straight from Next.js static.
• Sections (code) — React components and field schemas under agntcms/sections/<Name>/.
• Config — agntcms/config.ts, an explicit list of sections and adapter wiring.
• Skills — markdown instructions under .claude/skills/, synced from the @agntcms/skills npm package.
• Framework HTTP API — app/api/agntcms/<...>.dev.ts, dev-only handlers for the inline-edit UI: page CRUD, draft publish, section replace, asset upload, preview tokens.
• Deploy — a normal git push to a repository connected to Vercel (or any Next.js-compatible platform).

Storage adapters#

Content and assets are accessed through adapters, not hardcoded to the filesystem. The defaults — the FS content adapter and the public-folder asset adapter — are what every new project uses; they read and write files inside the project directory, which is why everything stays in git.

The adapter interfaces (ContentStorageAdapter, AssetStorageAdapter) are exported from @agntcms/next and can be swapped in agntcms/config.ts if you ever need to back content with a database or assets with S3. This is a v0.5 escape hatch, not a recommended default — the FS adapter is what the rest of the framework, the skills, and the docs assume.

Package map#

• @agntcms/next — runtime: domain model, storage adapters, React components, HTTP handlers (preview tokens, draft CRUD, replace section, asset upload).
• @agntcms/skills — the agent's playbook: one skill per project operation, synced into .claude/skills/ on scaffold and on update.

Both release in lockstep — one version across the board.

Versioning#

All four packages release in lockstep:

• @agntcms/next
• @agntcms/skills
• create-agntcms-app
• agntcms-template

One version across the board. Update them together.