caracms 0.3.3 → 0.4.0

package/skills/caracms-tina/SKILL.md

@@ -92,7 +92,8 @@ Copy `node_modules/caracms/skills/caracms-tina/tina-to-caracms.mjs` into the sit
 the approved `blockRenames`, `fieldDefaults` (values Tina's files leave out but the
 template's mapper code read as set: a toggle that defaulted on, a per-block background
 default that isn't the first option), `addressFields`, `headingFields`, `docTitleAlt`,
-the file-link pattern, and Tina's home file. **`addressFields` matters:** Tina's schema has
+the file-link pattern, Tina's home file and `holders` (which page holds which collection;
+the only source of holding, so an empty table holds nothing). **`addressFields` matters:** Tina's schema has
 no marker for a link field (a custom component serialises to `ui: {}`), so only strings
 named `href` are known to be addresses; list every other one. Everything below the table is generic and
 driven by Tina's generated schema; never add per-block code. If a block needs something
@@ -116,7 +117,11 @@ node scripts/tina-to-caracms.mjs --from ../share-web-main --scaffold-config
 - `--scaffold-config` writes a starting `caracms.config.ts` from Tina's schema, with
   Tina's labels and help. **Once.** After that the config and the block components are
   the site's own, hand-maintained, and a normal run never touches them (section 4 says
-  which options only you can add).
+  which options only you can add). A collection the adapt table's `holders` names
+  (`games: 'games'`) is **held by that page**: the scaffold writes `heldBy: 'pages'` and
+  no `urlBase`, and every run writes `"holds": "games"` on the page (section 6). A
+  collection not in the table keeps `urlBase`. The script prints a hint for each sections
+  collection that has a same-named page but isn't in the table, saying what to add.
 - `--recipients <address>` replaces every form's recipients in Site Settings with one
   address. **Always pass it for a branch environment**: the converted Site Settings name
   the client, and a test submission would email them. The run at the switch leaves it out.
@@ -140,7 +145,8 @@ caracms's (Tina's escapes such as `A\&M` and `mailto\:` undone), an image and it
 sibling → one media value, a Mux clip → a video value, `linkLabel` + `href` → one
 `link()`, references → document paths, Site Settings (`formNotifications` →
 `formRecipients`, `adminBranding` → `brand`, `adminAccess` → `editors`, `defaultSeo` →
-`seo`), file links → caracms file addresses, and Tina's `hidden` → `"hidden": true`
+`seo`), file links → caracms file addresses, Tina's `hidden` → `"hidden": true`
+(section 6), and the page that sits at a collection's base → `"holds": "<collection>"`
 (section 6).
 
 ## 3. Tina's pieces and what replaces each
