smoodly 0.0.60 → 0.0.61

package/dist/api-client.js

@@ -3,7 +3,7 @@
 // config exactly as the service's site computes them (site.ts siteStatics), so a cache key never disagrees across
 // the wire. A document's tags ride on the hit (SiteHit.tags), where the read layer takes them.
 import { countRead } from "./read-counter.js";
-import { pushBody, pushSchema } from "./push.js";
+import { pushBody, pushLine, pushSchema } from "./push.js";
 import { siteOptions, siteStatics, } from "./site.js";
 /** The content API refused a read: its status, its code (`unauthorized`, `not_found`, `validation`, `internal`) and its message. */
 export class SmoodlyApiError extends Error {
@@ -24,9 +24,11 @@ export function createSmoodlyApi(options) {
     const localeOf = (o) => o?.locale ?? statics.locales.default;
     const env = typeof process === "undefined" ? {} : process.env;
     const push = options.push ?? (env.NODE_ENV === "development" ? pushBody(options.config, env, "live") : false);
-    /** One push per client, awaited by every call until it settles; its failure is logged, never thrown. */
+    /** One push per client, awaited by every call until it settles; its failure is logged, never thrown. What landed is
+     *  said once, with the kind of space it reached (spec 2026-11-13 production first and the preview copy §7): a dev
+     *  server pushes its schema to the space it reads, so the developer must see when that space is production. */
     let pushed = null;
-    const pushOnce = (body) => (pushed ?? (pushed = pushSchema({ apiUrl, spaceId: options.spaceId, key: options.key, fetch: doFetch }, body).then(() => undefined, (e) => console.error(`smoodly: the schema push failed — ${e instanceof Error ? e.message : String(e)}; the site runs against the schema the space has.`))));
+    const pushOnce = (body) => (pushed ?? (pushed = pushSchema({ apiUrl, spaceId: options.spaceId, key: options.key, fetch: doFetch }, body).then((result) => { const line = pushLine(options.spaceId, result); console.log(`smoodly: ${line[0].toLowerCase()}${line.slice(1)}`); }, (e) => console.error(`smoodly: the schema push failed — ${e instanceof Error ? e.message : String(e)}; the site runs against the schema the space has.`))));
     async function call(path, params) {
         if (push)
             await pushOnce(push);

package/dist/astro/index.js

@@ -11,7 +11,7 @@ import { apiTransport, createSmoodlyContent } from "../content/content-api.js";
 import { markerJson, MARKER_PATH } from "../deploy-state.js";
 import { DEFAULT_API_URL, apiEnv, siteUrl } from "../env.js";
 import { createSmoodlyApi } from "../api-client.js";
-import { pushBody, pushSchema } from "../push.js";
+import { pushBody, pushLine, pushSchema } from "../push.js";
 import { loadSmoodlyEnv } from "./env-files.js";
 import { astroRouting, localeHref } from "./locale-paths.js";
 import { PREVIEW_BASE } from "./preview.js";
@@ -159,8 +159,8 @@ export default function smoodly(options = {}) {
                 astroRouting(i18n, loaded.locales, loaded.routing);
                 try {
                     const env = apiEnv(process.env);
-                    const { version, changed } = await pushSchema(env, pushBody(loaded, process.env, output === "static" ? "static" : "live"));
-                    logger.info(changed ? `smoodly: pushed schema version ${version} to ${env.spaceId}.` : `smoodly: schema unchanged (version ${version}).`);
+                    const line = pushLine(env.spaceId, await pushSchema(env, pushBody(loaded, process.env, output === "static" ? "static" : "live")));
+                    logger.info(`smoodly: ${line[0].toLowerCase()}${line.slice(1)}`);
                 }
                 catch (e) {
                     logger.warn(`smoodly: the schema push failed — ${e instanceof Error ? e.message : String(e)}; the site runs against the schema the space has.`);

package/dist/cli/push.js

@@ -4,7 +4,7 @@
 // except when npm runs the command as a build's `prebuild`: a push never fails a build (the spec's rule), so there it
 // says what failed and exits 0, and the site runs against the schema the space has.
 import { apiEnv } from "../env.js";
-import { pushBody, pushSchema } from "../push.js";
+import { pushBody, pushLine, pushSchema } from "../push.js";
 import { loadAppEnv } from "./app-env.js";
 import { loadConfig } from "./load-config.js";
 export async function runPush(_args, out, deps = {}) {
@@ -15,8 +15,7 @@ export async function runPush(_args, out, deps = {}) {
         const config = await loadConfig(cwd);
         const { apiUrl, spaceId, key } = apiEnv(env);
         const body = pushBody(config, env, env.SMOODLY_STATIC === "1" ? "static" : "live");
-        const { version, changed } = await pushSchema({ apiUrl, spaceId, key, fetch: deps.fetch }, body);
-        out(changed ? `Pushed schema version ${version} to ${spaceId}.` : `Schema unchanged (version ${version}).`);
+        out(pushLine(spaceId, await pushSchema({ apiUrl, spaceId, key, fetch: deps.fetch }, body)));
         return 0;
     }
     catch (e) {

package/dist/env.js

@@ -11,8 +11,9 @@ const ADMIN_NEEDS = SITE_NEEDS;
 const NEEDS = { site: SITE_NEEDS, admin: ADMIN_NEEDS };
 const isHttp = (v) => /^https?:\/\/[^/\s]+/.test(v);
 const DEPLOYING = "https://smoodly.io/docs/getting-started/deploying";
-/** A Smoodly key: its kind, the space it belongs to, the random part and the stamp (spec 2026-10-16 the control plane §1). */
-const SMOODLY_KEY = (kind) => new RegExp(`^${kind}_sp_(eu_)?[a-z2-7]{20}_[a-z2-7]{32}_[a-z2-7]{16}$`);
+/** A Smoodly key: its kind, the space it belongs to (a preview space's id carries `preview_`, spec 2026-11-13 production
+ *  first and the preview copy §8), the random part and the stamp (spec 2026-10-16 the control plane §1). */
+const SMOODLY_KEY = (kind) => new RegExp(`^${kind}_sp_(eu_)?(preview_)?[a-z2-7]{20}_[a-z2-7]{32}_[a-z2-7]{16}$`);
 /** The live site and its admin read over the API with its address, the space and the secret key (spec 2026-10-16 the
  *  control plane §5). A key in the wrong variable or of no known form is named here, not by a failed read later. */
 export function resolveSmoodlyEnv(env, need = "site") {

package/dist/push.d.ts

@@ -23,6 +23,13 @@ export type PushApi = {
     key: string;
     fetch?: typeof fetch;
 };
+/** What a push says when it landed: the version, and which kind of space it reached, read from the id (spec 2026-11-13
+ *  production first and the preview copy §7), so a developer who meant the preview space sees at once that the machine
+ *  reads production. */
+export declare function pushLine(spaceId: string, result: {
+    version: number;
+    changed: boolean;
+}): string;
 /** One push: the space's version of the registry, and whether this push changed it. A refusal throws `SmoodlyApiError`. */
 export declare function pushSchema(api: PushApi, body: PushBody): Promise<{
     version: number;

package/dist/push.js

@@ -2,6 +2,7 @@
 // delivery mode, and the package version, at `POST /v1/spaces/:space/schema` under the secret key. `smoodly push`, Astro's
 // build hook, the Next templates' prebuild and the API client in development all send this one body. The space keeps
 // the registry, versions it and purges its pages when it changed; a failed push never fails a build.
+import { spaceKind } from "./space-kind.js";
 import { SmoodlyApiError } from "./api-client.js";
 import { serializeRegistry } from "./registry-json.js";
 import { SMOODLY_VERSION } from "./version.js";
@@ -29,6 +30,13 @@ export function siteInfo(config, env, mode) {
 export function pushBody(config, env, mode) {
     return { registry: serializeRegistry(config), site: siteInfo(config, env, mode), package: SMOODLY_VERSION };
 }
+/** What a push says when it landed: the version, and which kind of space it reached, read from the id (spec 2026-11-13
+ *  production first and the preview copy §7), so a developer who meant the preview space sees at once that the machine
+ *  reads production. */
+export function pushLine(spaceId, result) {
+    const where = `the ${spaceKind(spaceId)} space ${spaceId}`;
+    return result.changed ? `Pushed schema version ${result.version} to ${where}.` : `Schema unchanged (version ${result.version}) in ${where}.`;
+}
 /** One push: the space's version of the registry, and whether this push changed it. A refusal throws `SmoodlyApiError`. */
 export async function pushSchema(api, body) {
     const apiUrl = api.apiUrl.replace(/\/+$/, "");

package/dist/space-kind.d.ts

@@ -0,0 +1,2 @@
+export type SpaceKind = "production" | "preview";
+export declare const spaceKind: (spaceId: string) => SpaceKind;

package/dist/space-kind.js

@@ -0,0 +1 @@
+export const spaceKind = (spaceId) => (/^sp_(eu_)?preview_/.test(spaceId) ? "preview" : "production");

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SMOODLY_VERSION = "0.0.60";
+export declare const SMOODLY_VERSION = "0.0.61";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/write-version.mjs from package.json — do not edit.
-export const SMOODLY_VERSION = "0.0.60";
+export const SMOODLY_VERSION = "0.0.61";

package/docs/collections/defining.md

@@ -0,0 +1,57 @@
+# Defining a collection
+
+A collection is a content type with a fixed shape and many entries: posts, people, products. You declare its fields once; editors get a list, a form and publishing for it.
+
+## The schema
+
+`smoodly.collection()` takes a name, a title and the fields of one entry:
+
+File: `smoodly/collections.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+// …
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  order: "manual",
+  fields: {
+    name: f.text(),
+    role: f.text().localized(),
+  },
+});
+```
+
+| Name | Description |
+| --- | --- |
+| `name` | What references and queries use. Keep it stable once entries exist. global, asset and media are reserved. |
+| `title` | The label in the admin's rail and list. |
+| `titleField` | The field whose value names an entry in lists and pickers. Without one, or while it is empty, an entry reads Untitled. |
+| `fields` | Any builders. A field named slug gives entries a URL part; .localized() gives a field a value per language. |
+| `path` | Serves each entry at its own URL under this segment. See Entry pages. |
+| `order` | How the list and queries sort. See Ordering. |
+| `admin.showInNav` | true gives the collection its own item in the admin's main navigation, after Pages, instead of a line in the Collections menu. Default false. |
+| `seo` | Adds the SEO & Social panel to the entry form; `{ description, image }` names the fields that fill an empty description and social image. See SEO. |
+
+Register the export in the `collections` list of `smoodly/collections.ts`, which the config registers. Every collection stores its entries in the same tables, so the admin lists a new one at once. Smoodly's service indexes the new collection's lists itself: there is nothing to migrate.
+
+## Entries in the admin
+
+The *Collections* item in the admin's rail opens a menu of every collection. A collection editors open all day can sit on the rail itself: add `admin: { showInNav: true }` to its schema and it appears after *Pages* under its title, and leaves the menu. A collection's list shows its entries with their title, status and when they changed, 20 to a page; *Previous* and *Next* under the rows move through a longer list, and *Per page* shows 100 or 500 instead, a choice the browser remembers. The box above the rows filters by the collection's `titleField`: it finds the entries whose title holds the text, in any language, and searches the whole collection, not the page on screen. A collection without a `titleField` has no filter. While a filter is on, a hand-ordered list does not drag. *+ New entry* creates an empty draft in the selected language and opens the form at once. The form autosaves, and carries the same *Publish* control as a page, so an entry is published per language like a page. *History* and *Discard changes* work the same way.
+
+An entry cannot be deleted while a page, a section or another entry references it. The message says how many, and the media library shows the same for assets.
+
+## Shared and localized
+
+A field's value is shared across languages unless it chains `.localized()`. In the starter's people, a person's name is the same everywhere and the role is translated. The form marks shared fields with a globe-off icon on a multilingual site, and the slug is always per language. [Localized fields](../languages/localized-fields.md) has the rules.
+
+## Where entries appear
+
+Three ways, which the next pages cover:
+
+- **Referenced** from a section or another entry with `f.ref()` or `f.refList()`: the starter's *People* section picks team members by hand. See [Reference and tags](../fields/reference-and-tags.md).
+- **At their own URL**, when the collection has a `path` and an [entry page](../collections/entry-pages.md).
+- **Queried** from your code with `q()`, for an index grid or a related list. See [Queries](../collections/queries.md).
+
+Next, [Entry pages](../collections/entry-pages.md).

package/docs/collections/entry-pages.md

@@ -0,0 +1,168 @@
+# Entry pages
+
+Give a collection a path and each entry gets its own URL. The entry page is the component that renders one entry there.
+
+## The path
+
+`path` on a collection is the URL segment its entries live under. The starter's articles sit at `/posts/<slug>` in English and `/artikkelit/<slug>` in Finnish:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  order: { by: "date", direction: "desc" },
+  fields: {
+    title: f.text().localized(),
+    image: f.image({ aspect: "3:2" }),
+    date: f.date(),
+    author: f.ref(() => people),
+    slug: f.slug({ from: "title" }),
+    excerpt: f.text().localized(),
+    // …
+  },
+});
+```
+
+A string applies to every language; an object names the segment per language. The collection needs a field named `slug` for the entry's own part. A collection without a `path` has no URLs: its entries appear only through references and queries.
+
+The path shows in the page tree as a mount, so editors see where the entries live. Pages cannot be created under it.
+
+## A nested path
+
+A path may have several parts. The starter's news sits under the company, at `/company/news/<slug>` and `/yritys/uutiset/<slug>` in Finnish:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const news = smoodly.collection({
+  name: "news",
+  title: "News",
+  titleField: "title",
+  path: { en: "company/news", fi: "yritys/uutiset" },
+  order: { by: "date", direction: "desc" },
+  // …
+});
+```
+
+Your code owns the whole address, not just its last part. The *Company* page at `/company` is an editor's page, or no page at all: renaming or moving it never moves the news, because published URLs should not change with an easy rename in the admin. The page tree lists the collection at the root with its full URL, and editors cannot put a page on `/company/news` or under it.
+
+Each part follows the slug rule. A language the map leaves out takes the default language's address.
+
+Change the path in code and the URLs of the index page and every entry change when the deploy goes live: Smoodly stores only each entry's own part, never the address. The old URLs stop working, so add a redirect in `next.config.ts` for them, as [Paths and slugs](../pages/paths-and-slugs.md#redirects) shows.
+
+## The entry page
+
+**Astro**
+
+A collection with a `path` needs an entry page: `src/entry-pages/<collection>.astro`, named after the collection. It receives `entry` and `head`:
+
+File: `src/entry-pages/articles.astro`
+
+```astro
+---
+// …
+const { entry, head } = Astro.props;
+const { locale, locales } = entry;
+// …
+const a = entry.fields;
+// …
+const { entries: newest = [] } = await getLiveCollection("articles", { locale, limit: 4 });
+// …
+---
+<Layout head={head} locale={locale} locales={locales}>
+  <article class="container article">
+    // …
+      <h1 class="article__title">{a.title}</h1>
+    // …
+    {a.image && <Image image={a.image} aspect="21:9" class="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+    <div class="article__body prose prose--lead"><RichText doc={a.body} sizes="(min-width: 900px) 720px, 100vw" /></div>
+  </article>
+  // …
+</Layout>
+```
+
+The entry's `fields` are resolved: images are ready for `Image`, and a reference such as `author` is `{ id, path, fields }`, the person's fields under `fields`. Beside `fields` the entry carries its `id`, `path`, `locale`, the language rendered, and `locales`, which maps every language to the entry's address there, for a language switcher, and `seo` when the collection turns [SEO](../pages/seo.md#seo-for-entries) on. `head` goes to the layout's `Head`.
+
+There is nothing to register: the file is the entry page. A collection with a `path` and no file is named in the server log at the first request, and its entries answer 404.
+
+**Next.js**
+
+A collection with a `path` needs an entry page, or the site stops at the first render and names the collection. `smoodly.entryPage()` pairs the collection with a component. An entry page has no schema of its own, so it is listed in `pages` in `smoodly/views.ts`, not in the config:
+
+File: `components/pages/Article.tsx`
+
+```tsx
+import { smoodly } from "smoodly/react";
+import { RichText } from "@/smoodly/richtext";
+import { SmoodlyImage } from "smoodly/image";
+import { articles } from "@/smoodly/collections";
+// …
+export const ArticlePage = smoodly.entryPage(articles, async function ArticleView({ entry }) {
+  const { locale, locales } = entry;
+  // …
+  const a = entry.fields;
+  // …
+  return (
+    <PageFrame locale={locale} locales={locales}>
+      <article className="container article">
+        // …
+          <h1 className="article__title">{a.title}</h1>
+        // …
+        {a.image && <SmoodlyImage image={a.image} aspect="21:9" className="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+        <div className="article__body prose prose--lead"><RichText doc={a.body} /></div>
+      </article>
+      // …
+    </PageFrame>
+  );
+});
+```
+
+The view receives `entry`, whose `fields` are resolved: images are ready for `SmoodlyImage`, and a reference such as `author` is `{ id, path, fields }`, the person's fields under `fields`. Beside `fields` the entry carries its `id`, `path`, `locale`, the language rendered, and `locales`, which maps every language to the entry's address there, for a language switcher, and `seo` when the collection turns [SEO](../pages/seo.md#seo-for-entries) on. Register the export in the `pages` list of `smoodly/config.ts`, beside the page types.
+
+An entry page has no zones. It is your own markup over the entry's fields, and editors change the entry in its form rather than in a canvas.
+
+## The index page
+
+The list at `/posts` itself is an ordinary fixed page whose slug matches the collection's path in every language:
+
+File: `components/pages/Articles.schema.ts`
+
+```ts
+export const articlesSchema = smoodly.schema.page({
+  name: "articlesIndex",
+  title: "Articles",
+  slug: { en: "posts", fi: "artikkelit" },
+  zones: {
+    hero: z.locked(pageHeroSchema),
+  },
+  seo: true,
+});
+```
+
+Its view and its registration are any page type's (see [Page types](../content-modeling/page-types.md)), with the schema listed in `pages` in the config.
+
+**Astro**
+
+The view is `src/page-types/articlesIndex.astro`.
+
+**Next.js**
+
+The view is `export const ArticlesPage = smoodly.page(articlesSchema, ArticlesView)`, listed in `pages` in `smoodly/views.ts`.
+
+The list page is live as soon as you deploy it, with an empty hero until an editor fills it. Its row appears in *Pages* the next time someone opens the admin.
+
+Because the slugs match, that page is the mount: the row in the page tree opens its editor, editors own its hero, and its view queries the entries for the grid below. [Queries](../collections/queries.md) shows that part. A nested path works the same way: the News index page's slug is `{ en: "company/news", fi: "yritys/uutiset" }`.
+
+**Astro**
+
+Nothing changes in the routes: the integration's page shell already resolves a URL to a page, a path or an entry, and renders an entry with its collection's entry page.
+
+**Next.js**
+
+Nothing changes in the routes: the catch-all route already resolves a URL to a page, a path or an entry, and renders an entry with its collection's entry page.
+
+Next, [Queries](../collections/queries.md).

package/docs/collections/ordering.md

@@ -0,0 +1,47 @@
+# Ordering
+
+A collection has one order, set in its schema, that the admin's list and your queries share.
+
+## The order option
+
+`order` takes one of two shapes:
+
+| Name | Description |
+| --- | --- |
+| `{ by, direction }` | Sort by a field, or by createdAt or updatedAt, ascending or descending. Without an order, a collection is newest first. On the live site updatedAt is the time of the last publish, so a draft save moves nothing; in draft mode it is the last save. |
+| `"manual"` | Editors drag entries into an order in the admin. Queries return that order. |
+
+The starter uses both: articles by date, people by hand.
+
+File: `smoodly/collections.ts`
+
+```ts
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  order: "manual",
+  // …
+});
+// …
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  order: { by: "date", direction: "desc" },
+  // …
+});
+```
+
+## By a field
+
+The field must be shared across languages, because the order is one list for every language. A localized field or the slug is refused at startup, and so is a field the collection does not declare. Numbers order as numbers and dates as dates, since a date field stores an ISO string.
+
+A query may override the order for one read with its own `order` option.
+
+## By hand
+
+With `"manual"`, the collection's list in the admin has a grip on every row, and dragging a row reorders the entries. The new order is immediate and not part of any draft: order belongs to the collection, not to an entry's version, so it needs no publish. On a multilingual site the order is shared by every language unless the config sets [`locales.order`](../languages/locales.md#one-order-or-one-per-language) to `"perLocale"`; then a drag reorders the language selected in the list, and a query returns its own language's order. Dragging works on flat collections; a nested collection, one with `tree`, lists its entries flat and cannot be reordered by drag.
+
+Next, [Globals](../globals/defining.md).

package/docs/collections/queries.md

@@ -0,0 +1,173 @@
+# Queries
+
+Read entries, globals and the page tree from your own views, typed by your registry, cached, and aware of drafts.
+
+## The read API
+
+**Astro**
+
+The reads are Astro live collections. `src/live.config.ts` names one loader per collection, global item, the pages and the page tree, from `smoodly/astro/content`:
+
+File: `src/live.config.ts`
+
+```ts
+export const collections = {
+  pages: defineLiveCollection({ loader: pageLoader() }),
+  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
+  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
+  // …
+  footer: defineLiveCollection({ loader: globalLoader(footer) }),
+  // …
+};
+```
+
+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 });
+---
+```
+
+| Name | Description |
+| --- | --- |
+| `getLiveCollection("articles", options)` | Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent. |
+| `getLiveEntry("articles", { path, locale })` | One entry by its URL path, or by id, with its references resolved. |
+| `getLiveEntry("footer", { locale })` | A global item's value in a language, for a layout. |
+| `getLiveEntry("pages", { path, locale })` | A page by URL path or id. |
+| `getLiveCollection("pageTree", { locale })` | The published page tree in a language, each item with its page fields, for a navigation. |
+
+Each result's `data` is the read shape below. Every read tags the response, so a publish expires the page that made it.
+
+**Next.js**
+
+`smoodly/server.ts` exports `q`, a set of read functions typed by the collections and globals you registered:
+
+File: `smoodly/server.ts`
+
+```ts
+export const q = (): Queries =>
+  new Proxy({} as Queries, {
+    get: (_, name) => async (...args: unknown[]) => {
+      await buildGate();
+```
+
+Each call passes the build gate before it reads the keys: while `next build` prerenders it waits for a request, so the build needs no keys; at run time it does nothing, so a page that calls `q()` stays cacheable.
+
+Call it in a server component, a page type's view or a route:
+
+File: `components/pages/Articles.tsx`
+
+```tsx
+import { q } from "@/smoodly/server";
+// …
+  const items = await q().getEntries("articles", { locale });
+```
+
+| Name | Description |
+| --- | --- |
+| `getEntries(collection, options)` | Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent. |
+| `getEntry(collection, idOrPath, options)` | One entry by id or by its URL path, with its references resolved. |
+| `getGlobal(name, options)` | A global's value in a language, for a layout or a page frame. |
+| `getPage(pathOrId, options)` | A page by URL path or id. |
+| `getPageTree(options)` | The published page tree in a language, each item with its page fields, for a navigation. |
+
+Every read takes `locale`; without it, the default language. Collection and global names are checked against the registry, so a typo is a type error.
+
+## What comes back
+
+Every read returns Smoodly's own keys at the top level and your content under `fields`, so a collection may have a field called `path` without a clash. Nothing else leaves the read: other languages' rows, draft pointers and editors' emails stay inside.
+
+| Read | Shape |
+| --- | --- |
+| `An entry` | `{ id, path, locale, locales, updatedAt, fields, seo? }`. `path` is the entry's URL in that language, or `null` without a collection path; `locales` is its address in every language; `updatedAt` is the last publish on the live site and the last save in draft mode; `seo` is present when the collection turns SEO on. |
+| `A page` | `{ id, title, path, locale, locales, template, fields, seo?, ancestors, children }`. `seo` is present when the page type has `seo: true`. |
+| `A global` | `{ locale, fields, settings?, styles? }`. A visual global adds `settings` and `styles`; an object global has `fields` only. |
+
+A collection read returns a list of these, `fields` typed from the collection, so an item needs no cast:
+
+**Astro**
+
+File: `src/page-types/articlesIndex.astro`
+
+```astro
+      {entries.map(({ data: entry }) => <ArticleCard article={entry.fields} url={href(entry.path!, page.locale)} locale={page.locale} />)}
+```
+
+**Next.js**
+
+File: `components/pages/Articles.tsx`
+
+```tsx
+          {items.map((entry) => (
+            <ArticleCard key={entry.id} article={entry.fields} url={url(entry.path!)} locale={locale} />
+          ))}
+```
+
+A reference arrives resolved, as deep as its own field says: a bare `f.ref` gives `{ id, path, fields }` and its target's references stay ids, `.resolve("author")` follows the named reference one level, and `.resolve()` follows the whole chain. [Reference and tags](../fields/reference-and-tags.md) has the table. In a list, images and references resolve in one batched pass per referenced collection, so a card has its author's fields and its image URL without a second read. A single entry resolves them the same way.
+
+## Filtering and limiting
+
+`where` matches fields by equality, or by any of several values:
+
+**Astro**
+
+File: `src/entry-pages/articles.astro`
+
+```astro
+---
+// …
+const { entries: byAuthor = [] } = authorId ? await getLiveCollection("articles", { locale, where: { author: authorId } }) : { entries: [] };
+// …
+---
+```
+
+**Next.js**
+
+File: `components/RecentNews.tsx`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function recentNews(locale: string) {
+  const items = await q().getEntries("articles", { locale, where: { date: "2026-09-02" }, limit: 3 });
+  return items.map((item) => item.fields.title);
+}
+```
+
+`where` sees every field, localized ones included, and filters the version shown: on the public site the published version, in the editor's preview the draft, so an unpublished edit never touches the live list. `slug` is not filterable, so find an entry by its path instead. For an array field such as tags or checkboxes, one value matches entries that contain it. The match is exact, case included. A tag is stored in the spelling the collection already uses, so once one entry has `Dinner`, another that types `dinner` stores `Dinner` too: filter with that spelling. `limit` applies after ordering and after the published-only filter, so it counts entries that are really there, and `order` overrides the collection's default for one query.
+
+The starter's article page reads the four newest articles and drops itself to show three related ones.
+
+## Paging a list
+
+`offset` skips that many entries after the order and the filter, before `limit` counts, so page N of a list is `limit` entries from `(N - 1) * limit`. The read returns the page's entries and no total: ask for one entry more than you show to know whether a next page exists.
+
+**Astro**
+
+Pass the same two options to `getLiveCollection`: `{ locale, limit: perPage + 1, offset: (page - 1) * perPage }`, show the first `perPage` entries, and link to the next page when the read returned one more.
+
+**Next.js**
+
+File: `components/ArticlePage.tsx`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function articlePage(locale: string, page: number, perPage = 10) {
+  const items = await q().getEntries("articles", { locale, limit: perPage + 1, offset: (page - 1) * perPage });
+  return { items: items.slice(0, perPage), hasNext: items.length > perPage };
+}
+```
+
+Each page is cached as its own read and expires with the collection, like any other list.
+
+## Draft mode and caching
+
+Inside the editor's canvas every query reads the draft rows: an unpublished article shows in the index grid as it will after publish. On the public site queries read published rows only and are cached; publishing an entry, a global or a page expires the queries that showed it, so the live site updates at once. A list is tagged by its collection and by every collection its references resolved into, so editing an author refreshes the article lists that show that author.
+
+Next, [Ordering](../collections/ordering.md).