smoodly 0.0.60 → 0.0.62

package/docs/languages/language-switcher.md

@@ -0,0 +1,103 @@
+# Language switcher and hreflang
+
+Every page and entry knows its own address in every language. A language switcher links from that map, and the site's hreflang tags come from the same one.
+
+## The language map
+
+A page type's view gets `page.locales`, and an entry page gets `locales`: one key per supported language. The value is the page's `slug`, `path` and `url` in that language, or `null` where the page does not exist or is not published there. In the editor's canvas an unpublished translation still counts; on the public site it never links.
+
+A switcher links to the same page where it exists, and to that language's home otherwise. The blank starter does it in one component:
+
+**Astro**
+
+File: `src/components/LocaleNav.astro`
+
+```astro
+---
+import { href } from "smoodly/astro/runtime";
+// …
+const codes = Object.keys(locales);
+---
+{codes.length > 1 && (
+  <nav class="container locales" aria-label="Language">
+    {codes.map((code) => <a href={href(locales[code]?.path ?? "/", code)} aria-current={code === locale ? "page" : undefined}>{code}</a>)}
+  </nav>
+)}
+```
+
+`href` from `smoodly/astro/runtime` adds the language prefix the site uses. With one language the map has one key and the component renders nothing, which is why the single-language scaffold shares the file.
+
+**Next.js**
+
+File: `components/LocaleNav.tsx`
+
+```tsx
+export function LocaleNav({ locale, locales }: { locale: string; locales: Record<string, LocaleAlternate | null> }) {
+  const codes = Object.keys(locales);
+  if (codes.length < 2) return null;
+  return (
+    <nav className="container locales" aria-label="Language">
+      {codes.map((code) => (
+        <a key={code} href={href(locales[code]?.path ?? "/", code)} aria-current={code === locale ? "page" : undefined}>{code}</a>
+      ))}
+    </nav>
+  );
+}
+```
+
+`href` from `smoodly/server.ts` adds the language prefix the site uses. With one language the map has one key and the component renders nothing, which is why the single-language scaffold shares the file.
+
+## Why the page decides it
+
+The links must land on the same page in the other language, so they come from the page on screen.
+
+**Astro**
+
+Every page view passes its own `locales` map to the layout, and the layout renders the header with the links. Astro renders the page before its layout, so the layout knows which page is on screen. [Header and footer](../globals/header-and-footer.md) has the file.
+
+**Next.js**
+
+The switcher lives with the page, not in the layout, because a layout cannot know which page is on screen and the links must land on the same page in the other language. The Lorem Co. starter renders its header, links included, from every page type through `PageFrame`:
+
+File: `components/PageFrame.tsx`
+
+```tsx
+  const header = await q().getGlobal("header", { locale });
+  const codes = Object.keys(locales);
+  const links: LocaleLink[] | undefined = codes.length > 1
+    ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+    : undefined;
+```
+
+[Header and footer](../globals/header-and-footer.md) has the whole file.
+
+## hreflang
+
+**Astro**
+
+`Head` from `smoodly/astro/components` writes one hreflang link per language where the page is published, from the same map the switcher reads. A single-language site gets none, only the page's canonical link. The links are absolute on `site` in `astro.config.ts`, which the starter reads from `SITE_URL`: set it to the site's real address, as [SEO](../pages/seo.md) explains.
+
+File: `src/layouts/Layout.astro`
+
+```astro
+    <Head of={head} fallback="Lorem Co." />
+```
+
+The visitor picks a language through the switcher; nothing redirects by browser language.
+
+**Next.js**
+
+`smoodlyMetadata` in the route files emits `alternates.languages` for every page and entry, from the same map the switcher reads: only the languages where the page has a URL, each through `href`. A single-language site emits none, only the page's canonical link. The links are absolute on the host in `SITE_URL`, which the installer sets to `http://localhost:3000`: set it to the site's real address, as [SEO](../pages/seo.md) explains.
+
+next-intl could derive hreflang and redirect visitors by browser language on its own, and the scaffold turns both off:
+
+File: `i18n/routing.ts`
+
+```ts
+  alternateLinks: false,
+  localeDetection: false,
+```
+
+Both assume a page has the same slug in every language. Once slugs translate, a derived hreflang points at a URL that does not exist, and a detection redirect keeps the English segments under `/fi/` and lands on a 404. So the visitor picks a language through the switcher, and the tags come from the content.
+
+Next, [Frameworks](../frameworks/astro.md).

