smoodly 0.0.59 → 0.0.61

package/docs/media/images-and-crops.md

@@ -0,0 +1,131 @@
+# Images and crops
+
+An image field stores which asset to show and how to frame it. Smoodly's media host cuts the framed area at the width the layout needs, in a modern format, and the image component renders it without layout shift.
+
+## Aspect ratios
+
+An image field declares the ratio of the box it renders into, or several:
+
+File: `components/sections/Hero.schema.ts`
+
+```ts
+    image: f.image({ aspect: "4:5" }),
+```
+
+The crop tool locks to the declared ratio, and with several, `["3:2", "1:1"]`, a switch lets the editor pick one per use. Without an aspect the crop is free and the box takes the crop's own ratio. Declare one where the layout fixes the shape, such as a card or a hero, so the box is known before the image loads. A crop counts only at the ratio the code declares now: change a field's ratio, or a named crop's, and the crops saved at the old one give way to the focus point at the new ratio until an editor frames them again.
+
+## Named crops
+
+Where the layout needs a different shape per screen, name a crop for each instead of one aspect:
+
+File: `components/sections/PageHero.schema.ts`
+
+```ts
+    image: f.image({ crops: { wide: "21:9", tall: "4:5" } }).optional(),
+```
+
+The editor gets a tab per crop in the crop tool, all sharing one focus point. A crop nobody framed follows the focus point at its ratio, so most images need no second look; a framed one keeps its rectangle. The first crop is the main one: the resolved value's `crop` and `aspect` are its, and `crops` holds every one by name.
+
+The view says where each crop applies, with a media query per name. Breakpoints live here, in code, never in content:
+
+**Astro**
+
+File: `src/sections/pageHero.astro`
+
+```astro
+    {image && <Image image={image} media={{ tall: "(max-width: 767px)" }} class="page-hero__image" sizes="100vw" priority {...m.field("image")} />}
+```
+
+**Next.js**
+
+File: `components/sections/PageHero.tsx`
+
+```tsx
+        {image && <SmoodlyImage image={image} media={{ tall: "(max-width: 767px)" }} className="page-hero__image" sizes="100vw" priority {...m.field("image")} />}
+```
+
+The component renders a `<picture>` with one `<source>` per named crop in `media`, in the order given, and the main crop as the `<img>`; each has its own widths and its own `width` and `height`, so nothing shifts on either screen.
+
+## The crop tool
+
+*Edit* on a filled image field opens the tool: the full image with a draggable crop rectangle, a draggable focus point, an alt text box for this use and a live preview at the chosen ratio.
+
+- The **crop** picks the part of the image to show.
+- The **focus point** decides what a crop nobody framed shows, and what stays visible when a view places the image in a box of another shape.
+- The **alt** for this use overrides the asset's own alt from the library when set.
+
+The value the field stores is the asset's id plus this framing. The same photo can be cropped differently in a card and in a hero, and a change in one place leaves the other alone.
+
+## Rendering
+
+The image component renders a box at the crop's ratio and a plain `<img>`, with the dimensions set so nothing shifts as it loads:
+
+**Astro**
+
+File: `src/entry-pages/articles.astro`
+
+```astro
+    {a.image && <Image image={a.image} aspect="21:9" class="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+```
+
+**Next.js**
+
+File: `components/pages/Article.tsx`
+
+```tsx
+        {a.image && <SmoodlyImage image={a.image} aspect="21:9" className="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+```
+
+Here an article's photo, cropped at 3:2 for its card, renders at 21:9 on the article page: the `aspect` prop overrides the ratio for this placement and the focus point keeps the subject in view. [Image, video and file](../fields/media.md) lists the other props.
+
+The bytes come from Smoodly's media host, `media.smoodly.io`. It cuts each image to the area its stored value gives (the editor's crop, or the ratio around the focus point, or the whole image) and serves the cut at one width from a fixed list (320, 640, 750, 828, 1080, 1280, 1536, 1920, 2560 and the cut's own width; from 640 to 1080 the steps `next/image` uses), at quality 75 unless you choose another, in AVIF where the browser takes it and WebP otherwise. The `srcset` lists those widths and `sizes` tells the browser which one the layout needs, so a visitor downloads only the cropped area at about the width it is shown. The page opens a connection to the media host while its HTML is parsed. There is no image config in your project and no image optimizer on your host: neither `next/image` nor Astro's `/_image` is involved. An SVG is served as uploaded.
+
+A static Astro build writes every image its pages show into its own output, under `/_smoodly/media/`: each listed width in AVIF and WebP, offered by type in a `<picture>`, since a static host cannot choose a format per browser. The pages then need nothing from Smoodly at run time and their images come from your own host; a publish reaches them with the next build. Videos and files keep their media address. In local development the service serves the originals and the component crops them in CSS.
+
+## Quality and width
+
+Every image is served at quality 75 with a `srcset` up to the cut's own width unless you say otherwise, in three places; the nearest wins. The whole site, in its config:
+
+File: `smoodly/config.ts`
+
+```ts
+import { defineConfig } from "smoodly";
+
+export const config = defineConfig({
+  registry: {},
+  locales: { default: "en", supported: ["en"] },
+  media: { quality: 85, maxWidth: 1920 },
+});
+```
+
+A kind of image, on its field:
+
+File: `components/sections/Gallery.schema.ts`
+
+```ts
+import { f } from "smoodly";
+
+export const photos = f.list(f.image({ quality: 95 }));
+```
+
+One placement, with the same two props on Astro's `Image` and Next's `SmoodlyImage`:
+
+File: `components/Card.tsx`
+
+```tsx
+import { SmoodlyImage, type ResolvedImage } from "smoodly/image";
+
+export function CardImage({ image }: { image: ResolvedImage }) {
+  return <SmoodlyImage image={image} quality={60} maxWidth={828} sizes="(min-width: 900px) 25vw, 50vw" />;
+}
+```
+
+`quality` is one of 50, 60, 75, 85, 95 or 100; any other number is refused when the config loads or the page renders, since each quality is a separate image the media host makes and keeps. 50 and 60 suit thumbnails and grids, 75 matches what `next/image` serves, 85 and above suit photography. 100 is heavy: a wide image at 100 weighs several times the same one at 85 for a difference few eyes see.
+
+`maxWidth` caps the `srcset` at the listed widths under it and adds no width: `maxWidth: 1000` lists 320, 640, 750 and 828. Use it where the layout never shows an image wide, so a sharp screen does not fetch more than the layout needs. Editors see neither setting. In local development the originals are served, so both apply only on the media host.
+
+## Images inside richtext
+
+A body image, inserted from a toolset with `image` in its nodes, stores the asset, an alt and a caption, and no crop: it renders at its natural ratio through `RichText`, with the text column's `sizes` and the project's `media.quality` and `media.maxWidth`. [Richtext and elements](../fields/richtext.md) covers the toolset.
+
+Next, [Languages](../languages/locales.md).

package/docs/media/library.md

@@ -0,0 +1,40 @@
+# The media library
+
+Every image, video and file editors upload lives in one library. A field stores a reference to an asset, so one photo can appear in many places and be found from each of them.
+
+## Uploading
+
+Editors upload from two places. A media field takes a dropped file straight away, or opens the library to pick one. *Media* in the rail shows the whole library, with an upload button and a filter for images, video and files.
+
+The browser measures an image's dimensions on upload, and captures a frame of a video as its poster, stored as an image asset of its own. What the site can accept is config:
+
+| Name | Description |
+| --- | --- |
+| `media.maxSize` | The largest file, in bytes. Default 25 MB. |
+| `media.accept` | The mime types offered in the file dialog and accepted on upload. Default: JPEG, PNG, WebP, AVIF, GIF, SVG, MP4, WebM and PDF. |
+
+A field narrows the list to its kind: an image field offers image types only.
+
+## The library
+
+Selecting an asset shows its details: the filename, its size and dimensions, and four editable texts:
+
+| Name | Description |
+| --- | --- |
+| `Title` | A name for the asset in the library, searched with the filename. |
+| `Alt` | The alt text an image carries wherever it is used, unless a field sets its own. |
+| `Caption, Credit` | Kept with the asset for your code to render. |
+
+Below them, *Used in N places* lists every page, entry and global that references the asset, from the same index that tracks references between entries.
+
+## Deleting and replacing
+
+An asset can be deleted only while nothing uses it; the message says how many places still do. Removing the field's value, or picking another asset, clears the use.
+
+Uploaded objects never change. *Replace* on a field picks a different asset for that field; the library keeps the old one until it is deleted. This is what lets the site cache media for a year: a URL always serves the same bytes.
+
+## Where files live
+
+Uploads go to Smoodly's storage, served with a year-long cache header; until media moves fully to Smoodly the files live in a bucket Smoodly runs. The browser uploads directly to storage with a signed ticket from the admin, so a large file never passes through your app.
+
+Next, [Images and crops](../media/images-and-crops.md).

package/docs/pages/drafts-and-publishing.md

@@ -0,0 +1,44 @@
+# Drafts and publishing
+
+Every change saves as a draft on its own. Publish makes the draft live, after Smoodly checks it. This page covers the three states, what publish checks, and the two ways back.
+
+## Autosave
+
+There is no Save button. Each change in the editor saves the draft after a moment, and the indicator in the top bar says *Saved* when it has. Nothing reaches the site until an editor publishes; a draft can stay unpublished for as long as it likes. Entries and globals autosave the same way.
+
+Saving is lenient: a draft may be incomplete, with required fields still empty.
+
+## The three states
+
+The badge next to *Publish* shows the page's state in the selected language:
+
+| State | Meaning |
+| --- | --- |
+| `Draft` | Nothing is live. The page has never been published in this language. |
+| `Published` | The live page matches the draft. |
+| `Unpublished changes` | The page is live, and the draft has moved on. This is the state that asks for a click. |
+
+Publishing is per language. A page published in English and edited in Finnish shows *Unpublished changes* in Finnish only.
+
+## What publish checks
+
+*Publish* validates the whole draft first. A required field left empty, a list past its `.max()`, a choice outside its options or a refused CSS snippet stops the publish, and the editor lists the fields to fix. Hidden fields are skipped.
+
+Publish also checks references. A page cannot go live in a language while it shows an entry or a global that is unpublished, or does not exist, in that language, and an entry or a global cannot go live while a reference field of its points at such an entry. The message names the offenders; publish those first.
+
+On a passing publish the live page updates at once, and so do the pages that list it.
+
+## Two ways back
+
+The ⋯ menu next to *Publish* offers two more actions, disabled when they do not apply:
+
+- **Discard changes** throws the draft away and restores the published version, so the page shows *Published* again.
+- **Unpublish** takes the page off the site. Its URL returns a 404 until it is published again. A page whose child is still published in that language cannot be unpublished, so that no page serves under a parent the site no longer shows: unpublish the children first. The home page and every fixed page stay published.
+
+*History*, the first item in the same menu, is on the [next page](../pages/version-history.md).
+
+## Entries and globals
+
+The entry form and a global's form carry the same badge, the same *Publish* and the same menu, and follow the same rules. Publishing a page never publishes a global it shows: a footer going live on every page is a click of its own, in the global's card in the canvas or on its own page under *Site*.
+
+Next, [Version history](../pages/version-history.md).

package/docs/pages/page-tree.md

@@ -0,0 +1,51 @@
+# The page tree
+
+How editors create, arrange and remove pages in the admin, and what your configuration allows them to do.
+
+## The list
+
+*Pages* shows every page as a tree: a row per page, indented under its parent, with its title, its URL, its page type and its status. A multilingual site has a language picker at the top; the tree's shape is shared across languages, and a page that does not exist in the selected language is dimmed. [Languages](../languages/locales.md) covers that side.
+
+Clicking a page opens the editor. Clicking a path expands it.
+
+## Creating pages
+
+*+ New page* asks for a slug, then for the page type when more than one open type is registered, and opens the new page in the editor. Its title starts as the slug until an editor renames it.
+
+*+ New path* creates a path: an item that groups pages under a shared part of their URL and has no page of its own. A row's ⋯ menu offers *New subpage* and *New subpath* under that row, and *Add page here* turns a path into a page by giving it a page type.
+
+How deep the tree may go is config. Without a setting, pages sit side by side at the root. The starter allows three levels:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  pages: { tree: { depth: 3 } },
+  // …
+});
+```
+
+The home page never has children, so a site's pages start at the root beside it.
+
+## Moving pages
+
+Editors drag a row by its grip to reorder it among its siblings, or to move it under another parent. The page's URL follows, because a URL is derived from the page's place in the tree. On a multilingual site a page moves only under a parent that exists in every language the page exists in, and the order is the same in every language unless the config sets [`locales.order`](../languages/locales.md#one-order-or-one-per-language) to `"perLocale"`.
+
+## Pages you own
+
+Two kinds of rows are code-owned and cannot be renamed, moved or deleted: fixed pages, from page types with a `slug`, and collection mounts, from collections with a `path`. Smoodly creates both on the first admin load, so they are there before an editor arrives.
+
+A mount is the collection's place in the tree. When a fixed page claims the same slug, as the starter's Articles index does, the mount row is that page and opens its editor. Without one, the row opens the collection's list.
+
+Code-owned rows always sit at the root, even when their URL has several parts: the starter's News row shows `/company/news` next to the editors' *Company* page. A row marked *No longer in code* is a page whose registration was removed; delete it. A notice under a page's title means visitors get your code's page at its address instead; rename or move it. [Paths and slugs](../pages/paths-and-slugs.md#urls-your-code-owns) covers both.
+
+## Renaming, duplicating and deleting
+
+*Rename…* in the ⋯ menu asks for the title and then the slug, in the selected language. The home page takes a title only; its slug is the config's `homePageSlug`.
+
+*Duplicate…* asks for a title and a slug and makes a new draft page beside the original, with a copy of its sections, page fields and SEO in the selected language. It appears on pages whose page type editors can create; a code-owned page has one address and cannot be duplicated.
+
+*Delete* removes the page in every language, after a confirm. It appears only on a page with no children: move or delete the children first.
+
+Next, [Paths and slugs](../pages/paths-and-slugs.md) explains what makes a valid URL.

package/docs/pages/paths-and-slugs.md

@@ -0,0 +1,74 @@
+# Paths and slugs
+
+A page's URL is derived from its place in the page tree: each item contributes one slug. This page covers what a slug may be, which URLs your code reserves, how a URL changes and how old addresses redirect.
+
+## Three words
+
+- The **URL** is a page's full address within the site, `/company/about-us`. The pages list shows it in the *URL* column.
+- A **path** is an item in the tree that groups pages under a shared part of their URL, like `company`. It has no page of its own, so `/company` is a 404 until an editor gives it a page type with *Add page here*.
+- The **slug** is one item's own part, `about-us`. Editors set it when they create a page and change it with *Rename…*.
+
+In code, parameters named `path` such as the one `renderSmoodlyPath()` takes hold the URL path, and the `page` prop offers both `page.path` and `page.url`. [Page types](../content-modeling/page-types.md) explains the difference.
+
+## What a slug may be
+
+Lowercase letters, digits and single hyphens: `about-us`, `2026-report`. Anything else is refused with a message, in the admin and in code. Two siblings cannot share a slug in the same language, and the admin says so when a second one is tried. The admin makes the slug from the title: `ä` becomes `a`, `ø` becomes `o` and `ß` becomes `ss`. A title in a script without Latin letters, such as `Новости`, makes no slug, and the admin asks you to type one.
+
+A slug is per language. On a multilingual site each language has its own, so `/company/about-us` and `/yritys/tietoa` can be the same page. [Locales and routing](../languages/locales.md) covers translated URLs.
+
+## When a URL changes
+
+A URL is never stored; it is derived from the slugs of the page and its ancestors. Renaming a slug or moving a page changes the URL of the page and of everything below it, at once and everywhere the site links to it through Smoodly.
+
+When the page is published, the admin asks before the change and offers **Redirect the old address**, ticked by default. Leave it ticked and every old address that was live, the page's and its published children's, keeps working: a visitor or a search engine who opens it is sent to the new address with a permanent redirect, so search ranking moves with the page. Untick it and the old addresses stop working. A draft's rename asks nothing and leaves nothing behind.
+
+A redirect points at the page, not at its new address. Rename the page again and both old addresses go straight to the current one. Rename it back and the old address is simply live again. Create a new page at an address that redirects, and the new page wins: the redirect is replaced without a question.
+
+The page's *Settings* tab lists the addresses that redirect to it under **Redirects from**.
+
+## Redirects
+
+*Settings › Redirects* lists every redirect in the current language, with the address it sends visitors to, and lets any member remove one. **Add redirect** takes an old address by hand, for example the URLs of a site you replaced with Smoodly, and the page or entry it should go to. The target is always Smoodly content, picked from a list.
+
+The old address is a site path in the current language, `/old-products/widget`. It needs a leading slash and no trailing slash, query string or hash. Its parts do not have to be slugs: capitals, dots and underscores are fine, because old sites had them, and matching is exact. Letters like ä and ö work too, typed or pasted from a browser's address bar as `/s%C3%A4%C3%A4`: both are the same address, and the list shows it the way you read it. The admin refuses an address a live page already owns, the admin's own address, and on a multilingual site an address with a file extension, because the language proxy never hands those to Smoodly.
+
+Two things to know:
+
+- **Browsers remember a permanent redirect.** After you remove one, a visitor who followed it before may keep landing on the new address until their browser forgets it. Search engines pick up the removal on their next crawl.
+- **Destinations outside Smoodly** and addresses with a file extension or a query string belong in your app's own redirects, which run before any read of Smoodly:
+
+```ts
+// next.config.ts
+export default {
+  async redirects() {
+    return [
+      { source: "/about.html", destination: "/about", permanent: true },
+      { source: "/shop/:path*", destination: "https://shop.example.com/:path*", permanent: true },
+    ];
+  },
+};
+```
+
+A collection's `path` or a fixed page's slug that changes in code leaves no redirect either. The URLs move to the new address when the deploy goes live; add a line like the one above for the old ones.
+
+## URLs your code owns
+
+Some segments are decided in code and checked when the config loads:
+
+| Name | Description |
+| --- | --- |
+| `A fixed page's slug` | smoodly.schema.page({ slug }): one page at that URL, in every language. Editors cannot rename it. It may have several parts, like about/team. |
+| `A collection's path` | smoodly.collection({ path }): its entries live under it, /posts/<slug>. Pages cannot be created under it. It may have several parts, like company/news. |
+| `homePageSlug` | defineConfig({ homePageSlug }), default home: the page with that slug is served at /. |
+| `The admin's path` | defineConfig({ admin: { path } }), default /admin: reserved in every language, so no page can take it. |
+
+Two of these claiming the same address is an error at startup, not a surprise in production.
+
+Your code owns each of these addresses whole. An editor cannot create, rename or move a page onto one or below one, except as a subpage of the fixed page itself; the admin refuses and names the owner: `"/company/news" belongs to the News collection.` The parts in between are not code's. An editor's `/company` page is an ordinary page, and when it is published its rename confirm says that `/company/news` stays where it is.
+
+Nothing an editor made is ever taken over:
+
+- **An editor's page already on the address** stays in the pages list, but visitors get the code's page there, as an `app/` route folder would beat it. The list shows a notice on it: rename or move it to give it a URL of its own. Its sections are never moved into the code's page.
+- **A registration removed from code** leaves its page behind, marked *No longer in code* in the pages list. It has no URL any more and can only be deleted.
+
+Next, [Drafts and publishing](../pages/drafts-and-publishing.md).

