Core / Project structure

Project structure

An agntcms project is a normal Next.js project with three added zones: your code, your content, and the framework's frozen zone. The boundary between them matters — it decides whether the next framework update applies cleanly or turns into a three-day merge.

Three zones#

User zone (your code)#

You write this; you change this. The agent steps in too — through skills, always explicitly, always with your knowledge.

agntcms/config.ts — the single registry of section types and adapters. Without an explicit entry here, a section is not visible in the admin.
agntcms/site-meta.ts — site name, description, base URL.
agntcms/sections/<Name>/ — section type folders. Each contains index.ts, schema.ts, component.tsx, optionally preview.png.
styles/theme.css — design tokens (colours, type, spacing). Consumed through Tailwind utility classes.
styles/globals.css and styles/typography.css — standard Next.js plus typography rules.
BRAND.md — brand guide and pointer to the design source (Claude Design bundle, if present).
next.config.ts, tsconfig.json, postcss.config.mjs — standard configs, editable to suit the project.

Content zone (your content)#

The content of the site. Edited by the editor (through Claude Code or the UI) and sometimes by you (through skills or the agent, not by hand). Going in here directly is almost always a process error — a skill should have run.

content/pages/<slug>.json — published pages. Each carries a slug, SEO metadata, and an array of sections.
content/drafts/<slug>.json — drafts. Same shape as published; visible only in dev.
content/history/<slug>/<timestamp>.json — version snapshots. Written automatically on every publish.
content/globals/<name>.json — site-wide blocks: header, footer, announcement, site meta.
content/history-globals/ — global snapshots. Same rules as pages.
public/assets/<sha256>.<ext> — images and files uploaded through the admin. The filename is the SHA-256 of the contents; do not rename.

Frozen zone (do not touch)#

The framework. Updated only through pnpm update @agntcms/next and pnpm update @agntcms/skills. Any hand edit here is either an accident or a breaking change that belongs at the framework level.

app/api/agntcms/ — admin and agent routes (the .dev.ts suffix keeps them out of the production build).
app/[[...slug]]/page.tsx — the single catch-all for every content page.
app/not-found.tsx — the Next.js not-found route; renders the CMS 404 page.
.claude/settings.json and .claude/skills/ — Claude Code config and agent skills, synced from @agntcms/skills.

User-editable defaults#

Ship with working implementations; customise freely when the project requires it.

app/sitemap.ts — reads site-meta and listPages to produce the XML sitemap.
app/robots.ts — reads site-meta for the canonical base URL.

Why it is strict#

So framework updates do not turn into a three-day merge. Imagine @agntcms/next v0.4 ships a new field in the admin API. In the usual approach you would have to find and update app/api/agntcms/... by hand, resolving conflicts with your edits. In agntcms you run pnpm update @agntcms/next, the frozen-zone files update cleanly (they were not supposed to be modified), and you get the new behaviour for free.

Any feature that requires editing the frozen zone by hand is either a design mistake or a breaking change in the framework itself. If it feels like that is what you need, almost certainly you are solving the problem the wrong way.

If you accidentally edited a frozen file#

Say to Claude Code:

run agntcms-frozen-guard.

The skill diffs every frozen file against the canonical version, shows what differs, and offers to roll it back. Accidental edits — gone. No edits — all clear.

What goes into git#

Both of your zones are committed: user zone (code, as usual) and content zone (content, including drafts and history). Drafts go into git deliberately — to prevent losing in-progress work across machines or hand-offs.

The frozen zone is committed too — it is part of the project. You do not touch it by hand, so it never appears in commits (except after pnpm agntcms-skills-sync or an @agntcms/next update).

Project zones — quick reference#

Zone	Path	Who edits
User	`agntcms/`, `styles/`, `BRAND.md`, Next.js configs	developer, sometimes the agent through skills
Content	`content/`, `public/assets/`	editor and the agent through skills (not by hand)
Frozen	`app/api/agntcms/`, `app/[[...slug]]/page.tsx`, `app/not-found.tsx`, `.claude/settings.json`, `.claude/skills/`	no one (version bumps only)
User-editable defaults	`app/sitemap.ts`, `app/robots.ts`	developer (working defaults; customise when needed)

← PreviousArchitecture Next →Creating sections