domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/plans/2026-10-09-content-api.md

@@ -0,0 +1,1192 @@
+# Content API - Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Load the `domma-api-surface` skill before Tasks 2-5.
+
+**Goal:** A read-only, versioned Content API at `/api/content/v1` - pages, menus, a public site-settings subset and search - gated by the same public / token / role modes as the Data API, and configured from a new **System › Content API** screen.
+
+**Architecture:** The public page access decision is lifted out of `server/routes/public.js` into `server/services/pagePublishing.js`, and both the site and the API call it. Token checks are factored out of `checkPublicAccess()` into `authenticateApiToken()`, which the collection gate and the new content gate share. Settings live in `config/content-api.json` via a service shaped like `search.js`. The admin screen is a Domma reactive view (observables + `M.applyBindings`), with its pure logic in `admin/js/lib/content-api-arrange.js`.
+
+**Tech Stack:** Node 20+ ESM, Fastify 5, `node:test` + `assert/strict`, Domma (`M` domma-reactive, `E`, `I`, `S`, `$`), no build step.
+
+**Spec:** `docs/superpowers/specs/2026-10-09-content-api-design.md`
+
+**Spec open questions - settled here (change before Task 7 if wrong):**
+1. Admin home: its **own screen**, System › Content API (`#/content-api`), permission `settings`.
+2. Per-page opt-out: **yes**. Frontmatter `api: false` keeps a page off the API (it still renders on the site).
+3. `requires` carries **no asset URLs** in v1.
+4. Edition: same tier as the Data API (confirm against `docs/editions-and-licences.md` in Task 9).
+
+**Test runs:** always `npm test -- <file>` (the runner copies the tree to a temp dir). Never bare `node --test` - many of these tests write pages and config.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `server/services/pagePublishing.js` | **New.** `resolvePublishedPage()`, `canPreviewDrafts()`, `isEffectivelyPublic()`. The one access decision for a single page. |
+| `server/services/search.js` | `isPubliclyListed()` (new, exported); `isSearchable()` built on it; draft rule becomes `status !== 'published'`. |
+| `server/routes/public.js` | Calls `resolvePublishedPage()`; keeps rendering, cache key and replies. |
+| `server/services/content.js` | Page writes also invalidate the `pages:list` tag. |
+| `server/services/apiTokens.js` | `authenticateApiToken()`; `{content}` scope shape in `validateScopes()`; `contentScopeAllows()`. |
+| `server/routes/api/collections.js` | `checkPublicAccess()` token branch delegates to `authenticateApiToken()`. |
+| `server/services/contentApi.js` | **New.** Settings defaults/normalise/get/save; `publicSiteSettings()`; page payload shaping (allowlists). |
+| `server/routes/api/content-public.js` | **New.** `checkContentAccess()` + the five `GET` routes. |
+| `server/routes/api/content-api.js` | **New.** Admin: `GET/PUT /api/content-api/settings`, `GET /api/content-api/_count`, `GET /api/content-api/preview`. |
+| `server/server.js` | Register both route files; `onSend` no-store exemption; sidebar item. |
+| `admin/js/lib/content-api-arrange.js` | **New.** Pure: form ↔ settings, dirty snapshot, chips, endpoint list, curl examples, preview row. |
+| `admin/js/views/content-api.js` | **New.** The screen - observables, bindings, tabs, try-it console, save, draft, router guard. |
+| `admin/js/templates/content-api.html` | **New.** Template, `data-model` / `data-bind-*` / `data-each`. |
+| `admin/js/views/index.js`, `admin/js/app.js` | Register the view, route and Tool banner entry. |
+| `admin/js/lib/api-tokens-arrange.js` | `@pages`-style content scope lines in `parseScopes()` / `scopesToText()` / `scopesSummary()`. |
+| `admin/css/admin.css` | `.cax-*` styles for the screen. |
+| Tests | Listed per task. |
+
+---
+
+## Task 1: Extract the page access decision
+
+The public site and the API must make the same decision, so the first step pulls it into a service, with no behaviour change.
+
+**Files:**
+- Create: `server/services/pagePublishing.js`
+- Modify: `server/routes/public.js:177-260`
+- Test: `tests/services/page-publishing.test.js` (new); existing `tests/routes/public-draft-preview.test.js`, `role-visibility.test.js`, `public-cache-headers.test.js`, `public-share-preview.test.js` must pass **unchanged**
+
+- [ ] **Step 1: Write the failing test**
+
+`tests/services/page-publishing.test.js`:
+
+```js
+/**
+ * pagePublishing.resolvePublishedPage - the single access decision for a
+ * public page, shared by the site (routes/public.js) and the Content API.
+ */
+import {after, before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import {resolvePublishedPage, isEffectivelyPublic} from '../../server/services/pagePublishing.js';
+import {createPage, deletePage} from '../../server/services/content.js';
+import {createProject, deleteProject, updateProject} from '../../server/services/projects.js';
+import {seedAll} from '../../server/services/presetCollections.js';
+import {load as loadRoles} from '../../server/services/roles.js';
+
+const P = '/zz-pp-' + Date.now();
+const anon = null;
+const user  = {id: 'u', role: 'user',  additionalRoles: []};
+const admin = {id: 'a', role: 'admin', additionalRoles: []};
+
+before(async () => {
+    await seedAll();
+    await loadRoles();
+    await createPage(`${P}/live`,    {title: 'Live',    status: 'published'}, 'x');
+    await createPage(`${P}/draft`,   {title: 'Draft',   status: 'draft'}, 'x');
+    await createPage(`${P}/sched`,   {title: 'Sched',   status: 'scheduled'}, 'x');
+    await createPage(`${P}/members`, {title: 'Members', status: 'published', visibility: 'user'}, 'x');
+    await createPage(`${P}/sec`,     {title: 'Section', status: 'published'}, 'x');      // /sec
+    await createPage(`${P}/sec/index`, {title: 'Section index', status: 'published'}, 'x');
+});
+
+after(async () => {
+    for (const p of ['live', 'draft', 'sched', 'members', 'sec', 'sec/index']) await deletePage(`${P}/${p}`).catch(() => {});
+});
+
+test('published public page → ok for anyone', async () => {
+    const v = await resolvePublishedPage(`${P}/live`, anon);
+    assert.equal(v.status, 'ok');
+    assert.equal(v.page.title, 'Live');
+    assert.equal(v.isDraft, false);
+});
+
+test('missing page → not-found', async () => {
+    assert.equal((await resolvePublishedPage(`${P}/nope`, anon)).status, 'not-found');
+});
+
+test('any non-published status is not-found without allowDrafts', async () => {
+    assert.equal((await resolvePublishedPage(`${P}/draft`, admin)).status, 'not-found');
+    assert.equal((await resolvePublishedPage(`${P}/sched`, anon)).status, 'not-found');
+});
+
+test('allowDrafts admits a pages.read viewer only', async () => {
+    assert.equal((await resolvePublishedPage(`${P}/draft`, admin, {allowDrafts: true})).status, 'ok');
+    assert.equal((await resolvePublishedPage(`${P}/draft`, user,  {allowDrafts: true})).status, 'not-found');
+    assert.equal((await resolvePublishedPage(`${P}/draft`, anon,  {allowDrafts: true})).status, 'not-found');
+});
+
+test('visibility: forbidden for anon, ok for the role and above', async () => {
+    assert.equal((await resolvePublishedPage(`${P}/members`, anon)).status, 'forbidden');
+    assert.equal((await resolvePublishedPage(`${P}/members`, user)).status, 'ok');
+    assert.equal((await resolvePublishedPage(`${P}/members`, admin)).status, 'ok');
+});
+
+test('forbidden verdict carries no page body', async () => {
+    const v = await resolvePublishedPage(`${P}/members`, anon);
+    assert.equal(v.page, undefined);
+});
+
+test('disabled project → not-found, whatever the visibility', async () => {
+    const slug = 'zz-pp-proj-' + Date.now();
+    await createProject({slug, name: 'PP'});
+    await createPage(`${P}/inproj`, {title: 'In project', status: 'published', project: slug}, 'x');
+    try {
+        assert.equal((await resolvePublishedPage(`${P}/inproj`, anon)).status, 'ok');
+        await updateProject(slug, {enabled: false});
+        assert.equal((await resolvePublishedPage(`${P}/inproj`, admin)).status, 'not-found');
+    } finally {
+        await deletePage(`${P}/inproj`).catch(() => {});
+        await deleteProject(slug).catch(() => {});
+    }
+});
+
+test('isEffectivelyPublic', () => {
+    assert.equal(isEffectivelyPublic(undefined), true);
+    assert.equal(isEffectivelyPublic('public'), true);
+    assert.equal(isEffectivelyPublic([]), true);
+    assert.equal(isEffectivelyPublic(['user', 'public']), true);
+    assert.equal(isEffectivelyPublic('user'), false);
+    assert.equal(isEffectivelyPublic('private'), false);
+});
+```
+
+Check `updateProject`'s real name and the field that disables a project in `server/services/projects.js` before running; adjust the two lines if they differ.
+
+- [ ] **Step 2: Run it - expect failure** (module not found)
+
+`npm test -- tests/services/page-publishing.test.js`
+
+- [ ] **Step 3: Create `server/services/pagePublishing.js`**
+
+```js
+/**
+ * Page publishing - may this viewer see this page?
+ *
+ * The one implementation of the public page access decision. The public site
+ * (routes/public.js) and the Content API (routes/api/content-public.js) both
+ * call it, so a page reachable over the API is reachable on the site by the
+ * same viewer and the reverse. It decides; it never replies or renders.
+ *
+ * Order matters and matches what the site has always done:
+ *   1. the page (with the directory-index fallback)
+ *   2. its project's kill-switch - a disabled project is a 404, no oracle
+ *   3. drafts - anything not `published` is a 404 unless drafts are allowed
+ *      AND the viewer holds pages.read
+ *   4. visibility - checkVisibility(), the ladder / `=role` rule
+ */
+import {getPage} from './content.js';
+import {getProjectForPage, isProjectEnabled} from './projects.js';
+import {checkVisibility} from '../middleware/auth.js';
+import {getPermissionsFor} from './roles.js';
+import {getEffectiveRoles} from './userRoles.js';
+
+/**
+ * Does a visibility value let everyone in without resolving a viewer?
+ * Missing, 'public', an empty array, or an array containing 'public'.
+ *
+ * @param {string|string[]|undefined} vis
+ * @returns {boolean}
+ */
+export function isEffectivelyPublic(vis) {
+    return !vis
+        || vis === 'public'
+        || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
+}
+
+/**
+ * May this viewer see unpublished pages? Gated on `pages.read` - the same
+ * permission that opens the Pages list in the admin.
+ *
+ * @param {object|null} user
+ * @returns {boolean}
+ */
+export function canPreviewDrafts(user) {
+    if (!user) return false;
+    const allowed = getPermissionsFor('pages', 'read');
+    return getEffectiveRoles(user).some(role => allowed.includes(role));
+}
+
+/**
+ * @param {string} urlPath - '/about', '/services', '/'
+ * @param {object|null} viewer - resolveViewer() result, or a JWT user, or null
+ * @param {{allowDrafts?: boolean}} [opts]
+ * @returns {Promise<
+ *   {status: 'ok', page: object, project: string, isDraft: boolean, isPublic: boolean} |
+ *   {status: 'not-found'} |
+ *   {status: 'forbidden'}
+ * >}
+ */
+export async function resolvePublishedPage(urlPath, viewer, {allowDrafts = false} = {}) {
+    let page = await getPage(urlPath);
+    if (!page && !urlPath.endsWith('/index')) {
+        page = await getPage(urlPath.replace(/\/$/, '') || '/');
+    }
+    if (!page) return {status: 'not-found'};
+
+    const project = await getProjectForPage(page.urlPath || urlPath, page.project);
+    if (!(await isProjectEnabled(project))) return {status: 'not-found'};
+
+    const isDraft = page.status !== 'published';
+    if (isDraft && !(allowDrafts && canPreviewDrafts(viewer))) return {status: 'not-found'};
+
+    const isPublic = isEffectivelyPublic(page.visibility);
+    if (!isPublic && !checkVisibility(viewer, page.visibility)) return {status: 'forbidden'};
+
+    return {status: 'ok', page, project, isDraft, isPublic};
+}
+```
+
+- [ ] **Step 4: Switch `server/routes/public.js` to it**
+
+Replace the first-pass lookup, project check, draft check and visibility check in the `/*` handler with:
+
+```js
+        const urlPath = '/' + (rawPath || '');
+
+        // The access decision - shared with the Content API (services/pagePublishing.js).
+        // The viewer is resolved on EVERY request: navbars, footers, overlays and [menu]
+        // on a public page filter by role too. Anonymous traffic resolves to null at once.
+        const userObj  = await resolveViewer(request);
+        const userRole = userObj ? [...getEffectiveRoles(userObj)].sort().join('+') : null;
+
+        const verdict = await resolvePublishedPage(urlPath, userObj, {allowDrafts: true});
+        if (verdict.status === 'not-found') {
+            reply.status(404);
+            return sendHtml(request, reply, await render404(urlPath));
+        }
+        if (verdict.status === 'forbidden') {
+            reply.status(403);
+            return reply.type('text/html; charset=utf-8').send(accessDeniedHtml(urlPath));
+        }
+        const {page, isDraft} = verdict;
+```
+
+Keep everything from `const baseUrl = getBaseUrl(request);` onwards as it is. Delete the local `canPreviewDrafts()` and import it from `pagePublishing.js` if anything else in the file still uses it (`/_preview` may; grep). Drop the now-unused imports (`getProjectForPage`, `isProjectEnabled`, `checkVisibility`, `getPermissionsFor`) only if nothing else in the file uses them.
+
+Keep the existing comments about per-viewer caching and draft `no-store` - they still describe the code below.
+
+- [ ] **Step 5: Run the new and the existing public tests**
+
+```
+npm test -- tests/services/page-publishing.test.js
+npm test -- tests/routes/public-draft-preview.test.js
+npm test -- tests/routes/role-visibility.test.js
+npm test -- tests/routes/public-cache-headers.test.js
+npm test -- tests/routes/public-share-preview.test.js
+```
+
+All pass, and the four existing files are **unmodified**.
+
+- [ ] **Step 6: Commit** - `refactor(public): extract the page access decision into pagePublishing`
+
+---
+
+## Task 2: One rule for "listed", and search brought into line
+
+**Files:**
+- Modify: `server/services/search.js` (`isSearchable`, around :472)
+- Test: `tests/routes/search-visibility.test.js` (extend), `tests/services/search-listed.test.js` (new)
+
+- [ ] **Step 1: Failing test** - `tests/services/search-listed.test.js`:
+
+```js
+/** isPubliclyListed - the list rule shared by search and the Content API. */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {isPubliclyListed, isSearchable} from '../../server/services/search.js';
+
+const page = (extra = {}) => ({urlPath: '/a', status: 'published', ...extra});
+
+test('only published pages are listed - not just "not draft"', () => {
+    assert.equal(isPubliclyListed(page(), null), true);
+    assert.equal(isPubliclyListed(page({status: 'draft'}), null), false);
+    assert.equal(isPubliclyListed(page({status: 'scheduled'}), null), false);
+    assert.equal(isPubliclyListed(page({status: undefined}), null), false);
+});
+
+test('a page in a disabled project is not listed', () => {
+    assert.equal(isPubliclyListed(page(), null, {offline: new Set(['/a']), noindex: new Set()}), false);
+});
+
+test('visibility applies', () => {
+    assert.equal(isPubliclyListed(page({visibility: 'user'}), null), false);
+    assert.equal(isPubliclyListed(page({visibility: 'user'}), {role: 'user', additionalRoles: []}), true);
+});
+
+test('noindex hides from search but not from the list rule', () => {
+    const p = page({seo: {noindex: true}});
+    assert.equal(isPubliclyListed(p, null), true);
+    assert.equal(isSearchable(p, null), false);
+});
+
+test('search no longer finds a scheduled page', () => {
+    assert.equal(isSearchable(page({status: 'scheduled'}), null), false);
+});
+```
+
+The visibility test needs roles loaded - add `before(async () => { await seedAll(); await loadRoles(); })` as in Task 1.
+
+- [ ] **Step 2: Run - expect failure** (`isPubliclyListed` not exported).
+
+- [ ] **Step 3: Implement** in `server/services/search.js`, above `isSearchable`:
+
+```js
+/**
+ * Could this viewer open this page from a list - published, in an enabled
+ * project, visible to them? The rule the Content API's page list and search
+ * share; noindex is search's own business and is not part of it.
+ *
+ * `status !== 'published'`, not `=== 'draft'`: the public route has always
+ * hidden every unpublished status, and search used to find a `scheduled` page
+ * that then 404ed.
+ */
+export function isPubliclyListed(page, viewer = null, exclusions = null) {
+    if (!page || page.status !== 'published') return false;
+    if (isOffline(page, exclusions)) return false;
+    return checkVisibility(viewer, page.visibility);
+}
+
+export function isSearchable(page, viewer = null, exclusions = null) {
+    return isPubliclyListed(page, viewer, exclusions) && !isNoindex(page, exclusions);
+}
+```
+
+Update `isSearchable`'s doc comment ("Drafts never" → "Unpublished pages never").
+
+- [ ] **Step 4: Run** `tests/services/search-listed.test.js`, `tests/routes/search-visibility.test.js`, `tests/routes/search-admin.test.js`. If a search fixture relied on a page with no `status` being found, that fixture was wrong (the site 404s it) - fix the fixture and say so in the commit.
+
+- [ ] **Step 5: Commit** - `fix(search): hide every unpublished status, not only drafts`
+
+---
+
+## Task 3: A list-level cache tag for pages
+
+**Files:** `server/services/content.js:170, 225, 243, 262`; test `tests/services/cache-invalidation.test.js` (extend)
+
+- [ ] **Step 1: Failing test** - add a case that `cache.wrap('t', fn, {tags: ['pages:list']})`, then `createPage(...)`, then the next `wrap` re-runs `fn`. Repeat for `updatePage`, `renamePage`, `deletePage`. Follow the file's existing setup for enabling the memory driver.
+- [ ] **Step 2: Run - expect failure.**
+- [ ] **Step 3:** Add `'pages:list'` to each of the four `cache.invalidateTags([...])` calls in `content.js`.
+- [ ] **Step 4: Run - pass.**
+- [ ] **Step 5: Commit** - `feat(cache): invalidate a pages list tag on every page write`
+
+---
+
+## Task 4: Shared token authentication and the `{content}` scope
+
+**Files:**
+- Modify: `server/services/apiTokens.js` (`validateScopes` :84, `scopeAllows` :110; new exports)
+- Modify: `server/routes/api/collections.js` (`checkPublicAccess` token branch)
+- Test: `tests/services/api-tokens-content-scope.test.js` (new); `tests/routes/collections-token-access.test.js`, `tests/routes/api-tokens.test.js`, `tests/routes/endpoints-execution.test.js` must pass unchanged
+
+- [ ] **Step 1: Failing test**
+
+```js
+/** Content scopes on API tokens, and the shared Bearer check. */
+import {before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    CONTENT_RESOURCES, authenticateApiToken, contentScopeAllows, createToken, revokeToken, scopeAllows, validateScopes
+} from '../../server/services/apiTokens.js';
+import {seedAll} from '../../server/services/presetCollections.js';
+
+before(async () => { await seedAll(); });
+
+test('validateScopes accepts {content} and {collection}, refuses a mix or an unknown resource', () => {
+    assert.equal(validateScopes([{content: 'pages'}, {collection: 'jobs', verbs: ['read']}]), null);
+    assert.match(validateScopes([{content: 'widgets'}]), /unknown content resource/);
+    assert.match(validateScopes([{content: 'pages', collection: 'jobs'}]), /either a collection or a content/);
+    assert.deepEqual([...CONTENT_RESOURCES], ['pages', 'menus', 'site', 'search']);
+});
+
+test('contentScopeAllows: unscoped allows all; scoped allows only listed', () => {
+    assert.equal(contentScopeAllows([], 'pages'), true);
+    assert.equal(contentScopeAllows([{content: 'pages'}], 'pages'), true);
+    assert.equal(contentScopeAllows([{content: 'pages'}], 'menus'), false);
+    // A token scoped to collections only gets no content - scoping never widens.
+    assert.equal(contentScopeAllows([{collection: 'jobs'}], 'pages'), false);
+});
+
+test('scopeAllows ignores content scopes when matching collections', () => {
+    assert.equal(scopeAllows([{content: 'pages'}], 'jobs', 'read'), false);
+    assert.equal(scopeAllows([{content: 'pages'}, {collection: 'jobs'}], 'jobs', 'read'), true);
+});
+
+test('authenticateApiToken: shape, validity, project, scope', async () => {
+    const {entry, plaintext} = await createToken({name: 't', project: 'core', scopes: [{content: 'pages'}]});
+    const req = (h) => ({headers: h ? {authorization: h} : {}});
+    try {
+        assert.deepEqual(await authenticateApiToken(req(null), {project: 'core', allows: () => true}),
+            {ok: false, status: 401, error: 'API token required'});
+        assert.equal((await authenticateApiToken(req('Bearer dcms_' + '0'.repeat(64)), {project: 'core', allows: () => true})).status, 401);
+        assert.equal((await authenticateApiToken(req(`Bearer ${plaintext}`), {project: 'other', allows: () => true})).status, 403);
+        assert.equal((await authenticateApiToken(req(`Bearer ${plaintext}`),
+            {project: 'core', allows: (s) => contentScopeAllows(s, 'menus')})).status, 403);
+        const ok = await authenticateApiToken(req(`Bearer ${plaintext}`),
+            {project: 'core', allows: (s) => contentScopeAllows(s, 'pages')});
+        assert.equal(ok.ok, true);
+        assert.equal(ok.token.id, entry.id);
+    } finally {
+        await revokeToken(entry.id);
+    }
+});
+```
+
+- [ ] **Step 2: Run - expect failure.**
+
+- [ ] **Step 3: Implement in `apiTokens.js`**
+
+```js
+/** The resources a `{content}` scope may name - the Content API's surface. */
+export const CONTENT_RESOURCES = Object.freeze(['pages', 'menus', 'site', 'search']);
+```
+
+`validateScopes` - each scope is EITHER `{collection, verbs?}` OR `{content}`:
+
+```js
+    for (const s of scopes) {
+        if (!s || typeof s !== 'object') return 'each scope must be an object';
+        const hasCollection = s.collection !== undefined;
+        const hasContent    = s.content !== undefined;
+        if (hasCollection && hasContent) return 'a scope names either a collection or a content resource, not both';
+        if (hasContent) {
+            if (!CONTENT_RESOURCES.includes(s.content)) return `unknown content resource "${s.content}"`;
+            if (s.verbs != null) return 'content scopes are read-only and take no verbs';
+            continue;
+        }
+        // …existing collection checks, unchanged…
+    }
+```
+
+`scopeAllows` - match only collection scopes:
+
+```js
+    const scope = scopes.find(s => s.collection !== undefined && s.collection === collectionSlug);
+```
+
+New:
+
+```js
+/**
+ * Does a token's scope list permit a Content API resource? Empty = everything
+ * in the project. A list that names no content resource permits none - a token
+ * scoped to collections is never widened by the Content API existing.
+ */
+export function contentScopeAllows(scopes, resource) {
+    if (!Array.isArray(scopes) || scopes.length === 0) return true;
+    return scopes.some(s => s.content === resource);
+}
+
+const BEARER = /^Bearer (dcms_[a-f0-9]{64})$/;
+
+/**
+ * The strict token check, shared by every externally consumable gate
+ * (collections, API Builder endpoints, the Content API). A token is the ONLY
+ * credential accepted - callers decide when token mode applies; this never
+ * looks at a JWT.
+ *
+ * @param {object} request - needs only request.headers
+ * @param {{project: string, allows: (scopes: object[]) => boolean}} opts
+ * @returns {Promise<{ok: true, token: object} | {ok: false, status: 401|403, error: string}>}
+ */
+export async function authenticateApiToken(request, {project, allows}) {
+    const match = (request.headers?.authorization || '').match(BEARER);
+    if (!match) return {ok: false, status: 401, error: 'API token required'};
+    const token = await validateToken(match[1]);
+    if (!token) return {ok: false, status: 401, error: 'Invalid, disabled or expired API token'};
+    if (token.project !== project) return {ok: false, status: 403, error: "Token is not valid for this resource's project"};
+    if (!allows(token.scopes)) return {ok: false, status: 403, error: 'Token scope does not permit this operation'};
+    return {ok: true, token};
+}
+```
+
+The project-mismatch message changes from "…this collection's project" to "…this resource's project". Grep the tests for the old string; if a test asserts it, keep the old wording for collections by passing an optional `projectError` in `opts` rather than editing the test.
+
+- [ ] **Step 4: `checkPublicAccess` delegates**
+
+```js
+    if (access.access === 'token') {
+        const project = resolveArtefactProject(schema);
+        const auth = await authenticateApiToken(request, {
+            project,
+            allows: (scopes) => scopeAllows(scopes, schema.slug, operation)
+        });
+        if (!auth.ok) return reply.status(auth.status).send({error: auth.error});
+        request.apiToken = auth.token;
+        return;
+    }
+```
+
+Update the import from `apiTokens.js`.
+
+- [ ] **Step 5: Run** the new test plus `collections-token-access`, `api-tokens`, `api-endpoints`, `endpoints-execution`. All pass unchanged.
+
+- [ ] **Step 6: Commit** - `refactor(api-tokens): shared token check; content scopes`
+
+---
+
+## Task 5: Content API settings and payload shaping
+
+**Files:**
+- Create: `server/services/contentApi.js`
+- Test: `tests/services/content-api-settings.test.js`, `tests/services/content-api-payload.test.js`
+
+- [ ] **Step 1: Failing tests**
+
+`content-api-settings.test.js`:
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {CONTENT_API_DEFAULTS, normaliseContentApiSettings} from '../../server/services/contentApi.js';
+
+test('off by default - an upgrade exposes nothing', () => {
+    const s = normaliseContentApiSettings({});
+    assert.equal(s.enabled, false);
+    assert.deepEqual(s, CONTENT_API_DEFAULTS);
+});
+
+test('access: public | token | a role name; anything else falls back to token', () => {
+    assert.equal(normaliseContentApiSettings({access: 'public'}).access, 'public');
+    assert.equal(normaliseContentApiSettings({access: 'token'}).access, 'token');
+    assert.equal(normaliseContentApiSettings({access: ' user '}).access, 'user');
+    assert.equal(normaliseContentApiSettings({access: ''}).access, 'token');
+    assert.equal(normaliseContentApiSettings({access: 42}).access, 'token');
+});
+
+test('resources: whitelisted, unknown keys dropped, missing = on', () => {
+    const s = normaliseContentApiSettings({resources: {pages: {enabled: false}, widgets: {enabled: true}}});
+    assert.deepEqual(Object.keys(s.resources), ['pages', 'menus', 'site', 'search']);
+    assert.equal(s.resources.pages.enabled, false);
+    assert.equal(s.resources.menus.enabled, true);
+});
+
+test('formats: subset of html/markdown, never empty', () => {
+    assert.deepEqual(normaliseContentApiSettings({formats: ['markdown', 'pdf']}).formats, ['markdown']);
+    assert.deepEqual(normaliseContentApiSettings({formats: []}).formats, ['html']);
+});
+
+test('listable and maxLimit', () => {
+    assert.equal(normaliseContentApiSettings({listable: false}).listable, false);
+    assert.equal(normaliseContentApiSettings({maxLimit: 5000}).maxLimit, 200);
+    assert.equal(normaliseContentApiSettings({maxLimit: 0}).maxLimit, 1);
+});
+```
+
+`content-api-payload.test.js`:
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {pageDetail, pageSummary, publicSiteSettings} from '../../server/services/contentApi.js';
+
+const page = {
+    urlPath: '/about', title: 'About', description: 'd', layout: 'default', tags: ['a'], category: 'c',
+    seo: {title: 'T', description: 'D', image: '/i.png', secretKey: 'x'},
+    createdAt: '2026-01-01', updatedAt: '2026-02-02', status: 'published', visibility: 'public',
+    dconfig: {x: 1}, sidebar: {y: 1}, internalNote: 'do not leak',
+    content: '## Hi [tabs]', html: '<h2>Hi</h2>', usedComponents: ['tabs'], perViewer: false, cacheTags: ['block:x']
+};
+
+test('summary: allowlisted keys only, no body', () => {
+    assert.deepEqual(Object.keys(pageSummary(page)).sort(),
+        ['category', 'description', 'layout', 'tags', 'title', 'updatedAt', 'urlPath'].sort());
+});
+
+test('detail: allowlist; unknown frontmatter never appears', () => {
+    const d = pageDetail(page, {format: 'both'});
+    for (const k of ['internalNote', 'dconfig', 'sidebar', 'status', 'visibility', 'cacheTags', 'content']) {
+        assert.equal(k in d, false, `${k} leaked`);
+    }
+    assert.deepEqual(d.seo, {title: 'T', description: 'D', image: '/i.png'});
+    assert.equal(d.html, '<h2>Hi</h2>');
+    assert.equal(d.markdown, '## Hi [tabs]');
+    assert.deepEqual(d.requires, {domma: true, components: ['tabs']});
+});
+
+test('detail: format picks the body', () => {
+    assert.equal('markdown' in pageDetail(page, {format: 'html'}), false);
+    assert.equal('html' in pageDetail(page, {format: 'markdown'}), false);
+});
+
+test('site settings: allowlist - smtp never present', () => {
+    const s = publicSiteSettings({title: 'S', tagline: 't', smtp: {pass: 'p'}, footer: {text: 'f'}, jwt: 'x'});
+    assert.equal('smtp' in s, false);
+    assert.equal('jwt' in s, false);
+    assert.equal(s.title, 'S');
+});
+```
+
+Before writing `publicSiteSettings`, open `config/site.json` and `server/services/renderer.js` (where `siteJson` is built) and pick the allowlist from keys that **already** reach every public page source - nothing new is exposed by the API.
+
+- [ ] **Step 2: Run - expect failure.**
+
+- [ ] **Step 3: Implement `server/services/contentApi.js`**
+
+```js
+/**
+ * Content API - settings and payloads.
+ *
+ * Settings live in config/content-api.json (optional; absence = the defaults,
+ * which are OFF - an upgrade must not expose a site that never chose to).
+ *
+ * Every payload is built from an ALLOWLIST. Frontmatter is open-ended (authors
+ * and plugins add keys freely) and site.json holds SMTP credentials, so a
+ * spread-then-delete is one forgotten key away from a leak.
+ */
+import {getConfig, saveConfig} from '../config.js';
+
+export const CONTENT_RESOURCE_KEYS = Object.freeze(['pages', 'menus', 'site', 'search']);
+export const FORMATS = Object.freeze(['html', 'markdown']);
+
+export const CONTENT_API_DEFAULTS = Object.freeze({
+    enabled: false,
+    access: 'token',
+    resources: Object.freeze(Object.fromEntries(CONTENT_RESOURCE_KEYS.map(k => [k, Object.freeze({enabled: true})]))),
+    formats: Object.freeze(['html']),
+    listable: true,
+    maxLimit: 200
+});
+
+const clamp = (v, lo, hi, fb) => { const n = Number(v); return Number.isFinite(n) ? Math.min(hi, Math.max(lo, Math.trunc(n))) : fb; };
+
+export function normaliseContentApiSettings(raw = {}) {
+    const access = typeof raw.access === 'string' && raw.access.trim() ? raw.access.trim() : CONTENT_API_DEFAULTS.access;
+    const resources = Object.fromEntries(CONTENT_RESOURCE_KEYS.map(k => [k, {enabled: raw.resources?.[k]?.enabled !== false}]));
+    const formats = Array.isArray(raw.formats) ? FORMATS.filter(f => raw.formats.includes(f)) : [...CONTENT_API_DEFAULTS.formats];
+    return {
+        enabled: raw.enabled === true,
+        access,
+        resources,
+        formats: formats.length ? formats : ['html'],
+        listable: raw.listable !== false,
+        maxLimit: clamp(raw.maxLimit, 1, 200, CONTENT_API_DEFAULTS.maxLimit)
+    };
+}
+
+export function getContentApiSettings() {
+    try { return normaliseContentApiSettings(getConfig('content-api')); }
+    catch { return normaliseContentApiSettings({}); }
+}
+
+export function saveContentApiSettings(patch) {
+    const next = normaliseContentApiSettings({...getContentApiSettings(), ...(patch || {})});
+    saveConfig('content-api', next);
+    return next;
+}
+
+const SUMMARY_KEYS = ['urlPath', 'title', 'description', 'tags', 'category', 'layout', 'updatedAt'];
+const DETAIL_KEYS  = [...SUMMARY_KEYS, 'createdAt'];
+const SEO_KEYS     = ['title', 'description', 'image', 'canonical', 'noindex'];
+
+const pick = (obj, keys) => Object.fromEntries(keys.filter(k => obj?.[k] !== undefined).map(k => [k, obj[k]]));
+
+export function pageSummary(page) {
+    return pick(page, SUMMARY_KEYS);
+}
+
+/**
+ * @param {object} page - a getPage() result the caller is allowed to see
+ * @param {{format: 'html'|'markdown'|'both'}} opts
+ */
+export function pageDetail(page, {format}) {
+    const out = pick(page, DETAIL_KEYS);
+    if (page.seo && typeof page.seo === 'object') out.seo = pick(page.seo, SEO_KEYS);
+    if (format === 'html' || format === 'both') out.html = page.html || '';
+    if (format === 'markdown' || format === 'both') out.markdown = page.content || '';
+    const components = Array.isArray(page.usedComponents) ? page.usedComponents : [];
+    out.requires = {domma: components.length > 0, components};
+    out.perViewer = Boolean(page.perViewer);
+    return out;
+}
+
+/** Site settings safe for any caller - see the allowlist note in the plan, Task 5. */
+export function publicSiteSettings(site = {}) {
+    // Fill from the keys renderer.js already embeds as __CMS_SITE__ - and no others.
+    return pick(site, ['title', 'tagline', 'description', 'language', 'brand', 'footer']);
+}
+```
+
+Widen `requires.domma` beyond `usedComponents` only if a test shows a Domma-dependent shortcode (tabs, carousel) that does not appear there - check `parseMarkdown` output for a `[tabs]` page first.
+
+- [ ] **Step 4: Run - pass.**
+- [ ] **Step 5: Commit** - `feat(content-api): settings and allowlisted payloads`
+
+---
+
+## Task 6: The public routes
+
+**Files:**
+- Create: `server/routes/api/content-public.js`
+- Modify: `server/server.js` (register; `onSend` exemption at :470)
+- Test: `tests/routes/content-api.test.js` (new), `tests/routes/content-api-parity.test.js` (new)
+
+- [ ] **Step 1: Failing route tests** - `tests/routes/content-api.test.js`. Harness as in `collections-token-access.test.js` (Fastify + `@fastify/jwt` + the routes). Settings are written with `saveContentApiSettings()` in each test and restored in `after()`. Cases, one `test()` each:
+
+1. Disabled (default) → every endpoint `404`.
+2. `access: 'public'`: `GET /api/content/v1/pages` → `200`, `{pages, total, page, limit}`; draft, scheduled, `visibility: user` and `api: false` pages absent.
+3. Single page `200` with `html`; `?format=markdown` → `400` while `formats: ['html']`; `200` once `formats` includes it; `?format=both` has both.
+4. `/pages/` → home; `/pages/<dir>` falls back to `<dir>/index`.
+5. Draft → `404`; `visibility: user` → `403` anonymous; `api: false` → `404`.
+6. `listable: false` → list `404`, single `200`.
+7. `resources.menus.enabled: false` → `/menus/navbar` `404`.
+8. `access: 'token'`: no header `401`; JWT `401`; token of another project → `404` for a page in this project (the project is the token's whole world); `{content: 'menus'}`-only token → `403` on `/pages`; `{collection: 'jobs'}`-only token → `403`; unscoped `core` token → `200` on a core page and `404` on a page in another project.
+9. `access: 'user'` (role): JWT for `user` → `200`; anonymous `401`; with `access: 'nonexistent-role'` a `user` JWT gets `403` and an `admin`-level-0 JWT `200`.
+10. Role mode `?preview=1` with `pages.read` → draft `200` and `cache-control: no-store`; without `pages.read` → `404`.
+11. `/site` never contains `smtp`.
+12. `/search?q=` → results; `config/search.json` `enabled: false` → `404`.
+13. Headers: public → `cache-control: public, max-age=60` + `etag`; token → `private`; role → `no-store`.
+14. `limit=0` → default 50; `limit=999` → `maxLimit`.
+
+`tests/routes/content-api-parity.test.js`: for fixture pages {public, draft, `user`, `=user`, `admin`, disabled-project} × viewers {anon, user, admin}, assert the allow/deny of `GET <path>` (via `publicRoutes`) matches `GET /api/content/v1/pages<path>` (role mode, JWT on both). `200 ↔ 200`, `404 ↔ 404`, `403 ↔ 403`.
+
+- [ ] **Step 2: Run - expect failure.**
+
+- [ ] **Step 3: Implement `server/routes/api/content-public.js`**
+
+```js
+/**
+ * Content API - /api/content/v1
+ *
+ * Read-only headless access to what the site publishes. Its own prefix:
+ * /api/v1/:slug matches any collection slug, and slugify() produces `pages`
+ * and `menus` happily, so living under /api/v1 would shadow real collections.
+ *
+ * GET /content/v1/pages            - paged summaries
+ * GET /content/v1/pages/*          - one page (?format=html|markdown|both)
+ * GET /content/v1/menus/:location  - bound menu, filtered for the caller
+ * GET /content/v1/site             - public site settings subset
+ * GET /content/v1/search?q=        - site search
+ *
+ * Access: config/content-api.json `access` - 'public', 'token' (strict,
+ * project-bound, {content} scopes) or a role name (JWT, ladder, unknown role
+ * fails closed to level 0). Page decisions go through resolvePublishedPage(),
+ * the same function the public site uses.
+ */
+import {getContentApiSettings, pageDetail, pageSummary, publicSiteSettings} from '../../services/contentApi.js';
+import {resolvePublishedPage, canPreviewDrafts} from '../../services/pagePublishing.js';
+import {listPages, getPageMtime} from '../../services/content.js';
+import {isPubliclyListed, searchExclusions, searchPages, getSearchSettings} from '../../services/search.js';
+import {resolveLocation} from '../../services/menus.js';
+import {authenticateApiToken, contentScopeAllows} from '../../services/apiTokens.js';
+import {getRoleLevel} from '../../services/roles.js';
+import {getEffectiveLevel} from '../../services/userRoles.js';
+import {getConfig} from '../../config.js';
+import {getBaseUrl} from '../public.js';
+import * as cache from '../../services/cache/index.js';
+
+const NOT_FOUND = {error: 'Not found'};
+
+/**
+ * Gate one request. Resolves to {mode, viewer, token} or sends the refusal and
+ * resolves to null. `project` is the resource's project for token binding -
+ * 'core' for site-wide resources; for a page the route re-checks after
+ * resolving it.
+ */
+export async function checkContentAccess(resource, request, reply) {
+    const s = getContentApiSettings();
+    if (!s.enabled || !s.resources[resource]?.enabled) { reply.status(404).send(NOT_FOUND); return null; }
+
+    if (s.access === 'public') return {mode: 'public', viewer: null, token: null, settings: s};
+
+    if (s.access === 'token') {
+        // No project here: pages carry their own, so the routes bind the token
+        // to it (inProject). See "Project binding" below.
+        const auth = await authenticateApiToken(request, {allows: (sc) => contentScopeAllows(sc, resource)});
+        if (!auth.ok) { reply.status(auth.status).send({error: auth.error}); return null; }
+        return {mode: 'token', viewer: null, token: auth.token, settings: s};
+    }
+
+    try { await request.jwtVerify(); } catch { reply.status(401).send({error: 'Unauthorised'}); return null; }
+    const named = getRoleLevel(s.access);
+    const required = Number.isFinite(named) ? named : 0;
+    if (getEffectiveLevel(request.user) > required) { reply.status(403).send({error: 'Insufficient permissions'}); return null; }
+    return {mode: 'role', viewer: request.user, token: null, settings: s};
+}
+```
+
+**Project binding:** in `authenticateApiToken` (Task 4), make `project` optional - compare only when it is given (`if (project !== undefined && token.project !== project)`), and add a Task 4 test that omitting it skips the check. The rule for content:
+- `pages` (single and list) and `search` results: only pages whose project is the token's (`inProject`). A page in another project is `404`.
+- `menus` and `site`: readable by any valid token. They are site-wide and already shown on every public page.
+
+Write this rule into the spec's "Tokens and projects" section in the same commit; it replaces "Menus and site settings … belong to `core`".
+
+Routes (inside `export async function contentPublicRoutes(fastify)`):
+
+```js
+    const headersFor = (reply, access) => {
+        if (access.mode === 'public') reply.header('cache-control', 'public, max-age=60');
+        else if (access.mode === 'token') reply.header('cache-control', 'private, max-age=0, must-revalidate');
+        else reply.header('cache-control', 'no-store');
+    };
+    const inProject = (access, project) => access.mode !== 'token' || access.token.project === project;
+    const apiOff = (page) => page?.api === false;
+
+    fastify.get('/content/v1/pages', async (request, reply) => {
+        const access = await checkContentAccess('pages', request, reply);
+        if (!access) return;
+        if (!access.settings.listable) return reply.status(404).send(NOT_FOUND);
+        const q = request.query || {};
+        const limit = Math.min(access.settings.maxLimit, parseInt(q.limit, 10) || 50);
+        const pageNo = Math.max(1, parseInt(q.page, 10) || 1);
+
+        const all = await listPages();
+        const exclusions = await searchExclusions(all);
+        let rows = all.filter(p => isPubliclyListed(p, access.viewer, exclusions)
+            && !apiOff(p)
+            && inProject(access, p.resolvedProject));
+        if (q.prefix) rows = rows.filter(p => (p.urlPath || '').startsWith(String(q.prefix)));
+        if (q.tag) rows = rows.filter(p => Array.isArray(p.tags) && p.tags.includes(String(q.tag)));
+        if (q.category) rows = rows.filter(p => p.category === String(q.category));
+        if (q.project) rows = rows.filter(p => p.resolvedProject === String(q.project));
+        // sort: sortOrder (listPages' own order) | title | updatedAt | createdAt
+        // …implement with a small comparator; order=desc reverses
+
+        headersFor(reply, access);
+        const start = (pageNo - 1) * limit;
+        return {pages: rows.slice(start, start + limit).map(pageSummary), total: rows.length, page: pageNo, limit};
+    });
+
+    fastify.get('/content/v1/pages/*', async (request, reply) => {
+        const access = await checkContentAccess('pages', request, reply);
+        if (!access) return;
+        const format = String(request.query?.format || 'html');
+        const allowed = format === 'both' ? ['html', 'markdown'] : [format];
+        if (!['html', 'markdown', 'both'].includes(format) || !allowed.every(f => access.settings.formats.includes(f))) {
+            return reply.status(400).send({error: `Format "${format}" is not available on this site`});
+        }
+        const urlPath = '/' + (request.params['*'] || '');
+        const preview = access.mode === 'role' && request.query?.preview === '1' && canPreviewDrafts(access.viewer);
+        const verdict = await resolvePublishedPage(urlPath, access.viewer, {allowDrafts: preview});
+        if (verdict.status === 'not-found' || apiOff(verdict.page) || (verdict.status === 'ok' && !inProject(access, verdict.project))) {
+            return reply.status(404).send(NOT_FOUND);
+        }
+        if (verdict.status === 'forbidden') return reply.status(403).send({error: 'Forbidden'});
+
+        const build = () => pageDetail(verdict.page, {format});
+        if (verdict.isDraft || access.mode === 'role') {
+            reply.header('cache-control', 'no-store');
+            return build();
+        }
+        const mtime = await getPageMtime(verdict.page.urlPath || urlPath);
+        const key = `content:v1:page:${verdict.page.urlPath}:${format}:m${mtime}:o${getBaseUrl(request)}`;
+        const tags = [`page:${verdict.page.urlPath}`, ...(verdict.page.cacheTags || []), 'nav', 'site'];
+        const body = await cache.wrap(key, async () => build(), {tags});
+        headersFor(reply, access);
+        reply.header('etag', `W/"${mtime}-${format}"`);
+        return body;
+    });
+```
+
+`menus/:location`, `site`, `search`: same shape - gate, build, headers. Menus: `resolveLocation(request.params.location, access.viewer, {urlPath: request.query.page})`; `null` → 404; refuse `location === 'overlay'` (404) and the `admin-sidebar` slot (404 - never expose the admin menu). Search: 404 when `getSearchSettings().enabled === false`; filter with `isSearchable` (already in `searchPages`) plus `!apiOff` and `inProject`; clamp `limit` to `getSearchSettings().maxResults`. Site: `publicSiteSettings(getConfig('site'))`.
+
+Page payloads in role mode for a `perViewer` page are rendered for that viewer: `resolvePublishedPage` fetches anonymously, so re-fetch with `getPage(verdict.page.urlPath, {user: access.viewer})` when `access.viewer` is set - as `public.js`'s `render()` does.
+
+- [ ] **Step 4: Wire into `server/server.js`**
+
+```js
+const {contentPublicRoutes} = await import('./routes/api/content-public.js');
+await app.register(contentPublicRoutes, {prefix: '/api'});
+```
+
+and in the `onSend` hook:
+
+```js
+    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/') || url.startsWith('/api/content/v1/')) return;
+```
+
+Update the comment above it to list the third surface. Check `server.js:141` (CORS open reads) - if `/api/v1/` is listed there for cross-origin reads, add `/api/content/v1/` alongside, since headless front ends are cross-origin by nature.
+
+- [ ] **Step 5: Run** both new test files, then `npm test` (full suite) once.
+- [ ] **Step 6: Commit** - `feat(content-api): /api/content/v1 pages, menus, site, search`
+
+---
+
+## Task 7: Admin API for the screen
+
+**Files:**
+- Create: `server/routes/api/content-api.js`
+- Modify: `server/server.js` (register the routes; the sidebar item moves to Task 8, with the screen it links to)
+- Test: `tests/routes/content-api-admin.test.js`
+
+- [ ] **Step 1: Failing test** - `GET /api/content-api/settings` needs `settings.read` (401 anon, 200 admin, returns normalised defaults); `PUT` needs `settings.update`, normalises (`formats: []` stored as `['html']`), returns `{ok, settings}`; `GET /api/content-api/_count` returns `{count, label, tone, details}` where `count` is the number of pages the API would list anonymously (or `0` + label `Off` when disabled); `GET /api/content-api/preview?path=/about&format=html&as=anon` renders through the same `pageDetail` and `resolvePublishedPage` as the public route, ignoring `enabled` (so the screen can test before switching on), and refuses `as` values other than `anon`.
+
+- [ ] **Step 2: Run - fail.**
+
+- [ ] **Step 3: Implement** - mirror `server/routes/api/search.js`: `authenticate` + `requirePermission('settings', 'read'|'update')`; badge details built with the helpers in `server/services/sidebarBadges.js` (rows: Access, Formats, Listable; tone `info` when on, nothing when off). Preview reuses an extracted function from `content-public.js` (`buildPageResponse(urlPath, {viewer, format, allowDrafts})`) - do not re-implement it.
+
+- [ ] **Step 4: Sidebar + register**
+
+```js
+registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Content API', url: '#/content-api', icon: 'file-text', permission: 'settings', countUrl: '/api/content-api/_count', inventory: true}});
+```
+
+- [ ] **Step 5: Run - pass. Commit** - `feat(content-api): admin settings, badge and preview endpoints`
+
+---
+
+## Task 8: System › Content API screen (Domma reactive)
+
+The screen follows **System › Search** (`admin/js/views/search.js` + `admin/js/templates/search.html` + `admin/js/lib/search-settings-arrange.js`) in every structural respect. The rules, all Domma:
+
+- **State is domma-reactive.** One `M.observable` per form field, `M.computed` for derived values (dirty, chips, endpoints, curl), `M.effect` for side effects, every effect's disposer pushed through `scope()`. No hand-held state variables beyond the `active` handle.
+- **Bindings, not DOM writes.** `M.applyBindings(model, root, {methods})` with `data-model`, `data-bind-text`, `data-bind-hidden`, `data-bind-class`, `data-bind-disabled`, `data-on-click`, `data-each`. Repeated rows use an inline row template inserted by the view (the router renders `templateUrl` through `_.render`, which eats `{{…}}`).
+- **Components:** `E.tabs` for the tabs, `E.toast` for outcomes, `E.confirm` for leave/restore, `E.contextMenu` (with `openMenuAt` from `tool-kit.js`) on try-it results, `helpPopovers()` for `data-help`, `addBannerAction()` for Save and Copy base URL, `I.scan(root)` for icons, `S` for the draft, `apiRequest` (`admin/js/api.js`) for HTTP.
+- **Loading:** first load through `whileLoading(slot, …, SHAPES.rows)` from `admin/js/lib/loading.js` - a skeleton, not `E.loader` and not "Loading…" text. `E.loader` only for work in progress (Save).
+- **Leaving:** the router guard RETURNS the `E.confirm` promise (`tests/admin/nav-guard-contract.test.js`); tear-down on `router:afterChange`; unsaved changes kept as a draft (`content-api.draft`) and offered back; `beforeunload` asks.
+- **Ctrl+S** saves (capture + `stopImmediatePropagation`, as Search does).
+- **Pure logic in the arrange lib**, tested under `tests/admin/`. The view holds wiring only.
+
+**Files:**
+- Create: `admin/js/lib/content-api-arrange.js`, `admin/js/views/content-api.js`, `admin/js/templates/content-api.html`
+- Modify: `server/server.js` - the System sidebar entry, moved here from Task 7 so it never links to a screen that does not exist yet:
+  `registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Content API', url: '#/content-api', icon: 'file-text', permission: 'settings', countUrl: '/api/content-api/_count', inventory: true}});` (check the icon exists in Domma's set)
+- Modify: `admin/js/views/index.js` (import + `contentApi: contentApiView`), `admin/js/app.js` (route `{path: '/content-api', view: 'contentApi', title: 'Content API - Domma CMS'}` beside `/search`; Tool banner map `contentApi: {displayName: 'Content API', icon: 'file-text'}`), `admin/css/admin.css` (`.cax-*`)
+- Test: `tests/admin/content-api-arrange.test.js`; `tests/admin/nav-guard-contract.test.js` (add the view if it enumerates views)
+
+- [ ] **Step 1: Failing arrange tests** - `tests/admin/content-api-arrange.test.js`:
+
+```js
+/** System › Content API - admin/js/lib/content-api-arrange.js. */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    curlExample, endpointRows, formFromSettings, liveChips, payloadFromForm, previewRow, snapshot
+} from '../../admin/js/lib/content-api-arrange.js';
+
+const S = {enabled: true, access: 'token', resources: {pages: {enabled: true}, menus: {enabled: false}, site: {enabled: true}, search: {enabled: true}},
+    formats: ['html'], listable: true, maxLimit: 200};
+
+test('form round-trips settings', () => {
+    assert.deepEqual(payloadFromForm(formFromSettings(S)), S);
+});
+
+test('form flattens resources and formats into plain fields for data-model', () => {
+    const f = formFromSettings(S);
+    assert.equal(f.resPages, true);
+    assert.equal(f.resMenus, false);
+    assert.equal(f.fmtHtml, true);
+    assert.equal(f.fmtMarkdown, false);
+    assert.equal(f.accessMode, 'token');
+    assert.equal(f.accessRole, '');
+});
+
+test('a role access mode splits into mode=role + the role name', () => {
+    const f = formFromSettings({...S, access: 'user'});
+    assert.equal(f.accessMode, 'role');
+    assert.equal(f.accessRole, 'user');
+    assert.equal(payloadFromForm(f).access, 'user');
+});
+
+test('turning both formats off keeps html - the server would anyway', () => {
+    assert.deepEqual(payloadFromForm({...formFromSettings(S), fmtHtml: false, fmtMarkdown: false}).formats, ['html']);
+});
+
+test('snapshot is order-stable for the dirty check', () => {
+    assert.equal(snapshot(formFromSettings(S)), snapshot({...formFromSettings(S)}));
+    assert.notEqual(snapshot(formFromSettings(S)), snapshot({...formFromSettings(S), listable: false}));
+});
+
+test('live chips describe the SAVED state', () => {
+    assert.deepEqual(liveChips({...S, enabled: false}).map(c => c.text), ['Off']);
+    const on = liveChips(S, {listed: 12}).map(c => c.text);
+    assert.ok(on.includes('On'));
+    assert.ok(on.includes('Token'));
+    assert.ok(on.includes('12 pages'));
+});
+
+test('endpoint rows: disabled resources are marked, list hidden when not listable', () => {
+    const rows = endpointRows('https://ex.com', S);
+    const menus = rows.find(r => r.path.startsWith('/api/content/v1/menus'));
+    assert.equal(menus.state, 'off');
+    assert.equal(rows.find(r => r.path === '/api/content/v1/pages').state, 'on');
+    const unlisted = endpointRows('https://ex.com', {...S, listable: false});
+    assert.equal(unlisted.find(r => r.path === '/api/content/v1/pages').state, 'off');
+});
+
+test('curl: token mode carries a Bearer placeholder, never a real token', () => {
+    const c = curlExample('https://ex.com', '/about', S);
+    assert.match(c, /Authorization: Bearer dcms_…/);
+    assert.match(c, /https:\/\/ex\.com\/api\/content\/v1\/pages\/about/);
+    assert.doesNotMatch(curlExample('https://ex.com', '/about', {...S, access: 'public'}), /Authorization/);
+});
+
+test('preview row: status, size and what the client must load', () => {
+    const r = previewRow({status: 200, body: {title: 'About', html: '<p>x</p>', requires: {domma: true, components: ['tabs']}}});
+    assert.equal(r.statusText, '200');
+    assert.equal(r.tone, 'ok');
+    assert.equal(r.requiresText, 'Needs Domma: tabs');
+    assert.equal(previewRow({status: 404, body: {error: 'Not found'}}).tone, 'bad');
+});
+```
+
+- [ ] **Step 2: Run - fail.** `npm test -- tests/admin/content-api-arrange.test.js`
+
+- [ ] **Step 3: Implement `admin/js/lib/content-api-arrange.js`** - pure ESM, no `$`/`E`/`M`, no DOM. Exports exactly those in the test plus `ACCESS_LABEL = {public: 'Public', token: 'Token', role: 'Role'}`. `endpointRows` returns `{method: 'GET', path, label, state: 'on'|'off', note}` for the five endpoints (menus path shown as `/api/content/v1/menus/navbar`).
+
+- [ ] **Step 4: Run - pass.**
+
+- [ ] **Step 5: Template `admin/js/templates/content-api.html`**
+
+Header comment as Search's (bound with `M.applyBindings`; row templates inserted by the view; no page heading - the Tool banner is the heading). Structure:
+
+```html
+<div class="cax">
+    <div class="cax-note dm-loading-slot" data-bind-hidden="!loading.value">Loading…</div>
+
+    <p class="cax-alert is-dirty" data-bind-hidden="!dirty.value">
+        <span data-icon="edit-3" data-icon-size="16"></span>
+        <span>Unsaved changes - Save (Ctrl+S) to apply them. Leave and they are kept as a draft for next time.</span>
+        <span class="cax-spacer"></span>
+        <button type="button" class="btn btn-sm btn-ghost" data-on-click="discard">Discard</button>
+        <button type="button" class="btn btn-sm btn-primary" data-on-click="save" data-bind-disabled="saving.value">Save</button></p>
+
+    <div class="tabs cax-tabs" data-bind-hidden="loading.value">
+        <div class="tab-list">
+            <button type="button" class="tab-item active">Access</button>
+            <button type="button" class="tab-item">Endpoints</button>
+            <button type="button" class="tab-item">Try it</button>
+            <button type="button" class="tab-item">How it works</button>
+        </div>
+
+        <!-- Access -->
+        <div class="tab-panel active">
+            <div class="cax-card">
+                <div class="cax-card-title">Live now
+                    <span data-help-title="Live now" data-help="What callers get at the moment - the saved settings, not what you are editing."></span></div>
+                <div class="cax-chips" data-each="chips.value key=text"></div>
+            </div>
+            <div class="cax-card">
+                <div class="cax-setting">
+                    <label class="form-label" for="cax-enabled">Enable the Content API
+                        <span data-help="Off answers 404 on every /api/content/v1 address. Pages on the site are not affected."></span></label>
+                    <input id="cax-enabled" type="checkbox" class="form-switch" data-model="enabled.value">
+                </div>
+                <label class="form-label" for="cax-access">Who may call it
+                    <span data-help="Public: anyone. Token: an API token from System › API Tokens, bound to a project. Role: a signed-in user of that role or more senior."></span></label>
+                <select id="cax-access" class="form-select" data-model="accessMode.value">
+                    <option value="token">API token</option>
+                    <option value="public">Public</option>
+                    <option value="role">A role…</option>
+                </select>
+                <div data-bind-hidden="accessMode.value !== 'role'">
+                    <label class="form-label" for="cax-role">Role</label>
+                    <select id="cax-role" class="form-select cax-roles" data-model="accessRole.value" data-each="roles.value key=name"></select>
+                    <small class="cax-err" data-bind-hidden="!roleErr.value" data-bind-text="roleErr.value"></small>
+                </div>
+            </div>
+            <div class="cax-card">
+                <div class="cax-card-title">Resources</div>
+                <!-- one cax-setting + form-switch per resource: resPages, resMenus, resSite, resSearch -->
+                <!-- listable switch, fmtHtml / fmtMarkdown switches, maxLimit number input (1-200) -->
+            </div>
+        </div>
+
+        <!-- Endpoints: data-each="endpoints.value key=path" list + copy buttons -->
+        <!-- Try it: path input (data-model="tryPath.value"), format select, Run button,
+             result: status chip, requiresText, <pre class="cax-json" data-bind-text="tryJson.value">,
+             curl <pre data-bind-text="curl.value"> with a Copy button -->
+        <!-- How it works: static prose - drafts, visibility, projects, api: false, formats, caching -->
+    </div>
+</div>
+```
+
+Write the elided cards in full in the real file, using the same `cax-setting` / `form-switch` / `data-help` pattern shown. The Markdown format switch's help says: *"Markdown is the page source - shortcodes included, which can name collections, views and forms the HTML does not show."*
+
+- [ ] **Step 6: View `admin/js/views/content-api.js`**
+
+Mirror `search.js` section by section - header comment, `SCREEN` regex `/^\/content-api(\?.*)?$/`, `wireRouter()` guard returning the confirm, `active` handle, `onMount`:
+
+```js
+import {apiRequest} from '../api.js';
+import {addBannerAction} from '../lib/plugin-chrome.js';
+import {helpPopovers} from '../lib/help-popover.js';
+import {openMenuAt, sidebarCount} from '../lib/tool-kit.js';
+import {SHAPES, whileLoading} from '../lib/loading.js';
+import {fmtDateTime} from '../lib/dates.js';
+import {
+    ACCESS_LABEL, curlExample, endpointRows, formFromSettings, liveChips, payloadFromForm, previewRow, snapshot
+} from '../lib/content-api-arrange.js';
+
+const SCREEN = /^\/content-api(\?.*)?$/;
+const SIDEBAR_URL = '#/content-api';
+const DRAFT_KEY = 'content-api.draft';
+
+const CHIP_TEMPLATE = `<span class="cax-chip" data-bind-class="cls">{{text}}</span>`;
+const ENDPOINT_TEMPLATE = `
+<div class="cax-row" data-bind-class="cls" data-path="{{path}}">
+    <span class="cax-method">{{method}}</span>
+    <span class="cax-main"><code>{{path}}</code><small>{{label}}</small></span>
+    <span class="cax-chip">{{stateText}}</span>
+    <button type="button" class="cax-kebab" aria-label="Actions for {{path}}" title="Actions">⋮</button>
+</div>`;
+const ROLE_TEMPLATE = `<option value="{{name}}">{{label}}</option>`;
+```
+
+In `onMount`:
+
+1. `wireRouter()`; dispose any previous `active`; `disposers` / `scope()` / `here()` exactly as Search.
+2. `const loading = M.observable(true);` - then
+   `const [settings, badge, roles] = await whileLoading(root.querySelector('.dm-loading-slot'), Promise.all([apiRequest('/content-api/settings'), apiRequest('/content-api/_count').catch(() => null), apiRequest('/roles').catch(() => [])]), SHAPES.rows);`
+   then `loading.value = false`. On error: `E.toast(…, {type: 'error'})` and return. Check the real roles list endpoint and its shape before wiring (`server/routes/api/roles.js`).
+3. State: `saved = M.observable(settings)`; `f = {}` of `M.observable` per key of `formFromSettings(settings)`; `form()` / `peekForm()`; `savedSnap`; `dirty = M.computed(() => snapshot(form()) !== savedSnap.value)`; `saving`; `chips` via `M.effect` from `liveChips(saved.value, {listed: badge?.count})`; `endpoints = M.computed(() => endpointRows(location.origin, payloadFromForm(form())).map(r => ({...r, stateText: r.state === 'on' ? 'On' : 'Off', cls: r.state === 'off' ? 'is-off' : ''})))`; `roleErr = M.computed(() => f.accessMode.value === 'role' && !f.accessRole.value ? 'Pick a role.' : '')`; `roles = M.observable(roleOptions)`.
+4. Try it: `tryPath`, `tryFormat`, `tryJson`, `tryRow` observables; `curl = M.computed(() => curlExample(location.origin, tryPath.value || '/', payloadFromForm(form())))`; `run()` calls `apiRequest('/content-api/preview?path=…&format=…&as=anon')` with a sequence guard like Search's `seq`, sets `tryJson.value = JSON.stringify(body, null, 2)` and `tryRow.value = previewRow({status, body})`. Run on the button, not on every keystroke.
+5. `save()` - as Search: `PUT /content-api/settings` with `payloadFromForm(peekForm())`, refuse while `roleErr.peek()`, take the server's normalised version as the new baseline, clear the draft, `sidebarCount(SIDEBAR_URL)`, toast `Saved - the Content API is on.` / `Saved - the Content API is off.`
+6. `discard()` - reset `f` from `saved.peek()`.
+7. Insert row templates into `.cax-chips`, `.cax-endpoints`, `.cax-roles`; `const tabs = E.tabs(root.querySelector('.cax-tabs'), {tabSelector: '.tab-item', panelSelector: '.tab-panel'});`; `const bindings = M.applyBindings(model, root, {methods: {save, discard, run, copyCurl, copyBase}});` and `scope(() => bindings.dispose())`; `scope(helpPopovers(root, {position: 'bottom'}))`.
+8. Endpoint rows: `E.contextMenu(list, {cursor: 'glyph', match: '.cax-row', inherit: false, density: 'compact', items: (row) => […]})` with Copy URL, Copy curl, Open in new tab (GET only, public mode only); ⋮ → `openMenuAt`; Shift+F10 on a focused row. Clipboard failure falls back to `E.toast(text, {type: 'info', duration: 8000})` as Search does.
+9. Banner actions: `addBannerAction($container, {id: 'content-api-save', icon: 'save', title: 'Save (Ctrl+S)', onClick: () => save()})` and `{id: 'content-api-tokens', icon: 'key', title: 'API Tokens', onClick: () => { location.hash = '#/api-tokens'; }}`.
+10. Ctrl+S, `beforeunload`, `keepDraft`, `active = {dirty, dispose}`, `I.scan(root)`, draft restore with `E.confirm` - copied from Search with the key and wording changed.
+
+- [ ] **Step 7: Register** in `views/index.js` and `app.js` (route + Tool banner map). Add `.cax-*` CSS to `admin/css/admin.css` by copying the `.ssx-*` block's structure (card, setting, chips, rows, alert) - reuse the same tokens, no new colours.
+
+- [ ] **Step 8: Contract tests** - run `tests/admin/nav-guard-contract.test.js` and any `tests/admin/*` that enumerate views or templates (grep for `search.html` / `searchView` in `tests/admin/`); add the new view wherever Search appears.
+
+- [ ] **Step 9: Run it** - start the app (`run` skill), open `#/content-api`, and check: the skeleton appears then goes; toggling marks the alert dirty; Discard resets; Save toasts and the sidebar badge updates; leaving with changes asks, and the draft is offered back on return; Try it on `/` returns 200 JSON; Endpoints right-click copies; both themes look right.
+
+- [ ] **Step 10: Commit** - `feat(admin): System › Content API screen`
+
+---
+
+## Task 9: Token editor - content scopes
+
+**Files:** `admin/js/lib/api-tokens-arrange.js`, `admin/js/views/api-tokens.js` (scopes help text and placeholder only), `server/services/scaffold*.js` (only if recipe `apiTokens[].scopes` is validated separately - grep); test `tests/admin/api-tokens-arrange.test.js` (extend)
+
+Text syntax: a line starting `@` is a content scope - `@pages`, `@menus`, `@site`, `@search`. Collection slugs come from `slugify()` and can never start with `@`, so there is no ambiguity.
+
+- [ ] **Step 1: Failing tests** (add to the existing file):
+
+```js
+test('content scopes: @resource lines round-trip, take no verbs, unknown refused', () => {
+    const scopes = [{collection: 'jobs', verbs: ['read']}, {content: 'pages'}, {content: 'menus'}];
+    assert.equal(scopesToText(scopes), 'jobs: read\n@pages\n@menus');
+    assert.deepEqual(parseScopes('jobs: read\n@pages\n @menus '), {scopes});
+    assert.match(parseScopes('@widgets').error, /not a content resource/);
+    assert.match(parseScopes('@pages: read').error, /take no verbs/);
+    assert.match(parseScopes('@pages\n@pages').error, /twice/);
+    assert.equal(scopesSummary([{content: 'pages'}]), 'content: pages');
+});
+```
+
+- [ ] **Step 2: Run - fail. Step 3: Implement** (export `CONTENT_RESOURCES` from the arrange lib with the same four values; keep in step with `apiTokens.js` - add a test that imports both and compares). Placeholder becomes `jobs: read&#10;enquiries: create, read&#10;@pages`; help text gains one sentence on `@pages` / `@menus` / `@site` / `@search`.
+
+- [ ] **Step 4: Run - pass. Commit** - `feat(api-tokens): content scopes in the token editor`
+
+---
+
+## Task 10: Docs
+
+- [ ] `docs/api-reference.md` - new section **Content API (`/api/content/v1/*`)** after "External API & API tokens": endpoints, query params, response shapes, access modes, token project/scope rules (`{content}` / `@pages`), errors, caching, `api: false`, formats and `requires`.
+- [ ] In-admin API reference: a **Content API** page beside `apiRefExternal` (find its view with `grep -rn apiRefExternal admin/js`), route `#/docs/api/content`, sidebar entry under **API Reference** (`server.js:668`). Same component style as the External API page.
+- [ ] `.claude/skills/domma-api-surface/SKILL.md` - a **Content API** section: own prefix and why, `resolvePublishedPage` is the one decision, `authenticateApiToken` shared, `{content}` scopes never widen a scoped token, allowlisted payloads, `api: false`.
+- [ ] `CLAUDE.md` - extend the "External API & API tokens" paragraph by one sentence naming `/api/content/v1`.
+- [ ] `docs/configuration.md` - `config/content-api.json` schema; add it to the CLAUDE.md config table (Owner: Yours).
+- [ ] `FEATURES.md`, `docs/DommaFeatures.md`, `docs/editions-and-licences.md` (confirm the tier), `CHANGELOG.md` (Added: Content API; Fixed: search found unpublished non-draft pages).
+- [ ] Mark the spec **Status: Approved - implemented in <version>** and fold in the project-binding rule settled in Task 6.
+- [ ] **Commit** - `docs: Content API`
+
+---
+
+## Done when
+
+- `npm test` passes in full.
+- The four existing public-route test files and the token/endpoint test files are unmodified.
+- The parity test passes for every page × viewer combination.
+- The screen has been driven in the real app (Task 8, Step 9).
+- No endpoint returns `smtp`, unknown frontmatter, a draft to a non-`pages.read` caller, or anything with the API off.