smoodly 0.0.36 → 0.0.38

package/README.md

@@ -1,1614 +1,36 @@
-# smoodly (core package)
+# smoodly
 
-Define a component once in code — it's instantly a typed, editable,
-AI-addressable building block your editors can compose, within the rails you
-set. Content lives in Supabase; the admin mounts into your own Next.js app.
+A code-first CMS for Next.js. Define a component once in code and it
+becomes a typed, editable building block your editors compose, within
+the rails you set. Content lives in Supabase; the admin mounts into
+your own app at `/admin`.
 
-    npx create-smoodly-app my-site
-
-A self-hosted app needs three environment variables: `SMOODLY_URL`,
-`SMOODLY_SECRET_KEY` and `SMOODLY_PUBLISHABLE_KEY`.
-Source and docs: https://github.com/laniakea-studio/smoodly-cms
-
-The registration runtime — the real implementation of the API designed in
-Phase 0 (`sketches/phase0/` remains the readable spec; `docs/DESIGN.md`
-holds the decisions). Test-driven; run with `npm test`.
-
-Implemented:
-
-- `f.*` field builders — inert, immutable, JSON-serializable descriptors
-  (ref thunks excepted); validation lives server/admin-side by design rule
-- `smoodly.schema.section/element` — descriptor capture + the
-  fields-only-`localized()` rule enforced at construction
-- `smoodly.section/element(schema, View)` — the typed pairing: returns a
-  real component carrying `.schema`; drift between schema and view is a
-  compile error at the pairing; style select defaults apply in hard-coded
-  JSX use; `Props<typeof schema>` infers required/optional/select types
-- `z.sections([...]).max(n)` / `z.freeform({ sections, custom? })` / `z.locked` — component
-  references in, names stored; `custom: true` lets editors add a custom section there
-- `smoodly.toolset` — plain values, element refs serialized to names
-- `smoodly.collection` — descriptors + admin hints; ref thunks resolve
-  post-evaluation and infer the target entry shape
-- `defineConfig` — registry name-uniqueness, the `styles` CSS values
-  behind Smoodly's styles set (`spacing.sm/md/lg`, `width.narrow/wide/full`;
-  package fallbacks fill the rest) and the `css: true` gate for the
-  custom-CSS box (spec 2026-09-14)
-- `<smoodly.Section>` — the root wrapper every section renders through:
-  `as`, Smoodly's `styles` steps rendered INLINE (`padding-top`,
-  `padding-bottom`, `text-align`, `--smd-width`; Default renders nothing),
-  the node's scoped `<style>` child (`[data-smd-node="…"]{…}`),
-  `data-smd-node` always, every other prop spread onto the root; settings
-  are never turned into attributes — the view writes its own
-- Four namespaces on a node (spec 2026-09-14, plan A): `fields`
-  (content), `settings` (the developer's knobs — any builder, never
-  localized, interpreted by the view; `meta` is gone), `styles`
-  (Smoodly's set: `spacingTop`, `spacingBottom`, `width`, `align`, each
-  an optional radio — `styles: false | { omit }` on a schema opts out),
-  `css` (the snippet; `css: false` on a schema removes the box).
-  `styles.ts` holds the descriptors and `inlineStyles`; `css.ts` refuses
-  `@import`, `url(`, `expression(`, `behavior:`, `</`, more than 4000
-  characters and unbalanced braces — on the escape-decoded snippet too —
-  and `safeCss`/`scopedCss` strip and scope at render. Publish validates
-  settings and css (`validateNode`); saves stay lenient.
-- Conditional fields (spec 2026-09-14 §12): every builder takes
-  `.hidden(f.when(path).is(v))` (`isNot`, `in`, `isEmpty`, `isNotEmpty`);
-  a bare path is a sibling, `fields.`/`settings.` crosses namespaces, an
-  unknown path throws at registration (`assertConditions`). One
-  `isHidden` in `conditions.ts` drives the form and the validator; a
-  hidden field's stored value is kept.
-- The custom section (spec 2026-09-14 §6, plan B, 2026-09-15): the
-  editor's own block, `Custom section` at the bottom of the "+" picker in
-  a `z.freeform({ custom: true })` zone. One flat node `{ type: "custom",
-  fields: { rows: [{ spans, gap, align, reverse, columns: [richtext…] }] },
-  styles, css? }` — the shape is ordinary descriptors (`custom/schema.ts`,
-  the list carries `widget: "rows"`), so `descriptorAt`, the media walk,
-  the validator and inline editing understand it with no special case.
-  `custom/rows.ts` is the pure reconcile: `renormalize` (integers ≥ 1
-  summing to 12, largest remainder), `setColumnCount` (a new column takes
-  the last span; a removed column folds into the last survivor, blank
-  paragraphs dropped — never silent deletion), `setSpan`, `spanAtX`,
-  `presetsFor`, `rowsProblems` (`Spans must sum to 12.`, `Between 1 and 6
-  columns.`, `One span per column.`), `columnsLabel`. `custom/css.ts`
-  emits the scoped layout CSS from the stored numbers and whitelisted
-  keywords only — one grid per row by `data-row`, gap `1rem · 2rem ·
-  3rem`, one `@media (max-width: <breakpoint>)` that stacks every row
-  (`.smd-row--reverse` flips the stack); `createCustomSection` renders
-  through `<smoodly.Section>` with `data-custom`, `.smd-row` /
-  `.smd-col` marked `rows.<i>` / `columns.<j>`, richtext through the
-  project's bound `RichText` or the root renderer over `elements`, the
-  layout `<style>` before the editor's css so the box wins.
-  `config.custom: { breakpoint?, toolset?, RichText? }` (default `48rem`
-  and the richtext default toolset plus `image`; the breakpoint must be a
-  length) resolves onto `config.custom` / `site.custom`; `renderPage`
-  registers the renderer under the `custom` type; the resolver and both
-  page stores carry the custom schema (`withCustomSchema`,
-  `PageStoreOptions.custom`) so column images resolve and count as usage;
-  publish runs `validateCustomNode` (structure through `rowsProblems`,
-  the columns' richtext, the css). In the admin: `AdminRegistry.custom`
-  (one synthetic section), `admin/custom-section.ts`, the picker entry
-  `Custom section · Your own rows of columns`, `RowsWidget` (a card per
-  row: `Columns` stepper, `Widths` bar with `1/2 · 1/2`-style presets,
-  `Gap`, `Vertical align`, `Reverse on mobile`, `Column N` editors,
-  `+ Add row`) over `SpanBar` (pointer drag in twelfths, arrow keys),
-  `Custom section · N columns` labels, deep-copy on duplicate.
-
-- `smoodly.schema.page` / `smoodly.page` / `<Zone>` / `renderPage` — the
-  pages runtime: policies normalized to plain data, tree nodes mapped to
-  registered components, fail-soft on unknown types
-- `collectionSQL` / `coreTablesSQL` — the stable schema (DESIGN.md §3):
-  `coreTablesSQL` emits the once-ever core tables including `entries`,
-  `entry_locales` and `entry_versions` (shared fields on the node,
-  localized fields, slug and status per locale row, merged snapshots
-  per locale for versioned collections; `space_id` multi-tenancy with
-  a default space for self-hosted, `sort` for manual ordering, and no
-  sibling-slug index at all — sibling uniqueness is the primary key of
-  `paths` plus a pre-check the stores make per locale, for entries and
-  pages alike);
-  `collectionSQL` emits only the disposable per-collection guardrails —
-  a published-only read view joining `entries` and `entry_locales` (one
-  row per published locale, a `locale` column; a versioned collection
-  reads the published snapshot; typed casts, snake_case aliases, refs as
-  plain id values) and partial btree indexes for the declared `order.by`
-  field, on the jsonb VALUE (`("fields"->'x')`)
-- `PageStore` contract + `MemoryPageStore` — id-keyed page persistence
-  over pages/page_locales/page_versions/paths — one node, one row per
-  locale, each locale with its own tree, draft, publish and history
-  (spec 2026-09-06). Every read and write takes the record's `id`, and
-  the URL is derived from the tree, never stored on the record. Pages
-  form a tree (`parentId`, sibling `sort`, a null `template` = folder,
-  `pages.tree.depth` capping how deep editors may nest), and expose
-  `rename` (a locale's slug/title), `move`, `setTemplate`, `addLocale`,
-  `removeLocale`, `resolvePath(locale, path)` and `pathsOf(id)` alongside
-  the draft/publish semantics (one version row per publish plus the live
-  draft, rewritten in place; publish moves that locale's pointer and
-  freezes the row; discard deletes the abandoned draft; `restore` writes
-  an old version as the draft; drafts never leak into published reads). The contract
-  is a reusable suite (`test/page-store-contract.ts`); every adapter runs
-  the same tests.
-- `SupabasePageStore` — the same id-keyed contract over
-  pages/page_locales/page_versions/paths (a server-side client from
-  `createSmoodlyClient`: the service role in self-host, a write key in
-  the cloud). Contract-tested against a real local stack: `supabase
-  start` at the repo root (the generated DDL is its one migration), then
-  `npm run test:supabase`; plain `npm test` skips it and never needs
-  Docker.
-- `paths.ts` — the ONE place a URL is derived: pure, framework-free
-  functions (`segmentFor` — a locale's own segment, no fallback —
-  `chainOf`, `pagePath`, `pagePathIn` (nullable, for the admin),
-  `pagePathRows`, `entryPathRows`, `entrySegment` (a locale's own slug,
-  no fallback), `assertSupportedLocale` (both stores), `buildPageTree`,
-  segment and depth assertions) that both adapters and the tree query call, so the index
-  and every derived `path` agree by construction. `pagePath` is the
-  single page-path derivation — `pagePathRows`, `buildPageTree` and the
-  site layer all go through it.
-- `PathIndex` — the derived URL index, `MemoryPathIndex` and
-  `SupabasePathIndex` over the `paths` table ((space, locale, path) → page
-  or entry). Pages and entries share ONE instance, so a page and an entry
-  can never claim the same URL; the Supabase adapter rewrites a whole
-  subtree in one statement through the `smoodly_rewrite_paths` SQL
-  function, and a collision surfaces as "the path … is already taken".
-- Collections declare their own URL shape: `path` (the code-owned base
-  segment, per locale — absent = the collection has no URLs), `tree`
-  (entries nest under entries up to a depth), and `order` (`"manual"` or
-  `{ by, direction }`, replacing `admin.orderBy` and driving both the
-  store's list order and the generated index). A declared field orders by
-  its jsonb VALUE, so numbers sort numerically and strings — ISO dates
-  included — alphabetically, the same in Supabase as in memory.
-- `smoodly.entryPage(collection, View)` — a paired component registered
-  like a page (`kind: "entryPage"`, name `entry:<collection>`), served for
-  every entry of the collection by the catch-all through
-  `renderSmoodlyPath`.
-- `resolveTree` — the batched ref-resolution pass: one fetch per
-  collection per round, ref-site depth modes (bare ref = entry only,
-  `.resolve(names)` = named refs one level, bare `.resolve()` = whole
-  chain), per-path cycle cutting with shallow copies, optional `maxDepth`
-  safety valve (default unlimited)
-- `resolveFields` — the same pass over ONE entry's fields against its
-  collection's descriptors, for the entry-page route: the shared task
-  collection and batched rounds are factored out, so a ref site behaves
-  identically whether it sits in a page tree or in an entry.
-- `localize.ts` — `fixedPathFor` (the path a fixed page registration
-  is served at in one locale — the escape hatch's addressing; a slug map
-  that omits a locale means "the same segment", since a registration is
-  code, not a record). Pages themselves have no fallback: title and slug
-  live on `page_locales`, and slugs stay `paths.ts`'s business.
-
-- `collectEntryRefs` / `collectTreeRefs` — the refs-index feeders: walk
-  an entry or a page tree against its schemas and list every outgoing
-  reference edge (derived, rebuildable, never the source of truth)
-- Page saves feed the refs index — a page's rows are the UNION of its
-  draft and published trees' edges (source kind `page`), rewritten on
-  every `saveDraft`/`publish`, so cross-kind safe-delete holds while
-  either tree shows an entry. Publish integrity: `publish` walks the
-  draft tree directly and blocks on missing/unpublished entries.
-  Revalidation fan-out: `affectedTargets` — reverse BFS over refs
-  (entry ← entry ← page, cycle-safe, optional `maxDepth`) returning
-  `{ pageIds, entryIds }`: every PUBLISHED page whose tree reaches the
-  changed entry, and the entry itself plus every entry that references it.
-  Ids, not slugs — `pageTag(id)`/`entryTag(id)` name the cache tags, and
-  the op handler's `revalidate` effect passes each to Next's `updateTag`,
-  so a rename never orphans a tag. All wired via
-  store constructor options (`sections`, `entries`, shared
-  `MemoryRefIndex` in memory); the cross-store contract
-  (`test/page-refs-contract.ts`) runs against memory AND Supabase.
-- Media (spec 2026-09-08): `f.image({ aspect? })` / `f.video()` / `f.file()`
-  store `{ asset, alt?, crop?, hotspot?, aspect? }`; `AssetStore` (memory +
-  `SupabaseAssetStore`: rows in `assets`, bytes in the public `media`
-  bucket, two-op signed uploads); the refs index carries `asset` edges
-  through lists, objects and styles, so delete is guarded and usage is
-  listed; `resolveTree`/`resolveFields`/the site layer resolve media to
-  `{ url, width, height, mime, alt, crop?, hotspot?, aspect? }` with one
-  fetch per page; `smoodly/image` ships `<SmoodlyImage>` (a box at the
-  aspect, the image framed by crop and hotspot over `next/image`),
-  `<SmoodlyVideo>`, `imageUrl` behind the loader seam (v1: the Next
-  loader only) and `smoodlyImages()` for next.config's `images`. Admin: the media
-  widget in every form, the library picker, the crop-and-hotspot editor,
-  the Media screen with metadata, usage links and guarded delete.
-- `EntryStore` contract + `MemoryEntryStore` + `SupabaseEntryStore` —
-  collection-entry persistence over entries/entry_locales/entry_versions/paths
-  — one node, one row per locale, each locale with its own slug, status
-  and `.localized()` fields, shared fields on the node, and a per-locale
-  version history for every collection (spec 2026-09-14; the 2026-09-06
-  opt-in is gone): `create({ locale })`, `update(id, locale, fields)`,
-  `setStatus(id, locale, status)`, `addLocale`, `removeLocale`,
-  `listVersions`, `getVersion` and `restore`; the draft row is rewritten
-  in place until published (spec 2026-09-13 history); saves rewrite the entry's refs rows over every locale's
-  live field set, `referencesTo` answers the reverse
-  question, `getMany` is the batched read whose signature is
-  `resolveTree`'s `EntryFetcher`, now `(collection, ids, locale, { status })`,
-  the published read of a versioned collection being the snapshot
-  (with `{ status: "published" }` for the
-  published-route read — a post-publish demotion resolves as missing
-  instead of leaking draft fields — DESIGN.md §3 "Page edges in refs"), deletes are blocked while
-  referenced,
-  entry slugs are unique among SIBLINGS per locale in both adapters
-  (a code pre-check; the `paths` primary key is the invariant),
-  and `reorder` rewrites sort 1..N through the `smoodly_reorder` SQL
-  function (one statement, `updated_at` untouched). Same
-  reusable-contract pattern as PageStore; `npm run test:supabase` runs
-  both adapters against the local stack
-
-- Proven end-to-end in `examples/site` — a real Next.js app wiring the
-  config + Supabase stores into routes: tag-cached resolved trees,
-  draft-mode preview, server-action writes with revalidation fan-out.
-  The example is the multilingual layout (next-intl, `en`/`fi`, the site
-  under `app/[locale]/`, the admin outside it), and `create-smoodly-app`
-  generates both of its templates from it — `templates/next-intl`
-  verbatim, `templates/next` with the four single-language route files
-  from `variants/single/` and two rewritten lines of glue
-
-- The space layer (spec 2026-09-04 §3): `space_id` on every content
-  table, `smoodly_current_space()`, the insert trigger, the row cap, the
-  three cloud-state tables (`members`, `space_keys`, `spaces`) and
-  the policy set. Service role bypasses it; a write key is scoped to its
-  space. Contract suites run in both modes; `test/isolation.supabase.test.ts`
-  proves isolation. Generated per-collection views are `security_invoker`,
-  so they read through the same policy set rather than their owner's
-  privileges. Live acceptance test in `test/rls.supabase.test.ts`. Note
-  for self-host: the anon key now reads published rows straight off the
-  base tables (`pages` and `entries` published in any locale, a published
-  `page_locales`/`entry_locales` row, the `page_versions`/`entry_versions`
-  row a published locale points at — shared content included, since it
-  is stored as entries, spec 2026-09-07), not only through the generated
-  views.
-
-- Admin login: `supabaseAdminAuth` (from `smoodly/admin`) + `gateAdminOp` around the ops seam;
-  `LoginView` + `useAdminSession` in the shell; `createSmoodlyAdmin({ auth })`.
-  Env: `smoodlyEnv()` / `createSmoodlyClient()`.
-
-- The admin, real and mounted: `smoodly/admin` (the AdminOps seam —
-  `createAdminOps`/`runAdminOp` server-side over the stores,
-  `makeClientOps` client-side forwarding `{ path, args }` through one
-  server action; typed `OpResult`, never throws — `serializeAdminConfig`
-  turns the registry into the admin's nav/forms; `validateFields` +
-  tree-ops for pure canvas mutations), `smoodly/admin/next`
-  (`createSmoodlyAdmin` binds registry + op action into `AdminPage`/
-  `AdminLayout` for the app's `[[...segments]]` route group;
-  `createAdminOpHandler` is the one server action the client ops call),
-  and `EditorBridge` (never on a live page: the renderer loads it lazily
-  through `next/canvas-slot.tsx` in editor mode only, spec 2026-09-29
-  pre-install fixes §1 — runs inside the draft-route iframe, reports node, zone and
-  marked-field geometry, forwards select/hover with the field under the
-  pointer, executes refresh/scroll, reports each committed render). Shell
-  (registry-derived nav, list views, its own client-side router —
-  `shell/router.ts`, `RouteLink`, a tab-close guard for pending saves; the
-  shell mounts from the layout and the catch-all page only makes the
-  URL exist, spec 2026-09-08),
-  entry form (widgets by field type, validation errors surfaced inline,
-  save/publish/unpublish/delete with the safe-delete guard's message
-  shown verbatim), and the editor view (dark instrument around a bright
-  canvas — the iframe is the site's own draft route, pixel-identical by
-  construction; every gesture mutates client tree state through pure
-  ops, a debounced `saveDraft` persists, and the bridge refreshes the
-  iframe on the save ack — refresh-on-change preview for structure; text
-  and richtext are edited in place in the canvas and inspector text edits
-  land there the same tick, spec 2026-09-10) are all real, in-house. The autosave itself is a framework-free
-  controller (`createDraftAutosave`: debounce, doubling capped retry,
-  pre-publish `flush`) wrapped by `useDraftAutosave`; the controller is
-  unit-tested with fake timers, the hook only for its initial snapshot. Proven end-to-end in
-  `examples/site/app/(smoodly)/admin` against the local Supabase stack —
-  see its README's acceptance walk.
-
-- The admin is the page TREE (spec 2026-09-05 §7): the ops seam addresses
-  pages by id — `pages.list`/`get`/`create`/`saveDraft`/`publish`/
-  `delete`/`rename`/`move`/`setTemplate`, plus `entries.move`.
-  `entries.get`/`create`/`save`/`setStatus` take a locale;
-  `entries.addLocale`/`removeLocale`.
-  `pages.list` materializes the code-owned root nodes before an editor
-  touches them (`admin/fixed-nodes.ts` derives fixed pages and collection
-  mounts from the registry and finds their records by the `pages.fixed`
-  owner key, schema v5), and every guard asks
-  the same `fixedNodeOf`: a fixed node is never renamed, moved or
-  deleted, and no page is created under a mount, and a `homePageSlug`
-  guard keeps the site root from being deleted, moved or re-slugged
-  even without a fixed registration. `pages.get` returns the
-  record, its draft, `paths` (locale → CMS path) and `urls` (`href`
-  applied), so the canvas and "View live" get site URLs. A tree write
-  expires the neighbours whose cached units embed it: publish and delete
-  the record and its parent, rename the subtree and its parent, move the
-  subtree plus the old and the new parent; `entries.move` expires the
-  entry and its descendants. The Pages list IS that tree — `admin/shell/pages-tree.ts`
-  is the pure view model (indent per depth, chevron on parents, the
-  derived path as the URL column, and per row its kind, status, sibling
-  position and whether it may take children), rendered by
-  `admin/shell/PagesList.tsx` with a row menu over the tree ops (New
-  subpage, New subpath, Add page here, Rename…, Delete — reordering is
-  the grip's: drag or its arrow keys, since 2026-09-15); a mount a fixed
-  page claims opens that index page's editor
-  on click like any page row (2026-09-09), a bare mount opens the
-  collection list. The editor
-  is keyed by id, with a locale switcher loading that locale's own tree
-  and pointing the canvas at `urls[locale]` and, while no block is
-  selected, page settings (`admin/editor/PageInspector.tsx`, spec
-  2026-09-10 page fields: **SEO & Social** — title, description, social
-  image, hide from search engines, under the tree's `meta` — and
-  **Settings** — the ACTIVE locale's title and slug through `pages.rename`,
-  the template's page fields under the tree's `fields`, remove from
-  locale). The entry form prefixes its slug field with the collection's
-  mount path. The serialized
-  registry carries `collections[].path`/`depth`, `pages[].slugs` and
-  `pageDepth`, and `defineConfig` validates `homePageSlug` — a real
-  segment, and never a collection's mount.
-
-- `createSmoodlySite` — the site layer (`site.ts`), framework-free: one
-  place turns a (locale, path) into a loaded page or entry, so the Next
-  renderer and the content API can never disagree about published-only
-  reads, folders or fallback. `locate(locale, path)` is one primary-key
-  hit on the `paths` index; `load(target, locale, path, { draft? })`
-  fetches the record and its tree (draft or published), resolves refs,
-  reads the locale's own rows, and returns a `SitePage` — `record`,
-  `template`, `tree`, localized `title`, `path`, `ancestors`, `children`,
-  `locale` and `locales` — the page's `{ slug, path }` in every supported
-  locale, null where it is absent or, outside draft mode, unpublished
-  (spec 2026-09-15) — or a `SiteEntry` with the locale's merged fields (a
-  versioned collection's published snapshot on the public path) resolved,
-  `locale`, and the same `locales` map (an entry's slug and path are null
-  where its row claims no URL). `getEntries` items and `getEntry` carry
-  `locale` and `locales` too.
-  `resolve(locale, path, { draft? })`
-  is the two in sequence — `locate` then `load` — for a caller that just
-  wants the hit. A folder (null template), an
-  unpublished record outside draft mode, or a missing one is `null`.
-  On top of it the content API for menus, sitemaps and custom routes,
-  published-only unless `draft: true` (spec 2026-09-11):
-  `getPagesTree({ locale, draft? })` (nested
-  `{ id, title, path, hasPage, fields, children }`), `getPage(pathOrId)`,
-  `getEntries(collection, { locale, parent?, order?, where?, limit?, draft? })`
-  — `where` is equality / any-of on shared fields and `limit` a SQL limit,
-  both run by the store — `getEntry(collection, idOrPath)` (an id, a
-  path, or a bare slug naming a root entry) and `getEntriesTree(collection)`.
-  In the app, read through `q` (next bullet) rather than the site layer.
-- `createSmoodlyQueries` (`smoodly/next`, spec 2026-09-11) — the read
-  API the scaffold exports as `q`: `getPageTree({ locale })`,
-  `getPage(pathOrId)`, `getEntries("articles", { where, order, limit,
-  parent })`, `getEntry("articles", idOrPath)` (an id or a path — a bare
-  slug is refused, since its unit would sit under a tag no op fires) and
-  `getGlobal("header")`. Typed by the registry (names are checked, fields
-  typed), the live draft inside the editor preview, and outside it one
-  `unstable_cache` unit per distinct call under a tag the admin ops
-  expire: `pages:tree` (every page op that changes the listing),
-  `entries:<collection>` (every entry write), `page:<id>`, `entry:<id>`,
-  `global:<name>`. `filterPageTree(items, keep)` prunes a tree for a nav
-  (a dropped parent drops its subtree).
-- `smoodly/next` — `createPageRenderer`, the site-route seam over that
-  layer, bound once by the app like `createAdminOpHandler`. The two route
-  files call `renderSmoodlyPath(segments, { locale?, searchParams? })` and
-  `smoodlyMetadata(segments, { locale? })`: a page at any depth in any
-  locale rendered by the shape its `template` names, with the `page` prop
-  (`{ id, title, path, url, ancestors, children }`, every ancestor and
-  child carrying `url` beside its locale-relative `path`, both put through
-  the `href` seam) beside `zones`; a collection
-  entry rendered by its `smoodly.entryPage` as `{ entry, path, locale, locales }`; a folder,
-  an absent locale or an unregistered template a 404. The published read is
-  cached per (locale, path) and tagged `page:<id>` / `entry:<id>` — the
-  `locate` hit runs outside the cache, because the tag needs the id first.
-  Draft mode reads drafts uncached, and the editor param mounts
-  `EditorBridge`. Metadata is the tree's `meta` plus
-  `alternates.languages`, the locales with a URL in the hit's `locales` map
-  through the injectable `href(path, locale)`
-  seam (identity by default, `getPathname` with next-intl) and emitted only
-  for a multi-locale site. `renderSmoodlyPage(Paired, …)` and
-  `smoodlyPageMetadata` remain as the escape hatch for a FIXED page
-  rendered from the developer's own route file; each serves only its own
-  registration's record. All four await Next's
-  `connection()` before reading the stores, so a route with no dynamic
-  segment is request-rendered without a `force-dynamic` export and
-  `next build` never reaches the database
-  (`test/next-page-renderer.test.tsx`). Page schemas may declare a fixed `slug`
-  (owned by code, not by editors); the admin reads it to filter
-  New Page and protect the record. `defineConfig({ homePageSlug })`
-  (default `"home"`) names the slug the site root serves; the paths index
-  derives every URL from it, and `pages.get(id)` hands the admin the
-  finished `paths` (locale → CMS path) and `urls` (`href` applied), so the
-  admin no longer derives a path of its own.
-- `smoodly/image` — the site's media components: `<SmoodlyImage>`,
-  `<SmoodlyVideo>`, `imageUrl(image, { width, quality? }, loader?)`,
-  `frameFor`/`boxAspectOf` (the crop math). Server-safe, no `"use client"`.
-- `smoodly/image/config` — `smoodlyImages()` for `next.config`'s `images`:
-  the Supabase host as a remote pattern, plus `dangerouslyAllowLocalIP`
-  when that host is loopback or private — Next 16's optimizer refuses a
-  private upstream otherwise, and the local stack is one. Its own entry
-  because Next loads `next.config.ts` in plain Node, where anything that
-  reaches `next/image` fails to resolve (next@16 has no `exports` map);
-  `smoodly/image` still re-exports the helper for code the bundler sees.
-- `smoodly/richtext` — the bound richtext renderer, `createRichText({
-  elements, sizes })`: the root `RichText` with the project's elements and
-  body images through `<SmoodlyImage>`. Its own entry for the same reason
-  as `smoodly/image`: it reaches `next/image`.
-
-- Locked zones are usable: `fillLockedZones` (a pure tree op) materializes
-  the one node of every empty locked zone from the component's `sample`
-  when the editor loads a draft, and the change rides the normal debounced
-  save. No gesture can insert into or remove from a locked zone, so this is
-  the only way the node gets there — it also covers pages that existed
-  before a locked zone was added to their schema.
-
-- Global content (spec 2026-09-07; `shared` → `global` in code
-  2026-09-15, spec 2026-09-14 §7): `smoodly.global({ name, title, section })`
-  registers a visual item, `smoodly.global({ name, title, fields })` an
-  object item; one registration materializes as a singleton entry in
-  every supported locale. `site.getGlobal(item, { locale })` and the Next
-  glue's `q.getGlobal("footer", { locale })` fetch it code-side (the
-  renderer's `getSmoodlyGlobal(item, { locale })` still works); the
-  editor places a visual item in a zone from the "+" picker as a linked
-  `{ type: "global", fields: { item, ref } }` node the resolve pass
-  rewrites into the section, and `z.locked(footer)` binds a zone to one.
-  Edited on its own admin page under Globals (`/admin/globals/<name>`),
-  with "used on N pages" from `refs`. Wired through the `globals` option
-  on the entry store and the site layer; a visual item's settings, styles
-  and css ride its row under `$settings`, `$styles` and `$css`.
-
-- Lists and editable objects (spec 2026-09-07 list field): `f.list(item)`
-  holds any builder but another list and refuses a ref or `.localized()`
-  anywhere inside (refs are top-level only; localization is whole-value on
-  a list or object). `.min`/`.max` count items. The admin edits an object
-  as an indented fieldset and a list as rows — summary, collapse, move up
-  and down, remove, "N of max", Add disabled at max — recursively through
-  `FieldWidget`, with the row logic as pure functions in `admin/forms/list.ts`.
-  `validateFields` recurses with dotted paths (`points.2.heading`) and
-  checks list length; the serializer ships a list's `item`.
-
-- Richtext, both directions: `RichText` (package root, pure React, no
-  wrapper) turns the TipTap document into paragraphs, headings, lists,
-  blockquotes, hard breaks and bold/italic/link marks, unknown nodes
-  degrading to their children; a link mark reaches the page only with a
-  safe scheme (http(s), mailto, tel, site-relative). The admin edits it
-  with a TipTap widget under a fixed toolbar (`admin/forms/RichtextWidget.tsx`,
-  spec 2026-09-08): the schema is always the full one, and the field's
-  toolset — typed names, `DEFAULT_TOOLSET` when a field declares none —
-  gates only creation (toolbar, shortcuts, input rules, paste), so content
-  a toolset forbids survives every round trip. Links carry `href` only. An
-  empty document is missing for a required field. The widget emits plain
-  JSON: ProseMirror's node attrs have a null prototype, which a server
-  action cannot serialize. Block nodes (spec 2026-09-08 block nodes): an
-  `image` node (media library, caption, alt override) and one generic
-  `element` node for every registered Element, always in the schema,
-  inserted through the toolbar's "+" or a `/` menu, edited as cards (the
-  element card renders its fields through `FieldWidget`, nested richtext
-  included). `RichText` takes `elements` and an `image` render prop;
-  `smoodly/richtext` exports `createRichText` bound over `<SmoodlyImage>`.
-  The media and refs walks descend into documents against the element
-  schemas (`elements` beside `sections` in the store, resolve and site
-  options).
-- The token guard and presence (spec 2026-09-26 concurrency): every
-  draft write carries `{ versionId, savedAt }` from the locale row's
-  `draftSavedAt` and is refused as `conflict` + `stale` when the draft
-  moved (the write itself is conditional in Supabase); the admin freezes
-  under a notice naming who saved and when and reloads through "Load
-  their version"; one private Realtime channel per space shows who edits
-  what (a lock in the lists, a line under the top bar) and announces
-  saves so a clean view refreshes and a dirty one freezes early. Schema
-  version 2 adds the draft-pointer foreign keys and the channel policies.
-  Only the editor's own edits freeze a view (2026-09-27): two editors
-  opening a fresh page at once both fill its locked hero, and the fill
-  that lands second used to freeze its view under "Your unsaved changes
-  here will be discarded" with nothing changed; now that view loads the
-  other's quietly, on the refusal or the `saved` broadcast. This was the
-  local-only timeout of "the guard alone" (CI's slower sign-in let the
-  first fill land first). Tests: `concurrency.spec.ts` ("two editors
-  opening a new page at once", with the channel cut and on; the fill
-  save is held so the race is deterministic).
-- ActionMenu near the screen's edge (2026-09-27): a row menu close to
-  the bottom opened below the viewport, where a fixed element cannot be
-  scrolled to, and the scroll event from bringing a row into view
-  arrived a frame after the click and closed the menu it had opened.
-  It now opens upward by the Combobox's `opensUp`, and closes only on a
-  scroll that moved its button. This was the Members test's flake (about
-  1 in 8 runs; the list was long because every concurrency run left
-  its second member behind — `concurrency.spec.ts` removes it in
-  `afterAll` since 2026-09-28, and `members.spec.ts` its invited Auth
-  user, which Remove member leaves in place). Tests: `admin-action-menu`, `members.spec.ts` (a
-  late scroll event, a real move, a row at the bottom of the screen).
-- The security pass over the database boundary (spec 2026-09-26 security
-  pass): the presence channel admits a signed-in member of the topic's
-  space (`smoodly_presence_member()`, the socket carries the session
-  token through the client's `accessToken` callback, re-sent on refresh);
-  every function pins `search_path`; the three mutation RPCs are revoked
-  from `anon`/`public`. Schema version 3. The threat table, one test per
-  cell: content, `refs`/`members`, `spaces`/`smoodly_meta` and storage
-  columns — `test/isolation.supabase.test.ts` ("space isolation", "read
-  keys", "cloud state rows") and `test/rls.supabase.test.ts`; presence
-  and RPC columns — `isolation.supabase.test.ts` ("signed-in users and
-  the public keys"); admin ops — `test/admin-auth.test.ts`,
-  `test/admin-auth.supabase.test.ts`, `test/admin-ops.test.ts` ("members
-  ops").
-- Redirects (spec 2026-09-26 redirects): a `paths` row with `redirect`
-  set is an old address of its target (schema version 4). A published
-  rename or move keeps the old addresses as redirects unless the editor
-  unticks "Redirect the old address" on the live-URL confirm; the live
-  URL wins an address; nothing chains; `renderSmoodlyPath` answers a
-  redirect row with `permanentRedirect` through `href`. Settings ›
-  Redirects (every member) lists, adds by hand (validated old address,
-  target type-ahead) and removes. Tests: `test/path-index-contract.ts`
-  (the rule table, both adapters), the store contracts, `admin-ops`
-  ("redirects on rename and move", "redirects ops"),
-  `next-page-renderer` ("redirects"), `examples/site/e2e/redirects.spec.ts`.
-- Content API contract (spec 2026-09-29 content API contract): every
-  read returns the public shape — `EntryItem`, `PageItem`, `GlobalItem`
-  (`src/read-shapes.ts`), nothing of other locales, pointers or editors
-  leaves the site layer; a reference resolves as `{ id, path, fields }`
-  as deep as its field says, in lists and single reads alike, and the
-  types follow the depth; `smoodly_list_entries` (schema version 7)
-  filters, orders and limits over the snapshot shown, so `where` sees
-  localized fields and never the live row; a list is tagged by every
-  collection it resolved into; `seo: true` or `{ description, image }`
-  on a collection adds the SEO & Social panel, stored per locale under
-  `$seo` (`src/seo.ts`); every content table admits a write key only, the
-  publishable key serves sign-in and presence (`presenceConfig`). Tests:
-  `test/entry-store-contract.ts` ("query"), `test/site.test.tsx`,
-  `test/next-queries.test.tsx`, `test/types-refs.test.ts`,
-  `test/seo.test.ts`, `test/isolation.supabase.test.ts`,
-  `test/rls.supabase.test.ts`.
-- Editor safety (spec 2026-09-27 editor safety): schema drift — stored
-  content the code no longer describes — is found by one pure walk
-  (`admin/drift.ts`) over the serialized registry. Broken findings
-  (an unknown section, element, page type or collection; a value that
-  doesn't fit its field; a zone rule broken) refuse publish for pages,
-  entries and global items; left-over ones (a removed field or zone, an
-  element outside its toolset, a localization change) never do. The
-  validator's one type check is `fits` (text and number checked for the
-  first time). Settings › Content health (every member) reports every
-  document, draft and live, grouped by the change; the editors mark the
-  open document (notice, Outline marks, a canvas placeholder, the
-  unknown-section inspector with Remove section, misfits as field
-  errors, a "No longer in the schema" group with Copy and Clear, Clear
-  zone). Turning `.localized()` on no longer deletes the other locales'
-  value (update, discard and restore keep a localized key's shared
-  value); the last `window.alert`s are `notify()`. No bulk writes
-  (OQ 35). Tests: `admin-drift`, `admin-drift-copy`, `admin-health`,
-  `admin-health-list`, `admin-health-page`, `admin-drift-markers`,
-  `admin-unknown-node`, the store contracts (`scanTrees`,
-  `scanEntries`, the pinning tests), `entry-store.supabase` (the
-  localized fix across two schemas), `examples/site/e2e/health.spec.ts`.
-- Shadowed-page detector (spec 2026-09-27 shadowed-page detector): a
-  canvas whose bridge never speaks within 4 s of the frame's load is
-  diagnosed — the editor fetches the canvas URL once and
-  `admin/editor/canvas-diagnosis.ts` names another route, a route file
-  that drops `searchParams`, a crash, a 404, a redirect, a refusal, a
-  framing header or a script error, as an editor sentence and a "For
-  your developer" line (`editor/CanvasWarning.tsx`, in place of
-  "Selection unavailable"). The renderer writes
-  `<meta name="smoodly-draft">` in draft mode only. No reserved-path
-  list (OQ 23 closed). Tests: `admin-canvas-diagnosis`,
-  `admin-canvas-warning`, `next-page-renderer` (the marker),
-  `admin-bridge`, `examples/site/e2e/editor.spec.ts`.
-- cacheComponents unsupported (spec 2026-09-27 cache components): under
-  Next's Cache Components the catch-all is served from a fallback shell
-  that commits 200, so 404s and 308s are lost; the renderer warns once
-  per renderer when `process.env.__NEXT_CACHE_COMPONENTS` is on, and the
-  Next.js guide says why. OQ 19 closed. Tests: `next-page-renderer`
-  ("cacheComponents").
-- Section guard (spec 2026-09-27 section guard): `Zone` calls a
-  plain-function section view inside try/catch (an async one through
-  `SectionGuard`, in place), so a throw in a section's own code leaves it
-  out and the page renders — nothing live, a placeholder in the canvas
-  and under `next dev`; the adapter's `rethrow` (Next: `unstable_rethrow`)
-  lets control flow through. In editor mode the Next adapter also wraps
-  each section in `<Suspense>` + the client `CanvasBoundary`, the bridge
-  reports crashed sections, the page editor lists them, and Publish asks
-  first. A healthy page's HTML is unchanged. Tests: `section-crash`,
-  `render` ("the section guard"), `next-canvas-boundary`,
-  `next-page-renderer`, `admin-crash-copy`, `admin-canvas-diagnosis`,
-  `examples/site/e2e/sections.spec.ts`.
-- No admin on the live site (2026-09-27): `supabaseAdminAuth` moved from
-  `smoodly/admin/next` to `smoodly/admin` (its `AuthConfig` type too).
-  `smoodly/server.ts`, which every site route imports, took it from the
-  `admin/next` barrel beside `createSmoodlyAdmin`, so the admin shell was
-  a client module of every site route. Confirmed by removing the import
-  and rebuilding; the starter's home page, production build, went from
-  1,616,602 to 628,849 bytes of JavaScript (8 chunks either way, the
-  1,050,601-byte chunk holding `AdminApp` gone). The rest of the page's
-  JavaScript is the site's own: of a 62,848-byte chunk, next-intl is
-  ~34 KB, `next/link` and `next/image` most of the rest, and the
-  editor-only modules ~3.4 KB (`EditorBridge` ~2.5 KB, the canvas net
-  ~0.9 KB) — too little to lazy-load. Tests: `site-entries` (every entry
-  but `smoodly/admin/next` reaches no client module except those two),
-  `examples/site/e2e/site-bundle.spec.ts` (CI only: production chunks).
-
-- Export and import (spec 2026-09-28 export/import): `npx smoodly export
-  [--out <dir>]` writes the key's space — the nine content tables with
-  history, the member list, the ready assets' files — into a folder
-  (`manifest.json`, `rows/<table>.json` without `space_id`, `media/`
-  without the space prefix), written as `.partial` and renamed last; it
-  refuses a publishable key (the `smoodly_meta` read), a database behind
-  the package, and a snapshot whose foreign keys do not close ("content
-  changed during export"). `npx smoodly import <dir>` writes it into a
-  space that is empty or holds only this export's rows, schema versions
-  equal: media first, rows in reference order with on-conflict-do-nothing,
-  so a stopped run finishes by running it again. Tests: `space-transfer`,
-  `cli-transfer`, `space-transfer.supabase`,
-  `examples/site/e2e/transfer.spec.ts`.
-
-- Nested addresses (spec 2026-09-29 nested paths, schema v5): a
-  collection `path` or fixed `slug` may have several parts
-  (`company/news`), each checked as a segment, a locale the map omits
-  filled from the default. `src/addresses.ts` turns the registry into
-  code addresses by owner key (`collection:<name>`, `page:<name>`),
-  `config.addresses`; `pages.fixed` names a code-owned record's owner,
-  the record stays a root with the last part as its slug, and its path
-  comes from the config. Anchored paths (spec 2026-09-29 anchored
-  paths): each `paths` row names its anchor (`pages.fixed`'s owner key,
-  `''` for the editors' tree) and stores only the editors' part; the
-  path index (`src/anchors.ts`, both adapters, `config.anchors`) joins
-  the address from the config, so a code change needs no write and the
-  live site does one lookup per request. `ensureFixedNodes` finds
-  records by owner and creates them over an editor's page, never
-  adopting it: code wins the address. The ops refuse a page write onto
-  or below a code address naming the owner; the Pages list flags an
-  editor's page there and a record no longer in code (delete only).
-  Tests: `addresses`, `anchors`, the path index contract,
-  `admin-fixed-nodes`, `admin-ops-addresses`, `admin-pages-tree`,
-  `site`, the page and entry store contracts,
-  `examples/site/e2e/entries.spec.ts`.
-
-- Pre-install fixes (spec 2026-09-29 pre-install fixes, schema v6): one
-  permissive policy per table and action (the write key reads through
-  `smoodly_read`; `smoodly_write` splits into insert, update and delete
-  where a public read exists, the media pair too), the missing
-  foreign-key and published-version indexes, `smoodly_space_row_cap`
-  revoked from anon. A live page runs no Smoodly client code: the canvas
-  bridge and the section net load lazily from one stub under 1 KB
-  (`next/canvas-slot.tsx`), and `smoodly/bridge` is no longer an export.
-  Draft mode shows a preview pill (`next/preview-pill.tsx`: an inline
-  Shadow DOM script, bottom centre, movable left/centre/right, hidden
-  until reload, Exit preview through `previewRoute`, which every starter
-  mounts at `app/api/preview/route.ts`; `previewPill()` for routes the
-  renderer does not draw). The page editor, the entry form and the
-  Globals form save a pending edit on unmount (`close()` on the autosave
-  controller, reopened by the hook's effect for StrictMode; it waits for a
-  save in flight and sends the rest with that save's token) and ask only
-  before a tab close (`useUnloadGuard`); `useLeaveGuard`'s in-app "Discard"
-  confirm has no caller now. Draft mode's pill is absent from History's
-  version iframe (`smoodly-version`), whose Exit would end draft mode under
-  the editor.
-  The cached unit is keyed by (locale, path, kind, id). A new list item's
-  required select or radio stores its first option. Every starter sets
-  `metadataBase` from `SITE_URL`, which the installer writes. Tests:
-  `migration-policies`, `sql`, `canvas-slot`, `site-entries`,
-  `next-preview-route`, `next-preview-pill`, `next-page-renderer`,
-  `admin-autosave`, `admin-list-helpers`, `env` (installer),
-  `e2e/publish.spec.ts`, `e2e/editor.spec.ts`, `e2e/languages.spec.ts`,
-  `e2e/site-bundle.spec.ts` (CI-only).
-
-Not yet: canvas drag-and-drop (list fields, the outline, manual
-collections and the pages tree drag since 2026-09-09 — spec
-`docs/superpowers/specs/2026-09-09-drag-and-drop-design.md`), undo/redo, sample/placeholder content
-marking. Per-locale section visibility is not coming: each locale has its
-own tree, so a locale that does not want a section removes it (DESIGN.md
-§3, 2026-09-14).
-
-## Releasing
-
-Both packages move together. Bump before build (the CLI's templates are
-regenerated from `examples/site` in the build and pin `smoodly@<version>`),
-the user runs the two publishes (npm 2FA is a browser passkey), tag only
-after both are on the registry. From the repo root:
-
-    npm version 0.0.12 -w smoodly -w create-smoodly-app --no-git-tag-version
-    npm run build
-    npm publish -w smoodly --dry-run && npm publish -w create-smoodly-app --dry-run
-    npm publish -w smoodly --access public              # user; first, the scaffold pins it
-    npm publish -w create-smoodly-app --access public   # user
-    npm view smoodly@0.0.12 version                    # 404s for a minute or two after a good publish; poll
-    npm view create-smoodly-app@0.0.12 version
-    git commit -am "release: 0.0.12 — <changes since 0.0.11>" && git tag v0.0.12 && git push --tags origin main
-
-`prepublishOnly` rebuilds each package. The Claude Code skill
-`.claude/skills/releasing-smoodly` carries the same order with its checks.
-
-## Follow-ups
-
-The code-level debt register, triaged 2026-09-29 into four buckets:
-**Now** (before the first client install), **Next** (hardening soon
-after), **Later** (by area) and **Cloud** (only once Smoodly Cloud
-exists). Each item ends with where it was logged. A fixed item is
-deleted — git history and the specs keep the record — and a new one
-goes straight into its bucket. Design-level questions live in
-`docs/DESIGN.md`'s Open questions, not here.
-
-### Now
-
-Nothing open.
-
-### Next
-
-#### Data integrity
-
-- Older than this plan: the Supabase `addLocale` rollback on
-  `alreadyInLocale` (`supabase-store.ts`, the insertLocale catch)
-  deletes the racing WINNER's locale row and versions. Two admins
-  adding one locale at once converge on the next list; fix by rolling
-  back only what this call inserted. *(2026-09-29, nested collection paths)*
-- A ready asset whose `poster_id` names a pending asset would fail the
-  export's consistency check on every run (pending assets are not
-  exported). Unverified whether the upload flow can leave that state;
-  if it can, export the poster or null the pointer with a warning. *(2026-09-28, export/import)*
-- Publish, discard and restore compare the token, then move the pointer under a
-  pointer filter: a save that rewrites the same draft row in place between the
-  two is published unseen (one round trip wide). A SQL function would close it. *(2026-09-26, concurrency)*
-- Publish integrity for an entry's own refs: an entry can publish while
-  pointing at an unpublished entry; pages are gated, entries are not. *(2026-09-14, collections draft/publish)*
-- Unpublishing a page does not cascade: a published child keeps serving
-  under an unpublished parent's path. Decide whether it should. *(2026-09-13, publish flow)*
-- `entries.move` expires the entry and its descendants but does not fan
-  out to the pages referencing them, nor to the old and the new parent
-  entries the way `pages.move` does — asymmetric with `entries.save` and
-  `entries.setStatus`, which both fan out. *(2026-09-06)*
-
-#### Multi-statement writes (no transaction on the Supabase adapters)
-
-- The Supabase entry adapter's `removeLocale` deletes the row and its
-  versions before the paths rewrite with no rollback; its residue
-  comment describes the opposite case (a surviving path row for a
-  removed locale, not a present node without its path row). *(2026-09-06)*
-- The Supabase entry adapter's rollbacks are best-effort and can mask the
-  original throw: `create`'s catch runs `paths.remove` before the node
-  delete (a failing remove strands the node and replaces the real error),
-  `update` and `move` restore by writing, and those writes can throw in
-  place of the rewrite's rejection. `recordVersion` is two statements
-  (insert, then point at it), so a failure between them leaves an
-  unreferenced `entry_versions` row — invisible to every policy and
-  harmless, but it accumulates. *(2026-09-06)*
-- `move` is best-effort across two statements (reorder, then path rewrite):
-  a failed rewrite restores each destination sibling's prior `sort` row by
-  row, so a failure in the rollback itself still leaves the order changed. *(2026-09-05)*
-- Rollback gaps that remain: a `smoodly_reorder`/`smoodly_reorder_pages`
-  failure AFTER the re-parent update has no rollback at all; the entry
-  `create` rollback discards its delete result (an orphan row survives
-  silently); and a throw inside any rollback replaces — masks — the original
-  error. *(2026-09-05)*
-- `setTemplate`/`saveDraft` insert the version row before the pointer update:
-  an infra failure between the two orphans a version. *(2026-09-05)*
-
-#### Addresses and code-owned records
-
-- `homePageSlug` is compared with a collection's whole default path, so
-  `"home/news"` passes boot with the home page as its middle part: the
-  home record serves `/`, so `/home` is no page while `/home/news` is.
-  Refuse an address whose first part is the home slug if a site trips on
-  it. *(2026-09-29, nested collection paths)*
-- An owner key that changes in code — a fixed page that becomes a
-  collection's index page (`page:x` → `collection:y`), a collection
-  renamed — leaves the old record "No longer in code" with its
-  sections and history, and a new empty record takes the address.
-  Carry the record over (rewrite `fixed`) when a site asks. *(2026-09-29, nested collection paths)*
-- An index page registration renamed (`a` → `b`) leaves the record on
-  template `a`: `ensureFixedNodes` only handles a folder gaining an
-  index page, and `setTemplate` refuses a record that has one. *(2026-09-29, nested collection paths)*
-
-#### Security
-
-- The bridge posts with `"*"` on both sides. Safe today: the admin
-  accepts a message only when `e.source` is its own iframe's window, and
-  the canvas acts on two kinds, refresh and scroll. The target-origin
-  pass belongs to the content-surface sweep (spec §Out of scope). *(2026-09-26, security pass)*
-- The invite's `redirectTo` is a client-supplied string bounded by the
-  auth project's redirect allow-list; a same-origin check in the op is
-  one line when wanted. *(2026-09-26, security pass)*
-- The content-surface sweep: `f.link` values reach section components
-  unfiltered, uploads allow SVG and PDF on a public bucket (SVG served
-  with `?download=`), the custom CSS refusal list, richtext hrefs. *(2026-09-26, security pass)*
-- `RichText` drops the anchor of a link mark whose href is not http(s),
-  mailto, tel or site-relative (`/`, `#`, `?`, `.`). The href is normalised
-  the way URL parsers do (tab, LF and CR removed) before the scheme test;
-  `javascript:`, `data:`, protocol-relative `//host` and the backslash form
-  `/\host` are rejected. The admin's link field does not validate on input yet. *(2026-09-07, list field)*
-
-#### The live site
-
-- A section's crash on a live page after data changed outside the page
-  editor (an entry or a global item edited in its form): the guard
-  catches a throw in the section's own view, but one inside a component
-  it renders, in a richtext element's view or in a `'use client'`
-  section still fails the page, and no canvas previews those forms.
-  Catching it live needs `<Suspense>` (spec 2026-09-27 section guard,
-  measured). Revisit if a real site hits it. *(2026-09-27, shadowed-page detector)*
-- Publishing a global the site layout reads (the footer) serves the old
-  layout on the first public request made right after the publish returns;
-  every request after it, and a first request made ~3 s later, is fresh.
-  Pages do not show it (an unpublish answers 404 at once). Seen on
-  `next dev`; `e2e/globals.spec.ts` polls the home page for it. Find out
-  whether `updateTag` over a layout's `getGlobal` read expires late, and
-  whether `next start` behaves the same. *(2026-09-26, browser suite)*
-- A robots `Disallow` for the admin path from `next/meta`. *(2026-09-17, admin path)*
-- Scripts and the seed write through the stores and expire nothing; a
-  `revalidate` hook for out-of-band writers. *(2026-09-11, queries)*
-- Delivery caching (checked 2026-09-08): Supabase Storage's basic CDN
-  fronts every public-bucket object on a hosted project with no code on
-  our side, and the Smart CDN (Pro plan, automatic) only adds
-  invalidation on overwrite, which never happens — objects are
-  immutable, no upsert on either path, Replace picks a new id. So both
-  upload paths now set a year-long `cache-control`
-  (`MEDIA_CACHE_SECONDS`): the `cacheControl` option on the server-side
-  upload, the header on the browser's signed PUT (without it a signed
-  upload lands as `no-cache`; Storage's default is one hour). The live
-  suite reads the header back from the local stack. Not yet verified
-  against a hosted project's CDN edge; check `cf-cache-status` and
-  `cache-control` on a real upload there once. Remaining: in v1 the
-  site's `<SmoodlyImage>` goes through `next/image`, so the visitor hits
-  the app server's image cache and only its origin fetch touches the
-  CDN; video, files and SVGs hit the CDN directly. A Supabase Image
-  Transformations loader (`/storage/v1/render/image/public/...`, Pro
-  only, must stay optional) would move resizing to the CDN — the transform
-  loader under Cloud. *(2026-09-08, media library)*
-- `examples/site/smoodly/server.ts` should carry `import "server-only"` now that it also exports `publicAuth` — a client-side import would fail loudly at build instead of at runtime. *(2026-09-04)*
-- Empty locked zones on the site side: `renderPage` renders nothing for a locked zone with no node. A page that predates the zone shows no prefooter on the published site until an editor opens it (the editor fills and saves). Options: render the component from `sample` when the zone is empty, or fill on `createPage`/schema load server-side. Fine for now — seeded and admin-created pages both arrive filled. *(2026-09-03)*
-
-#### The editors
-
-- A visual global item's settings misfits (`settings.x`) don't reach
-  their widgets in the Globals form: `GlobalFields` keys errors by the
-  bare field key, the same gap the validator's refusal keys had before.
-  The notice and the refusal list still name them. *(2026-09-27, editor safety)*
-- A `refList` on a global item's `settings` still loads no options in
-  the Globals form or the page editor: both collect targets from the
-  item's `fields` only. *(2026-09-17, reference picker and tags)*
-- A validation failure on a shared save retries with backoff like a
-  transport failure; the field error shows on the widget meanwhile. A
-  distinct "fix the field" state would stop the retries. *(2026-09-13, shared inline editing)*
-- Escape inside any inspector control bubbles to the editor's window
-  handler and clears the block selection — the link popover stops it, a
-  textarea or the TipTap content does not. A `keydown` guard on
-  `.sm-inspector` would fix it for every control. *(2026-09-08, richtext widget)*
-
-#### Admin
-
-- Left open by the pre-install fixes' final review (2026-09-29): the pill
-  has `href="#"` on Exit and no keyboard way to move it; it appears after
-  a soft navigation from a non-Smoodly route only once the page reloads
-  (React never runs a script it creates on the client); a remounted view's
-  `pages.get` can read the draft before the outgoing view's `close()` save
-  commits (the next edit then meets `StaleBanner`); an in-flight save that
-  fails after `close()` is not retried; a required `radio` with no value
-  shows no pill pressed while the list item now stores the first option,
-  and `nodeFromSample` seeds a required `select` as `""`; `useLeaveGuard`
-  has no caller left; `examples/site/.env.local.example` lacks `SITE_URL`.
-  *(2026-09-29, pre-install fixes)*
-- `admin/ui/theme.tsx` pulls Public Sans from Google Fonts with an `@import`.
-  Fine today; a self-hosted font (or `next/font` in the glue layer) removes the
-  third-party request and the flash before it loads. *(2026-09-05)*
-
-#### Performance
-
-- `pages.get` makes four sequential store round trips for a non-root page
-  (`getPage`, `getDraftTree`, `pathsOf`, and the parent read behind
-  `parentLocales`; three for a root, which has no parent to read), and the
-  editor calls it on load and after every rename — one store call
-  returning them all would cut the editor's latency. *(2026-09-06)*
-
-#### Code health
-
-- `classify` in `ops-impl.ts` is ~20 order-sensitive substring checks over
-  store messages — `"already exists in locale"` must precede
-  `"already exists"`, or an addLocale conflict reads as a slug conflict. A
-  typed code on `pageErrors` (thrown and matched, not re-parsed) would
-  remove the ordering hazard before plan 2 adds the entry messages. *(2026-09-06)*
+## Install
 
-#### Tests and CI
-
-- The blank-intl starter is typechecked, not walked: the first tester-agent
-  mission (each tester site on its own local Supabase stack, two at a time),
-  after the 0.0.35 release. *(2026-09-15, locale alternates)*
-- Drag and drop has no browser test (spec §4): the outline, the pages
-  tree and list rows reorder by real pointer drags; the first plan that
-  touches `useSortable` adds them. *(2026-09-26, browser suite)*
-- The suite runs Chromium only; the admin's WebKit and Firefox
-  behaviour is unverified. *(2026-09-26, browser suite)*
-- The seed's early exit probes `/` alone, and `createPage` writes the path
-  row before the tree is published, so a crash between the home record and
-  the last page leaves a database every later run reports as "already
-  seeded"; recovery is `supabase db reset`. A probe on the last thing the
-  seed writes, or a per-step check, would make it resumable. *(2026-09-07, starter)*
-- The package root (`src/index.ts`) must stay free of Node builtins:
-  every scaffolded section does `import { f, smoodly } from "smoodly"`,
-  and a `"use client"` section's browser build would fail on one.
-  `sharedEntryId` (`src/shared-id.ts`) moved off `node:crypto` onto Web
-  Crypto for this reason (fix pass, 2026-09-07). Nothing tests the
-  invariant itself — a future addition that reaches for `node:fs`,
-  `node:crypto`, etc. from a module reachable through the root would
-  regress it silently. *(2026-09-07, shared content)*
-- The single-language branch — no locale selector in the Pages list, no
-  switcher, no add/remove — has no automated coverage; only three sites
-  branch on the locale count (`PagesList.tsx`, `EditorView.tsx` and
-  `page-renderer.tsx`'s alternates), so a regression there shows up only
-  in a scaffolded single-language app. *(2026-09-06)*
-- The no-database build is the real proof that routes never prerender against the stores; the unit test only stubs `next/server`. Script it (`SUPABASE_URL=http://127.0.0.1:9 npx next build` in `examples/site`, expect `ƒ /`) and add it to CI, which today runs only the package's tests and typecheck — so a regression is caught when Next changes `connection()` semantics. — Partly resolved 2026-09-26: the `browser` job builds the example site and drives it, but with a database; the no-database build is still unscripted. *(2026-09-03)*
-
-### Later
-
-#### Page editor and inline editing
-
-- The page editor's publish banner lists fields as plain text; the forms'
-  lines focus the widget. Selecting the node from a `node.field` path is
-  the missing piece. *(2026-09-14, collections draft/publish)*
-- Richtext instant write from the inspector: the pure `RichText` render
-  swapped into the container while the widget is typed in. *(2026-09-10, inline editing)*
-- Item-level chrome in the canvas ("Key points · 3 of 4" on hover, add,
-  remove, reorder in place, later drag within a list): the item marks are
-  the hook. *(2026-09-10, inline editing)*
-- Placeholder and validation marks on the page (the sample-sourced
-  placeholder treatment, "required, empty" outlines) wait for the tree's
-  placeholder marking. *(2026-09-10, inline editing)*
-- A coverage hint for developers: the admin knows a section's text fields
-  and could list the ones without a mark. *(2026-09-10, inline editing)*
-- AI verbs ("rewrite this heading") need a field under the cursor, which
-  a mark is. *(2026-09-10, inline editing)*
-- Direct-child spacing rules on a richtext container (Tailwind `space-y-*`,
-  `.prose > p`) do not reach the canvas editor's blocks during a session;
-  flex and grid gaps are copied (onto the ProseMirror root since the
-  walk, 69aecc6). Documented, not fixed. *(2026-09-10, inline editing)*
-- The floating toolbar flips below the caret only near the top of the
-  DOCUMENT (where the page box clips it); it scrolls with the content, so
-  a caret at the top of the scrolled canvas has its toolbar out of view
-  until the editor scrolls. A flip keyed to the scroller's viewport would
-  fix it. *(2026-09-10, inline editing)*
-- No starter section gives the canvas a richtext with blocks: the Image
-  and text body is marks-only, and the article body (the `article`
-  toolset) is edited in the entry form. The walk borrowed the article
-  toolset for the block steps; a starter section with a long-form body
-  would let the canvas show them. *(2026-09-10, inline editing)*
-- The caret placed right after an existing `/` reopens the slash menu
-  (TipTap's suggestion re-triggers on the character before the caret).
-  Harmless; a trigger keyed to typing only would be stricter. *(2026-09-10, inline editing)*
-
-#### Richtext and elements
-
-- Image sizing and float in a body (full width, wide, small, left/right):
-  a later additive `styles` on the image node; the site's CSS answers it. *(2026-09-08, block nodes)*
-- Inline elements: `inline: true` on the registration; cursor, marks and
-  selection around an inline atom are a separate node-view effort. *(2026-09-08, block nodes)*
-- The column context (`contexts: ["column"]`) waits for Phase 3 rows;
-  accepted and unused today. *(2026-09-08, block nodes)*
-- Element copy between fields: a pasted element the target toolset
-  forbids is dropped silently; a notice would be kinder. *(2026-09-08, block nodes)*
-- `hasContent` treats an unresolved image node as content, so a body
-  whose only image was deleted from the library still passes "required". *(2026-09-08, block nodes)*
-- The "+" menu and the slash menu share `RichtextInsertMenu` but keep
-  separate active-row state and key handling; one keyboard model would
-  be smaller. *(2026-09-08, block nodes)*
-- A page and entry picker in the link popover: a link inside a richtext
-  document is a reference the refs index, the resolver and the localizer
-  cannot see (they address refs by top-level key). Its own spec. *(2026-09-08, richtext widget)*
-- Every richtext descriptor now carries its toolset, so the serialized
-  registry grew by a few bytes per field; if the AI-facing schema wants
-  the vocabulary once instead of per field, dedupe there. *(2026-09-08, richtext widget)*
-
-#### Forms, fields and pickers
-
-- A `Create…` button in the reference picker: create the target entry
-  without leaving the form. Needs its own answer for modal vs navigation
-  and for the parent form's pending autosave. *(2026-09-17, reference picker and tags)*
-- Thumbnails in picker rows: collections have no preview-image
-  convention (`titleField` only). *(2026-09-17, reference picker and tags)*
-- Tags keep insertion order; no drag reorder. *(2026-09-17, reference picker and tags)*
-- Tag suggestions exist on collection entry forms only, and only for
-  top-level `f.tags()` fields: a tags field inside an object, on a
-  section, a global or a page is a plain chip input. *(2026-09-17, reference picker and tags)*
-- The picker's "open" link goes to `/admin/<collection>/<id>` without
-  the edited locale; the form opens in the URL's or the default locale. *(2026-09-17, reference picker and tags)*
-- The Combobox list is portaled into the admin wrapper and fixed to the
-  viewport (2026-09-27), so a modal body or scrolling form no longer
-  clips it; it flips upwards when the viewport has no room under the
-  input (`listPlacement`) and follows the input on scroll. It does not
-  yet shrink when neither side has room for it. A single select (a
-  single `f.ref`, the redirect target) shows its pick inside the input;
-  a single ref's status, open link and remove sit in the input too. *(2026-09-17, reference picker and tags)*
-- A create dialog (title and slug) before "+ New entry", if empty Untitled
-  drafts turn out to litter lists. *(2026-09-14, collections draft/publish)*
-- `f.date()` and `f.datetime()` share one in-house calendar
-  (`admin/forms/DatePicker.tsx` over the pure `date-picker.ts`); the
-  browsers' own pickers were rejected (they differ and take no tokens).
-  Weeks start on Monday and month names come from the browser's language
-  — `weekStart` and a month-name locale as config keys are follow-ups. *(2026-09-25, date pickers)*
-- Not built: a time-only field, a date range, `.min` / `.max` on dates. *(2026-09-25, date pickers)*
-- Refs inside lists and objects are refused at build time (`f.list`,
-  `f.object`). A list of objects each holding a ref (a featured entry with
-  its own caption) needs the resolver, the refs index and the admin's
-  ref-option loading to address nested paths; add when a site asks. *(2026-09-07, list field)*
-- `emptyValue` for an `image`/`video`/`file` item is `undefined`, so a new
-  media row starts empty; a required image item is then a validation
-  error until filled, which is the intended nudge but reads as an error
-  on a row the editor just added. *(2026-09-07, list field)*
-- A list item's subtree still uses the row index as its React key, so a list
-  of objects each holding a list hands the inner rows another item's collapse
-  state when an outer row moves; fix with a stable per-item key when nested
-  lists get real use. *(2026-09-07, list field)*
-
-#### Custom sections and section settings
-
-- Inline editing of a column on the canvas is OFF (2026-09-15, after the
-  first day's use): a click on a column reveals its editor in the
-  inspector (`onFieldClick` in `EditorView.tsx` skips the session for the
-  `custom` type). The marks, paths and session code are in place and
-  tested; turn it on once a walk on a real device passes. *(2026-09-15, custom section)*
-- A canvas drag on column edges (today the bar in the inspector). *(2026-09-15, custom section)*
-- A background for a custom section from a config palette. *(2026-09-15, custom section)*
-- Elements as direct column children (today through richtext's menus). *(2026-09-15, custom section)*
-- A per-zone cap on columns (`custom: { columns: 2 }` or similar). *(2026-09-15, custom section)*
-- Presets exist for 2, 3 and 4 columns; 5 and 6 have the bar only. *(2026-09-15, custom section)*
-- Rows reorder with the ↑/↓ buttons only; no grip, no keyboard drag. *(2026-09-15, custom section)*
-- An empty column has no box on the live page (an empty paragraph
-  renders 0px tall), so it cannot be clicked into from the canvas; the
-  inspector's `Column N` editor is the way in. A `min-height` in editor
-  mode would give it a target. *(2026-09-15, custom section)*
-- An empty column publishes (its richtext descriptor is `optional`);
-  whether publish should refuse a row of only empty columns is open. *(2026-09-15, custom section)*
-- Growing a row copies the LAST span before renormalizing, so `[5, 7]` →
-  `[3, 5, 4]`, not thirds; a preset is one click away. Equal thirds on
-  grow would be the other reasonable rule. *(2026-09-15, custom section)*
-- A class-mapping API for projects that want the wrapper to emit
-  classes instead of inline values (DESIGN.md OQ 13). *(2026-09-15, section settings)*
-- `f.global()` — a ref field on a section that renders a global item. *(2026-09-15, section settings)*
-- An AI helper filling the CSS box from a prompt (the box stores CSS,
-  never a prompt, so the helper only fills it). *(2026-09-15, section settings)*
-- `and` / `or` conditions; today one `f.when()` per field. *(2026-09-15, section settings)*
-- A condition inside a list item can read the item's siblings and the
-  top-level namespaces, not another item; per-item scoped `settings.`
-  references inside lists are not a thing yet. *(2026-09-15, section settings)*
-- An element's settings cannot be hidden by the enclosing section's
-  settings: an element card's scope is the element's own fields and
-  settings. *(2026-09-15, section settings)*
-- A hidden field's refs still count as usage in the refs index (its value
-  is kept, so the edge is real; whether usage should hide with it is open). *(2026-09-15, section settings)*
-
-#### Globals
-
-- Layout items in the outline: a "From the layout" group the bridge could
-  populate from the `shared:` ids it reports; canvas-only today. *(2026-09-13, shared inline editing)*
-- The shared card's usage line lists page ids; titles need a pages
-  lookup the editor does not hold (the usage rows carry only ids). *(2026-09-13, shared inline editing)*
-- A "save and publish" action for sites that want no draft stage on a
-  shared item (every item is versioned since 2026-09-13; the flag is
-  gone). *(2026-09-13, shared inline editing)*
-- The picker offers a shared item only in zones whose allow list includes
-  its section (`allowedShared` in `admin/tree-ops.ts`), so a shared item's
-  section is always also offered as an ordinary section. A "placeable
-  only" mode (a shared item whose section no zone lists) would let the
-  starter keep the quote shared-only. *(2026-09-07, starter)*
-- `f.shared(() => item)` — a ref field on a section that renders a shared
-  item inside the section's own markup (spec 2026-09-07 decision 3). *(2026-09-07, shared content)*
-- Instance mode: a shared *type* with many editor-created items; today
-  the answer is a collection plus a section with `f.ref` (decision 1). *(2026-09-07, shared content)*
-- Zone-shaped shared items (`smoodly.shared({ zone })`) (decision 2). *(2026-09-07, shared content)*
-- Standalone live preview on a visual item's admin page — would need a
-  preview route in the glue. Less pressing since 2026-09-13: every shared
-  render is edited in the page canvas, and the Globals page is the form. *(2026-09-07, shared content)*
-- Built-in meta on shared items and on placements (anchor per placement
-  is the likely shape). *(2026-09-07, shared content)*
-- A placement of an object item or an unregistered item gates the page's
-  publish (the refs edge is emitted without a registry lookup) yet never
-  renders; only a hand-edited tree can produce one. *(2026-09-07, shared content)*
-
-#### Drag and drop
-
-- Cross-zone drag in the outline: each zone is its own sortable list;
-  moving a block between zones is still insert-and-remove. *(2026-09-09)*
-- Nested manual collections show no grip (`canReorder` requires
-  `depth === 1`) until the entry tree UI exists — a flat index is not a
-  sibling index there. *(2026-09-09)*
-- Canvas drag: the overlay should reuse `ui/sortable.ts` across the
-  iframe boundary; `useSortable` measures container children, which the
-  overlay's ghost rows can be. *(2026-09-09)*
-- A dragged subtree stays collapsed after the drop (`onDragStart`
-  collapses it through `toggle` and nothing re-expands it). *(2026-09-09)*
-
-#### Admin UI
-
-- The Globals page has no tab row: Content's groups, then a `Settings`
-  label and the Settings groups, stacked. A tab row there would match the
-  canvas card. *(2026-09-15, section settings)*
-- The warm look is the comparison block now (`WARM_*` + `WARM_EXTRA` in
-  `src/admin/ui/theme.tsx`, `localStorage.smoodly-look = "warm"`); the
-  technical block is deleted (tag `look-technical` keeps it). Remove the
-  warm block once the neutral look is judged, the same way. *(2026-09-25, neutral restyle + confirm dialog)*
-- Keep the previous view painted until the next one has data: today a
-  navigation switches instantly and the new view shows its own loading
-  state; a transition that holds the old view, or prefetches the next
-  view's ops call on hover, is the next step. *(2026-09-08, client routing)*
-- `LocaleSwitcher` in pill form has no "+ add" affordance: an absent
-  locale reads subtle and switching to it lands on the form's or the
-  editor's "doesn't exist yet · Add" pane, which adds. The dropdown form
-  (four locales and up) still adds straight from its "Add locale" group,
-  so the two forms differ by one click; a "+" inside the pill would close
-  that gap. *(2026-09-09, admin tweaks)*
-- The image field's canvas height (300px) lives twice: `CANVAS_H` in
-  `MediaWidget.tsx` sizes the frame, `.sm-media__canvas` /
-  `.sm-media__thumb` cap it in the stylesheet. One token would do. *(2026-09-09, admin tweaks)*
-- `.sm-form>*{max-width:680px}` caps the banner too; if a wide
-  field type ever appears (a table), give it an opt-out class. *(2026-09-09, admin tweaks)*
-- An element card decides "open" from its fields alone (blank = open);
-  an element whose fields are all optional and empty by design stays
-  open on every load. The richtext image card is never collapsible. *(2026-09-09, admin tweaks)*
-- The "+" menu anchors to the toolbar's right end (`right:0` in
-  `.sm-richtext__head`), which is under the "+" only while the toolbar
-  fits on one line; in the 320px inspector the toolbar wraps and the
-  menu sits below the wrapped row's end. *(2026-09-09, admin tweaks)*
-- The entry form's column is narrower than the inspector, so the default
-  toolbar wraps to two rows there; the inspector shows it on one. *(2026-09-08, richtext widget)*
-- A list row's collapsed summary shows the item's first string subfield —
-  the header nav rows read `/`, `/posts` — where the label would identify
-  the row; `itemSummary` could prefer a `label`/`title`/`heading` key
-  (walk, 2026-09-07). *(2026-09-07, starter)*
-- Page settings prints `paths[locale]` under each slug field — the
-  locale-relative CMS path, not `urls[locale]`, the site URL the canvas
-  and "View live" actually open. On a translated site the Finnish hint
-  reads `/yritys/tietoa-meista` while the page lives at
-  `/fi/yritys/tietoa-meista`. Both maps are already in `EditorView`;
-  which one belongs under the field is a UI decision, not a missing
-  value. *(2026-09-06)*
-- The row menu in `PagesList.tsx` does not close on Escape — only a click
-  on the backdrop closes it. *(2026-09-06)*
-- `PageSettings` re-seeds its inputs from `record` on every rename (and
-  every publish), so keystrokes typed while a rename is in flight can be
-  dropped. The blur- and Enter-driven commits themselves are unaffected. *(2026-09-06)*
-- A childless folder row is inert on click (a mount opens its collection,
-  a page opens the editor, a folder with children expands); "Add page
-  here" lives in the row menu only. *(2026-09-06)*
-- The tree rows nest interactive buttons — the chevron and the `···`
-  menu — inside a `role="button"` row. It works, because both stop the
-  click and the keydown, but it is an accessibility smell a real treegrid
-  would not have. *(2026-09-06)*
-- The Pages list offers "Add <locale>" on a dimmed row whose parent lacks
-  that locale, and learns the refusal only after the round trip.
-  `pagesTreeRows` already carries every node's locales, so the parent's
-  presence could disable the item with its reason up front, exactly as
-  the editor's switcher does with `parentLocales`. `EntriesList` has the
-  same gap (and `entryRows` would have to carry the locales again — the
-  dead field was deleted rather than left unused); it is unreachable
-  today, since nothing in the admin creates a child entry. *(2026-09-06)*
-- Design system pass (DESIGN.md §2, "The admin's visual system"): the shell,
-  lists, entry form, login and editor were restyled onto `admin/ui/theme.tsx`.
-  Deferred deliberately, because each is a feature rather than a restyle: the
-  list search field and status filter, the locale select in the shell's top bar
-  (the editor has one; the lists always read the default locale), the article
-  sidebar's taxonomy/SEO/publish-date sections, and the rich-text toolbar. The
-  pages list's tree shape (chevrons, depth indent) and its row `···` menu
-  shipped 2026-09-06, without the drag handle. The tokens for all of them are
-  already in place. *(2026-09-05)*
-- `lucide-react` is now a runtime dependency, for the toggle's two icons. The
-  rest of the UI still uses the design system's unicode glyphs (↑ ↓ ⧉ × ··· ▾
-  ← ⋮⋮); swapping them for Lucide is the next step whenever it is wanted. *(2026-09-05)*
-
-#### Addresses and the Pages tree
-
-- The rename/move confirm's code-address line names the addresses in
-  the selected locale only, though a move re-paths every locale; the
-  Pages list's conflict notice is one ellipsized line (the whole text
-  on hover), and an editor's flagged page cannot be moved from the
-  notice itself. *(2026-09-29, nested collection paths)*
-- An index page removed from code leaves the collection's record with
-  its template (spec amendment 3): the record keeps rendering as that
-  page type's stale name until an editor or a later pass clears it. *(2026-09-29, nested collection paths)*
-
-#### Collections
-
-- Nested entries have no admin UI beyond `entries.move`: nothing creates
-  a child entry or shows the entry tree, and the entry form's slug prefix
-  is the collection's mount base only, not the parent chain. *(2026-09-06)*
-- A published entry under a draft parent is dropped from `getEntriesTree`
-  (the parent is not in the list to hang it from) but returned flat by
-  `getEntries`. Untested either way. *(2026-09-05)*
-
-#### Queries (`q`)
-
-- `presence()` serves the presence channel only; a future read gateway (DESIGN.md OQ 31) is not built on it — no key but a write key reads content. *(2026-09-26, concurrency; 2026-09-30 §8)*
-- `where` ranges and negation. *(2026-09-11, queries)*
-- `EntryItem.updatedAt`, and `order: updatedAt`, read the LIVE locale row, so a draft autosave bumps the public timestamp and can reorder a public list; read the published version's `saved_at` for published reads. *(2026-09-30, content API contract final review)*
-- The bare-slug `getEntry` fallback re-reads the whole collection and resolves every entry's references and media before matching one slug; match on `record` first, then resolve only the hit (or query by slug). *(2026-09-30, content API contract final review)*
-- `SmoodlySite.resolve` (and `load`) still return the full `EntryRecord` (every locale, `updatedBy`) on the object the developer holds; the types are unexported and the spec calls it internal — mark it `@internal` or move both off the public interface. *(2026-09-30, content API contract final review)*
-- A nested `.resolve({ a: { b: true } })` types only the top level (`Rebase<V, keyof P>`) while the runtime resolves deeper; type the nesting. *(2026-09-30, content API contract final review)*
-- Any-of over an array-valued field: any-of compares the text form of
-  the field, so it covers selects, refs and numbers; on a checkboxes,
-  refList or list field `site.getEntries` refuses it rather than match
-  nothing — both adapters agree on the text form, so a one-element array
-  never matches its element. *(2026-09-11, queries)*
-- `getEntriesTree` has no `q` counterpart yet; add one when a site
-  needs a nested collection nav. *(2026-09-11, queries)*
-- `getShared(["header", "footer", "contact"], { locale })` returning a
-  typed tuple, as sugar over the `Promise.all` the layout writes today.
-  Keep one cache unit per item under its own tag — a single unit tagged
-  with all three would expire the header whenever the footer is edited. *(2026-09-11, queries)*
-- An explicit JSON `null` VALUE in a declared `order.by` field sorts
-  FIRST in Supabase (a jsonb null is the lowest jsonb value, not SQL
-  NULL, so `nullsFirst: false` does not reach it) and LAST in memory. A
-  MISSING key is SQL NULL and sorts last in both, and the admin only ever
-  produces that — a cleared number field emits `undefined`, which the
-  JSON body drops — so this needs a programmatic or external writer.
-  Mixed types in one field diverge for the same reason: Postgres orders
-  jsonb by type first (null < string < number), memory by `String(...)`. *(2026-09-05)*
-
-#### SEO and page fields
-
-- A `styles` block on pages, when a case needs presentation separate
-  from content. *(2026-09-10, page fields and SEO)*
-- Refs in page fields, once the refs index walks them. *(2026-09-10, page fields and SEO)*
-- A canonical URL field and a search-result preview snippet in the
-  SEO & Social tab. *(2026-09-10, page fields and SEO)*
-- Configurable SEO set (`meta: { seo: { twitter: true } }`) if the four
-  values prove too few. *(2026-09-10, page fields and SEO)*
-- Link fields are raw: an image in a page field reaches a nav link as
-  `{ asset, alt }`, not a URL. Resolve on demand if a nav ever wants one. *(2026-09-10, page fields and SEO)*
-- Page-field labels derive from the key (`showInNavigation` → "Show In
-  Navigation"), as every field's do; a `.label()` builder option would
-  read better for long keys. *(2026-09-10, page fields and SEO)*
-
-#### Site rendering and starters
-
-- A separate canvas route would take the last Smoodly bytes off live
-  pages (the lazy stub that loads the bridge and the canvas boundary in
-  the editor frame), at the cost of the frame no longer loading the
-  page's real address: the site's layout would have to be reached from
-  a sibling route, and a developer's own route file or the escape hatch
-  would preview differently from live. Only if a site needs zero.
-  *(2026-09-29, pre-install fixes)*
-- A layout-only language switch, if a real site needs one: a
-  `q().getAlternates(path)` over the `paths` index plus a proxy header
-  carrying the request path. Not built until asked for — the starters
-  render the switch from the page (`components/PageFrame.tsx`,
-  `components/LocaleNav.tsx`). *(2026-09-15, locale alternates)*
-- A paired component (`smoodly.section`) accepts only its schema's props, so
-  a layout cannot hand the footer the contact item or the header the locale
-  links through the paired `Footer`/`Header`; the starter's layouts render
-  `FooterView`/`HeaderView` directly with the extra prop. A supported way
-  to pass layout-only props through a paired component (or a `children`
-  slot) would let the layouts use the registered component. *(2026-09-07, starter)*
-- A per-locale collection path or fixed slug must name the default locale;
-  the installer rewrites the starter's two lines to name exactly the
-  chosen locales (`articlesSegments` in `scaffold.ts`), since a path
-  claiming a locale the site lacks fails the index-page rule at config
-  load. A "fall back to the first declared segment" rule in
-  `defineConfig` would make the patch unnecessary. *(2026-09-07, starter)*
-- Registry names are one namespace across sections, elements, collections
-  and page shapes (`assertUniqueNames`); the starter names its People
-  section `peopleSection` and its Articles page `articlesIndex` to stay
-  clear of the collections. Namespacing by kind would let a section and a
-  collection share a name. *(2026-09-07, starter)*
-- With `fi` as the default locale the seed writes the English content into
-  `fi`. Before this fix the index page was seeded at `posts`
-  while the collection's `fi` path is `artikkelit`, so `ensureFixedNodes`
-  materialized a second, empty Articles page at `artikkelit` and the
-  links pointed at `/posts`; the seed now derives the segment from the
-  collection's `path` per locale. Left: the starter's copy in a `fi`
-  default is still English. *(2026-09-07, starter)*
-- Cache tags are still `page:<id>`: publishing one locale expires every
-  locale's cached unit of that page (spec 2026-09-06 §4). A
-  `page:<id>:<locale>` tag would halve the revalidations on a bilingual
-  site. *(2026-09-06)*
-- Examples and guides write `url(entry.path!)`: `path` is `string | null` on every entry, though a collection that declares `path` always has one — type it `string` for those and drop the assertions. *(2026-09-30, content API contract final review)*
-- `smoodlyMetadata` does not apply the registration check `renderSmoodlyPath`
-  applies: a record whose `template` has no registration is a 404 body with
-  its meta emitted beside it. *(2026-09-05)*
-
-#### Media
-
-- Video transcoding and adaptive streaming: a Mux or Cloudflare Stream
-  loader behind the `media.loader` seam, if a site ever needs more than
-  an MP4 over Storage's CDN. *(2026-09-08, media library)*
-- Sweeping abandoned `pending` asset rows (an upload that began and
-  never called `finishUpload`); a periodic op or a cleanup on `list`. *(2026-09-08, media library)*
-- A private bucket with signed reads, for sites that must not expose
-  draft-only media by URL before publish. *(2026-09-08, media library)*
-- Pre-generated image variants at upload time, for hosts without sharp. *(2026-09-08, media library)*
-- Image dimensions server-side cover JPEG and PNG (`imageDimensions`); a
-  WebP or AVIF seeded through `AssetStore.create` lands without a size
-  and resolves to nothing until the row is edited. Browser uploads
-  measure every type. *(2026-09-08, media library)*
-
-#### History and publishing
-
-- Client-side undo in the editor (a stack of tree snapshots); the store
-  is no longer an undo stack by design. *(2026-09-13, history)*
-- The author per version row and in the lists; named versions. *(2026-09-13, history)*
-- History on the canvas card's menu and in the list row menus. *(2026-09-13, history)*
-- A diff between two versions. *(2026-09-13, history)*
-- The lists' row menus (Pages, Entries) do not offer Unpublish; the
-  document's own control does. *(2026-09-13, publish flow)*
-
-#### Collaboration
-
-- A hard lock with takeover, if a real team asks: presence has the facts. *(2026-09-26, concurrency)*
-- Presence on the members and media screens; today only pages, entries and
-  global items track. *(2026-09-26, concurrency)*
-- Postgres Changes for live list refresh; the lists still load on navigation. *(2026-09-26, concurrency)*
-- Field-level merging of two editors' changes; the guard refuses whole documents. *(2026-09-26, concurrency)*
-- A dropped socket clears presence on Realtime's timeout (tens of seconds); the
-  lock outlives a closed tab by that much. *(2026-09-26, concurrency)*
-
-#### Members
-
-- Members management shipped 2026-09-25 (spec
-  `docs/superpowers/specs/2026-09-25-members-management-design.md`); out
-  of its scope: a pending-invite status and "resend invite" on a row
-  (needs the Auth user's `last_sign_in_at`, which the cloud projection
-  does not carry); removing the Auth account together with the member
-  row; invites from the cloud's `/admin` (they are smoodly.io's); a
-  project whose Auth is OAuth-only (the invite mail asks for a password). *(2026-09-25, settings + members)*
-- The members list is not paged (tens of rows, not thousands). *(2026-09-25, settings + members)*
-
-#### Redirects
-
-- Destinations outside Smoodly, extension and query-string addresses,
-  code-owned renames (a collection `path`, a fixed slug): the guide's
-  `next.config` recipe; a `redirects` table is OQ 34. *(2026-09-26, redirects)*
-- The content API's `getPage("/old")` returns null for a redirect row
-  (spec §7); a `follow` option is a one-line addition if a site asks. *(2026-09-26, redirects)*
-- A redirect row has no audit columns (who, when); add them with a
-  need. The Redirects page is not paged. *(2026-09-26, redirects)*
-
-#### Export and import
-
-- `import --replace`: delete the space's content and media first, after
-  typing the space to confirm — a backup restored over a live project.
-  Mention it in the not-empty refusal when it lands. *(2026-09-28, export/import)*
-- A readable export for leaving Smoodly: one document per page or entry,
-  fields resolved, no internal IDs. *(2026-09-28, export/import)*
-- A "Download backup" button in the admin: the same export behind an op,
-  zipped for an editor. *(2026-09-28, export/import)*
-- Import cannot expire the app's cache tags; it prints a restart note. A
-  revalidate call through the app (an op the CLI could reach) would make
-  the note unnecessary. *(2026-09-28, export/import)*
-
-#### Content health and drift
-
-- Content health lists an entry slug outside the grammar, but its link
-  opens an entry form that marks nothing on the slug: drift leaves the
-  slug out on purpose (a marker would flash while it is typed), so only
-  the publish refusal marks it. Mark it in the form once the box has lost
-  focus, if editors miss it. *(2026-09-29, pre-install fixes)*
-- Content health does not check page slugs: pages refuse a bad slug at
-  create and rename, so only an import of older data or a hand edit could
-  hold one. *(2026-09-29, pre-install fixes)*
-- Refs inside unknown nodes are not indexed: without a schema nothing
-  says which values are refs, so safe-delete cannot see them. Publish
-  refuses such nodes and a live one renders nothing. *(2026-09-27, editor safety)*
-- Leftover shared values after `.localized()` is turned on stay on the
-  entry as every locale's fallback; removing them for good waits on
-  the fix tooling (OQ 35). `localization-on` is reported only where a
-  locale has no value of its own, so a fully translated entry no
-  longer lists it. *(2026-09-27, editor safety)*
-- A CLI drift report was left out (the admin already has the config and
-  the database; a CLI needs the service key and a TS config loader). *(2026-09-27, editor safety)*
-- Turning `.localized()` off for a field with per-locale values leaves
-  those values in `entry_locales.fields` until the next save of each
-  locale (a save writes only the current split) — the drift/codemod
-  pipeline (Phase 2) is where "keep en, discard fi" belongs. *(2026-09-06)*
-
-#### Schema and migrations
-
-- The views of a removed collection stay (spec 2026-09-26 §3); a
-  `drop view` is the developer's. *(2026-09-26, schema migrations)*
-- `smoodly migrate` never pushes; a `--push` flag if the two-step
-  proves annoying. *(2026-09-26, schema migrations)*
-
-#### Data lifecycle
-
-- A locale dropped from `locales.supported` leaves its `page_locales`,
-  `page_versions` and `paths` rows in place but unreachable — nothing
-  lists or serves them, and nothing cleans them up. It is the mirror of
-  the materializer's top-up, and wants the same deliberate answer (an
-  admin-visible orphan list, or a prune op). *(2026-09-06)*
-- `addLocale` does not bump the entry's `updatedAt` while `removeLocale`
-  does. Both adapters agree, so the contract is honest, but "adding a
-  language is not an edit and removing one is" is arbitrary — decide it
-  deliberately before someone sorts a list by Updated. *(2026-09-06)*
-- No `rebuildPaths()`: the index is documented as derived and rebuildable, but
-  nothing rebuilds it. *(2026-09-05)*
-
-#### Config and registration
-
-- `LOCALE_CODE_RE` accepts any 2–4 letter subtag as script or region
-  (`en-ZZZZ` passes), and a duplicate entry in `supported` passes
-  silently — boot validation catches typos in shape, not in fact. *(2026-09-06)*
-- `entryPathRows` relies on the stores validating locale keys on write
-  (no guard of its own); `list`/`getMany` accept an unsupported locale
-  silently and read as "no content". *(2026-09-06)*
-- `sections` is passed twice — to `createSmoodlySite` (ref resolution) and to
-  `createPageRenderer` (the component map) — and `elements` cannot be passed
-  at all; the two lists can drift silently. *(2026-09-05)*
-- `SmoodlyConfig.registry.pages` (`Registered` in `src/config.ts`) has no
-  call signature, so every app's glue casts it `as PageRegistration[]`. *(2026-09-05)*
-- Two `entryPage` registrations for one collection are silently accepted.
-  `PageStore.rename` still accepts a locale outside `supported`; the admin
-  op rejects it first, so only a direct store caller reaches it. *(2026-09-05)*
-
-#### Scale and performance
+    npx create-smoodly-app my-site
 
-- `listLive` / `listRedirects` on Supabase read at most PostgREST's
-  `max_rows` (1000) per locale, as before, now ordered by (anchor, path)
-  and sorted by URL in JS; page them if a locale's redirect list grows
-  past it. *(2026-09-29, nested collection paths)*
-- Scan paging: `health.scan` makes one bulk read per table (versions by
-  id in chunks of 100), and PostgREST's max-rows would cap a very large
-  space. Page it, and add a rail badge, when a real site's size asks. *(2026-09-27, editor safety)*
-- Server search for ref candidates: `useRefOptions` loads the whole
-  target collection once per locale. When a collection outgrows that,
-  the hook changes (a search op, plus "titles for these ids" for the
-  picked rows); `RefPicker` takes options as a prop and does not. *(2026-09-17, reference picker and tags)*
-- `entries.distinct` flattens in JS over `entries.list`; an RPC over
-  `jsonb_array_elements` when a collection outgrows it. *(2026-09-17, reference picker and tags)*
-- `InspectorFields` filters hidden entries per render; a section with
-  many conditions re-evaluates every keystroke. Fine at the sizes seen. *(2026-09-15, section settings)*
-- Ops are built per call (`createAdminOps` inside the handler) so the
-  session rides in as `actor`; if that ever measures, memoize the
-  actor-free parts. *(2026-09-13, history)*
-- A GIN index on `entries.fields` when a customer's collection is large
-  enough to need it; additive, no migration. *(2026-09-11, queries)*
-- Every revalidating op (publish, delete, a save of published content)
-  answers with a fresh RSC render of the admin route — the layout's
-  styles included, ~30 KB — because `updateTag` runs inside the server
-  action and Next re-renders the tree it was posted to. Harmless now
-  that the shell lives in the layout (the empty page subtree is what
-  remounts), but it is the price of server actions as the transport. *(2026-09-08, client routing)*
-- `getSmoodlyShared` reads the store per request in draft mode and once
-  per (item, locale) otherwise; a layout calling it for several items
-  makes one round trip each — batch if it shows. *(2026-09-07, shared content)*
-- `ops.shared.get` runs `ensureSharedItems` and then lists the item
-  again; one round trip could go. *(2026-09-07, shared content)*
-- `ensureSharedItems` runs on every `ops.shared.list()` — which is every
-  editor mount, not only the Shared content page — costing one
-  `entries.list` per registration per open. *(2026-09-07, shared content)*
-- `fanOut` resolves every shared registration's row id (one
-  `entries.list` each) on every entry write, so it can expire
-  `shared:<name>` when something the item references changes; a row-id
-  cache would remove the reads but has to survive materialization. *(2026-09-07, shared content)*
-- `ensureFixedNodes` runs on every `pages.list` and every ROOT
-  `pages.create` — one `listPages()` each, and a second one when it
-  tried to create something. It also treats a root record sitting at a
-  fixed slug as that node even when its `template` is a foreign one: the
-  node is adopted, never recreated, and the ops then guard it as
-  code-owned. *(2026-09-06)*
-- `fixedNodeSpecs(config)` rebuilds the whole spec list on every
-  `fixedNodeOf` call, and the ops call `fixedNodeOf` per guarded write. A
-  `WeakMap` memo keyed by the config object is the whole fix. *(2026-09-06)*
-- `SupabasePageStore.updateLocale` re-reads the record (`must(id)`) after
-  every update, so `setTemplate` is N+1 in the page's locales: one update
-  and one full read each. Only the last read is used. The Supabase entry
-  adapter is the same shape: `create` is insert → insert → read →
-  version → read → paths → refs, and `removeLocale` re-fetches the entry
-  three times. *(2026-09-06)*
-- `entries.list` filters `{ locale, status }` in memory after fetching
-  every row (PostgREST cannot filter the parent by an embedded row
-  without `!inner`, which would drop the other rows); fine at collection
-  sizes today. *(2026-09-06)*
-- `assertPublishable` (`store.ts`) awaits one `entries.get` per
-  referenced entry, sequentially, on every publish — a `refList` of a
-  dozen articles is a dozen serial reads, now per locale. `getMany(ids,
-  locale)` takes exactly that shape and would make it one call. *(2026-09-06)*
-- `loadPage` calls `listPages()` for ancestors and children on every cache
-  miss; fine for hundreds of nodes, a `children(id)`/`chain(id)` store query
-  is the fix when a site outgrows it. *(2026-09-05)*
-- `loadEntry` probes each mounted collection in turn: the `paths` row
-  carries the target id but not its collection. *(2026-09-05)*
+This creates a Next.js site with the admin mounted, the database schema
+in place and a first editor who can sign in.
 
-#### Code health
+## Environment
 
-- `SharedForm.tsx` is a near-verbatim fork of `EntryForm.tsx`
-  (`applyResult`, `InfoRow`, the ref-options effect; the locale helpers
-  are shared since 2026-09-08) and `SharedList.tsx` is the third copy of
-  the remembered-locale block (`EntriesList`, `PagesList`); extract a
-  `useFormLocale` hook when the next form arrives. *(2026-09-07, shared content)*
-- `CollectionSchema.kind` was widened to carry `"shared"`, so a
-  `SharedSchema` typechecks where `registry.collections` is expected;
-  `defineConfig` should throw on a `kind === "shared"` entry listed there. *(2026-09-07, shared content)*
-- Because `fanOut` lists every shared registration, an entry store built
-  without `options.shared` now fails on every ordinary entry write with
-  "no collection named", not only on `ops.shared.*`; both scaffolds pass
-  the same `shared` array to the store and the config, so this bites only
-  a hand-wired app. *(2026-09-07, shared content)*
-- `subtreeIds` and `entrySubtreeIds` in `ops-impl.ts` are the same O(n²)
-  walk over a full list, written twice. One generic descendant walk when
-  the list sizes make it matter. *(2026-09-06)*
-- `ops-impl.ts` is ~436 lines with a ~165-line `pages` group. The guard
-  helpers (`nameOf`, `isHomeNode`, `supportedLocale`, `mountGuard`,
-  `owned`) are the extraction seam — a `pages-ops.ts` taking them as
-  collaborators. The `entries` group now duplicates two of them outright:
-  the `supportedLocale` guard and the `parentLocales` computation exist
-  once per group. *(2026-09-06)*
-- `EntryForm.tsx` grew the locale lifecycle beside the fields; the
-  `LocaleSwitcher` is shared with the editor now, the add/remove flows
-  are not (`doAddLocale`/`doRemoveLocale` exist twice). *(2026-09-06)*
-- `removeLocale`'s blocker list (`localeInUse`) is unordered in the
-  Supabase adapter — the children query has no `.order()` — so a
-  multi-blocker message can name the titles in a different order than the
-  memory adapter's. Message text only; the contract case has one blocker. *(2026-09-06)*
-- `entry-store.ts` is ~624 lines. The pure helpers (`localizedKeys`,
-  `splitFields`, `entryFieldsIn`, `entryRefEdges`, `entryTitleIn`) are the
-  extraction seam from the memory adapter, the same shape as the
-  `EditorView.tsx` and `ops-impl.ts` entries in this list. *(2026-09-06)*
-- The memory stores default to SEPARATE private path indexes while the
-  Supabase stores share one `paths` table: pages and entries share a URL space
-  only when the wiring passes one `paths` option to both (convention, not
-  structure). *(2026-09-05)*
-- `SupabasePathIndex` falls back to `pathTakenError("?", "?")` when
-  Postgres reports a unique violation without `details` — the message then
-  names no path. *(2026-09-05)*
-- `chainOf` has no cycle guard: a corrupted `parent_id` loop would spin
-  forever. The stores prevent cycles on `move`, so it is unreachable today. *(2026-09-05)*
-- The `scroll` message in `admin/editor/protocol.ts` is no longer sent: with the
-  canvas column as the scroller, `EditorView` scrolls it directly instead of
-  asking the bridge to `scrollIntoView` across the frame. `EditorBridge` still
-  handles the message, so old and new admins interoperate; drop the message on
-  the next protocol change. *(2026-09-05)*
-- `exports` has no `"./package.json"` entry, so tooling that reads a dependency's `package.json` through the exports map cannot. One line to add when something needs it. *(2026-09-04)*
-- `src/ref-index.ts` contains two raw NUL bytes used as key separators, which makes git show the file as binary in diffs. Replacing them with `\0` escapes would make it diffable again. *(2026-09-04)*
-- `serialize.ts` structural cast duplicates `PageSchema`; tighten `Registered.schema` so the cast goes. *(2026-09-03)*
-- `EditorView` split (autosave extracted 2026-09-03; the rest 2026-09-08, before the TipTap widget): `usePageLocale` (switch/add/remove, over `locale-url.ts`), `useCanvasBridge` (geometry, select/hover, `postToCanvas`, the geometry timeout), `CanvasOverlay` over `overlay-geometry.ts` (`plusButtonsFor`, pure and tested), `InsertPicker`, `Outline`, `NoticePane`. `EditorView.tsx` is ~660 lines of load, gestures, publish and layout. Remaining seam: the inspector's field form (`FieldWidget` rows plus the tabs) stays put until inline editing lands (DESIGN.md §3 puts TipTap in the canvas, not the sidebar). The ref-option loading became `forms/useRefOptions.ts` (2026-09-17). (logged 2026-09-06, updated 2026-09-08) *(2026-09-03)*
+A self-hosted app needs three variables:
 
-#### Tests
+| Variable | What it is |
+| --- | --- |
+| `SMOODLY_URL` | Your Supabase project's URL |
+| `SMOODLY_SECRET_KEY` | The project's secret key. Server-only. |
+| `SMOODLY_PUBLISHABLE_KEY` | The project's publishable key |
 
-- The media test uploads a starter photo under a suffixed name rather
-  than a fixture file, so `e2e/fixtures/` from the spec does not exist. *(2026-09-26, browser suite)*
-- ListView rows that are not clickable (Members) carry no role; the
-  members test finds its row by `.sm-table__body > div`. A table role
-  set (`table`/`row`/`cell`) on ListView would give every list a proper
-  locator. *(2026-09-26, browser suite)*
-- The picker's click cannot be unit-tested (no DOM in the suite); the
-  walk covers it. A jsdom environment for the admin tests is a future
-  tooling item. *(2026-09-15, custom section)*
-- The list widget has no test for an object item holding a nested list
-  subfield. *(2026-09-07, list field)*
-- The row menu's item set (`menuItems`) and the row-click routing live in
-  `PagesList.tsx`, untested; extract them into `pages-tree.ts` before
-  plan 4 adds entry rows to the same menu. *(2026-09-06)*
-- `publish`'s "has no draft to publish" branch is unreachable with the
-  memory store — `createPage` gives every templated page a first version
-  — and is untested. It is defence for the Supabase adapter. *(2026-09-06)*
-- Classifications the ops tests do not assert: a move that breaks the
-  home page's no-children rule or exceeds the tree depth (create asserts
-  both), and `entries.move`'s cross-collection and sibling-slug guards.
-  `MemoryEntryStore.move` has no children guard at all — the subtree
-  rides along — so `has child` is reachable from delete only. *(2026-09-06)*
-- No test pins that a published child's breadcrumb carries an UNPUBLISHED
-  ancestor's title with `hasPage: false`; `site.test.tsx` covers the
-  folder ancestor only, and the two paths share one `hasPage` predicate. *(2026-09-06)*
-- `MemoryPageStore.publish` throws the "is a folder" message when a
-  templated row has no draft version. Unreachable through the ops (a
-  templated page always gets a first version), but the message would be
-  wrong if it ever were. *(2026-09-06)*
-- `admin-entries-list.test.ts` has no case for a row with differing
-  pointers (the `draft edits` status), nor one asserting that an absent
-  row's `updatedAt` falls back to the node's. Two assertions. *(2026-09-06)*
-- The live suites run on vitest's DEFAULT 5s per-test timeout against a real
-  database, while a single contract test makes dozens of round trips. On a
-  loaded or degraded local stack `npm run test:supabase` then fails with bare
-  timeouts on arbitrary tests (every file passes on its own, and the whole
-  run passes with `--testTimeout=30000`). Either raise the timeout in
-  `scripts/test-supabase.sh` or accept the flake in CI. *(2026-09-05)*
-- Entry `move` coverage is thinner than pages' — no omitted-index, clamp or
-  cross-collection tests. *(2026-09-05)*
+## Upgrading
 
-### Cloud
+A new version can need a newer database schema. After updating the
+package, `npx smoodly migrate` writes the migration files; the
+Upgrading guide has the rest.
 
-- A copy inside one database with fresh IDs — the cloud's "duplicate
-  environment", staging → production; needs the reference walk (parent
-  links, version pointers, refs, paths, asset ids in trees, fields and
-  richtext) the eject avoids by keeping IDs. *(2026-09-28, export/import)*
-- Every op call with a junk token costs one `auth.getUser` against the
-  auth project; rate limiting is the session-model spec's (OQ 20). *(2026-09-26, security pass)*
-- The social image URL goes through the default `next` loader at 1200px;
-  the cloud's transform loader (OQ 28) should serve a real 1200×630. *(2026-09-10, page fields and SEO)*
-- A cross-origin admin needs the bridge-side editing variant (spec §3). *(2026-09-10, inline editing)*
-- Transform loaders beyond the Next default: Supabase Image
-  Transformations, imgix, Cloudflare Images (DESIGN.md OQ 28). *(2026-09-08, media library)*
-- `<SmoodlyImage>` sizes the image by the crop factor, so `sizes` picks a
-  candidate for the box, not for the framed image; a CDN loader with
-  `handlesCrop` removes the overfetch. *(2026-09-08, media library)*
-- Light/dark toggle (nav foot): the choice is stored in `localStorage`
-  (`smoodly-theme`) and written as `data-theme` on the admin wrapper, never on
-  the host `<html>`. It is per browser, not per editor account — a server-side
-  preference would need a place to live (`members`, or a cloud user profile). *(2026-09-05)*
-- Once the policy-based published read exists, decide whether it becomes the canonical headless read path and the generated per-collection views turn optional (cloud has no views). *(2026-09-04)*
-- A malformed `space_id`/`key_id` claim raises `22P02` inside the policy: fails closed but surfaces as a 500. Only reachable from a validly-signed key, so it is a cloud key-minting guard, not a request-path one. *(2026-09-04)*
-- **Verified and kept 2026-09-26 (security pass §3)** — Authorization trusts the JWT claims alone; `smoodly_space_key_revoked()` checks only `revoked_at`. When cloud key-minting exists, make it a full key check (the claims must match the `space_keys` row). *(2026-09-04)*
-- **Verified and kept 2026-09-26 (security pass §3)** — `memberOf` and `SupabaseMemberStore` read `members` (and `spaces`) with no space filter: under a cloud write key RLS scopes it, but a service-role client bypasses RLS and would admit an editor of any space. Harmless in self-host (one space); never use a service-role client against the shared content project. *(2026-09-04)*
+## Docs and source
 
-## Notes for maintainers
+Guides: https://github.com/laniakea-studio/smoodly-cms/tree/main/guides
+Source: https://github.com/laniakea-studio/smoodly-cms
 
-- The live suites wipe `members` and the content tables; a pane walk after
-  them needs `npm run reseed` (or `scripts/demo-editor.ts`) first. *(2026-09-26, concurrency)*
-- Drafting version N+1: `npx tsx scripts/emit-migration.ts` prints the
-  whole schema plus the upsert; keep only the delta, name the file with
-  the current UTC stamp and `_smoodly_v<N+1>.sql`, bump `SCHEMA_VERSION`,
-  run `npm run db:migrate` at the root so the repo copy follows, and
-  `npm run check:migrations`. Additive only; a contraction waits for the
-  compatibility window and carries `-- smoodly:contraction`. *(2026-09-26, schema migrations)*
+MIT licensed.