Overview

Ounce is a CMS engine that ships as one npm package, @ouncepage/core, and one Astro integration. You describe your content in a config file. It gives you an admin at /admin, the routes that serve your pages, the middleware that guards them, and a typed API for reading content back out.

It runs on Cloudflare Workers. D1 stores content, R2 stores media, Cloudflare Access authenticates editors. Those three are not pluggable.

A project that uses it has no src/pages/ and no src/middleware.ts unless it wants them. What is left in your own source tree is your content model and your design, which is the point.

Who writes what

You write	Ounce provides
A Zod schema and a field list per content type	The forms, validation, sanitising and save path
Astro components that render your sections	The loop that renders them, the page model and the preview
ounce.config.ts	Every route under /admin, plus /[...path], /404 and /media/[...key]
A csp block, if your templates embed anything	Authentication, security headers and the policy
Migrations for your own tables, if any	The settings, pages, page_sections, revisions, media, media_uses, redirects, editors and mcp_tokens tables

Content model

Three kinds of thing, and the distinction decides which API you use.

Settings are global singletons keyed by a string: site, footer, navigation. One row each, no page owns them.

Pages are routes. A page owns a slug, a title, SEO and Open Graph fields, and an ordered list of sections.

Sections are typed blocks owned by exactly one page. One instance per type per page, enforced by PRIMARY KEY (page_id, key). That constraint is what makes a hardcoded anchor id inside a section component legitimate.

Extension points

These are the only ones. Everything else is closed.

Point	Adds	Page
Field type	A new type usable in any field list	Field types
Section type	A renderable block	Section types
Plugin	A bundle of the below, with its own settings form	Plugins
Page tab	Fields on every page’s editor	Page tabs
Admin screen	A route under /admin/x/	Admin screens
Analytics provider	A dashboard source	Analytics providers
Assistant provider	An AI backend for the content assistant	Assistant providers

Authentication and media storage are deliberately not extension points. There is one implementation of each and it is not swappable.

Every page

InstallAdding @ouncepage/core to an Astro project on Cloudflare Workers.

ArchitectureThe three layers, and one field traced from schema to rendered page.

Site configdefineSite, the one file the integration reads.

RoutingThe routes Ounce injects, and the headers its middleware writes.

DatabaseThe D1 tables Ounce owns and the environment it reads.

Extension points, in the order most people need them:

PluginsThe Plugin object, and what each key adds to the admin.

Field typesdefineField, and what a field component must render.

Section typesAdding a typed content block and the component that renders it.

Rendering fieldsA field your template ignores silently swallows content.

Page tabsAdding fields to every page's editor from a plugin.

Admin screensSidebar entries and your own pages under /admin/x/.

AnalyticsThe AnalyticsProvider interface and its capability flags.

AssistantsThe AssistantProvider interface and the tool loop the engine drives.

How the platform behaves, and what to read when it misbehaves:

RolesThree roles, nine permissions, and how a plugin guards a route.

HistoryHow revisions are recorded, and the rule that keeps them honest.

Silent failuresFailures that produce no error, and how to confirm each one.

Reference:

Built-in typesEvery field type the engine ships, with its options and stored shape.

Entry factoriesReady-made entries for SEO, menus, social links, FAQs and repeating lists.

AI toolsConsuming this documentation programmatically.

Where to start

Installing: Install.

Understanding it: Architecture. It traces one field from the schema you declare to the HTML a visitor gets, which is the fastest way to know which file to open.

Something behaving strangely rather than erroring: Silent failures. Most of what goes wrong here produces a page that renders and a save that looks like it worked.

Assumptions

You know Astro, you know Zod, and you have a Cloudflare account. Every code sample here is complete and runnable, not a fragment.