smoodly 0.0.60 → 0.0.62

package/docs/getting-started/install.md

@@ -0,0 +1,108 @@
+# Install with create-smoodly-app
+
+One command creates a website with the Smoodly admin mounted, connected to a space that holds its content. At the end you have the Lorem Co. starter running on your machine.
+
+## Before you start
+
+You need:
+
+- Node.js 22.12 or newer.
+- An account at [smoodly.io](https://smoodly.io/sign-in), with an email address.
+- A project for the site. A new project has one space, **production**: the content the live site reads. You build the site in it; nothing is public until you deploy.
+
+Open the project's production space. Its page shows the three values the installer asks for: the space id (`sp_…`), the secret key (`sk_…`) and the publishable key (`pk_…`). Keep the page open; the next step pastes them.
+
+## Create the site
+
+Run the installer with the folder to create:
+
+```bash
+npx create-smoodly-app my-site
+```
+
+It asks four things:
+
+1. **Framework?** *Astro* renders each section from an `.astro` file and caches whole pages until an editor publishes. *Next.js* renders sections as React server components. Both get the same admin and the same content. [Frameworks](../frameworks/astro.md) has the details.
+2. **Multilingual site?** Answer no for one language. Yes asks for the locales, the first being the default (`en, fi`). You can read about this choice in [Locales and routing](../languages/locales.md).
+3. **Starter?** *Lorem Co.* is a small company site that uses every feature, which you then edit into your own. *Blank* has one of each part and nothing else: a Text section, a Button element, a `posts` collection with its entry page, a Home and a Page type. This guide uses Lorem Co.
+4. **The space's values.** Paste the space id, the secret key and the publishable key from the space page. The secret key is asked hidden. A key pasted into the wrong question is refused with a message saying which one it is.
+
+The folder can be a name (`my-site`), a path (`../sites/my-site`) or `.` for the current empty folder. Its last part becomes the package name, so it takes lowercase letters, digits, dots, dashes and underscores.
+
+Then it works on its own for a minute or two. It installs the packages and writes the space's values to an env file. It then pushes the site's content model to the space, fills the space with the starter's content and makes a first git commit.
+
+> **Note:** If a step fails, the folder stays and the installer prints the rest under *Finish by hand*: the command that picks up where it stopped. A failed push, for example, finishes with `npx smoodly push && npm run seed` in the new folder.
+
+## Without questions
+
+Every question has a flag, so a script or a coding agent can run the installer with no terminal to answer in:
+
+```bash
+npx create-smoodly-app my-site --yes --framework astro --starter lorem --locales en,fi --space sp_… --secret-key sk_… --publishable-key pk_…
+```
+
+| Flag | What it answers |
+| --- | --- |
+| `--yes` | Takes the default for anything not given: Astro, one language, the Lorem Co. starter. The space's values have no default, so they are still asked. |
+| `--framework astro\|next` | The framework. |
+| `--locales en,fi` | A multilingual site. The first locale is the default. |
+| `--starter lorem\|blank` | The starter. |
+| `--space` | The space id, `sp_…`. |
+| `--secret-key` | The space's secret key, `sk_…`. |
+| `--publishable-key` | The space's publishable key, `pk_…`. |
+
+`npx create-smoodly-app --help` prints the same list. Without a terminal and without the three values, the installer stops and names the flags to pass.
+
+## Run it
+
+When the installer prints *Ready*, start the site:
+
+```bash
+cd my-site
+```
+
+```bash
+npm run dev
+```
+
+**Astro**
+
+Open [localhost:4321](http://localhost:4321) for the site and [localhost:4321/admin](http://localhost:4321/admin) for the admin.
+
+**Next.js**
+
+Open [localhost:3000](http://localhost:3000) for the site and [localhost:3000/admin](http://localhost:3000/admin) for the admin.
+
+The admin sends you to smoodly.io to sign in with your account, and back. The *Pages* list shows the Lorem Co. pages: Home, Articles (at `/posts`), and under the *Company* path About us with its Team page, and News (at `/company/news`).
+
+## What you got
+
+Your content model lives in your code. The dev server and every build push it to your space, so a field you add is editable at once; nothing migrates.
+
+**Astro**
+
+The site keeps its settings in `.env`, Astro's own env file; the integration reads it at `astro dev` and `astro build`:
+
+| Name | Description |
+| --- | --- |
+| `SMOODLY_SPACE_ID` | The space your content lives in, `sp_…`. |
+| `SMOODLY_SECRET_KEY` | The server-only key the site reads content with, `sk_…`. Never expose it to the browser. |
+| `SMOODLY_PUBLISHABLE_KEY` | The space's public key, `pk_…`. It reads published content and nothing else. |
+| `SITE_URL` | The site's own address, `http://localhost:4321` until you deploy. The integration makes it `site`, absolute links in the page head are built from it, and the push gives it to the space. |
+
+The rest is an ordinary Astro project. Your views live in `src/`, and the Smoodly setup lives in `src/smoodly/`.
+
+**Next.js**
+
+The site keeps its settings in `.env.local`:
+
+| Name | Description |
+| --- | --- |
+| `SMOODLY_SPACE_ID` | The space your content lives in, `sp_…`. |
+| `SMOODLY_SECRET_KEY` | The server-only key the site reads content with, `sk_…`. Never expose it to the browser. |
+| `SMOODLY_PUBLISHABLE_KEY` | The space's public key, `pk_…`. It reads published content and nothing else. |
+| `SITE_URL` | The site's own address, `http://localhost:3000` until you deploy. Absolute links in the page head are built from it, and the push gives it to the space. |
+
+The rest is an ordinary Next.js app. Your components live in `components/`, and the Smoodly setup lives in `smoodly/`.
+
+[Keys](../getting-started/keys.md) says what each value can reach. [Project structure](../getting-started/project-structure.md) walks through every file. Next, [make your first page](../getting-started/first-page.md) in the admin.

package/docs/getting-started/keys.md

@@ -0,0 +1,40 @@
+# Keys
+
+The space id and the two keys a Smoodly site uses, where each one may live, what the public one can reach, and how to rotate or revoke a key.
+
+## Three values
+
+Your space's page at smoodly.io shows the three values your env file names. The env file is `.env` in an Astro project, Astro's own env file, and `.env.local` in a Next.js app:
+
+| Variable | Lives | Does |
+| --- | --- | --- |
+| `SMOODLY_SPACE_ID` | server | The space your content lives in, `sp_…`. Every read names it, and a key is refused by any other space. |
+| `SMOODLY_SECRET_KEY` | server only | The space's secret key, `sk_…`. The site reads with it, drafts included, and scripts write with it: the push, the seed, `export` and `import`. It reaches this space only. Never ship it to a browser, a client component or a public repository. |
+| `SMOODLY_PUBLISHABLE_KEY` | server and browser | The space's publishable key, `pk_…`. It reads published content and nothing else. |
+
+The live site and its admin need the space id and the secret key. The admin's browser holds no key: it posts to Smoodly's API with the editor's session, and the API checks the session against the space's members. The starter's `/api/preview` route reads `SMOODLY_PREVIEW_SECRET` for draft previews outside the admin (Next.js only); leave it unset and the route refuses to turn draft mode on.
+
+A preview space's values carry its name: the id is `sp_preview_…` (`sp_eu_preview_…` under the EU jurisdiction), and both keys carry the same `preview`. A production space's have no mark. An env file therefore shows which space it holds. A site needs `smoodly` 0.0.61 or newer to read a preview space; an older version refuses the key as not a Smoodly key. [Deploying](../getting-started/deploying.md#a-preview-space) says when to add one.
+
+`SMOODLY_API_URL` is the address of Smoodly's API, `https://api.smoodly.io` unless you set it. Set it only to reach another service address.
+
+## What the publishable key can reach
+
+Treat it as public. Someone who has it, and nothing else, can read your published content over the API with plain `fetch`, from anywhere, and the media files by their URL.
+
+They cannot:
+
+- read a draft: drafts take the secret key;
+- write, publish, delete or reorder anything: every write takes the secret key or an editor's session;
+- see who your members are, or who is editing what: presence takes a member's session, never a key;
+- open the admin: it needs a member's session.
+
+## Rotating a key
+
+Rotate a key from the space page when someone who should not have it may have seen it, or on a schedule of your own. The space mints a new key and the old one keeps working for the time you choose, a day unless you say otherwise, so the site serves without a gap while you put the new key in your env file and your host's settings and redeploy. You can also end the old key at once: then every site still holding it stops reading until it has the new one.
+
+## Revoking a leaked key
+
+Revoke a key that has leaked. It is refused from its next request, so revoke it once the new key is live: a site still holding it answers its pages with an error naming the key. Every read sends the key again, so a corrected key works on the next request without a restart.
+
+Next, [Deploying](../getting-started/deploying.md).

package/docs/getting-started/project-structure.md

@@ -0,0 +1,142 @@
+# Project structure
+
+What create-smoodly-app puts in your project, and which files you change as you build the site. Everything is ordinary code in your repository; Smoodly adds a folder of setup and mounts the admin.
+
+## The files
+
+**Astro**
+
+A single-language Lorem Co. site:
+
+```
+my-site/
+├── astro.config.ts           the integration: smoodly() mounts the admin, the preview and the pages
+├── src/
+│   ├── layouts/Layout.astro  the site's document: head, header, footer
+│   ├── page-types/           one .astro file per page type, by its name
+│   ├── sections/             one .astro file per section
+│   ├── elements/             one .astro file per element richtext may embed
+│   ├── entry-pages/          one .astro file per collection with a path
+│   ├── components/           every schema (Name.schema.ts) and the starter's helpers
+│   ├── smoodly/              the Smoodly setup
+│   ├── live.config.ts        Smoodly's content as live collections
+│   ├── strings.ts, messages/ the starter's fixed UI text
+│   └── styles/global.css
+├── scripts/seed.ts           the starter content, written from code
+├── public/images/            the starter's photos
+└── .env                      the space's values
+```
+
+A multilingual site adds `i18n` to `astro.config.ts`, with the same locales as `src/smoodly/config.ts`; the site checks that they agree when it starts. The root holds the usual `package.json` and `tsconfig.json`, plus a `README.md`, and an `AGENTS.md` for coding agents that `CLAUDE.md` points to.
+
+**Next.js**
+
+A single-language Lorem Co. site:
+
+```
+my-site/
+├── app/
+│   ├── (site)/              the website
+│   │   ├── layout.tsx
+│   │   └── [[...path]]/page.tsx
+│   ├── (smoodly)/admin/     the admin
+│   ├── api/preview/route.ts draft previews on and off
+│   └── globals.css
+├── components/
+│   ├── pages/               page types
+│   ├── sections/            sections
+│   ├── elements/            elements for richtext
+│   └── …                    the starter's helpers: PageFrame, ArticleCard, strings,
+│                            and articles.ts and news.ts for their URLs
+├── messages/en.json         the starter's fixed UI text
+├── smoodly/                 the Smoodly setup
+├── scripts/seed.ts          the starter content, written from code
+├── public/images/           the starter's photos
+└── .env.local               the space's values
+```
+
+A multilingual site puts the website under `app/[locale]/` instead of `app/(site)/`, adds `i18n/` and `proxy.ts` for [next-intl](https://next-intl.dev), which handles the translated URLs, and a file in `messages/` per language. The root holds the usual `package.json`, `next.config.ts` and `tsconfig.json`, plus a `README.md`, and an `AGENTS.md` for coding agents that `CLAUDE.md` points to.
+
+## The website
+
+**Astro**
+
+There are no route files. `smoodly()` in `astro.config.ts` serves the pages at every address a page file of your own under `src/pages/` does not take. It also mounts the admin at `/admin`, and the preview address editors see the canvas through. `src/pages/404.astro` is yours: the site's "not found" page.
+
+To serve the admin somewhere other than `/admin`, see [The admin](https://smoodly.io/docs/getting-started/admin).
+
+**Next.js**
+
+The site's route is one file, and it needs no editing:
+
+| Name | Description |
+| --- | --- |
+| `app/(site)/[[...path]]/page.tsx` | Every CMS URL: the home, every page at any depth and every collection entry. Smoodly finds the page by its URL, renders it with its page type, and Next keeps it cached until a publish expires it. |
+| `app/(site)/layout.tsx` | The site's root layout: fonts, globals.css and the footer. Yours to change. |
+
+The admin sits in its own route group as one route file and takes no layout, so the site's layout never wraps it. To serve it somewhere other than `/admin`, see [The admin](https://smoodly.io/docs/getting-started/admin).
+
+## Your components
+
+This is where you spend your time, in every framework.
+
+**Astro**
+
+Each section, element and page type is two files. `src/components/…/Name.schema.ts` holds the schema (the fields editors fill). A view named after the schema holds the markup: `src/sections/hero.astro` renders the section named `hero`.
+
+| Name | Description |
+| --- | --- |
+| `src/page-types/` | One view per page type: which zones it renders and where. Lorem Co. has home, page, articlesIndex and newsIndex. |
+| `src/sections/` | One view per section editors place in zones: hero, points, quote and the rest. The header and footer are sections too. |
+| `src/elements/` | One view per element editors insert inside richtext, like callout and cta. |
+| `src/entry-pages/` | One view per collection with a path: articles and news. |
+
+A new section is its schema under `src/components/sections/`, the schema in `src/smoodly/sections.ts` and in the zone of each page type that may hold it, and its view in `src/sections/`. The site names a schema with no view, and a view with no schema, at the first request. [Sections](../content-modeling/sections.md) shows how.
+
+**Next.js**
+
+Each section, element and page type is two files: `Name.schema.ts` holds the schema (the fields editors fill) and `Name.tsx` the React component that renders them.
+
+| Name | Description |
+| --- | --- |
+| `components/pages/` | Page types: which zones a page has and what may go in them. Lorem Co. has Home, Page, Articles, Article, News and News post. |
+| `components/sections/` | Sections editors place in zones: Hero, Points, Quote and the rest. The header and footer are sections too. |
+| `components/elements/` | Small components editors insert inside richtext, like Callout and Cta. |
+
+A new section is two files here, its schema in `smoodly/sections.ts`, its component in `smoodly/views.ts`, and its schema in the zone of each page type that may hold it. [Sections](../content-modeling/sections.md) shows how.
+
+## The Smoodly setup
+
+**Astro**
+
+| Name | Description |
+| --- | --- |
+| `src/smoodly/config.ts` | The registry and settings: the schemas of page types, sections, collections and globals, plus locales, time zone and styles, in one defineConfig(). It imports no view. |
+| `src/smoodly/sections.ts` | The list of section schemas the config registers. |
+| `src/smoodly/collections.ts` | Collections such as articles and people. |
+| `src/smoodly/globals.ts` | Global content such as the header and footer. |
+| `src/smoodly/elements.ts` | The list of element schemas richtext may embed. |
+| `src/smoodly/toolsets.ts` | What each richtext field offers. |
+| `src/live.config.ts` | One loader per collection, global item, the pages and the page tree. Your views read through getLiveCollection and getLiveEntry. |
+
+You edit all of them as the site grows. There is no file of wiring: the integration in `astro.config.ts` reads the config and finds the views by their file names.
+
+**Next.js**
+
+| Name | Description |
+| --- | --- |
+| `smoodly/config.ts` | The registry and settings: the schemas of page types, sections, collections and globals, plus locales, time zone and styles, in one defineConfig(). It imports no component. |
+| `smoodly/sections.ts` | The list of section schemas the config registers. |
+| `smoodly/views.ts` | The components that render the registered schemas, and the entry pages. |
+| `smoodly/collections.ts` | Collections such as articles and people. |
+| `smoodly/globals.ts` | Global content such as the header and footer. |
+| `smoodly/elements.ts` | The list of element schemas richtext may embed. |
+| `smoodly/toolsets.ts` | What each richtext field offers. |
+| `smoodly/richtext.tsx` | The site's richtext renderer, bound to its elements. |
+| `smoodly/server.ts` | Reads content for the site, and exports content() for writing it from code. Server-only. |
+
+You edit the first seven as the site grows. The last two are wiring you rarely touch. The admin itself is one route file, `app/(smoodly)/admin/[[...segments]]/route.ts`.
+
+`scripts/seed.ts` is how the starter's content got there: a script that writes pages and entries under the same rules as the admin. [Content from code](../getting-started/content-from-code.md) shows how to write your own.
+
+Next, [make your first page](../getting-started/first-page.md).

package/docs/getting-started/working-together.md

@@ -0,0 +1,42 @@
+# Working together
+
+Who can open the admin, and what happens when two people open the same page: the admin shows who is where, and never lets one person's save silently overwrite another's.
+
+## Who can open the admin
+
+Everyone who can open the admin is a member of the space, with a role:
+
+|  | Admin | Editor |
+| --- | --- | --- |
+| `Edit, publish, unpublish and delete content; upload and delete media` | yes | yes |
+| `Open Settings` | yes | no |
+| `Manage the space's members` | yes | no |
+
+Members are managed in the project at smoodly.io; the admin's Members page lists them and links there ("Manage members at smoodly.io"). A space always keeps at least one admin, so it cannot lock itself out: a member list without one is refused.
+
+## Signing in
+
+Editors sign in at smoodly.io, never on your site: `/admin` sends them there and back, and someone already signed in at smoodly.io comes straight back without a form. What your site's admin holds is a session for its own space only, renewed while they keep working and good for 30 days from their last visit. *Sign out* in the admin's account menu signs them out of this site and leaves their smoodly.io account signed in; the account menu's *My Account* opens their account at smoodly.io. Someone removed from the project is signed out of its sites at once: their next action sends them to sign in, and the others stop seeing them in presence.
+
+## Who is editing what
+
+A lock after a title in Pages, in a collection or in Sections means someone else has that item open in the language you are looking at. Hover it for their name. Opening the item anyway shows a line under the top bar: *aleksi is also editing this page.* Nothing is locked; it is a heads-up.
+
+Presence runs on Smoodly's service, over one connection per open admin tab. Without it the admin works exactly the same, minus the locks and the line; a tab that loses its connection reconnects on its own.
+
+## When two people save the same thing
+
+Every save, publish, discard and restore carries the version you last loaded. If the other person saved in between, yours is refused rather than applied over theirs, and a red notice says who saved and when:
+
+> aleksi saved a newer version at 14:32.
+> Your unsaved changes here will be discarded.
+
+The form stops taking input until you press **Load their version**, which shows what they saved. Your unsaved edits are gone; the notice says so before you press it.
+
+Most of the time you never see that notice. When the other person saves, an open view that has no unsaved edits quietly refreshes to their version, and one with unsaved edits shows the notice at once.
+
+Only your own edits count. Opening a new page fills its fixed sections for you, and that is saved like an edit. If the other person opened the page first and their view filled it, yours takes their version without the notice.
+
+## Languages are separate
+
+Drafts are per language. Someone editing the Finnish page does not lock the English one, and saves in one language never conflict with the other.

package/docs/globals/defining.md

@@ -0,0 +1,99 @@
+# Defining a global
+
+A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.
+
+## Two kinds
+
+`smoodly.global()` takes a name, a title, and exactly one of `section` or `fields`:
+
+File: `smoodly/globals.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+import { headerSchema } from "@/components/sections/Header.schema";
+import { footerSchema } from "@/components/sections/Footer.schema";
+import { quoteSchema } from "@/components/sections/Quote.schema";
+
+export const header = smoodly.global({ name: "header", title: "Header", section: headerSchema, layout: true });
+
+export const footer = smoodly.global({ name: "footer", title: "Footer", section: footerSchema, layout: true });
+
+export const contact = smoodly.global({
+  name: "contact",
+  title: "Contact details",
+  fields: {
+    email: f.text(),
+    phone: f.text().optional(),
+    address: f.text().localized(),
+  },
+  layout: true,
+});
+
+export const quote = smoodly.global({ name: "quote", title: "Quote", section: quoteSchema });
+
+export const globals = [header, footer, contact, quote];
+```
+
+- A **visual global** takes a registered section's schema. Its fields, settings and styles are the section's, and it renders through the section's view. The starter's header, footer and quote are visual.
+- An **object global** takes fields of its own and renders nowhere by itself; your code reads it. The starter's contact details are one, read by the footer.
+
+Register the list in the config's `globals`. A visual global's section must be in the `sections` list too, which is why the starter's header and footer sit in `smoodly/sections.ts` although no zone lists them.
+
+## Layout globals
+
+`layout: true` says a global is part of every page: the header, the footer, the contact details the footer shows. On Astro the page's own read brings every layout global along, so the layout's `getLiveEntry` calls cost nothing; a page that hides the header simply does not read it. Leave the flag off a global that editors place in zones or that one view reads, such as the starter's quote or a form section used on a few pages: it is resolved into each page that places it, and a view that reads it pays one call. In development, a page render that reads an unflagged global prints a hint naming it, once. On Next the flag changes nothing: its data cache keeps every global until that global is published again.
+
+## In the admin
+
+*Sections*, under ⋮ in the admin's top bar, lists every global with its kind, *Visual* or *Fields*, and its status in the selected language. A *Fields* global opens a form like an entry's, the fields in schema order. A *Visual* global opens on a canvas: a page of the site that shows it, the home page for a `layout` global and otherwise the first page that places it, with the global selected and the rest of the page dimmed. Its fields sit beside the canvas under *Content* and *Settings*, text marked for inline editing can be typed in place, and when several pages place it, *Shown on* picks the page. A visual global no page shows yet opens as a form. Either way the page autosaves, and carries the same *Publish* control, *History* and *Discard changes* as a page.
+
+A global exists in every language from the start, so there is nothing to add or delete. Publishing is per language, as for pages. A field's value is shared across languages unless it chains `.localized()`: the starter's contact email is one value, its address is translated.
+
+## Reading a global
+
+Your code reads a global by name and language, through the [reads](../collections/queries.md). It is `null` until the global is published in that language, so the caller renders nothing rather than an empty header.
+
+**Astro**
+
+A global item is its own live collection, `globalLoader(footer)` in `src/live.config.ts`, read with `getLiveEntry("footer", { locale })`; the value is the entry's `data`:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
+  getLiveEntry("header", { locale }),
+  getLiveEntry("footer", { locale }),
+  getLiveEntry("contact", { locale }),
+]);
+// …
+---
+// …
+    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}
+```
+
+**Next.js**
+
+`getGlobal` reads it:
+
+File: `app/[locale]/layout.tsx`
+
+```tsx
+  const [footer, contact] = await Promise.all([
+    q().getGlobal("footer", { locale }),
+    q().getGlobal("contact", { locale }),
+  ]);
+  // …
+          {footer && <FooterView {...footer.fields} settings={footer.settings} styles={footer.styles} contact={contact?.fields} />}
+```
+
+A global resolves to `{ locale, fields }`, and a visual global adds `settings` with defaults filled, and `styles`. Spread `fields` onto the section's view, with `settings` and `styles` beside it, and the section renders with the spacing steps an editor chose and the id the canvas uses to select it.
+
+## Placing a global on a page
+
+A visual global can also be placed in a zone. `z.locked(quote)` binds a zone to it, so every page of that type shows the one quote; in a freeform or sections zone that allows the global's section, the *Add section* picker offers it under *Global*. A placed global is a link, not a copy: editing it anywhere changes it everywhere, and the canvas tags it *global*.
+
+A page cannot be published in a language while a global it shows is unpublished there. Publishing the page does not publish the global; that is a click of its own, in the global's canvas card or on its page.
+
+Next, [Header and footer](../globals/header-and-footer.md) walks through the starter's layout.

package/docs/globals/header-and-footer.md

@@ -0,0 +1,117 @@
+# Header and footer
+
+The starter's header and footer are visual globals rendered by your layout, not sections placed on pages. This page walks through how they are defined, rendered and edited.
+
+## The sections
+
+The header is a section like any other, with one difference in its schema:
+
+File: `components/sections/Header.schema.ts`
+
+```ts
+export const headerSchema = smoodly.schema.section({
+  name: "header",
+  title: "Header",
+  description: "The site header: brand and navigation.",
+  fields: {
+    brand: f.text(),
+    nav: f.list(f.object({ label: f.text(), href: f.link() })).localized(),
+  },
+  sample: { brand: "Lorem Co.", nav: [{ label: "Home", href: "/" }] },
+  // Nobody pads the header from the editor: no Spacing & layout group.
+  styles: false,
+});
+```
+
+`styles: false` takes away the *Spacing & layout* group, because the header's spacing is the design's. The brand is shared across languages and the navigation is localized as a whole, so each language has its own labels and links. The footer follows the same pattern with a tagline, three link columns and a copyright line.
+
+Both are registered in `smoodly/sections.ts` and named with `smoodly.global()` in `smoodly/globals.ts`, which gives each a row under *Sections* and its `sample` as starting content. No zone lists them, so the *Add section* picker never offers them. Both are `layout: true` ([Defining a global](../globals/defining.md#layout-globals)): on Astro they arrive with the page's own read, so rendering them costs no extra call.
+
+## Rendering them
+
+**Astro**
+
+The layout reads the header, the footer and the contact details as live entries, and renders the sections' views with the values spread:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
+  getLiveEntry("header", { locale }),
+  getLiveEntry("footer", { locale }),
+  getLiveEntry("contact", { locale }),
+]);
+const codes = Object.keys(locales);
+const links = codes.length > 1
+  ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+  : undefined;
+---
+// …
+    {header && <Header {...header.data.fields} settings={header.data.settings} styles={header.data.styles} home={href("/", locale)} locales={links} />}
+    <main><slot /></main>
+    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}
+```
+
+The footer's view takes one prop its schema does not have, the contact object; a view is a plain `.astro` file and accepts anything. The header's language links need the page on screen, and in Astro the layout knows it: every page view passes its own `locales` map to the layout, which Astro renders after the page.
+
+**Next.js**
+
+The root layout reads the footer and the contact details and renders the footer's view:
+
+File: `app/[locale]/layout.tsx`
+
+```tsx
+import { FooterView } from "@/components/sections/Footer";
+import { q } from "@/smoodly/server";
+// …
+  const [footer, contact] = await Promise.all([
+    q().getGlobal("footer", { locale }),
+    q().getGlobal("contact", { locale }),
+  ]);
+  return (
+    <html lang={locale} className={`${serif.variable} ${sans.variable}`}>
+      <body>
+        <NextIntlClientProvider>
+          {children}
+          {footer && <FooterView {...footer.fields} settings={footer.settings} styles={footer.styles} contact={contact?.fields} />}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+```
+
+The layout renders `FooterView`, the view, rather than `Footer`, the paired component, because it passes one prop the footer's schema does not have: the contact object. A paired component accepts only its schema's fields; a view is a plain component and accepts anything. The footer exports both.
+
+The header is not in the layout. A layout cannot know which page is on screen, and the language links in the header must land on the same page in the other language. So every page type renders the header itself, through the starter's `PageFrame`, from the page's own language map:
+
+File: `components/PageFrame.tsx`
+
+```tsx
+export async function PageFrame({ locale, locales, children }: {
+  locale: string;
+  locales: Record<string, LocaleAlternate | null>;
+  children: ReactNode;
+}) {
+  const header = await q().getGlobal("header", { locale });
+  const codes = Object.keys(locales);
+  const links: LocaleLink[] | undefined = codes.length > 1
+    ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+    : undefined;
+  return (
+    <>
+      {header && <HeaderView {...header.fields} settings={header.settings} styles={header.styles} home={href("/", locale)} locales={links} />}
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+On a single-language site there are no links and the header shows the brand and navigation alone. [Language switcher and hreflang](../languages/language-switcher.md) covers the `locales` map.
+
+## Editing them
+
+Editors change the header and footer under *Sections*, or in any page's canvas: both are selectable there, tagged *global*, with their own form and their own *Publish* in the inspector. The header's navigation edits in place like any list with [marks](../content-modeling/marks.md). Publishing a page never publishes the footer, because a footer going live on every page is a deliberate click.
+
+Next, [The media library](../media/library.md).

package/docs/index.md

@@ -0,0 +1,83 @@
+# Smoodly
+
+> Smoodly is a code-first CMS for Astro and Next.js. A developer registers sections, collections and page types in code, editors build pages in a visual admin mounted in the site at /admin, and the content lives in Smoodly Cloud, read by the site over the API.
+
+Start a site with the installer. It creates a fresh app; it does not add Smoodly to an existing one. With these flags it asks nothing:
+
+    npx create-smoodly-app <folder> --yes --framework astro|next --starter blank|lorem [--locales en,fi] --space <sp_…> --secret-key <sk_…> --publishable-key <pk_…>
+
+The three space values are on the project's production space page at smoodly.io. In an installed site, the guides for that version are in node_modules/smoodly/docs/ and the project's AGENTS.md holds the working rules.
+
+## Getting started
+
+- [Install with create-smoodly-app](getting-started/install.md): One command creates a website with the Smoodly admin mounted, connected to a space that holds its content. At the end you have the Lorem Co. starter running on your machine.
+- [Project structure](getting-started/project-structure.md): What create-smoodly-app puts in your project, and which files you change as you build the site. Everything is ordinary code in your repository; Smoodly adds a folder of setup and mounts the admin.
+- [Your first page](getting-started/first-page.md): Create a page in the admin, fill it with sections and publish it, as an editor would. Then look at the code that decided what the editor was allowed to do.
+- [Content from code](getting-started/content-from-code.md): Write pages, entries, globals and images from a script instead of the admin: to seed a new site, or to move a client's old content in. At the end you have a script you can run again after it stops halfway.
+- [Working together](getting-started/working-together.md): Who can open the admin, and what happens when two people open the same page: the admin shows who is where, and never lets one person's save silently overwrite another's.
+- [Keys](getting-started/keys.md): The space id and the two keys a Smoodly site uses, where each one may live, what the public one can reach, and how to rotate or revoke a key.
+- [Deploying](getting-started/deploying.md): Put your Smoodly site on the internet: give it the production space's values and let its build push the schema; then, once it is live, add a preview space to develop against.
+- [Export and import](getting-started/export-and-import.md): Copy a space's content into a folder, and from the folder into a new space: every page, entry, version and media file. It is how you move a site or keep a copy.
+
+## Content modeling
+
+- [Modeling content](content-modeling/overview.md): The five things you register, what each one holds, and where it lives in your project. Read this once; the rest of the group takes them one at a time.
+- [Defining a section](content-modeling/sections.md): A section is a full-width component editors place in a zone. You describe its fields once, in a schema file, and Smoodly derives the editor form, the Add section entry and the TypeScript props from that one definition. This page walks through the Lorem Co. starter's Hero.
+- [Defining a page type](content-modeling/page-types.md): A page type is a page component with zones: the places where editors add sections. This page walks through the Lorem Co. starter's Home and Page types, and what a page type learns about its place in the site.
+- [Zones and freedom](content-modeling/zones.md): A zone is a place in a page type where editors add sections. Its policy sets how much they may change there, from filling one section's fields to placing any section in any order.
+- [Settings, styles and CSS](content-modeling/styles-and-settings.md): Beyond its fields, a placed section carries three more things editors can change: the settings you declare, Smoodly's own spacing and width steps, and a custom CSS box you can turn on. All three sit on the Settings tab.
+- [The custom section](content-modeling/custom-section.md): The one section editors lay out themselves: rows of richtext columns on a 12-column grid, offered where a zone allows it. You turn it on, pick what its columns may hold, and style the result; Smoodly owns the grid.
+- [Marks and inline editing](content-modeling/marks.md): Marks are the attributes a section spreads on the elements that render its fields. They tell the canvas which field an editor clicked, so text edits in place and everything else opens in the inspector.
+- [When the schema changes](content-modeling/changing-schemas.md): Sites change after launch: a section goes, a field is renamed, a zone gets stricter. This page covers what stored content keeps when the code moves on, how the admin shows it, and what Publish refuses until an editor fixes it.
+
+## Fields
+
+- [All fields](fields/overview.md): Every field builder on f, what editors see for each, and the chain of modifiers they share. The pages that follow take them a few at a time.
+- [Text, number, date and time](fields/text.md): The plain values: a line of text, a number, a date, a date with a time, and the slug that becomes part of an entry's URL.
+- [Richtext and elements](fields/richtext.md): Formatted text stored as structured data, the toolset that decides what editors may put in it, and the elements they can insert between the paragraphs.
+- [Link](fields/link.md): A link is a text box that takes a full URL or a path on your site. Pair it with a label in an object to make a button.
+- [Choices](fields/choices.md): A switch, a dropdown, a row of pills or a checkbox list: the fields that pick from a closed set you declare.
+- [Image, video and file](fields/media.md): The three media fields, the resolved values your view receives, and the components that render them.
+- [List and object](fields/list-and-object.md): Group fields into one value with an object, or let editors repeat a value with a list. The two nest one level, which is as far as a sidebar form stays readable.
+- [Reference and tags](fields/reference-and-tags.md): A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.
+- [Conditional fields](fields/conditional.md): Hide a field while another field has a certain value, so editors see only the fields that apply.
+
+## Pages
+
+- [The page tree](pages/page-tree.md): How editors create, arrange and remove pages in the admin, and what your configuration allows them to do.
+- [Paths and slugs](pages/paths-and-slugs.md): 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.
+- [Drafts and publishing](pages/drafts-and-publishing.md): 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.
+- [Version history](pages/version-history.md): Every publish keeps a version. Editors look back at any of them and restore one as the new draft, without touching what is live.
+- [SEO and social](pages/seo.md): 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.
+
+## Collections
+
+- [Defining a collection](collections/defining.md): A collection is a content type with a fixed shape and many entries: posts, people, products. You declare its fields once; editors get a list, a form and publishing for it.
+- [Entry pages](collections/entry-pages.md): Give a collection a path and each entry gets its own URL. The entry page is the component that renders one entry there.
+- [Queries](collections/queries.md): Read entries, globals and the page tree from your own views, typed by your registry, cached, and aware of drafts.
+- [Ordering](collections/ordering.md): A collection has one order, set in its schema, that the admin's list and your queries share.
+
+## Globals
+
+- [Defining a global](globals/defining.md): A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.
+- [Header and footer](globals/header-and-footer.md): The starter's header and footer are visual globals rendered by your layout, not sections placed on pages. This page walks through how they are defined, rendered and edited.
+
+## Media
+
+- [The media library](media/library.md): 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.
+- [Images and crops](media/images-and-crops.md): 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.
+
+## Languages
+
+- [Locales and routing](languages/locales.md): A site publishes in one language or several. This page covers declaring the languages, how each gets its own URLs, and what editors see when a page exists in some languages and not others.
+- [Localized fields](languages/localized-fields.md): On an entry or a global, a field is shared across languages unless it chains .localized(). This page covers the rule, where it applies and what it means for queries.
+- [Language switcher and hreflang](languages/language-switcher.md): Every page and entry knows its own address in every language. A language switcher links from that map, and the site's hreflang tags come from the same one.
+
+## Frameworks
+
+- [Astro](frameworks/astro.md): How Smoodly plugs into an Astro project: one integration in astro.config, views by file name, reads as live collections, pages cached whole and expired by tag, and what happens on a request. The installer writes all of it; this page is for reading it.
+- [Next.js](frameworks/nextjs.md): How Smoodly plugs into a Next.js app: the one route file, the server seam, the admin route group, and what happens on a request. The installer writes all of it; this page is for reading it.
+
+## Reference
+
+- [Upgrading](reference/upgrading.md): Update the package and deploy. Your content model lives in your code and every build pushes it to your space: there is no migration to run.