smoodly 0.0.60 → 0.0.61

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 rail 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.

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 Site 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.