caracms 0.3.3 → 0.4.0

package/README.md

@@ -36,7 +36,8 @@ npm install
 ```
 
 `init` adds the plumbing (the Node adapter, the integration, a minimal `caracms.config.ts`
-and page component, the route that serves documents, the schemas) and links caracms's
+and page component, the one catch-all route that serves every document with an address,
+the schemas) and links caracms's
 skills into `.claude/skills/`. It doesn't touch the site's pages. Bringing them in is the
 job of the `caracms-adopt` skill, one page at a time.
 
@@ -58,6 +59,27 @@ Run from the site's root:
 The skills (`caracms-content`, `caracms-blocks` and `caracms-adopt`, in `skills/`) say how
 the rest works, matching the installed version.
 
+## Collections and addresses
+
+A collection that has pages of its own gets its address from exactly one of three places:
+
+| Source | In the config | In the content | A document's address |
+|---|---|---|---|
+| **Pageless** | no `urlBase` | none | none: records other pages list (a team, awards, logos) |
+| **A prefix in code** | `urlBase: '/tags/'` | none | `urlBase` + slug: `/tags/<slug>`, with no page at `/tags` |
+| **Held by a page** | `heldBy: 'pages'` | the page's file says `"holds": "journal"` | the page's address + `/` + slug: posts at `/journal/<slug>`, and at `/blog/<slug>` once the page moves |
+
+`heldBy` and `urlBase` are exclusive, and a held collection is flat. A page holds at most
+one collection (never Home), and `caracms validate` reports a `holds` that doesn't match a
+`heldBy`.
+
+One catch-all route, `src/pages/[...path].astro`, serves all three. It lists what to build
+with `addressedDocuments(site)` from `caracms/content` (`{ collection, path, url }` for
+every public page, leaving out hidden ones and files that can't be opened), and a site that
+renders on demand uses `documentAt(site, pathname)`. A collection needs no route of its
+own; a prefix collection whose base keeps its own route file is left out of the reader,
+and a route with parameters left at a held collection's address is a `validate` error.
+
 ## Hosting
 
 caracms runs on any host that keeps one Node server running behind HTTPS: Railway,
@@ -90,8 +112,9 @@ These go on the site's server. `caracms init` prints the same list.
 
 | Name | Needed | What it's for |
 |---|---|---|
-| `GITHUB_REPO` | required | The site's repository, as owner/name. |
-| `CARACMS_GITHUB_TOKEN` | required, or the App | A fine-grained token (`github_pat_…`) on that one repo: Contents read and write, Metadata read (Deployments read is optional). Never `GITHUB_TOKEN`. |
+| `CARACMS_CLOUD_KEY` | instead of the GitHub variables | The site's key from CaraCMS Cloud (`cck_…`). It replaces the token or App and `GITHUB_REPO`: see [CaraCMS Cloud](#caracms-cloud). |
+| `GITHUB_REPO` | required, but not with the cloud key | The site's repository, as owner/name. |
+| `CARACMS_GITHUB_TOKEN` | required, or the App, or the cloud key | A fine-grained token (`github_pat_…`) on that one repo: Contents read and write, Metadata read (Deployments read is optional). Never `GITHUB_TOKEN`. |
 | `GITHUB_APP_ID` | instead of the token | The GitHub App's ID, for anyone setting up many sites. Set the token or the App, not both. |
 | `GITHUB_APP_PRIVATE_KEY` | with `GITHUB_APP_ID` | The App's private key. |
 | `SITE_URL` | required | The site's public address, https://. The same value at build and at run time. |
@@ -275,6 +298,39 @@ site, signs every commit, and isn't tied to a person. Use it for anyone running
 a handful of sites, or a repo that requires signed commits. Install it on the site's repo
 only, with the same permissions as the token.
 
+### CaraCMS Cloud
+
+A site run by CaraCMS can take its GitHub access from CaraCMS Cloud instead of a token or
+an App of its own. The cloud gives the site's server a short-lived token for the site's
+repo, and only that repo, about once an hour.
+
+1. CaraCMS sets the site's repo in CaraCMS Cloud.
+2. Install the caracms GitHub App on that repo, choosing only that repo. The site's page in
+   app.caracms.com says whether it's installed, and links to the App's install page when
+   it isn't.
+3. Make a key for the site in app.caracms.com and set it as `CARACMS_CLOUD_KEY` on the
+   site's server.
+
+The key replaces `CARACMS_GITHUB_TOKEN` (or `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`)
+and `GITHUB_REPO`: the repo comes from the cloud when the server starts, so setting
+`GITHUB_REPO` beside the key is refused, and so is setting a token or an App as well.
+Everything else in [the variables](#the-variables) is still the site's own: `SITE_URL`,
+`REDIS_URL`, `CARACMS_SECRET`, the sign-in variables, and the image, video and form
+variables. There's no webhook: a check once a minute keeps the editor's Publish status up
+to date.
+
+If the cloud says no when the server starts (the App isn't installed on the repo, the
+site has no repo yet, the key was revoked), `/admin` answers 503 with the cloud's own
+sentence, and the public site still serves. The next visit to `/admin` tries again. If it
+says no later, while the editor is open, the editor shows the same sentence until the
+cloud gives a token again. A repo changed in CaraCMS Cloud reaches the site at its next
+start.
+
+**On a laptop**, a cloud key turns `astro dev` into live mode on the site's real repo,
+as the App's variables do. Use a key from CaraCMS Cloud's dev deployment there (set its
+address as `CARACMS_CLOUD_URL`), never a production key: the dev deployment only gives
+out tokens for throwaway repos. Leave `CARACMS_CLOUD_URL` unset everywhere else.
+
 ### Behind Cloudflare
 
 caracms sees through Cloudflare's proxy (the orange cloud) by itself: when the address

package/bin/caracms.mjs

@@ -12,20 +12,22 @@
 // The Node adapter's standalone server sends prerendered pages and static files
 // before Astro's middleware runs, so a password or a `noindex` header can't be added
 // there. This serves the adapter's own handler (static files, then Astro) behind the
-// gate (gate.mjs): robots.txt, the pre-launch password, then `X-Robots-Tag`.
+// gate (gate.mjs): robots.txt, the pre-launch password, `X-Robots-Tag`, a page beside a
+// folder of the same name, then Site Settings' redirects.
 //
 // It runs from the site's root (the directory with `dist/` and `content/`) and reads,
 // once at start:
 //   PORT (default 8080), HOST (default 0.0.0.0), the site's address (Astro's `site` from
 //   dist/server/caracms-build.json, else SITE_URL, else RAILWAY_PUBLIC_DOMAIN),
 //   CARACMS_PRELAUNCH (`user:password`), CARACMS_CLIENT_IP_HEADER (else the detected
-//   host's default; with neither, it exits with the fix), and content/site-settings.json → brand.name.
+//   host's default; with neither, it exits with the fix), and content/site-settings.json →
+//   brand.name and redirects.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { createGate, describeClientIpSource, markProcessGated, parsePrelaunch, parseSiteUrl, publicAddress, readBuildInfo, readClientIpSource } from './gate.mjs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createGate, describeClientIpSource, markProcessGated, parsePrelaunch, parseSiteUrl, publicAddress, readBuildInfo, readClientIpSource, readRedirects } from './gate.mjs';
 
 const USAGE = `Usage: caracms <command>, from the site's root
 