package/docs/pages/seo.md

@@ -0,0 +1,126 @@
+# SEO and social
+
+A page type can give its pages an SEO & Social tab: a title, a description, a social image and a switch to hide the page from search engines. Smoodly turns them into the page's metadata.
+
+## Turning it on
+
+Add `seo: true` to a page type. Every page type in the starter has it:
+
+File: `components/pages/Page.schema.ts`
+
+```ts
+export const pageSchema = smoodly.schema.page({
+  name: "page",
+  title: "Page",
+  // …
+  seo: true,
+  // …
+});
+```
+
+The tab appears in the inspector when nothing on the canvas is selected, before *Settings*.
+
+## The four fields
+
+| Field | Notes |
+| --- | --- |
+| `Title` | Used in search results and link previews. Empty means the page's own title. The counter turns amber past 60 characters and blocks nothing. |
+| `Description` | The same, past 160 characters. |
+| `Social image` | From the media library; 1200 × 630 is recommended. |
+| `Hide from search engines` | A switch. On, the page asks search engines not to index or follow it. |
+
+The values are content: they are saved as a draft, published with the page, and per language. A description edited on a draft does not reach the live page until the next publish, and an old version shows the description it was published with.
+
+## What the site emits
+
+**Astro**
+
+Every page type and entry page view receives `head`, and the layout hands it to `Head` from `smoodly/astro/components` inside `<head>`:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <Head of={head} fallback="Lorem Co." />
+  </head>
+```
+
+For a page it writes the document title, the description, the Open Graph title, description, image and URL, the canonical link to the page's own address, and `noindex` when the switch is on. `fallback` titles a document Smoodly has no title for. A page type without `seo: true` still gets its page title; `seo: true` adds the tab and the rest on top.
+
+Every page and entry gets its canonical link. On a multilingual site it also gets the hreflang links to the same page in the other languages. [Language switcher and hreflang](../languages/language-switcher.md) covers where they come from.
+
+The links are absolute on `site` in `astro.config.ts`, which the starter reads from `SITE_URL`. Without `site` they are built from each request's own address, and the build warns. Set `SITE_URL` to your production address where you deploy: [Deploying](../getting-started/deploying.md) lists it with the other variables.
+
+An entry gets its metadata the same way when its collection turns SEO on, described below. Without it, an entry page gets its canonical link and the language alternates only.
+
+**Next.js**
+
+The route file hands metadata to Next through `smoodlyMetadata`, which the installer wires. The multilingual layout's catch-all route:
+
+File: `app/[locale]/[[...path]]/page.tsx`
+
+```tsx
+export async function generateMetadata({ params }: { params: Params }) {
+  const { locale, path = [] } = await params;
+  return smoodlyMetadata(path, { locale });
+}
+```
+
+For a page it sets the document title, the description, the Open Graph title, description, image and URL, the canonical link to the page's own address, and `robots` when the switch is on. The Open Graph image is served at 1200 pixels wide from the media bucket. What the tab leaves empty falls through to the defaults in your root layout. A page type without `seo: true` still gets its page title as the document title; `seo: true` adds the tab and the rest on top.
+
+Every page and entry gets its canonical link. On a multilingual site it also gets `alternates.languages`, the hreflang links to the same page in the other languages. [Language switcher and hreflang](../languages/language-switcher.md) covers where they come from.
+
+The links are absolute when your root layout sets `metadataBase`. Every starter sets it with `metadataBase: siteUrl()`, from `smoodly`: it reads `SITE_URL`, refuses a value without `https://` by name, and falls back to `http://localhost:3000` with a warning in production. Set `SITE_URL` to your production address when you deploy: [Deploying](../getting-started/deploying.md) lists it with the other variables.
+
+An entry gets its metadata the same way when its collection turns SEO on, described below. Without it, an entry page gets its canonical link and the language alternates only.
+
+## SEO for entries
+
+A collection can give its entries the same SEO & Social panel. Add `seo` to the collection:
+
+File: `smoodly/collections.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+
+export const notes = smoodly.collection({
+  name: "notes",
+  title: "Notes",
+  titleField: "title",
+  path: "notes",
+  seo: { description: "excerpt", image: "cover" },
+  fields: {
+    title: f.text().localized(),
+    slug: f.slug({ from: "title" }),
+    excerpt: f.text().localized(),
+    cover: f.image(),
+  },
+});
+```
+
+`seo: true` adds the panel and falls an empty title back on `titleField`. The object form also names the fields that fill an empty description and an empty social image, so articles carry real metadata before anyone touches the panel; an editor's value in the panel still wins, and the switch hides one entry from search engines. The panel's hints say what an empty value falls back on.
+
+The values are saved per language, in the draft, like the entry's other fields. Reads return them as `seo`, the effective values with the fallbacks applied, and the page head uses them.
+
+**Astro**
+
+An entry read with `getLiveEntry("articles", { path, locale })` carries them as `data.seo`, and an entry page's `entry.seo`.
+
+**Next.js**
+
+File: `components/ArticleMeta.tsx`
+
+```tsx
+import { q } from "@/smoodly/server";
+
+export async function articleDescription(id: string, locale: string) {
+  const article = await q().getEntry("articles", id, { locale });
+  return article?.seo?.description;
+}
+```
+
+`$seo` is reserved: a collection cannot declare a field of that name, and the panel's values never show up in `fields`.
+
+Next, [Collections](../collections/defining.md).

