caracms 0.0.0-stage → 0.2.0

package/skills/caracms-blocks/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: caracms-blocks
+description: Build or change a caracms site's code — blocks and their fields, collections (with or without pages), text styles and lockups, Site Settings fields, the page component, forms, and how the site's scripts (GSAP, Lenis, carousels) behave in the editor's live preview. Use when editing caracms.config.ts or the Astro components it names.
+---
+
+# Building blocks and collections
+
+`caracms.config.ts` is everything caracms knows about the site. It's plain data: fields
+are made with helpers from `caracms/config`, and components are named by their path from
+the site's root (strings, never imports). `astro.config` passes it to the integration
+(`integrations: [caracms(site)]`). A mistake in it stops `astro dev` and `astro build`
+with a sentence naming the problem.
+
+```ts
+import { defineSite, list, richText, text } from 'caracms/config';
+
+export default defineSite({
+	collections: {
+		pages: { kind: 'sections', folder: 'content/pages', urlBase: '/', nested: true },
+	},
+	blocks: {
+		faq: {
+			label: 'Questions',
+			component: 'src/components/caracms/Faq.astro',
+			fields: {
+				heading: text({ heading: true }),
+				items: list({ question: text(), answer: richText() }, { itemLabel: 'question' }),
+			},
+		},
+	},
+	textStyles: {},
+	page: 'src/components/caracms/Page.astro',
+});
+```
+
+A block's `type` in the content is its key here, so **never rename a block key or a field
+key** once content uses it: the content would stop matching. Add new ones instead.
+
+After changing the config, run `npx caracms schemas` (or `validate --fix`) so `schemas/`
+and the content's `$schema` keys match, and commit `schemas/` with the change.
+`astro dev` rewrites the schema files when it starts or restarts, but never touches
+content.
+
+## Fields
+
+All from `caracms/config`. Every one takes `label` (default: the key, title-cased) and
+`help` (a line under the field in the editor).
+
+| Helper | Options | The component gets |
+|---|---|---|
+| `text()` | `multiline`, `heading` (it can hold the page's `h1`), `max` (a soft limit) | `string` |
+| `lockup({ style })` | `style`: a key of `textStyles`; `heading` (default true) | `{ lines, phone }` |
+| `select({ options })` | `options`: strings or `{ value, label }`; `default` (else the first) | the value |
+| `richText()` | `headings: ['h2']` or `['h2', 'h3']` (default none); `links` (default true) | rich text, for `<RichText>` |
+| `link()` | `addressOnly: true` for an address with no words | `{ label, href }`, or `{ href }` / `null` |
+| `buttons({ styles })` | `styles` (strings or `{ value, label }`), `max` (default 2), `allowNoLink` | `[{ label, href, style }]` |
+| `toggle()` | `default` | `boolean` |
+| `number()` | `min`, `max`, `step` | `number \| null` |
+| `date()` | | `"YYYY-MM-DD"` or `null` |
+| `media()` | `only: 'image'` or `'video'`; `play: 'loop'` | for `<Media>` |
+| `reference({ to })` | `to`: a collection's key | the document's path, or `null` if it's gone |
+| `list(field)` / `list({ … })` | `itemLabel`, `min`, `max` (warned, never enforced) | an array |
+| `group({ … })` | | one object |
+
+- A list of several fields may hold one list among its fields; that inner list can't hold
+  a list. A group can't hold a group.
+- Type a component's data from the schema:
+  `export type FaqData = BlockData<typeof faq.fields>;` (keep the block's config in a
+  `.ts` beside its component and import it into `caracms.config.ts`).
+
+## A block component
+
+```astro
+---
+import Block from 'caracms/components/Block.astro';
+import RichText from 'caracms/components/RichText.astro';
+import Text from 'caracms/components/Text.astro';
+import type { BlockProps } from 'caracms/document';
+import type { FaqData } from './faq.ts';
+
+type Props = BlockProps<FaqData>;
+const { block, cms } = Astro.props;
+---
+
+<Block cms={cms} class="faq">
+	<Text cms={cms} field="heading" value={block.heading} class="faq-title" />
+	{block.items.map((item, i) => (
+		<details>
+			<summary><Text cms={cms} field={`items.${i}.question`} value={item.question} as="h3" /></summary>
+			<RichText cms={cms} field={`items.${i}.answer`} value={item.answer} class="prose" />
+		</details>
+	))}
+</Block>
+```
+
+- **Wrap the block in `<Block cms={cms}>`** (`as` sets the element, default `section`;
+  `class` and other attributes pass through). In the editor's preview it marks the block
+  so it can be selected.
+- **Attributes pass through as on a plain element**, on `Block`, `Text`, `RichText`,
+  `Lockup`, `Buttons`, `Link` and `Media`: a bare `data-hero` renders bare,
+  `hidden={false}` renders nothing. `aria-*`, `draggable`, `contenteditable`,
+  `spellcheck` and `writingsuggestions` keep their `"true"` / `"false"` values.
+- **Whitespace in a slot**: Astro's compiler drops the space between an expression and an
+  element in any component's slot, so `<Link …>{label} <span>→</span></Link>` loses it.
+  Write `{label}{" "}<span>→</span>`.
+- **Draw every field through the package's component for its kind**, with `field` (its
+  key, or a dotted path into a list: `items.0.question`) and `value`. In the preview they
+  carry the markers that make text editable on the page; on the public page they're plain
+  markup. Each takes `class` and `as` (the element) and passes other attributes on.
+  - `Text`: a `<p>`, or `h1`/`h2` for a `heading: true` field (the page's first heading is
+    the `h1`). `as` overrides that. It always renders its element, since the editor
+    needs one to edit, so text that was a bare text node gains one: use the element the
+    old markup had where it had one (`as="span"` inside a sentence).
+  - `Lockup`: a lockup in its text style, fitted to its box.
+  - `RichText`: a `<div>` of the rich text's HTML.
+  - `Link`: an `<a>` holding the label (or what you put inside `<Link>`); a link with no
+    label or no address draws nothing. An address-only link wraps what's inside it (an
+    image, an icon). An address-only link's value is `{ href }`, or `null` when it's
+    empty or isn't a valid address; handle `null` in your own markup (draw no link), never
+    fall back to `href=""`. A valid address is a `/path`, `https://`, `mailto:`, `tel:`,
+    `#id`, or `#` alone.
+  - `Buttons`: the buttons, each with `buttonClass` and `<buttonClass>--<style>`.
+  - `Media`: exactly one `<img>` (or the clip). Pass `sizes` (and optionally `ratio`,
+    width / height) for a fluid image, or a CSS `width` and/or `height` for a fixed one;
+    `fit: 'contain'` to fit instead of crop. The block's CSS sizes it through `class`.
+    It takes the element's own attributes (`id`, `title`, `draggable`, `aria-*`,
+    `data-*`) too. With an empty value it draws nothing for visitors and, in a preview,
+    a dashed placeholder the editor can click to pick the image. So call it as
+    `(block.media || cms.preview) && <Media …/>`, not `block.media && …`, wherever an
+    empty slot should still be reachable on the page.
+  - **A media value reaches the block resolved, not as stored.** Where the file has
+    `{ key, alt, focal, w, h }` or `{ video, play, poster: 12.5 }`, the block gets
+    `{ kind: 'image', key, alt, decorative, focal, position, w, h }` or
+    `{ kind: 'video', playbackId, play, name, mp4, poster: <url>, duration, w, h }`
+    (`poster` is Mux's still as a URL, `w`, `h` and `duration` are numbers or `null`;
+    `block.media` is `null` when the slot is empty). A site helper that reads a media
+    value (a hero's poster, a video's `playbackId`) reads this shape; use `kind` to tell
+    the two apart.
+- `cms` is the render context: `cms.preview` (a preview render), `cms.first`,
+  `cms.index`, `cms.read` (other documents, below). For "the first block on the page"
+  (an eager hero, a heading that opens the page) use `cms.first`, true for the first
+  block that renders. Not `cms.index === 0`: `index` is the entry's place in the
+  document's `blocks`, counting entries that don't render (an unknown type, a shared block
+  that's gone). `headingTag(cms, 'heading')` from
+  `caracms/document` gives `'h1'` or `'h2'` for markup of your own.
+- In a preview, draw empty fields too (`cms.preview || block.heading`), so an editor can
+  click into them.
+
+## Collections
+
+```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
+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'] },
+```
+
+- 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
+  component's `<Blocks>` renders it. For a pageless collection that's only the editor's
+  preview of one document.
+- `title` is every document's own; no field can be called `title` (or, on a `sections`
+  collection, `blocks` or `seo`).
+- Options: `label`, `columns` and `sort` (the editor's table), `view`
+  (`{ default: 'list' | 'grid' }`), and on a `sections` collection `fields` (page fields)
+  and `blocks` (the block types its pages may use).
+- **Show a pageless collection** from a block: `await cms.read.documents('people')` gives
+  every document as `{ path, title, data }` (`data` is its fields' values, as a component
+  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.
+- Shared blocks (`content/shared/`) and Site Settings are built in; no config.
+
+## Site Settings fields
+
+```ts
+settings: { fields: { menu: list({ label: text(), href: link({ addressOnly: true }) }), phone: text() } },
+```
+
+They're edited under Site Settings and saved in `content/site-settings.json`, beside the
+package's own keys (`title`, `editors`, `brand`, `seo`, `googleTag`, `formRecipients`,
+`redirects`, which a field can't be called). The page component gets them as
+`Astro.props.settings` (plus `settings.brand.name`): the header, the footer and other
+parts of the page around the blocks read them there. A preview shows the draft.
+
+The site's own `.astro` routes get the same object from `siteSettings`, so a header and
+footer shared with them read one source:
+
+```astro
+---
+import { siteSettings } from 'caracms/content';
+import { site } from 'virtual:caracms/config';
+const settings = await siteSettings(site, Astro.locals);
+---
+```
+
+**A block that needs Site Settings** (a form block showing the site's phone number) reads
+them the same way, with `siteSettings(site, Astro.locals)`: in a preview it reads the
+editor's draft, so an edit to Site Settings shows in the block too. `cms.read` is for
+collections only; it doesn't reach Site Settings.
+
+## Text styles and lockups
+
+A lockup is a heading whose lines are set by the editor and fitted to their box in a
+text style. A style, in `textStyles`:
+
+```ts
+display: {
+	family: 'Site Display', cssVariable: '--font-display',
+	fontFile: { measure: 'src/fonts/Display.ttf', web: 'src/fonts/Display.woff2' },
+	weightRange: '400 700', axes: { wght: 600 },
+	sizePx: 96, minSizePx: 40, trackingEm: -0.02, leading: 1, textTransform: 'none',
+},
+```
+
+`measure` must be a TTF or OTF; `axes` pins every variable axis (`{}` for a static font).
+`<Fonts />` in the page's `<head>` loads the styles' fonts. `phoneLinesWidth` (default
+640) is where a lockup's phone lines take over. A plain heading that doesn't need fitting
+is simpler as `text({ heading: true })` in the site's own CSS.
+
+## The page component
+
+The config's `page` renders a whole page from a document, for the public site and the
+editor's preview alike. It gets `PageProps` (`caracms/document`): `document`,
+`collection`, `path`, `preview`, `data` (the document's own fields), `settings`,
+`listPage`, `read`.
+
+```astro
+<html lang="en" data-preview={preview ? '' : undefined}>
+	<head>
+		<Head document={document} collection={collection} path={path} preview={preview} listPage={listPage} />
+		<Fonts />
+	</head>
+	<body>
+		<SiteHeader items={settings.menu} />
+		<main><Blocks document={document} collection={collection} preview={preview} listPage={listPage} /></main>
+		<SiteFooter />
+	</body>
+</html>
+```
+
+- `path` (`string | null`) is the document's address (`/`, `/about`,
+  `/work/harbour-coffee`), the same on the public page and in the editor's preview: no
+  trailing slash, not URL-encoded. Page 2 of a paged listing (`/journal/page/2`) gives its
+  document's `/journal` (`listPage` says which page). It's null when the document has no
+  page of its own (a shared block's preview, a collection without pages). Read it as
+  `const { path } = Astro.props`, never from `Astro.url` or `?path=`: in the preview those
+  are the editor's own address. Pass it on as `<Head path={path}>` (it's optional there);
+  `caracms init`'s page component does.
+- `<Head>` (`caracms/components/Head.astro`) writes the title, description, canonical and
+  share tags. A page's title is its own `seo.title` as written; otherwise, on the home
+  page, Site Settings' `seo.title`, then the brand name; otherwise
+  `<document title> · <brand name>`. (A home title like `<brand> | <tagline>` goes in the
+  home page's own `seo.title`.) The ` · ` is the
+  config's `titleSeparator`, spaces included: `titleSeparator: ' | '` beside `page` in
+  `defineSite({ … })` keeps a site's old `About | Fernhill`. It's code, not a Site
+  Settings field: the title's format is design. `titleFallback: 'site'` beside it makes every
+  page without its own `seo.title` fall back as the home page does (Site Settings'
+  `seo.title`, then the brand name); the default is `'page-and-brand'`. A code route builds its title the same way
+  from `siteSettings`: `` `${title}${settings.seo.titleSeparator}${settings.brand.name}` ``. `<Blocks>` renders the blocks (or a fields document through its
+  collection's component).
+- `document.kind === 'shared'` is a shared block's own preview: render it without the
+  header and footer.
+- `<Media>` needs a block's `cms`, so images in the page's frame (a logo) stay the site's
+  own files.
+
+## Forms
+
+```ts
+forms: {
+	contact: { label: 'Contact', email: { subject: 'New enquiry' }, fields: {
+		name: { label: 'Your name', autocomplete: 'name' },
+		email: { label: 'Email', type: 'email' },
+		message: { label: 'Message', type: 'textarea', optional: true },
+	} },
+},
+```
+
+Field `type`s: `text` (default), `email`, `tel`, `textarea`, `select` (with `options`),
+`files`. A form's key is stored on every submission, so never rename it once it's live.
+Draw it in a block with `<Form form="contact" preview={cms.preview} submit="Send" />`
+(`caracms/components/Form.astro`); a block can offer a choice with
+`select({ options: [{ value: 'contact', label: 'Contact' }] })`. Submissions land in the
+editor's inbox and are emailed to Site Settings' `formRecipients` for that form.
+
+A field can also take `help`, `placeholder` (text, email, tel, textarea), `prefix` (text,
+tel), `error` (its own error line), `autocomplete`, and on a textarea `rows` (its height in
+lines, 1 to 50; default 6).
+
+The markup's classes are `.cms-form`, `.cms-form-field`, `.cms-form-label`,
+`.cms-form-help`, `.cms-form-error`, `.cms-form-submit` and `.cms-form-status`. For a
+site that draws its own look, `<Form>` takes, each optional (left out, it renders as
+without them):
+
+- `class`, and any other attribute (`data-reveal`, `id`, `aria-*`), on the `<form>`. The
+  form's own attributes (`action`, `method`, its `data-caracms-*`…) can't be replaced.
+- `submitClass`: classes on the submit button, beside `cms-form-submit`
+  (`submitClass="btn btn-primary"`).
+- `thanks`: the line after a send, in place of "Thanks, we'll be in touch shortly."
+  `failed`: the line when a send fails, in place of "Something went wrong. Please email
+  us directly." (when the endpoint gives its own sentence, that shows instead).
+- `errors`: each field type's error line, in place of the package's wording:
+  `errors={{ email: 'Please check your email address.' }}`. A field's own `error` still wins.
+- `actions`: wraps the button and the status line in `<div class="cms-form-actions">`, so
+  the site's CSS can set them in a row.
+- `labelPlaceholders`: a field that can take a placeholder and sets none uses its label.
+
+```astro
+<Form form="contact" preview={cms.preview} class="contact-form" data-reveal
+	submitClass="btn btn-primary" thanks="Thanks — we'll be in touch." actions labelPlaceholders />
+```
+
+## Scripts and the live preview
+
+The editor shows the page in iframes, through the same page component with
+`preview` on. When an editor changes something, the new render is **morphed into the
+frame's `<body>`**: the page isn't reloaded, `<html>` and `<head>` stay, and the body's
+elements are made to match the server's render (so classes and inline styles a script set
+on them can be reset).
+
+- **`<html data-preview>`**: set it in the page component from `preview` (as above), so
+  scripts can tell: `document.documentElement.hasAttribute('data-preview')`.
+- **Opening another document reloads the frames**, so that page loads as on the public
+  site and its own module scripts run on arrival. Only an edit morphs.
+- **`caracms:rendered`**: after each morph (an edit) the frame's `document` gets this
+  event; never on a load, which runs the scripts as usual, and never on the public site:
+
+  ```js
+  document.addEventListener('caracms:rendered', () => { /* pick up new elements, refresh */ });
+  ```
+
+For motion (GSAP, ScrollTrigger, Lenis, Locomotive), the recipe that works:
+
+1. **Read the flag once**, when the site's motion starts:
+   `const preview = document.documentElement.hasAttribute('data-preview')`.
+2. **Leave the scroll native in the preview**, since the editor scrolls the frames to the
+   block being edited. With Lenis, keep the instance (other code may call it) but turn
+   wheel smoothing off: `new Lenis({ smoothWheel: !preview })`.
+3. **Show every animation in its finished state in the preview**, or an editor edits
+   blind: no intro, no entrance, nothing hidden until a scroll reveals it. If the site
+   already has a settled path (what it does on a back/forward visit, or under
+   `prefers-reduced-motion: reduce`), take that path whenever the preview loads (each
+   document opened is a fresh load). A head
+   script that plays an intro stays out of the preview altogether (the page component
+   leaves it out when `preview` is set).
+4. **On `caracms:rendered`, set up again**, on the settled path, then
+   `ScrollTrigger.refresh()`. Either set up only the elements that are new and drop
+   those that are gone, or, if every setup in the preview is settled, revert them all
+   (their GSAP contexts) and run them again: nothing replays, because nothing animates.
+   What jumps is rebuilding with the entrances on.
+
+```js
+const preview = document.documentElement.hasAttribute('data-preview');
+const lenis = new Lenis({ smoothWheel: !preview });
+const settle = preview || matchMedia('(prefers-reduced-motion: reduce)').matches;
+runSetups({ settled: settle }); // the site's own: each section's GSAP, in a gsap.context()
+document.addEventListener('caracms:rendered', () => {
+	revertSetups();
+	runSetups({ settled: true });
+	ScrollTrigger.refresh();
+});
+```
+
+(`runSetups` and `revertSetups` stand for the site's own code; caracms provides only the
+flag and the event.) With `prefers-reduced-motion: reduce`, show the end state too.

package/skills/caracms-content/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: caracms-content
+description: Change a caracms site's content — the JSON files in content/ (pages, collection documents, shared blocks, Site Settings), rich text, images, references, adding an editor — and get it merged with a pull request after `caracms validate`. Use whenever a task adds, edits, moves or deletes content on a site that has caracms.config.ts.
+---
+
+# Changing content on a caracms site
+
+The site's content is JSON files in the repo. The site builds from them, and editors change
+the same files through the editor at `/admin`. What a file may hold is set by
+`caracms.config.ts`: its collections, blocks and fields. Read it first; it's the schema.
+
+**Write files the way the editor saves them:** two-space JSON with a trailing newline, one
+member per line, a string array, a media value and each rich-text block on one line of
+their own. Otherwise the editor's next save reformats the whole file. `validate` warns on
+a file that's laid out otherwise, and `validate --fix` rewrites it the editor's way
+(whitespace only: every key stays where it is, every value as it is).
+
+## Where things are
+
+- **Collections** are in `caracms.config.ts` → `collections`, each with a `folder`.
+  - `kind: 'sections'`: a page is a title and a list of blocks. With `nested: true`
+    (the usual `pages` collection at `urlBase: '/'`), the file's path is the address:
+    `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.
+- **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.
+- **Schemas**: `schemas/<collection>.schema.json`, `schemas/shared.schema.json`,
+  `schemas/site-settings.schema.json`, generated from the config. Every content file's
+  first key is `"$schema"`, the relative path to its schema
+  (`"../../schemas/pages.schema.json"`). Never edit `schemas/` by hand; `caracms schemas`
+  writes it.
+
+File names are lower case words with hyphens (`about-us.json`), since they're addresses.
+
+## The file shapes
+
+A page (`sections`):
+
+```json
+{
+  "$schema": "../../schemas/pages.schema.json",
+  "title": "About",
+  "blocks": [
+    { "type": "hero", "heading": ["A small studio", "with big ideas"], "intro": "Six people." },
+    { "type": "text", "heading": "How we work", "body": "One team from start to launch." },
+    { "shared": "start-a-project" }
+  ]
+}
+```
+
+- `title` is required. It names the page in the editor and in the browser's title
+  (`<title> · <brand name>`, unless `seo.title` is set; the config's `titleSeparator` can
+  make the ` · ` another separator); it isn't necessarily drawn on the page. The home page
+  is the exception: its title is its own `seo.title`, else Site Settings' `seo.title`, else
+  the brand name (the document's `title` only when all of those are empty). With the
+  config's `titleFallback: 'site'`, every page falls back that way, not only the home page.
+- Each block is `{ "type": <a key of the config's blocks>, ...its fields }`. A field left
+  out reads as empty.
+- `{ "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`.
+- An optional `"seo": { "title", "description", "image" }` sets the page's search and
+  share text; leave it out to use Site Settings' defaults.
+
+A fields document: `{ "$schema", "title", ...fields }`, keys in the config's order.
+
+A shared block: `{ "$schema": "../../schemas/shared.schema.json", "title": "Start a project", "block": { "type": "cta", ... } }`.
+
+## Field values
+
+Match each field's kind in the config (`text()`, `richText()`, …):
+
+| Field | Stored as |
+|---|---|
+| `text()` | `"a string"`; with `multiline: true`, `\n` between lines |
+| `lockup({ style })` | lines: `["A small studio", "with big ideas"]`, or with phone lines `{ "lines": [...], "phone": [...] }` |
+| `select({ options })` | one option's `value` |
+| `richText()` | a list, below |
+| `link()` | `{ "label": "Contact us", "href": "/contact" }` |
+| `link({ addressOnly: true })` | `{ "href": "/contact" }` |
+| `buttons({ styles })` | `[{ "label", "href", "style": <a style's value> }]` |
+| `toggle()` | `true` / `false` |
+| `number()` | a number |
+| `date()` | `"2026-10-21"` |
+| `media()` | an image or a clip, below |
+| `reference({ to })` | the referenced document's path in that collection, as a string: `"harbour-coffee"` |
+| `list(field)` | an array of that field's values |
+| `list({ a: …, b: … })` | an array of objects, keys in the config's order |
+| `group({ … })` | one object, keys in the config's order |
+
+**Links** (`href`, in links and buttons) are a `/path` on the site, a full `https://` URL,
+`mailto:someone@example.com`, `tel:+353…`, or a fragment: `#anchor`, or `#` alone (a
+placeholder). Anything else shows as plain text.
+
+**Rich text** is a list of single-key objects:
+
+```json
+"body": [
+  { "p": "We drew the letters from the old **ferry signs**, see [the print work](/services/print)." },
+  { "h2": "From the harbour wall" },
+  { "ul": ["First point", "Second point"] },
+  { "ol": ["Step one", "Step two"] }
+]
+```
+
+- `p`, `ul` and `ol` always; `h2` and `h3` only if the field allows them
+  (`richText({ headings: ['h2'] })`); never `h1`.
+- Inline: `**bold**`, `*italic*`, `[text](href)` (unless the field has `links: false`),
+  `\n` for a line break. Marks open and close inside one paragraph, heading or list item.
+  Write a literal `*`, `[`, `]` or `\` as `\*`, `\[`, `\]`, `\\`.
+
+**Images** are `{ "key": "uploads/1fb083002e3a/harbour-wall.jpg", "alt": "The harbour wall at dusk", "w": 4000, "h": 2667 }`,
+optionally `"focal": [0.4, 0.3]` (the point to keep in a crop, from the left and the top,
+0–1) or `"decorative": true` (then `"alt": ""`).
+
+- The `key` must already be in the site's media library. **You can't upload from a
+  content change.** Reuse a key that's already in the content, or ask a person to upload
+  the image in the editor (or a developer to run `caracms media import`, which prints the
+  key, `w` and `h`).
+- Give every image its `w` and `h`. Without them it still renders, but the page can't keep
+  its space while it loads, and `validate` warns. `caracms media import <the image's file>`
+  prints them (an image already in the bucket isn't uploaded again). A file's key (a PDF
+  in a media slot) needs no size.
+- `alt` says what the image shows, for someone who can't see it.
+- A clip (a Mux video) is `{ "video": "<playback ID>", "play": "loop" | "player" }`; only
+  the editor makes those.
+
+## Site Settings
+
+`content/site-settings.json` holds:
+
+- `editors`: the email addresses that can sign in to the editor. **To add a person,** add
+  their address to this list.
+- `brand`: `name` (the site's name in the editor and in titles) and `accent` (`#rrggbb`).
+  The logo and icon are uploaded in the editor.
+- `seo` (the default search title, description and share image), `googleTag`
+  (`G-…` or `GTM-…`), `formRecipients` (`{ "<form id>": ["someone@example.com"] }`),
+  `redirects` (`[{ "from": "/old", "to": "/new" }]`).
+- The site's own fields, from `caracms.config.ts` → `settings.fields` (a menu, footer
+  links, contact details…).
+
+## Moving or deleting a page
+
+Prefer the editor for these: it updates links to the page and adds a redirect. By hand:
+rename or delete the file, fix every `href` and `reference` that pointed at it (search
+`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`.
+
+## Choosing blocks for a page
+
+**Read the page component before choosing** (the config's `page`, usually
+`src/components/caracms/Page.astro`). How a page looks around its blocks can depend on
+what it's made of: the header's colour or variant, `<main>`'s classes or an intro can
+follow from the page's first block (a map keyed by block type), or from a page field (a
+key after `title`). Pick the first block and the page fields for the look the page should
+have, and compare with an existing page that looks that way.
+
+**When no block fits the content,** a content change can't make one: blocks are code, and
+code is the `caracms-blocks` skill's. Don't bend a block that doesn't fit (a heading
+squeezed into a plain text field), and don't write a component as part of a content
+change. Either:
+
+- say in the pull request what's missing and what you used instead, or
+- make the block first, as a separate change with the `caracms-blocks` skill, then the
+  content on top of it.
+
+Either way, tell the person who asked: they may want the block, or a different page.
+
+## Getting it merged
+
+1. **Work on a new branch** off the site's main branch, and open a pull request into it.
+   Never commit to `main` directly.
+2. **Never touch the `drafts` branch.** It's the editor's: it holds editors' unpublished
+   changes, and publishing from the editor commits to `main`. Don't push to it, merge it
+   or base work on it.
+3. **Run `npx caracms validate` from the site's root before you open the pull request**
+   (with pnpm, `pnpm caracms validate`). It checks every content file against
+   `caracms.config.ts`:
+   - Each problem is a line `file › path.in.the.json: what's wrong`, under `Errors:` or
+     `Warnings:`. It exits 1 when there are errors. Fix every error.
+   - Warnings (a missing `$schema`, schema files out of date, a heading too long for its
+     box, an unknown select value, an image with no `w` or `h`, a file the editor's save
+     would reformat) don't break anything, but fix the ones you caused.
+   - `npx caracms validate --fix` writes the schemas, adds any missing `$schema` keys and
+     lays out each file as the editor saves it, changing only whitespace (that's all it
+     fixes). `--json` prints `{ "errors": [...], "warnings": [...] }`,
+     each `{ "file", "path", "message" }`.
+4. Keep the pull request to content (`content/`, and `schemas/` if `--fix` changed it).
+   Changing blocks or the config is the `caracms-blocks` skill's, in a change of its own
+   (see Choosing blocks for a page).
+
+The site builds from these files, so a merged content change is live on the next deploy.