@@ -56,6 +58,20 @@ function readBrandName(root) {
 	}
 }
 
+/**
+ * The adapter's static files folder, as it finds it (@astrojs/node → resolveClientDir):
+ * the built server-to-client path from its options, applied to `dist/server` here.
+ * `dist/client` when the options don't say.
+ */
+function clientDirOf(options, root) {
+	const serverDir = join(root, 'dist/server');
+	try {
+		return resolve(serverDir, relative(fileURLToPath(new URL(options.server)), fileURLToPath(new URL(options.client))));
+	} catch {
+		return join(root, 'dist/client');
+	}
+}
+
 async function start() {
 	const root = process.cwd();
 	const entry = join(root, 'dist/server/entry.mjs');
@@ -87,7 +103,15 @@ async function start() {
 	const publicSite = publicAddress(process.env, readBuildInfo(root));
 	const siteUrl = publicSite?.value;
 	const prelaunch = process.env.CARACMS_PRELAUNCH;
-	const gate = createGate({ handler: built.handler, clientIpSource: ipSource.source, siteUrl, prelaunch, brandName: readBrandName(root) });
+	const gate = createGate({
+		handler: built.handler,
+		clientIpSource: ipSource.source,
+		siteUrl,
+		prelaunch,
+		brandName: readBrandName(root),
+		clientDir: clientDirOf(built.options, root),
+		redirects: readRedirects(root),
+	});
 
 	const server = createServer(gate);
 	server.on('error', (err) => fatal(err.message));

package/bin/gate.mjs

@@ -12,12 +12,17 @@
 //   2. The pre-launch password (`CARACMS_PRELAUNCH`), except for the editor and its
 //      API, `/_astro/…` and `/health`.
 //   3. `X-Robots-Tag` on the way out, kept whatever the adapter writes.
-//   4. The adapter's own handler (static files first, then Astro).
+//   4. A page beside a folder of the same name (`services/advisory.html` and
+//      `services/advisory/`) is asked for by its file: the adapter would look in the
+//      folder for an index.html and answer 404.
+//   5. Site Settings' redirects, on what would be a 404: a prerendered 404 page never
+//      reaches Astro's middleware (redirect-middleware.ts, which serves them in dev).
+//   6. The adapter's own handler (static files first, then Astro).
 
 import { createHash, timingSafeEqual } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 import { isIP } from 'node:net';
-import { join } from 'node:path';
+import { join, resolve, sep } from 'node:path';
 import { CLOUDFLARE_IPV4, CLOUDFLARE_IPV6 } from './cloudflare-ips.mjs';
 
 /** The header the gate owns. */
@@ -199,6 +204,88 @@ export function parseSiteUrl(value) {
 	return { host: url.host.toLowerCase(), origin: url.origin, indexable };
 }
 
+// ── Pages beside a folder, and redirects ────────────────────────────────────────
+
+const isFile = (path) => {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+};
+const isDirectory = (path) => {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * The file to serve for a page whose address is also a folder: with `build.format:
+ * 'file'`, `/services/advisory` is `services/advisory.html`, beside a `services/advisory/`
+ * folder of the pages under it. The adapter sees the folder, looks for its index.html
+ * and answers 404, so the gate asks for the `.html` itself. Null for anything else: a
+ * path the two views don't agree on, `/`, a trailing slash, a file extension, a folder
+ * with its own index.html, or no such file under `clientDir`.
+ */
+export function pageBesideFolder(clientDir, views) {
+	const path = views.full;
+	if (!clientDir || path === null || views.app !== path || path === '/' || path.endsWith('/')) return null;
+	if (/\.[^/]*$/.test(path.slice(path.lastIndexOf('/')))) return null;
+	const root = resolve(clientDir);
+	const folder = resolve(root, '.' + path);
+	if (!folder.startsWith(root + sep)) return null;
+	if (!isDirectory(folder) || isFile(join(folder, 'index.html')) || !isFile(folder + '.html')) return null;
+	return path + '.html';
+}
+
+/**
+ * Site Settings' redirects, as the package reads them (src/redirects.ts; kept in step by
+ * gate.test.ts): `/path` addresses without a trailing slash; an entry that isn't two of
+ * them, goes nowhere or repeats a `from` is dropped.
+ */
+export function redirectAddress(value) {
+	if (typeof value !== 'string') return null;
+	const v = value.trim();
+	if (!/^\/(?!\/)[^\s?#]*$/.test(v)) return null;
+	const trimmed = v.replace(/\/+$/, '');
+	return trimmed === '' ? '/' : trimmed;
+}
+
+export function parseRedirects(raw) {
+	if (!Array.isArray(raw)) return [];
+	const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+	const out = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+		const from = redirectAddress(entry.from);
+		const to = redirectAddress(entry.to);
+		if (!from || !to || same(from, to) || out.some((r) => same(r.from, from))) continue;
+		out.push({ from, to });
+	}
+	return out;
+}
+
+/** Where a request for `pathname` (as sent) goes, or null: matched decoded, without a trailing slash; letter case counts. */
+export function redirectFor(list, pathname) {
+	let path = pathname;
+	try {
+		path = decodeURI(pathname);
+	} catch {}
+	path = path.replace(/\/+$/, '') || '/';
+	return list.find((r) => r.from === path)?.to ?? null;
+}
+
+/** `content/site-settings.json` → `redirects` under `root`, read once at start (the file is the build's). Empty when it's missing or unreadable. */
+export function readRedirects(root) {
+	try {
+		return parseRedirects(JSON.parse(readFileSync(join(root, 'content/site-settings.json'), 'utf8'))?.redirects);
+	} catch {
+		return [];
+	}
+}
+
 // ── The visitor's IP (Decision 8) ───────────────────────────────────────────────
 
 /** The header the gate sets on every request; `clientIp()` (src/live/auth/request.ts) reads only this in production. */
@@ -406,9 +493,9 @@ const sha256 = (buf) => createHash('sha256').update(buf).digest();
  * The gate, as `(req, res) => void` around the adapter's `handler`.
  * @param {{ handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => unknown,
  *   clientIpSource: string, siteUrl?: string, prelaunch?: string, brandName?: string,
- *   log?: (line: string) => void }} options
+ *   clientDir?: string, redirects?: { from: string, to: string }[], log?: (line: string) => void }} options
  */
-export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandName, log = (line) => console.error(line) }) {
+export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandName, clientDir, redirects = [], log = (line) => console.error(line) }) {
 	if (!CLIENT_IP_SOURCES.includes(clientIpSource)) throw new Error(`createGate: clientIpSource must be one of ${CLIENT_IP_SOURCES.join(', ')}.`);
 	let warnedMissing = false;
 	const site = parseSiteUrl(siteUrl);
@@ -481,7 +568,24 @@ export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandN
 		const robots = guarded ? NOINDEX_NOFOLLOW : indexable ? null : NOINDEX;
 		if (robots) holdHeader(res, ROBOTS_HEADER, robots);
 
-		// 4. The adapter.
+		if (req.method === 'GET' || req.method === 'HEAD') {
+			// 4. A page beside a folder of the same name, by its file.
+			// (As sent, plus `.html`: the views are decoded, the request target mustn't be.)
+			const file = guarded ? null : pageBesideFolder(clientDir, views);
+			const raw = rawPathOf(req.url);
+			if (file && raw !== null) {
+				req.url = raw + '.html' + req.url.slice(raw.length);
+			} else if (!guarded && redirects.length) {
+				// 5. A redirect, only where the site answers 404: a real page always wins.
+				const to = raw === null ? null : redirectFor(redirects, raw);
+				if (to) {
+					const query = req.url.indexOf('?');
+					redirectOn404(res, to + (query === -1 ? '' : req.url.slice(query)));
+				}
+			}
+		}
+
+		// 6. The adapter.
 		try {
 			const result = handler(req, res);
 			if (result && typeof result.catch === 'function') result.catch((err) => fail(res, err));
@@ -492,6 +596,53 @@ export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandN
 	return gate;
 }
 
+/**
+ * Turns the response into a 301 to `location` if the handler answers 404, however it
+ * writes it (`writeHead`, or a status and an implicit head on the first write or end).
+ * The 404's own headers and body are dropped; the held robots header stays.
+ */
+function redirectOn404(res, location) {
+	const writeHead = res.writeHead.bind(res);
+	const write = res.write.bind(res);
+	const end = res.end.bind(res);
+	let redirected = false;
+	const redirect = () => {
+		redirected = true;
+		for (const name of res.getHeaderNames()) res.removeHeader(name);
+		writeHead(301, { Location: location, 'Cache-Control': 'no-cache', 'Content-Length': 0 });
+		end();
+	};
+	const callback = (args) => {
+		const cb = args.find((a) => typeof a === 'function');
+		if (cb) queueMicrotask(cb);
+	};
+	const is404 = () => !res.headersSent && res.statusCode === 404;
+	res.writeHead = (status, ...rest) => {
+		if (redirected) return res;
+		if (status === 404 && !res.headersSent) {
+			redirect();
+			return res;
+		}
+		return writeHead(status, ...rest);
+	};
+	res.write = (...args) => {
+		if (!redirected && is404()) redirect();
+		if (redirected) {
+			callback(args);
+			return true;
+		}
+		return write(...args);
+	};
+	res.end = (...args) => {
+		if (!redirected && is404()) redirect();
+		if (redirected) {
+			callback(args);
+			return res;
+		}
+		return end(...args);
+	};
+}
+
 function fail(res, err) {
 	console.error('caracms start: the request failed:', err);
 	if (!res.headersSent) {

package/bin/templates/catch-all.astro.txt

@@ -1,25 +1,26 @@
 ---
 /**
- * Every document in the Pages collection (content/pages/), nested ones included: the
- * file's path is the address. Written by `caracms init`. It serves documents only. The
+ * Every document with an address: the Pages collection (content/pages/, nested ones
+ * included: the file's path is the address), and every collection a page holds or that
+ * has a urlBase of its own. Written by `caracms init`. It serves documents only. The
  * site's other routes in src/pages/ keep serving their own pages, and their addresses are
  * reserved: a page is code or a document, never both.
  */
 import RenderDocument from 'caracms/components/RenderDocument.astro';
-import { listDocuments, readDocument } from 'caracms/content';
+import { addressedDocuments, readDocument } from 'caracms/content';
 import { site } from 'virtual:caracms/config';
 
 export const prerender = true;
 
 export async function getStaticPaths() {
 	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page,
-	// and nor has a hidden one (or one under it): visitors get the 404 page.
-	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
-	return entries.map((e) => ({ params: { path: e.path === 'index' ? undefined : e.path }, props: { path: e.path } }));
+	// and nor has a hidden one (or one under it, or held by it): visitors get the 404 page.
+	const documents = await addressedDocuments(site);
+	return documents.map((d) => ({ params: { path: d.url === '/' ? undefined : d.url.slice(1) }, props: { collection: d.collection, path: d.path } }));
 }
 
-const { path } = Astro.props;
-const { document } = await readDocument(site, 'pages', path);
+const { collection, path } = Astro.props;
+const { document } = await readDocument(site, collection, path);
 ---
 
-<RenderDocument document={document} collection="pages" />
+<RenderDocument document={document} collection={collection} />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/skills/caracms-adopt/SKILL.md

@@ -63,8 +63,9 @@ unapproved, and don't approve it in passing (`pnpm approve` also reviews build s
 - `caracms.config.ts`: a `pages` collection at `/` (nested), one `text` block, no text
   styles;
 - `src/components/caracms/Page.astro` (the page component) and `TextBlock.astro`;
-- `src/pages/[...path].astro`, which serves the documents in `content/pages/` and nothing
-  else, and `src/pages/health.ts`;
+- `src/pages/[...path].astro`, the one catch-all, which serves every document with an
+  address (the pages today; a collection added later needs no route of its own, section
+  6) through `addressedDocuments` from `caracms/content`, and `src/pages/health.ts`;
 - `content/site-settings.json` (its `brand.name` is the package name title-cased: correct
   it), and `schemas/`;
 - `astro.config` edits: the Node adapter (standalone), `integrations: [caracms(site)]`,
@@ -304,7 +305,7 @@ something in the site reads the marker, keep it as a `toggle()` field on the col
 otherwise drop it. Either way, say so in the pull request.
 
 **Code routes.** Every route in `src/pages/` other than caracms's `[...path].astro` (and a
-collection's own route, below) is the site's code, and its address is reserved: a static
+prefix collection's own route, section 6) is the site's code, and its address is reserved: a static
 route (`contact.astro`) reserves exactly `/contact`; a route with parameters
 (`work/[slug].astro`) reserves everything under `/work/`. The editor refuses a page there
 ("… is served by the site's own code (…), so a page can't go there."), and `validate`
@@ -353,7 +354,23 @@ go only when nothing in the code still uses them.
 The site's Astro content collections (`src/content.config.ts`) become caracms collections
 when editors should change them:
 
-- A collection with pages of its own: `kind: 'fields'` with a `urlBase`, and its route.
+- **Pick the address source for each**, one of three:
+
+  | Source | In the config | In the content | A document's address |
+  |---|---|---|---|
+  | **Pageless** | no `urlBase` | none | none (a team, an FAQ, logos) |
+  | **A prefix in code** | `urlBase: '/tags/'` | none | `urlBase` + slug, with no page at the prefix |
+  | **Held by a page** | `heldBy: 'pages'` | the page's file says `"holds": "journal"` | the page's address + `/` + slug |
+
+  A collection whose old site had a page at its base (a Journal page and the posts under
+  it, a Work page and its case studies) is **held** by that page: `heldBy: 'pages'` in
+  place of `urlBase`, and `"holds": "<collection>"` in the page's file, after `title`.
+  Its documents are served from the page's address and follow the page if it moves. A
+  prefix with no page at it (tags) keeps `urlBase`. Neither needs a route:
+  `[...path].astro` serves them through `addressedDocuments` (`documentAt` for a site
+  that renders on demand). Delete the old collection's `[slug].astro`; one left at a
+  held collection's address is a `validate` error. A prefix collection's route file you
+  keep is the site's own, and the reader leaves that collection out.
 - A collection only other pages show (a team, an FAQ, logos): `kind: 'fields'` with **no
   `urlBase`** and a `component` (the editor's preview of one document). A block shows them
   with `cms.read.documents('<name>')`, which orders them **by title**: keep the old order

package/skills/caracms-blocks/SKILL.md

@@ -148,15 +148,32 @@ const { block, cms } = Astro.props;
 
 ## Collections
 
+A collection with pages gets its address from exactly one of three places:
+
+| Source | In the config | In the content | A document's address |
+|---|---|---|---|
+| **Pageless** | no `urlBase` | none | none (a team, an FAQ): other pages show them |
+| **A prefix in code** | `urlBase: '/tags/'` | none | `urlBase` + slug, with no page at the prefix |
+| **Held by a page** | `heldBy: 'pages'` | the page's file says `"holds": "journal"` | the page's address + `/` + slug; move the page and they follow |
+
 ```ts
-// A collection with pages of its own, at /work/<slug>
-work: { kind: 'fields', folder: 'content/work', urlBase: '/work/', component: 'src/components/caracms/CaseStudy.astro', fields: { … } },
-// A collection with no pages (a team, an FAQ): leave out urlBase
+// Held by a page: the Work page's file says "holds": "work", so a case study is at /work/<slug>
+work: { kind: 'fields', folder: 'content/work', heldBy: 'pages', component: 'src/components/caracms/CaseStudy.astro', fields: { … } },
+// A second section builder, held by the Journal page ("holds": "journal"): posts at /journal/<slug>
+journal: { kind: 'sections', folder: 'content/journal', heldBy: 'pages', fields: { date: date() }, blocks: ['text', 'image'] },
+// A prefix in code, with no Tags page: /tags/<slug>
+tags: { kind: 'sections', folder: 'content/tags', urlBase: '/tags/' },
+// A collection with no pages (a team, an FAQ): leave out urlBase and heldBy
 people: { kind: 'fields', folder: 'content/people', component: 'src/components/caracms/Person.astro', fields: { role: text(), photo: media({ only: 'image' }) } },
-// A second section builder (a journal)
-journal: { kind: 'sections', folder: 'content/journal', urlBase: '/journal/', fields: { date: date() }, blocks: ['text', 'image'] },
 ```
 
+- **`heldBy` names the nested section builder whose page holds the collection** (`'pages'`),
+  and is exclusive with `urlBase`. The held collection is flat (not `nested`), either
+  kind. The mount is in the content, not here: one page of `pages` says
+  `"holds": "journal"` (a document key after `title` and `hidden`; the editor shows it
+  on the page and doesn't change it), one collection per page and one page per
+  collection, never Home. Until a page holds it the collection has no addresses; `caracms validate` errors
+  on a collection no page holds, two pages holding one, and a `holds` anywhere else.
 - A `fields` collection's `component` renders one document: it gets
   `{ document, cms }` (`FieldsDocumentProps` from `caracms/document`), with
   `document.title` and each field's value; draw fields with `field="<key>"`. The page
@@ -172,14 +189,20 @@ journal: { kind: 'sections', folder: 'content/journal', urlBase: '/journal/', fi
   gets them), **ordered by title**. For another order, give the documents a `number()`
   field and sort in the component, or let a page pick and order them with
   `list(reference({ to: 'people' }))`. `cms.read.document('people', path)` reads one.
-- The collection's route: a collection with a `urlBase` needs a route in `src/pages/` whose
-  static part is that `urlBase` (`src/pages/work/[slug].astro`, rendering with
-  `RenderDocument` from `caracms/components/RenderDocument.astro` and `listDocuments` /
-  `readDocument` from `caracms/content`, as `src/pages/[...path].astro` does for pages).
-  Its `getStaticPaths` leaves out entries with a `warning` (a file that can't be opened) and
-  `hidden` ones (a page hidden from the site, or one under it): those answer the 404 page.
-  Every other route in `src/pages/` is the site's own code, and its address can't hold a
-  document.
+- **Routes: one catch-all serves every document with an address.** `src/pages/[...path].astro`
+  (`caracms init` writes it) builds from `addressedDocuments(site)` in `caracms/content`,
+  which lists `{ collection, path, url }` for every public page of Pages, every held
+  collection and every prefix collection, and renders with `RenderDocument` from
+  `caracms/components/RenderDocument.astro` and `readDocument`. A site that renders on
+  demand asks `documentAt(site, pathname)` for the document at a request path (or
+  `null`). Both leave out entries with a `warning` (a file that can't be opened) and
+  `hidden` ones (a page hidden from the site, one under it, and the documents of a hidden
+  holder): those answer the 404 page. **Don't write a route per collection.** A collection
+  doesn't need `src/pages/work/[slug].astro`, and one left at a held collection's address
+  is a `validate` error. A prefix collection that keeps its own route file
+  (`src/pages/tags/[slug].astro`) is left out of the reader, so the page is never built
+  twice. Every other route in `src/pages/` is the site's own code, and its address can't
+  hold a document.
 - Shared blocks (`content/shared/`) and Site Settings are built in; no config.
 
 ## Site Settings fields

package/skills/caracms-content/SKILL.md

@@ -23,10 +23,20 @@ a file that's laid out otherwise, and `validate --fix` rewrites it the editor's
     `content/pages/about.json` is `/about`, `content/pages/services/print.json` is
     `/services/print`, and `content/pages/index.json` is Home. An `index.json` anywhere
     deeper is an error: `/services` itself is `content/pages/services.json`.
-  - `kind: 'fields'`: each document is a title plus the collection's `fields`. With a
-    `urlBase` (`/work/`), `content/<folder>/<slug>.json` is `/work/<slug>`. With no
-    `urlBase` the documents have no page of their own (a team, an FAQ); other pages show
-    them.
+  - `kind: 'fields'`: each document is a title plus the collection's `fields`.
+  - **A collection with pages gets its address from one of three places:**
+
+    | Source | In the config | In the content | A document's address |
+    |---|---|---|---|
+    | Pageless | no `urlBase` | none | none: a team, an FAQ; other pages show them |
+    | A prefix in code | `urlBase: '/tags/'` | none | `urlBase` + slug: `content/tags/news.json` is `/tags/news` |
+    | Held by a page | `heldBy: 'pages'` | the page's file says `"holds": "journal"` | the page's address + `/` + slug: with `content/pages/journal.json` holding it, `content/journal/a-day.json` is `/journal/a-day` |
+
+    A held collection's posts follow their page: move the page to `/blog` and they are at
+    `/blog/<slug>`. Only the config's `heldBy` and the page's `"holds"` say so, and
+    they must agree (`validate` errors when they don't). One catch-all route
+    (`src/pages/[...path].astro`) serves all three through `addressedDocuments` from
+    `caracms/content`; a collection needs no route of its own.
 - **Shared blocks** (one block used on several pages): `content/shared/<name>.json`
   (or the config's `sharedFolder`).
 - **Site Settings**: `content/site-settings.json`, one file.
@@ -65,6 +75,10 @@ A page (`sections`):
 - `{ "shared": "<name>" }` places the shared block `content/shared/<name>.json` there.
 - If the collection has `fields` of its own (page fields), they're top-level keys after
   `title` and before `blocks`.
+- A page that holds a collection says so with `"holds": "<collection key>"`, after `title`
+  (and `hidden`) and before the page fields, `seo` and `blocks`. Only a page of the
+  collection the held collection's `heldBy` names can hold one, never Home, one page per
+  collection and one collection per page. Don't put it anywhere else.
 - An optional `"seo": { "title", "description", "image" }` sets the page's search and
   share text; leave it out to use Site Settings' defaults.
 
@@ -152,8 +166,15 @@ rename or delete the file, fix every `href` and `reference` that pointed at it (
 `content/` for the old address and path), and for a page that was public add
 `{ "from": "/old-address", "to": "/new-address" }` to Site Settings' `redirects`.
 
-A page can't go at an address the site's own code serves (a route in `src/pages/`), or at
-`/admin`, `/_caracms` or `/files`.
+**A page that holds a collection takes its documents with it**, and so does every page
+under it: in the editor, Change address… moves them all and adds a redirect for each old
+address. By hand, the held documents' files don't move (their address is the page's plus
+the slug), but every `href` to each of them changes and each old address that was public
+needs its own `redirects` entry. A holder can't be deleted while it holds: take its
+`"holds"` line out first, or move the documents to another page.
+
+A page can't go at an address the site's own code serves (a route in `src/pages/`), at
+a held document's address (`/journal/a-day`), or at `/admin`, `/_caracms` or `/files`.
 
 ## Choosing blocks for a page