package/docs/pages/version-history.md

@@ -0,0 +1,23 @@
+# Version history
+
+Every publish keeps a version. Editors look back at any of them and restore one as the new draft, without touching what is live.
+
+## What a version is
+
+A version is a snapshot of a page's content in one language. Smoodly keeps one for every publish, plus the current draft. Saving rewrites the draft rather than adding a version, so a page's history is a short list of the moments someone chose to go live, not a trail of keystrokes.
+
+The same holds for entries and globals.
+
+## Looking back
+
+*History* is the first item in the ⋯ menu next to *Publish*, on the page editor, the entry form and a global's form. It opens a modal with the versions of the selected language on the left, newest first. The current draft is tagged *Draft* and the version the site serves is tagged *Live*.
+
+Selecting a version shows it on the right: a page renders as the site would render it, an entry or a global appears as its form, read-only. Each version carries when it was saved. The page's *Updated* line, in the inspector, names the editor whose last change touched it.
+
+## Restoring
+
+*Restore* copies the selected version's content into the draft, after a confirm. The current draft is replaced; nothing goes live until an editor publishes, so a restore can be looked at and discarded like any other change. Restoring never removes a version: the history only grows.
+
+A page that has never been published has nothing to restore, and *Discard changes* on a page with unpublished changes drops the abandoned draft rather than keeping it as a version.
+
+Next, [SEO and social](../pages/seo.md).