caracms 0.3.4 → 0.5.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,41 @@ 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.
+
+## Arranging pages
+
+The editor's Pages tree reads Home first, then the pages and groups with pages (or a held
+collection) under them, then the rest, each A–Z. To change that, "Arrange pages…" in the
+tree's header opens a screen at `/admin/arrange`: drag pages to order them, nest one under
+a page or group, make and rename groups, then review every old → new address and apply it
+as one change, with one tick for redirects from the old addresses. Nothing changes until
+Apply, and if the pages change underneath it, Apply refuses and shows the review again.
+
+The order is saved in Site Settings as `pageOrder` (each parent's path → its children's
+slugs), so no site field can use that name. It orders the editor's tree, the Inside picker
+and `listDocuments(site, 'pages')`; the site's menus stay lists in Site Settings.
+`caracms validate` warns on an entry that names no page, and `--fix` prunes it.
+
 ## Hosting
 
 caracms runs on any host that keeps one Node server running behind HTTPS: Railway,
@@ -90,8 +126,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 +312,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/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.4",
+  "version": "0.5.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
 

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;