@@ -150,7 +156,7 @@ sibling → one media value, a Mux clip → a video value, `linkLabel` + `href`
 | `tina/`, `tina/__generated__/`, Tina's dependencies | yes | `caracms.config.ts` |
 | `public/admin/`, `public/admin-previews/` | yes | `/admin` (caracms's editor) |
 | `server.mjs`, `server/` (Express: forms, downloads, the admin, previews) | yes | `caracms start`; forms → `/_caracms/form` (section 8); downloads → caracms file addresses `/files/<12 hex>/<name>` |
-| `src/pages/[...slug].astro` and other collection routes reading Tina | yes | caracms routes (section 6) |
+| `src/pages/[...slug].astro` and the collection routes reading Tina (`blog/[slug].astro`) | yes | the one catch-all (section 6) |
 | `src/lib/sections.ts` (the mappers: Tina document → component props) | yes, except page-wide logic | blocks draw from their own data; page-wide rules → the page component (section 5) |
 | `Sections.astro` / `PageView` | yes | the page component and `<Blocks>` |
 | `data-tina-field` on every element | yes | caracms's markers, added by `Block`, `Text`, `RichText`, `Media` in a preview only |
@@ -301,17 +307,53 @@ block, when the template put it there: section links jump to those ids.
 
 ## 6. Routes, hidden pages and the 404
 
-`init` writes the pages' catch-all (`src/pages/[...path].astro`) once Tina's
-`[...slug].astro` is gone (it refuses while another route catches the top of the site).
-Write one route per other collection with an address (`src/pages/games/[slug].astro`) the
-same way: `listDocuments` + `readDocument` + `RenderDocument`. Every `getStaticPaths`
-leaves out **`e.warning`** (a file that can't be opened) and **`e.hidden`** (a hidden page,
-or one under it):
+A collection with pages gets its address from one of three places, and the port picks
+one per collection:
+
+| Source | In the config | In the content | A document's address | In the template |
+|---|---|---|---|---|
+| **Pageless** | no `urlBase` | none | none | a team, awards, logos: other pages list them |
+| **A prefix in code** | `urlBase: '/tags/'` | none | `urlBase` + slug | `/tags/<slug>`, with no Tags page |
+| **Held by a page** | `heldBy: 'pages'` | the page says `"holds": "posts"` | the page's address + `/` + slug | the Blog page and its posts: `/blog/<slug>` |
+
+**Don't write a route per collection.** A template's Blog page **holds** its posts
+collection: the posts are at the page's address, so they follow the page wherever it
+moves. A prefix with no page (tags) keeps `urlBase`. `init` writes one catch-all
+(`src/pages/[...path].astro`, once Tina's `[...slug].astro` is gone: it refuses while
+another route catches the top of the site), and it serves pages, held documents and
+prefix documents alike, through the reader from `caracms/content`:
 
 ```ts
-const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
+import { addressedDocuments } from 'caracms/content';
+
+export async function getStaticPaths() {
+	const documents = await addressedDocuments(site); // { collection, path, url }[]
+	return documents.map((d) => ({ params: { path: d.url === '/' ? undefined : d.url.slice(1) }, props: { collection: d.collection, path: d.path } }));
+}
 ```
 
+The reader already leaves out **`e.warning`** (a file that can't be opened) and
+**`e.hidden`** (a hidden page, one under it, and the documents of a hidden holder). A
+site that renders on demand asks `documentAt(site, pathname)` instead: the document at a
+request path, or `null`.
+
+**The script holds only what the adapt table says.** `holders: { games: 'games' }` (or
+`posts: 'blog'` where the folder isn't named like the page) makes `/games/` the page's
+address and the collection's; with no entry nothing is held, so a site ported before this
+keeps its `urlBase`. For each sections collection that has a same-named page and no entry,
+the script prints a hint with the line to add (then re-run with `--scaffold-config
+--force`); a fields collection is never suggested. Home never
+holds a collection, one page holds one collection, and a held collection is flat;
+`validate` says when any of that is wrong. A `holds` added to a page by hand is
+lost on the next run (`content/` is written whole), so the table is where it belongs.
+
+**Delete the template's collection routes.** A route with parameters left at a held base
+(`src/pages/blog/[slug].astro`) is a `validate` error: the catch-all serves those
+documents. A route at a prefix collection's base (`src/pages/tags/[slug].astro`) is the
+site's own for that collection, and the reader leaves the collection out, so keep it only
+for a page the catch-all can't draw (a listing built from logic); otherwise delete it
+and let the catch-all serve the prefix too.
+
 **Hidden pages:** Tina's `hidden` becomes `"hidden": true` at the top of the document,
 after its title. A hidden page isn't served (visitors get the site's own `404.astro`),
 isn't in the sitemap, isn't offered by the link picker, and isn't in a block's

package/skills/caracms-tina/field-kinds.md

@@ -52,6 +52,7 @@ Inline, `**bold**`, `*italic*` and `[text](href)` carry over (Tina's `__bold__`
 - **Block types** take the adapt table's `blockRenames`, and otherwise go from camelCase to kebab case (`textMedia` → `text-media`).
 - `seo { metaTitle, metaDescription, ogImage, ogImageAlt }` → caracms's `seo { title, description, image }`.
 - **Hidden:** a section builder's boolean `hidden` → `"hidden": true` at the top level of the document, beside `title` and `blocks` (absent means shown). The home page can't be hidden: it's left shown, with a warning.
+- **Holds:** the page the adapt table's `holders` names for a collection (`games: 'games'`, `posts: 'blog'`; the table is the only source, with no default from names) gets `"holds": "<collection>"` after `title` and `hidden`, and the scaffolded config gives that collection `heldBy: 'pages'` in place of `urlBase`. The home page never holds one. A table entry whose page doesn't exist is a warning. For each sections collection with a same-named page that isn't in the table, the script prints a hint line saying what to add (a fields collection is never suggested).
 - Every file starts with its `$schema` (`../../schemas/<collection>.schema.json`), as `caracms schemas` stamps it.
 - A key in a Tina file that its schema no longer has is left out, with a warning.
 
@@ -86,3 +87,4 @@ At the top of the script, under "ADAPT HERE". Everything else is generic.
 | `docTitleAlt` | bare images whose alt is the document's title (a client's logo) |
 | `fileLinks` | the Tina site's own file route and the bucket key behind it |
 | `homeFile` | Tina's home page file |
+| `holders` | a collection key → the page file that holds it (`games: 'games'`, `posts: 'blog'`); the only source of holding, so a collection not listed keeps its `urlBase` |

package/skills/caracms-tina/tina-to-caracms.mjs

@@ -19,6 +19,12 @@
  *   Tina's labels and help, over `caracms init`'s starting config. It refuses any other
  *   existing config unless `--force`. Do it once: after that the config and the block
  *   components are the site's own, hand-maintained, and a normal run never touches them.
+ *   A collection whose template has a page at its base (`pages/games.json` for a `games`
+ *   collection) is held by that page only if the adapt table `SITE.holders` says so
+ *   (`games: 'games'`): then the scaffold writes `heldBy: 'pages'` in place of `urlBase`,
+ *   and every run writes `"holds": "games"` on the page. Not in the table: the collection
+ *   keeps `urlBase: '/games/'` (a prefix in code), and the script only prints a hint line
+ *   for each sections collection that has a same-named page, saying what to add.
  *
  * WHAT IT OWNS: `content/`, nothing else. Each run deletes `content/` and writes it again
  * from Tina's files, so the same input gives byte-identical output, and a run on newer
@@ -54,6 +60,7 @@ import { pathToFileURL } from 'node:url';
  * @property {string[]} docTitleAlt
  * @property {{ pattern: RegExp, sourceKey: (name: string) => string }} fileLinks
  * @property {string} homeFile
+ * @property {Record<string, string>} holders
  */
 
 /** @type {SiteTable} */
@@ -87,6 +94,17 @@ export const SITE = {
 	fileLinks: { pattern: /^\/files\/([^/?#]+)$/, sourceKey: (name) => `uploads/${name}` },
 	/** Tina's home page file (it becomes `index`). */
 	homeFile: 'home',
+	/**
+	 * The collections held by a page (collection key → page file name, without `.json`):
+	 * this table is the only source, with no default from names (`games: 'games'`,
+	 * `posts: 'blog'`). The scaffold's `heldBy` and every run's `"holds"` both come from it, so
+	 * a site ported without an entry is never given a `holds` its config doesn't expect.
+	 * The script suggests candidates: a sections collection with a same-named page that isn't
+	 * listed here is printed as a line saying what to add.
+	 */
+	holders: {
+		// posts: 'blog',
+	},
 };
 
 // ── The template's conventions (the same in every site made from it) ────────────────────
@@ -516,6 +534,7 @@ export function layout(value, shape, depth = 0) {
  * or fields) with its compiled fields, the blocks by caracms key, and Site Settings.
  */
 export function readSchema(schema, site = SITE) {
+	/** @type {Record<string, any>} */
 	const collections = {};
 	const blocks = new Map(); // key → { template, label, specs }
 	const warnings = [];
@@ -554,7 +573,9 @@ export function readSchema(schema, site = SITE) {
 	}
 	const settings = schema.collections.find((c) => c.name === SETTINGS);
 	const settingsSpecs = settings ? compileFields(settings.fields.filter((f) => !OWN_SETTINGS.has(f.name)), SETTINGS, site) : [];
-	return { collections, blocks, settings, settingsSpecs, warnings };
+	/** @type {string[]} Hint lines `findHolders` fills in. */
+	const holderCandidates = [];
+	return { collections, blocks, settings, settingsSpecs, warnings, holderCandidates };
 }
 /** A Tina template's own description (`ui.description`, or `description`), or ''. */
 const templateDescription = (t) => String(t.ui?.description ?? t.description ?? '').trim();
@@ -618,12 +639,53 @@ const seoOf = (raw, conv, where) => {
 };
 const SEO_SHAPE = { kind: 'object', keys: new Map([['image', INLINE]]) };
 
+/**
+ * The collections held by a page (collections under pages). The source is the adapt table
+ * `SITE.holders` (collection key → page file name) and nothing else: a collection the table
+ * names, whose page exists in the pages folder, is held by that page. The scaffold writes
+ * `heldBy: 'pages'` (and no `urlBase`) for it, and the conversion writes `"holds": "<key>"`
+ * on the page, both from this one decision. A collection the table doesn't name is a prefix
+ * in code and keeps its `urlBase` (so a site ported before this change, with an empty table,
+ * comes out the same). Sets `holder` (the page's file name) on each collection it finds;
+ * Home never holds one. A table entry naming a page that doesn't exist is a warning in
+ * `read.warnings`. `read.holderCandidates` lists the *sections* collections that aren't in
+ * the table but have a same-named page, as hint lines (a fields collection is never
+ * suggested). Returns the page name → collection key map.
+ */
+export function findHolders(read, from, site = SITE) {
+	const holders = new Map();
+	read.holderCandidates.length = 0;
+	const pages = Object.values(read.collections).find((c) => c.key === 'pages' && c.sections);
+	if (!pages) return holders;
+	const names = new Set(jsonFiles(path.join(from, pages.tina.path)).map((f) => f.replace(/\.json$/, '')));
+	for (const c of Object.values(read.collections)) {
+		if (c === pages || c.key === 'pages') continue;
+		const page = site.holders?.[c.key];
+		if (page === undefined) {
+			if (c.sections && names.has(c.key) && c.key !== site.homeFile && c.key !== 'index') {
+				read.holderCandidates.push(`${c.key} has a page at ${pages.tina.path}/${c.key}.json: to have that page hold it, add ${c.key}: '${c.key}' to SITE.holders, then re-run with --scaffold-config --force`);
+			}
+			continue;
+		}
+		if (!names.has(page)) {
+			read.warnings.push(`SITE.holders: ${c.key} is held by the page "${page}", but there's no ${pages.tina.path}/${page}.json, so it isn't held`);
+			continue;
+		}
+		if (page === site.homeFile || page === 'index' || holders.has(page)) continue;
+		c.holder = page;
+		holders.set(page, c.key);
+	}
+	return holders;
+}
+
 /**
  * Convert every document. Returns `{ files: Map<relPath, text>, conv }`; nothing is written.
  * `recipients`: the `--recipients` address, or undefined.
+ * @param {{ from: string, schema: any, slugify: any, site?: SiteTable, recipients?: string }} args
  */
 export function convertAll({ from, schema, slugify, site = SITE, recipients }) {
 	const read = readSchema(schema, site);
+	const holders = findHolders(read, from, site);
 	const conv = converter({ collections: read.collections, slugify, site });
 	conv.warnings.push(...read.warnings);
 	const docs = []; // { rel, data, shape }
@@ -643,6 +705,8 @@ export function convertAll({ from, schema, slugify, site = SITE, recipients }) {
 				if (name === 'index') conv.warn(where, "the home page can't be hidden in caracms, so it's shown");
 				else data.hidden = true;
 			}
+			// The page that holds a collection says so, after its title and hidden (the editor's order).
+			if (c.key === 'pages' && holders.has(name)) data.holds = holders.get(name);
 			const own = Object.fromEntries(Object.entries(raw).filter(([k]) => ![c.titleField, c.blocksField, ...(c.hasSeo ? ['seo'] : []), ...(c.hasHidden ? ['hidden'] : [])].includes(k)));
 			Object.assign(data, conv.object(c.specs, own, where, doc));
 			if (c.sections) {
@@ -867,12 +931,13 @@ export function scaffoldConfig(read) {
 	const cols = Object.values(read.collections).map((c) => {
 		const parts = [`label: ${q(c.label)}`];
 		if (c.sections) {
-			parts.push(`kind: 'sections'`, `folder: ${q(`content/${c.key}`)}`, `urlBase: ${q(c.key === 'pages' ? '/' : `/${c.key}/`)}`);
+			// A page at the collection's base holds it (heldBy); with no page the prefix stays in code (urlBase).
+			parts.push(`kind: 'sections'`, `folder: ${q(`content/${c.key}`)}`, c.holder ? `heldBy: 'pages'` : `urlBase: ${q(c.key === 'pages' ? '/' : `/${c.key}/`)}`);
 			if (c.key === 'pages') parts.push('nested: true');
 			if (c.blockKeys.length !== allBlocks.length) parts.push(`blocks: ${q(c.blockKeys)}`);
 			if (c.specs.length) parts.push(`fields: ${fieldsConfig(c.specs, read, used, '\t\t\t')}`);
 		} else {
-			parts.push(`kind: 'fields'`, `folder: ${q(`content/${c.key}`)}`, `component: ${q(`src/components/caracms/${pascal(c.key)}.astro`)}`, `fields: ${fieldsConfig(c.specs, read, used, '\t\t\t')}`);
+			parts.push(`kind: 'fields'`, `folder: ${q(`content/${c.key}`)}`, ...(c.holder ? [`heldBy: 'pages'`] : []), `component: ${q(`src/components/caracms/${pascal(c.key)}.astro`)}`, `fields: ${fieldsConfig(c.specs, read, used, '\t\t\t')}`);
 		}
 		return `\t\t${/^[a-z][a-z0-9]*$/.test(c.key) ? c.key : q(c.key)}: {\n\t\t\t${parts.join(',\n\t\t\t')},\n\t\t},`;
 	});
@@ -993,6 +1058,9 @@ async function main() {
 			for (const f of [...conv.files.values()].sort((a, b) => a.key.localeCompare(b.key))) console.log(`  ${f.sourceKey} → ${f.key}`);
 		}
 	}
+	const held = Object.values(read.collections).filter((c) => c.holder);
+	if (held.length) console.log(`Held by a page: ${held.map((c) => `${c.key} (the ${c.holder} page says "holds": "${c.key}")`).join(', ')}.`);
+	for (const line of read.holderCandidates ?? []) console.log(`Hint: ${line}.`);
 	if (args.recipients) console.log(`Form recipients: every form's are ${args.recipients} (--recipients).`);
 	if (conv.warnings.length) console.log(`Warnings:\n  ${conv.warnings.join('\n  ')}`);
 	return 0;

package/src/cli/validate.ts

@@ -24,7 +24,8 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ResolvedCollection, ResolvedSite } from '../config.ts';
-import { codeRouteAt, codeRouteMessage, shadowingMessage, shadowingRoutes, type CodeRoute } from '../code-routes.ts';
+import { codeRouteAt, codeRouteMessage, leftBehindMessage, leftBehindRoutes, shadowingMessage, shadowingRoutes, type CodeRoute } from '../code-routes.ts';
+import { heldBases } from '../held.ts';
 import { pagesRoutes, readCodeRoutes, srcDirOf } from '../code-routes-disk.ts';
 import { listDocuments, type DocumentEntry } from '../content.ts';
 import { own } from '../document.ts';
@@ -308,9 +309,10 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 	if (raw.title !== undefined && typeof raw.title !== 'string') error(c, 'title', `Expected text (a string), found ${what(raw.title)}.`);
 	switch (collection.kind) {
 		case 'sections': {
-			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', 'blocks', 'seo']);
+			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', 'holds', 'blocks', 'seo']);
 			// M9 Decision 7.
 			if (raw.hidden !== undefined && raw.hidden !== true) error(c, 'hidden', `Expected true (hidden from the site) or no "hidden" at all, found ${what(raw.hidden)}.`);
+			if (raw.holds !== undefined) checkHolds(c, collection, raw.holds);
 			if (!Object.hasOwn(raw, 'blocks')) error(c, 'blocks', 'This page has no "blocks". Every page has a list of blocks, even an empty one ([]).');
 			else if (!Array.isArray(raw.blocks)) error(c, 'blocks', `Expected a list of blocks, found ${what(raw.blocks)}.`);
 			else raw.blocks.forEach((b, i) => checkBlock(c, b, at('blocks', i), collection));
@@ -318,16 +320,19 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 			return;
 		}
 		case 'fields':
-			checkFields(c, own, raw, '', `a ${collection.label} document`, 0, [SCHEMA_KEY, 'title', 'seo']);
+			checkFields(c, own, raw, '', `a ${collection.label} document`, 0, [SCHEMA_KEY, 'title', 'seo', 'holds']);
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			checkSeo(c, raw.seo, 'seo');
 			return;
 		case 'shared':
-			unknownKeys(c, raw, [SCHEMA_KEY, 'title', 'block'], '', 'a shared block');
+			unknownKeys(c, raw, [SCHEMA_KEY, 'title', 'block', 'holds'], '', 'a shared block');
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			if (!Object.hasOwn(raw, 'block')) error(c, 'block', 'This shared block has no "block".');
 			else checkBlock(c, raw.block, 'block', null);
 			return;
 		case 'settings': {
-			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects']);
+			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects', 'holds']);
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			if (raw.editors !== undefined && !strings(raw.editors)) error(c, 'editors', `Expected a list of email addresses, found ${what(raw.editors)}.`);
 			if (raw.brand !== undefined) {
 				if (!isObject(raw.brand)) error(c, 'brand', `Expected { "name", "accent", "logo", "icon" }, found ${what(raw.brand)}.`);
@@ -354,6 +359,23 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 	}
 }
 
+/** Collections under pages (Decision 13): `"holds"` on anything but a page. */
+const HOLDS_ON_A_PAGE = '"holds" is for a page: it says which collection\'s documents sit under the page\'s address. Only a page of the collection that collection\'s heldBy names can hold one. Take it out.';
+
+/**
+ * Decision 13: a page's `"holds"` names a collection whose `heldBy` is this page's collection.
+ * Home holding one, and two pages holding one, are the collection's problems (held.ts), reported on their files by validateSite.
+ */
+function checkHolds(c: Context, collection: ResolvedCollection, holds: unknown) {
+	if (typeof holds !== 'string') return error(c, 'holds', `Expected a collection's key (text), like "journal", found ${what(holds)}.`);
+	const held = own(c.site.collections, holds);
+	if (!held || !held.heldBy) {
+		const heldOnes = Object.values(c.site.collections).filter((h) => h.heldBy === collection.name).map((h) => `"${h.name}"`);
+		return error(c, 'holds', `"holds" names "${holds}", which isn't a collection a page holds${heldOnes.length ? ` (a ${collection.label} page can hold ${heldOnes.join(' or ')})` : ''}. A collection is held when its config says heldBy: '${collection.name}'.`);
+	}
+	if (held.heldBy !== collection.name) error(c, 'holds', `${held.label} is held by a page of ${c.site.collections[held.heldBy]?.label ?? held.heldBy} (its heldBy), not of ${collection.label}. Move "holds" to a page there.`);
+}
+
 /** Every finding for the site's content. `codeRoutes`: the site's own (default: read from its src/pages). */
 export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[] = readCodeRoutes(site.root, srcDirOf(site.root), Object.values(site.collections))): Promise<Report> {
 	const report: Report = { errors: [], warnings: [] };
@@ -373,10 +395,25 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 	}
 
 	// A second route with parameters at a collection's base hides its documents (code-routes.ts → one per base).
-	for (const s of shadowingRoutes(pagesRoutes(site.root, srcDirOf(site.root)), Object.values(site.collections))) {
+	const routes = pagesRoutes(site.root, srcDirOf(site.root));
+	for (const s of shadowingRoutes(routes, Object.values(site.collections))) {
 		report.errors.push({ file: s.route.file, path: '', message: shadowingMessage(s) });
 	}
 
+	// Collections under pages (Decision 13): a held collection with no addresses, its sentence on each file it names.
+	const bases = heldBases(site.collections, entries);
+	const held: { name: string; label: string; base: string; holder: string }[] = [];
+	for (const base of Object.values(bases)) {
+		const collection = site.collections[base.collection]!;
+		if (base.base && base.holder) held.push({ name: collection.name, label: collection.label, base: base.base, holder: base.holder.label });
+		if (!base.problem) continue;
+		const holders = entries.filter((e) => e.collection === collection.heldBy && e.holds === collection.name).map((e) => e.file);
+		for (const file of holders.length ? holders : [collection.folder]) report.errors.push({ file, path: holders.length ? 'holds' : '', message: base.problem });
+	}
+	// Decision 14: a route left at a held base serves those addresses ahead of the catch-all.
+	const leftBehind = leftBehindRoutes(routes, held);
+	for (const left of leftBehind) report.errors.push({ file: left.route.file, path: '', message: leftBehindMessage(left) });
+
 	const urls = new Map<string, DocumentEntry>();
 	for (const entry of entries) {
 		const c: Context = { file: entry.file, site, report, warningContext, exists };
@@ -399,13 +436,17 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 		if (isObject(raw) && raw[SCHEMA_KEY] === undefined) warning(c, '', `This file has no "$schema" (${JSON.stringify(schemaRef(collection, entry.file))}). \`caracms validate --fix\` adds it.`);
 		const saved = savedForm(text, collection, site);
 		if (saved !== null && saved !== text) warning(c, '', REFORMAT_MESSAGE);
-		if (entry.url !== null && collection.urlBase !== null) {
+		if (entry.url !== null) {
 			const route = codeRouteAt(entry.url, codeRoutes);
-			if (route) error(c, '', `${codeRouteMessage(entry.url, route)} Delete ${route.file} if this document replaces it, or move the document.`);
+			// A route left at a held base is reported once, on the route (above), not on every document under it.
+			if (route && !leftBehind.some((l) => l.route.file === route.file)) error(c, '', `${codeRouteMessage(entry.url, route)} Delete ${route.file} if this document replaces it, or move the document.`);
 			const same = sameAddress(entry.url);
 			const first = urls.get(same);
-			if (first) error(c, '', `${first.file} is at ${entry.url} too. Two documents can't share an address: move one.`);
-			else urls.set(same, entry);
+			if (first) {
+				// Decision 8: a clash is an error on both files (each names the other).
+				error(c, '', `${first.file} is at ${entry.url} too. Two documents can't share an address: move one.`);
+				report.errors.push({ file: first.file, path: '', message: `${entry.file} is at ${entry.url} too. Two documents can't share an address: move one.` });
+			} else urls.set(same, entry);
 		}
 	}
 

package/src/code-routes.ts

@@ -108,6 +108,32 @@ export function codeRoutesFrom(routes: readonly CodeRoute[], collections: readon
 	return routes.filter((r) => shadowing.has(r) || !(r.dynamic && bases.has(sameAddress(r.url))));
 }
 
+/**
+ * Collections under pages (Decision 14): the prefix collections whose base has a route with
+ * parameters of its own (`tags/[slug].astro`), which the catch-all's reader leaves to that route,
+ * so no address is built twice. Never a collection at `/` (its own route is the catch-all) or a
+ * held one (its documents are always the catch-all's).
+ */
+export function ownRoutedCollections<C extends { name: string; urlBase: string | null; heldBy?: string | null }>(routes: readonly CodeRoute[], collections: readonly C[]): C[] {
+	return collections.filter((c) => c.urlBase !== null && !c.heldBy && sameAddress(c.urlBase) !== '/' && routes.some((r) => r.dynamic && sameAddress(r.url) === sameAddress(c.urlBase!)));
+}
+
+/** A route with parameters left at a held collection's resolved base (Decision 14): it serves those addresses ahead of the catch-all. */
+export interface LeftBehindRoute {
+	route: CodeRoute;
+	/** The held collection's label, its resolved base, and its holder's label. */
+	collection: { name: string; label: string; base: string; holder: string };
+}
+
+/** Every route with parameters whose static prefix is a held collection's resolved base (`journal/[slug].astro` after the switch). */
+export function leftBehindRoutes(routes: readonly CodeRoute[], held: readonly LeftBehindRoute['collection'][]): LeftBehindRoute[] {
+	return held.flatMap((collection) => routes.filter((r) => r.dynamic && sameAddress(r.url) === sameAddress(collection.base)).map((route) => ({ route, collection })));
+}
+
+/** validate's and the dev log's sentence for a route left at a held base (Decision 14). */
+export const leftBehindMessage = (l: LeftBehindRoute): string =>
+	`${l.route.file} serves ${l.collection.base}…, where the ${l.collection.holder} page's ${l.collection.label} documents are now. Delete it: the catch-all serves them.`;
+
 /** validate's sentence for a route that shadows a collection's documents. */
 export const shadowingMessage = (s: ShadowingRoute<{ name: string; urlBase: string | null }>): string =>
 	`${s.route.file} is a second route with parameters at the ${s.collection.name} collection's address (${s.collection.urlBase}), beside its own ${s.own.file}. Astro ranks it first, so it serves the addresses of that collection's documents and hides them. Move it under a folder of its own, or delete it if the documents replace it.`;

package/src/components/Head.astro

@@ -14,7 +14,7 @@
 import { join } from 'node:path';
 import { site } from 'virtual:caracms/config';
 import { build } from 'virtual:caracms/public';
-import { documentUrl } from '../content.ts';
+import { documentAddress } from '../content.ts';
 import type { PageProps } from '../document.ts';
 import { googleTagSnippet, headOf, withoutHtml } from '../head.ts';
 import { readMediaConfig } from '../media.ts';
@@ -30,17 +30,17 @@ const listPage = !preview && Number.isInteger(Astro.props.listPage) && Astro.pro
 const settingsText = await renderSourceOf(Astro.locals).readText(join(site.root, SITE_SETTINGS_FILE));
 // A public page's path is its own address; a preview's is the document's: the page component's
 // `path` when it's passed on, else the GET's `?path=` (for the home page's title).
-const previewPath = () => {
+const previewPath = async () => {
 	if (Astro.props.path !== undefined) return Astro.props.path;
-	const c = Object.hasOwn(site.collections, collection) ? site.collections[collection]! : null;
 	const path = Astro.url.searchParams.get('path');
-	return c && path ? documentUrl(c, path) : null;
+	// Collections under pages: a held document's address is its holder's + its slug.
+	return path ? documentAddress(site, collection, path, renderSourceOf(Astro.locals)) : null;
 };
 const head = headOf({
 	document,
 	settingsText,
 	// A public page's own address, without a `build.format: 'file'` prerender's `.html` (head.ts).
-	path: preview ? previewPath() : withoutHtml(Astro.url.pathname),
+	path: preview ? await previewPath() : withoutHtml(Astro.url.pathname),
 	siteUrl: preview ? null : build.siteUrl,
 	media: readMediaConfig(),
 	tagAllowed: build.production && !preview,

package/src/components/RenderDocument.astro

@@ -28,7 +28,7 @@
  */
 import { Page } from 'virtual:caracms/page';
 import { site } from 'virtual:caracms/config';
-import { documentUrl } from '../content.ts';
+import { documentAddress } from '../content.ts';
 import { own, type AnyDocument, type PageProps } from '../document.ts';
 import { documentPath } from '../head.ts';
 import { documentReader, renderFields, renderSourceOf, settingsRenderData } from '../read.ts';
@@ -52,10 +52,10 @@ const reader = documentReader(site, source);
 const data = fields && values ? await renderFields(fields, values, reader) : {};
 const settings = await settingsRenderData(site, source, reader);
 const previewOf = Astro.props.previewPath ?? Astro.url.searchParams.get('path');
-const ownCollection = own(site.collections, collection);
 const path = documentPath({
 	preview,
-	previewUrl: preview && ownCollection && previewOf ? documentUrl(ownCollection, previewOf) : null,
+	// Collections under pages: a held document's address is its holder's + its slug, read through the render's source.
+	previewUrl: preview && previewOf ? await documentAddress(site, collection, previewOf, source) : null,
 	pathname: Astro.url.pathname,
 	listPage,
 });

package/src/components/sitemap.xml.ts

@@ -1,7 +1,8 @@
 /**
  * `/sitemap.xml` (M6 Decision 12), prerendered at build from `SITE_URL` (Astro's `site`).
- * Every document with a URL: Pages, nested ones included, and every collection with a
- * `urlBase`, as absolute URLs on the site's address. One file, no index (a site's
+ * Every document with a URL: Pages, nested ones included, every collection with a
+ * `urlBase`, and every held one at its holder's address (collections under pages), as
+ * absolute URLs on the site's address. One file, no index (a site's
  * sitemap is small). Injected only when the address is known, so a build without
  * `SITE_URL` has no sitemap.
  */
@@ -19,9 +20,9 @@ const xml = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&
 export async function sitemapUrls(siteUrl: string): Promise<string[]> {
 	const urls: string[] = [];
 	for (const collection of siteCollections(site)) {
-		if (collection.urlBase === null) continue;
+		if (collection.urlBase === null && !collection.heldBy) continue;
 		for (const entry of await listDocuments(site, collection.name)) {
-			// M9 Decision 7: a hidden page (or one under it) isn't on the site.
+			// M9 Decision 7: a hidden page (or one under it, or held by it) isn't on the site.
 			if (entry.warning || entry.url === null || entry.hidden) continue;
 			urls.push(`${siteUrl}${entry.url.split('/').map((p) => encodeURIComponent(p)).join('/')}`);
 		}

package/src/config.ts

@@ -41,8 +41,17 @@ export interface SectionsCollectionConfig {
 	kind: 'sections';
 	/** The folder holding the collection's content files, relative to the site's root. */
 	folder: string;
-	/** The URL the collection's documents live under: `/` for Pages, `/journal/` for a journal. */
-	urlBase: string;
+	/** The URL the collection's documents live under: `/` for Pages, `/tags/` for tags. Leave it out for a collection a page holds (`heldBy`). */
+	urlBase?: string;
+	/**
+	 * Collections under pages (Decision 2): the documents' address follows a page instead of a
+	 * prefix in code. Names the nested section builder (`'pages'`) one of whose pages holds this
+	 * collection: that page's file says `"holds": "<this collection>"`, and the documents are at
+	 * the page's address + `/` + their slug (`/journal/<slug>`), wherever the page moves. Not
+	 * with `urlBase`, and the collection is flat. Until a page holds it, its documents have no
+	 * addresses (`caracms validate` says why).
+	 */
+	heldBy?: string;
 	/**
 	 * Pages' rule (Decision 8): documents nest in folders and the file's path is the
 	 * URL; `index.json` at the top of the folder is `urlBase` itself, and an
@@ -105,6 +114,15 @@ export interface FieldsCollectionConfig<F extends Fields = Fields> {
 	 * in the page component, as a shared block's own preview is.
 	 */
 	urlBase?: string;
+	/**
+	 * Collections under pages (Decision 2): the documents' address follows a page instead of a
+	 * prefix in code. Names the nested section builder (`'pages'`) one of whose pages holds this
+	 * collection: that page's file says `"holds": "<this collection>"`, and the documents are at
+	 * the page's address + `/` + their slug (`/journal/<slug>`), wherever the page moves. Not
+	 * with `urlBase`, and the collection is flat. Until a page holds it, its documents have no
+	 * addresses (`caracms validate` says why).
+	 */
+	heldBy?: string;
 	/** Every document's fields, in the form's order. `title` is every document's own, so it can't be one of them. */
 	fields: F;
 	/**
@@ -267,8 +285,14 @@ export interface ResolvedCollection {
 	folder: string;
 	/** Absolute. */
 	dir: string;
-	/** Always starts and ends with `/`. Null for the reserved collections, and a fields collection with no pages of its own (M6c G1). */
+	/**
+	 * Always starts and ends with `/`. Null for the reserved collections, and a fields collection with no pages of its own (M6c G1).
+	 * A held collection's (`heldBy`) is null here, in the config, and its holder's address + `/` once a listing resolves it
+	 * (held.ts → withHeldBases); every caller that has a listing uses the resolved one.
+	 */
 	urlBase: string | null;
+	/** Collections under pages (Decision 2): the nested section builder whose page holds this collection; absent when none does. */
+	heldBy?: string;
 	nested: boolean;
 	/**
 	 * A fields collection's fields (labelled); a section builder's page fields (M6c G2,
@@ -347,6 +371,12 @@ export interface ResolvedSite {
 	 * integration at setup (and by the commands). Absent before then: nothing is reserved.
 	 */
 	codeRoutes?: CodeRoute[];
+	/**
+	 * Collections under pages (Decision 14): every route in `src/pages/`, the collections' own
+	 * included, read with `codeRoutes`. The catch-all's reader (content.ts → addressedDocuments)
+	 * leaves out a prefix collection with its own route, and logs a route left at a held base.
+	 */
+	pageRoutes?: CodeRoute[];
 }
 
 export class CaracmsConfigError extends Error {
@@ -419,12 +449,20 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 		if (c.kind !== 'sections' && c.kind !== 'fields') fail(`collection "${name}": kind must be 'sections' or 'fields' (got ${JSON.stringify((c as { kind?: unknown }).kind)}).`);
 		if (!c.folder) fail(`collection "${name}": folder is required.`);
 		const dir = claimFolder(name, c.folder);
+		// Collections under pages (Decision 2): a page holds it, so its address comes from the content, never a urlBase too.
+		const heldBy = (c as { heldBy?: unknown }).heldBy;
+		if (heldBy !== undefined) {
+			if (typeof heldBy !== 'string' || heldBy === '') fail(`collection "${name}": heldBy must name the collection whose page holds it, like 'pages'.`);
+			if (c.urlBase !== undefined) fail(`collection "${name}": it has both urlBase ('${c.urlBase}') and heldBy ('${heldBy}'). Its address comes from one: a prefix in code (urlBase) or the page that holds it (heldBy). Take one out.`);
+			if ((c as { nested?: unknown }).nested) fail(`collection "${name}": a collection a page holds is flat (its documents are at the page's address + their slug), so it can't be "nested".`);
+		}
 		// M6c (G1): a list-of-fields collection may have no pages of its own (no urlBase).
-		const pageless = c.kind === 'fields' && c.urlBase === undefined;
-		if (!pageless && (typeof c.urlBase !== 'string' || !c.urlBase.startsWith('/'))) {
-			fail(c.urlBase === undefined ? `collection "${name}": a section builder needs a urlBase, like '/' or '/journal/' (its documents are pages there).` : `collection "${name}": urlBase must start with "/".`);
+		const pageless = c.kind === 'fields' && c.urlBase === undefined && heldBy === undefined;
+		if (!pageless && heldBy === undefined && (typeof c.urlBase !== 'string' || !c.urlBase.startsWith('/'))) {
+			fail(c.urlBase === undefined ? `collection "${name}": a section builder needs a urlBase, like '/' or '/tags/', or heldBy: 'pages' when a page holds it (its documents are pages there).` : `collection "${name}": urlBase must start with "/".`);
 		}
-		const urlBase = pageless ? null : c.urlBase!.endsWith('/') ? c.urlBase! : `${c.urlBase}/`;
+		const urlBase = pageless || heldBy !== undefined ? null : c.urlBase!.endsWith('/') ? c.urlBase! : `${c.urlBase}/`;
+		const held = heldBy !== undefined ? { heldBy: heldBy as string } : {};
 		const label = c.label ?? titleCase(name);
 		if (c.kind === 'fields') {
 			if ((c as { nested?: unknown }).nested) fail(`collection "${name}": a list-of-fields collection is flat (one level of slugs under its urlBase); "nested" is for section builders.`);
@@ -432,7 +470,7 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 			mustExist(c.component, `collection "${name}": component`);
 			if (!c.fields || typeof c.fields !== 'object') fail(`collection "${name}": fields is required.`);
 			fieldsCollections.push([name, c]);
-			collections[name] = { name, label, kind: 'fields', folder: c.folder, dir, urlBase, nested: false, fields: {}, component: abs(c.component), columns: null };
+			collections[name] = { name, label, kind: 'fields', folder: c.folder, dir, urlBase, ...held, nested: false, fields: {}, component: abs(c.component), columns: null };
 		} else {
 			if (c.columns !== undefined && c.nested) fail(`collection "${name}": columns are for the editor's table of a flat collection; a nested one (Pages) is a tree.`);
 			if (c.sort !== undefined && c.nested) fail(`collection "${name}": sort is for the editor's table of a flat collection; a nested one (Pages) is a tree.`);
@@ -441,10 +479,16 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 				if (!c.fields || typeof c.fields !== 'object' || Array.isArray(c.fields)) fail(`collection "${name}": fields must be an object of fields, like { side: select({ options: ['left', 'right'] }) }.`);
 				pageFieldCollections.push([name, c.fields]);
 			}
-			collections[name] = { name, label, kind: 'sections', folder: c.folder, dir, urlBase, nested: c.nested ?? false, fields: null, component: null, columns: null };
+			collections[name] = { name, label, kind: 'sections', folder: c.folder, dir, urlBase, ...held, nested: c.nested ?? false, fields: null, component: null, columns: null };
 		}
 	}
 	if (Object.keys(collections).length === 0) fail('declare at least one collection.');
+	// Decision 6: a holder is a page of a nested section builder (Pages), whose slugs are addresses.
+	for (const c of Object.values(collections)) {
+		if (c.heldBy === undefined) continue;
+		const by = Object.hasOwn(collections, c.heldBy) ? collections[c.heldBy]! : fail(`collection "${c.name}": heldBy names "${c.heldBy}", which isn't one of the site's collections (${Object.keys(collections).join(', ')}).`);
+		if (by.kind !== 'sections' || !by.nested || by.urlBase === null) fail(`collection "${c.name}": heldBy names "${c.heldBy}", which isn't a nested section builder (like Pages), so none of its documents can hold a collection.`);
+	}
 	const ownCollections = { ...collections };
 
 	const settingsFolder = SITE_SETTINGS_FILE.slice(0, SITE_SETTINGS_FILE.lastIndexOf('/'));
@@ -475,8 +519,10 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 			validateField(field, `${where}: field "${key}"`, fieldCheck(where));
 		}
 		const columns = checkColumns(where, c.columns, c.fields, fail);
-		if (c.urlBase === undefined && columns?.includes('address')) fail(`${where}: its documents have no pages of their own (no urlBase), so there's no 'address' column.`);
-		const sort = checkSort(where, c.sort, columns ?? DEFAULT_COLUMNS.filter((k) => k !== 'address' || c.urlBase !== undefined), c.fields, fail);
+		// A held collection (heldBy) has addresses too, once a page holds it (Contracts → Config).
+		const addressed = c.urlBase !== undefined || c.heldBy !== undefined;
+		if (!addressed && columns?.includes('address')) fail(`${where}: its documents have no pages of their own (no urlBase), so there's no 'address' column.`);
+		const sort = checkSort(where, c.sort, columns ?? DEFAULT_COLUMNS.filter((k) => k !== 'address' || addressed), c.fields, fail);
 		collections[name] = { ...collections[name]!, fields: withLabels(c.fields), columns, sort };
 	}
 	// M6c (G2): a section builder's page fields, beside `title`, `blocks` and `seo` in the file.