smoodly 0.0.59 → 0.0.61

package/docs/frameworks/astro.md

@@ -0,0 +1,110 @@
+# Astro
+
+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.
+
+## The integration
+
+One line in `astro.config.ts` mounts Smoodly:
+
+File: `astro.config.ts`
+
+```ts
+import { defineConfig, memoryCache } from "astro/config";
+import node from "@astrojs/node";
+import smoodly from "smoodly/astro";
+// …
+  cache: { provider: memoryCache() },
+// …
+  site: process.env.SITE_URL,
+  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
+```
+
+`smoodly()` adds three routes and one middleware, so the project has no route file for any of them:
+
+- **The admin**, at `/admin`. To move it, pass `adminPath: "/studio"` here and set `admin: { path: "/studio" }` in the config; the admin says so when the two disagree.
+- **The preview address**, `/_smoodly/preview/<path>`, where the admin's canvas shows drafts.
+- **The pages**, at every address a page file of your own does not take.
+
+`config` names the Smoodly config file. `site` is the site's own address: canonical and hreflang links are absolute on it. Astro reads `astro.config.ts` before `.env`, so `process.env.SITE_URL` there sees only a value set in the shell or on the host; when it is empty, `smoodly()` sets `site` from `SITE_URL` in `.env`, and the build warns when nothing names one. The integration reads `.env` at `astro dev` and `astro build`, the `SMOODLY_` keys and `SITE_URL`; `npm start` reads it when it is there, and a deployed server takes the variables from its host.
+
+## Views by file name
+
+A view is an `.astro` file named after its schema's `name`. There is no list of views to keep:
+
+| Folder | What it renders, and its props |
+| --- | --- |
+| `src/page-types/<name>.astro` | A page type. It receives `page` (where the page sits: title, path, ancestors, children, locales), `zones` and `head`. |
+| `src/sections/<name>.astro` | A section. Its fields arrive flat, with `settings` and `styles`. |
+| `src/elements/<name>.astro` | An element inside richtext. Its fields and `settings`. |
+| `src/entry-pages/<collection>.astro` | The entry page of a collection with a `path`. It receives `entry` and `head`. |
+
+A schema with no view, and a view with no schema, are named once in the server log at the first request. A section is the same file in every framework apart from its view; [Sections](../content-modeling/sections.md) shows one.
+
+## Reads
+
+Smoodly's content reaches your views as Astro live collections. `src/live.config.ts` names one loader per collection, global item, the pages and the page tree:
+
+File: `src/live.config.ts`
+
+```ts
+import { defineLiveCollection } from "astro:content";
+import { entriesLoader, globalLoader, pageLoader, pageTreeLoader } from "smoodly/astro/content";
+// …
+export const collections = {
+  pages: defineLiveCollection({ loader: pageLoader() }),
+  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
+  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
+  // …
+  header: defineLiveCollection({ loader: globalLoader(header) }),
+  // …
+};
+```
+
+A view reads with `getLiveCollection` and `getLiveEntry` from `astro:content`:
+
+File: `src/page-types/articlesIndex.astro`
+
+```astro
+---
+import { getLiveCollection } from "astro:content";
+// …
+const { entries = [] } = await getLiveCollection("articles", { locale: page.locale });
+// …
+---
+```
+
+A collection takes `locale`, `where`, `order` and `limit`; `getLiveEntry("footer", { locale })` reads a global item, and `getLiveEntry("pages", { path, locale })` one page. In a preview the same reads return drafts. A global flagged `layout: true` is answered from the page's own read, so a layout's `getLiveEntry` calls cost no call ([Defining a global](../globals/defining.md#layout-globals)).
+
+## The cache
+
+Every read tags the response with what it read. Once the page is rendered, the response is stored whole, and a publish expires exactly the tags it touched. The first request after a publish reads from the service again; the rest are served from the cache. A 404, a draft and anything under the preview address are never stored.
+
+`memoryCache()` keeps pages in the server process's memory: one process, one cache. On Vercel, `cacheVercel()` stores them on the CDN instead; [Deploying](../getting-started/deploying.md) shows the swap.
+
+That is live mode, the default: pages render on demand and a publish is live at once. The other mode is static: with `output: "static"` in `astro.config`, every published page is built as a file, visitors need no function and no service, and editors press **Deploy** in the admin when their publishes should go live. Sections, schemas, the admin and the preview address are the same in both; [Deploying › Static](../getting-started/deploying.md#static) has the switch and the Deploy tile.
+
+## Preview
+
+The admin's canvas loads a page at the preview address. A signed cookie, set for the admin's session, opens it; without the cookie the address is closed. Reads there return drafts, and the editor's bridge is added to the response. A live address never shows a draft and carries no Smoodly script. There is no pill: drafts are seen in the admin only.
+
+## Images
+
+`Image` from `smoodly/astro/components` renders an `f.image()` value as plain HTML, an `<img>` or a `<picture>`:
+
+File: `src/sections/hero.astro`
+
+```astro
+{image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+The box keeps the crop's aspect and the `srcset` lists the cut's widths on Smoodly's media host, in AVIF or WebP, so Astro's image service, `/_image` and `image.remotePatterns` are not involved and no image setting is needed. `Head` opens a connection to the media host when the page shows an image. In static output the build writes every image its pages show into the output instead, so a static page loads its images from your own host. [Images and crops](../media/images-and-crops.md) has named crops and the `media` prop.
+
+## Languages
+
+`i18n` in `astro.config.ts` and `locales` in the config name the same set; the site refuses to start when they disagree, and the installer writes both. Smoodly follows Astro's rule for the default locale: no prefix unless `routing.prefixDefaultLocale` says so. `Head` writes one hreflang link per language the page is published in. [Locales and routing](../languages/locales.md) has the rest.
+
+## A page of your own
+
+A file under `src/pages/`, such as `src/pages/pricing.astro`, wins its address. A page an editor creates at `/pricing` saves and publishes, but visitors see your file, and the page editor says so. `src/pages/404.astro` is the site's "not found" page.
+
+To write content from a script, see [Content from code](../getting-started/content-from-code.md).

package/docs/frameworks/nextjs.md

@@ -0,0 +1,147 @@
+# Next.js
+
+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.
+
+## The route file
+
+One file under `app/(site)` serves every CMS URL, and it needs no editing:
+
+File: `app/(site)/[[...path]]/page.tsx`
+
+```tsx
+import { renderSmoodlyPath, smoodlyMetadata } from "@/smoodly/server";
+// …
+export function generateStaticParams() {
+  return [];
+}
+// …
+export default async function Page({ params, searchParams }: { params: Params; searchParams: SearchParams }) {
+  return renderSmoodlyPath((await params).path ?? [], { searchParams });
+}
+```
+
+`renderSmoodlyPath` resolves the URL path to a page, a path in the tree or an entry, and renders it with its page type or entry page; no segments is the home. A page or entry that does not exist, or is not published, is a 404. A multilingual site has the same file under `app/[locale]` and passes the language along.
+
+`generateStaticParams` returning nothing is what makes the page cacheable: Next builds no page ahead, renders each address on its first visit and keeps the result until a publish expires it ([What happens on a request](#what-happens-on-a-request)). Keep the export; without it Next renders the route on every request.
+
+A route file of your own beside this one, `app/(site)/pricing/page.tsx`, wins for that exact URL by Next's precedence; deeper URLs still reach the catch-all. A page an editor creates at `/pricing` saves and publishes, but visitors see your route instead. The page editor says so: when its canvas cannot show the page, a warning names the cause, with a line starting "For your developer:" that says what to change. A home of your own is the same file: return your component when `path` is empty.
+
+A page under this route may not read cookies, headers or search params, and neither may a section or the layout above it: Next decided the page is static, so a dynamic API inside the render answers a 500 in production, and `next dev` does not show it. A page that needs them is its own route file, which renders on every request. The same goes for `connection()`: a snippet from before 0.0.50 that awaits it in `smoodly/server.ts` turns every page into that 500. The file passes `searchParams` on to `renderSmoodlyPath`, which reads them inside draft mode only: the canvas asks for the page with a `smoodly-editor` parameter, and without it the page renders with no editor bridge, so nothing in the canvas can be selected. The page editor names that case too.
+
+## The server seam
+
+`smoodly/server.ts` builds everything the routes and the admin share, once per server, and only when first used, so a build with no environment still succeeds:
+
+File: `smoodly/server.ts`
+
+```ts
+  const site = createSmoodlyApi({ ...apiEnv(), config });
+  // …
+  const renderer = createPageRenderer({ site, ...views(), href });
+  // …
+  const q = createSmoodlyQueries({ site, collections, globals });
+```
+
+`createSmoodlyApi` reads your content over Smoodly's API, one call per read, and computes everything else the renderer needs from the config, so the two cannot disagree. Your site opens no database. `views()` hands the renderer your components from `smoodly/views.ts`, checked against the config's schemas the first time the site renders.
+
+The live site reads two variables: `SMOODLY_SPACE_ID`, the space your content lives in, and `SMOODLY_SECRET_KEY`. The admin needs the same two: it learns where editors sign in from Smoodly's API. `SITE_URL` is the address the build pushes to the space with the schema (`prebuild: "smoodly push"` in `package.json`). [Keys](../getting-started/keys.md) explains them. It exports the two functions the routes call, `q` for [queries](../collections/queries.md), and `href`, the one seam that turns a language-relative path into a site URL.
+
+The file also builds `content()`, which scripts write content through ([Content from code](../getting-started/content-from-code.md)). It takes it from `smoodly/admin` and posts to the same API with the secret key:
+
+File: `smoodly/server.ts`
+
+```ts
+  return createSmoodlyContent({ config, href, transport: apiTransport(apiEnv()) });
+```
+
+## The admin
+
+The admin is one route. The `smoodly` package ships it prebuilt, so your app compiles none of it:
+
+File: `app/(smoodly)/admin/[[...segments]]/route.ts`
+
+```ts
+import { createAdminRoute } from "smoodly/next";
+import { config } from "@/smoodly/config";
+import { adminDeps, presence } from "@/smoodly/server";
+
+export const { GET, POST } = createAdminRoute(() => ({ config, ...adminDeps(), presence }));
+```
+
+`GET` serves the admin's page and the script and fonts it loads. The admin's operations run in Smoodly's API, which accepts them from the addresses your builds pushed and checks the editor's session against the space's members; the browser never holds a write key. `POST` takes two calls only: the API's call after a publish naming the cache tags to expire, which must be signed with the API's own key and less than a minute old, and the editor's browser turning on draft mode with a grant the API signed, accepted from the site's own address only.
+
+`presence` is where the browser opens the editing-presence connection (Smoodly's API and your space), public values read from `smoodly/server.ts` per request; where editors sign in, the page asks Smoodly's API. Leave `presence` out and the admin works the same, minus [who is editing what](../getting-started/working-together.md).
+
+The route folder under `app/(smoodly)` must match `admin.path` in the config; [The admin](https://smoodly.io/docs/getting-started/admin) covers moving it. The admin's page has no layout, so the site's layout never wraps it.
+
+## Content in the browser
+
+The publishable key is public and reads published content only, so a component that runs in the browser could read with it. The starter's way is a route in your own app that reads through `q` on the server: the browser holds no key, and the route decides what leaves. A component that needs entries, a search box or a "load more" button, asks that route:
+
+File: `app/api/articles/route.ts`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function GET(request: Request) {
+  const locale = new URL(request.url).searchParams.get("locale") ?? undefined;
+  const items = await q().getEntries("articles", { locale, limit: 12 });
+  return Response.json(items.map((item) => ({ id: item.id, path: item.path, title: item.fields.title })));
+}
+```
+
+Return only what the browser should see: the route decides, not the service. Published content only leaves the route, because a request outside the editor's draft mode reads published rows.
+
+## What happens on a request
+
+A CMS route is never built ahead: `next build` reads nothing from the service and needs no keys. Each address renders on its first visit, outside draft mode, and Next keeps the page in its route cache, which Vercel serves from its CDN without running your function. The render reads under tags that name the page or entry by id, the layout's global items by name, and, for a 404, a redirect or a code-owned page, one tag for every address. Publishing, unpublishing, renaming or deleting expires exactly those tags at once; the next visit renders fresh. Nothing expires on a timer. One consequence: a renamed page's old address answers its permanent redirect without the request's query string, since the cached answer cannot read it.
+
+Draft mode is Next's way of rendering unpublished content for one browser. The editor turns it on for the editor's browser by posting a grant from Smoodly's API to the admin route, then loads the site's real URL in the canvas with `/~editor` after it, which mounts the bridge the canvas talks to. In draft mode every read returns the live draft rows, and *History* renders an old version at the page's URL followed by `/~version~` and the version's id. The flags ride the path, not the query, because Vercel passes a cached route only its own parameters, even in draft mode. The public site honors neither: outside draft mode such an address is not found.
+
+## Preview mode
+
+Opening the page editor turns on draft mode for that browser. Every page Smoodly renders then shows a floating pill, outside the editor's canvas: *Preview · unpublished changes*, with *Exit preview*. Editors can drag it to the left, center or right, move it with the arrow keys, or hide it until the next reload. Outside draft mode the page's HTML has no trace of it, and no page loads Smoodly's editor code.
+
+Exit goes to `/api/preview?disable`, the route every starter ships:
+
+File: `app/api/preview/route.ts`
+
+```ts
+export { previewRoute as GET } from "smoodly/next";
+```
+
+If you moved that route, tell the renderer with the `previewRoute` option of `createPageRenderer`, like `previewRoute: "/my/preview"`.
+
+A page you render yourself, without `renderSmoodlyPath`, can show the pill too:
+
+File: `app/pricing/page.tsx`
+
+```tsx
+import { draftMode } from "next/headers";
+import { previewPill } from "smoodly/next";
+
+export default async function Pricing() {
+  const { isEnabled } = await draftMode();
+  return <main>{isEnabled && previewPill()}</main>;
+}
+```
+
+The pill loads as a small script of its own, in preview only.
+
+## Cache Components
+
+Leave `cacheComponents` off in `next.config.ts`. Next 16's Cache Components mode brings the `"use cache"` directive and partial prerendering for every route: a static shell goes out first and the rest streams in. Smoodly's catch-all serves paths that are unknown at build time, so under that mode it is always sent from a shell that has already committed status 200. A page that doesn't exist then answers 200 with a `noindex` tag instead of 404, and a redirect answers 200 instead of 308, both of which search engines treat worse. No route can opt out of the mode, so Smoodly does not support it.
+
+You keep `unstable_cache` and `revalidateTag`, and every page and entry is already cached under its own tag. What you give up is `"use cache"` in your own code.
+
+If the mode is on, the server log says so once, at the first page render:
+
+```text
+smoodly: Next's cacheComponents is on, and Smoodly does not support it — …
+```
+
+## Images
+
+`SmoodlyImage` from `smoodly/image` renders an `f.image()` value as a plain `<img>`, or a `<picture>` for named crops, over cuts from Smoodly's media host in AVIF or WebP. It does not use `next/image`, so `next.config.ts` holds no `images` setting and Vercel's image optimization is never billed. The component calls React's `preconnect` for the media host, which React places in the head. [Images and crops](../media/images-and-crops.md) has the rest.
+
+Next, [Upgrading](../reference/upgrading.md) says what a new version asks of your code.

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.