smoodly 0.0.60 → 0.0.62

package/docs/getting-started/content-from-code.md

@@ -0,0 +1,263 @@
+# Content from code
+
+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.
+
+## Where it runs
+
+**Astro**
+
+`createContent(config)` from `smoodly/astro` builds the content API for a script. It reads `.env` and posts to Smoodly's API with the secret key, which runs the same operations as the admin, with no editor signed in. So every rule the admin enforces holds for a script too: required fields, slug rules, the checks before a publish. It needs the secret key, so it runs on the server only: in a script or an endpoint.
+
+The starter's own content is written this way:
+
+File: `scripts/seed.ts`
+
+```ts
+const { config } = await import("../src/smoodly/config");
+// …
+const { node } = await import("smoodly");
+const { createContent } = await import("smoodly/astro");
+const { content, href } = createContent(config);
+```
+
+`href` turns a path in one language into the site's URL, on the same rules as the site. When `astro.config.ts` sets `i18n`, pass the same object: `createContent(config, { i18n })`. The samples below use `c` for the content API; a script of yours starts like this:
+
+```ts
+import { node } from "smoodly";
+import { createContent } from "smoodly/astro";
+import { config } from "@/smoodly/config";
+
+const { content: c } = createContent(config);
+```
+
+Add a line to `package.json` for it, and run it with `npm run`, from the project's folder:
+
+File: `package.json`
+
+```json
+{
+  "scripts": {
+    "services": "tsx scripts/services.ts"
+  }
+}
+```
+
+```bash
+npm run services
+```
+
+The samples below import from `@/smoodly/server`, the Next.js file; in an Astro script those lines are the three above. Two things about such a script: `astro check` reads it, and a file with a top-level `await` must be a module, which any `import` line at the top makes it; and `@/` resolves from the project's folder, so run it through `npm run`, not `tsx` from elsewhere.
+
+**Next.js**
+
+`smoodly/server.ts` exports `content()`. It posts to Smoodly's API with the secret key, which runs the same operations as the admin, with no editor signed in, so every rule the admin enforces holds for a script too: required fields, slug rules, the checks before a publish. It needs the secret key, so it runs on the server only: in a script, a route handler or a server action. A script that uses a section, an element or a field you just added needs the schema pushed first: a dev server or a build pushes it when it starts, and `npx smoodly push` does it on its own; until then the service refuses the publish, naming the type the space does not know yet.
+
+The starter's own content is written this way. `scripts/seed.ts` loads `.env.local`, then takes `content()`:
+
+File: `scripts/seed.ts`
+
+```ts
+import next from "@next/env";
+// …
+const { loadEnvConfig } = next;
+
+loadEnvConfig(process.cwd());
+// …
+const { content, href, node } = await import("../smoodly/server");
+// …
+const c = content();
+```
+
+`content()` reads the keys when it is called, not when `smoodly/server` is imported, so a script of your own can import it at the top and call `loadEnvConfig` first. Add a line to `package.json` for it, and run it with `npm run`, from the project's folder:
+
+File: `package.json`
+
+```json
+{
+  "scripts": {
+    "services": "tsx scripts/services.ts"
+  }
+}
+```
+
+```bash
+npm run services
+```
+
+## A page
+
+A page is created in one language, given its sections, and published. `node()` builds a section for the tree: its fields are typed from the section's own definition, so a wrong field name fails in your editor. The function below finds the page before it creates it, so it can run again; the last section says why each step is safe to repeat.
+
+File: `scripts/services.ts`
+
+```ts
+import next from "@next/env";
+import { SmoodlyContentError } from "smoodly/admin";
+import { content, node } from "@/smoodly/server";
+import { pageHeroSchema } from "@/components/sections/PageHero.schema";
+import { pointsSchema } from "@/components/sections/Points.schema";
+
+next.loadEnvConfig(process.cwd());
+const c = content();
+
+async function servicesPage() {
+  const page =
+    (await c.pages.find("en", "/services")) ??
+    (await c.pages.create({ parentId: null, locale: "en", slug: "services", template: "page", title: "Services" }));
+  await c.pages.setTree(page.id, "en", {
+    zones: {
+      hero: [node(pageHeroSchema, { heading: "Services", text: "What we do for our clients." })],
+      body: [node(pointsSchema, { heading: "Three things", points: [{ icon: "circle", heading: "Design", text: "Sites that read well." }] })],
+    },
+  });
+  await c.pages.publish(page.id, "en");
+  // The Finnish page starts as a copy of the English one, at its own slug.
+  if (!page.locales.fi) await c.pages.addLocale(page.id, "fi", { from: "en", slug: "palvelut", title: "Palvelut" });
+  await c.pages.publish(page.id, "fi");
+  return page;
+}
+```
+
+The example is the multilingual Lorem Co. starter's: on a one-language site leave out the Finnish lines, and on Blank the Page type has a `body` zone only. `hero` and `body` are the zones of the starter's Page type, and each takes the sections its zone lists. The Finnish page holds the English text until `setTree(page.id, "fi", …)` gives it its own. `template` is the page type's `name`, and `parentId` is another page's id, or `null` for the top level. `getTree(id, locale)` reads a page's draft back, for a script that changes a page instead of replacing it. `pages.list({ locale, template })` gives every page in a language, folders left out, for a script that changes many:
+
+File: `scripts/rename.ts`
+
+```ts
+import next from "@next/env";
+import { content } from "@/smoodly/server";
+
+next.loadEnvConfig(process.cwd());
+const c = content();
+
+for (const page of await c.pages.list({ template: "page" })) {
+  const tree = await c.pages.getTree(page.id, "en");
+  // …change the tree, then:
+  if (tree) await c.pages.setTree(page.id, "en", tree);
+}
+```
+
+Every call throws a `SmoodlyContentError` when the admin would have refused it. It comes from `smoodly/admin`, which is server code: a script may import it, the site's pages and sections never do. The error carries a `code` and, for a publish that failed validation, one line per field:
+
+File: `scripts/services.ts`
+
+```ts
+async function run(step: () => Promise<unknown>) {
+  try {
+    await step();
+  } catch (error) {
+    if (!(error instanceof SmoodlyContentError)) throw error;
+    console.error(error.code, error.message);
+    for (const field of error.fields) console.error(field.field, field.message);
+    process.exit(1);
+  }
+}
+```
+
+The draft stays as the script left it, so you can fix the content and run the publish again.
+
+## Entries, globals and images
+
+An entry is created with its fields, then published. A localized field gets its other language with `addLocale`. A reference is stored as the other entry's id, so pass `person.id` where a field is an `f.ref()`. A slug that follows another field, `f.slug({ from: "title" })`, is filled from it when you leave it out, as the admin's form does; pass `slug` to choose your own.
+
+An `f.richtext()` value is the editor's own document, TipTap JSON: a `doc` holding paragraphs, headings and lists, each holding text. A required richtext field left out is a *Required* error on publish:
+
+File: `scripts/services.ts`
+
+```ts
+const text = (t: string) => ({ type: "doc", content: [{ type: "paragraph", content: [{ type: "text", text: t }] }] });
+await c.entries.create("recipes", { locale: "en", fields: { title: "Fish stew", body: text("Serves four.") } });
+```
+
+File: `scripts/services.ts`
+
+```ts
+async function person() {
+  const aino = await c.entries.create("people", { locale: "en", fields: { name: "Aino Virtanen", role: "Designer" } });
+  await c.entries.addLocale("people", aino.id, "fi", { from: "en", fields: { name: "Aino Virtanen", role: "Muotoilija" } });
+  await c.entries.publish("people", aino.id, "en");
+  await c.entries.publish("people", aino.id, "fi");
+  return aino;
+}
+```
+
+A global exists once, so there is nothing to create: `set` writes its fields and `publish` makes them live. Until the publish the change is a draft: the live site shows the old fields, draft mode shows the new ones, which is a quick way to try a preview link.
+
+File: `scripts/services.ts`
+
+```ts
+async function contactDetails() {
+  await c.globals.set("contact", "en", { email: "hello@example.com", address: "Main Street 1, Helsinki" });
+  await c.globals.publish("contact", "en");
+}
+```
+
+`media.upload()` takes a file path or bytes and puts the file in the media library. The admin's rules apply: an accepted file type and the size limit from `media` in the config. It returns the value an `f.image()` field stores, so it goes straight into a node or an entry:
+
+File: `scripts/services.ts`
+
+```ts
+async function teamPage() {
+  const photo = await c.media.upload("public/images/about_main.jpg", { alt: "The team at work" });
+  const page = await c.pages.create({ parentId: null, locale: "en", slug: "team", template: "page", title: "Team" });
+  await c.pages.setTree(page.id, "en", {
+    zones: { hero: [node(pageHeroSchema, { heading: "Our team", text: "The people you will work with.", image: photo })] },
+  });
+  await c.pages.publish(page.id, "en");
+}
+```
+
+## Run it twice
+
+A script that stops halfway, on a validation error or a dropped connection, gets run again. Each step above is safe to repeat, or guarded:
+
+- `pages.find(locale, path)` returns the page at that URL, a draft included, or `null`. Finding before creating makes the page once.
+- `setTree`, `globals.set` and `publish` replace what is there, so a second run leaves the same result.
+- `addLocale` refuses a language the page already has, so check `page.locales` first.
+- `entries.find(collection, { slug })` finds an entry by its slug, in the default language unless you pass a `locale`.
+- `entries.list(collection, { where })` lists the entries whose fields match, for a collection without a slug field, such as the starter's people. A field holding a list, such as tags, matches when it holds the value:
+
+File: `scripts/services.ts`
+
+```ts
+const [existing] = await c.entries.list("people", { where: { name: "Aino Virtanen" } });
+const aino = existing ?? (await person());
+```
+- Every `media.upload` adds a file to the library. Upload where the thing that uses it is created, once.
+
+File: `scripts/services.ts`
+
+```ts
+await run(async () => {
+  const hadTeam = (await c.pages.find("en", "/team")) !== null;
+  await servicesPage();
+  await contactDetails();
+  // The team page, its photo and its person are made together, on the first run only.
+  if (!hadTeam) {
+    await person();
+    await teamPage();
+  }
+});
+```
+
+## Code-owned pages
+
+A fixed page type, such as Home or a collection's list page, has its URL in code. It is live as soon as the code is deployed, with empty zones, and you never create it. `find` returns its record, making it first when the space is new. Then you fill it like any page:
+
+File: `scripts/services.ts`
+
+```ts
+async function articlesList() {
+  const list = await c.pages.find("en", "/posts");
+  if (!list) return;
+  await c.pages.setTree(list.id, "en", { zones: { hero: [node(pageHeroSchema, { heading: "Articles", text: "What we have been writing." })] } });
+  await c.pages.publish(list.id, "en");
+}
+```
+
+Its title and slug stay what the page type says, in every language.
+
+## Members
+
+Who can sign in to the admin is not set from code. A space's member list is kept at smoodly.io and arrives in the space whole; the admin's Settings › Members page shows it and links there.
+
+Next, [the admin](https://smoodly.io/docs/getting-started/admin) is where editors take over from here.

package/docs/getting-started/deploying.md

@@ -0,0 +1,131 @@
+# Deploying
+
+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.
+
+## What a deploy needs
+
+**Astro**
+
+A Smoodly site on Astro is a server-rendered Astro site. The starter's `@astrojs/node` adapter deploys to any host that runs `astro build` and starts `dist/server/entry.mjs`. Pages are cached in that process's memory and expire when an editor publishes.
+
+On Vercel, swap the adapter for Vercel's, and the cache for its CDN:
+
+File: `astro.config.ts`
+
+```ts
+import { defineConfig } from "astro/config";
+import vercel from "@astrojs/vercel";
+import { cacheVercel } from "@astrojs/vercel/cache";
+import smoodly from "smoodly/astro";
+
+export default defineConfig({
+  output: "server",
+  adapter: vercel(),
+  // Pages are cached on Vercel's CDN and expired by tag when an editor publishes.
+  cache: { provider: cacheVercel() },
+  site: process.env.SITE_URL,
+  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
+});
+```
+
+Install it with `npm install @astrojs/vercel`. The steps below name Vercel's settings; other hosts have the same ones under other names.
+
+Run the function near your visitors. A page that is not in the CDN yet makes one call to Smoodly's API, answered from the edge when cached and otherwise by your space, which lives near where you made the project: Stockholm for a project made from Europe. On Vercel, `vercel.json` sets the function's region with `{ "regions": ["arn1"] }` (Stockholm; the [region list](https://vercel.com/docs/regions) names the rest). Vercel's Speed Insights (`@vercel/speed-insights`, mounted as its Astro or Next component in your layout) records real visitors' Web Vitals; it is your site's script, not Smoodly's, and optional.
+
+### Static
+
+Set Astro's output to static and every published page is built as a file: visitors need no function, and the site stays up if Smoodly's API is down.
+
+File: `astro.config.ts (static)`
+
+```ts
+import { defineConfig } from "astro/config";
+import vercel from "@astrojs/vercel";
+import smoodly from "smoodly/astro";
+
+export default defineConfig({
+  output: "static",
+  adapter: vercel(),
+  site: process.env.SITE_URL,
+  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
+});
+```
+
+Publishing does not change the live site. Editors press **Deploy** in the admin's top bar, next to their avatar, when they are done, and the host builds. Give the site the host's deploy hook as `SMOODLY_DEPLOY_HOOK` where `astro build` runs (on Vercel: Settings › Git › Deploy Hooks): the build hands it to Smoodly's API with the site's address; without it the tile shows what is waiting and Deploy stays disabled. `SITE_URL` must be the site's own address, and the build refuses static output without it: the tile reads the build's marker, `/_smoodly/build.json`, from there. It says *Building…* until the new build answers, *N changes* while publishes wait (an unpublish or a delete counts as one too), and *The build has not landed* after ten minutes with no new build, in which case look at the host's log. A host that strips query strings from a cached file can hold the old marker for its max-age.
+
+The admin, its revalidate and preview routes and the preview address still run on demand, so the deployment is files plus one function; a host with no function at all cannot run the admin. A static page has no lists by query string and no draft at its real address: drafts are edited through the preview address, as in live mode. A moved page's old address becomes one of the host's redirects at build, so it is answered without a function too. The cache provider in `astro.config` is unused in static output and may stay.
+
+**Next.js**
+
+A Smoodly site on Next.js deploys like any other Next.js app: to Vercel, or to any host that runs `next build` and `next start`. Pages are served from the host's cache (on Vercel, the CDN: `x-vercel-cache: HIT`) and expire when an editor publishes; the function runs for the first visit of an address and for the editor's preview. The steps below name Vercel's settings; other hosts have the same ones under other names.
+
+## Environment variables
+
+Set these in your host's project settings. Production gets the production space's values. Your host's Preview environment gets the preview space's once the project has one ([A preview space](#a-preview-space)), and the production space's until then. A missing or wrong key answers every page with a 500 and names the variable in the server log, your host's function logs:
+
+| Variable | What it is |
+| --- | --- |
+| `SMOODLY_SPACE_ID` | The space your content lives in, `sp_…`. A key from another space is refused by name. |
+| `SMOODLY_SECRET_KEY` | The space's secret key (`sk_…`). Server-only: never expose it to the browser. A wrong key fails every page with one of these: the publishable key `holds the publishable key`; a string that is no Smoodly key `is not a Smoodly secret key`; a key the space does not hold `is not one of the space's live keys`. Every read sends the key again, so a corrected key works on the next request. |
+| `SMOODLY_PUBLISHABLE_KEY` | The space's publishable key (`pk_…`): it reads published content only, so a browser may hold it. |
+| `SITE_URL` | The site's own address with its scheme, like `https://www.example.com`. The build pushes it to the space: the admin's operations are accepted from it, and a publish calls it back. Your root layout builds `metadataBase` from it, so the canonical link, hreflang links (on a multilingual site) and social image URLs are absolute. Unset, it falls back to `http://localhost:3000` and the server warns once per process (a build prints it from each of its workers); a value without `http://` or `https://` stops every page with an error that names it. It is read when the server starts, so restart or redeploy after changing it. |
+| `SMOODLY_PREVIEW_SECRET` | Next.js only; an Astro site has no such route and ignores the variable, since its drafts live at the preview address inside the admin. Optional. Lets a link turn draft mode on outside the admin: `/api/preview?secret=…&path=/` sets the draft cookie and redirects to `path`; a wrong or missing secret gets a 401. `/api/preview?disable` turns it off and needs no secret. Leave the variable unset and only the admin can turn draft mode on. |
+
+On Astro the same variables are read at build and at run time. `SITE_URL` becomes `site`, fixed into the build, so set it where `astro build` runs (in the host's settings, or in `.env` for a build on your machine); without it, the absolute links in the page head are built from each request's own address, and the build warns.
+
+[Keys](../getting-started/keys.md) says what each key can reach, and how to rotate one.
+
+### Seeing what a page costs
+
+Set `SMOODLY_DEBUG_READS=1` on the server and every page answers with two headers: `x-smoodly-reads`, the number of calls to Smoodly's API the response made (a page is one: the lookup brings the layout globals along, so the layout's reads cost nothing; a list on the page is one more, and so is a global without `layout: true` that a view reads), and `Server-Timing`, each call by its key with when it started and how long it took, then the render. `curl -sD - -o /dev/null https://your-site/?v=1` shows them on a cache miss. Leave the variable unset for visitors.
+
+## The push at build
+
+Your content model lives in your code, and each build pushes it to the space with the site's address. A Next site's `prebuild` script runs `smoodly push`; an Astro build does it itself. The build log shows `Pushed schema version 1 to the production space sp_…`, or `Schema unchanged (version 1) in the production space sp_…` when nothing changed (`the preview space sp_preview_…` for a preview space), so the log says which space the build reached. The dev server says the same line once when it starts. A push that fails is logged and never fails the build. There is no migration to run and no document to rebuild: a package upgrade or a content-model change reaches the space with the next deploy.
+
+In live mode every page renders on request, so the framework's build reads no content: a build without the keys still succeeds and only skips the push. A static Astro build reads every published page, so it needs the keys.
+
+If your site takes the package from a packed tarball in the repository rather than from npm, replacing the file is not enough: a host that restores `node_modules` from its build cache (Vercel does) sees the same path and version and keeps the old package. Deploy once without the cache (`vercel --prod --force`), or give the tarball a new name.
+
+## The starter's content
+
+The installer already filled the space with the starter's content. On a new site that is the production space, so the content you build on is where the live site reads it and a first deploy has nothing to copy. If the installer's seed failed, or you chose to run it later, run it yourself; it fills the space your env file names:
+
+```bash
+npm run seed
+```
+
+A space without a schema refuses the seed with `no_schema`: start the dev server or build first, which pushes the schema.
+
+## A preview space
+
+A preview space is a full copy of production to develop against: its pages, entries, history, redirects and media. A project has none until you add one, and many sites never need one before they go live.
+
+Add it once the site is live. A dev server and every build push the site's schema to the space they read. Before launch that is what you want. After it, a schema change you try on your machine, or in a preview deployment, would change what the live site serves if they still read production.
+
+1. Open the project at smoodly.io, go to *Spaces & keys* and choose **Add a preview space**. Its two keys are shown once; its id stays on the page.
+2. Put the three values in your env file, and in your host's Preview environment.
+3. Wait for the copy; the page shows its progress. While it runs the preview space refuses edits, uploads and schema pushes, its admin says a copy is in progress, and a site reading it may show missing pages.
+4. When the copy is ready, restart the dev server and redeploy the preview environment. Their push was refused if they started during the copy, and a site signs in to its admin only from an address its push gave the space.
+
+If a copy fails, the page says why, and the preview space stays locked: its admin and a push say the copy failed. Choose **Try again** there to continue where it stopped, or **Refresh from production** to start over.
+
+A preview space's values say what they are: its id is `sp_preview_…` and both keys carry it. The build log names the space a push reached, so you can see which one a build used.
+
+**Refresh from production**, on the same page, replaces everything in the preview space with a new copy: preview's own content changes are lost, and its keys and its schema stay the same. After a refresh, restart or redeploy the site that reads preview: it may hold pages it cached before. Nothing travels the other way. Content is edited in production; preview is where code and schema changes are tried against a copy of it.
+
+## Sign-in on the real address
+
+Editors sign in at `/admin` on the deployed site as they do locally: the admin sends them to smoodly.io and back. The deploy's push gives the space the site's address, and smoodly.io sends an editor back only to an admin address the space recorded that way (a preview deploy's and `localhost` included), so there is nothing to set.
+
+## Preview and drafts
+
+**Astro**
+
+Editors see drafts at the preview address, `/_smoodly/preview/<path>`, inside the admin only: a signed cookie opens it, and nothing there is cached. A live address never shows a draft, and there is no pill.
+
+**Next.js**
+
+The editor turns on draft mode (Next's way of rendering unpublished content for one browser). While it is on, a small pill at the bottom of each page says *Preview · unpublished changes*. *Exit preview* turns draft mode off through `/api/preview`, which every starter includes. Visitors never get the pill or any of its code.
+
+Next, [Astro](../frameworks/astro.md) and [Next.js](../frameworks/nextjs.md) cover what each framework adds.

package/docs/getting-started/export-and-import.md

@@ -0,0 +1,73 @@
+# Export and import
+
+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.
+
+## What travels
+
+`npx smoodly export` writes your site's content into a folder: every page and entry with its whole history, the redirects, and the media library with its files. `npx smoodly import` writes that folder into another space. Every id stays the same, so the site renders exactly as before.
+
+To copy production into a project's preview space, use **Add a preview space** or **Refresh from production** at smoodly.io ([Deploying](../getting-started/deploying.md#a-preview-space)): the service copies it for you. These two commands are for moving a site to another project and for keeping a copy.
+
+Members do not travel: a space's members are set in the project at smoodly.io. The import lists the source's members, so you can add them to the new space there.
+
+Both commands run in your app's folder and read `SMOODLY_SPACE_ID` and `SMOODLY_SECRET_KEY` from `.env.local` (Astro: `.env`). The secret key decides whose content they reach, so there is nothing else to pass. The publishable key is refused, because it reads no drafts and writes nothing:
+
+```
+smoodly: SMOODLY_SECRET_KEY holds the publishable key (pk_…) — copy the secret key (sk_…) from the space page.
+```
+
+## Export
+
+```bash
+npx smoodly export
+```
+
+```
+Exported space sp_…: 14 pages (41 versions), 32 entries (118 versions), 51 assets (38.2 MB), 9 redirects
+→ smoodly-export-2026-10-16/
+```
+
+The folder lands in the folder the command runs in. It holds `manifest.json`, one JSON file per table under `rows/` and the media files under `media/`. Zip it to hand it over. `--out <dir>` names another folder. An existing folder is never overwritten. The starters' `.gitignore` lists `smoodly-export-*`, so the folder stays out of your repository.
+
+An editor who saves while the export runs can stop it with `Content changed during export — run it again.` Run it again.
+
+## Import into a new space
+
+A space that already has content refuses an import, so import into a new one:
+
+1. Export, with the env file still naming the space you are leaving.
+2. Create a new project at smoodly.io and copy its production space's three values.
+3. Point the env file at the new space: its `SMOODLY_SPACE_ID`, `SMOODLY_SECRET_KEY` and `SMOODLY_PUBLISHABLE_KEY`.
+4. Push the schema, so the space can serve the site (a build or the dev server would push it too):
+
+```bash
+npx smoodly push
+```
+
+5. Import:
+
+```bash
+npx smoodly import smoodly-export-2026-10-16
+```
+
+The path is the export folder's, relative or absolute, so it can stay in the old site's folder. A live page reads what landed straight away: there is nothing to rebuild.
+
+```
+Imported 14 pages, 32 entries, 51 assets and 9 redirects into space sp_….
+Members in the source — add them to the space's members in the project at smoodly.io:
+  anna@example.com (admin), mikko@example.com (editor)
+Restart or redeploy the app: it may have cached pages from while the space was empty.
+```
+
+6. Add the members to the new space at smoodly.io: nobody can sign in to its admin until its member list names them. Then restart or redeploy the app.
+
+## When import refuses
+
+Import checks everything before it writes anything.
+
+- **The space already has content.** Import writes only into an empty space, and it never deletes. Use a new project's space.
+- **The space is being copied into.** A preview space refuses an import while a copy from production runs, and after one failed. Wait for the copy, or retry it at smoodly.io.
+- **The service versions differ.** The export and the target space must come from the same version of Smoodly's service. The message says which side is newer.
+- **It stopped midway**, on a dropped connection for example. Run the same command again: rows and files that already landed are skipped. A run that finds everything already there says `Nothing new` and writes no content.
+
+Next, [Upgrading](../reference/upgrading.md).

package/docs/getting-started/first-page.md

@@ -0,0 +1,98 @@
+# Your first page
+
+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.
+
+## Create the page
+
+This page assumes the Lorem Co. starter from [Install](../getting-started/install.md), running on your machine. The steps in the admin are the same for every framework.
+
+1. Open `/admin` on your running site and sign in.
+2. On *Pages*, click *+ New page*.
+3. Enter `services` as the slug, the last part of the page's URL.
+
+Lorem Co. has one page type that editors can create, so the admin skips that question and opens the new page. On a site with several page types, it asks which one to use.
+
+## Edit it in the canvas
+
+The editor shows the page as the site renders it (the canvas) on the left, and the fields of whatever you select (the inspector) on the right.
+
+1. Click the hero at the top. It is marked *locked*: editors fill its fields but cannot move or remove it.
+2. In the inspector, change *Heading* to `Services`. The canvas updates as you type, and *Saved* appears at the top. Every change saves as a draft on its own; nothing is live yet.
+3. Click *Add section* under the hero and pick *Points*. It arrives filled with sample content, so the page never shows an empty section.
+4. Change the section's *Heading* to `What we do`. The toolbar on the selected section moves it up or down, duplicates it or removes it.
+
+The switch at the top right (next to the eye button) turns the canvas into the structure view: every section is a card with its title and a line of its content. Drag a card by its grip to reorder the page, click a card to edit its fields in the inspector, and switch back to see the page as the site renders it. As with every edit, the live site changes nothing until you publish.
+
+Every change can be taken back: Cmd+Z (Ctrl+Z on Windows and Linux), or the left arrow at the top right, undoes the last edit step by step, and Shift+Cmd+Z or the right arrow brings it back. A burst of typing is one step.
+
+To reuse a section on another page, pick *Copy* in the section's ⋯ menu (on its card in the structure view, or on its row in the Page Outline), and on the other page pick *Paste before* or *Paste after* in a card's or row's ⋯ menu, or *Paste* on a zone's heading in the structure view. The entry is greyed out when that page's zone does not allow the section.
+
+## Publish
+
+Click *Publish* at the top right. The status next to it changes from *Draft* to *Published*, and the eye button (*View live*) opens the page at `/services` on your site.
+
+A new page's title starts as its slug, so the browser tab says "services". To change it, go back to *Pages*, open the ⋯ menu at the end of the page's row and pick *Rename…*. The admin asks for the title and then the slug; enter `Services` and keep the slug. The title changes on the live page at once.
+
+## Why the editor could do that
+
+Everything the editor was allowed to do comes from the page type's schema. It is the same file in every framework; in an Astro project it lives under `src/components/pages/`.
+
+File: `components/pages/Page.schema.ts`
+
+```ts
+export const pageSchema = smoodly.schema.page({
+  name: "page",
+  title: "Page",
+  zones: {
+    hero: z.locked(pageHeroSchema),
+    body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
+  },
+  // …
+});
+```
+
+The page type's view decides where each zone renders:
+
+**Astro**
+
+File: `src/page-types/page.astro`
+
+```astro
+---
+import { Zone } from "smoodly/astro/components";
+// …
+---
+<Layout head={head} locale={page.locale} locales={page.locales}>
+  // …
+  <Zone of={zones.hero} />
+  <Zone of={zones.body} />
+</Layout>
+```
+
+The file's name pairs it with the schema named `page`.
+
+**Next.js**
+
+File: `components/pages/Page.tsx`
+
+```tsx
+import { smoodly, Zone, type Props } from "smoodly/react";
+// …
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+// …
+export const StandardPage = smoodly.page(pageSchema, PageView);
+```
+
+`smoodly.page()` pairs it with the schema.
+
+Each zone is a place on the page where editors work, and its policy sets how much they may change:
+
+| Name | Description |
+| --- | --- |
+| `z.locked(PageHero)` | Exactly one page hero. Editors fill its fields but cannot add, move or remove it. |
+| `z.freeform({ … })` | Any number of the listed sections, in any order. custom: true also offers the custom section, which editors lay out themselves. |
+
+The form in the inspector came from the Points section's own definition: one field for the heading and a list of one to six points. Change a field there and the form changes with it.
+
+Next, [Sections](../content-modeling/sections.md) shows how to write a section of your own, and [Zones and freedom](../content-modeling/zones.md) covers the three zone policies.