package/docs/languages/locales.md

@@ -0,0 +1,119 @@
+# Locales and routing
+
+A site publishes in one language or several. This page covers declaring the languages, how each gets its own URLs, and what editors see when a page exists in some languages and not others.
+
+## Declaring the languages
+
+The config names the default language and the supported set. A single-language site declares one:
+
+File: `smoodly/config.ts`
+
+```ts
+  locales: { default: "en", supported: ["en"] },
+```
+
+**Astro**
+
+A multilingual site, which the installer scaffolds when you answer yes to *multilingual*, names the set twice: in `i18n` in `astro.config.ts`, for Astro's routing, and in the config. The installer writes both, and the site refuses to start when they disagree:
+
+File: `astro.config.ts`
+
+```ts
+  i18n: { locales: ["en", "fi"], defaultLocale: "en" },
+```
+
+File: `src/smoodly/config.ts`
+
+```ts
+  locales: { default: "en", supported: ["en", "fi"] },
+```
+
+**Next.js**
+
+A multilingual site, which the installer scaffolds when you answer yes to *multilingual*, keeps the set in one place for [next-intl](https://next-intl.dev) and imports it into the config:
+
+File: `i18n/routing.ts`
+
+```ts
+export const routing = defineRouting({
+  locales: ["en", "fi"],
+  defaultLocale: "en",
+  localePrefix: "as-needed",
+  alternateLinks: false,
+  localeDetection: false,
+});
+```
+
+File: `smoodly/config.ts`
+
+```ts
+  locales: { default: routing.defaultLocale, supported: [...routing.locales] },
+```
+
+The config cannot go the other way round: the proxy that routes languages runs in the edge runtime and cannot load the registry.
+
+A locale code is a plain string such as `en`, `fi`, `en-US` or `zh-Hant`. Adding a language later is a config change; every fixed page and global gets a row in it on the next admin load.
+
+## One URL per language
+
+Every page and entry has its own slug in each language it exists in, so URLs translate whole: `/company/about-us` in English can be `/fi/yritys/tietoa` in Finnish. Fixed pages and collection paths take a per-language map in code; the starter's Articles index is `posts` in English and `artikkelit` in Finnish.
+
+**Astro**
+
+The language prefix is Astro's: the default language has none, unless `routing: { prefixDefaultLocale: true }` in `i18n` says so, and the others get theirs. Smoodly follows the same rule. `href` from `smoodly/astro/runtime` turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
+
+File: `src/layouts/Layout.astro`
+
+```astro
+---
+// …
+  ? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
+// …
+---
+```
+
+On a single-language site it returns the path unchanged. The admin sits outside the language prefix. A site that prefixes the default language says so in the config too, with `routing: { prefixDefaultLocale: true }`, so the links Smoodly builds for editors carry the prefix; the site refuses to start when the two disagree.
+
+**Next.js**
+
+The language prefix is next-intl's: with `as-needed`, the default language has none and the others get theirs. Smoodly never adds a prefix itself. One function in `smoodly/server.ts` turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
+
+File: `smoodly/server.ts`
+
+```ts
+export const href = (path: string, locale: string) => getPathname({ locale, href: path });
+```
+
+On a single-language site the same function returns the path unchanged. The proxy skips `/admin`, which sits outside the language segment and has no prefix. A site whose `localePrefix` is `always` says so in the config too, with `routing: { prefixDefaultLocale: true }`, so the links Smoodly builds for editors carry the prefix.
+
+## Pages that exist in some languages
+
+A page or an entry exists in the languages it has been added to, and nothing falls back: a page that exists only in Finnish is a 404 in English. The pages list and every collection list have a language picker, and a page missing from the selected language shows dimmed, with *Add en* in its menu.
+
+Adding a language copies the content on screen as the first draft in the new language, for the editor to translate. A page can be added to a language only when its parent exists there, and removed from one only while no child page has it. Fixed pages, collection mounts and globals exist in every language from the start and never lose one.
+
+Publishing is per language. A page published in English and edited in Finnish is *Published* in one and *Unpublished changes* in the other, and each language has its own history.
+
+## One order, or one per language
+
+Editors drag pages into an order in the page tree, and entries in a collection ordered `"manual"`. By default that order is shared: a drag made in any language reorders every language.
+
+Add `order: "perLocale"` to `locales` in the config, next to `default` and `supported`, and each language keeps its own. A drag then reorders only the language selected in the list, and the page tree, a page's `children` and a manual collection's queries return the order of the language they are read in. Until an editor drags, every language has the order it had before.
+
+Only the order differs. A page still sits under the same parent in every language; moved under a new parent, it lands where it was dropped in the selected language and last in the others. A page added to a language starts where the language it was copied from has it.
+
+Setting `order` back to `"shared"` (or removing it) keeps each language's order as it is until the next drag among the same siblings, which every language then takes.
+
+## The site's own words
+
+Labels that are not content, such as *All articles* or *min read*, are yours to translate.
+
+**Astro**
+
+The starter keeps them in `src/messages/<locale>.json` and reads them through `src/strings.ts`, with no library behind it. A language without its own file shows the English words.
+
+**Next.js**
+
+The multilingual starter keeps them in `messages/<locale>.json` and reads them through next-intl; the single-language starter ships the English map with no library behind it.
+
+Next, [Localized fields](../languages/localized-fields.md).

package/docs/languages/localized-fields.md

@@ -0,0 +1,61 @@
+# Localized fields
+
+On an entry or a global, a field is shared across languages unless it chains .localized(). This page covers the rule, where it applies and what it means for queries.
+
+## The rule
+
+`.localized()` gives a field its own value per language. Without it, one value serves every language:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  order: "manual",
+  fields: {
+    name: f.text(),
+    role: f.text().localized(),
+  },
+});
+```
+
+A person's name is the same in Finnish and English; the role is translated. Shared is the default because most of an entry is: the photo, the date, the author, the price. The starter's articles localize the title, the excerpt, the body and the tags, and share the image, the date and the author.
+
+A global follows the same rule. The contact details share the email and localize the address; the header shares the brand and localizes the navigation.
+
+## Where it applies
+
+| Place | Effect of .localized() |
+| --- | --- |
+| `Collection and global fields` | Decides storage: the field gets a value per language. |
+| `slug` | Always per language, with or without .localized(): each language has its own URL. |
+| `Lists and objects` | Localizes the whole value. Inside an item or a subfield it is a type error; localize the top-level field that holds it, for a list of objects the list. |
+| `Settings` | Never. A layout choice is the same in every language, and .localized() on a setting throws. |
+| `Page fields` | Not needed: page fields are stored per language already. |
+| `Section fields on a page` | No effect on storage. A page's content is per language as a whole. |
+
+A page's whole tree is per language: adding a language copies the tree, and from then on the two are edited apart. That is why a page's sections need no `.localized()`, and why a change made in English is not mirrored in Finnish.
+
+## In the form
+
+On a multilingual site the entry and Globals forms mark every shared field with a globe-off icon, so an editor translating knows which values will change in every language at once. Adding a language copies every field as the first draft, shared and localized alike; the shared ones then stay in step by themselves.
+
+## Changing it later
+
+Adding or removing `.localized()` on a field that already holds content moves nothing in storage:
+
+- **Turning it on**: the value saved while the field was shared stays as every language's fallback. Each language shows it until an editor saves that language, which gives the language its own value. Until then, the form's notice says the value is still shared.
+- **Turning it off**: each language keeps showing its own value until it is saved. The first save in a language makes that language's value the one every language shows, and the form warns about it before the save.
+
+[When the schema changes](../content-modeling/changing-schemas.md) covers the other changes and the *Content health* page that lists them.
+
+## In code
+
+Reads merge the shared and the localized values for the language asked, so a view sees one flat set of fields. Two things follow from the split:
+
+- A `where` filter in a [query](../collections/queries.md) matches shared fields only. Filtering on a localized field or on the slug is refused, because those live per language.
+- A collection's `order.by` must be a shared field, because the order is one list for every language.
+
+Next, [Language switcher and hreflang](../languages/language-switcher.md).

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

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

package/docs/media/library.md

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

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

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

package/docs/pages/page-tree.md

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

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

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