---
title: "Contributor docs"
description: "Architecture guide and package-by-package walkthrough will be added as packages land (Sprint 2+)."
url: https://cloudhal.dev/docs/contributing
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/contributing/README.md
---
# Contributor docs

- [Development environment](https://github.com/cloudhal-dev/cloudhal/blob/main/CONTRIBUTING.md) — setup, commands, PR rules
- [Architecture decisions](https://cloudhal.dev/docs/adr)
- [Design system](https://cloudhal.dev/docs/design/design) — binding rules for Studio and any admin UI (Kumo)
- [RFCs](https://github.com/cloudhal-dev/cloudhal/tree/main/docs/rfcs) — design proposals; start with RFC-0001 (Site Graph)

Architecture guide and package-by-package walkthrough will be added as packages land (Sprint 2+).


---
title: "Cloudhal Studio design system"
description: "Verified sources: kumo-ui.com (installation, components-vs-blocks, blocks, component docs, registry), the Kumo repository (sidebar.tsx, blocks, the docs app shell), the kumo-design skill, Cloudflare dashboard…"
url: https://cloudhal.dev/docs/design/design
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/DESIGN.md
---
# Cloudhal Studio design system

**Binding for every admin surface** (`apps/studio`, capability panels, docs UI). Cloudhal is a premium, community-facing product; its admin must read like the current Cloudflare dashboard. The implementation vocabulary is **Kumo** (`@cloudflare/kumo` 2.14, 54 components + 3 blocks) consumed through `@cloudhal/ui`. The official `kumo-design` skill (`.agents/skills/kumo-design`, installed from `cloudflare/kumo`) is part of this document; `apps/studio/test/design-rules.test.ts` enforces the mechanical rules in CI.

Verified sources: kumo-ui.com (installation, components-vs-blocks, blocks, component docs, registry), the Kumo repository (`sidebar.tsx`, blocks, the docs app shell), the kumo-design skill, Cloudflare dashboard documentation and changelogs (accounts/zones navigation, keyboard shortcuts 2026-05, navigation updates 2025–2026). Date: 2026-10-08.

## 1. Dashboard anatomy

The Cloudflare dashboard is: a **left sidebar** that is the primary navigation and whose contents switch between an *account surface* and a *zone surface* (a switcher sits at the top of the sidebar); **grouped, collapsible menus named by capability, not product**; a slim **top bar** with quick search (`/`, ⌘K) and the user menu; a **content area** with breadcrumbs, a page header (title, description, tabs, right-aligned actions), and **cards or tables**; resource lists carry a sticky right column with usage/help; empty states, skeleton loading, toasts and banners are system-wide.

Studio mirrors this one-to-one:

| Part | Kumo implementation |
|---|---|
| App shell | `Sidebar.Provider defaultOpen collapsible="icon" peekable mobileBreakpoint={768} className="h-dvh"` → `<Sidebar>` + a content column `flex h-full min-h-0 flex-1 flex-col overflow-y-auto overscroll-y-contain bg-kumo-overlay`. The provider must have a definite height because Kumo's `<aside>` is `h-full`; the column scrolls, the sidebar stays viewport-tall. **The document never scrolls**: the shell is `h-dvh` (the visible viewport, mobile toolbars included) and `#root` is `min-h-dvh` — with `h-svh`/`min-h-screen` the page was taller than a phone's visible area, so reaching the end of the column or the sidebar scrolled the whole document, half-hiding the top bar and opening an empty strip below. Scrolling never chains on: the column is `overscroll-y-contain`, the sidebar's viewport `overscroll-behavior: contain` (`@cloudhal/ui/styles.css`), `<body>` `overscroll-none`. The column is the page's scroll root (`usePageScrollRootRef` / `usePageScrollRoot` from `PageFrameProvider`); scrollspy and jumps use it, never `window`. The column is `relative`, so absolutely positioned bits in pages (`sr-only` labels in long tables) are contained by it — with the provider as their containing block they sat below a long list and made the document taller than the window (the "extra space after the end" on Snapshots). Sidebar 16.25 rem expanded, 57 px icon rail; `Sidebar.Header` is `h-12` like the top bar, so their bottom edges are one line. |
| Surfaces | *Account surface* (all sites) and *site surface* (one site); the switcher at the top of the sidebar is a `DropdownMenu` listing sites and "All sites". |
| Top bar | `header.sticky.top-0.z-10.h-12.shrink-0.border-b.border-kumo-line.bg-kumo-canvas`: `Sidebar.Trigger` (below `md`, the only way into the sheet), **the page's breadcrumbs** (`PageCrumbsSlot`; Kumo `Breadcrumbs` are `h-12`, exactly the bar), then right-aligned the `CommandPalette` button (⌘K and `/`; the palette, `CommandMenu`, loads with its first opening), the surface's actions (site surface: `SitePublish`, the Publish split button), the notification bell (`NotificationsBell`, §2n), the theme menu (`ThemeSwitch`: ghost icon button showing the current choice, `DropdownMenu` radio items Light / Dark / System; hidden below `sm`), the language `Select` (hidden below `sm`) and last the **user menu** (`UserMenu`: a circle ghost button with the person's `Avatar`, `DropdownMenu` with name + role, Account, Team, All sites, Theme and Language submenus, Sign out) — all `size="sm"`. The palette also offers "Theme: …" commands. On a site (RFC-0029 §7) it is Kumo's grouped palette (`Results` → `Group` + `GroupLabel` → `Item` / `ResultItem`):
  - **Groups.** Commands first (`useSitePalette`: the site's screens as a table, then New article, Create snapshot, Publish, All sites), then the site's content from `GET /api/sites/:siteId/search`, from two letters on, after 150 ms. Content comes one group per kind: Articles, Pages, Categories and tags, Media, Menu items, Redirects.
  - **A hit.** It shows its kind's icon, then where it lives (`breadcrumbs`: collection or taxonomy, path or slug, and Draft / In review). Enter or a click opens its editor; ⌘/Ctrl opens it in a new tab.
  - **Publish.** Publish opens `SitePublish`'s `ApprovalDialog`; the palette never publishes on its own.
  - **Footer.** It lists the keys.
  - **Matching.** Commands match with `foldName`, so case and Turkish İ/ı are folded. |
| Content container | `PageLayout` (`@cloudhal/ui`) — the only container: `mx-auto max-w-[1400px] px-4 py-6 sm:px-6 md:px-8 md:py-8 lg:px-10`, `width="narrow"` caps at 960 px. Screens never set `mx-auto`/`max-w-*` themselves (lint `page-container`). |
| Breadcrumbs | Built only by `Crumbs` / `SiteCrumbs` (`components/Crumbs.tsx`): "Cloudhal Studio › ui-audit › Pages › About", `Breadcrumbs.Current loading`, `Breadcrumbs.Clipboard` for the current resource id. Passed to `PageLayout crumbs`, which portals them into the top bar — never rendered in the content. |
| Page header | Kumo's `PageHeader` block (owned copy: every row flush with the content edge, 14 px description, `icon`, `actions`, controlled `tab`, loading title), rendered by `PageLayout` from its `title`, `description`, `icon` (24 px, top-level list pages only), `actions` (the page's primary action — "New page", "Create key" — lives here, never in the toolbar row) and `tabs`. Tabs are for **sub-views of one page only**; a tab bar that repeats the sidebar is forbidden (the old site tab bar was removed for that reason). |
| Lists | `PageLayout` (+ `aside` for usage/help: the `ResourceListPage` two-column body, 380 px sticky once the content is ≥ 64 rem) + `ListToolbar` (Kumo `Toolbar`, default size so it lines up with `Select`/`Button`) + `LayerCard className="p-0"` + `Table` + `Pagination`; empty → a bare `Empty` in the table's place. |
| Sections | `SectionCard` (`@cloudhal/ui`): Kumo `LayerCard` with the `Secondary` header row (title, optional 16 px icon, `actions` right: count `Badge`, ghost `LinkButton` "View all", small buttons) and the `Primary` body (`description`, `children` in `grid gap-5 px-5 pt-4 pb-5`, `flush` for a `Table`, `footer` row for Save/Discard). Never nested (lint `layer-card-nesting`); never a bare `LayerCard` with hand-made headers. |
| Neutral panels | `InsetPanel` (`@cloudhal/ui`, `outline` / `recessed`) for summaries and quoted agent text inside cards and dialogs ("Now → New", the agent's reason); `Surface` for standalone neutral surfaces. Hand-made `rounded-* ring` divs are forbidden in screens (lint `no-ad-hoc-surface`). |
| Feedback | `Banner` (page/section), `Field`/`Input error` (inline), `Toasty` + `useKumoToastManager` (transient). |
| Confirmation | `ApprovalDialog` (ours, on `Dialog`) for publish/rollback; `DeleteResource` (block) for typed-name deletes; `LayerDialog.Alert` for other destructive alerts. Always rendered, controlled by `open`. |
| Forms & detail sheets | `LayerDialog.Root open onOpenChange` → `LayerDialog.Content` whose **direct** children are `Title`, optional `Description`, `Body`, optional `Actions` (Kumo throws otherwise; branch *inside* each part). Desktop dialog, bottom sheet on phones. |
| Code & config | `CodeHighlighted` from `@cloudhal/ui/code` (Shiki, lazy, `showCopyButton`) for snippets and JSON payloads; `ShikiProvider` lives at the app root (`CodeProvider`, localised copy labels). `Code` stays for one-line CLI hints in usage panels. |

Keyboard parity with the dashboard: `⌘K` / `/` open the palette; `t s` toggles the sidebar; `?` lists shortcuts (palette entry).

**Lazy message namespaces.** Every word goes through `useT()` (`apps/studio/src/i18n`), but not every word is in every page's first load. The core catalogs `en.ts`/`<locale>.ts` hold what the shell and most screens need, and only one language of them loads: English is in the first load (it is also every key's fallback), every other language is a dynamic import (`loadLocale`, found by file name) that `main.tsx` awaits before the first render and a language switch awaits before it applies; a feature whose wording only its own screens show keeps it in a **lazy namespace**: one top-level key, moved verbatim into `i18n/lazy/<ns>.en.ts` (`export const messages = { <ns>: { … } } as const`, the source of truth for its keys) and `i18n/lazy/<ns>.tr.ts` (`export const messages: NamespaceMessages<"<ns>"> = …`, so a missing or extra Turkish key is a type error), registered in `i18n/namespaces.ts` (one dynamic import per namespace and locale — a page fetches only the language it shows). Today: `analytics` (Analytics screen), `analyticsSettings` (site settings, Agents' "Allow analytics"), `readers` (editors' Readers card, overview card, list views column), `comments` (comment queue, thread, commenter, article editor card, Approvals) `commentsSettings` (site settings in every locale, Agents' "Allow comments") `appearance` (the color roles under site settings' Appearance form and its Header and footer section) `media` (the media library, a file's page, uploads, the image picker, takedowns; loaded with every route that shows them) and `menus` (the navigation editor and its dialogs, and menu references in the page, article and term editors, the page and article lists and the snapshot diff).
- **Reading.** A component that shows namespace words asks for them: `useT("analytics")` / `useI18n("readers")` returns a `t` typed for the core keys plus that namespace (`useT()` alone does not accept them, so a forgotten namespace is a type error) and suspends until the current locale's module is there. Text in another locale (the privacy notice) uses `useMessages([ns], LOCALE_LIST)` + `translate`.
- **Loading — no flash of keys.** The route that renders the namespace loads it with its chunk: `lazyRouteComponent(() => withMessages(import("./routes/X.tsx"), ["readers"]), "X")` in `router.tsx` (in parallel, also on hover preload), so the screen never suspends for words; if one is missed, the component suspends to the route's pending state rather than showing keys. A language switch first loads, in the new language, every namespace loaded in the old one, then switches (in a transition). `bundle-budget.ts` fails the build if `i18n/lazy/` reaches the initial load.
- **No hard-coded words** (AGENTS.md hard rule 10). Nothing a person reads is a literal in `apps/studio/src` or `packages/ui/src`: JSX text and string children, `aria-label`, `title`, `placeholder`, `alt`, `label`, `description`, `content` and every `…Label`/`…Text`/`…Title`/`…Description`/`…Placeholder`/`…Message`/`…Hint` attribute or property, tables of labels (`{ draft: "Draft", … }`), default values and `??`/`||` fallbacks, toasts and `confirm()`, `document.title`. Blocks take every word as a prop and have no English fallback (`StatusBadge label`, `DeleteResource labels`, `ApprovalDialog confirmLabel`/`cancelLabel`). A failed request is worded by `apiErrorText(t, error)` (`lib/api-errors.ts`: `errors.api.<code>`, then the server's message, then the status), never `error.message` directly. Search folds text with the Studio locale (`usePaging`'s `fold`, `toLocaleLowerCase(locale)`), never `toLowerCase()`. The `i18n` rule of the design lint (`apps/studio/scripts/i18n-lint.ts`) parses every `.ts`/`.tsx` of both trees with oxc and fails `pnpm check`; ids, keys, class lists, URLs, protocol values and logs are not prose and pass. A literal that reads the same in every language goes in its `ALLOWED` list (product and format names) with a reason, or carries an `i18n-ignore: <reason>` comment on its line or the line above.
- **Message syntax** (RFC-0032, ADR-0032). A catalog value is text with `{name}` arguments, or an ICU MessageFormat 1 message: `{count, plural, =0 {…} one {# file} other {# files}}` (the CLDR categories of the language; `#` or `{count}` is the number in the locale), `{kind, select, page {…} other {…}}`, `{n, selectordinal, …}`, `{n, number}` / `{n, number, percent|integer|compact}`. `other` is required; a literal brace is quoted, `'{}'`. `@cloudhal/messages` compiles the catalogs at build time (the `catalogs()` Vite plugin in `vite.config.ts` and `vitest.config.ts`), so no parser ships. `t()` is typed per key from `src/i18n/generated/params.ts` (`pnpm gen`; a plural argument is a `number`, a select one of its values); a message a block fills in itself keeps its placeholders with `keep("name")`. A count is one `plural` message called with the number (`t("editor.words", { count })`), never a `…One` key or a `count === 1 ?` ternary (the test rejects `…One`/`…Many` keys). When a translation needs another grammatical form of a data argument (Turkish names a role once, `{role}`, where English says `{roles}`; a taxonomy's own singular and plural labels), English declares it in `forms` (`en.ts`, by key prefix): the form becomes a required parameter of those keys and the only substitute a translation may use. A word that changes with a value is a `select` over the value with whole sentences (`{action, select, approve {… approved} … other {…}}`), never a translated word injected into a sentence. A translation that cannot use an argument at all (a Turkish case suffix on an arbitrary name) declares it in its core catalog's `dropped`, with the reason; the test rejects any other missing argument and any stale entry. A list a person reads goes through `listOf(items)` (`Intl.ListFormat` in the Studio language: "a, b, and c", "a, b ve c"; `formatList(locale, …)` from `@cloudhal/messages/format` outside React), never `items.join(", ")`; `" · "` between separate facts is a visual separator and stays. Numbers, dates, times, relative times, display names and collation come from the cached, locale-taking layer in `@cloudhal/messages/format` (`formatNumber`, `formatDate`, `formatRelative`, `numberFormat`, `dateTimeFormat`, `relativeTimeFormat`, `displayNames`, `collator`; `NUMERIC_DATE`/`NUMERIC_DATE_TIME` for what `toLocaleDateString`/`toLocaleString` showed), always with the Studio locale (or a fixed one for machine formats such as the `en-CA` day keys), never `new Intl.*` or `toLocaleString()` in a screen or block. The design lint enforces these: `i18n-format` (a formatter built on the spot), `i18n-plural` (two messages chosen by whether a number is 1) and `i18n-concat` (a sentence assembled from several `t()` results, or a list joined with `", "`), in `pnpm check`, `pnpm design:lint` and the agent hook; a reviewed exception carries `i18n-ignore: <reason>`. `test/i18n-messages.test.ts` checks every language: valid syntax, English's argument kinds kept, every plural category of the language present.
- **Adding keys.** Keys go in English and in every registered language (core: `en.ts` and each `<locale>.ts`; a lazy namespace: each `lazy/<ns>.<locale>.ts`, never back into the core catalogs; `test/i18n.test.tsx` checks keys and placeholders for every language). A branch made before a namespace moved (e.g. `analytics.bots.*` added under `analytics` in `en.ts`/`tr.ts`) merges by moving its lines unchanged into `lazy/analytics.en.ts`/`lazy/analytics.tr.ts` — the blocks keep their indentation there. A new feature with more than a few kilobytes of wording, shown on its own screens, starts as a lazy namespace; words the shell shows (navigation, commands) stay core (`nav.analytics`, `commands.goAnalytics`).
- **Languages.** `i18n/locales.ts` is the registry: one entry per language, keyed by its BCP 47 tag (also `<html lang>`, every `Intl` formatter and `calendarLocaleProps`, so dates and numbers follow the Studio language, never the browser's), with its native `name`, `dir` (set on `<html dir>`), `fallback` chain (always ending in English) `reviewed` and, where formatting needs it, an `intl` tag (Arabic and Persian `…-u-nu-latn`, Western digits, ADR-0033; `setIntlTags` makes every formatter of `@cloudhal/messages` use it). Besides English (the source) and Turkish (the owner's), every language is an AI translation awaiting review by a person who speaks it (`reviewed: false`, ADR-0034; the first right-to-left one is Arabic). The language menus show each name in itself only; that a language is an unreviewed AI translation is a comment on its registry entry, for maintainers. Loaders are not written by hand: `import.meta.glob` finds `i18n/<locale>.ts` (`export const messages: Messages`) and `i18n/lazy/<ns>.<locale>.ts`; `bundle-budget.ts` keeps every core catalog but English out of the first load. Studio opens in English, its global default, for everyone: the browser's language is not consulted; a person's own choice in the language menu is stored and wins (`matchLocale` remains for matching a tag to a registered language).
- **Pseudo-locale and catalog checks** (the i18n review's Phase 5). On a dev server (and in tests) `?pseudo` or `localStorage["cloudhal.studio.pseudo"] = "1"` shows every catalog message as "[Šààṽéé]" — accented, about a third longer, bracketed — generated from the compiled English messages (`@cloudhal/messages/pseudo`) with every argument and plural kept: plain English on screen is a hard-coded word, a missing "]" is a cut-off label, a broken layout has no room for German. It is never a language in the menus, and production builds do not contain it (`import.meta.env.DEV`; the bundle budget fails if the module reaches a chunk). `SHOTS_PSEUDO=1 pnpm design:shots -- …` takes the screenshots in it. `test/i18n-messages.test.ts` also fails on an **unused key**: `apps/studio/scripts/i18n-usage.ts` collects every literal and template key in Studio's code (string constants resolved, a literal naming a group reaches the group); `node apps/studio/scripts/i18n-usage.ts` lists them. Missing keys and placeholder parity were already checked (types, `test/i18n.test.tsx`).
- **Right-to-left readiness** (ADR-0033 D and B). Studio and the `@cloudhal/ui` blocks use logical utilities only — `ms`/`me`, `ps`/`pe`, `start`/`end`, `text-start`/`text-end`, `border-s`/`border-e`, `rounded-s`/`rounded-e`/`rounded-ss`… — never `ml`/`mr`, `pl`/`pr`, `left`/`right`, `text-left`/`text-right`, `border-l`/`border-r`, `rounded-l`/`rounded-r` (lint `rtl-logical`; `scripts/i18n-codemod/logical-utilities.ts` converts; an element placed by Floating UI in physical coordinates keeps `left-0` with an `i18n-ignore` reason). `<html dir>` and Base UI's `DirectionProvider` (in `KumoLocale`, through `@cloudhal/ui`) follow the locale registry's `dir`. `SHOTS_PSEUDO=rtl pnpm design:shots -- …` (or `?pseudo=rtl` on a dev server) renders the right-to-left pseudo-locale to find what does not mirror. Kumo's own components are made logical by the generated patch (`node scripts/kumo-patch.ts`, ADR-0033 A1; `kumo-upstream-notes.md` §7); Icons that mean a direction in reading order — back and forward, previous and next, "from → to", a closed tree row, opening a row, reply, indent, opening elsewhere, signing in and out, sending — go through `DirectionalIcon` (`<DirectionalIcon icon={ArrowRight} />`, or `directional(ArrowRight)` where a prop or table takes an icon component), which sets Phosphor's `mirrored` from Base UI's direction (ADR-0033 C1, lint `rtl-icon`). Physical and temporal directions stay as they are: up and down, sort order, clocks, refresh and undo circles, a chart's trend; such an icon among the matched names carries an `i18n-ignore` reason. Kumo's own ten directional icons (submenu, sidebar, pagination, date range, command palette) and the breadcrumb separator mirror through `rtl:-scale-x-100` from the hand-written `patches/kumo/rtl-icons.patch`, which reads `<html dir>` rather than Base UI's context (`kumo-upstream-notes.md` §7). Arrow keys follow the direction too: blocks whose Left and Right mean previous and next, open and close, or nest and move out (`MenuTree`, `CalendarMonth`) read the key through `readingKey(key, useDirection())`, and their help text names the keys as they work in the language (`menus.tree.instructionsRtl`).
- **Translation workflow** (ADR-0034). **Only English is edited by hand** (`en.ts`, `lazy/<ns>.en.ts`). Every other catalog is generated by `pnpm i18n:import` from translation files — nested ICU JSON, `.i18n/<locale>/<core|namespace>.json`, written by `pnpm i18n:export` with `.i18n/descriptions.json` (English text and the note above each key) — and carries a hash of its messages: a hand edit fails `pnpm check` (`node scripts/i18n-exchange.ts check`, run by `test/i18n-messages.test.ts`). The import checks keys and ICU syntax before writing anything, keeps a catalog's own exports after its messages (Turkish `dropped`), formats the files and runs the catalog tests. New English keys: export, translate the new keys in each language's JSON (by hand or with the `translate` skill, `.agents/skills/translate`), import. The translation platform (Weblate or Tolgee) and its hosting wait for the owner; the exchange format is the one it will read.
- **Adding a language** (the i18n review's Phase 6): (1) **prerequisites** — a language with plural categories beyond one/other (ar, ru, uk, pl, cs, …: `Intl.PluralRules(…).resolvedOptions().pluralCategories`) waits for ICU plurals (the review's Phase 1), a right-to-left one (ar, he, fa, ur) for logical CSS and Kumo's direction support (Phase 3); (2) add the registry entry with `reviewed: false`; (3) `pnpm i18n:export`, write `.i18n/<locale>/*.json` (the `translate` skill drafts them; an AI translation is fine as a first draft; its registry entry says so in a comment until reviewed), `pnpm i18n:import --locale <locale>` — it generates `i18n/<locale>.ts` and every `lazy/<ns>.<locale>.ts`; (4) `pnpm --filter @cloudhal/studio typecheck` and `test/i18n.test.tsx` (keys, placeholders, no English sentences left, every namespace present); (5) `vite build` — the bundle budget must not move (the language loads only for its users); (6) `pnpm design:shots` in the language at 1440 and 390 px (German and Finnish run long); (7) a speaker reviews in context, then `reviewed: true`.

## 2. Page templates

Every route file declares one template in `ROUTE_TEMPLATES` (`apps/studio/scripts/design-lint.ts`); the lint then requires that template's blocks. A new screen fails until it is registered.

| Template | Built from |
|---|---|
| `queue` | `PageLayout`, flush `SectionCard`s of `divide-y` rows / a `Table`, `SectionEmpty` (Approvals) |
| `moderation` | `PageLayout`, `ListToolbar` ↔ `BulkActionBar`, `LayerCard p-0` of `CommentRow`s, `Empty`, `Pagination` (reader comments, §2w) |
| `list` | `PageLayout` (crumbs, title, description, `actions`, optional `aside`), `ListToolbar`, `LayerCard p-0` + `Table`, `Empty`, `Pagination` |
| `dashboard` | `PageLayout`, `Columns variant="2-1"`, `SectionCard`s |
| `settings` | `PageLayout`, `SettingsLayout` (sticky `TableOfContents`), `SettingsSection` (= `SectionCard`) |
| `editor` | `PageLayout`, `EditorLayout` (+ `PreviewPanel`), `SectionCard`s |
| `auth` | `AuthLayout` (`@cloudhal/ui`), `Tabs`, `Input`/`PasswordField`, full-width primary `Button`, `Banner` |
| `token` | `AuthLayout` without tabs, `takeHashToken`, `Banner` for the link's state, `SkeletonLine`s while it is inspected, `Input`/`NewPasswordFields`, full-width primary `Button` (`/invite`, `/reset-password`, §2r) |
| `recover` | `AuthLayout` without tabs, one email `Input`, full-width primary `Button`, the neutral answer as a `Banner`, a `LinkButton` back to sign in (`/forgot-password`, §2r) |
| `shell` | `AppFrame`, `Sidebar.*`, `SidebarSwitcher` |

```tsx
<PageLayout
  crumbs={<SiteCrumbs siteId={siteId} trail={[{ label: t("pageHeaders.pages.title") }]} />}
  title={t("pageHeaders.pages.title")}
  description={t("pageHeaders.pages.description")}
  actions={<Button variant="primary" icon={<Plus />}>…</Button>}
  aside={<SectionCard title=…>…</SectionCard>}   // optional
>
  …toolbar, cards, tables…
</PageLayout>
```
Reference implementations: `routes/SitesPage.tsx` (list + aside), `routes/PagesPage.tsx` (list), `routes/SiteOverviewPage.tsx` (dashboard), `routes/LoginPage.tsx` (auth).

### 2a. Resource list (sites, pages, articles, snapshots, activity, agent keys, skills)
```tsx
<PageLayout crumbs={…} icon={<Icon size={24} />} title description
  actions={<Button variant="primary" icon={<Plus />}>New page</Button>}
  aside={<SectionCard title="From the terminal" icon={<TerminalWindow size={16} />}>…<Code /></SectionCard>}>
  <ListToolbar search onSearch placeholder actions={…Select filters, RefreshButton…} />
  <LayerCard className="p-0"><Table><Table.Header><Table.Row><Table.Head/>…<Table.Head sticky="right"/></Table.Row></Table.Header>
    <Table.Body>{rows.map(r => <Table.Row key={r.id}><Table.Cell><Link href>{r.title}</Link></Table.Cell>…<Table.Cell sticky="right"><RowMenu /></Table.Cell></Table.Row>)}</Table.Body></Table></LayerCard>
  <Pagination page perPage={25} totalCount setPage controls="full" />
</PageLayout>
```
Empty → a bare `Empty icon={<Icon size={48} />} title description commandLine contents` in place of the table (Kumo `Empty` draws its own frame — never wrap it in `LayerCard`); inside a card, cell or dialog use `SectionEmpty` (frameless). Never pass `className` to `Empty`. Loading → `TableSkeleton` (a `Table.Body`, so always inside `<Table>`). Times in lists are relative (`RelativeTime`) with the absolute time in a `Tooltip`. Every control on one toolbar row has the same height (Kumo default size).

Multilingual sites (`site.locales.length > 1`, an internal review (2026-10) §4a): Pages and Articles show one row per translation group (`lib/translation-groups.ts`), by its default-language version or the original, with a "Languages" column of `LanguageChips`. The toolbar gets a language `Select` ("All languages (grouped)" by default, or one language: that language's versions as a flat list, without the Languages column); picking a language makes it the site's **working language** (`lib/working-language.ts`, this browser only), which new pages and articles start in. Single-language sites show neither.

Snapshots: the primary "Create snapshot" opens a `LayerDialog` (optional label `Input` + `Radio appearance="card"`: keep the live site / publish it); publishing continues into `ApprovalDialog` before anything is sent. `SnapshotTimeline` rows keep Compare (ghost) and Publish/Roll back (secondary) in separate trailing columns so actions align, the last one `sticky="right"`; times via its `renderTime` prop (`RelativeTime`).

### 2b. Resource detail / editor
`PageLayout` (crumbs via `SiteCrumbs` with `copy={id}`; title; description = status badge + path in mono; actions = `PreviewToggle`, `StatusActions` — a secondary "More actions" ⋯ `DropdownMenu` with a "Status" group plus Duplicate and Delete, and the next lifecycle step as a labelled secondary button, Publish via `ApprovalDialog` — and the primary Save with `loading`, disabled until dirty) → `EditorLayout`. Main: `SectionCard`s with fields in `Grid 2up/3up` (`items-start gap-x-4 gap-y-5`, inputs `w-full`); page sections are one `SectionCard` each (kind icon + name, id as `InlineCopyText`, ghost square icon buttons with tooltips: move up/down, remove → `ConfirmDialog`), added from an "Add section" `DropdownMenu`. Side: `DetailsCard` (`dl` rows: ID, language, revision, updated as `RelativeTime`…) and `DangerZoneCard` (`secondary-destructive` → `DeleteResource`), both in `EditorLayout.tsx`. Lifecycle = explicit actions, never a status `Select`.

### 2c. Settings / form
Same header; `Columns variant="1-2"` (a fixed 13 rem sticky `TableOfContents` and cards capped at 56 rem, side by side once the page container is ≥ `@4xl`); one `SectionCard` per section, `Switch` for instant settings, `SensitiveInput` for secrets, `ClipboardText` for ids; sticky footer `border-t border-kumo-line` with `Button variant="primary" type="submit" loading`.
Studio implements it as `SettingsLayout` + `SettingsSection` (`components/Settings.tsx`): the `TableOfContents` is sticky from the page container's `@4xl` breakpoint (hidden below it; the cards stack); its label is a sentence-case `Text` with the nav's `aria-label`, never `TableOfContents.Title` (Kumo renders it in capitals) and driven by `useSectionSpy` on the shell's scroll root (Kumo's `useTableOfContentsActiveId` watches `window`, which never scrolls in the shell): the current section is the last one whose top passed the line below the top bar, the **last section at the end of the page** (short closing sections can never reach the line), and a clicked item stays current until the person scrolls again (wheel, touch, pointer, keys), so a jump never snaps back to its neighbour; items scroll the content column themselves (no router hash navigation), and a `#section` deep link lands on its card. Each section is a `SectionCard` (`SettingsSection` maps `aside` → `actions`): header (title, optional badge/actions right), body with a muted description, controls carrying their own `label`/`description`/`error`, label/value rows as `dl` (`SettingRow`), and a footer row `border-t border-kumo-hairline` with the section's own actions (ghost "Discard" only while dirty, primary "Save changes" disabled until dirty). Sections save independently. A section holding a `Table` uses `flush` (no body padding). Text inputs in cards get `className="w-full"` so they never overflow the card at 375 px; field pairs use a container-query grid (`@container` → `@lg:grid-cols-2 items-start`), each field with its own description so rows stay aligned.
Saves that `PUT` a whole document send the latest cached copy plus the section's fields; a 409 shows `Banner variant="alert"` "This site changed somewhere else" with `Banner.Action` "Load latest" (the form keeps unsaved edits unless the server's values for those fields changed).

### 2d. Destructive flow
`Button variant="secondary-destructive"` → `DeleteResource open onOpenChange resourceName onDelete isDeleting {...deleteResourceProps(t, type, { action?, error })}` (Studio's `components/deleteLabels.ts`: the dialog's `labels` and the failure, worded from the catalog). Non-typed destructive confirmations: `LayerDialog.Alert`. Never `{open && <Dialog/>}`.

### 2e. Auth
`AuthLayout` (`@cloudhal/ui`): canvas background, a centred 400 px column — brand row (icon tile + product name), one `Surface` card (`rounded-xl px-6 py-5 ring-kumo-line`) with the heading (`Text heading lg`, "Welcome back" / "Create your account") and description, then the form: segmented `Tabs` (sign in / create account), `Input label` fields at full width, `PasswordField` (show/hide), `Button variant="primary" loading` full width, `ErrorBanner` for failures; a footer row under the card (licence note, language `Select`). No sidebar.

### 2f. Editor with live preview (page and article editors)
`EditorLayout` (Studio) around the 2b form, with `PreviewPanel` (`@cloudhal/ui`) as the preview:
- **content ≥ 64 rem** (container query on `PageLayout`'s `@container/page`, so the sidebar's state counts): two equal columns — the form (main sections, then details and danger zone) left, the preview right, `sticky top-16`, height `calc(100svh - 6rem)`, filling its column (`PreviewPanel fill`). A secondary `PreviewToggle` labelled "Hide preview" / "Show preview" (`Tooltip`, `aria-pressed`) in the header actions hides it; the choice is remembered per browser and the layout falls back to `Columns 2-1`.
- **content < 64 rem**: underline `Tabs` "Edit | Preview" above the content; Edit shows the 2b `Columns 2-1` (stacked on phones).
- `PreviewPanel`: `LayerCard` with a `Secondary` toolbar — heading, status slot (`Badge warning dot` "Unsaved changes" + `Tooltip` when the form is dirty), segmented `Tabs size="sm"` for Desktop/Tablet/Mobile (icon + label, label hidden on phones), `RefreshButton`, `LinkButton external` "open in new tab" — and a `Primary` viewport on `bg-kumo-recessed`. Desktop fills the panel; tablet (768) and mobile (390) render at their real width, scaled down only when the panel is narrower, framed with `ring ring-kumo-line`. Loading = `SkeletonLine` rows in an overlay with `role="status"`.
- The frame is always `<iframe sandbox="">` (no scripts, no same-origin, no forms), except in the Build view (§2ac) on the same-origin `/preview` endpoint; it reloads when the document's `rev` changes (i.e. after every successful save) and on demand. Unsaved changes are previewed too: the term editor (§2p) and, since RFC-0014 phase 1c, the page and article editors (`DraftEditorPreview`) send the form to `POST …/preview` (scope `content:read`, nothing written) after each 400 ms pause in typing, and `PreviewPanel live srcDoc` swaps the server's rendering of the draft into the same sandboxed frame — so there is no "Unsaved changes" badge to explain; "Open in new tab" opens the saved version. With nothing unsaved the frame shows the saved `/preview` as before. A failed draft render shows an error `Badge` with the reason in a `Tooltip`.

### 2g. Credentials (agent keys) — modes, create, one-time reveal
Every key has a **mode** (ADR-0015) — how independently the agent works; scopes stay the hard limit and a mode never grants more. Studio offers the four key modes, in order of autonomy: `plan` (read + preview), `manual` (every change waits), `edits` (default: edits free, publish/rollback/delete wait), `auto` (like edits, small article-only publishes go live without a person). `bypass` is never offered or sent for a key (the API answers 400); it is only *explained*, with `cloudhal mcp --mode bypass`.

List page per 2a (`PageLayout`, crumbs Agents › Keys and MCP, "Create key" in `actions`; the elevated-keys banner sits between the toolbar and the table; empty = bare `Empty` with `commandLine` + secondary Create key): name + key prefix (`start…`, mono) in one cell; **Mode** column with `ModeBadge` (while elevated: `KeyModeCell`, see *Elevation* below); scopes — one outline `Badge` "Mode default · n scopes" (scopes in its `Tooltip`) when they equal the mode's prefill, otherwise the full `ScopeBadge` list (a `Tooltip` per scope), so customised keys stand out; created/expiry; status dot; row `DropdownMenu` (Change mode, Elevate temporarily, End elevation now while one runs, Copy key ID, separator, Revoke). The `aside` holds the `SectionCard` "Connect an MCP client": endpoint and header as `ClipboardText`, segmented `Tabs` over ready-to-paste client configs in `CodeHighlighted` (the local tab uses `cloudhal mcp --mode edits`); the copy says the agent is told its mode when it connects. Then the compact **"How modes work"** flush `SectionCard`: one-line description, a compact `Table` (Mode × Content / Publish / Rollback, delete) whose cells are dot `Badge`s — Blocked neutral, Waits warning, Free success, "Small: free" success — each with a `Tooltip` explaining the rule, then the tools that always wait with a key (rollback, delete_page, delete_entry; label + mono name), a `ClockCountdown` line recommending a temporary elevation over a permanent Auto key, and the local bypass command. The table overrides Kumo's cell padding to `px-1` (first/last column `pl-5`/`pr-5`) so four columns fit the 380 px side column and a phone in English and Turkish; keep labels short.

**Mode picker** (`ModePicker`, `components/AgentModes.tsx`) — the one way to choose a mode:
- `Radio.Group appearance="card"` (legend visually hidden via `Radio.Legend className="sr-only"`), one `Radio.Item` per key mode, iterating `KEY_MODES` (never a literal list; CI checks).
- Card `label`: mode icon (Phosphor: plan `Eye`, manual `UserCheck`, edits `PencilSimple`, auto `Lightning`, bypass `LockSimpleOpen`, 16 px, `text-kumo-subtle`), the name, a **risk `Badge`**: plan/manual `success` + `ShieldCheck` "Safest", edits `info` + `Star` "Recommended", auto `warning` + `Warning` "Use with care"; in the change dialog the key's current mode adds an outline "Current".
- Card `description`: one line on behaviour, then a `HandPalm` line "**Waits for you:** …".
- `BypassHint` under the cards; `edits` preselected.
- Choosing `auto` (where it is not already the mode) shows `AutoModeConfirm`: `Banner variant="alert"` with a `Lightning` icon explaining the low-risk rule (articles only, nothing removed, ≤ 20 changes, marked auto-approved, one-click rollback), and a `Checkbox` "I understand that this agent can publish without my approval" that must be ticked; the primary action shows an inline error otherwise. CI checks that every screen rendering `ModePicker` also renders `AutoModeConfirm`.

`ModeBadge`: filled, semantic tone by autonomy — plan `secondary`, manual `success`, edits `info`, auto/bypass `warning` — with the mode icon and a `Tooltip` (behaviour + what waits). `subtle` renders it `outline` for dense audit cells so the decision badge stays loudest. Carries `data-mode`.

Create = one `LayerDialog`, three states in the same parts (no fragments in `Content`):
1. **Mode** (step 1 of 2): the mode picker (+ auto consent, bypass hint). Primary "Continue".
2. **Name and scopes** (step 2 of 2): an `InsetPanel layout="row"` summary (Mode + `ModeBadge`, "Waits for you: …", secondary "Change" back to step 1), `Input` name (+description, inline `error` after a submit attempt), then `Collapsible` **"Advanced: scopes"** — closed by default, a "Customised" `Badge info` in the trigger when the set differs from the mode's prefill. Inside: "Prefilled for {mode} mode…" hint, ghost "Use the mode's scopes" reset when customised, the scope `Checkbox`es grouped in labelled `InsetPanel`s (Read / Write / Publish and roll back, hint per group, raw scope in mono), and `Banner variant="secondary"` when scopes the mode needs are missing. Changing the mode re-fills the scopes. The request sends `{name, mode}` and adds `scopes` only when customised (the server prefills from the mode). Primary "Create key" (`loading`); dismissal disabled while pending. No `<form>` element around Kumo `Checkbox` (it is a `<button>` and would submit) — Enter in the name field submits.
3. **Reveal**: `Banner variant="alert"` "You won't see this key again", the key in `ClipboardText size="lg"`, the client config with the key filled in (`CodeHighlighted` + copy). Primary "I've stored the key". The plaintext lives only in component state and is dropped when the dialog closes.

Change mode = `LayerDialog` from the row menu (`ChangeAgentModeDialog`): the mode picker starting at the current mode, bypass hint, auto consent, then — right above the action — an `InsetPanel` "Now [ModeBadge] → New [ModeBadge]" with "Applies on the agent's next call" (running calls finish in the old mode; the change is audited). Primary "Change mode" is disabled until the mode differs. A refusal (400) stays in the dialog as `Banner variant="error"` with the server's message; success closes it, shows a success toast "{name} now works in {mode} mode." and refetches the list.
Revoke = `DeleteResource` with the action "Revoke key" (`deleteResourceProps(…, { action })`), success toast.

**Elevation** (ADR-0016) — a key works in a more autonomous mode for a while, then returns to its own mode by itself. The icon for anything time-boxed is Phosphor `ClockCountdown`.
- **Row menu** "Elevate temporarily" sits under "Change mode". For a key whose own mode is already `auto` nothing is above it (bypass is local), so the item is `disabled` with a `Tooltip` "Already in Auto…" (the tooltip hangs on a `render={<div />}` wrapper because a disabled Kumo menu item takes no pointer events). Never hidden.
- **Elevate dialog** (`ElevateAgentKeyDialog`, `LayerDialog size="base"`), top to bottom: an info `Banner size="sm"` "This replaces the elevation in force" when one runs (with its mode and end); "Own mode [ModeBadge]" with "Stays as it is"; a visible "Elevate to" label over `ModePicker only={modesAbove(own)}` — cards with nothing to offer are absent, the next mode up is preselected; `AutoModeConfirm` whenever the target is `auto` (also when replacing an Auto elevation); **Duration** as a `fieldset` with segmented `Tabs` presets 15 min / 1 hour (default) / 4 hours / 1 day / Custom — presets outside the server's `agentModes.elevation` bounds are dropped; Custom shows `Input type="number"` (label, "Between 5 minutes and 1 day." description, inline `error` "At least …"/"At most …" while typing, "Enter a number" after a submit attempt) next to a `Select` Minutes/Hours (hours accept a decimal comma, rounded to whole minutes); **Reason** `Input` (optional, ≤ 200 characters, "Shown in the audit log."). Right above the action, the `InsetPanel` summary: "Now [own] → Elevated [target]", then `ClockCountdown` + bold "Until 14:30 (in 1 hour), then back to Edits." (`elevationSummary`: today → time only, within the week → weekday + time, else date + time; the person's locale and time zone) and "Applies on the agent's next call. You can end it early from the key's menu." A 400 stays in the dialog as `Banner variant="error"` with the server's message; success closes it, toasts "Desk works in Auto mode until 14:30, then back to Edits." and refetches. Primary "Elevate" (`loading`), dismissal disabled while pending.
- **Mode cell while elevated** (`KeyModeCell`): the elevated `ModeBadge`, then an outline `Badge` with `ClockCountdown` "42 min left" (short units, nearest minute, at least 1) whose `Tooltip` reads "Elevated from Edits until 14:30 by you" plus the reason in quotes; under them `Text xs secondary` "Own mode: Edits", so the key's own mode stays recognisable. One line (`whitespace-nowrap`); the table scrolls sideways on phones. The page re-reads the clock every 30 s (`useNow`) and schedules a refetch one second after the earliest end (`useElevationExpiry`); a cell whose end has passed shows the own mode even before the refetch lands.
- **Summary banner** (`ElevatedKeysBanner`, top of the list, `role="status"`): "1 agent key is elevated" / "n agent keys are elevated", one line per key "Desk: Edits → Auto until 14:30", `Banner.Action` "End now" (or "End all now"). `alert` tone when any key is elevated to Auto, `default` otherwise. Keys inside the notice window (`agentModes.elevation.noticeMinutes`, 10) add a warning `Badge` with `ClockCountdown` "Ends in 8 min" to their line, and the banner adds `Banner.Action` "Extend 1 hour" (several: "Extend all 1 hour") before "End now" — the same `useExtendElevation` as the bell (§2n). The actions wrap under the text on phones. In the key's Mode cell the timer badge turns `warning` inside that window.
- **End now** (row menu, banner) acts immediately with a success toast "Elevation ended · Desk is back in Edits mode." — no confirmation dialog: it only takes autonomy away, is audited, and elevating again is one dialog away (the same reasoning as approving a non-destructive request, §2m). Failures are error toasts.
- **Agents ask** (ADR-0016 addendum): on servers reporting `features.elevationRequests`, a key whose agent waits for an elevation shows a dot `Badge warning` "Asks for Auto" under its mode, a `Link` to that site's Approvals with a `Tooltip` ("Desk asks to work in Auto mode for 1 hour. Open Approvals to decide."). It reads each site's pending list through the same cached query the site surface polls (`usePendingElevations`), without polling of its own. A grant made from a request keeps the agent's words as the key's reason; the timer tooltip renders it as "Requested by the agent: “…”".
- **Change mode while elevated**: an info `Banner size="sm"` at the top of the dialog, "Elevated to Auto until 14:30", whose description follows the selected card — "The elevation stays in force until 14:30, then the key works in Manual mode." while the new own mode is still below the elevation, "Auto reaches the elevated mode, so this change ends the elevation." otherwise (the server's rule). The list is updated from the returned summary as a whole, so an ended elevation disappears at once.

### 2h. Audit log (site › Activity)
Toolbar row: `ListToolbar` (search `Toolbar`, default size: tool, label, actor, skill) with, on the right, a ghost "Clear filters" (only while filtered), a `Toolbar` of `Select render={<Toolbar.Button />}` per facet (actor type, decision) and a `RefreshButton`, all at the default height. Empty and filtered-empty are a bare `Empty` in the table's place. `LayerCard p-0 overflow-x-auto` + `Table`, columns in reading order: Tool (localised imperative label, raw MCP name in mono below), Decision (`DecisionBadge`: filled, icon; allow = success, approval-required = warning, deny = error; an `auto`-mode publish that went live without a person — `autoCheck.lowRisk` on an allow row (older rows: reason starting "auto mode: published without approval") — adds `AutoApprovedBadge`, `warning` + `Lightning` "Auto-approved" with a localised tooltip; both via `DecisionCell`, also on the overview's recent activity), Actor (`ActorBadge` + name + the mode the call ran under as a subtle `ModeBadge`; people have none; a call made under a time-boxed elevation — `elevation: {from, until}` on the row — gets a `ClockCountdown` marker inside the badge (`role="img"`, label "Temporarily elevated") and its tooltip leads with "Temporarily elevated from Edits until 14:30"), When (relative, absolute in `Tooltip`), Outcome (`OutcomeBadge`, dot), Skill, Snapshot (link to the diff), sticky chevron `Button` that opens the row. The whole row is clickable for pointer users; the chevron is the keyboard path. Paging is cursor-based: `useInfiniteQuery` over `nextBefore`, a footer with "Showing n of m loaded events" and a secondary "Load more" (`loading`), or "You've reached the first recorded event". Filters apply to loaded rows and say so in the filtered-empty state. Search also matches the mode. Detail = `LayerDialog size="lg"`: reason as a `Banner` (error for deny, alert for approval; for an auto-approved publish an alert "Published without a person" with the article count, replacing the raw reason), a `dl` of facts (including **Mode** with a full `ModeBadge`, and for elevated calls an **Elevation** row: "Temporarily elevated from Edits until <absolute time>" with a muted line on the key's own mode) separated by `divide-kumo-hairline`, the input JSON in `CodeHighlighted`, "View changes" → snapshot diff. People's actions on keys have labels too (`agent-key.elevate` "Elevate agent key", `agent-key.mode`, `agent-key.elevation-end`); a grant row adds, under the tool name, subtle "[Edits] → [Auto ⏱]" badges (`ElevationGrant`) and an outline `Robot` badge "Requested by the agent" when its reason ends with "requested by the agent (appr_…)"; its detail adds an **Elevation granted** row (badges, "Auto mode until <absolute time>, then back to Edits.", the request id as `InlineCopyText`). The overview page shows the five newest events in a compact "Recent activity" card with "View all".

### 2i. Snapshot diff
Opened from the snapshot row's ghost "Compare" button or `?diff=<snapshotId>` (Activity links there), so it is linkable and closes back to the plain URL. `LayerDialog size="xl"`: segmented `Tabs` choosing the base (previous snapshot / live version; plain text when only one exists), counts as `Badge`s (`n added` success, `n changed` warning, `n removed` error, with icons; a zero count is `secondary`; loading is `SkeletonLine`s in an `InsetPanel`), then one section per non-empty change type: heading + count, `LayerCard p-0` + `Table` with the item (title linked to its editor, kind as an outline `Badge`, path and copyable id below; "No longer exists" for deleted nodes) and the revision (`rev a → b`). Empty states: "No differences", "Nothing to compare with".
- **Text changes** (RFC-0014 phase 2): a changed page or article row has a ghost "Show changes" (`aria-expanded`) that loads both versions from their snapshots (`GET …/snapshots/:id/nodes/:nodeId`, `content:read`; cached, snapshots never change) and shows `NodeTextChanges`: short fields as "old → new" (`<del>`/`<ins>`), then the body — or each rich-text section, with other sections as Added/Removed/Changed badges — as a `BodyDiff` (`@cloudhal/ui`). `BodyDiff` works on the markdown source: a success/danger `Badge` pair with the words added and removed; added blocks on `bg-kumo-success-tint` (`<ins>`), removed ones struck through on `bg-kumo-danger-tint` (`<del>`), edited ones on `bg-kumo-recessed` with the changed words tinted inline; a hidden "Added:"/"Removed:"/"Edited:" before each change, so colour is never the only signal; runs of unchanged blocks fold behind a ghost "3 unchanged blocks". The split and the diff are `@cloudhal/core-ts/body-blocks` (`bodyDiff`, Worker-safe; blocks aligned by longest common subsequence, removed and added blocks that still share ≥ 35 % of their words paired as edits). The release compare (§2x) shows the same `BodyDiff` for the body under its field table, live → pinned.

### 2j. Account (account surface › Settings › Account; also in the user menu)
Settings template (§2c). **Profile**: initials `Avatar` (block, `lg`), name `Input` (validated, Enter saves), email read-only `Input` with an explanation, actor ID (`user_…`, what activity and snapshots record) as `InlineCopyText`, and the person's staff role as a `RoleBadge` row (§2s). **Password**: `PasswordField` — Kumo's `InputGroup` password pattern (`InputGroup.Input` + `InputGroup.Button` eye toggle with tooltip) — for current / new / confirm; errors appear after the first submit attempt and Better Auth codes map onto fields (`INVALID_PASSWORD` → current password); "Sign out of all other sessions" `Checkbox`, checked by default; no `<form>` (Kumo `Checkbox` is a button), Enter submits. **Active sessions**: flush `Table` (device icon + "Chrome on macOS" with the raw user agent in a `Tooltip`, "This device" `Badge info`, IP in mono, last active / signed in as `RelativeTime`, ghost "Sign out" on other rows) the newest five rows with a ghost "Show all n" in the footer, and a footer action "Sign out other sessions" (the header holds only the count badge); both confirm through `ConfirmDialog` (`LayerDialog.Alert`). Better Auth lists sessions only for a sign-in younger than a day (`SESSION_NOT_FRESH`): that is `Banner variant="secondary"` with "Sign in again", not an error. **Notifications** (between sessions and access, §2n): a Kumo `Switch` "Notify me in this browser when an elevation is about to end or an agent asks for one" with a muted hint, a `SettingRow` "Browser permission" with a dot `Badge` (Allowed success / Not asked yet neutral / Blocked error), a secondary "Send a test notification" while on; denied adds `Banner variant="secondary"` explaining how to allow notifications in the browser's site settings (the switch is disabled); a browser without the API gets no switch, only a muted note. **Studio access** and **This server** are two sections. **Studio access**: the sign-up policy from `/api/instance` as a `SettingRow` with a dot `Badge` and a plain explanation of the mode (owner only / closed / open / not reported; `open` adds `Banner variant="alert"`), how to change it, and "This server" features with On/Off dot badges.

### 2k. Site settings (site › Settings tab and the sidebar group "Settings")
Settings template. **General**: name `Input`, slug read-only in an `InputGroup` with a `/` addon, default language `Select` over `site.locales`, languages as outline `Badge`s, site ID `InlineCopyText`. **Domains**: flush `Table` (hostname in mono, role `Badge info` with a star for primary / outline "Alias", row `DropdownMenu`: Visit, Make primary, Remove domain) or a flush `SectionEmpty`; an add row as a hybrid `InputGroup`: `https://` addon, input, attached secondary `InputGroup.Button` "Add domain". Input is normalised (scheme, path, case) and validated with the contract's hostname pattern; the first domain becomes primary, removing the primary promotes the next (the `ConfirmDialog` says which). Every change is a full-document `PUT` (CAS). A muted info line says DNS is configured separately. **Preview links**: `Radio appearance="card"` (current drafts / a snapshot), snapshot `Select` (label · time · live), page `InputGroup` with the primary host as addon, lifetime `Select` (1 h / 1 d / 7 d); the result is an `InsetPanel` with the URL in `ClipboardText`, "Open link" `LinkButton external`, target `Badge` and expiry; without a domain the token is shown under `Banner variant="alert"`. A server without a preview secret (`features.previewLinks === false`, or 404) gets `Banner variant="secondary"` and no form.

### 2l. Skills (account surface › Agents › Skills)
`PageLayout` (crumbs Agents › Skills) with `aside`: "How agents use skills" `SectionCard` — four numbered steps and a `Collapsible` `tools/call` example whose `_meta["cloudhal.skill"]` narrows the call; then the "Add your own" `SectionCard`). Table: skill (name, two-line description, `skill://…/SKILL.md` as `InlineCopyText`), scopes (the agent-keys `ScopeBadge`; unknown scopes as mono outline badges), tools that need approval (warning `Badge` with a hand icon, localised tool name), reference count (file names in a `Tooltip`), chevron → `SkillDetailDialog` (`LayerDialog lg`: scopes with the "never more than the key" note, approvals, requirements, reference files, `ClipboardText` resource, `CodeHighlighted` call). Empty: `Empty` with a `commandLine`; a server without MCP: `Banner variant="secondary"`.

### 2m. Approvals (site › Approvals; sidebar History › Approvals with a count)
Agents with keys cannot approve their own publish / rollback / delete (ADR-0014): the request waits here for a person. Agents in `manual` mode (ADR-0015) also send every content edit here; those requests (`cause: "manual-mode"`; older servers: reason starting "manual mode:") are not shown with the server's terse reason but replaced by a localised sentence with a `ModeBadge mode="manual"` ("{agent} works in Manual mode, so this change waits for you: Update article.") plus a muted hint, and by "Manual mode: {tool}" in History; they approve directly (no confirmation dialog), like any non-destructive tool. Every other request shows its `mode` as a subtle `ModeBadge` before the prompt; an `auto`-mode publish the low-risk rule held back (`autoCheck.lowRisk === false`) adds a muted line saying why in the person's language ("Auto mode publishes small article updates on its own. This one waits for you because it changes pages, site settings, taxonomies or redirects."). Activity and Approvals are separate sidebar items; the pending count appears on the sidebar `MenuBadge` and the overview banner from one query, refresh is in the page header actions, polled every 15 s (`refetchInterval`) only while the site shell is mounted; a 404 (approvals off) stops polling and shows `Banner variant="secondary"`.
- **Waiting for you**: one flush `SectionCard` (HandPalm icon, description) with `divide-y` rows (no nested cards): `ToolCell` (localised label + raw name), `ActorCell` (`ActorBadge` + name), Deny (secondary) / Approve (primary) with `loading`, the server's prompt as **plain text** (it can quote agent-written titles; never HTML — CI checks there is no `dangerouslySetInnerHTML`), requested / expires as `RelativeTime` with a warning `Badge` under an hour, and `Collapsible` arguments in `CodeHighlighted`. Ordered by expiry. Empty: `SectionEmpty` "Nothing is waiting for you".
- **Approve** on `publish`, `rollback`, `delete_page`, `delete_entry` opens `ApproveRequestDialog` (`LayerDialog`): the prompt in an `InsetPanel`; for publish the approximate changes (live snapshot → newest snapshot: count badges + "View changes", labelled as an approximation because edits after the newest snapshot are not counted); for rollback the target snapshot with "View changes"; for deletes the target id; and an info `Banner` "Single use, for the site as it is now" (void if anything changes before the agent calls again). `request_elevation` has its own dialog (below). Other tools and Deny act immediately with a toast.
- **409** (decided, used or expired meanwhile): error toast "This request is no longer pending", the dialog closes, the list refetches.
- **Elevation requests** (`tool: "request_elevation"`, ADR-0016 addendum; `ElevationRequest.tsx`) are a different kind of request and look it. The server's English prompt is never shown. The left cell is laid out like `ToolCell`: a 16 px `ClockCountdown` icon with "Elevation request" and the raw `request_elevation` in mono below; History uses the same cell. The body shows, in order:
  - the change as two full `ModeBadge`s, "Edits → Auto". The own mode comes from `/api/agent-keys` (`input.keyId`), else the prompt's "its own mode is …", else the request's `mode` (`requestOwnMode`);
  - a localised sentence, "Desk asks to work in Auto mode for 1 hour.";
  - the agent's reason as `AgentReason` (recessed `InsetPanel`) labelled "The agent's reason", quoted, as **plain text** (agent-controlled);
  - a muted line on what approving does. When the key's own mode has caught up with the request meanwhile, `Banner variant="secondary" size="sm"` instead says there is nothing to grant and to deny it;
  - in the meta row, `ClockCountdown` "If you approve now: until 14:30".

  **Approve** always opens `ApproveElevationDialog` (`LayerDialog size="base"`); **Deny** stays one click. Top to bottom, the dialog has:
  - `AgentReason`;
  - **Mode** with the requested `ModeBadge`, fixed (no picker), and "To grant another mode, deny this request and elevate the key from Agents.";
  - `AutoModeConfirm` when the mode is `auto`;
  - **Duration**: "Requested: 1 hour. Shorter is fine, longer isn't possible.", then segmented `Tabs` with the standard presets shorter than the request plus the request itself, preselected (`grantPresets`; an odd request reads "1 hr 30 min" in the presets' words), then Custom. Custom has the elevate dialog's number + unit fields, bounded by the server minimum and the request ("At most 1 hour");
  - an outline `InsetPanel` summary "Now [own] → Elevated [mode]", the bold "Desk works in Auto mode until 14:30, then back to Edits." and "Applies on the agent's next call…".

  The primary action is "Grant elevation" (`loading`). The POST sends `{minutes}` only when shortened. Errors:
  - A **400** stays in the dialog as `Banner variant="error"`.
  - A **409** shows the server's message plus "The request stays in the list while it is pending…", and refetches approvals and keys. If the refetch shows the request is no longer pending, the dialog closes with the "no longer pending" toast.

  On success, a toast "Elevation granted · Desk works in Auto mode until 14:30, then back to Edits." and approvals, agent keys and activity are invalidated. CI checks that the dialog is the only caller of `api.approvals.grantElevation`, renders `AutoModeConfirm` with its guard, never sends more than requested, and that the page routes elevation approvals to it first.
- **History**: flush `SectionCard` (ClockCounterClockwise icon) with a `Table` (or `SectionEmpty`): request (tool + truncated prompt in a `Tooltip`), status dot `Badge` (approved success, denied error, used neutral, expired warning), agent, requested, decided (time + "by you" or the deciding actor id). Elevation requests read `ClockCountdown` "Elevation request" over "Elevation to Auto · 1 hour" (the requested time), and a used one is "Granted" (success).
- **Overview**: while requests wait, `Banner variant="alert"` with a hand icon and `Banner.Action` "Review requests" above the cards.

### 2n. Notifications (top bar bell; ADR-0016 addendum "told before it ends")
`GET /api/notifications` lists what needs the signed-in person: their elevations ending within `noticeMinutes` (`elevation-ending`) and agents asking to elevate one of their keys (`elevation-request`). Items carry stable ids. Studio reads it with one query (`useNotifications`, key `["notifications"]`), owned by the bell, so it runs only while someone is signed in: every 60 s, every 15 s while an elevation is ending, also in a background tab (`refetchIntervalInBackground`) so browser notifications can arrive. A 404 (older server) is "no notifications": nothing is fetched again — not on an interval, on focus or on remount.
- **Bell** (`NotificationBell` block, `@cloudhal/ui`): a ghost square `Button size="sm"` with a 16 px `Bell` in the top bar, between the surface's actions and the language select, on every surface and at every width. A count `Badge variant="primary"` sits on its corner (hidden at 0, "9+" above 9); the button's name carries the count ("Notifications (2)").
- **Panel**: Kumo `Popover` (`align="end"`, `positionMethod="fixed"`, 24 rem, at most the viewport minus 1 rem) without its own padding: a header row (`Popover.Title` "Notifications", a secondary count `Badge`), a scrolling list of `NotificationItem`s divided by `divide-kumo-hairline` (max 32 rem / 70 svh), and a footer row with a ghost "Notification settings" that opens Account › Notifications. Empty: `SectionEmpty` with `BellSimple` "You're all caught up". Items whose end or expiry has passed drop out before the next poll.
- **`NotificationItem`**: a 16 px tone icon aligned with the first line (`warning` `ClockCountdown` for an ending elevation, `info` `Robot` for a request), a bold title with optional meta on the right, the body, then one row of `size="sm"` actions that wraps on phones.
  - *Elevation ending soon*: `ModeBadge` of the elevated mode + warning `Badge` `ClockCountdown` "8 min left" (recomputed from `until`), then "Desk's Auto mode ends in 8 min (14:30), then back to Edits." Actions: a `ButtonGroup` — secondary "Extend 1 hour" and a ▾ `DropdownMenu` with a "Counts from now" group of 30 min / 1 hour / 4 hours, each with its new end ("4 hours · until 18:30"); secondary "End now"; ghost `LinkButton` "Open Agents". Extend and End disable each other while pending.
  - *Agent asks*: "Planner asks for Edits · 30 min" with `RelativeTime` as meta, the reason in `AgentReason` (recessed `InsetPanel`, **plain text**: agent-controlled), and a secondary `LinkButton` "Review" to that site's Approvals.
- **Extend = re-post the mode in force** (`useExtendElevation`, `components/Elevation.tsx`): `POST /api/agent-keys/:id/elevation {mode, minutes}` with the elevated mode and the preset clamped to the server's bounds; it replaces the elevation in force and counts from now. The keys are read first, and an elevation that has ended or changed mode is refused with an error toast ("This elevation has already ended") — re-elevating is a new grant, and new grants (with the Auto consent) only happen in the elevate dialog. **End** is `useEndElevation`. Both toast, update the key list and invalidate `agent-keys`, `notifications` and `approvals`; deciding an approval invalidates `notifications` too. The bell, its toasts and the Agents banner never call the API for elevations themselves (CI checks).
- **One-time toasts** (`useNotificationAlerts`, hosted by the bell): an id seen for the first time while Studio is open raises a notice toast once — `warning` "Desk's Auto mode ends in 8 min" / "At 14:30 it goes back to Edits…" with the actions "Extend 1 hour" and "Open Agents"; `info` "Planner asks for Edits · 30 min" with the quoted reason and "Review". The toast carries the item's id (Kumo shows an id once), stays 15 s, and an action closes it. Whatever is there on the session's **first** answer is not announced (the bell lists it). Announced ids are remembered per browser in `localStorage` (`cloudhal.studio.notifications.shown`, last 200, every access in `try/catch`), so a reload never repeats one. New items also refresh the key list or approvals.
- **Browser notifications** (opt-in, Account › Notifications): turning the switch on calls `Notification.requestPermission()` from the click; the choice lives in `localStorage` (`cloudhal.studio.notifications.browser`). For each newly announced id, when the person opted in, permission is `granted` and `document.visibilityState !== "visible"`, Studio raises `new Notification(title, {body, tag: id})` with the toast's words; clicking it focuses the window and opens Agents or the site's Approvals. A visible tab gets only the toast. Delivery beyond an open tab (email, push) is not Studio's job yet.

### 2o. Search and sharing (editors and lists)
The public site emits canonical, robots `noindex`, Open Graph/Twitter tags, JSON-LD, `sitemap.xml` and RSS from what the editors store (`page.seo`; for articles the `summary` as description and `coverImage` as `og:image`). Studio edits those fields and shows their effect read-only; helpers live in `lib/seo.ts`, the cards in `components/Seo.tsx`, the visuals in the `SeoPreview` blocks (`@cloudhal/ui`).
- **Blocks** (`packages/ui/src/blocks/SeoPreview.tsx`): `ImagePreview` — the only `<img>` in Studio (`referrerPolicy="no-referrer"`): a fixed frame (`card` 1.91:1, the Open Graph crop; `thumb` 16:9, 3.5 rem) with four states, `data-image-status` empty / loading (`Loader`) / loaded / error (`ImageBroken` + label), a `caption` under the frame (the size) that an `errorHint` replaces while broken, and `onLoad` with the natural size. `SearchResultPreview` — a neutral sketch of a search result built from tokens (globe tile, site name, `host › path` breadcrumb, title in `text-kumo-link`, description; a muted italic placeholder when nothing is set; optional badge `footer`). `SocialCardPreview` — image frame, then host, bold title and two-line description. No third-party logos or fonts. All text is plain text.
- **Sources**: screens never pass a stored `src` straight to `ImagePreview`; it goes through `previewImageUrl` (the `validateImageSrc` rule: `https://…` or a site path starting with `/`, never `//`, `http:`, `data:` or other schemes — stricter than the renderer's `safeSrc`), which resolves site paths against the primary domain (`primaryHostname`). CI checks both.
- **Article › Cover image** (`CoverImageCard`, a `SectionCard` with an `Image` icon after the Article card): the description says the image comes from the media library. Body is `ImageRefField` (§2u), a `@container` grid — preview 2/5 and fields 3/5 side by side from `@md`, stacked below. The source is a media-library file chosen with the picker (`InsetPanel` "From your media library" with the file's name, type, size and a secondary "Change"; a secondary "Choose from library" while empty), then the alt text — "Alt text for this use", optional, placeholder and hint quoting the file's own alt — and, under a `Collapsible` "Use an image address instead" (open on load for an image that has only an address), the "Image URL" `Input` (mono, `inputMode="url"`, `(optional)`, hint with an example path). Typing an address detaches the library file (`editImageRef` drops `assetId`). An address image keeps the old rules: errors on the URL after leaving the field or a save attempt ("Use https://…", "Enter an https:// address or a path that starts with /"), alt "required" once a URL is set, broken-image hints explaining where site paths load from (the primary domain, or "add one in Settings › Domains"). A ghost "Remove image" in the header clears the slot; clearing both fields by hand removes `coverImage` too (the contract has no empty `src`). Dimensions are not form fields: a library file brings its own; when a *newly typed* address loads, its natural `width`/`height` are stored and shown as the caption ("1200 × 630 px"); a new URL drops stale ones.
- **Article › Search and social preview** (`ArticleSeoPreviewCard`, read-only, first card of the editor's side column): segmented `Tabs size="sm"` in the header — "Search result" (`SearchResultPreview` in an outline `InsetPanel`: site name, `host › collection › slug`, title, summary cut by `truncateForSearch`) and "Social card" (`SocialCardPreview`, `max-w-md`, the cover image). The description says the summary is used as the meta description and the cover as the share image — articles have no SEO object until RFC-0002, so no new fields. Under the preview a `dl` of `SettingRow` checks with dot `Badge`s: Title (≤ 60 good, longer "Too long"), Meta description (summary) (missing / short < 50 / good / long > 160, warning tone), Share image (missing warning, broken error, good). The Summary field itself shows "Used as the meta description…" and a counter.
- **Page › Search engines and sharing** (`PageSeoCard`, after the Page card): "SEO title" `Input` (placeholder = page title, "Leave empty to use the page title", counter `n / 60`, `maxLength` 300), "Meta description" `InputArea` (guidance "Aim for 50–160", counter `n / 160`, `maxLength` 500), "Hide from search engines" Kumo `Switch` with a hint (adds noindex; the page stays reachable) — on, it adds `Banner variant="alert"` with an `EyeSlash` icon explaining what noindex does (CI checks the switch never appears without it); `Collapsible` "Advanced" (a `Custom` info `Badge` in the trigger when set, open on load when set) with "Canonical URL" (mono `Input`, absolute `http(s)://host…` only, error after leaving the field or a save attempt, hint "Usually empty: the page's address on {primary domain} is used…"); then "Search preview" — the same `SearchResultPreview` in an `InsetPanel`, showing the canonical's host and path when valid and a warning `Badge` "Hidden from search" while noindex is on. Empty strings and `noindex: false` are removed, an empty `seo` is dropped (`applySeo`/`cleanSeo`); limits come from the contract (CI compares them).
- **Counters** (`CharacterCount`): `Text`-sized `n / recommended` at the right end of the field's description, `tabular-nums`, `text-kumo-warning` past the recommended length (the hard limit is the input's `maxLength`).
- **Saving**: every save path of both editors (Save, lifecycle buttons, Publish before the `ApprovalDialog` opens) runs `valid()` first; invalid fields show their errors, an error toast "Fix the highlighted fields before saving." appears and the card scrolls into view. CI checks no `save.mutate` is unguarded.
- **Lists**: Pages shows an outline `Badge` with `EyeSlash` "noindex" next to the title of hidden pages (`Tooltip` explains it). Articles lead the title cell with a `thumb` `ImagePreview` of the cover (an image placeholder when there is none), so rows stay aligned; site paths load from the primary domain.

### 2p. Categories, tags and redirects (RFC-0002 §8, ADR-0017)
People govern the vocabulary in Studio; agents use MCP. Helpers live in `lib/taxonomy.ts` (validation mirrors the core-ts invariants; names fold and resolve with `@cloudhal/core-ts/names`, the store's own functions) and `lib/redirects.ts`; shared cells and the data hook (`useTaxonomyData`: site, taxonomies, every term with usage, one query each) in `components/Taxonomy.tsx`. A taxonomy's label is the site's own in Studio's language, else Studio's word for the default `category`/`tag` (`taxonomy.defaults.*`), else the site's label; mid-sentence labels are lower-cased.
- **Taxonomy screen** (site › Content › "Categories & tags", list template, `routes/TaxonomyPage.tsx`, `?taxonomy=<key>&filter=<status>`): `PageLayout` tabs, one per taxonomy (categories, tags, then custom keys); header actions, left to right: a secondary square `GearSix` button (`Tooltip` and `aria-label` "Tag settings") opening the settings dialog for the current tab, secondary `FolderSimplePlus` "New taxonomy", primary "New category"/"New tag". Toolbar: search (names, synonyms, slugs) and a segmented `Tabs` filter All / Public / Internal / Proposed (warning count `Badge`) / Retired — it scrolls inside the toolbar on phones. While proposals wait, an alert `Banner` "Proposals waiting for review: n" with `Banner.Action` "Review". `LayerCard p-0` + `Table`: **Name** (`TermNameCell`: bold name in the default locale linked to the editor, state badges — warning `Hourglass` "Proposed", outline `EyeSlash` "Internal", secondary "Retired"/"Merged into X" — the archive path in mono; hierarchical taxonomies render a tree, depth-first in `position` order, each level indented with an `ArrowElbowDownRight`; a filtered child whose parent is hidden says "in News"), **Articles** ("published / total", linked to the articles list filtered by that term, `Tooltip` "n published of m"; "Last used" with `RelativeTime` below — one column so the table fits next to the aside), **Search engines** (`IndexBadge`: success dot "Indexed", warning dot "Not indexed: 1 of 3", neutral "Empty" (404), warning "noindex", or muted "No archive"/"Not public yet"; every state has a `Tooltip`; categories count their sub-tree, as archives do), **Visibility** (info "Public" / outline `EyeSlash` "Internal"), and a sticky row `DropdownMenu` — Edit, Rename slug, Merge into…, Move… (hierarchical), Make internal/public, separator, Retire (danger); a proposal's menu has Merge into an existing term… and Reject. **Proposals** show "Proposed by" with `ActorCell` (agent badge + name) and their review actions in the name cell: secondary "Approve" (one click, like approving a non-destructive request; toast), ghost "Merge…" and "Reject" (both through the governance dialog). Empty: bare `Empty` per filter; a site without taxonomies gets `Empty` with `commandLine` `cloudhal migrate tags-to-terms --dry-run` and "Preview the move". **Aside**: "Vocabulary health" (`TaxonomyHealthCard`, from `taxonomyReport` in `@cloudhal/core-ts` — the one report: MCP `taxonomy_report` only words the same result, and a parity test keeps them equal; the card reads every entry of every collection, as MCP does): near-duplicates as "LLMs → LLM" with the reason and a secondary "Merge" that opens the merge dialog prefilled (a proposed source goes through review), waiting for review (+ "Review"), articles without a primary term (required taxonomies) or without any term ("Articles without a category", hierarchical and not required), indexed archives without an intro, used once, not on any article (flat taxonomies), empty (no published article in the sub-tree: a 404) and very large categories; `SectionEmpty` "Nothing to tidy up" otherwise. Then "How categories work": structure, who adds terms, per-article rule (required · up to n), archives and the indexing threshold, as `SettingRow`s, with a ghost `GearSix` "Edit" in its header. A site without taxonomies offers "New taxonomy" next to "Preview the move" in its `Empty`. The sidebar item carries the proposal count (`Sidebar.MenuBadge`).
- **Term editor** (`routes/TermEditorPage.tsx`, editor template, `EditorLayout` with the §2f preview column): header title = name, description = taxonomy `Badge`, state badges and the archive path; actions = `PreviewToggle` (its tooltip says the preview shows unsaved changes), Approve (proposals), a secondary ⋯ `DropdownMenu` with the governance operations, primary Save (disabled until dirty). **Archive preview** (`TermArchivePreview`): unlike page and article previews it shows the *unsaved* draft — names, intro, SEO, image are posted (`POST …/terms/:id/preview`, after a 350 ms pause in typing, `keepPreviousData`) and the server's rendering of the archive page (the starter's markup, `archiveHead` title and description) is swapped into the same `sandbox=""` frame through `srcdoc`, the document carrying the preview CSP in a meta tag; the refresh spinner turns while a newer render is on its way, no skeleton per keystroke. The panel's status slot shows what the public address answers with the draft: the `IndexBadge` (indexed / "Not indexed: 2 of 3" / noindex / empty / not public yet …, the renderer's `archiveState` table) and an outline `HTTP 200|404|410` badge with a `Tooltip`; it renders the page even for a proposed, internal or empty term. "Open in new tab" opens the saved version (`GET …/preview`). A segmented `Tabs` locale switch appears above the cards on multi-locale sites (an error `Badge` marks a locale with errors after a save attempt). Main: "Names and synonyms" (`Input` name, required in the default locale; synonyms as `TagInput`, `maxValues` 50), "Archive introduction" (markdown `InputArea`, mono, counter to 20,000), "Image" (the cover-image card, §2o, retitled), "Search engines and sharing" (`SeoFields kind="archive"`, the page SEO panel's fields: counters, noindex `Switch` + its `Banner`, canonical under "Advanced", search preview of the archive path). Aside: "Indexing" (the `IndexBadge` and a sentence: "/tag/js has 2 of the 3 published articles it needs…"), "Placement" (parent + "Move…", `position` number input), "Slug history" (read-only `InsetPanel` of earlier archive paths with the redirect each left; `SectionEmpty` when none; ghost "Rename slug"), `DetailsCard`, `DangerZoneCard` "Retire this tag". Slug, parent, visibility and retirement never change through Save — only through the governance dialog. `valid()` runs before every save: default-locale name, lengths, synonyms that repeat or already name another term (invariant 12, folded like the store), SEO limits, the image rule, position 0–100,000; a retired term is read-only behind a secondary `Banner`.
- **Governance dialog** (`GovernanceDialog`, one component for rename, merge, retire, move, visibility, reject and merge-a-proposal; `LayerDialog size="lg"`, always rendered): title naming the term, a description of what the operation does, then the choice — rename: slug `InputGroup` with the archive base as addon, validated like the store (taken, reserved by a history → a `Checkbox` "Reclaim it"), earlier slugs listed; merge: a tree-aware `TermCombobox` of active terms (never the term or its sub-tree); retire: `TermCombobox` "Redirect to…" with "No redirect" and a hint that says 410 Gone (hierarchical: the public parent is the default); move: parents within depth 5 plus "Top level". Then the **preview** (a dry run, `POST …/<op> {dryRun: true}`, debounced while typing; `SkeletonLine`s while it loads; "Make a choice to see what changes." before): "Articles n" with up to five titles, paths and `Status` ("These articles change/lose it in the same operation. One change can touch up to 400 articles."), "Redirects n" as `from → to` mono rows with an outline "301 permanent" `Badge` and "Pages and feeds below the old address follow too.", existing redirects that follow along. Consequences as `Banner`s: error "Too large for one change" with the count and the 400 limit (`too_large`; the action stays disabled — also when a 409 `too_large` comes back), error "n published or in-review articles would lose their only category" (`required_term`), alert "Its archive will answer 410 Gone" / "stops being public" (404), default "becomes public". Every dialog ends with a muted `Camera` line "One change, one snapshot. It goes live with the next publish." The primary is destructive for retire and reject and disabled until the preview is in. A 409 conflict stays in the dialog; success toasts with the counts and invalidates terms, taxonomies, entries, redirects and snapshots. CI checks that only this dialog runs governance operations (approve excepted) and that it previews first.
- **Taxonomy settings** (`TaxonomySettingsDialog`, `LayerDialog size="lg"`, one component for "New taxonomy" and a taxonomy's settings; validation in `lib/taxonomy-settings.ts` mirrors core-ts `#checkTaxonomy` / `updateTaxonomy`): four sections separated by hairlines, each a `Text bold` heading with a muted line. **Name**: key `Input` (mono; lower-cased as typed; reserved words of the filter grammar — `RESERVED_FIELDS` from `@cloudhal/core-ts/filter` — and taken keys refused while typing; disabled with "Keys never change" when editing), then singular/plural `Input`s per site locale in a container-query two-column grid (default locale required, others optional but in pairs). **Terms**: `Switch` "Terms can have a parent" with its hint (an error `Banner` while terms still have parents and it is turned off); `Radio.Group appearance="card"` "Who adds new terms" — People only (`success` `ShieldCheck` "Safest"), Agents propose (`info` `Star` "Recommended"), Agents add freely (`warning` `Warning` "Use with care") — each card saying exactly what agents may do (an error `Banner` while proposals wait and "People only" is chosen). **On articles**: `Switch` Required, number `Input` "At most per article" (empty: 50), `Switch` "Applies to every collection"; off shows an `InsetPanel` of `Checkbox`es, one per collection in mono (`/posts`). **Archive pages**: `Switch` public archives, the address as an `InputGroup` with the primary host as addon (placeholder `/<key>`, follows the key until typed; errors name the colliding taxonomy, page or collection prefix), then what saving does to addresses — moving an enabled archive previews the prefix redirect the core leaves (`/category → /topics` with an outline "301 permanent" badge in an `InsetPanel`, "Pages and feeds below…", re-pointed redirects), turning archives off is an alert `Banner` "Archive pages will answer 404", turning them on a default `Banner` —, `Switch` RSS feed (disabled without archives), number `Input` "Articles needed for search engines". The `Camera` one-snapshot line closes the body; primary "Create taxonomy" / "Save settings" (disabled until something changed). A created taxonomy's tab opens.
- **New term** (`CreateTermDialog`, `LayerDialog`): name (default locale), slug derived from the name until edited (`InputGroup` with the base path), parent for categories (`TermCombobox` with "Top level"), an "Internal" `Switch` with its hint, and an alert `Banner size="sm"` "This looks like an existing term" naming near-duplicates (`similarTerms`: same folded form, plural, small edit distance). People create active terms directly.
- **Pickers** (`components/TermPickers.tsx`, article editor card "Categories and tags", `ArticleTermsCard`): hierarchical taxonomies get a multi-select `Combobox` (`TriggerMultipleWithInput`, `Combobox.Chip`) whose options are the tree — children indented with their path ("in News"), proposals marked — matched on names, synonyms and slugs; at most `maxPerEntry` (other options disabled, the description says so); one choice is the primary automatically, several show a `Select` "Primary category" (and a star on the primary chip). Required taxonomies say "Needed to send it to review or publish it"; the editor's `valid(status)` refuses review/publish without a primary (field error + toast "Choose a category first", the card scrolls into view). Flat taxonomies get the tag `Autocomplete` (`filter={null}`, suggestions from `tagSuggestions`): existing tags first — exact matches on top, then prefix and substring matches on name, synonym ("synonym “JS”") or slug, more used first; a query that resolves (RFC-0002 §6.3, plural folding included) never offers "create"; otherwise the last option is `Plus` "Create “x”" with a warning line "Looks like LLM…" when near-duplicates exist (they are listed as options too). Chosen tags are `TermChip`s (`@cloudhal/ui`) with a remove button; proposals are quieter with an `Hourglass` and a `Tooltip`. The article saves `terms` (canonical: no empty assignment) and `tags: []`; legacy `tags` on a migrated site show as a secondary `Banner` "… become tags when you save". A site without taxonomies keeps the legacy `TagInput` on `tags` and shows the migration `Banner`.
- **Migration** (`TagsMigrationBanner` + `TagsMigrationDialog`): an info `Banner` "Move your tags to categories and tags" with `Banner.Action` "Preview the move" on the articles list, the article editor and the taxonomy screen while the site has no taxonomies or entries still carry tags. The dialog runs the dry run on open and shows an `InsetPanel` summary (tags found, articles rewritten, tags new/reused, taxonomies created), skipped articles as an alert `Banner`, and "Studio takes a snapshot before and after…"; "Run the move" executes it, after which the dialog offers "Undo the move" (revert by migration id).
- **Articles list**: a Category column (primary first with a warning star, `+n` with the rest in a `Tooltip`; a warning `Badge` "No category" for review/published articles of a required taxonomy) and a Tags column (two outline `Badge`s and `+n`). Facets in the toolbar: a `Toolbar` of `Select render={<Toolbar.Button />}` — category (tree, indented) and tag (by usage) — plus a ghost "Clear filters"; they become `?category=&tag=` and the API filter `category:<slug>>*+tag:<slug>` (sub-categories included, `+` sent as `%2B`). Filtered-empty is its own `Empty`.
- **Redirects** (site › Settings › Redirects, list template, `routes/RedirectsPage.tsx`): toolbar search + a source `Select`; `Table` columns Old address (mono, `/…` for prefix redirects), Sends to (mono with an arrow; an outline "External" `Badge` with the host in a `Tooltip`), Type (`301`/`302` badge with a `Tooltip`, "and below" for prefix), Source (slug change info `TextAa`, merge secondary `ArrowsMerge`, retired warning `Archive`, manual outline `User`; the source node linked to its editor; the note), Updated, row menu (Edit, Delete → `ConfirmDialog` that says the old address answers 404 after the next publish, and that an automatic one breaks links). `RedirectDialog` (`LayerDialog`): old address in an `InputGroup` with the primary host (normalised: a pasted URL keeps its path; read-only when editing), target, "Applies to" and "Kind" as card `Radio`s (302 only for manual redirects), note; validated like core-ts (pattern, served paths — pages, published articles, public archives —, duplicates, `http:`, self and loops through existing redirects). An external https target goes through a second step: alert `Banner` "Visitors will leave for help.example.org", the host in an `InsetPanel`, primary "Redirect to help.example.org" (CI checks it).
- **Snapshot diff** (§2i): terms are named in the default locale with their archive path and link to the term editor, taxonomies by label and base path, redirects as `from → to`; changed and added articles list their term changes as outline badges under the row ("+ tag JavaScript", "− tag LLM", "Primary category → News"), from `GET …/diff/…?assignments=1`.

### 2q. Team: members and invites (account surface › Settings › Team; RFC-0005, ADR-0018)
List template (`routes/MembersPage.tsx`, `/team`, `?view=activity`), helpers in `lib/roles.ts`, dialogs in `components/MemberDialogs.tsx` and `components/InviteDialog.tsx`, badges and the explainer in `components/Roles.tsx`. The sidebar's Settings group lists **Team** (member count `MenuBadge`) above Account; the account menu has Team too.
- **Header**: `UsersThree` 24 px, title "Team", primary "Invite people" (`useGate("members.invite")`: disabled with the reason for Authors and Contributors), `PageLayout` tabs **Members | Activity** (sub-views of one page).
- **Members table** (`LayerCard p-0` + `Table`, `ListToolbar` search, `Pagination` over 25): **Member** — the `Avatar` block (initials, `@cloudhal/ui`), bold name, an outline "You" badge on the person's own row, the email in secondary text *only when the server sends it* (`members:manage`); **Role** — `RoleBadge` (icon + name, a `Tooltip` with what the role may do: Owner/Administrator `info`, Editor/Author `secondary`, Contributor `outline`); **Joined** — `RelativeTime`; sticky row menu. Owner first, then by rank and name. Below `sm` the role sits under the name and Joined is left out, so a row fits next to its menu at 375 px.
- **Row menu** (`DropdownMenu`): Change role…, Create password reset link…, Transfer ownership… (only for the Owner; on non-Administrator rows disabled with "Ownership goes only to an Administrator"), separator, Remove from team… (danger). Every item follows the rank rule (`roleChangeProblem`: self, the Owner, no `members:manage`) and stays in place **disabled with a tooltip** naming why (`GatedItem`, the tooltip on a `render={<div />}` wrapper). Someone without `members:manage` gets one disabled ⋯ trigger with the reason instead of a menu of no's.
- **Change role** (`ChangeRoleDialog`, `LayerDialog`): the member in an `InsetPanel` (identity + current `RoleBadge`), a `Select` of every role but Owner (ownership moves only by transfer) whose description is the chosen role's summary, an `InsetPanel` "Now [Editor] → [Author] · Applies at once", and for a demotion an alert `Banner` "Their agent keys narrow too". A 403 `rank` stays in the dialog in words (`members.rank.<problem>`). When the server returns `keysNarrowed`, the dialog turns into its result before closing: an info `Banner` "Agent keys narrowed: n" and one row per key (name, new mode as `ModeBadge`s when it changed, the scopes it works with now as `ScopeBadge`s, "Its elevation ended"). Otherwise a toast.
- **Remove** (`RemoveMemberDialog`, `LayerDialog.Alert`, destructive primary): the member, then what happens, one icon line each — signed out everywhere; agent keys disabled (counted from `GET /api/agent-keys?all=1` when the caller has `agents:manage`); pending invites cancelled (counted); their agents' waiting requests denied; "their articles and activity stay; inviting them again restores access". The toast repeats the server's counts.
- **Password reset link** (`ResetLinkDialog`): confirm (works once, one hour, signs them out everywhere, voids earlier links) → the link **once**, like a key reveal: alert `Banner` "You won't see this link again", `ClipboardText size="lg"`, expiry in an `InsetPanel` ("Expires in 1 hour (absolute)"). Primary "I've copied the link"; closing drops it.
- **Transfer ownership** (`TransferOwnershipDialog`, `LayerDialog.Alert`): strong words — alert `Banner` with `Crown` "You can't undo this yourself", "Ada becomes the Owner and you become an Administrator. Only Ada can give ownership back."; the change as `RoleBadge`s Administrator → Owner; three consequence lines; `PasswordField` "Your password" (re-entry; `wrong_password` lands on the field, `not_administrator` in a `Banner`); destructive primary "Transfer ownership".
- **Pending invites**: flush `SectionCard` (`EnvelopeSimple`, count `Badge`) shown to people with `members:invite`; `Table` of email (with "Link"/"Sent by email", a warning `Badge` "Not completed" for an accepted invite without an account), role, expiry ("in 7 days", rounded by `expiresIn`, the absolute time under it; a warning dot "Expired"), inviter ("You" + `RelativeTime`), row menu Re-invite (opens the invite dialog prefilled; the server replaces the pending invite) and Revoke (`ConfirmDialog`: "the link stops working at once"). Invites for roles above the person's are disabled with the reason. Empty: `SectionEmpty` with an "Invite people" button.
- **Aside**: flush `SectionCard` "Roles" — `RoleList`, each role as a badge and one sentence (the person's own marked "Your role") — and "How invites work": single use, bound to one email and role, expiry (7 days by default, Administrator invites within 72 h, from `/api/instance`), agent keys never exceed their person, one Owner.
- **Activity view**: the deployment's own feed (`ActivityList source={{kind:"deployment"}}`, `GET /api/activity`: invites, accepts, role changes, removals, transfers, key narrowing, labelled under `tools.member*`), without the skill and snapshot columns. Without `audit:read` a secondary `Banner` says who sees it.
- **Invite dialog** (`InviteDialog`, `LayerDialog`, two steps in the same parts):
  1. *Who and in which role*: `Input` email (Enter submits; errors after a submit attempt), a `Select` of `invitableRoles` from `/api/me` (an Editor sees Author and Contributor only), the expiry `Select` of presets within the server's bounds (1 hour, 1 day, 3 days, 7 days, 14 days; for Administrator at most 72 h, with the description saying so), the **role explainer** — a compact `Table` of the offered roles × Articles / Publish / Structure / Team, cells as dot `Badge`s (green all, amber limited, grey none) with a `Tooltip` each, worked out from `instance.roles.abilities` — and, when the server can mail (`invites.delivery` includes `email`), card `Radio`s "Copy a link" / "Send by email". API refusals (`rank`, `invalid_expiry`, `delivery_unavailable`, `already_member`, `too_many_invites`, `rate_limited`) are words in an error `Banner`.
  2. *The link, once*: alert `Banner` "You won't see this link again — share it privately, in a direct message; whoever opens it first joins as Editor", `ClipboardText size="lg"`, an `InsetPanel` with the role, email, "Expires in 7 days (absolute)" and "If it reaches the wrong person, revoke it from Pending invites." Primary "I've copied the link". The link lives only in component state. With email delivery step 2 is a success `Banner` "Sent to …".

### 2r. Public token pages (`/invite`, `/reset-password`)
Template `token`, the auth frame of §2e without tabs. The secret is in the URL **fragment** (`#chinv_…`, `#chrst_…`): `takeHashToken` reads it once (memoised for re-renders), strips it at once with `history.replaceState` so it never stays in history, screenshots or `Referer`s, and sends it **only in POST bodies** (`/api/invites/inspect|accept`, `/api/password-reset/inspect|complete`; CI checks). No session needed; no GET touches the token.
- **Invite**: `SkeletonLine`s while inspecting; then title "Join {deployment}", description "{inviter} invited you as {Role}", an `InsetPanel` with the `RoleBadge`, the role's summary and the expiry; the email as a read-only `Input` ("The invite is for this address"). A **new** account adds Name and `NewPasswordFields` (new + repeat, a Kumo `Meter` with "Strength: fair" and one line of advice, tones by strength); an **existing** one (a removed person invited back) gets a secondary `Banner` and its password. Primary full-width "Accept invite"; success signs in, drops every cached query of the previous person, toasts "Welcome to {deployment}" and lands on `/sites`.
- **Errors in place**: 410 or no token → error `Banner` "This invite can't be used" / "This link is incomplete" with a "Go to sign in" `LinkButton`; someone else signed in → alert `Banner` "You're signed in as …" with `Banner.Action` "Sign out" and the primary disabled with the reason; `already_member` → `Banner` with sign in; `weak_password`, `wrong_password`, `name_required` land on their fields.
- **Reset**: the same pattern — "Choose a new password" for {name}, the expiry, the email read-only, `NewPasswordFields`, "You'll be signed out on every device"; success shows "Your password is set" and a primary "Sign in" `LinkButton`; 410 says to ask for a new one (sign-in page or an Administrator).
- **Forgot password** (`/forgot-password`, template `recover`, RFC-0011): the sign-in tab shows a small "Forgot password?" `Link` under the password (always: the sign-in screen cannot read `/api/instance`). One email `Input` and "Email me a link"; the answer is the same for every address — a default `Banner` `EnvelopeSimple` "Check your email" / "If {email} belongs to an account here, a reset link is on its way…" — so the screen never tells who has an account. A server without a sender (404 `email_unavailable`) shows a secondary `Banner` "This server can't send email — ask an Administrator". Both end with "Back to sign in".

### 2s. Role gating (RFC-0005 I16)
The server decides; Studio only hides or disables what it would refuse **and says why**.
- **Source**: `GET /api/me` (`useMe`, query `["me"]`) — `role`, `scopes`, the `can` ability map, `invitableRoles`. `useCan(ability)` reads it; anything not known to be denied (loading, older servers) reads as allowed. `useGate(ability)` adds the reason, built from the least senior role that has the ability (`minimumRole` over `/api/instance` → `roles`): "Only Editors and above can publish others' work." Screens never compare role names (CI checks); only the Team screens do.
- **Patterns**: a gated `Button` is `disabled` with `title={gate.reason}` (Kumo wraps a disabled titled button in a `Tooltip`; CI checks every `disabled={!x.allowed}` carries its reason); a gated menu item stays in place, disabled, its `Tooltip` on a `render={<div />}` wrapper; a screen the person may read but not change gets `ViewOnlyBanner` (secondary, `LockSimple`, "You can view this" + the reason) and its controls go inside `ReadOnly` (a disabled `<fieldset>`: inputs, buttons and menu triggers off at once, links still work). Sidebar items stay enabled: every member may read every screen.
- **Where**: pages and the page editor (`pages.write`), categories/tags, the term editor and redirects (`structure.write`), site settings General and Domains (`settings.write`; preview links stay), the tags migration (`settings.write`), others' articles (`entryAccess`: Editors any, Authors their own, Contributors their own until published — the editor shows `ViewOnlyBanner` and a disabled fieldset, and the articles list disables Delete).
- **Publishing** (`usePublishMode`, `usePublishSite` in `components/Publish.tsx`): Editors and above "Publish"; an Author "Publish" when Studio's guess (`ownOnlyGuess`: only their own published articles changed since the live snapshot) says own-only, else **"Request publish"** with its own confirm copy ("Your changes include work by others…", "Send request"); a 202 shows an info notice "Publish requested — an Editor must approve" with "Open Approvals". A Contributor sees Publish disabled with the reason; in the article editor the draft step reads **"Submit for review"** and Publish stays disabled ("An Editor publishes yours after review"). Snapshot rows use `SnapshotTimeline`'s `publishDisabledReason` / `rollbackDisabledReason`.
- **Approvals**: `canDecide === false` disables Approve (and Deny, unless it is the person's own or their agent's request) with a reason line under the meta (`approvals.decide.*`: own request, not the key's creator, mode above the role, missing scope, not own); a 403 `cannot_decide` toasts the same words. A person's own request (cause `role`) shows a warning `Badge` `Hourglass` "Waiting for an Editor", "{name} wants to publish the site." and why their role can't alone (from the server's reason), and **Withdraw** instead of Deny/Approve. Approving such a request publishes it ("Approved and published"); 409 `state_changed` says the site moved on. People's names carry their `RoleBadge` (from `GET /api/members`) here and in Activity.
- **Agent keys**: `useAgentModeRules` carries the person's cap — `keyModes` stops at it (a Contributor's picker shows Plan, Manual, Edits and `RoleCapHint` "Your role allows agent keys up to Edits mode"), elevations offer only modes up to it, and the Elevate item is disabled with that reason. The scope picker shows each scope as the role grants it (`scopeOptions`): an own variant in place of the full scope ("Your role gives content:write only for your own work"), or the scope disabled ("Your role can't give this to a key"). A key whose `effectiveScopes` are narrower than its stored scopes shows the effective ones with a warning `Badge` "Narrowed by role" (tooltip: the creator's role now, and what it was given). Administrators get **Your keys | All keys** tabs; All keys lists every key with a "Created by" column (`Avatar`, name, `RoleBadge`) and a menu with End elevation and Revoke, while Elevate stays disabled ("Only the person who created this key can elevate it").
- **Activity**: without `audit:read` a secondary `Banner` "Your activity — Editors and above see everyone's".
- **Notifications** (§2n): `member-joined` (success `UserPlus`, "Ada joined", the role badge, "Open Team") and `role-changed` (info `ShieldStar`, "Your role is now Author", Editor → Author badges, who changed it); a new `role-changed` refetches `/api/me`, the members and the keys, so gating follows at once.
- **Account**: the profile shows the person's role as a `RoleBadge` row; the account menu's header shows the name and the role.

### 2t. Navigation menus (RFC-0003 §8, ADR-0019)
People shape the site's menus in Studio; agents propose changes over MCP and wait for approval. Helpers live in `lib/menus.ts` (draft operations through `applyMenuOps`, the item form and its contract checks, target options, the §6.3 delta lines, `draftProblem`), shared cells and hooks in `components/Menus.tsx` (`TargetChip`, `HiddenBadge`, `useHiddenReason`, `useMenuReferences`, `UsedInMenusCard`, `MenuDeleteNotice`, `useStructureWrite`).
- **Screen** (site › Settings › Navigation, editor template, `routes/NavigationPage.tsx`, `?menu=<key>&item=<itemId>`): `PageLayout` tabs per menu — "Header" (`primary`), "Footer", then custom keys; the header actions are `PreviewToggle`, secondary "New menu", ghost "Discard" while dirty and primary "Save menu" (disabled until dirty). Switching tabs with unsaved changes asks first (`ConfirmDialog`). `EditorLayout` with the preview column: main — banners (changed elsewhere, save problem, "n items are hidden on your site"), then the items `SectionCard` (flush, `TreeStructure` icon, count `Badge` "12 / 500" in the header that turns `warning` from 80 % of a limit, secondary small "Add item"); aside — "Settings" (`Select` "Levels" 1–6 with an inline error when items already sit deeper, then `SettingRow`s for items, deepest level and fullest level with the same badges), `DetailsCard` (key, id, revision, updated) and `DangerZoneCard` "Delete this menu" (`ConfirmDialog` that says the theme's derived default returns with the next publish and earlier snapshots keep the menu).
- **`MenuTree`** (`@cloudhal/ui` block; Kumo has no tree): the WAI-ARIA tree pattern on flat rows — `role="tree"` with `aria-describedby` keyboard help, rows `role="treeitem"` with `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded` on parents, a name from the label and a description from the chips; one tab stop (roving `tabIndex`). Keys: ↑/↓ move focus, →/← expand, collapse and step in and out, Home/End, `Alt+↑/↓` reorder among siblings, `Alt+→` nests under the previous sibling, `Alt+←` moves out right after the parent, Enter/F2 edit, Delete/Backspace remove; keys pressed inside a row's own controls are theirs. Every move keeps focus on the item and is announced in a polite live region ("Status nested: position 1 of 1, under Docs, level 2."); a refused move says why (first, last, no item above, top level, `maxDepth`, a full level). Pointer drag and drop is an enhancement: a drop line before/after a row (indented to its level) or a ring for "inside", refused (danger tint, nothing moves) beyond `maxDepth`, past `perLevel` or into the item's own subtree. Rows: a `DotsSixVertical` handle, the expand caret, hairline guides per level, the label (a fallback title is muted with "from the page title"), the target chip and the state badge on a second line, then the screen's actions. Controlled: the block reports `MenuTreeMove`s (`applyMenuOps` "move" semantics); `readOnly` drops handles and moves.
- **Row actions**: a ghost square "Edit" (`PencilSimple`, tooltip) and a ⋯ `DropdownMenu` — "Add item inside", "Move up", "Move down", "Move under the item above", "Move out one level", separator, "Remove" (danger). Unavailable entries stay visible and disabled; "Add item inside" and the indent at the depth limit carry a `Tooltip` on a `render={<div />}` wrapper explaining the limit. Removing an item with children confirms first (`ConfirmDialog` with the count); removing a leaf only changes the draft.
- **Target chips** (`TargetChip`, outline `Badge` with the kind's icon): "Page /about", "Article /posts/hello", "Category News", "Collection posts", "External status.example.com ↗" (host only, so a label cannot hide where a link goes; "(opens in a new tab)" for screen readers), "Group"; a deleted target reads "Deleted page".
- **Hidden items** (`HiddenBadge`, `warning` + `EyeSlash`, `secondary` for "item above is hidden"): "Hidden: page deleted", "page not published", "archive empty or not public", "term retired", "no page lists it", "nothing inside is shown", with the full explanation in a `Tooltip`. Rows hidden for a reason of their own get a secondary small "Fix" `DropdownMenu` — "Choose another target…" (the item dialog) or "Add item inside" for an empty group, and "Remove". Resolution comes from the server's preview helper (`POST /menus/preview`, the renderer's `menuLookup` + `resolveMenu`), so Studio, MCP and the site agree.
- **Item dialog** (`MenuItemDialog`, `LayerDialog lg`): the **target picker** — a grouped `Combobox` (`Combobox.Group` + `GroupLabel`): Pages, Articles, one group per taxonomy (terms as a tree, indented, retired terms left out), Collections, Other ("External link", "Group (no link)"); options show the path in mono and a status `Badge` (Draft, In review, Archived, Proposed, Internal). A target that will stay hidden adds a secondary `Banner` ("This is a draft…"). External links get a mono "Web address" `Input` (https only, validated like the contract: `http:` and user-info refused, errors after leaving the field or an attempt), an `InsetPanel` "Visitors leave for status.example.com." and the `Checkbox` "Open in a new tab". Groups explain themselves in an `InsetPanel`. Then one label `Input` per site locale: the placeholder is the fallback (the target's title, or the default-locale label for other locales), the description says what happens when it stays empty, and it is required for collection, URL and group items. New items choose a "Place" (`Select`: top level or under any item with room). The dialog edits the draft only.
- **Save** (`MenuSaveDialog`, `LayerDialog lg`): the change in the RFC-0003 §6.3 format inside an `InsetPanel` — one row per line with a coloured sign (`+` success, `−` danger, `↕`/`↳` info, `~`/`!` warning) and the sentence ("“Status” → external: status.example.com, new tab, under “Help”, position 1"; a fallback label is marked "(title)"), the description "3 changes · 14 → 15 items", an alert `Banner` when added or edited items stay hidden, and the `Camera` line "One change, one snapshot. It goes live with the next publish." Before it opens, `draftProblem` catches what the store would refuse (an empty group, a missing label, too deep, too many) as an error `Banner` and focuses the item. Confirming sends one `PUT` with the menu's `rev`. A 409 keeps the edits and shows an alert `Banner` with "Compare with latest" (rebase the draft on the newer menu; the delta then shows the difference) and "Load latest". CI checks the save path.
- **Preview** (`NavigationPreview` block in a `SectionCard` with segmented Desktop/Mobile `Tabs` and an "Unsaved changes" dot badge): a neutral sketch of the visitor-facing header (site name, top-level items, dropdowns for children up to three levels — the blog theme's — the active trail opened, external links marked) and footer ("Built with Cloudhal", the footer menu or the theme's RSS link), plus page lines between them; the edited part is tinted. "Preview as" takes a path and marks the active item with the renderer's rules (exact → underlined, prefix/context → marked; a sentence says which rule matched); a language `Select` appears on multi-locale sites. Custom keys get a secondary `Banner`: the theme decides where they appear.
- **Without a menu** (well-known keys): the main card "Current header" lists the derived items read-only in a `MenuTree` (`readOnly`), explains why, and offers primary "Create menu from current pages" and secondary "Start empty"; the aside explains "How menus work" (linked by id, hidden never broken, agents ask first, one save one snapshot). **From pages** (`FromPagesDialog`) runs the dry run on open and lists the items in an `InsetPanel` (hidden ones with their badge), a `Checkbox` "Include top-level categories (n)" re-runs it, and "Create menu" is the only write. **New menu** (`CreateMenuDialog`): card `Radio`s for the well-known places the site lacks plus "Custom key" (a slug `Input`, immutable later), and "Levels".
- **Elsewhere**: the pages list marks linked pages with an outline `TreeStructure` `Badge` "In menu" (the menus in a `Tooltip`); page, article and term editors carry "In menus" (`UsedInMenusCard`: "Header (primary) · About" linking to `?menu=primary&item=…`, or `SectionEmpty` "Not in any menu"); every page and article delete (`DeleteResource notice`) shows an alert `Banner` naming the items that will be hidden and flagged (`MenuDeleteNotice`). The snapshot diff names menu rows "Header (primary)" and adds outline badges "+2 −1 ↕1 ~0" and "3 → 4 items" (`?menus=1`). Activity labels the five MCP menu tools.
- **Who**: writes need `structure.write` (Editor and above, RFC-0005); others see the same screen read-only with a secondary `Banner`, no handles, no Save, no Add, no row actions (`useStructureWrite` reads `/api/me`'s ability map; the API refuses anyway).

### 2u. Media library (RFC-0004 §8, ADR-0020)
Files are Asset nodes; people manage them in Studio over REST, agents over MCP. Helpers live in `lib/media.ts` (the type table, sniffing and image header reader are `@cloudhal/core-ts/media`'s, so Studio refuses what the pipeline refuses before sending a byte; names, sizes in the person's locale, the details form and its checks) and `lib/uploads.ts` (the only place file bytes leave Studio); cells in `components/Media.tsx` (`KindIcon`, `AssetFrame`, `AssetBadges`, `UsageBadge`), the queue in `components/MediaUpload.tsx`, the picker and the image slot in `components/MediaPicker.tsx`, the takedown in `components/TakedownDialog.tsx`.
- **Library** (site › Content › Media, list template, `routes/MediaPage.tsx`): `Images` 24 px, primary "Upload" (`useGate("assets.upload")`, disabled with the reason; it opens the system chooser through `useFileChooser`). `ListToolbar` search (titles, alt text, captions, credits, file names; 250 ms pause) and, on the right, a ghost "Clear filters" while filtered, a `Toolbar` of `Select render={<Toolbar.Button />}` — kind (All kinds, Images, Video, Audio, Documents, Data files) and state (All files, Unused, Missing alt text, Added by agents, Retired; retired files never show otherwise) — and a segmented `Tabs` Grid | List (icon + label, the label hidden on phones; remembered per browser). The body is wrapped in `MediaDropZone variant="overlay"`: dropping files anywhere on the library opens the upload dialog with them. **Grid**: `MediaGrid` of `MediaTile`s linking to the file (`AssetFrame size="tile"`: the picture from the private content route, or the kind's icon and extension; name; "PNG · 34 KB"), solid overlay badges: usage ("Unused", "Used in 2 places") and, compact, retired and "No alt". **List**: `LayerCard p-0` + `Table` — File (`thumb`, name linked, state badges), Type (with dimensions), Size, Used in (`UsageBadge`), Added (name + `RelativeTime`), sticky `RowMenu`. Loading: `SkeletonLine`s (grid) or `TableSkeleton`; empty and filtered-empty are bare `Empty`s (the first with the Upload button). Paging is the cursor API: "Showing n files" with a secondary "Load more", or "All files are shown".
- **Upload** (`UploadDialog`, `LayerDialog lg`, and the picker's Upload tab; one `UploadPanel`): a `MediaDropZone` ("Drop files here", the limits, "Choose files"; paste works while it has focus), then an `InsetPanel` "Files" with "n of m uploaded" and one row per file — `ImagePreview thumb` of the person's own file (an object URL) or `MediaKindFrame`, name, type `Badge`, size and dimensions, and the state in words: "Checking the file…", "Ready to upload", a `Meter` with the percentage, "Uploaded", "Already in your library" (the server knew the hash), "Stopped", or the refusal in red (`media.upload.errors.*`: type not accepted, HEIC → convert to JPEG, contents don't match the type, over the cap, too many pixels, SVG with scripts, quota, taken down, link expired or used, too many uploads waiting, at most 20 at a time, connection lost). Images in the queue get an "Alt text" `Input` (required) and a `Checkbox` "Decorative — it adds nothing a reader would miss"; a photo with GPS adds an alert `Banner` "This photo contains the place it was taken" and the `Checkbox` "Keep location and camera details" (people only; stripped by default). The primary reads "Upload n files" and stays disabled until every image is described, then "Done"; dismissal is disabled while bytes move; a ghost ✕ removes a waiting file or stops one in flight. One ticket request for the batch, then one streamed `PUT` per file (three at a time), each to its own signed, single-use URL; the dialog never posts multipart forms (CI checks).
- **A file** (`routes/AssetPage.tsx`, editor template without a preview column): title = the file's name; description = kind `Badge`, `UsageBadge`, state badges and the public path in mono; actions = secondary `LinkButton` "Open file" (the private content route, new tab) and primary Save (disabled until dirty, or for a file the person may not edit). Banners: error "This file was taken down" (with the reason; the Owner gets `Banner.Action` "Allow it again"), secondary "This file is retired", `ViewOnlyBanner` when someone else uploaded it and the person lacks `assets.manage` (the server's `editable`; the form sits in `ReadOnly`). Main: "Preview" (`AssetFrame size="card"`, `fit="contain"`), "Description and credit" (a segmented locale `Tabs` on multi-locale sites; Title; for images "Alt text" `InputArea` with a `CharacterCount` against 125 and a "Decorative image" `Switch` with its hint — alt is required in the default locale unless decorative, checked by `valid()` before every save like the server's rule; Caption; Credit and License side by side in a container grid — the license `Select` offers common SPDX licences, "Another SPDX license…" with an identifier `Input`, and "Link to a license…" with address and name), "Address" (`InputGroup` with `/media/<16 hex>/` addon and the extension as suffix; old links redirect), "Used in" (flush `Table` of the nodes with kind `Badge`, title linked to its editor, path in mono, and the slot — cover, share image, section, archive image, text — or `SectionEmpty` "Not used anywhere"). Aside: "File" (`dl` of `SettingRow`s: type and MIME, size, dimensions, SHA-256 and the as-uploaded SHA-256 as `InlineCopyText` in 0.9 em mono, public URL and checksum file "live after the next publish"; ghost "Download" in the header), "Added by" (`ActorCell`, "Uploaded as …" / "Fetched from …", `RelativeTime`), `DetailsCard` (ID, revision, updated) and `DangerZoneCard items` — Retire/Restore (secondary, `assets.manage`; restore refused while taken down), Delete (`assets.manage`, disabled while used: "Used in n places. Remove those uses first, or retire it instead." → `DeleteResource` naming the file) and Take down (Owner only, `TakedownDialog`). Every disabled action carries its reason.
- **Take down** (`TakedownDialog`, `LayerDialog.Alert`): alert `Banner` "You can't undo this", an `InsetPanel` "What happens" (bytes deleted from storage and every snapshot; 410, or 451 for a legal reason; the file retires and pages lose the picture; the same bytes refused until an Owner allows them; browsers and services that saved a copy may keep it), a required "Reason" `InputArea` (audited with the name) and a `Checkbox` "This is a legal requirement (answer 451)"; destructive primary "Take down".
- **Picker** (`AssetPickerDialog`, `LayerDialog lg`): segmented `Tabs` Library | Upload. Library: a search `Input` and a `MediaGrid` of active images as toggle `MediaTile`s (brand ring and check when chosen; the slot's current file preselected), "Load more", `SectionEmpty` with a switch to Upload when there is nothing. Upload: the upload panel for one image with an inline secondary "Upload"; a finished upload becomes the choice. Primary "Use this image" writes `{assetId, src: url, alt, width, height}` (`imageRefFor`). **`ImageRefField`** is the image slot everywhere — the article cover and the term image (inside `CoverImageCard`, §2o) and the page editor's Image and Hero sections (Hero optional) — so every slot reads and behaves the same.
- **Elsewhere**: the sidebar's Content group lists Media (`Images`) after Categories & tags, and the command palette has "Go to media"; the snapshot diff names media rows by title or file name with "PNG · 34 KB" below and links them to the file (deleted files read "No longer exists"); Activity labels the agents' asset tools and people's `asset.*` events ("Upload file", "Take down file").

### 2v. Analytics (RFC-0006 §10, ADR-0021)
Cookie-less site analytics: page views and visits (unique visitors only when the owner turns them on), sources, countries, devices, Core Web Vitals, errors and crawler renders. People read them in Studio over REST, agents over MCP (`analytics:read`). The **blocks** are in `@cloudhal/ui`; the Analytics screen is below. Blocks take every word as a prop (Studio passes `useT("analytics")` strings, keys `analytics.*` in the lazy namespace `i18n/lazy/analytics.{en,tr}.ts` (§1 "Lazy message namespaces") and `pageHeaders.analytics.*`); numbers, dates and country names go through `Intl` in the Studio locale (`createAnalyticsFormatter`), times are UTC because buckets are.
- **Entries.** `StatTile`/`StatTileGroup`, `AnalyticsRangePicker`, `BreakdownTable`/`BreakdownMeters`, `AnalyticsQuotaBanner`, `AnalyticsBotBanner`, `useChartPalette` and the range (`analytics-range.ts`) and formatting (`analytics-format.ts`) helpers live in the main entry; `@cloudhal/ui` declares `sideEffects` (CSS and the ECharts registration only), so a screen pays only for the blocks it uses. Studio's build fails when analytics code reaches the initial load or the entry/initial budget is exceeded (`apps/studio/bundle-budget.ts`); the router validates the Analytics URL with `lib/analytics-search.ts` and the range checks only. The blocks that draw with ECharts — `AnalyticsTimeseries`, `CountryMap`, `ReadersSummary` — live in **`@cloudhal/ui/charts`**, which registers ECharts once with only the modules they use (`LineChart`, `BarChart`, `MapChart`, grid, tooltip, visual map, aria, mark line, brush, toolbox, `SVGRenderer`). Only the lazy Analytics route and the editors' Readers card import it, so nothing else pays for ECharts (`echarts@^6`, Apache-2.0, Kumo's optional peer).
- **`StatTile`** (in `StatTileGroup`, a `dl`): label (`Text sm` secondary) with an optional info `Button` + `Tooltip` (`hint`: "Daily unique visitors, summed"), the value as a 20 px heading in `tabular-nums` ("—" plus `emptyLabel` for screen readers when unknown), a `DeltaBadge` against the previous period — `success` + `TrendUp` up, `warning` + `TrendDown` down, `secondary` + `Minus` within ±2 % (`higherIsBetter={false}` flips the tones), its words (`describeDelta`: "+12% vs previous 30 days") in a `Tooltip` and for screen readers — and an optional `Sparkline` (token stroke, decorative). Loading = `SkeletonLine` in the value's place. Each tile is an outline `InsetPanel`. The group is a container-query grid: two columns, three from `@lg` for three tiles, four from `@2xl` for four; `density="compact"` stays at two (side columns, Readers card).
- **`AnalyticsRangePicker`** (page header `actions`): segmented `Tabs size="sm"` Today · 7 days · 30 days · 90 days · 12 months; a secondary "Custom…" `Button` (`CalendarBlank`) opening a `Popover` with Kumo's `DatePicker` (`mode="range"`, two months, `timeZone="UTC"`, the range in force preselected with its last month on the right, `today`/`endMonth`/`disabled` so nothing after today (UTC) can be picked; two clicks pick a range, a click on a finished range starts a new one) in the Studio locale through `calendarLocaleProps` (§2v Kumo locale), a "Days are in UTC" line with `GlobeHemisphereWest`, a live line with the picked range or the hint, an error past two years, ghost Cancel and primary Apply (disabled until valid); and, when the screen passes `onCompareChange`, a small "Compare" `Switch`. Controlled through `{preset}` or `{from, to}` (UTC days, `to` exclusive — the URL's `?range=30d` / `?from=&to=`); the picked days are applied on Apply. The calendar (react-day-picker and date-fns inside Kumo, ~67 kB minified) is `React.lazy` from Kumo's deep `components/date-picker` entry, preloaded on hover or focus of "Custom…", with `SkeletonLine`s until it arrives. Kumo's `DateRangePicker` is deprecated and hard-codes English: never use it. A custom range shows on the button ("Sep 1 – 30, 2026", `aria-pressed`). `resolveAnalyticsRange` turns a range into UTC days and the bucket size (hourly ≤ 2 days, daily otherwise); `previousAnalyticsRange` gives the comparison period. The two months wrap onto two rows when the popover is narrower than both (react-day-picker's `.rdp-months` wraps), so it fits a phone; the block also takes `trailing` controls (the screen's refresh button) that wrap with it.
- **`AnalyticsTimeseries`** (the "Traffic" card, 280 px; the Readers card, 120 px `type="bar"` `compact`): Kumo `TimeseriesChart` — `gradient` lines, series colours from `useChartPalette` (brand, purple, teal, orange tokens), `yAxisMinInterval={1}`, `Intl` ticks (compact numbers on the y axis), `tooltipValueFormat`, `tooltipTimestampFormat` (the bucket in the Studio locale and UTC — "Thu, Oct 8, 2026", "Oct 8, 14:00", "8 Eki 2026 Per"; Cloudhal's Kumo patch, §2v Kumo locale), `tooltipFooter` "Times in UTC", the current partial bucket dashed (`incomplete.after`), `loading`, `isDarkMode` from `data-mode`, `ariaDescription` with the numbers. Kumo's time axis works in the browser's zone, so the block shifts instants by the local offset and formats ticks and the tooltip's time back in UTC: the tooltip, the axis and day boundaries all read UTC. While loading, Kumo's skeleton (which announces "Loading chart") sits in an `aria-hidden` wrapper and a `role="status"` line speaks `labels.loading` instead. Above the plot, `ChartLegend.SmallItem`s with each series' total and a ghost "Show as table" toggle (`aria-expanded`) that swaps the plot for a scrolling, focusable `Table` of every bucket — the chart's text alternative. Overlapping axis labels are hidden.
- **`BreakdownTable`** (flush `SectionCard`s: Top content, Sources › Channels | Referrers | Campaigns, the countries list): item (16 px channel icon, title as a `Link` to its editor or **plain text** — referrer hosts are never linked, a mono detail line such as the path, a `badge` slot for the kind or "No longer exists"), the metric and an optional second metric in `tabular-nums`, and the share as a Kumo `Meter` whose label is visually hidden (the row names it) with "12%" beside it. `limit` folds the rest, server-marked `other` rows and whatever the period's `total` leaves unlisted into one muted "(other)" row (its second metric shows "—" unless it is known). Container-aware: the second metric appears from `@lg`, the bar from `@sm`, so a phone keeps names, figures and percentages. Loading = skeleton rows inside the table; no rows = the screen's `empty` (`SectionEmpty`). **`BreakdownMeters`**: the same rows as a list of labelled `Meter`s ("62% · 7,700") for devices, browsers, operating systems and an article's top channels (`showOther={false}` lists only the top rows, shares still of the whole); a bar list reads better than a pie, so no pie charts.
- **`CountryMap`** (flush "Countries" `SectionCard` in the aside): Kumo `ChoroplethMap` (`aspectRatio` 1.6, `showLegend`; the legend's ends are `labels.high`/`labels.low`, merged into ECharts' `visualMap.text` by `useChartFrame` after Kumo's own options, because Kumo hard-codes "High"/"Low") over Natural Earth 1:110m admin-0 shapes passed in by the screen (lazy-loaded; a pulsing `bg-kumo-recessed` placeholder until they arrive), joined on `ISO_A2_EH` (Natural Earth's `ISO_A2` is `-99` for some countries). **Never `tooltipFormatter`** — Kumo inserts its return value as raw HTML (the design lint refuses it in screens and blocks): the block writes each feature's localised name (`Intl.DisplayNames`) into the shapes and joins on it, so Kumo's own escaping tooltip reads "Germany · 1,204". Shading uses `log1p` so one large country does not wash out the rest (the tooltip shows the real figure); the ramp runs from the brand faded into the card to the brand pushed towards the contrast colour, and countries without data use `--color-kumo-fill` (`--color-kumo-recessed` vanishes on a dark card). Under the map, the top eight countries as a compact `BreakdownTable` (`XX` "Unknown", `T1` "Tor", the rest "Other countries") — the map's text alternative; the map itself is a `role="img"` with a description.
- **`AnalyticsQuotaBanner`**: the Free-plan warning, an alert `Banner` (`Warning` fill) with the explanation, a warning-toned `Meter` "Requests yesterday" ("62,400 of 100,000 a day") and the screen's `Banner.Action`s ("Lower vitals sampling", "Analytics settings"), wrapping under the text on phones. Shown when `shouldWarnFreePlan(requests, planHint)`: not marked paid and yesterday's page views + analytics requests + renders above 60,000.
- **`AnalyticsBotBanner`**: "possible bot traffic" (RFC-0006 §5.5), an alert `Banner` (`Robot` fill) with three parts in its description — what was seen ("1,502 page views arrived in the hour from Oct 11, 3:00 AM UTC, 250.3 times a usual hour. The numbers for this period may be inflated by scripts posing as visitors."), what to do ("Check that day's top pages and referrers. If it happens again, set analytics.rateLimit in cloudhal.json…") and a `Collapsible` "Why this warning" with one line per reason (the spike against a usual hour, the share of visits without a referrer, one browser, one page — each with the threshold it crossed) and a secondary note that it is an estimate from patterns, not proof, and that a post shared in chat apps can look the same. The screen's `Banner.Action` ("Show that day") wraps under the text on phones. Words are props; the screen words each reason from its `code`.
- **`ReadersSummary`**: the body of the editors' "Readers" card (§10.2) — compact `StatTile`s (Page views, Visits), the 120 px daily bar chart, the top three channels as `Meter`s, the slug-history line ("Old addresses still bring readers: 42 this month", `ArrowBendDownRight`) and a ghost `LinkButton` "Open in analytics" (`/analytics?filter=node:<id>`). `empty` replaces the body with the card's own state: never published, no readers yet, or — for Contributors — the reason (§2s).
- **Colour, theme and motion.** `useChartPalette` resolves Kumo's tokens to hex through the browser (a probe element and a 1×1 canvas) and again when `data-mode` or the OS scheme changes; without a canvas it falls back to Kumo's `ChartPalette`, the same family. Charts are destroyed and redrawn in the new theme. With `prefers-reduced-motion` the charts' animations, the meters' transitions and the map placeholder's pulse are off. Every chart is resized whenever its card changes width (Kumo's own observer skips its first report), including in a hidden tab.
- **Screen** (`routes/AnalyticsPage.tsx`, template `dashboard`, lazy route `/sites/:id/analytics`, RFC-0006 §10.1; cards in `components/AnalyticsSections.tsx`, words and shared hooks in `components/Analytics.tsx`, URL and vitals helpers in `lib/analytics.ts`): sidebar Overview › **Analytics** (`ChartLine`) after Overview and "Go to analytics" in the palette. `PageLayout` (crumbs `SiteCrumbs` › Analytics, `ChartLine` 24 px, "Analytics", "Visits to your site, counted without cookies or personal data.", no page tabs); `actions` = `AnalyticsRangePicker` with the compare `Switch` (on by default) and the `RefreshButton` passed as its `trailing` control, so on phones the presets fill one row and Custom… · Compare · refresh the next. The range lives in the URL (`?range=7d`, `?from=&to=`; 30 days is the plain URL, presets go to the API by name so the server's clock decides the days), `&compare=0` turns deltas and the previous-period line off, `&filter=node:<id>|channel:…|country:XX|device:…` filters every report that takes one (a secondary `Banner` with `Funnel` names it — "Showing Germany only" — with "Show all traffic"; the site-wide errors and crawler cards are left out while filtered, the vitals device switch is disabled). "Today" refetches every 60 s while visible; the refresh button invalidates every `["analytics", siteId, …]` query. Each card fetches its own report (`useReport`), shows its own skeleton, and on failure a `SectionEmpty` "This could not be loaded" with "Try again"; the summary failing shows `AnalyticsErrorBanner` above the cards ("Cloudflare's analytics service is busy" for a retryable 503). Reads wait for `/api/me` (`useAnalyticsAccess`), so a Contributor gets only the secondary `LockSimple` `Banner` "Analytics is for Authors and above" with the reason and no request.
  - **Banners**, above the cards, at most one of each: not running (secondary, `features.analytics` off or `store: "none"`), can't read yet (secondary, `reader: "none"`), the Free-plan warning (`AnalyticsQuotaBanner` with "Analytics settings" when `shouldWarnFreePlan(quota.requests, planHint)`), query budget reached (secondary, `ClockCountdown`), off for this site but with history (secondary, "Turn on in settings"), and **possible bot traffic** (`AnalyticsBotBanner`, from `…/analytics/bots`, when the level is `watch` — title "Unusual spike in page views" — or `likely` — "Possible bot traffic"; site-wide, so it ignores the filter; "Show that day" sets `?from=&to=` to the busiest hour's UTC day and is left out when that day is already shown; not asked while live reads are unavailable — can't read yet, budget spent, nothing recorded — or the period has no page views; a failed read shows nothing, since a missing warning is better than a false one).
  - **Empty states** (a bare `Empty` in the columns' place, only when the period has no page views and no filter): the server has no analytics (404) or the deployment records nothing → "Analytics is not running" with `commandLine` `cloudhal deploy`; the site is off → "Analytics is off for this site" with primary "Turn on in settings" (`useGate("analytics.settings")`, disabled with the reason; it opens `settings#analytics`); can't read yet → the A1 explanation; nothing in 12 months → "No visits yet" with "Open the site" (primary domain); a quiet period → "No visits in this period" with "Show the last 12 months".
  - **Main column**: "Traffic" (`StatTileGroup`: Page views, Visits with its info hint, Unique visitors only when on or present, Views per visit; deltas from the summary's previous period, sparklines from the series; while three tiles share two columns the third spans both; `AnalyticsTimeseries` 280 px with Page views, Visits and — when comparing — "Page views, previous period" shifted onto the current days; a muted note when the answer is partial or estimated; ghost "Export CSV" in the header → `…/analytics/export`), "Top content" (flush, `BreakdownTable` limit 10 with visits as the second metric, kind outline `Badge`, titles linked to the article, page or term editor, "No longer exists" muted; "Show all" → `LayerDialog lg` with 100 rows, `Pagination` of 20 and `showOther={false}`), "Sources" (flush; header `Tabs` Channels | Referrers | Campaigns, campaigns with their own Campaign | Source | Medium `Tabs` row; by visits; channel icons; referrer hosts plain text with a note), "Errors and redirects" (flush; header `Tabs` Broken links | Redirects; status `Badge` 404 warning, 410/451 secondary, 5xx error, 3xx info; the requested path truncated mono plain text; "Linked from" linked to the page or article editor when the path is one, else mono text or "Typed or external"; `RelativeTime`; a sticky square ghost `Signpost` button with a tooltip opens `RedirectDialog` prefilled with the path (`initialFrom`), disabled with the reason without `structure.write`; a note "Includes every error, cached or not…").
  - **Aside**: "Countries" (flush `CountryMap` over the Natural Earth shapes in `src/assets/geo`, imported with `?url` and fetched once, never cached out), "Devices" (`Tabs` Device | Browser | OS + `BreakdownMeters`, top 5 + other), "Core Web Vitals" (`Tabs` All | Mobile | Desktop; per metric the short name and full name, a rating `Badge`, a `Meter` of good samples toned success/warning/danger with "p75 2.1 sec · 80% good"; "From 1 in 5 page views…"; sampling off → `SectionEmpty` with "Analytics settings" for those who may change it), "AI and search crawlers" (flush `Table`, outline `Badge` "Cache misses only", class `Badge` AI info / Search secondary / others outline), "About this data" (`SettingRow`s: Privacy "Cookie-less" success dot, Unique visitors On/Off dot with "Change in settings", while they are on "Privacy signals" with the share of page views that sent GPC/DNT ("5% of page views"), Source live/daily totals/mixed, on Cloudflare the "Cache hits (estimated)" `Meter` ("about 90%", hint: 1 − pages rendered ÷ page views, no-JS visitors not counted; hidden when the API returns `null`), the Free-plan request `Meter` "198 of 100,000 a day on Workers Free", the live query budget `Meter` when budgeted, "Daily totals updated" `RelativeTime`; an `InsetPanel` saying when totals are computed).
  - Every Kumo string on the screen follows the Studio language (the calendar, the map legend, the chart tooltip's time and loader; §2v Kumo locale). The overview "Last 7 days" card, the editors' Readers card (`SectionCard` + 7 days | 30 days | All time `Tabs` around `ReadersSummary`) and the site settings Analytics section (§2k, RFC-0006 §10.3) are separate screens.
- **Readers card** (built, `components/Readers.tsx` + `lib/readers.ts`, keys `readers.*`, a lazy namespace loaded with the editors, the overview and the lists, §1): `ReadersCard` in the article editor's aside right after the search preview, and first in the page editor's aside (RFC-0006 §10.2 "in the page editor's too"). `SectionCard` "Readers" (`ChartLine`, `id="readers"`) with segmented `Tabs size="sm"` 7 days | **30 days** (default) | All time in its header; "All time" asks `from` = the first publish (`publishedAt`, else `createdAt`) cut to the API's two years, and is never compared; 7 and 30 days ask `compare=previous`, so the tiles carry their `DeltaBadge` ("+12% vs the previous 30 days"). Body: `ReadersSummary` from `@cloudhal/ui/charts`, **lazy** (`React.lazy` + `Suspense` with the card's skeleton lines), so the editor bundle never carries ECharts; channels ranked by visits and named in the person's language; the old-address line from `redirectHits` ("Old addresses still bring readers: 42 in the last 30 days"); "Open in analytics" → `/sites/:siteId/analytics?filter=node:<id>`; a muted line when the envelope is `partial`. States, in order: **left out** when `features.analytics` is missing, off or `store: "none"`, and when the site's own settings are off (`…/analytics/status`, read only by people who may) — nothing renders while `/api/me` and `/api/instance` are unknown, so nothing flickers; **Contributors** (`useGate("analytics.read")`) get a `SectionEmpty` (`LockSimple`) "Analytics aren't part of your role" with the gate's reason, and **no analytics request is made**; **can't read yet** (`reader: "none"`) a quiet `SectionEmpty` (`Hourglass`), no request; **never published** (`status` draft/review without `publishedAt`; pages count `archived` as published) "Stats start when this article/page is published" (`RocketLaunch`), no request; **no readers** (0 page views and 0 redirect hits) `SectionEmpty` "No readers yet"; errors → `ErrorBanner` with "Try again" inside the card. Tabs show only while numbers can be shown.
- **Overview card** (built, `OverviewAnalyticsCard`): first in the site overview's side column, `SectionCard` "Last 7 days" (`ChartLine`) with a ghost "View analytics" `LinkButton` (→ `/sites/:siteId/analytics`) in its header; body: compact `StatTileGroup` (Page views, Visits, deltas against the previous 7 days), the 120 px `AnalyticsTimeseries` line (`compact`, lazy like the Readers card) and the three most read nodes as `BreakdownMeters` (`top/node?limit=3`; shares of all page views; deleted nodes read "No longer exists"). Three requests (`summary?compare`, `series?interval=day`, `top/node`), all `range=7d`, cached 60 s. Same states as the Readers card; no visits → `SectionEmpty` "No visits yet".
- **Views column** (built, `components/ListViews.tsx` + `lib/list-views.ts`, keys `readers.listColumn.*`): the Articles and Pages lists end with a right-aligned "Views · 30 days" column before the row menu — page views per row in `tabular-nums` from **one** `top/node?range=30d&limit=100` query (the API's maximum) shared by both lists and cached 5 min; never one request per row. A node missing from a short answer shows 0; when the answer is full (100 rows) or folds the tail into `(other)`, a missing node shows a muted "—" with a `Tooltip` (and screen-reader text) "Not among the 100 most read in the last 30 days". `SkeletonLine` cells while loading. Same gating as the cards (`useAnalyticsCard`): the column is left out — with no analytics request — for Contributors, and left out when `features.analytics` is off, unreadable (`reader: "none"`), off for the site, or when the query fails. The lists are not sortable, so neither is the column.
- **Kumo locale** (built; `components/KumoLocale.tsx` at the root inside `I18nProvider`, `calendarLocaleProps` in `@cloudhal/ui`, one `pnpm patch`). Kumo 2.14 (the latest release) has no `locale` prop, and its `KumoLocaleProvider` takes only `translations.layerDialog.{close, cancel}` (plus `translations.label.{optional, moreInformation}` from our `patches/kumo/label-locale.patch`: `Label`'s "(optional)" suffix, shown by `Field`, `Checkbox` and `Select` with `required={false}`, and its tooltip button's name; Studio passes `common.optional`/`common.moreInformation`, `kumo-upstream-notes.md` §8): Studio passes `common.close`/`common.cancel`, so a `LayerDialog` without explicit `closeLabel`/`dismissLabel` speaks the Studio language and follows a switch (explicit props still win, and screens keep passing them). Everything else is reached through the props Kumo already has, without forking:
  - **Calendars** — Kumo `DatePicker` only (react-day-picker 9 inside, every DayPicker prop passes through), never the deprecated `DateRangePicker` (it hard-codes weekday initials, "Previous month", "Next month", "Edit month and year", "Timezone: ", "Reset Dates" and `en-US` day names, and names months in the browser's locale). Spread `calendarLocaleProps(locale, labels, timeZone?)` into it: `formatters` (month caption, weekday names) and `labels` (grid, weekday, day buttons with today/selected, previous/next, navigation) through `Intl` in the Studio locale, `weekStartsOn` from `Intl.Locale` week info (Sunday for en-US, Monday for tr), `lang`, and `timeZone`. No date-fns locale is shipped; the words that are not dates (`CalendarLabels`) come from `useT()`.
  - **Charts** — numbers, ticks and table cells through `createAnalyticsFormatter` (`tooltipValueFormat`, axis formats); `ChoroplethMap`'s hard-coded legend "High"/"Low" is replaced with `CountryMap`'s `labels.high`/`labels.low` by merging `visualMap.text` after Kumo's options (`useChartFrame`'s patch, lazily, like Kumo's own updates); `TimeseriesChart`'s loader (`aria-label` "Loading chart") is hidden from assistive technology while a `role="status"` line speaks `labels.loading`. ECharts' own `locale` (init option) would be reachable by passing a wrapped `echarts` whose `init` adds it, but nothing ECharts writes is shown (the aria description, ticks and tooltips are ours, the toolbox is hidden), so it is not set.
  - **The hand-written patches** (`patches/kumo/tooltip-timestamp.patch` below; `label-locale.patch` above; `rtl-icons.patch`, §1 right-to-left readiness; all folded into the generated `patches/@cloudflare__kumo@2.14.0.patch` by `scripts/kumo-patch.ts`, which also makes Kumo's utilities logical, ADR-0033 A1) — `TimeseriesChart` writes its tooltip's time with a module-level `Intl.DateTimeFormat(undefined)` (browser locale, seconds) and has no prop for it. `patches/@cloudflare__kumo@2.14.0.patch` (`patchedDependencies` in `pnpm-workspace.yaml`) adds an optional `tooltipTimestampFormat?: (timestamp: number) => string` (two lines in `dist/chunks/chart-*.js`, one in the typings); `AnalyticsTimeseries` passes the bucket in the Studio locale and UTC. A test in `packages/ui/test/analytics.test.tsx` fails if the patch is not applied. **On every Kumo upgrade:** pnpm refuses to install while the patch names a version that is not installed — check whether Kumo now has the prop (or `locale`), drop or re-create the patch (`pnpm patch @cloudflare/kumo@<version>`), and re-check every gap here and in `docs/design/kumo-upstream-notes.md` (the upstream issue texts, not filed).
  - **Left English** — nothing Studio shows. Kumo strings Studio does not reach: `TimeseriesChart`'s "+N more" (more than ten series) and "Reference marker" (markers unused), `ChoroplethMap`'s default `valueFormat` (`CountryMap` passes its own).
- **Site settings › Analytics** (`components/AnalyticsSettings.tsx`, model in `lib/analytics-settings.ts`, words in the lazy `analyticsSettings` namespace — every locale loads with the route, for the notice tabs; RFC-0006 §10.3, §2k): a `SettingsSection` `#analytics` between Domains and Preview links, in the table of contents. Header badge: dot `success` "On", `neutral` "Off", or `neutral` "Not running" when the deployment records nothing. Body, top to bottom: a secondary `Banner` for the deployment (`features.analytics` from `/api/instance`, else the settings response): "Analytics aren't running on this deployment" (`enabled: false` or `store: "none"`, with the `cloudhal.json` + deploy hint) or "Visits are recorded, but Studio can't read them yet" (`reader: "none"`, A1: nothing is lost, daily totals until reading works); then the save error or the 409 `Banner variant="alert"` "These settings changed somewhere else" + "Load latest" (the form is rebased: fields the server changed take its value, other unsaved edits stay); then the controls inside `ReadOnly` — `Switch` "Count visits" ("Adds a 1 KB script… No cookies"), `Switch` "Count unique visitors" with its cookie-less explanation (disabled while visits are off). Turning unique visitors **on** first opens a `LayerDialog.Alert` (alert `Banner` with `ShieldWarning` "This is processing of personal data", the unique-visitors notice paragraph to add to the privacy policy, primary "Count unique visitors"; Cancel leaves it off); turning it **off** shows an alert `Banner size="sm"` "Saving deletes today's random value", which says the salt is per deployment, so it goes for every site at once and other sites' unique counts may count someone twice later that day. A container-query grid of `Select`s (array items, so the order is the RFC's): "Measure page speed" (Off, 1 in 20, 1 in 10, 1 in 5 (default), 1 in 2, Every page view; the description adds the request cost, "Adds about 20% more requests"), "Keep daily totals" (Forever (default), 5/2/1 years; another stored value shows as "n days"), "Cloudflare plan" (Not sure, Workers Free, Workers Paid; it only drives the quota warning). Outside `ReadOnly`, so readers can still copy it: "Privacy notice for your site" — segmented `Tabs` English | Türkçe (the Studio locale first), the §6.5 paragraph in an `InsetPanel recessed` (with `lang`) in the variant the switches give *now* (the hint says so while unsaved), "This is information, not legal advice.", and a secondary "Copy notice" `Button` (`Copy`; heading and paragraphs as plain text; success toast). A paragraph reads badly in `ClipboardText`'s one-line mono field, hence the button. Last, a `dl` of `SettingRow`s about the deployment: Recorded in (dot `Badge`), Read from (`warning` dot when not yet), Daily totals ("Computed every hour" with the Cron Trigger hint, or "Computed when someone opens Analytics"), Live data ("Last 92 days"). Footer: ghost "Discard" while dirty, primary "Save changes". The PUT sends `rev` and only the changed fields; the success toast says when the site follows ("within a minute" after the purge, "as cached pages expire" when it failed) or that today's random value was deleted. **Gating**: reading needs `analytics.read` (Authors and above; a Contributor gets a secondary `Banner` with `LockSimple` and the reason, and nothing is fetched), changing needs `analytics.settings` (Administrators and above): switches and Save are `disabled` with `title={gate.reason}`, the selects sit in `ReadOnly`. A server without the analytics routes (404) gets "This server doesn't offer analytics" and no form.
- **Agent keys › "Allow analytics"** (`components/AnalyticsKeyAccess.tsx`, RFC-0006 §9.1 and open question 4): keys are never widened on their own, so a key without `analytics:read` (made before it existed, or customised without it) shows under its scopes an outline `Badge` "No analytics" (`Tooltip`: why, and that analytics are totals only, no personal data) and a secondary `Button size="xs"` "Allow analytics" (`ChartLine`). One click, no confirmation (it adds one read-only scope and is audited as `agent-key.scopes`): `PATCH /api/agent-keys/:id {addScopes: ["analytics:read"]}`, success toast "Analytics allowed · Desk can read site analytics from its next call.", the list refetches and the hint goes; a refusal is an error toast with the server's message. Gated by the person's own `analytics.read` for their keys and, in the Administrators' "All keys" view, by whether the key creator's role can read analytics ("Cem's role can't read analytics, so their keys can't either."): `disabled` with `title={access.reason}`. Disabled keys and keys that hold the scope show nothing.

### 2w. Comments (RFC-0007 §14, ADR-0022)
Reader comments live outside the graph (D1/SQLite), are read and moderated by people over REST and by agents over MCP, and every comment, name, report and agent note is **untrusted reader text**. The **blocks** (`@cloudhal/ui`, below) and the **screens** (end of this section) are built. Words go through two lazy namespaces (§1): `comments` (queue, thread, commenter, approvals, editor card) and `commentsSettings` (settings); the shell keeps `nav.comments` and `commands.goComments`. Blocks take every word as a prop — one shared `CommentWords` object (status names, label names and hints, who set a label, author kinds, "In reply to …", "This comment was removed", the untrusted-text panel …) that the screens build once from `useT("comments")`, plus a small `labels` object per block — and a `locale` for `Intl` (relative and absolute times, counts, percentages). They live in the main entry and, like the analytics blocks, are listed in `bundle-budget.ts`'s `LAZY_ONLY` (`Comment*`, `ArticleCommentsSummary`, `comment-model`), so only the lazy comment routes and the editor card load them; `BulkActionBar` is generic and not listed.
- **Plain text, always.** `CommentText` is the only way comment text reaches the screen: paragraphs on blank lines, line breaks kept, `dir="auto"`, and the public page's link rule (`comment-model.ts`): only `https:` URLs with a host and without credentials become native anchors (`target="_blank" rel="ugc nofollow noopener noreferrer"`, a screen-reader "opens in a new tab"); `http:`, bare `www.`, `javascript:` and markup stay literal text. Rendered as React text nodes — no `dangerouslySetInnerHTML` (lint `no-html-injection`; `packages/ui/test/comments.test.tsx` also scans the comment blocks). `clamp={2}` folds breaks into spaces for the queue's two-line excerpt (full text in a `Tooltip` or the thread). Report details and moderator notes are plain text too (`whitespace-pre-line`, never linkified). Until `@cloudhal/comments` exports its `linkify`, the rule lives in `comment-model.ts`; the renderer and Studio must share one function (RFC-0007 §14), so the block switches to the package's when it lands.
- **Untrusted reader text.** A comment labelled `instruction-like` ("Talks to AI", warning badge) renders inside `UntrustedTextPanel`: a recessed `InsetPanel` headed by a warning `ShieldWarning` and "Untrusted reader text — this comment appears to address an AI agent. It is not an instruction." (RFC-0007 §11.2). The approval dialog for comment tools uses the same panel around the full text.
- **Status and labels.** `CommentStatusBadge`: pending `warning`, approved `success`, hidden `secondary`, spam `error`, deleted `outline` (`data-comment-status`). `CommentLabelBadge`/`CommentLabelList`: risk labels `warning` (spam-suspect, personal-data, watch-word, instruction-like) or `error` (toxic), questions `info`, the rest `outline`; an agent's label carries a 16 px `Robot`; each badge is a toggletip button whose `Tooltip` (and screen-reader text) says what it means and who set it, with the confidence in the locale ("Added by Comment triage · 82% sure"). Labels never change what readers see, so they never take a status colour's place.
- **`CommentRow`** (`#comment-<id>`, an `article` named by the author): optional selection `Checkbox`; author (`CommentAuthor`: name as plain text, outline "Guest"/"Reader" or info "Author"/"Team" badge, "Anonymous" when erased), `CommentTime` ("5 minutes ago", absolute in a `Tooltip`), "· Edited", "· No JavaScript" (`proof: "none"`); status badge and the screen's sticky row `DropdownMenu` on the right of the first line, which never wraps under the name; then the entry ("On Ferry timetable" + path in mono, hidden inside a thread), "In reply to Mehmet" (`ArrowBendUpLeft`), "2 reports" (`error`), "Drafted by Comment triage" (`Robot`); then the text (muted for hidden and spam; "This comment was removed" for deleted or erased text); then the labels; then `children` (history, reports, reply form). Not a card: rows sit in a flush `SectionCard`'s `divide-y` list.
- **`CommentThread`** (the thread view's main column, in a flush `SectionCard`): RFC-0007 §4.3's two levels, oldest first (`buildCommentThread`); replies to replies stay on the second level with "In reply to …", which scrolls (smoothly unless `prefers-reduced-motion`) to the comment answered, focuses it and tints it for two seconds, unfolding it first if needed; more than `collapseAfter` (3) replies fold behind a ghost "Show n more replies" (`aria-expanded`, `aria-controls`); replies whose top-level comment is missing hang under a "This comment was removed" placeholder. Replies are indented by a hairline `border-l` (`ml-4`, `sm:ml-8`). Slots: `renderActions`, `renderDetails` (history, reports, statement of reasons), `renderReply` (the staff reply form under the comment answered), `selection`. States: `loading` (skeleton rows and a `role="status"` line), `empty` (`SectionEmpty`), `error` (an error `Banner` with "Try again").
- **`BulkActionBar`** (replaces the queue's `ListToolbar` while rows are selected): a `fieldset` the toolbar's height (`min-h-9`, `bg-kumo-tint`, `ring-kumo-line`) so the table does not move — select-all `Checkbox` (checked, indeterminate or clear), "12 selected" in a polite live region, the actions as `size="sm"` buttons (the safe one `primary`, the rest `secondary`), ghost "Clear" (`X`); Escape clears; wraps on phones. A disabled action keeps its reason: Kumo's `title` tooltip on the wrapper and the button's accessible description ("Only people can approve comments").
- **`CommentFilters`** (right of the queue's `ListToolbar`, like the media library's filters): a Kumo `Toolbar` of `Select render={<Toolbar.Button />}` — `facets` in order from status (left out on the queue, whose page tabs are the status), entry ("All articles" + titles, `entriesLoading`), label, actor ("Hidden or labelled by agents", RFC-0007 §11.2 point 4) and date (Any time, 24 hours, 7/30/90 days; `commentFilterSince` gives the API's `since`) — and a ghost "Clear filters" that resets only the facets shown. On phones the joined selects scroll inside the toolbar, never the page.
- **`CommenterSummary`** (the commenter page's identity card, `commenters:data` only): a `dl` of rows — names used (outline badges, plain text), email in mono **only when `canSeeEmail`** (the block ignores a passed address otherwise), first and last comment (date and relative time), ban (`error` "Banned until 10 Jan 2027" / "Banned until lifted" with the subjects and reason, or a neutral dot "Not banned") — then the comments counted by status in an `InsetPanel` (two columns, five from `@md`), then the screen's actions (Ban…, Export their data, Erase…).
- **`StatementOfReasons`** (EU DSA Art. 17; thread details of a hidden, spam or deleted comment and the commenter's export preview): a labelled `InsetPanel` `dl` — decision and what it does ("Hidden — removed from the public page"), grounds (the reason code in words), facts and circumstances (the note, plain text), automated means (yes / a person decided), decided by (`ActorBadge` + name, "Approved by Ayşe for Comment triage" when a person approved an agent's request), decided on, and optionally how to contest it. **`CommentHistory`**: the `comment_events` rows in a `Collapsible` "History (n)", newest first — action, reason, time, actor, note; no comment text is ever in an event.
- **`CommentReports`** (DSA Art. 16 notices on one comment, thread details and the Reported tab): `Flag` and "2 of 3 reports open" with an outline badge per reason, then each report — reason badge (`error` for illegal content, else `warning`), open/resolved dot badge, time, the reader's details as plain text in a recessed `InsetPanel`, the resolution — open reports first, with the screen's "Resolve…" on open ones. A report never changes a status by itself.
- **`ArticleCommentsSummary`** (the body of the article editor's "Comments" `SectionCard`, `ChatsCircle`, aside after Readers): the thread mode as segmented `Tabs size="sm"` Default · Open · Closed · Hidden (or, without permission, the mode as an outline badge with the reason, §2s), "Readers see" + the effective state as a dot badge (open `success`, closed/off `neutral`, hidden `warning`), the close line with `CalendarBlank` and a ghost "Change" (opens the "Close on…" `DatePicker` through `calendarLocaleProps`), the counts as badges (approved `success`; pending `warning` and reported `error` only when above zero) and a ghost `LinkButton` "Moderate" to the thread. `empty` replaces the body (comments off for the collection with "Comment settings"; never published "Comments open when this article is published"; Contributors' reason), `loading` shows skeleton lines.
- **Screens (as built, RFC-0007 step 8).** Routes `/sites/:siteId/comments` (`?tab=`), `/sites/:siteId/comments/:nodeId` (`?comment=` lands on one, `?reply=` opens the reply form) and `/sites/:siteId/commenters/:commenterId`, lazy with the `comments` namespace; every gated query waits for `/api/me`, so a role that may not see something never asks for it.
  - **Queue** `routes/CommentsPage.tsx` (template `moderation`: `PageLayout`, `ListToolbar`/`BulkActionBar`, `LayerCard p-0` of `CommentRow`s, `Empty`, `Pagination`). The rows are `CommentRow`s, not table cells, so the untrusted panel, labels and reports fit at 390 px. Page `tabs` Pending (n) · Reported (n) · Approved · Spam · Hidden; `ListToolbar` search (names and text of the loaded page — the API has no text search yet) + `CommentFilters` (article, label, "Hidden or labelled by agents", date) + `RefreshButton`; each row has a selection `Checkbox` and the `CommentMenu` (`components/Comments.tsx`: Approve/Restore, Hide…, Mark as spam…, Back to pending, Delete… for Editors, Resolve report…, Reply, Open thread, Commenter… — each item disabled with its `useGate` reason). While rows are selected `BulkActionBar` replaces the toolbar: the tab's actions (`bulkActionsFor`), only for the selected comments the action fits (`eligibleFor`), disabled with the reason (the role, or "none of the selected comments can be …"); no bulk delete (the API deletes one comment at a time). Hide…/Spam…/Delete… open `ModerateDialog` (reason `Select` in words, optional note; Delete is a `LayerDialog.Alert`). A bulk call answers per comment: one toast when all went through, "1 of 2 comments approved" with one line per reason otherwise, an error badge on each row left as it was (`FailedBadge`), the failed ones stay selected, and conflicts add an alert `Banner` with "Reload". Pending agent requests show an info `Banner` "Comment triage asks to approve 2 comments" → Approvals. `Pagination` follows the API's cursor (`hasNextPage`, sequential). Aside: "How moderation works" (`SettingRow`s) and "Today" (daily-cap `Meter`, purges waiting with "Purge site cache", Comment settings, Export comments / with emails for those allowed). Sidebar Content › Comments (`ChatsCircle`) with the pending `MenuBadge` from the bell's `comments-pending` digest (own articles for Authors), only when `features.comments.available` and `comments.read`; palette "Go to comments"; overview `CommentsWaitingBanner` "4 comments are waiting".
  - **Thread** `routes/CommentThreadPage.tsx` (template `editor`, `EditorLayout` without preview): title = the article, description = state dot badge + "Closes on …", action "Open article". Main: a flush `SectionCard` with `CommentThread` (every status, oldest first, cursor "Load more comments"); per comment the `CommentMenu` (an Author on someone else's article gets the reason), and details read with `GET …/comments/:id` when they matter (reports, a removal, the comment linked to) or on "History": `StatementOfReasons` for hidden/spam/deleted, `CommentReports` with "Resolve…" (`LayerDialog`, required resolution), `CommentHistory`. The staff reply form opens under the comment answered: `InputArea` with a live counter to 5,000, a recessed `InsetPanel` preview of exactly what the page will show (`CommentAuthor` with the badge it will carry — Author on one's own article, else Team — and `CommentText`), "Publish reply". Aside: "Thread" card (segmented mode `Tabs`, mode hint, Readers see, Close date + "Change" → `CloseDateDialog` with `DatePicker` + `calendarLocaleProps`, end of the day UTC, "Remove close date"; Hidden asks first, `HideThreadConfirm`) and `DetailsCard` (article id, path, counts). Thread writes send the thread's `rev`; a 409 says so and re-reads.
  - **Commenter** `routes/CommenterPage.tsx` (template `editor`; `commenters:data` only — others get `ViewOnlyBanner` and no request): main = their latest 50 comments as `CommentRow`s (menu: Reply, Open thread); aside = Identity `SectionCard` with `CommenterSummary` (email only here) and its actions: Ban… (`LayerDialog`: duration, reason, email and/or network `Checkbox`es with what each does, note, "Also hide their approved comments") or "Lift ban" (bans found with `GET …/comment-bans?commentId=`), Export their data (downloads the JSON), Erase… (`LayerDialog.Alert`, `Radio appearance="card"` Anonymise / Also delete the text, an `InsetPanel` of what happens that follows the choice, required reason, destructive "Erase"). Without `CLOUDHAL_COMMENTS_KEY` (503) a `Banner` says why there is no email.
  - **Settings › Comments** (`components/CommentSettings.tsx`, `lib/comment-settings.ts`, `SettingsSection #comments`, words in `commentsSettings`): `Switch` Accept comments; collections as `Checkbox`es (`/posts` in mono) each with its own "Close threads in /posts" `Select` (Same as the site, Never, 14…365 days); keep visible while off; close after; bot protection `Radio appearance="card"` (proof of work with a "Default" badge, or Turnstile → site key `Input` and the write-only secret: `SensitiveInput` + "Save secret", then "Saved {date}" with ghost Replace / Remove — never read back; without the comments key a `Banner`; the CSP note); JavaScript-less posting; link limit and daily cap (`Input type=number`, the cap's D1 writes in its description, today's `Meter`); watch and blocked words (`TagInput`); Workers AI labels (a `LayerDialog.Alert` first; disabled while `features.comments.aiLabels` is false); retention `Select`s (client data at most 30 days); the disclosure snippet with English | Türkçe `Tabs` that follows the switches, "Copy notice". One PUT with only the changed fields and `rev`; a 409 shows "These settings changed somewhere else" + "Load latest" and keeps other edits (`rebase`). Read with `comments.read`, changed with `comments.settings` (`ReadOnly` otherwise).
  - **Editor card** `components/ArticleCommentsCard.tsx` (aside after Readers): `ArticleCommentsSummary` with the mode tabs (Hidden confirmed first), the close line and "Change" (`CloseDateDialog`), counts and "Moderate"; nothing at all without comments on the deployment; Contributors see the reason, never-published articles "Comments open when this article is published", collections that are off "Comments are off for this collection" with "Comment settings" for Administrators; an Author on someone else's article sees the mode, not a control.
  - **Approvals** (§2m, `components/CommentApprovals.tsx`): a comment request reads in words ("Approve 2 comments", "Publish a reply" with the drafted text quoted in a recessed `InsetPanel`, plain text) instead of the server's English prompt, and tool labels name the seven comment tools. Approve opens `ApproveCommentsDialog` (`LayerDialog lg`): an info `Banner` "Single use, for these comments as they are now", the comments themselves as `CommentRow`s in an outline `InsetPanel` (untrusted panel included), for a reply the answered comment, the draft and "Publishes as you, Ayşe, with the Team badge", for a thread the article and the new mode/close date; the primary "Approve 2 comments" / "Publish reply" / "Open thread" carries the call out. The toast says what was done (with "1 of 2 done" from the tool's results); 409 `state_changed` says the comments changed after the agent asked and the request closed; 409 `carry_out_failed` says it was approved but could not be carried out.
  - **Notifications** (§2n): the bell renders all five `comments-*` kinds (`ChatsCircle` info for pending with the oldest's wait, `Flag` warning for reported, `PauseCircle` warning for paused, `ClockCountdown` warning for purge waiting with "Purge site cache", `Robot` info for an agent's comment request) with Review / Comment settings / Open comments; toasts and browser notifications use the same words; a new comment item refreshes the queue. Unknown kinds from a newer server are left out of the bell. Links with `?`/`#` go through `splitHref` (search and hash).
  - **Agents page**: `AllowComments` (`components/CommentKeyAccess.tsx`) next to "Allow analytics": "No comments" + "Allow comments" (`addScopes: ["comments:read"]`) for keys without it, gated like analytics (the creator's role for others' keys); a server that answers `scope_not_addable` is remembered for the session and only the badge stays, with a hint to create a new key. Keys that read comments and can change content carry the §11.2 point 5 warning badge "Reads comments, edits content". No triage key template yet.

### 2x. Schedules (RFC-0008 §15, ADR-0023)
Releases, embargoes, scheduled publishing and automations on one calendar. The **blocks** are in `@cloudhal/ui` (below); the **screens** (RFC-0008 §15.1) are described at the end of this section. Blocks take every word as a prop — one shared `ScheduleWords` object (kind names and the state names of releases, automations, runs and approvals) that the screens build once from `useT("schedules")` (a lazy namespace, §1), plus a small `labels` object per block — and dates as plain values: instants as RFC 3339 strings placed and timed in the site's `timeZone` (IANA, `Site.timeZone`, UTC when absent), calendar days as `YYYY-MM-DD`, a `locale` for `Intl` and `weekStartsOn` from `firstDayOfWeek(locale)` (Monday in Turkish). There is no date library: day arithmetic runs on UTC-midnight calendar dates (`schedule-model.ts`), names and times come from `Intl` (24-hour where the locale is, `hourCycleOf`), recurrence is expanded by the server and only shown (`NextRuns`). The blocks are in `bundle-budget.ts`'s `LAZY_ONLY`, so they load with the lazy schedule routes and the lazily loaded "Schedule…" dialog, never with the shell (about 44 kB minified, 14 kB gzip for all twelve, Kumo and icons aside); the calendar inside `DateTimeField` is Kumo's `DatePicker`, `React.lazy` like the analytics range's.
- **Visual language** (RFC-0008 §15.3): **fill = certainty, tone = state, icon = kind and origin; colour is never the only signal** (WCAG 1.4.1). `scheduleLook` maps an entry to one of nine looks: `quiet` (scheduled by a person or approved: `bg-kumo-tint`, the kind icon — publish and embargo `CalendarCheck`, expiry `CalendarX`, release `Package`, automation `Robot`), `auto` (the same + `Lightning`, the `AutoApprovedBadge` language), **`proposed`** (draft or waiting for approval: a **dashed `border-kumo-warning` outline with no fill**, `Robot` for an agent's + `HandPalm`), `struck` (denied, expired, canceled, skipped, stopped: `line-through`, `text-kumo-inactive`; hidden by default views, `isHiddenByDefault`), `danger` (conflict `Warning`, failed `WarningCircle`, missed `ClockCounterClockwise`, broken `LinkBreak`: `bg-kumo-danger-tint`), `running` (`bg-kumo-info-tint` + a turning `CircleNotch`, still under `prefers-reduced-motion`), `done` (published, ran: `bg-kumo-recessed`, muted), `ghost` (a future recurring occurrence: outline ring only, `ArrowsClockwise`) and `paused` (the ghost with `Pause`). **The dashed outline (D14)** is drawn only inside `ScheduleItem`, as `border border-dashed` without any shadow, because §4's `ring` edges cannot be dashed. The design lint's `shadow-borders` and `no-ad-hoc-surface` rules apply to screens, not to `packages/ui/src/blocks`, so the block needs no lint exception — and a screen that draws its own dashed card still fails.
- **`ScheduleStatusBadge`** — every state of `Release` (RFC §5.2), `Automation` and `ScheduleRun` (§5.3) and of an approval, as a Kumo `Badge` with an icon and the state's word: draft outline `PencilSimpleLine`, waiting for approval `warning` `HandPalm` (+ an outline `ClockCountdown` badge with `timeLeft`), scheduled outline `CalendarBlank`, publishing/running `info` with a turning `CircleNotch` inside `role="status"`, published/ran/active `success`, conflict/failed/missed/broken `error`, expired/canceled/skipped/stopped/paused `secondary`, paused by Cloudhal and over budget `warning` (`PauseCircle`, `Gauge`), ended/due outline; approvals: approved outline `CheckCircle`, automatic `warning` `Lightning`, denied `error` `Prohibit`. A `reason` makes it a toggletip button (keyboard too, and in the accessible name). `data-subject`/`data-state` for tests.
- **`ScheduleItem`** — `variant="chip"`: a button at least 24 px tall (SC 2.5.8) with the look's icons, the time (`tabular-nums`) and the truncated title; its accessible name is the whole sentence (`scheduleItemSentence`: "09:00, Publish, Election results, proposed by Desk, Waiting for approval, 3 h left", or the screen's own `entry.label`). `variant="row"` (the agenda, the "+N more" popover, the phone day list): time, kind icon with its word for screen readers, the title (`Link` when `href`, struck through when struck), `meta` (collection, locale, terms), `origin` (`ActorBadge` + `ModeBadge subtle`), the status badge — none for the quiet "Scheduled", the approval's own badge for approved or automatic — and `actions` (Deny/Approve, the ⋯ menu whose "Move to…" is the single-pointer twin of dragging, SC 2.5.7); it wraps on phones.
- **`CalendarMonth`** (Month view, RFC §15.2, §15.7) — a WAI-ARIA APG date grid on a fixed Kumo `Table` (`role="grid"`, seven columns from `weekStartsOn`, short weekday headers with the long name for screen readers) with **one tab stop** and a roving `tabindex`: arrows by day and week, Home/End to the week's ends, PageUp/PageDown by month (Shift: year) — leaving the shown weeks asks `onMonthChange(month, day)` and focus follows; Enter or F2 into the day's chips (arrows between them; chips are never tab stops), Escape back to the day. Cells are named by the screen (`labels.day`: "Monday 12 October, today, 3 items: 2 publishes, 1 waiting for approval"); today has `aria-current="date"`; past days and weekends are `bg-kumo-recessed`; entries land on their day in the site zone (23:30 UTC is tomorrow in Istanbul). At most `maxChips` (3) chips, then a "+N more" `Popover` with the day's rows. **Moving:** with `onMove`, chips of `movable` entries (future, not running, not locked, not an occurrence — the screen decides) drag onto another day (native drag and drop on desktop chips, no drag library), and Alt+arrow on a focused chip is the keyboard twin; both only call `onMove({entry, fromDay, toDay, via})` — the screen opens `RescheduleDialog` with the old time on the new day, nothing is optimistic. A polite `role="status"` region speaks the screen's `announcement`. **Phones** (`density="dots"`, or `auto` at ≤ 640 px through `matchMedia`): a cell is the day number and up to three dots in the looks' tones plus a warning approval dot (decorative; the cell's name carries the counts), the whole cell is the target and selects the day (`aria-selected`, Enter or Space), and the chosen day's rows show under the grid ("Today · Monday 12 October", or `labels.emptyDay`).
- **`AgendaList`** (Agenda view, the default on every width) — entries grouped by their day in the site zone under **sticky** `h3` day headings (`top-12`, under the top bar, `border-b border-kumo-line`; `stick="top"` inside other scroll containers), rows in a `divide-y` list; today gets a "Now" rule (a danger hairline with the word, read by screen readers) between past and future, its finished items fold behind a ghost "3 done today" (`aria-expanded`), and a day's recurring runs past `foldRecurringAfter` (3) fold behind "21 more automation runs". Loading = `SkeletonLine`s with a status line; nothing = a frameless `SectionEmpty` (`CalendarDots`) with the screen's `emptyContents`; cursor paging = a secondary "Load more" (`loading`). The view switch tells screen readers the agenda is a complete equivalent of the month.
- **`CalendarNav`** — a `fieldset` named by `labels.group`: secondary square ‹ › buttons (`aria-label`) around "Today" (disabled while today is shown), the period ("October 2026") in a polite live region, a `goTo` slot for the screen's "Go to date" `Popover` + `DatePicker`, and the Agenda | Month segmented `Tabs` with `viewHint`. Shortcuts (`j`/`k`, `g t`, `a`/`m`, `g d`) are the screen's and call the same handlers.
- **`ScheduleFilters`** (the `CommentFilters` pattern) — a Kumo `Toolbar` of facet buttons (kind, state, origin, approval, collection, category or tag, language — whichever the screen passes, with worded options), each opening a `DropdownMenu` of checkbox items (every facet is multi-valued; the menu stays open while ticking), the count as a `Badge` and in the button's name ("Kind, 2 selected"); a ghost "Clear filters" while anything narrows; and the view menu (`BookmarkSimple`: built-in views first — All, Waiting for approval, Proposed by agents, This week, Needs attention, Mine — then saved ones, and "Save view…") as radio items. Controlled; the URL is the screen's (`lib/schedules-search.ts`). A `DropdownMenu` checkbox list is lighter than RFC §15.4's `Combobox multiple` in a `Popover` and fits the short facets; long ones (terms) may move to a `Combobox` with the screen.
- **`TimezoneNote`** — `GlobeHemisphereWest` and "Times are in Istanbul time (UTC+3)" in muted text, both times ("09:00 Istanbul · 08:00 your time, Berlin") in a toggletip, and an optional "Show in my time" `Switch` (controlled). It generalises §2v's "Days are in UTC".
- **`DateTimeField`** — Kumo has no time picker: a Kumo `Field` (label, description, error) around a secondary date `Button` ("Publish at, Date: 2 Nov 2026") that opens a `Popover` with the lazy `DatePicker` (`calendarLocaleProps`, days in UTC so a picked day is exactly that day, `min`/`max`/`today`) and an `InputGroup` with the typed time (named by the field's label) and the zone as an end addon ("Istanbul (UTC+3)"). The time reads "9", "930", "09:30", "9.30" and, in 12-hour locales, the locale's own AM/PM words (`parseTimeOfDay`), is written back in the locale's hour cycle (`formatTimeOfDay`; 24-hour in Turkish) and emitted as `HH:mm`; an unreadable time shows `labels.invalidTime`. Validation is the screen's (`error`): past, "less than 5 minutes away", a DST gap ("02:30 does not exist on 29 March in Berlin; it runs at 03:30"). `useTimeOfDayDraft` is the shared time-text state.
- **`RecurrenceEditor`** (D3) — the presets as `Radio appearance="card"` (Every hour, Every day, Weekdays, Every week, Every month, Once, Custom), then only what the choice needs: the time (minutes for hourly), the weekday `Select`, the day-of-month `Select` (1–31, last day), and for Custom every N days/weeks/months, weekday `Checkbox`es in `weekStartsOn` order (short names, long for screen readers), monthly "on day N" / "on the second Tuesday", and the end (never / on a date / after N runs). A muted hint asks for a minute off the hour (RFC §9.5) when the time is on it. It emits a structured `RecurrenceValue`; `recurrenceRule` turns it into the RRULE subset (hourly = DAILY with every BYHOUR, never HOURLY or BYSETPOS; UNTIL in floating local time) and `recurrenceProblems` lists what to word. The sentence ("Weekdays at 09:07", "Her ayın ikinci salısı 09:07") is the screen's, from its own templates, shown in an `InsetPanel` and spoken politely.
- **`NextRuns`** — the next five runs from the server (`POST …/automations/preview-rule`) as an outline `InsetPanel` `dl`: the day and the time in the site zone, a warning `ClockClockwise` "Clock change" badge on DST days, the screen's note for a moved run; loading lines with a status, an empty line.
- **`RescheduleDialog`** ("Move to…", D4, D12) — `LayerDialog size="base"`, always rendered and controlled by `open`: the item as the description, an outline `InsetPanel` "Now → New", the `DateTimeField` (from today), an alert `Banner` for a clash, an info `Banner` "The approval is kept" (`approvalEffect="kept"`: a person who may approve moves it) or an alert `Banner` "Moving voids the approval; it asks again" (`voided`: an agent's move or a content change), the screen's error `Banner` for a 409 ("This schedule changed somewhere else" + "Load the latest"); primary "Move" (`loading`, disabled until a valid, different time), dismissal disabled while busy. After it, the screen's toast offers **Undo** for 10 s.
- **`ScheduleRunRow`** (History tab) — a `Table.Row` under `ScheduleRunHeader` (same column order): time (site zone, date below), kind (outline `Package` "Release" / `ArrowsClockwise` "Built-in job" or "Agent task", the trigger below — Cron, Clock, Request, Timer, Run now), subject (linked), origin (the screen's `ActorBadge`), **state** (`ScheduleStatusBadge` subject `run`, plus the warning `ShieldWarning` **"Read visitor text"** taint marker, D10, whose toggletip names the tool and time) and **outcome** (outline badge) in separate columns, lateness ("On time" under a minute, "3 min late" from `Intl` units, the DST or zone-rules note), budget use ("Calls 60/50 · Writes 2/10 · Requests 1/5", `tabular-nums`, error text and a warning "Over budget" badge when a limit is passed) and a sticky last column for the snapshot and audit links. An empty cell is "—" with `labels.none` for screen readers. The table scrolls sideways on phones (`LayerCard p-0 overflow-x-auto`).
- **Turkish** (RFC §15.8): weeks start on Monday, times are 24-hour, dates read "12 Ekim Pazartesi", "Bugün"/"Yarın" come from `Intl.RelativeTimeFormat` (`relativeDay`, sentence case), counts through the screen's `Intl.PluralRules`.

**Screens** (Studio; words in the lazy namespaces `schedules` and `scheduleSettings`; helpers in `lib/schedules.ts`, the client in `lib/schedules-api.ts`, shared parts in `components/Schedules.tsx` — all `LAZY_ONLY`; the shell keeps only `api.scheduler`, the nav item and four route registrations, and the routes check their own URL with `lib/schedules-search.ts`):
- **Header** (`useSchedulesHeader`): `PageLayout` with `CalendarDots` 24 px, "Schedules", the tabs **Calendar · Automations · History** (one route each: `/sites/:id/schedules`, `…/automations`, `…/history`), a secondary square `Keyboard` button (from `md`) and the primary split "New schedule ▾" (Schedule a publish… · New release… · New automation…, the last gated on `automations.manage`). Under the tabs `SchedulesBanners`: an alert "n schedules need attention" with Review (→ the Needs attention view), a secondary "Schedules are paused" with the reason, and the error "Scheduled work is not running" (`SchedulerStalledBanner`, also on the site overview, lazily, when `/api/scheduler` is unhealthy and work is due).
- **Calendar** (`routes/SchedulesPage.tsx`, template `calendar`): `ListToolbar` (search) with `ScheduleFilters` (kind, state groups, origin, approval; the view menu: All, Waiting for approval, Proposed by agents, This week, Needs attention, Mine, then views saved in this browser with "Save view…"), `CalendarNav` with "Go to date" (`Popover` + `DatePicker`), `TimezoneNote` with "Show in my time" when the viewer's zone differs, then a `LayerCard p-0` with `AgendaList` (default; the card is `overflow-visible` so the day headings stick under the top bar) or `CalendarMonth` (full width: the aside — Waiting for approval, Scheduler, From the terminal — goes with the agenda). The URL is the state: `view`, `date`, `kind`, `state`, `origin`, `approval`, `q`, `v` (view), `new` (opens a dialog). Rows carry the creator (`ActorBadge` + name), the items count, overlaps, and for an agent's gate-only reduction an outline `ShieldCheck` "Edits mode reduction" instead of "Automatic" (`metadata["cloudhal.mode"]`). Waiting releases show Deny / Approve (Approve confirms in `ApprovalDialog`); the ⋯ menu has Open release, Move to…, Publish now, Unschedule. **Move** (`useMoveDialog`) is one path for the menu, a desktop drag and Alt+arrow: `RescheduleDialog` prefilled with the old time on the new day, approval kept (a person who may approve) or voided, a clash with other releases at the same minute, 409 → "Load the latest"; the move is sent as wall-clock `localTime` + zone, then a 10 s toast with **Undo**. **Shortcuts** (only outside fields, dialogs and menus): `j`/`k` next/previous month, `a`/`m` Agenda/Month, `g t` today, `g d` go to date, `c` schedule a publish, `f` focuses the filters, `?` lists them in a dialog; Studio's own ⌘K and `/` are untouched and `t` alone is not used.
- **Automations** (list): name with the job `Badge` and a state badge when not on, "Runs as" (`ActorBadge` Cloudhal for built-ins; agent + subtle `ModeBadge` of the cap), "When" in the server's words (`preview-rule`, the rule and zone in a `Tooltip`), next run, last run (`ScheduleStatusBadge` + `RelativeTime`), an On `Switch` (pause / resume), the ⋯ menu (Run now — 409 "already running this minute" in words —, Edit, History, Duplicate, Delete through `DeleteResource`). **Editor** (`AutomationDialog`, `LayerDialog lg`): name; the job as `Radio` cards (five built-ins, Agent task); for agent tasks the key note, `ModePicker` (role-capped) with `AutoModeConfirm`, "Reads visitor text" `Switch`, instructions, run window, budget; `RecurrenceEditor` with the server's sentence and `NextRuns`; an `InsetPanel` "What this automation can do"; a key minted on create is shown once (`ClipboardText`); a cap above the key's mode (409 `mode_cap_above_key`) says to create the automation again.
- **History** (list): `ScheduleRunRow`s with state, kind and origin `Select`s in the URL, cursor paging, and a ghost "Details" opening `ScheduleRunDialog` — state, outcome, trigger, error, the summary as plain text, counts and the built-in jobs' **findings** by code in words (broken links with redirect proposals, stale articles, feed problems, digest sections), visitor or fetched text marked "From visitors".
- **A release** (`routes/ReleasePage.tsx`, editor template): title, state badge and "Publishes … · Istanbul (UTC+3)"; Move to… and Publish now in the header; outcome banners (published with lateness and snapshot, missed, expired, failed, canceled); after a conflict "Changed since approval" with Re-pin and approve / Cancel; Items (`ReleaseItems`: kind, path, pinned vs live version, closure, overlaps, locks, Compare → `ReleaseDiffDialog`, three columns after a conflict); Approval; the aside When (schedule a draft or "Publish when approved"), Title, Details and the danger zone (Unschedule, Cancel → `ConfirmDialog`).
- **Editors**: a secondary "Schedule…" next to Publish (`ScheduleAction`, on servers with schedules; the dialog loads on hover or click) opens `ScheduleDialog` — the items, "At a time" (`DateTimeField`, site zone, at least 5 minutes ahead) or "As soon as it's approved", the closure note, whether the person approves as they schedule or sends it for approval; unsaved edits are saved and the article marked Published first. The aside's **Schedule** card (`ScheduleCard`): "Visible from" and "Hide after" as `DateTimeField`s converted to UTC instants on change (clock-change gaps worded), the releases the node is in, `gates_unsupported` / `invalid_availability` in words, and when `features.schedules.gates` is false a secondary banner with the fields off. Held content gets `LockedBanner` ("Locked: publishes …", Unschedule and edit, Edit and re-approve / Edit and send for approval, Open release) and a read-only form.
- **Elsewhere**: Settings › General "Time zone" (`TimeZoneField`, `Combobox`, the browser's zone offered; `invalid_time_zone` in words) and Settings › Schedules (`ScheduleSettingsSection`: scheduler health, the kill switch confirmed with a reason, the daily automation write cap with a `Meter`); Approvals render release requests as the release (`ReleaseRequestDetails`, lazily) and `lift_embargo` with the agent's reason; the bell words the eleven schedule kinds (`lib/schedule-notices.ts`, loaded with the first one) and the sidebar item counts conflicts, misses, failures and approvals due.

### 2y. Body editor (RFC-0014 phase 1)
Markdown bodies (article bodies, page `richText` sections in markdown) are edited with **`MarkdownEditor`** from **`@cloudhal/ui/editor`** — its own subpath, like `/charts`, because Tiptap and ProseMirror are about 620 kB minified (190 kB gzip) with the menus. Studio reaches it only through `components/BodyEditor.tsx`, which `React.lazy`-loads it with the first body on screen and shows the plain Markdown `InputArea` until then; the editor's modules are in `bundle-budget.ts`'s `LAZY_ONLY`. Words come from the lazy namespace `bodyEditor` (§1), loaded with the article and page editor routes. HTML bodies keep the plain `InputArea`.
- **Markdown is the only stored format.** The editor never stores HTML or its own JSON. Loading splits the body into top-level blocks with `marked` (GFM, as the site renders); saving compares each block with what the editor would write for the original and **keeps the original bytes of every untouched block** — opening and saving changes nothing, and editing one paragraph rewrites that paragraph only (`editor/markdown-blocks.ts`, tests in `markdown-editor-codec.test.tsx`).
- **Nothing is silently rewritten.** A block the editor cannot keep exactly — raw HTML, link definitions, a ```` ```surface ```` fence (RFC-0020 §5, whose info string a code block would cut), or anything whose rendered HTML would change after a trip through the editor (`isLossy`) — is a **source block**: a read-only `InsetPanel variant="recessed"` with a secondary `Badge` "Markdown", the hint "Kept exactly as written. Edit it in Markdown mode." and the source in `font-mono`. It saves as written.
- **Layout:** a Kumo `Toolbar` (`size="sm"`, groups split by `border-kumo-hairline`): Bold, Italic, Strikethrough, Inline code, Link · Heading (h2), Subheading (h3) · Bulleted, Numbered, Checklist, Quote, Code block, Insert table, Divider, Image (when the host passes `onPickImage`) · Undo, Redo. Pressed formats are `aria-pressed` with `bg-kumo-tint`; buttons keep the selection (`onMouseDown` prevents focus loss). Then segmented `Tabs` **Rich text | Markdown**. The editing surface is `bg-kumo-control` with `ring ring-kumo-line` (`ring-kumo-focus` while focused), `rounded-lg`, at least 256 px tall (128 px for page sections), with content styles in `ui/styles.css` (`.ch-md-content`: 14px text, headings 20/18/16 px semibold, Kumo tokens only). Markdown mode is **CodeMirror 6** (`editor/SourceEditor.tsx`, MIT) on the same text: GFM highlighting in Kumo tokens (headings strong, links `text-kumo-link`, code and markers subtle), line wrapping, its own undo; it is a further lazy chunk (about 300 kB minified, 99 kB gzip) loaded on the first switch, with the `InputArea` as fallback. Only the GFM grammar is bundled, not the HTML/CSS/JS ones `markdown()` would add. The rich editor stays mounted, so its undo survives a switch.
- **Links** go through a `Popover` with an "Address" `Input`: only `https:`, `http:`, `mailto:`, `tel:`, `asset:` and site-relative addresses (the renderer's `safeHref` rule); anything else shows the field error and is not applied. Pasted and typed links follow the same rule.
- **Images** keep their stored `src`; `asset:<id>` shows through Studio's private content route (drafts included), other addresses as the SEO preview resolves them.
- **Read-only** forms (roles below Editor, a release lock) pass `readOnly`: a `fieldset` cannot turn off `contenteditable`.
- **Slash menu:** `/` at the start of a block or after a space (never in code) opens a `listbox` ("Insert block") under the caret — Text, Heading, Subheading, the lists, Checklist, Quote, Code block, Insert table, Divider, Image — filtered by what follows the `/` against the label, an English key and synonyms, with the UI locale's case rules (Turkish "ı"/"İ"). Arrows move, Enter or Tab inserts, Escape dismisses until the next `/`; focus never leaves the text. `bg-kumo-elevated`, `shadow-lg ring ring-kumo-line`, `rounded-lg`, options `rounded-md` with the chosen one `bg-kumo-tint`; Floating UI (through `@tiptap/suggestion`) keeps it attached while the page scrolls and flips it above near the bottom.
- **Selection toolbar:** a non-empty text selection gets a small `Toolbar` above it (`@tiptap/react/menus` `BubbleMenu`; same surface as the slash menu): Bold, Italic, Strikethrough, Inline code, Link. It stays while its link popover is open. Not on node selections or in code blocks.
- **Images from the library:** the host's `onPickImage` returns `{ src, alt? }`; Studio opens `AssetPickerDialog` (§2u) and writes `![](asset:<id)` — an empty alt, so the site uses the library's alt text, and it stays current when the library's changes.
- **Paste:** text that reads as markdown (block syntax, `**…**`, `[…](https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/…)`, inline code) arrives as blocks through the same codec as loading, so anything the editor cannot model becomes a source block. HTML from rendered pages (headings, lists, links, emphasis present) is left to the editor's schema; HTML that is only styled spans (code editors such as VS Code) yields to its text.
- **Source blocks** have a ghost "Edit as Markdown" button: Markdown mode opens with that block's text selected.
- **Outline:** a ghost `Button` "Outline" (`ListDashes`) next to the mode tabs, with a warning dot `Badge` counting heading problems, opens a `Popover` with the headings as a `nav` of ghost buttons indented by level; choosing one moves the caret there. The page already has its H1 (the article title, the hero), so an H1 in the body and a heading more than one level below the previous one get a warning `Badge` ("Use H2: the page has its H1", "Skips a level"). Nothing is changed automatically.
- **Preview:** the editor's preview follows unsaved edits (§2f).
- **Suggestions** (RFC-0014 phase 4): an agent's open proposals for a body (`edit_body` with `mode: "propose"`) sit above its editor — the article body, or each markdown rich-text section of a page — under a `Text` heading "Suggestions" with an info `Badge` "2 open" (`components/BodyProposals.tsx`). Each is an `InsetPanel`: an `ActorBadge` "{name} suggests", `RelativeTime`, the agent's note, then a `BodyDiff` of what accepting would change **now** (computed by `GET /api/sites/:siteId/proposals`, `content:read`), then a secondary "Reject" and a primary "Accept" (`POST …/:id/accept|reject`; deciding needs what updating the node needs — own limits for articles, `content:write` for pages). Accepting writes at once, so while the form has unsaved changes "Accept" is disabled with the hint "Save or discard your changes first." beside it — a hint, not a `Tooltip`, which would wrap the button in its own. A proposal whose blocks changed since it was filed shows a warning `Badge` "Out of date" (its `Tooltip` names the block) and the hint text in place of the diff; it can only be rejected. Accepting one that went stale meanwhile returns 409 and a danger toast. Accepted blocks keep the agent as their author with `via: "proposal"`. A suggestion of several operations lists them as a `Checkbox.Group` "Changes to accept", one `Checkbox.Item` per operation in words ("Change “First” to “Opening”", "Remove “Second.”"; "Rewrite “…”" for a replaced block, whose new text the diff shows; the agent's text as plain text, one line, at most 80 characters), all ticked; unticking one re-fetches the diff for the rest (`POST …/:id/preview`, a `SkeletonLine` meanwhile) and Accept becomes "Accept 1 of 2"; with none ticked the hint "Choose at least one change." replaces the diff and Accept is disabled.
- **Blocks** (RFC-0015 phase 6b, §2aa): body directives (`::button{…}`, `:::callout{…}` … `:::`) show as an `InsetPanel` (outline) per block (`editor/directives.tsx`), named for assistive tech by the type's title:
  - a header that is not editable text: the type's icon, its title in bold, a secondary one-line summary of its first text props, a warning `Badge` "Check properties" when the props do not fit, and a ghost `xs` "Properties" button (`SlidersHorizontal`) at the end;
  - "Properties" opens a `Popover` (320 px, scrolls past 70 % of the viewport) with the type's title and the generated `BlockPropsForm`; edits apply as they are typed and are disabled when the editor is read-only;
  - a container's inner text sits under the header and is edited in place, like the rest of the body; its untouched blocks keep their bytes;
  - a type the deployment does not list shows "Unknown block · {name}" with its attributes as the summary, the hint that it is kept and not shown on the site, and the ghost "Edit as Markdown" button; it saves unchanged;
  - the `/` menu lists the body types after the built-in blocks, with their icons and titles in the UI language (found by the English name too), and inserts the type's example.
- **Approvals** (§2m): a pending `edit_body` request shows "What approving changes in “{title}”" and the same `BodyDiff` under its prompt (`data-approval-changes`), computed when the list loads; a request that no longer applies shows none.
- **Ask AI** (RFC-0016 §3): when the site has AI on, the person holds `ai.invoke` and the server reaches Workers AI, the selection toolbar ends with a `Sparkle` button "Ask AI". It hands the whole top-level blocks the selection touches to `AiCommandDialog` (`MarkdownEditor`'s `onAskAi`, `selectionBlocks`).
- **Focus mode** (`docs/design/body-focus-mode.md`): a ghost `ArrowsOut` "Focus" button at the end of the header row (and Ctrl/⌘+Shift+\ from inside the editor) turns the editor into a full-screen modal layer (`dialog` named after the editor, the rest of Studio `inert`): a `max-w-3xl` column, a sticky top bar with the toolbar, the host's `focusActions` (the article editor's save state and Save), a "Spotlight" `Switch` (dims every block but the current one, remembered per browser) and "Leave focus"; Esc leaves and focus returns to the button. Never entered on page load.
- **Interactive blocks in the body** (```surface): the source block draws the block with the site's static preview (`previewSource` → `api.entries.previewFragment`, a frame with `sandbox="allow-same-origin"` and no scripts — same origin only so it can be sized to its content, the second exception after §2ac — cached per text) and keeps the code behind a ghost "Show code" toggle; "Edit as Markdown" still opens it. Invalid ones show the preview's problem note instead.
  - The `LayerDialog` has a "What to do" `Select` with the seven commands. "Change tone" adds a tone `Select`, "Translate" a language `Select` named through `Intl.DisplayNames`, "Your own instruction" an `InputArea` of at most 500 characters. A secondary "Run" button sits beside them.
  - While the answer streams: "Writing…", with the text as plain text in a `bg-kumo-recessed` box, and a "Stop" button.
  - Then a `BodyDiff` of selection → answer under "Suggested text". A code fence around the whole answer is dropped. "Try again" reruns.
  - The primary **Replace** puts the answer into the editor in one undo step. It is refused, with an error `Banner`, when the selected blocks changed meanwhile. Cancel discards.
  - Server refusals are worded: `ai_budget`, `ai_busy`, `ai_off`, `ai_model_unavailable`, `ai_rate_limited`, `ai_unavailable`, `ai_failed`. Nothing is saved until the person saves the form.

### 2z. AI settings (RFC-0016)
Site › Settings gets an **AI** section (`components/AiSettings.tsx`, lazy namespace `aiSettings`), after Schedules:
- a success `Badge` "On" (`Sparkle`) in the header while AI is on;
- a secondary `Banner` "This deployment can't reach Workers AI yet" when `/ai/settings` reports `transport: "none"`, saying what to add (`"ai": {}` in cloudhal.json, or the two environment variables on Node). The rows stay editable, so an owner can choose settings first.
- **Rows** (`SettingRow`s):
  - "AI in the editor" — a `Switch`, off until the owner turns it on.
  - "Model" — a `Combobox` over `GET …/ai/models`. Recommended models come first, labelled "· Recommended", then the account's catalogue. Under it: the recommended model's note, its context window, and where the text goes ("Selected text goes to Workers AI in this Cloudflare account" or "…to {provider} through your AI Gateway").
  - "Daily limit" — a number `Input`, 0 to 10,000, with a `Meter` "7 of 100 used today".
- **A `Collapsible` "AI Gateway and other providers"**, open when either is set:
  - "AI Gateway" — an id `Input`;
  - "Model from another provider" — `provider/model`. While it is filled, it is the model used and the `Combobox` is disabled; it needs a gateway, and the field says so.
- An alert `Banner` warns when the chosen Workers AI model is missing from the live catalogue: "…no longer offered by Workers AI…".
- Below Administrator (`ai.settings` = `site:settings`) the controls are disabled with the gating reason, and the model shows as text.

### 2aa. Component sections (RFC-0015 phase 6a, ADR-0030)
Pages can hold **component sections**: a block type from the registry (`GET /api/sites/:siteId/block-types`, `content:read`) with its props (`components/BlockSection.tsx`).
- **Adding:** the page editor's add-section `DropdownMenu` lists the section kinds, then a `DropdownMenu.Separator` and a group "Blocks" with every type allowed in sections, each with its icon (the type names a Phosphor icon; `Cube` otherwise) and its title in the UI language. A new section starts from the type's example.
- **The card:** a `SectionCard` titled with the type's title and icon, like the other kinds.
- **The form:** **`BlockPropsForm`** from `@cloudhal/ui`, generated from the type's props schema — no code per type, for Cloudhal's types and a theme's alike:
  - a `string` is an `Input` (`type="url"` for links); `format: "markdown"` or `x-widget: "textarea"` an `InputArea`; an `enum` a `Select`, or a horizontal `Radio.Group` with `x-widget: "radio"` (enum values worded through `editor.blocks.values.*` when Studio knows them, else the value);
  - `number`/`integer` a number `Input`; `boolean` a `Checkbox`;
  - a flat object a `fieldset` with its fields; a list a bold `Text` label, then one `InsetPanel` per item headed "Item {n}" with ghost square buttons Move up (`ArrowUp`), Move down (`ArrowDown`) and Remove item (`Trash`), then a secondary `sm` "Add item" (`Plus`), disabled at `maxItems`;
  - labels and hints come from the schema's `title`/`description` (per locale when given), else the prop name in words;
  - an optional field emptied is removed from the props, not stored as "";
  - problems from the same interpreter the store runs (`validateProps`) show on their field as it is edited (for a link: "a safe link"); saving props that do not fit is refused with 422 `invalid_props`.
- **Unknown types** (a theme type this deployment no longer has): the card is titled "Unknown block · {name}", with an alert `Banner` saying it is kept but not shown on the site, and the props as read-only JSON in a `font-mono` `InputArea`. It saves unchanged.
- **Read-only** roles and release locks disable the form like any section.
- **On the site and in previews:** built-ins render escaped, framework-free markup (`.ch-callout`, `.ch-button`, `.ch-embed`, `.ch-faq` in the starter's CSS); a theme can map a type to its own Astro component in `theme.ts` `blocks`. A section whose props do not fit, or whose type no one renders, renders nothing on the site and a labelled placeholder in previews.

### 2ab. Appearance (RFC-0017 §1, ADR-0031)
Site › Settings gets an **Appearance** section after Domains (`components/AppearanceSettings.tsx`): the theme's design settings from its `src/settings.ts` (`GET`/`PUT /api/sites/:siteId/theme-settings`).
- **The form** is `BlockPropsForm` over the theme's schema (§2aa).
  - Colors are a `Field` with an `InputGroup`: a swatch addon (`ring ring-kumo-line`, the value or the default) and a `font-mono` input of at most 7 characters.
  - Enums are worded by the schema's `x-labels`, per locale.
  - Each field's description comes from the theme.
- **Checks as typed:** the same interpreter the store runs, contrast rules included ("contrast with surface is 1.9:1; needs 4.5:1"). "Save changes" is disabled while a problem shows. The server answers misfits with 422 `invalid_props`, and a stale site `rev` with 409 and the conflict `Banner`.
- **The description** names the theme. A secondary hint under the form says saved changes show on the site after the next publish.
- A theme without settings shows only "The {theme} theme has no design settings to change."
- Below Administrator (`settings.write` = `site:settings`) the fields are disabled, with the gating reason on the button.

### 2ac. Build view (RFC-0020 §6, phase 20b)
`/sites/:siteId/pages/:pageId/build` (`routes/BuildPage.tsx`, template `editor`, lazy namespace `build`): a page while agents build it. The page editor's header has a secondary "Build live" `LinkButton` (`Lightning`, `Tooltip`) that opens it.
- **Header.** The title is "Build · {page title}". The actions are a connection `Badge` (`success` dot "Live", `warning` dot "Connecting…" / "Reconnecting…") and a secondary "Back to editor" `LinkButton`.
- **Body.** `EditorLayout` with the preview always shown.
  - Main, first: `SectionCard` "Build with AI" (`components/BuildChat.tsx`, phase 20c).
    - Transcript: `BuildChatLog`, oldest first. It shows the person's brief in bold, the model's notes with a `Sparkle`, a live `Loader` line ("Writing Band, Heading…"), the outcome with `CheckCircle` and repairs in mono, and errors with `WarningCircle`.
    - Composer: an `InputArea` "What should the page have?" and a primary "Build" button, which becomes a secondary "Stop" while the turn runs.
    - When AI is off: a `SectionEmpty` with "Open settings". When the deployment cannot reach Workers AI: a `SectionEmpty` saying how to connect it.
  - Main: `SectionCard` "Activity" holding `BuildActivity` (`@cloudhal/ui`). The list is newest first. Each entry shows the actor icon and name, the tool in mono, an "Applied" (`success`) or "Refused" (`warning`) dot `Badge` and a relative time. Below that: a summary line ("2 sections changed · 3 operations"), then Cloudhal's repairs or the refused parts with their JSON Pointers, in mono. The list is `aria-live="polite"`. With nothing yet it shows a `SectionEmpty`.
  - Aside: `SectionCard` "Connect an agent", with the MCP endpoint and the page id as `InlineCopyText` and three numbered steps (`get_catalog`, `patch_draft`, fix `VALIDATION_FAILED`).
- **Preview.** `PreviewPanel live morph`:
  - The server sends the whole preview document with each change (`GET …/build/events`, server-sent events). The panel merges it into the shown document: sections are matched by `data-section-id`, unchanged ones are kept, so scroll position and open tabs survive. Changed sections are outlined for 1.6 s and the last one scrolls into view.
  - To merge, the frame is `sandbox="allow-same-origin"`. Scripts stay off. The document is Cloudhal's own escaped preview HTML under the preview CSP.
- **Picking (click-to-scope).**
  - The preview header has a secondary "Pick" button (`Target`, `aria-pressed`). While picking it turns primary and reads "Click a part of the page".
  - `PreviewPanel pick` lays a transparent button over the frame: the part under the pointer gets a `ring-kumo-brand` outline with a light brand tint, a click picks it, and Escape stops.
  - The picked part keeps a `ring-kumo-brand` outline that follows scrolling and new versions.
  - Build chat shows the scope as an `info` `Badge` (`Target`) above the brief, with an icon-only "Change the whole page instead" button.
- **No editing here.** People edit in the page editor; agents change the draft through MCP.

### 2ad. Corrections in the article editor (RFC-0019 §2, phase 19b)
`components/ArticleCorrections.tsx`, in the article editor's main column after the body. It is absent until the article has been published.
- `SectionCard` "Corrections" with `Megaphone`. Its description says readers see these at the end, newest first, and that a published correction is reworded, never removed.
- The list is `CorrectionList` (`@cloudhal/ui`): rows in a `divide-y` list, newest first. Each row has a kind `Badge` (correction `warning`, clarification `info`, update `neutral`), the time or "Not saved", and the note as text. Only unsaved rows have an icon-only "Remove correction" button. With none, it shows a `SectionEmpty`.
- The form: a `Select` "Kind", an `InputArea` "What changed" (≤ 2,000) and a secondary "Add correction" button that appends to the draft. A line says it goes live with the next publish. The store stamps the time on save, and the `auto` mode check makes that publish wait for a person.

### 2ae. Design rules in Site settings (RFC-0021 §5, phase 21a)
`components/DesignRulesSettings.tsx`, a `SettingsSection` after Appearance (`#design`, "Design rules").
- **Editor.** An `InputArea` in mono for the site's DESIGN.md, with a character count against 24,000. While empty, a secondary "Start from the headings" button fills in the recommended headings.
- **Theme rules.** The theme's DESIGN.md sits read-only inside a `Collapsible` ("The blog theme's rules"), with a line saying the site's rules win.
- **Feedback.** `design_lint` warnings show as an `alert` `Banner` ("Worth a look"). A conflict on save shows the shared conflict wording.
- **Hints.** A secondary line says agents propose changes that wait in Approvals. Below Administrator the section is read-only, with the gate's reason.

### 2af. Playground session (RFC-0036 §5, ADR-0038)
- Only when `/api/instance` reports `features.playground` (try.cloudhal.com). Studio has no sign-in there: `requireSession` accepts a 403 from `/api/auth` when the instance is a playground.
- **Session bar**: `PlaygroundBar` under the top bar on every screen — a compact secondary `Banner` (`Timer`), title "Playground", the minutes left as an ICU plural with the privacy note, a ghost "Reset" (`POST resetUrl`, then the landing page) and a primary "Deploy to Cloudflare" `LinkButton` (external). At zero minutes the browser returns to the landing page.
- **Left out**: the account surface's Agents group and Team/Account items (and their palette commands), the user menu's Account, Team and Sign out. A direct visit to `/agents`, `/team` or `/account` shows `PlaygroundUnavailable`: a bare `Empty` (`LockSimple`) "Available in your own install" with the Deploy button. The site sidebar leaves out Analytics, Activity, Approvals and the Automation group (Agents, Schedules). Elsewhere site screens are gated as everywhere else, by `features.*` and the principal's abilities; a `403 playground` answer counts as a feature that is off (`isNotEnabled`).

## 3. Sidebar specification
```tsx
<Sidebar.Provider defaultOpen collapsible="icon" peekable mobileBreakpoint={768}>
  <Sidebar>
    <Sidebar.Header>{/* switcher: DropdownMenu listing sites + "All sites" */}</Sidebar.Header>
    <Sidebar.Content>
      <Sidebar.Group><Sidebar.GroupLabel>Overview</Sidebar.GroupLabel><Sidebar.Menu>
        <Sidebar.MenuButton icon={House} href active tooltip>Overview</Sidebar.MenuButton>
      </Sidebar.Menu></Sidebar.Group>
      <Sidebar.Group><Sidebar.GroupLabel>Content</Sidebar.GroupLabel><Sidebar.Menu>…Pages, Articles, Categories & tags (proposal count), Media…</Sidebar.Menu></Sidebar.Group>
      <Sidebar.Group><Sidebar.GroupLabel>History</Sidebar.GroupLabel><Sidebar.Menu>…Snapshots, Activity, Approvals (pending count)…</Sidebar.Menu></Sidebar.Group>
      <Sidebar.Group><Sidebar.GroupLabel>Automation</Sidebar.GroupLabel><Sidebar.Menu>…Agents (collapsible: Keys and MCP → /agents, Skills → /agents/skills), Schedules "Soon"…</Sidebar.Menu></Sidebar.Group>
      <Sidebar.Group><Sidebar.GroupLabel>Settings</Sidebar.GroupLabel><Sidebar.Menu>…Settings → site settings, Navigation (menus, §2t), Redirects (account surface: Team → /team with the member count, Account → /account)…</Sidebar.Menu></Sidebar.Group>
    </Sidebar.Content>
    <Sidebar.Footer className="z-2"><Sidebar.Trigger /></Sidebar.Footer>
    <Sidebar.Rail />
  </Sidebar>
  <main className="flex-1 bg-kumo-overlay">…</main>
</Sidebar.Provider>
```
Composition rules verified against Kumo's own `SidebarDemo.tsx`:
- The header switcher is **not** a `MenuButton` (that auto-wraps in `<li>` and renders a bullet outside a `Menu`); it is a plain row trigger for `DropdownMenu` with `w-(--anchor-width)` content and a check on the current item — `@cloudhal/ui` ships it as `SidebarSwitcher`.
- `Sidebar.Loading` replaces `Sidebar.Content` until navigation data resolves; never render an empty menu.
- Counts and states go in `Sidebar.MenuBadge` (`4`, `Soon`, `Beta`); unavailable items are `disabled`, never hidden.
- Sub-navigation uses `Sidebar.MenuItem` → `Sidebar.Collapsible` → `CollapsibleTrigger render={<Sidebar.MenuButton>… <Sidebar.MenuChevron /></Sidebar.MenuButton>}` → `CollapsibleContent` → `MenuSub`/`MenuSubButton`.
- `Sidebar.Footer` holds **only** `Sidebar.Trigger`, as in Kumo's `SidebarFullDemo`, so it stays inside the 57 px rail when collapsed; the user menu is the avatar at the end of the top bar (`UserMenu`), reachable whether the sidebar is expanded, collapsed or a sheet. The footer is `z-2`: `Sidebar.Rail` (z-1, full height, inside the peek zone) used to cover the trigger, so hovering it started a peek, the rail slid away with the widening sidebar, the peek stopped and the rail came back — the sidebar flickered under the cursor. `Sidebar.Rail` toggles the sidebar from its edge.
- Below the mobile breakpoint the sidebar is a sheet; choosing a page closes it (`CloseSheetOnNavigate`, like Kumo's `NavTree` demo).

Rules from `sidebar.tsx`: `MenuButton` auto-wraps in `<li>`; `MenuItem` only around `Collapsible`; `tooltip` shows only when collapsed and not peekable; `GroupLabel` becomes a divider when collapsed; sub-menus via `Sidebar.Collapsible` + `MenuSub`/`MenuSubButton`; account↔site via `Sidebar.SlidingViews`; below `mobileBreakpoint` the sidebar is a sheet. Group names follow capabilities (Overview, Content, History, Automation, Settings), never product names.

## 4. Typography, spacing, colour
- **Text only through `Text`**: body 14 px (`size="base"`), `xs` 12 / `sm` 13 for captions, `lg` 16 only for headings; `variant="heading"` (16 px) and `size="lg"` (20 px) for page-level; page titles come from the blocks. Sentence case; product names title-cased; `bold` prop for emphasis; never `font-bold`, never `tracking-*`, never uppercase.
- **Spacing**: `gap-1.5` between a heading and its description, `gap-6` between blocks, card padding `px-5 py-4`, page container `p-6 md:p-8 lg:px-10 lg:py-9`, `max-w-[1400px]`.
- **Colour**: semantic tokens only — surfaces `bg-kumo-canvas|base|elevated|recessed|tint|overlay|contrast`, brand `bg-kumo-brand`, status `kumo-info|success|warning|danger` (+`-tint`), text `text-kumo-default|strong|subtle|inactive|placeholder|inverse|link`. No raw Tailwind colours, no `dark:` (Kumo themes via `light-dark()`; toggle with `data-mode="dark"`). The person chooses Light, Dark or System (the default, following `prefers-color-scheme` live) in the top bar's `ThemeSwitch`; the choice lives in `localStorage` (`cloudhal.studio.theme`, `lib/theme.ts`, synced across tabs) and an inline script in `index.html` applies it as `data-mode` (and `color-scheme`) on `<html>` before first paint, so a reload never flashes the other theme. The only fixed colours allowed are inside the preview frame, which shows the visitor-facing site (its own theme) on a light canvas.
- **Semantic badge colours**: decisions and outcomes use the status variants (success / warning / error); actor kinds and scope groups use tints (`info`, `secondary`, `outline`, `warning` for publish/rollback scopes) — never the saturated `purple`/`blue`/`neutral` fills, which out-shout the status column.
- **Edges**: `ring ring-kumo-line` (elevated) / `ring-kumo-hairline` (flat); never `border` + `shadow`; concentric radii (`rounded-xl p-1` → `rounded-lg`); sticky elements separate with `border-b border-kumo-line`; no `transition-colors` on hover.
- **Icons** (Phosphor): 16 px in nav, inline text, toolbars, card headers; 20 px icon-only buttons; 24 px top-level list-page title (`PageLayout icon`); 48 px `Empty`; `weight="fill"` only for status (banners, toasts) and the brand mark. Studio ships three weights only — regular, `bold`, `fill` (`apps/studio/phosphor-weights.ts` drops thin, light and duotone from every icon definition; a test refuses them in source). Icon-only buttons need `aria-label` and `shape="square"`.

## 5. States
| State | Implementation |
|---|---|
| Loading | Prefer each component's own loading affordance: `Sidebar.Loading`, `Breadcrumbs.Current loading`, `Select loading`, `Button loading`, `InputGroup.Addon` with `Loader` for async validation; `SkeletonLine` rows only where no component owns the state (table bodies, text cards). Never a spinner-only page. |
| Empty | `Empty` with icon (48), title, description, `commandLine` for CLI parity, `contents` for the CTA. |
| Error | `Banner variant="error"` with `Banner.Action` retry; field errors via `Input error`; conflicts (409) explain "someone else changed this" and offer reload. |
| Success | `useKumoToastManager().add({ title, description, type: "success" })`; long jobs via `promise()`. |
| Confirm | `ApprovalDialog`, `DeleteResource`, `LayerDialog.Alert`; controlled by `open`. |
| Busy | `Button loading`, dismiss disabled while pending. |
| Not available | A feature the server does not run (404 from `/activity`, `/agent-keys`) is not an error: `Banner variant="secondary"` with an info icon explaining what to start or enable; create actions are disabled. |
| More data | Cursor APIs (`nextBefore`): footer with "Showing n of m loaded" and a secondary "Load more" (`loading`); client-side `Pagination` stays for fully loaded lists. |
| Polling | Counts that must stay current (pending approvals) use `refetchInterval` (15 s) on a query owned by the surface shell, so polling stops when the surface unmounts; a 404 stops it for good. The bell's notifications poll every 60 s (15 s while an elevation ends), also in the background, and never again after a 404 (§2n). |
| Re-authenticate | Actions the auth server allows only after a recent sign-in (the session list) show `Banner variant="secondary"` with a "Sign in again" action, never an error. |
| Time | Relative in lists and detail cards ("5 minutes ago", `Intl.RelativeTimeFormat` in the active locale, re-rendered every 30 s) with the absolute timestamp in a `Tooltip`; absolute in audit detail dialogs. |

## 6. Component usage matrix (all 54)
Studio must use each component where it fits; "later" means the surface does not exist yet (analytics, scheduling, agents) and the component is reserved for it.

| Component | Studio use |
|---|---|
| Autocomplete | the tag picker in the article editor (`TagPicker`, §2p); author suggestions (later) |
| Badge | status pills; `Sidebar.MenuBadge` for "Soon/Beta"; scopes, change counts, diff kinds; Cloudhal wrappers `StatusBadge`, `DecisionBadge`, `OutcomeBadge`, `ActorBadge` carry `data-*` for tests |
| Banner | page/section errors (with `Banner.Action` retry), limits, warnings, one-time-secret notice, policy reasons |
| Breadcrumbs | every detail/editor page, `Clipboard` for ids |
| BubbleMap / Chart / ChoroplethMap / GlobeMap / SankeyChart / TimeseriesChart | analytics (§2v): `TimeseriesChart` inside `AnalyticsTimeseries`, `ChoroplethMap` inside `CountryMap` (never with `tooltipFormatter`), both through `@cloudhal/ui/charts`; `ChartLegend` for series totals; `BubbleMap` was considered and rejected for country totals (RFC-0006 §10.1); `Chart`, `GlobeMap`, `SankeyChart` unused |
| Button | all actions; 6 variants; `loading` |
| ButtonGroup | split actions (the top bar's Publish ▾) |
| Checkbox | bulk select (`Table.CheckCell`, `BulkActionBar`, `CommentThread` selection, §2w), non-instant settings, agent-key scopes (grouped) |
| ClipboardText | ids and keys in settings; MCP endpoint/header; the one-time key reveal (`size="lg"`) |
| CloudflareLogo | not used (Cloudflare brand) |
| Code | one-line CLI parity in usage panels |
| CodeHighlighted (`@cloudhal/ui/code`) | client config snippets, tool input JSON (`showCopyButton`) |
| Collapsible | approval arguments, a comment's moderation history (`CommentHistory`, §2w), the skills `tools/call` example, the reasons of the possible-bot-traffic banner (§2v), "Advanced: scopes" when creating an agent key, the page SEO panel's "Advanced" (canonical URL, §2o); run step details (later) |
| Combobox | the category picker (multi-select with chips), merge/move/redirect targets (`TermCombobox`, §2p); the grouped menu target picker (§2t); site/page pickers |
| CommandPalette | global ⌘K / `/` |
| DatePicker / DateRangePicker | `DatePicker mode="range"` in the analytics custom range (`AnalyticsRangePicker`, UTC, lazy, §2v), `mode="single"` in `DateTimeField` (scheduled publish, "Move to…", §2x), always with `calendarLocaleProps`; history filters (later). `DateRangePicker` is deprecated and English-only: never |
| Dialog | small decisions (`ApprovalDialog`) |
| DropdownMenu | row menus, switcher, user menu, "More" actions |
| Empty | every list |
| Field | wraps controls that lack a `label` prop |
| Grid | detail/settings layouts |
| InlineCopyText | ids in dense cells |
| Input / InputArea / InputGroup | forms; `InputGroup.Addon` for slug/URL/host prefixes (`/`, `https://`, the preview host) and async validation state; `InputGroup.Button` for the password show/hide toggle (`PasswordField`) |
| Label | standalone labels only |
| LayerCard | section cards (never nested) |
| LayerDialog | create/edit forms (create agent key, create snapshot), detail sheets (activity event), snapshot diff, destructive alerts |
| Link / LinkButton | in-table titles, inline links, "View changes", "Open in new tab" (`external`); hrefs with `?query` are split for TanStack Router by `AppLink` |
| Loader | inline busy only |
| MenuBar | editor formatting toolbar (later) |
| Meter | password strength under a new password (`NewPasswordFields`, §2r); per-file upload progress (§2u); analytics shares, devices, channels and the Free-plan estimate (`BreakdownTable`, `BreakdownMeters`, `AnalyticsQuotaBanner`, §2v) |
| Pagination | every table |
| Popover | the notification panel (`NotificationBell`, §2n); filters, help |
| Radio | exclusive settings; `appearance="card"` for the preview-link target, the agent mode picker (§2g) and the "after creating" choice of the create-snapshot dialog |
| Select | filters, enums (never for status mutation) |
| SensitiveInput | API keys, secrets |
| Sidebar | app navigation (§3) |
| SkeletonLine | loading rows |
| Slider | agent parameters (later) |
| Surface | standalone neutral surfaces (`AuthLayout` card) |
| PageLayout / Columns / SectionCard / SectionEmpty / InsetPanel / AuthLayout / NotificationBell / NotificationItem / TermChip (Cloudhal blocks) | page anatomy, container-aware two-column bodies (instead of `Grid 2-1/1-2`), section cards, frameless empty states inside cards, inset summaries, auth screens, the top bar's notification bell and panel rows, removable term chips outside a `Combobox` (§1, §2, §2n, §2p) |
| LanguageChips (Cloudhal block) | the Languages cell of Pages and Articles on a multilingual site: one `Badge` chip per site language linking to that version (published success, draft secondary, outdated warning, needs review info), a missing language as an outline `Button size="xs"` with a "Write by hand" `DropdownMenu`; more than four languages collapse to "n/m" with the chips in a `Popover` (§2a) |
| Avatar (Cloudhal block) | a person's initials in a round tint (`sm` 24 / `base` 32 / `lg` 48 px): the Team table, dialog headers, the all-keys owner column, the Account profile; never an image |
| MenuTree / NavigationPreview (Cloudhal blocks) | the keyboard-first navigation tree (WAI-ARIA tree, live-region announcements, drag and drop as an enhancement) and the header/footer sketch of the menu editor (§2t); `MenuTree readOnly` for derived menus |
| SurfaceOutline (Cloudhal block) | a generated section (RFC-0020 surface) as an outline in the page editor: readable component names, what each shows (its text, then "shows /path" or "computed (fn)"), hairline rows with depth guides like `MenuTree`, an outline badge with the id, parts not on the page marked; text fields open per row on demand (pencil, `aria-expanded`); row actions from the screen ("Change with AI" links to Build with `?section=&component=`). The data stays behind a `Collapsible` "Show JSON" |
| ColorRolePreview (Cloudhal block) | the color roles a theme derives from its tokens (RFC-0023) under the Appearance form: per scheme (light, and dark once a seed is set) an `InsetPanel` with a small sample drawn in the site's colors (headline, body text, link, brand button, accent tag) and a swatch list of every role with its hex value; the contrast repairs below as plain sentences. The site's colors are inline styles; the frame, type and spacing are Kumo's |
| ImagePreview / SearchResultPreview / SocialCardPreview (Cloudhal blocks) | cover image frame and list thumbnails (`size` card / thumb / `tile` 4:3, `fit` cover / contain), search result and share card previews (§2o, §2u); the only `<img>` in Studio |
| MediaDropZone / useFileChooser (Cloudhal blocks) | where files come in: drag and drop, paste and the file button (`variant="area"`), or a drop overlay around the library (`variant="overlay"`); the only raw file `<input>` in Studio; `useFileChooser` opens the system chooser from any button (§2u) |
| FocalPointPicker (Cloudhal block) | where an image's subject is (RFC-0028): the picture with a crosshair, set by click or the arrow keys (Shift for bigger steps, Home for the centre), announced as a slider whose value names both coordinates, a ghost "Clear focal point", and wide, square and tall crop previews; on the file's page in place of the preview frame (§2u) |
| MediaGrid / MediaTile / MediaKindFrame (Cloudhal blocks) | the media library's and the picker's tiles: auto-fill columns of at least 10 rem, a tile that links (library) or toggles (picker, `aria-pressed`, brand ring and check), and the 4:3 kind-and-extension frame for files that are not images (§2u) |
| StatTile / StatTileGroup / DeltaBadge / Sparkline (Cloudhal blocks) | key figures with a delta badge against the previous period (success up, warning down, neutral within ±2 %), an optional info tooltip and sparkline, laid out as a container-query `dl` grid of two to four columns (§2v) |
| AnalyticsRangePicker (Cloudhal block) | the analytics range: preset `Tabs`, "Custom…" `Popover` with a lazy `DatePicker mode="range"` (UTC, Studio locale), optional compare `Switch`; controlled by `{preset}` or `{from, to}` (§2v) |
| BreakdownTable / BreakdownMeters (Cloudhal blocks) | ranked analytics breakdowns — top content, channels, referrers (never linked), campaigns, countries — with share `Meter`s and one folded "(other)" row; small breakdowns (devices, top channels) as a `Meter` list (§2v) |
| AnalyticsTimeseries / CountryMap / ReadersSummary (Cloudhal blocks, `@cloudhal/ui/charts`) | traffic over time with a legend and a data-table toggle (UTC throughout); the country choropleth with its top-countries table and no HTML tooltips; the editors' Readers card body (§2v) |
| PlaygroundBar (Cloudhal block) | the playground session bar: time left, Reset and Deploy to Cloudflare in a compact secondary `Banner` (§2af) |
| AnalyticsQuotaBanner (Cloudhal block) | the Workers Free request warning with its estimate as a `Meter` (`shouldWarnFreePlan`, §2v) |
| AnalyticsBotBanner (Cloudhal block) | the possible-bot-traffic warning on the Analytics screen with its reasons in a `Collapsible` (§2v) |
| CommentText / CommentRow / CommentThread (Cloudhal blocks) | comment text as plain text with the public page's `https:`-only link rule (never HTML), one comment with its author, status, labels, entry, reply context and untrusted-text panel, and the two-level thread with folded replies and in-reply-to jumps (§2w) |
| CommentStatusBadge / CommentLabelList / CommentAuthor / CommentTime / UntrustedTextPanel (Cloudhal blocks) | the parts of a comment, also for queue table cells (§2w) |
| BulkActionBar (Cloudhal block) | the bar that replaces a list's toolbar while rows are selected: select all/some, count, actions with disabled reasons, Clear (§2w) |
| CommentFilters / CommenterSummary / StatementOfReasons / CommentHistory / CommentReports / ArticleCommentsSummary (Cloudhal blocks) | the moderation queue's filters, a commenter at a glance (email only when allowed), the DSA Art. 17 statement of reasons and moderation history, DSA Art. 16 reports, and the article editor's Comments card body (§2w) |
| CalendarMonth / AgendaList / CalendarNav (Cloudhal blocks) | the schedules calendar: the APG month grid (one tab stop, chips with "+N more", drag and Alt+arrow moves through `onMove`, dots and a day list on phones), the agenda grouped by day under sticky headings with a "Now" rule and folds, and the ‹ Today › / period / Agenda–Month row (§2x) |
| ScheduleItem / ScheduleStatusBadge / ScheduleFilters / TimezoneNote (Cloudhal blocks) | one scheduled thing as a chip or row in the schedules visual language (proposals dashed, D14), every release/automation/run/approval state as an icon + word badge, the calendar's multi-value filters and views, and the site-zone note with "Show in my time" (§2x) |
| DateTimeField / RecurrenceEditor / NextRuns / RescheduleDialog / ScheduleRunRow (Cloudhal blocks) | date + 24-hour time in the site zone (the lazy `DatePicker` and a typed time), recurrence presets and the RRULE subset, the server's next runs with clock-change badges, "Move to…" with the approval kept or voided, and the run history row with lateness, budget use and the taint marker (§2x) |
| Switch | instant settings; browser notifications (Account › Notifications); page "Hide from search engines" (§2o) |
| Table | all lists |
| TableOfContents | settings sections (`SettingsLayout`, driven by `useTableOfContentsActiveId`) |
| Tabs | page-header tabs (controlled from the route), segmented switches (device width, snippet format, diff base, elevation and grant duration presets), underline Edit/Preview on narrow editors |
| TagInput | legacy article tags on sites not yet migrated; a term's synonyms (§2p) |
| Text | all text |
| Toasty | root provider; notice toasts (`useToast().notice`: `warning`/`info`, the item's id, up to two actions) for notifications |
| Toolbar | search/filter rows (`Select render={<Toolbar.Button />}` for facets) |
| Tooltip | icon buttons, truncated cells, absolute time behind relative time, scope descriptions (`TooltipProvider` at root) |
| RefreshButton | reload a live list (activity) or the preview frame |
| PreviewPanel (Cloudhal block) | every editor (§2f); the only place an `<iframe>` may appear |

## 7. Anti-patterns (CI-enforced where mechanical)
**Enforcement.** `apps/studio/scripts/design-lint.ts` holds the per-file rules (raw elements, class rules, entry points, ad-hoc surfaces, page anatomy, dialog rendering, card nesting, i18n, route templates). It runs three ways: in CI through `apps/studio/test/design-rules.test.ts` (`pnpm check`), by hand with `pnpm design:lint [files…]`, and **on every file an agent writes** through the Claude Code hook in `.claude/settings.json` (exit 2 sends the violations back to the agent at once). Biome additionally forbids `@cloudflare/kumo`, `@base-ui/react` and other icon sets in `apps/**`. When a rule blocks something Kumo cannot express, the answer is a new block in `packages/ui/src/blocks` (with the same rules), never an exception in a screen.

Raw `<table>/<h1>/<button>/<input>/<select>/<a>/<ul>/<p>` in screens; hand-rolled sidebars, headers, cards; raw Tailwind colours; `dark:`; `font-bold`, `tracking-*`, uppercase headings; hover colour transitions; `border` + `shadow`; nested `LayerCard`; conditionally rendered dialogs; status mutation through `Select`; `DANGEROUS_className` to restyle Kumo; a `Tooltip` used as a menu/popover trigger (`Trigger render={<Tooltip …/>}` swallows the trigger's props — nest it the other way, `<Tooltip render={<DropdownMenu.Trigger render={<Button/>}/>}/>`); hard-coded English (every string through `useT()`; Kumo's own labels through `KumoLocaleProvider`, `calendarLocaleProps` and the block labels, §2v Kumo locale); spinner-only pages; uniform `p-5` card padding; a raw `<iframe>` in a screen or any iframe without `sandbox=""`; fragments or conditionals directly inside `LayerDialog.Content`; a `<form>` around Kumo `Checkbox`/`Switch` (they are buttons and submit it); past-tense labels for audit events ("Deleted page" for a call that was denied) — use the tool's imperative name; a top bar that can shrink (`shrink-0` on sticky bars inside flex columns); rendering agent- or server-supplied text (approval prompts, skill descriptions) as HTML — always plain `Text`, never `dangerouslySetInnerHTML`; a chart or map `tooltipFormatter` / `dangerousHtmlFormatter` (Kumo inserts the result as HTML; lint `no-html-tooltip`, §2v); letting a self-approved action skip the person (approvals are decided only in Studio, ADR-0014); offering or sending `bypass` for an API key, a mode list that is not `KEY_MODES`, or letting a key become `auto` without the explicit consent checkbox (ADR-0015); offering an elevation to a mode that is not above the key's own, or elevating to `auto` without that same checkbox (ADR-0016); extending with any mode but the one in force, re-elevating a key whose elevation has ended from a notification, or changing an elevation outside `useExtendElevation`/`useEndElevation`; announcing a notification twice, or announcing what was there on the session's first load (§2n).

## 8. Review checklist
Before merging UI: `pnpm design:lint`; look up components with `pnpm kumo ls` / `pnpm kumo doc <Name>` / `pnpm kumo blocks` before writing markup; screenshot every touched screen at 1440 and 390 px with `pnpm design:shots -- <routes>` (headless Chrome against your dev server; fails on sideways scrolling or console errors; `SHOTS_SCHEME=dark|light` and `SHOTS_LOCALE=tr` for both themes and Turkish; for role-gated screens, one run per role's test account) and compare against this document; run `pnpm --filter @cloudhal/studio test` (design rules); confirm every new string exists in `en.ts` and every `<locale>.ts` (`test/i18n.test.tsx`); confirm the kumo-design rules (14px, sentence case, tokens) by reading the diff.


---
title: "Agent-built sites: gap analysis"
description: "What stops Claude, Codex or any MCP agent from building a modern, interactive, well-structured site end to end on Cloudhal, and what to build next. Collected 2026-10-15."
url: https://cloudhal.dev/docs/design/agent-built-sites-gap-analysis
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/agent-built-sites-gap-analysis.md
---
# Agent-built sites: gap analysis

What stops Claude, Codex or any MCP agent from building a **modern, interactive, well-structured site end to end** on Cloudhal, and what to build next. Collected 2026-10-15.

## Method

- **Inventory of the code.** An audit of the repository: 89 MCP tools, the surface catalog, the theme layer, the interaction runtime, media, guidance and site-level structure.
- **Building a page ourselves.** A real build: Claude (Claude Code) connected to the live newsroom over MCP with an `edits`-mode key and rebuilt the home page draft with `patch_draft`. Snapshot `snap_3V4W1D5DCY7X75EE84JN`, approval `appr_S3EM38GW74Y5YSV`.
- **Three web research tracks:**
  - how AI site builders reach modern design (v0, Lovable, Framer, Webflow, Wix Harmony, Figma Sites/Make, Google Stitch, Relume, Builder.io);
  - what site and design MCP servers expose, and what Claude and Codex support;
  - what modern sites need technically in 2026, CSS-first.
- **Two runs of the Build model eval** (RFC-0020 open question 7).

Vendor claims are marked as such in the sources. Third-party claims that were not verified are listed under Caveats.

## Where Cloudhal stands

| Capability | Cloudhal today | Evidence |
|---|---|---|
| Pages as validated data | **Strong.** Surfaces: a flat tree, 25 primitives plus 5 blocks, repairs, JSON Patch, `VALIDATION_FAILED` with pointers | `core-ts/surfaces.ts` |
| Safe streaming build loop | **Strong.** Build view, Build chat, MCP Apps preview, click-to-scope, held steps | RFC-0020 status |
| Interop | **Strong.** A2UI v0.9 and json-render in and out | `core-ts/surface-interop.ts` |
| Governance | **Strong.** Drafts, snapshots, approvals, agent modes, audit | ADR-0015/0016 |
| Design tokens | **Weak.** 6 site-wide settings: 4 colors, 4 system font stacks, 3 radii, contrast-checked. No web fonts, no dark mode | `starters/blog/src/settings.ts` |
| Per-section or per-element styling | **Missing.** Only tone/spacing/width/align enums on a few primitives; no `style` on surfaces (RFC-0018 18d not shipped) | catalog |
| Section library, layouts, variants | **Missing.** No hero/feature/pricing/logo/testimonial compositions; one blog theme with a `max-w-3xl` column | RFC-0018 18b–18f pending |
| Motion | **Missing.** No keyframes, transitions, reveals or page transitions in theme or catalog (18f not shipped) | `global.css` |
| Rich components | **Missing.** Icons, carousel, marquee, counter, table, chart, dialog/lightbox, video background | RFC-0020 deviations |
| Forms and server actions | **Missing.** No contact, newsletter or polls | RFC-0020 §8 |
| Images | **Weak.** Upload by bytes (4 MB) or URL; no stock search, no generation, no focal point or treatments | `media/types.ts` |
| Seeing the result | **Missing.** `preview_page` returns HTML with a *neutral* stylesheet, not the theme. No screenshots, no a11y or performance checks | `astro-renderer/preview.ts:447` |
| Agent design guidance | **Missing.** Server instructions and the 6 official skills say nothing about design, layouts or page recipes; `catalogPrompt` (~9 KB) teaches syntax only | `mcp-server/server.ts`, `skills/official` |
| Site-level orchestration | **Weak.** One page per call; no `plan_site` / `apply_plan` (RFC-0017 7b); menus and theme settings always need approval; publish carries every pending draft | tools audit; own build |

**Building a page ourselves** confirmed each weak row:

- **Styling:** the only choices were tones, spacing and ratios. No palette, typography, background, hover or motion.
- **Seeing the result:** checking the result needed a separate browser. `preview_page` would have shown a neutral layout.
- **Images:** they were found by hand, by matching articles to asset ids. There is no "photo of Cappadocia" search.
- **Variety:** a card grid is just Card, Image and Heading. Nothing gives it a modern rhythm.
- **Publishing:** it also carried an unrelated draft article, a draft page, and the earlier Build chat output (a placeholder section from GLM-4.7-Flash).

## Five findings

1. **The architecture is right.** Builders whose AI picks from presets and tokens (Framer, Webflow, Wix Harmony, Figma Sites, Relume) produce the most consistently polished marketing sites. Code-generating tools (v0, Lovable) reach quality through curated libraries (shadcn) and heavy repair pipelines.

   Every generative-UI spec we checked leaves styling to the host: A2UI theme keys, json-render variants, Adaptive Cards host config, Kumo semantic tokens. None has a motion vocabulary. Cloudhal's "data, never code" model matches the best performers. It needs a **richer vocabulary**, not a different model.

2. **The gap is vocabulary, not mechanics.** Cloudhal can already stream, validate, repair, preview and govern. What agents lack is something worth choosing:
   - a token system with real variety;
   - section compositions with variants;
   - surface treatments;
   - motion presets.

   That is what makes a page look 2026.

3. **Agents are blind.** Lovable drives a real browser and screenshots at three widths. Webflow returns element snapshots, Figma `get_screenshot`, Builder a preview URL plus a screenshot.

   Both Claude Code and Codex pass image tool results to the model, so a screenshot tool is directly usable. Cloudhal gives agents neutral HTML that does not even show the theme. Without seeing, an agent cannot iterate toward good design.

4. **Guidance is the cheapest lever.** Anthropic's ~400-token `frontend-design` skill fixes much of the generic "AI look" (Inter, purple gradients, flat backgrounds).

   - Webflow serves guidelines as a tool and as a resource, plus per-site Agent Instructions.
   - Sanity serves best-practice rules as tools.
   - Relume's MCP picks components by section description and content count, and found models otherwise "always chose 3 pricing plans".

   Instructions and tools are the only channels every client honours. Codex has no MCP prompts, and Claude Code cuts instructions at 4,096 characters.

5. **Reliability comes from the pipeline, not the model.** The Build eval showed this: format tolerance, held steps and repairs moved gpt-oss-120b from 3/5 to 5/5 finished briefs. v0 reports raw LLM output failing up to ~10% of the time and 93% error-free generations after its autofixer (vendor numbers). Keep investing in deterministic repair before model calls.

## Gaps and proposals, by priority

Each proposal says what an agent sends as data and how Cloudhal renders it CSS-first, under `script-src 'self'` with no model-written code.

### P0: let agents see and steer (foundation)

**G1. Render-and-look tool.**
- **Tool.** `render_page {siteId, pageId, widths: [1440, 390], fullPage?}` returns `image` content (PNG) plus `structuredContent` with deterministic QA:
  - horizontal scroll at 390 px;
  - images without alt text;
  - heading order;
  - text/background contrast of the rendered tokens;
  - empty images;
  - CLS risk (media without a ratio).
- **Renderer.** It renders the **theme** (the real preview route), not `PREVIEW_CSS`.
- **Implementation.**
  - On Cloudflare: Browser Run (Browser Rendering) screenshot from the admin Worker.
  - On Node: the headless-Chrome path already in `apps/studio/scripts/screenshots.ts`.
- **Follow-up.** axe-core and a Lighthouse lab run as `audit_page`.
- **Effort:** M. **Why first:** it raises the ceiling of every other improvement (finding 3).

**G2. Design guidance as tools, skill and instructions.**
- A Cloudhal **site-design skill** in the spirit of `frontend-design`, written in terms of Cloudhal tokens, sections and motion presets. It covers:
  - one distinctive font pairing;
  - a dominant colour with accents;
  - an orchestrated entrance;
  - section rhythm (alternating surfaces);
  - real content counts (no default "3 plans");
  - checking with `render_page` before publish.
- **Delivery.** Served three ways:
  - as `skill://` (SEP-2640);
  - as a `get_design_guidelines` tool (for Codex);
  - in the first lines of the server instructions, which today never mention `get_catalog` or surfaces.
- **Per-site rules.** Site-resident **design rules** (Webflow's Agent Instructions, Stitch DESIGN.md) let an owner pin brand rules every agent receives.
- **Effort:** S. **Why:** the cheapest lever (finding 4).

**G3. Design token system v2** (extends RFC-0017 7a and RFC-0018). The agent picks only enums; code expands them.
- **Colour.** A seed hue, a scheme (tonal / vibrant / neutral / mono), a contrast level and a mode (light / dark / auto). The renderer generates OKLCH roles and checks WCAG 2.2 at expansion time.
- **Type.** A curated font-pairing id (self-hosted variable WOFF2), a scale ratio and fluid sizes (`clamp()`, Utopia-style `--step-n`), with `text-wrap: balance` on headings.
- **Shape and density.** Radius (none → full), density (compact / cozy / airy).
- **Dark mode.** Through `light-dark()` once the blog theme's fixed greys move to variables (an RFC-0018 prerequisite).
- **Export.** Exportable as W3C DTCG 2025.10 for Figma and Style Dictionary.
- **Effort:** M–L.

**G4. Section and surface styles** (RFC-0018 18d, moved up).
- Per section and per Band/Card, a `surface`: plain, muted, inverse, accent, gradient, mesh, or pattern (dots / grid / noise).
- Also `width` (contained / wide / full-bleed), `spacing` and `anchor`.
- Gradients and meshes are layered `radial-gradient`s from theme tokens; patterns are SVG data URIs. No images and no CSS from the agent.
- **Effort:** M.

### P1: a vocabulary worth choosing

**G5. Section library with variants.**
- Named compositions of primitives, chosen by **content count and description**, not just by title:
  - hero: centered, split 7:5, split media-left, bento, with social proof;
  - features: grid, bento, alternating;
  - logo cloud and marquee;
  - testimonials: grid, wall, carousel;
  - pricing with a monthly/yearly toggle;
  - FAQ, stats with counters, timeline, CTA band, team, newsletter, footer.
- **Tools.** `list_sections {query}` and `insert_section {sectionKind, variant, content}` expand to an ordinary surface, so it stays editable and diffable. Also exported to `catalogPrompt` as examples.
- **Precedent.** Tailwind Plus's most frequent sections were Features 15, Hero 12, Pricing 12, CTA 11 and Team 9. Relume ships 1,000+ components.
- **Effort:** L, delivered incrementally.

**G6. Motion presets** (RFC-0018 18f, moved up). This would set Cloudhal apart, since no generative-UI spec has motion.
- **Site level.** `theme.motion: none | subtle | expressive`.
- **Per node.** `reveal: fade-up | fade | scale | slide-x | stagger` and `hover: lift | glow | tilt | underline-grow`.
- **Elsewhere.** Marquee, count-up, and page transitions.
- **CSS.** `animation-timeline: view()` inside `@supports` and `prefers-reduced-motion: no-preference`. The final state is the default, so Firefox, which lacks scroll-driven animations, still shows content.
  - Page transitions use cross-document View Transitions (`@view-transition { navigation: auto }`, Chrome and Safari; Firefox navigates normally).
  - Stagger uses a renderer-set `--i`.
  - Counters use `@property` with the final number in the DOM.
- **Effort:** M.

**G7. Missing primitives.**
- **Icon:** a curated SVG sprite, Lucide subset; v0 snaps to the nearest real icon.
- **Video:** an asset, poster and loop, usable as a background.
- **Carousel:** scroll snap, plus runtime buttons; `::scroll-button` as an enhancement.
- **Marquee, Counter, Table.**
- **Dialog/Lightbox:** `<dialog>` / popover, anchor positioning.
- **Media with focal point and treatments:** duotone, framed, tilt.
- **Band with background image and scrim.**
- **Children for blocks**, deferred in RFC-0020.
- **Effort:** M per group.

**G8. Images an agent can actually find.**
- **Search:** `search_images {query}` over a licensed stock provider, through the existing server-side fetch with allow-list and attribution stored on the asset.
- **Generation:** `generate_image {prompt, ratio}` with Workers AI, written as an asset with required alt text.
- An art-direction token keeps imagery consistent.
- RFC-0017 open question 6 said "never generate images". Revisit it, since Wix, Hostinger, Sanity and Figma all generate.
- **Effort:** M.

### P2: whole sites, not single pages

**G9. Plan → outline → build.**
- **Tools.** `plan_site` proposes a sitemap with per-page section outlines (Relume, Framer Wireframer and Squarespace Blueprint all start here). `apply_plan` (RFC-0017 7b) builds all pages, the navigation and the theme as one reviewable change, with **one** approval.
- **Batch creation.** Batch page creation inside a plan; menus stop needing one approval per change.
- **Effort:** L.

**G10. Scoped publish.** Publish only the pages and entries a change touched, instead of everything pending. Our own home-page build carried unrelated drafts. Releases (RFC-0008) already pin node versions, so this can reuse them. **Effort:** M.

**G11. Forms and server actions.** One "reader actions" RFC (RFC-0020 open question 5): contact, newsletter and poll, with Turnstile, rate limits, a submission store and email delivery (already present for auth). **Effort:** L.

**G12. Responsive overrides.** A small per-breakpoint map on layout nodes (`columns {base, md, lg}`, `hide`, `order`), never raw CSS. **Effort:** S–M.

### P3: polish and ecosystem

- **MCP ergonomics:**
  - `_meta["anthropic/requiresUserInteraction"]` on publish and rollback, so Claude asks even in auto modes;
  - accurate `readOnlyHint` / `destructiveHint`;
  - instructions under 4,096 characters with keywords first (Claude Code tool search);
  - `outputSchema` everywhere;
  - document Codex `approval_mode` for publish.
- **MCP Apps preview with theme CSS and images.** Today images do not load and the preview uses neutral styles.
- **Visual property panel** for the picked node in Studio (click-to-scope is done; v0 Design mode and Lovable Visual Edits add direct edits).
- **Theme packages and presets** (RFC-0018 18b/18e): "Editorial Serif", "SaaS Bold", "Minimal Mono", "Warm Studio", each a set of G3 tokens, G4 surfaces and G6 motion.
- **A capability-scoped "island"** for bespoke widgets: calculators, configurators. Every tree-based builder has an escape hatch (Webflow AI code components, Framer Workshop, Wix custom elements). This needs its own RFC and threat model.
- **i18n for agents:** hreflang, translation links, locale-aware sitemap and navigation.

## Suggested order

| Step | Contents | Unlocks |
|---|---|---|
| 1 | G2 guidance + G1 `render_page` | Agents can see and are told what good looks like; it improves results with today's catalog |
| 2 | G3 tokens v2 + G4 surface styles | Distinctive sites from the same structure; dark mode |
| 3 | G6 motion + G7 icons, carousel, marquee, counter, video | "Feels modern" |
| 4 | G5 section library + G8 images | Fast, varied, on-topic pages |
| 5 | G9 plan/apply + G10 scoped publish | Whole sites in one reviewed change |
| 6 | G11 forms, G12 responsive, P3 items | Real business sites |

**Measuring it.** Extend the Build model eval with a **design pass**:
- render each result at 1440 and 390 px (G1);
- run the deterministic QA;
- score screenshots against a rubric with a vision model: hierarchy, typography, color, rhythm, imagery, motion use.

Track first-render success, QA pass rate and design score per model and per release, as v0 tracks first-render success.

## Caveats

- Several builder details are vendor claims, or come from third-party summaries: Framer 2026 agent updates, Lovable "90% fewer errors", Wix internals, Codex prompt support, Canva tool names.
- Browser support:
  - scroll-driven animations and cross-document View Transitions are not in Firefox stable as of October 2026 (Interop 2026 targets);
  - `light-dark()` reaches Baseline "widely available" around November 2026.

  Treat them as progressive enhancement.
- WCAG 2.2 AA is the bar; APCA is informative only.

## Sources

**Builders**
- v0 agent architecture: https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent
- v0 design systems: https://v0.app/docs/design-systems
- v0 Design mode: https://v0.app/docs/design-mode
- Fireworks on v0's autofixer: https://fireworks.ai/blog/vercel
- Lovable Visual Edits: https://lovable.dev/blog/introducing-visual-edits
- Lovable browser testing: https://docs.lovable.dev/features/browser-testing
- Framer animations: https://framer.com/features/animations
- Webflow AI site builder: https://webflow.com/blog/ai-site-builder
- Webflow interactions with GSAP: https://webflow.com/blog/webflow-interactions-with-gsap
- Wix Harmony: https://www.wix.com/press-room/home/post/wix-launches-wix-harmony-the-ai-website-builder-that-merges-human-and-artificial-intelligence-rein
- Figma Sites: https://www.figma.com/blog/introducing-figma-sites/
- Figma Make guidelines: https://developers.figma.com/docs/code/write-design-system-guidelines/
- Google Stitch: https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-ai-ui-design/
- Relume: https://relume.io/
- Relume Library MCP: https://www.relume.io/relume-library-mcp
- Builder.io Fusion: https://builder.io/blog/fusion
- Anthropic frontend-design skill: https://claude.com/blog/improving-frontend-design-through-skills

**MCP**
- Webflow MCP: https://developers.webflow.com/mcp/tools/data-tools.md
- Webflow skills: https://developers.webflow.com/mcp/reference/skills.md
- Figma MCP: https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
- Builder Fusion MCP: https://www.builder.io/c/docs/fusion-mcp-server
- Sanity MCP: https://www.sanity.io/docs/ai/mcp-server
- Vercel MCP: https://vercel.com/docs/ai-tooling/vercel-mcp/tools
- Cloudflare Browser Rendering: https://developers.cloudflare.com/browser-rendering/
- MCP tools spec: https://modelcontextprotocol.io/specification/latest/server/tools
- MCP Apps: https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp
- Skills extension: https://modelcontextprotocol.io/seps/2640-skills-extension
- Claude Code MCP: https://code.claude.com/docs/en/mcp
- Codex MCP: https://learn.chatgpt.com/docs/extend/mcp?surface=cli
- Chrome DevTools MCP: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/tool-reference.md
- Playwright MCP: https://playwright.dev/mcp/vision-mode

**Web platform**
- Interop 2026: https://web.dev/blog/interop-2026
- Same-document View Transitions Baseline: https://web.dev/blog/same-document-view-transitions-are-now-baseline-newly-available
- Cross-document View Transitions: https://developer.chrome.com/docs/web-platform/view-transitions/cross-document
- WebKit features in Safari 26: https://webkit.org/blog/17333/webkit-features-in-safari-26-0/
- DTCG 2025.10: https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/
- Radix Themes: https://www.radix-ui.com/themes/docs/components/theme
- Utopia fluid type: https://utopia.fyi/type/
- Tailwind Plus components: https://tailwindcss.com/components


---
title: "Focus mode for the body editor — research and decision"
description: "The owner asked for a focus button in Studio's body editor (2026-10-17). Sources at the end."
url: https://cloudhal.dev/docs/design/body-focus-mode
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/body-focus-mode.md
---
# Focus mode for the body editor — research and decision

The owner asked for a focus button in Studio's body editor (2026-10-17). Sources at the end.

## What established editors do
| Editor | What focus hides | Dimming | Shortcut | Remembered |
|---|---|---|---|---|
| WordPress (Distraction free) | Closes sidebars; the top toolbar fades and returns on hover; hides the block toolbar and most "+" inserters (blocks come from `/`) | Separate **Spotlight** mode dims every block but the current one | ⇧⌘\\ / Ctrl+Shift+\\ | Per browser (localStorage) |
| iA Writer (Focus Mode) | The app is already bare; focus is about the text | **Sentence** or **paragraph** stays lit, the rest dims | ⌘D | Yes |
| iA Writer / Typora (Typewriter) | — | — | View menu | Yes; iA advises turning it off while editing (selections make the screen jump) |
| Typora (Focus) | — | Everything but the current block fades | View menu | Yes |
| Obsidian (plugins) | Full screen writing | Current line or paragraph dimming, typewriter scroll, limited line length | e.g. F8 / F9 | Yes |

What writers expect from all of them: one click or one shortcut in and out, the words and the formatting tools still there, nothing else on screen, the choice remembered, and never losing track of whether the work is saved.

## Decision (shipped)
- A **Focus** button in the body editor's header row (and **Ctrl/⌘+Shift+\\**, WordPress' convention, from inside the editor) turns the editor into a full-screen writing layer: a readable column (`max-w-3xl`), the formatting toolbar and mode switch in a sticky top bar, everything else of Studio out of view.
- **The save stays at hand**: the host passes `focusActions`; the article editor shows "Unsaved changes / All changes saved" and its Save button in the layer's top bar.
- **Spotlight** (a switch in the layer) dims every top-level block except the one being written (Tiptap's Focus extension, `has-focus`); remembered per browser (`cloudhal.editor.spotlight`, storage failures ignored). No transition under reduced motion.
- **Leaving**: Esc (unless the slash menu took it), the "Leave focus" button or the shortcut; focus returns to the Focus button.
- **Accessibility**: the layer is a modal `dialog` named after the editor; everything outside it is `inert` while it is open (Tab and screen readers stay inside); the button carries `aria-pressed` and the shortcut as its title.
- **Never automatic**: focus mode is entered on request only, never restored on page load (opening an article in a full-screen layer would surprise); only the spotlight preference is remembered.
- Markdown mode works inside the layer too.

## Later
- **Typewriter scrolling** (keep the caret line at a fixed height): useful for long drafts, but it fights selection while editing (iA's own warning); add as an opt-in switch if writers ask.
- ~~Page editor sections~~: done — the page editor provides its save through `FocusSaveContext`, so its rich-text sections show the same save state and Save in focus mode.
- Word count and reading time in the layer's top bar.

## Sources
- WordPress, Distraction Free mode: https://wordpress.org/documentation/article/distraction-free-mode/
- iA Writer, Focus Mode: https://ia.net/writer/support/editor/focus-mode
- Typora, Focus Mode and Typewriter Mode: https://support.typora.io/Focus-and-Typewriter-Mode
- Obsidian Typewriter Mode plugin: https://github.com/davisriedel/obsidian-typewriter-mode


---
title: "Carousels and sliders: research and decisions"
description: "Research for RFC-0027 (a carousel for generated UI and theme hero areas). Sources at the end."
url: https://cloudhal.dev/docs/design/carousels
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/carousels.md
---
# Carousels and sliders: research and decisions

Research for RFC-0027 (a carousel for generated UI and theme hero areas). Sources at the end.

## The platform (October 2026)
- **Everywhere, no JavaScript**: scroll snap; fragment links (`href="#slide-3"`) as slide pickers (they also jump the page and change the hash); lazy images in horizontal scrollers (Chrome 121+ uses the vertical thresholds).
- **Chromium only**: CSS carousels (`::scroll-button()`, `::scroll-marker`, `:target-current`, Chrome 135; Safari and Firefox have none, ~71% global); `scroll-target-group: auto` (Chrome 140: ordinary anchor links get `:target-current`); `scroll-state()` queries (Chrome 133: `snapped`, `scrollable`); `interactivity: inert` (Chrome 135).
- **Native markers' accessibility is not ready**: they are exposed as tabs without tabpanels, with wrong counts and focus in hidden slides (Sara Soueidan, 2025); Chrome has fixed part of it.
- **Not in the platform**: looping and auto-advance (left out of the CSS proposal on purpose).

## Accessibility and evidence
- **APG carousel pattern**: a labelled `region` with `aria-roledescription="carousel"` (the label never says "carousel"); slides are labelled `group`s (`aria-roledescription="slide"`, "3 of 10" as a fallback); native buttons that never move focus; a rotation control first in Tab order that stops rotation for good; a polite live region, off while rotating.
- **WCAG 2.2.2**: auto-advancing content needs pause/stop; pausing only while focused is not enough; our page-wide pause (RFC-0024) already helps.
- **Evidence against auto-rotating heroes**: ~1% of visitors click a slide, 89% of those slide 1 (Notre Dame); NN/g: people miss later frames — use ≤ 5, show "2 / 5", dots are weak, use a peek, allow ~3 words per second, prefer a static hero; Baymard: 46% of homepage carousels have usability problems; government design systems leave carousels out.

## Approaches

| Approach | Size | For us |
|---|---|---|
| CSS only (snap, anchors, Chromium extras) | 0 KB | The baseline: works without JS, no CLS, native swipe and momentum, RTL by logical properties |
| Embla / Keen | ~6–7 KB | Transform-based, third party |
| Splide | ~12 KB | Best accessibility out of the box (our model for behaviour) |
| Swiper | ~20 KB | Every feature, heavy, JS-first |
| Material 3 layouts | — | Names worth borrowing: hero (one large + peek), uncontained rail |

## Decisions
1. **One catalog component, `Carousel`**, each child one slide (Cards, Images, Stacks…), with `label` (required) and `variant` `hero | rail | gallery | testimonials`; `perView` (1–4 or auto with `itemWidth`), `peek`, `align`, `gap`, `aspect` (required for hero and gallery), `controls`, `markers` (`numbers` shown as "2 / 5" by default; `labels`, `dots`, `thumbs` for galleries), `loop`, `autoplay`. Catalog-only, like RFC-0024/0025 components: no contract change.
2. **No-JS baseline**: a scroll-snap track (focusable, `overscroll-behavior-inline: contain`), markers as real anchor links (`scroll-target-group: auto` + `:target-current` add the active style in Chromium), arrow buttons rendered hidden for the module to reveal (their space reserved). **No native `::scroll-button()`/`::scroll-marker`** until their accessibility settles and Safari or Firefox ship them.
3. **A small first-party module, `carousel.1.js`** (~3–4 KB, only with a carousel): prev/next with correct ends (direction-aware, RTL), position tracking (`scrollend` or IntersectionObserver), "2 / 5" and `aria-current` on markers, marker clicks scroll the track (no page jump, no hash), a polite live region after the reader moves, `inert` for off-screen hero slides where CSS cannot, and autoplay with all guards. No scroll hijacking: swipe is native scroll.
4. **Autoplay: hero only, off by default.** At most one per page; interval ≥ 5 s and long enough for the longest slide's text (~3 words per second); never below motion `standard`, under reduced motion, while the reader has paused motion, or in a hidden tab; stops for good on focus, pointer or swipe, pauses on hover; a rotation button first in Tab order.
5. **Loop: hero only** (the module rewinds; without JS the carousel is bounded). Rails never loop.
6. **Limits**: hero 2–5 slides, rail and testimonials 2–12, gallery up to 24; no carousel inside a carousel, a Marquee or a Scrolly; overlays are never slides (a slide's Button may open one).
7. **Images**: hero slide 1 eager with high fetch priority in the first section, all other slides lazy; one frame `aspect` for every hero and gallery slide; `sizes` from `perView`; gallery and hero slides use the fit modes of `docs/design/images.md` (gallery defaults to blur-fill).
8. **Gallery stays apart from `Lightbox`**: a gallery carousel may open its image large in a Lightbox later.
9. **Guidance**: static hero by default; a hero carousel only for 2–5 equally important messages; nothing reachable only from slide 3+.
10. **`render_page` checks**: `carousel-label`, `carousel-lcp`, `carousel-focus`, `carousel-autoplay`, CLS while stepping, and a no-JS pass; `overflow-x` and `tap-target` cover the track and controls.

## Rollout (RFC-0027)
| Phase | Scope |
|---|---|
| 27a | `Carousel` rail and hero without JavaScript: catalog, rules, rendering, CSS, image loading, label/LCP checks |
| 27b | `carousel.1.js`: buttons, position, live region, inert fallback, markers that scroll; focus and CLS checks |
| 27c | `gallery` (thumbnails) and `testimonials` |
| 27d | Hero `loop` and `autoplay` with every guard; the autoplay check |
| 27e | Theme hero areas accept a hero carousel; DESIGN.md and `get_design` guidance; the build eval's rubric |

## Sources
- WebKit Interop 2026 https://webkit.org/blog/17818/announcing-interop-2026/ · web.dev Interop 2026 https://web.dev/blog/interop-2026 · carousel best practices https://web.dev/articles/carousel-best-practices
- CSS carousels https://developer.chrome.com/blog/carousels-with-css · spec https://drafts.csswg.org/css-overflow-5/#scroll-marker-pseudo · caniuse https://caniuse.com/wf-scroll-markers · MDN https://developer.mozilla.org/en-US/docs/Web/CSS/::scroll-marker · Chrome 140 https://developer.chrome.com/blog/chrome-140-beta · scroll-target-group https://una.im/scroll-target-group/ · CSS scrollspy https://sarasoueidan.com/blog/css-scrollspy/ · scroll-state https://developer.chrome.com/blog/css-scroll-state-queries · Chrome 135 https://developer.chrome.com/blog/chrome-135-beta · accessible carousel https://developer.chrome.com/blog/accessible-carousel · explainer https://github.com/flackr/carousel/blob/main/README.md · CSS carousels' accessibility https://sarasoueidan.com/blog/css-carousels-accessibility
- APG https://www.w3.org/WAI/ARIA/apg/patterns/carousel/ · WCAG 2.2.2 https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html · Notre Dame https://erikrunyon.com/2013/07/carousel-interaction-stats/ · NN/g https://www.nngroup.com/articles/designing-effective-carousels/ · Baymard https://baymard.com/blog/homepage-carousel · Scottish Government https://designsystem.gov.scot/styles/images/carousels · Queensland Health https://www.design-system.health.qld.gov.au/about/exploring-our-decisions/carousels · Dawn #1183 https://github.com/Shopify/dawn/issues/1183 · Shopify a11y https://shopify.dev/themes/best-practices/accessibility
- Embla https://www.embla-carousel.com/ · Splide a11y https://splidejs.com/guides/accessibility/ · Swiper https://swiperjs.com/swiper-api · Material carousel https://developer.android.com/develop/ui/compose/components/carousel · scrollend in Safari 26.2 https://webalur.com/en/blog/safari-version-26-2-introduces-scrollend


---
title: "Icons on public sites: research and decisions"
description: "Research for the next RFC (icons in themes and surfaces). Studio already uses Phosphor through Kumo; public sites have almost none: hand-drawn SVGs for the menu, caret and close buttons, and social links as text."
url: https://cloudhal.dev/docs/design/icons
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/icons.md
---
# Icons on public sites: research and decisions

Research for the next RFC (icons in themes and surfaces). Studio already uses Phosphor through Kumo; public sites have almost none: hand-drawn SVGs for the menu, caret and close buttons, and social links as text.

## What Astro offers (installed: astro 7.3.6)
- **SVG components are stable** (since 5.7): `import Logo from "./logo.svg"` renders an inlined `<svg>`, props override the file's attributes; `size`, `title` and sprite `mode` were removed in 5.6 (use `width`/`height`, `aria-label`). https://docs.astro.build/en/guides/images/ · https://astro.build/blog/astro-570/ · https://astro.build/blog/astro-560/
- **SVG optimisation** is still experimental (`experimental.svgOptimizer`, svgo, build only). https://docs.astro.build/en/reference/experimental-flags/svg-optimization/
- **No official icon library.** And SVG components work only for `.astro` imports at build time; our surfaces are rendered to strings in plain TypeScript (`packages/astro-renderer/src/surfaces.ts`), so we need icons as strings in TS data.

## Options

| Option | License | Icons | Style | String in a Worker | Notes |
|---|---|---|---|---|---|
| `@phosphor-icons/core` | MIT | ~1,500 | 6 weights (thin…fill, duotone) | via our codegen | Same family as Studio; ~75 brand logos |
| `lucide-static` | ISC | ~1,600 | stroke, adjustable width | yes, exports strings | No brand logos by policy |
| `astro-icon` (Iconify) | — | any set | any | `.astro` only | Bundles whole sets in server output without `include` |
| `unplugin-icons` | MIT | all Iconify | any | `?raw` at build | Needs a bundler step |
| `@iconify-json/*` + `@iconify/utils` | per set | 200k+ | any | yes (`iconToSVG`) | Good for codegen |
| `simple-icons` | CC0, per-icon licenses vary | 3,400+ brands | fill | yes | Dropped LinkedIn in v14; brands can ask removal |
| Tabler | MIT | 6,000+ | stroke + filled | via codegen | Large, no Studio match |
| Heroicons | MIT | ~300 | outline/solid | via codegen | Small, no brands |

Sources: https://github.com/phosphor-icons/core · https://lucide.dev/guide/packages/lucide-static · https://lucide.dev/brand-logo-statement · https://github.com/natemoo-re/astro-icon · https://github.com/unplugin/unplugin-icons · https://iconify.design/docs/libraries/utils/icon-to-svg.html · https://github.com/simple-icons/simple-icons/blob/develop/DISCLAIMER.md · https://shields.io/blog/simple-icons-14 · https://github.com/tabler/tabler-icons · https://github.com/tailwindlabs/heroicons

## Accessibility
- **Decorative** (next to text): `aria-hidden="true" focusable="false"`, no `<title>`. https://www.w3.org/WAI/tutorials/images/decorative/
- **Icon-only buttons and links**: the name goes on the control (`aria-label` or hidden text), the SVG stays hidden; labelling the SVG fails in some screen readers. https://www.sarasoueidan.com/blog/accessible-icon-buttons/
- `fill="currentColor"`, `width/height="1em"`; check `forced-colors`. https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors
- **RTL**: directional icons (arrows, chevrons, back, external, send) mirror under `[dir=rtl]`; logos, checks and clocks do not.

## Decisions
1. **Phosphor** (`@phosphor-icons/core`, MIT): the same family as Studio, so previews and the admin match; six weights let a theme choose a feel as a token; brand logos in the same style.
2. **Social icons from Phosphor** (11 of our 12 networks). **Bluesky** from simple-icons (`siBluesky`) after checking its per-icon license, until Phosphor has one. Logos are monochrome in `currentColor`, never recoloured or distorted, and only link to the owner's own profiles.
3. **Delivery: inline SVG strings** from a generated, versioned TS map in `@cloudhal/core-ts/icons` (no JavaScript, no request, CSP unchanged, Worker-safe, works in `.astro` and in surfaces). A codegen script reads an allow-list, runs svgo and writes the map; `pnpm drift` covers it. Same-page `<symbol>`/`<use>` dedupe later, for repeated icons.
4. **Semantic names, a curated set of about 96**: interface (≈20: `menu`, `close`, `search`, `chevron-down`, `arrow-right`, `external`…), actions and status (≈25: `check`, `info`, `warning`, `download`, `copy`, `share`…), content and topics (≈35: `mail`, `phone`, `map-pin`, `calendar`, `clock`, `star`, `heart`, `quote`, `play`…) and social (the 12 `SocialLink` networks). Names are the contract, so a theme can swap the drawings later.
5. **`IconName` lives in `@cloudhal/core-ts/icons` for now** (revised in RFC-0026): icons sit in surface props, which the catalog checks, and no contract field uses them yet; the enum joins `common.schema.json` when one does (menu item icons, for example).
6. **Catalog**: an `Icon` primitive (`name`, `label?`, `size`, `tone`); `icon` on `Button` (with `iconPosition`), `Badge` and `Stat`; list markers. Icons are decorative unless given a label; a Button keeps its label as the accessible name. `catalogPrompt` lists the names by group; a repair suggests the nearest name.
7. **Themes**: phase 1 picks a Phosphor weight (regular, light, bold, fill) as a design token, with one map per weight behind its own subpath; phase 2 lets a theme package supply its own drawings for the same names.

## Rollout (RFC-0026)
1. Contract `IconName`, `core-ts/icons` (`renderIcon`), regular weight; replace the theme's hand-drawn menu, caret and close icons; footer social links become labelled icon links.
2. Catalog: `Icon`, `icon` on Button, Badge and Stat, list markers; prompt, checks and repair; RTL and forced-colors CSS.
3. The weight token and per-weight subpaths; optional same-page dedupe.
4. Theme-supplied icon maps; Studio pickers use the same names.


---
title: "Image presentation: placeholders and fit — research and decisions"
description: "Research for the next RFC (images that load gracefully and fit any frame). Sources at the end."
url: https://cloudhal.dev/docs/design/images
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/images.md
---
# Image presentation: placeholders and fit — research and decisions

Research for the next RFC (images that load gracefully and fit any frame). Sources at the end.

## What we have today
- **Contract** (`asset.schema.json`, `AssetImage`): `width`, `height`, `animated`, `blurhash` (nothing computes it) and `lqip` (a raster `data:` URL, ≤ 4096 characters). No colour, focal point or alpha flag; `ImageRef` has no fit fields.
- **Ingest**: Studio computes the LQIP in the browser (`apps/studio/src/lib/media.ts`, ≤ 32 px WebP); the server only validates it. Agent and import uploads get none.
- **Rendering** (`astro-renderer/src/media.ts`): the LQIP is a `background-image` on the `<img>` itself, scaled with `cover`, unblurred, no fade. Transformations are opt-in (`cdn-cgi`), `fit=scale-down`, no `gravity`.
- **Fit**: surface `Image` crops with `object-fit: cover` for a ratio; the lightbox stage uses `contain`.
- **Two bugs** in the current approach:
  1. a transparent PNG/WebP keeps showing its LQIP through its transparent pixels after it loads;
  2. wherever an image is `contain`ed in a larger box, the blocky 32 px LQIP shows in the bars.

## Placeholder techniques

| Technique | Bytes | Needs visitor JS | Quality | Alpha | Notes |
|---|---|---|---|---|---|
| Dominant colour | ~7 B | No | Calm | — | Unsplash ships it with a hash |
| CSS-only gradient LQIP | ~20 B | No | Very coarse | No | Clever, too coarse |
| BlurHash | ~30 B | Yes (canvas) | Good | No | Breaks our no-JS rule |
| ThumbHash | ~35 B | Yes, or server decode | Better | Yes | Same problem |
| Tiny raster LQIP (16–24 px WebP) | 100–400 B | No | Best per byte, once blurred | Yes | Facebook, Medium, Mux |
| LQIP in an SVG `feGaussianBlur` | + ~300 B | No | Smooth | Yes | Next.js `placeholder="blur"` |

- There is no CSS `:loaded`; a fade-in needs a script, and images must never be hidden when JS is off.
- Blur is cheap when static and drawn from a tiny source; animating a blur radius is expensive.

## Mismatched aspect ratios
- **cover + focal point** (crop steered by a stored `{x, y}` → `object-position`, and `gravity=XxY` with transformations): cards, grids, heroes.
- **contain + blur-fill** (the image whole, its side areas filled by the same image enlarged and blurred — the look of social video tools and media galleries): lightbox stages, gallery carousels, portrait shots in landscape frames.
- **contain + colour-fill** (the bars in the image's dominant colour): logos, transparent images, screenshots.
- Gimmicky when used everywhere, behind small tiles, or with a large radius.

## Decisions
1. **Visitors get LQIP + colour, no hash.** No JavaScript, best quality per byte. `blurhash` stays in the contract (unused, documented); no ThumbHash.
2. **New optional `AssetImage` fields**: `color` (`#rrggbb`), `alpha: true` (transparency, read from the file's header at ingest: PNG colour type/`tRNS`, WebP VP8X, AVIF `auxC`), `focal` (`{x, y}` in 0–1). The LQIP target tightens to 16–24 px, ≤ ~400 B.
3. **Renderer**: the placeholder stays the `<img>`'s background, but becomes the colour plus the LQIP blurred inside an SVG filter, covering the box; no LQIP for transparent images (fixes bug 1); bars never show the raw LQIP (fixes bug 2). (A wrapper element was considered first; RFC-0028 §2 explains why it was not needed.)
4. **Fit modes**: `cover` (default with a ratio), `contain`, `blur-fill`, `color-fill`, `natural`. Defaults: Image with a ratio → cover; Lightbox stage → blur-fill; carousel gallery slides → blur-fill; cards and heroes → cover with the focal point.
5. **Blur-fill** is that same blurred background left visible around a contained image: painted from the LQIP already in the page, decorative, gone in forced colours. No second image download, no `backdrop-filter`.
6. **No fade-in**: the image paints over its placeholder (honest, no script). A fade would need a second layer under every image (RFC-0028 Status, 28d).
7. **Budget**: placeholders up to ~24 KB per page; beyond that, colour only. `render_page` counts them and flags images cropped by `cover` with no focal point when the ratios differ a lot.
8. **Focal point**: set by people in Studio and by agents through the existing policy-checked asset update; per-use overrides and `fit` on `ImageRef` wait until a page needs them (a contract change for every image use).
9. **Server-side placeholders** for agent and import uploads: through the Cloudflare Images binding **when the deployment has one** (a 16–24 px WebP + colour; 5,000 unique transformations a month are free, then billed). Otherwise Studio computes them, and a `cloudhal media placeholders` backfill fills old assets. *Turning the binding on for the live deployment is the owner's call.*

## Rollout (RFC-0028)
1. Contract `color`/`alpha`/`focal`; alpha from the header parsers; Studio adds colour and alpha; the wrapper placeholder; bugs 1 and 2 fixed; budgets.
2. Fit modes and focal point in the catalog, CSS and transformations; `render_page` checks.
3. Server-side placeholders through the Images binding; the backfill command.
4. Fade-in and `gravity=auto` focal suggestions: decided against (RFC-0028 Status).

## Sources
- ThumbHash https://evanw.github.io/thumbhash/ · CSS-only LQIP https://leanrada.com/notes/css-only-lqip/ · Mux https://www.mux.com/blog/blurry-image-placeholders-on-the-web · Facebook preview photos https://engineering.fb.com/2015/08/06/android/the-technology-behind-preview-photos/ · Medium https://jmperezperez.com/medium-image-progressive-loading-placeholder/ · Unsplash https://unsplash.com/documentation/changelog · Next.js Image https://nextjs.org/docs/app/api-reference/components/image
- Cloudflare transformations https://developers.cloudflare.com/images/transform-images/transform-via-url/ · Images binding https://developers.cloudflare.com/images/transform-images/bindings/ · pricing https://developers.cloudflare.com/images/pricing/ · limits https://developers.cloudflare.com/images/get-started/limits/ · Workers limits https://developers.cloudflare.com/workers/platform/limits/ · jSquash https://github.com/jamsinclair/jSquash
- `:loaded` https://lists.w3.org/Archives/Public/public-css-archive/2025Sep/0177.html · fade-in needs JS https://medienbaecker.com/articles/animate-native-lazy-loading · no-JS failure https://forum.getpublii.com/topic/fadein-lazy-load-feature-causes-broken-images-without-javascript-enabled/ · blur cost https://developer.chrome.com/blog/animated-blur/ · forced colours https://www.w3.org/TR/css-color-adjust-1/


---
title: "Kumo upstream notes (not filed)"
description: "Issue texts for gaps Cloudhal found in Kumo 2.14.0 (the latest release on 2026-10-12) while making Studio speak Turkish. Nothing here has been filed: the maintainer decides what to send, and when."
url: https://cloudhal.dev/docs/design/kumo-upstream-notes
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/kumo-upstream-notes.md
---
# Kumo upstream notes (not filed)

Issue texts for gaps Cloudhal found in [Kumo](https://github.com/cloudflare/kumo) **2.14.0** (the latest release on 2026-10-12) while making Studio speak Turkish. Nothing here has been filed: the maintainer decides what to send, and when. How Studio works around each gap today is in `docs/design/DESIGN.md` §2v "Kumo locale"; the local changes to Kumo are in `patches/@cloudflare__kumo@2.14.0.patch`, generated by `scripts/kumo-patch.ts` from `patches/kumo/*.patch` and the right-to-left conversion (§7).

When Kumo is upgraded, go through this list: drop what the new release fixes (and the matching workaround or patch), and keep the rest.

---

## 1. `TimeseriesChart`: no way to format the tooltip's timestamp

**Status in Cloudhal:** patched locally (`tooltipTimestampFormat`).

### Title

`TimeseriesChart`: add `tooltipTimestampFormat` (tooltip time follows the browser locale and always shows seconds)

### Body

The tooltip heading of `TimeseriesChart` is formatted by a module-level formatter in `src/components/chart/TimeseriesChart.tsx`:

```ts
const tooltipDateFormat = new Intl.DateTimeFormat(undefined, {
  month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false,
});
```

So:

- the language is the browser's, not the app's: a Turkish UI in an English browser shows "Oct 8, 14:00:00" next to Turkish axis labels and footer;
- the time zone is the browser's: data bucketed in UTC cannot be labelled in UTC (we shift every point by the local offset to make it read UTC);
- the shape is fixed: daily buckets still show a time with seconds.

Every other text in the chart already has a hook (`xAxisTickFormat`, `yAxisTickFormat`, `tooltipValueFormat`, `tooltipFooter`), so the timestamp is the odd one out.

**Proposal.** An optional prop, used by both the series and the marker tooltip:

```ts
/** Formats the tooltip's timestamp heading. Defaults to the current browser-locale format. */
tooltipTimestampFormat?: (timestamp: number) => string;
```

```diff
- formatTimestamp,
+ formatTimestamp: tooltipTimestampFormat ?? formatTimestamp,
```

This is exactly what we apply as a two-line `pnpm patch` today; happy to open the PR.

---

## 2. `TimeseriesChart`: hard-coded English in the loader and tooltip

**Status in Cloudhal:** worked around (the loader is wrapped in `aria-hidden` and the block renders its own `role="status"`); the other strings are not reached by Studio.

### Title

`TimeseriesChart`: translatable "Loading chart", "+N more" and "Reference marker"

### Body

`TimeseriesChart` has three English strings with no prop and no `KumoLocaleProvider` entry:

- the skeleton's `aria-label="Loading chart"` (read by screen readers whenever `loading` is set);
- the tooltip's `+{hiddenCount} more` when there are more series than `tooltipMaxItems`;
- `"Reference marker"`, the fallback name of a marker without `label`.

**Proposal.** Add them to `KumoLocaleProvider`'s translations (e.g. `translations.chart.{loading, moreSeries(count), referenceMarker}`), and/or a `labels` prop on `TimeseriesChart`. A provider entry is preferable: apps set it once.

---

## 3. `ChoroplethMap`: legend reads "High" / "Low"

**Status in Cloudhal:** worked around (ECharts `visualMap.text` merged after Kumo's options).

### Title

`ChoroplethMap`: let the legend's end labels be set (`legendText` or locale)

### Body

With `showLegend`, `ChoroplethMap` builds `visualMap: { text: ["High", "Low"], … }` inside its options, with no prop to change it. Apps in other languages have to reach into the ECharts instance and `setOption({ visualMap: { text } })` after every Kumo update.

**Proposal.** `legendText?: [high: string, low: string]` (or `legendLabels: { high, low }`), defaulting to the provider's translations (`translations.map.{high, low}`) and then to English. While there: the default `valueFormat` uses `value.toLocaleString()` (browser locale); taking the provider's locale would make the default tooltip match the app.

---

## 4. `DateRangePicker`: hard-coded English and browser-locale months

**Status in Cloudhal:** avoided — Studio uses `DatePicker mode="range"` with localised `formatters`/`labels` instead.

### Title

`DateRangePicker`: hard-coded English strings and `en-US` / browser-locale dates (or remove it in favour of `DatePicker mode="range"`)

### Body

`DateRangePicker` is marked `@deprecated` ("Use `DatePicker` with `mode="range"`"), but it is still exported, documented and listed by the Kumo CLI, and it cannot be localised:

- weekday initials are a constant: `["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]`, and the week always starts on Sunday;
- `aria-label`s "Previous month", "Next month", "Edit month and year";
- the footer "Timezone: " and the "Reset Dates" button (also title case, against the Kumo sentence-case rule);
- day buttons' `aria-label`s use `toLocaleDateString("en-US", …)` plus English ", selected as start date" / ", selected as end date" / ", within selected range";
- month names use `toLocaleString("default", …)`, i.e. the browser locale, so the heading and the weekdays can be in different languages;
- the default `timezone` is "New York, NY, USA (GMT-4)";
- the picker cannot be given a selection (`selected`/`defaultValue`), only reports changes.

**Proposal.** Either remove it in the next major (the deprecation already points to `DatePicker`), or, if it stays, take `locale` (for `Intl`), `weekStartsOn` and a `labels` object, and read defaults from `KumoLocaleProvider`. In the meantime the docs and `kumo ls` could flag it as deprecated so new code does not pick it.

---

## 5. `KumoLocaleProvider` covers only `LayerDialog`

**Status in Cloudhal:** used for dialogs; everything else is passed per component.

### Title

`KumoLocaleProvider`: a `locale` and translations for the rest of Kumo (date picker, charts, maps)

### Body

`KumoLocaleProvider` accepts `translations.layerDialog.{close, cancel}` and nothing else reads it. Apps that run in another language have to localise every other component by hand, and some (items 1–4) cannot be localised at all.

**Proposal.**

- A `locale` prop (BCP 47) on the provider, read by every component that formats dates or numbers: `DatePicker` (react-day-picker's `formatters`/`labels` built with `Intl` in that locale, `weekStartsOn` from `Intl.Locale#getWeekInfo`, `lang`), `TimeseriesChart` (tooltip time and default value format), `ChoroplethMap`/`BubbleMap` (default `valueFormat`), and ECharts' own `locale` init option in `Chart` (today `echarts.init(el, theme)` is called without options, so an app cannot set it except by wrapping the `echarts` object it passes in).
- Translation keys for the remaining built-in strings (items 2–4, plus react-day-picker's labels: previous/next month, navigation, "Today", "selected").
- `DatePicker` keeps its per-instance props (they win over the provider).

For reference, this is how Cloudhal localises `DatePicker` without a date-fns locale, using only props Kumo passes through (`packages/ui/src/blocks/calendar-locale.ts`):

```ts
const caption = new Intl.DateTimeFormat(locale, { month: "long", year: "numeric", timeZone });
<DatePicker
  lang={locale}
  weekStartsOn={firstDayOfWeek(locale)}
  formatters={{ formatCaption: (m) => caption.format(m), formatWeekdayName: (d) => short.format(d) }}
  labels={{ labelPrevious: () => t.previousMonth, labelNext: () => t.nextMonth, labelDayButton: … }}
/>
```

---

## 6. `DeleteResource` block: every word is English

**Status in Cloudhal:** fixed in our copy (`packages/ui/src/blocks/kumo/delete-resource/`): a required `labels` prop replaces `resourceType`/`deleteButtonText`; Studio fills it with `deleteResourceProps` (`apps/studio/src/components/deleteLabels.ts`).

### Title

`DeleteResource` block: take its words as props (title, warning, "Type … to confirm", Cancel, aria-labels)

### Body

The block (`kumo add DeleteResource`) hard-codes "Delete {name}", "This action cannot be undone. This will permanently delete the …", "Type … to confirm:", "Cancel", `aria-label`s "Close", "Copy … to clipboard", "Type … to confirm deletion", and the button "Delete {resourceType}". It also lower-cases `resourceType` with `toLowerCase()` (wrong for Turkish "I"), and the sentence order is fixed in JSX, so a translation cannot move the name.

**Proposal.** A `labels` object (or `KumoLocaleProvider` keys) with templates that contain `{name}`, rendered with the name as the highlighted chip wherever the template puts it, as Cloudhal's copy does.

---

## 7. Right-to-left: Kumo's styles are physical

**Status in Cloudhal:** Studio and the `@cloudhal/ui` blocks use logical utilities only (lint `rtl-logical`, ADR-0033 D); Base UI's `DirectionProvider` (re-exported by Kumo) wraps Studio, fed by the locale registry's `dir` (ADR-0033 B). Kumo's own components are patched (ADR-0033 A1, decided 2026-10-18 with Arabic as the first RTL language): `scripts/kumo-patch.ts` rewrites the 217 physical utilities of Kumo 2.14's `dist` to logical ones into the generated `patches/@cloudflare__kumo@2.14.0.patch`; offsets that are centred (`left-1/2`) or measured by a physical `translate-x` (the tabs' indicator, centred dialogs) stay physical. Studio's and the blocks' directional icons mirror through `DirectionalIcon` (ADR-0033 C1). Kumo's own ten (`DropdownMenu`'s submenu caret, the sidebar's caret, `Pagination`'s four, `DateRangePicker`'s two, `CommandPalette`'s arrow and breadcrumb caret) and `Breadcrumbs.Separator`'s inline SVG chevron are patched too (`patches/kumo/rtl-icons.patch`): each gets `rtl:-scale-x-100`, and the sidebar caret's open `rotate-90` gets `rtl:-rotate-90` so it still points down. That variant reads `dir` from the DOM (Studio sets `<html dir>`), not Base UI's `DirectionProvider`, because several of the icons sit in conditional JSX where a hook cannot be called; a subtree given only `DirectionProvider direction="rtl"` without a `dir` attribute does not mirror them. **Still open upstream:** everything in the issue below — Cloudhal re-applies both the conversion and the icon patch on each Kumo upgrade until Kumo ships them. The issue below is ready to paste; **the owner files it**, not an agent.

### Title

Support right-to-left layouts: logical properties in Kumo's components (and `dir`-aware placement)

### Body

Kumo 2.14's compiled CSS has about 239 physical utilities (`ml-*`, `mr-*`, `pl-*`, `pr-*`, `left-*`, `right-*`, `text-left`/`text-right`, `border-l`/`border-r`, `rounded-l`/`rounded-r`) and 12 logical ones (`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`), plus 3 `rtl:` variants. In an Arabic or Hebrew UI under `<html dir="rtl">`, the sidebar, dialog close buttons, input addons, table cell alignment, toolbars and popover offsets therefore stay left-to-right, although Base UI underneath already supports direction (`DirectionProvider`, which Kumo re-exports at `@cloudflare/kumo/primitives/direction-provider`).

**Proposal.**

- Use Tailwind 4's logical utilities in every component (`ms`/`me`, `ps`/`pe`, `start`/`end`, `text-start`/`text-end`, `border-s`/`border-e`, `rounded-s`/`rounded-e`/`rounded-ss`…). In left-to-right pages they render exactly as today, so the change is invisible to existing users.
- Read the direction from Base UI's context for placement that is computed (popover side `inline-start`/`inline-end`, sidebar side, the order of icon and label where it matters).
- Document which icons mirror (back, forward, carets in breadcrumbs and menus) and offer a `mirrored`-aware icon slot. Kumo's own directional icons today — `DropdownMenu`'s submenu caret, the sidebar's caret, `Pagination`'s first/previous/next/last, `DateRangePicker`'s month arrows, `CommandPalette`'s arrow and caret — should set Phosphor's `mirrored` from the direction context.
- A lint in Kumo's own CI against new physical utilities keeps it that way.

Cloudhal's interim plan, if an RTL language comes before this: a generated `pnpm patch` that rewrites the compiled classes (the same mapping as our codemod, `scripts/i18n-codemod/logical-utilities.ts`), re-generated on each Kumo upgrade.

---

## 8. `Label`: "(optional)" and "More information" are hard-coded English

**Status in Cloudhal:** patched locally (`patches/kumo/label-locale.patch`): `KumoLocaleProvider` takes `translations.label.{optional, moreInformation}`, and Studio passes `common.optional` / `common.moreInformation`. Seen in the Arabic and Hebrew screenshots, where every optional field read "(optional)".

### Title

`Label`: translatable optional suffix and tooltip button name (`KumoLocaleProvider`)

### Body

`Label` (used by `Field`, `Checkbox` and `Select` when `required={false}`) renders the literal `"(optional)"`, and its tooltip trigger has `aria-label="More information"`. Neither has a prop, and `KumoLocaleProvider` does not cover them, so an app in another language shows English next to every optional field.

**Proposal.** Add them to the provider, as `layerDialog` already is:

```ts
interface KumoTranslations {
  layerDialog: { close: string; cancel: string };
  label: { optional: string; moreInformation: string };
}
```

```diff
+ const { label: words } = useKumoLocale();
  …
- children: "(optional)"
+ children: words.optional
  …
- "aria-label": "More information",
+ "aria-label": words.moreInformation,
```

The parentheses belong in the string: some languages write the suffix differently (Arabic "(اختياري)", Japanese "（任意）" with full-width brackets). This is the change Cloudhal applies today; happy to open the PR.


---
title: "Site chrome and overlays: R&D report"
description: "Where we are."
url: https://cloudhal.dev/docs/design/site-chrome-and-overlays
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/site-chrome-and-overlays.md
---
# Site chrome and overlays: R&D report

**What this covers:**
- how site headers and footers should work in Cloudhal as agent-chosen data;
- how the theme core should provide overlays (modal, drawer, popover, tooltip, lightbox, toast, announcement and consent bars);
- how agents should use them.

Collected 2026-10-16 from an audit of the repository and two web research tracks. It is the groundwork for RFC-0025 (to be written; the directions below are decided) and the companion of RFC-0024 (motion), which reuses the same runtime and accessibility rules.

**Confidence.** Claims about the platform cite primary sources (MDN, specs, browser vendors, W3C). Builder features are vendor pages and marked as such. Anything unverified is listed under "Caveats".

## Summary
- **Where we are.**
  - The header and footer are hard-coded in the blog theme's `Base.astro`; only the menus are data.
  - There is no logo, call-to-action, sticky header, mobile menu button, announcement bar, social links or consent banner.
  - There are no overlays at all; dropdowns are `<details>` without Esc or outside-click handling.
  - Every site therefore has the same top and bottom, and an agent cannot change them.
- **The platform now does most of the work natively.**
  - `<dialog>` (modal, Esc, inert background) is widely available.
  - The Popover API is Baseline 2024; Invoker Commands (`command`/`commandfor`, which open dialogs and popovers **without JavaScript**) are Baseline since December 2025; CSS anchor positioning is Baseline since January 2026.
  - The rest (`closedby`, `popover="hint"`, `interestfor`, scroll-state queries) are not yet in every engine and need fallbacks.
- **Recommendation.**
  - Model the header and footer as **structured site chrome**: enums for layout and behavior, plus slots for logo, menus, actions and social links. The theme renders them with accessibility built in, the same way RFC-0023 made colors data.
  - Model overlays as **catalog components inside surfaces** (`Dialog`, `Drawer`, `Popover`, `Tooltip`, `Lightbox`), opened by a `Button` action that the renderer maps to Invoker Commands, with a real link as the no-JavaScript fallback.
  - Site-wide overlays (mobile menu, announcement, consent, toasts) belong to the chrome, not to page content.

## Where Cloudhal stands
| Area | Today | Evidence |
|---|---|---|
| Header | Site name as text, primary menu (`<details>` dropdowns, 3 levels), optional search form; not sticky; wraps on phones, no menu button | `starters/blog/src/layouts/Base.astro:46-66`, `components/NavMenu.astro:20-35` |
| Footer | Hard-coded "Built with Cloudhal", footer menu or an RSS link | `Base.astro:78-95` |
| Menus | Accepted model (RFC-0003): menus by key, nested items, page/entry/term/collection/url/group; MCP `list/get/set/update/delete_menu` (approval); Studio Navigation | `docs/rfcs/0003-navigation.md`, `mcp-server/src/menu-tools.ts` |
| Site data | `name`, theme, design rules; **no logo, social links or chrome settings** | `core-contracts/schemas/site.schema.json` |
| Overlays | None. A2UI `Modal` imports as a `Disclosure` | RFC-0020 :333 |
| Runtime | `surface.7.js`: actions `set`, `toggle`, `navigate`, `scrollTo` …; no dialog or popover handling | `astro-renderer/src/surface-client.ts` |
| CSP | `script-src 'self'`; `style-src 'self' 'unsafe-inline'` | `astro-renderer/src/csp.ts:12` |

## The platform in October 2026
| Feature | Status | What we use it for | Fallback |
|---|---|---|---|
| `<dialog>` + `showModal()` | Baseline widely available | modal, drawer, lightbox, mobile menu | none needed |
| `closedby="any"` | Chrome 134, Firefox 141; **not Safari** | close on backdrop click | runtime closes on backdrop click |
| Popover API (`auto`, `manual`) | Baseline 2024 | dropdowns, mega menus, footnotes, toasts | `<details>` for menus |
| `popover="hint"` | Chrome, Firefox; **not Safari** | tooltips | treated as `manual`; the runtime opens it on focus and hover |
| Invoker Commands (`command`, `commandfor`) | Baseline 2025 (Chrome 135, Firefox 144, Safari 26.2) | "this button opens that overlay", no JavaScript | also emit `popovertarget` (Baseline 2024) for popovers; dialogs fall back to a real link |
| Interest Invokers (`interestfor`) | Chrome 142 only | hover and focus tooltips | runtime (focus and hover), never the only way in |
| CSS anchor positioning | Baseline newly available (January 2026) | popover and tooltip placement | centered popover or `position-try` fallback |
| `@starting-style` + `allow-discrete` | Baseline 2024 | enter and exit animations (RFC-0024 levels) | no animation |
| `overlay` property | Chrome only | exit animation in the top layer | exit is cut, works anyway |
| `<details name>` | all engines | exclusive accordions, menus without JavaScript | none needed |
| `scroll-state()` queries | Chrome only | "stuck" header style, hide on scroll | small script, or a plain sticky header |

**Accessibility rules that shape the design:**
- **Site navigation is a disclosure pattern, never `role=menu`.** Use buttons with `aria-expanded`; Esc closes the open item and focus returns to its button (WAI-ARIA APG disclosure navigation).
- **A drawer is a modal dialog at the edge** of the screen.
- **Landmarks:** one `header`, labelled `nav`s (Primary, Footer), one `main`, one `footer`, and a skip link first.
- **Sticky headers and non-modal banners must not cover the focused element** (WCAG 2.4.11), which `scroll-padding-top` and `scroll-padding-bottom` solve.
- **Toasts** need a live region that is already in the page. Errors and toasts with actions do not dismiss themselves.

## Header
### Model
Site-wide, in a new `Site.chrome.header` object (a contract change, RFC needed). Every field is an enum or a reference:

```jsonc
{
  "layout": "logo-left" | "logo-left-nav-center" | "centered" | "split" | "minimal",
  "behavior": "static" | "sticky" | "hide-on-scroll" | "fixed",
  "shrink": false,
  "overHero": "solid" | "transparent",          // transparent only over a band with a dark or loud surface
  "width": "content" | "wide" | "full",
  "surface": "plain" | "muted" | "raised" | "inverse" | "brand",   // RFC-0023 surfaces
  "mobile": { "collapseAt": "sm" | "md" | "lg" | "always", "style": "dropdown" | "drawer-start" | "drawer-end" | "fullscreen" },
  "logo": { "asset": "asset:…", "assetDark": "asset:…", "alt": "…", "height": "s" | "m" | "l" },  // name as text when absent
  "nav": "primary",                              // a menu key (RFC-0003)
  "utility": "utility",                          // optional second menu, shown small, above or right
  "actions": [                                   // at most 3
    { "kind": "button", "label": "Start free", "href": "/signup", "variant": "primary" | "secondary" },
    { "kind": "search" }, { "kind": "locale" }, { "kind": "theme-toggle" }, { "kind": "motion-toggle" }
  ]
}
```

- **Menus stay where they are.** The header refers to a menu key; it does not copy items. Menu items gain an optional `mega` kind later, with columns of links and an optional featured card. That is an RFC-0003 amendment.
- **Logo and social links** go in a new `Site.brand { logo, logoDark, mark, social[] }`, so the header, footer, SEO (`Organization` JSON-LD) and Studio share them.
- **Per-page override.** `Page.chrome { header: "default" | "transparent" | "hidden", footer: "default" | "minimal" | "hidden" }` covers landing pages and checkout-like flows.

### Rendering, CSS first
- **Always emitted:**
  - a skip link to `#main`;
  - `<header>`;
  - `<nav aria-label>`, labelled from the menu name;
  - disclosure buttons for groups (the parent link stays a real link next to its toggle);
  - `html { scroll-padding-top: var(--ch-header-h) }` for sticky and fixed headers;
  - a reserved header height so nothing shifts.
- **Desktop submenus and mega menus:** a `popover="auto"` panel opened by its button, placed with anchor positioning. Esc and outside clicks close it natively. Without JavaScript or popover support, the same markup works as `<details name="nav">`.
- **Mobile menu:** a modal `<dialog>` (drawer or fullscreen) opened by `<button command="show-modal">`, or a disclosure dropdown. Without Invoker Commands the button is a link to `/menu`, a server-rendered page of the same menu, so the site always works without JavaScript.
- **Behaviors:**

  | Behavior | Rendering |
  |---|---|
  | `sticky` | `position: sticky`; the "stuck" shadow or solid background uses `scroll-state(stuck: top)` inside `@supports` (Chrome), and stays solid elsewhere |
  | `hide-on-scroll` | a few lines in the motion module set `data-ch-scroll-dir` on `<html>`; CSS translates the header. Disabled at motion `none` and under reduced motion: a plain sticky header |
  | `shrink` | `transform` and padding through custom properties, never height on the layout box |
  | `transparent` over a hero | allowed only when the first band's surface is `inverse`, `brand`, `gradient`, `accent`, or an image with a scrim. The header text then takes that surface's text role, so contrast is guaranteed, and `render_page` checks it |

### How agents should use it
- **Most sites:** `logo-left` with `sticky` and one primary button. Landing pages: `transparent` over a loud hero. Editorial: `centered` or `split` with a utility bar.
- **Keep it short:** at most 7 top-level items and at most 1 primary button. `mobile.style` follows the item count: fewer than 5 items → `dropdown`; otherwise `drawer-end`.
- **Never** place the newsletter, cookie notice or chat in the header.

## Footer
### Model
`Site.chrome.footer`:

```jsonc
{
  "layout": "simple" | "columns" | "columns-newsletter" | "cta-band" | "minimal",
  "surface": "plain" | "muted" | "inverse",
  "tagline": "…",
  "columns": [ { "heading": "Product", "menu": "footer-product" } ],   // up to 5, each a <nav aria-label>
  "cta": { "heading": "…", "button": { "label": "…", "href": "…" } },  // for cta-band
  "newsletter": { "heading": "…", "form": "newsletter" },             // needs the reader-actions RFC (G11)
  "social": true,                                                      // from Site.brand.social, icons with labels
  "legal": { "copyright": "© {year} {site}", "menu": "legal" },
  "extras": ["locale", "theme-toggle", "motion-toggle"],
  "credit": true                                                       // "Built with Cloudhal", owner can turn it off
}
```

- **Rendering.** Each column is a labelled `nav`. Social links are icon links with visible or `aria-label` names (an icon set from RFC-0024's companion work, G7). `{year}` and `{site}` are the only placeholders, filled by the renderer.
- **Pause control.** When the page needs one (RFC-0024 §1), the footer is where the "Pause motion" button lives.
- **How agents should use it:**
  - `columns` with 2–4 menus for sites with many pages;
  - `simple` for small sites;
  - `cta-band` for landing pages (it replaces a last CTA band in the page, so agents should not build both).

## Announcement and consent bars
- **Announcement:** `Site.chrome.announcement { text, link, tone, dismissible, id }`.
  - Rendered on the server above the header, never injected, so there is no layout shift.
  - A dismissal sets a first-party cookie `ch_dismiss=<id>`, so the server leaves the bar out next time. A versioned `id` brings it back when the text changes.
- **Consent:** `Site.chrome.consent { mode: "none" | "notice" | "choices", policy: "/privacy" }`.
  - A non-modal bottom bar (`popover="manual"`) with `scroll-padding-bottom` while it is open (WCAG 2.4.11), or a modal `<dialog>` for `choices`.
  - The choice is stored in a first-party cookie.
  - Cloudhal's own analytics (RFC-0006) is cookieless, so most sites need `none` or `notice`. This is a legal decision per site, so agents propose it and a person sets it (approval).

## Overlays in the theme core
### Primitives
New catalog components. Their content is their children, so it is built, checked and streamed like any surface content. They render outside the flow, in the top layer.

| Component | Props | Native element | No-JS / missing-feature fallback |
|---|---|---|---|
| `Dialog` | `title` (required, accessible name), `size` (sm/md/lg/full), `dismiss` (`any`/`closerequest`/`explicit`), `fallbackHref` | `<dialog>` + `showModal()` via `command="show-modal"`; `closedby` | trigger is a link to `fallbackHref`; backdrop close by the runtime in Safari |
| `Drawer` | `title`, `placement` (start/end/bottom), `size` | modal `<dialog>` at the edge | as `Dialog` |
| `Popover` | `placement` (block-end/block-start/inline-end/inline-start), `width` | `popover="auto"` + `popovertarget`/`toggle-popover`, anchor-positioned on its trigger | centered popover; footnote-style popovers also link to an `#id` in the page |
| `Tooltip` | `text` (≤ 160 characters, no interactive content) | `popover="hint"` + `interestfor` | runtime opens it on focus and hover; Esc closes it; never the only way to get the information |
| `Lightbox` | `items` (assets or videos with alt), `start` | modal `<dialog>` with `--next`/`--prev` commands handled by the runtime | thumbnails link to the full image or video |

- **Opening.** A `Button` gets a new action, `onClick: { action: "open", target: "<component id>" }`, plus `close` for buttons inside an overlay.
  - The renderer maps it to `command` and `commandfor` (and `popovertarget` for popovers), sets `aria-controls`, and keeps `href` as the fallback.
  - The store checks that the target exists in the same surface and is an overlay component.
- **The runtime's part** (a small addition to the interaction runtime or the motion module):
  - return focus to the trigger on close where the browser does not;
  - close on backdrop click where `closedby` is missing;
  - set `aria-expanded` on triggers;
  - lightbox navigation;
  - open tooltips on focus and hover in Safari.
- **Scroll lock:** `html:has(dialog:modal) { overflow: hidden; scrollbar-gutter: stable }` in CSS. Overlays get `overscroll-behavior: contain`.
- **Motion:** enter and exit with `@starting-style` and `allow-discrete`, scoped to RFC-0024's levels (fade at `subtle`, slide and scale at `standard` and above, none under reduced motion).
- **A2UI interop:** `Modal` now maps to `Dialog` instead of `Disclosure`.

### How agents should use overlays
- **Prefer the page.** Content people need to read or link to belongs on a page, not in a dialog. Overlays are for short, optional detail: terms in a sign-up flow, a video, an image gallery, a definition, filters.
- **Choosing a kind:**
  - `Dialog` for a focused task or a short read;
  - `Drawer` for a list beside the page (filters, cart, table of contents);
  - `Popover` for a small panel tied to a button;
  - `Tooltip` for a few words of explanation;
  - `Lightbox` for media.
- **Never open an overlay on page load, on a timer or on exit intent.** Newsletter and promotion pop-ups are not available. This is a rule the store enforces: overlays open only from a user action.
- Every `Dialog` and `Drawer` has a title and a visible close button (the renderer adds it). Popovers and tooltips never hold forms.

## Agents, MCP and CLI
- **MCP tools:**
  - `get_chrome` (read) returns the header, footer, announcement and consent settings with their allowed values;
  - `set_chrome` changes them, with a person's approval like `set_theme_settings`;
  - `get_design` summarizes them;
  - `set_brand` sets the logo and social links (approval).
  - Menus keep their own tools.
- **Catalog and checks.** `catalogPrompt` teaches the overlay components and the `open` action. Checks:
  - every `open` target resolves;
  - overlays have titles;
  - tooltips hold no interactive content;
  - at most 3 overlays per surface.
- **`render_page` checks:**
  - `skip-link`;
  - `landmarks`;
  - `focus-obscured` (focus every link while scrolling and check the sticky header and bars do not cover it);
  - `header-contrast` (transparent headers);
  - `overlay-open`: open each overlay through its trigger and check focus moves in, Esc closes it, focus returns and its contrast passes. The screenshots include each open overlay.
- **CLI:**
  - `cloudhal chrome get` / `cloudhal chrome set --file chrome.json`;
  - `cloudhal render` (from RFC-0024) also renders the mobile menu open with `--open-menu`.
- **Studio:** a "Header and footer" section in Site settings (layout, behavior, mobile style, actions, footer columns, announcement), next to Navigation. The site-design skill gains chrome recipes per kind of site.

## Proposed phases (for RFC-0025)
| Phase | Scope |
|---|---|
| 25a | `Site.brand` and `Site.chrome.header`/`footer` (contract), the theme's header and footer from data (layouts, sticky, logo, actions, columns, social, legal, credit), skip link and landmarks, `get_chrome`/`set_chrome`, Studio section |
| 25b | Mobile menu (drawer, fullscreen, dropdown, `/menu` fallback), popover submenus with anchor positioning, `hide-on-scroll`, `shrink`, transparent over hero with the contrast rule |
| 25c | Overlay components (`Dialog`, `Drawer`, `Popover`, `Tooltip`, `Lightbox`), the `open`/`close` actions, the runtime additions, the overlay checks |
| 25d | Announcement and consent bars, toasts, `Page.chrome` overrides, `mega` menu items (RFC-0003 amendment) |

## Decisions (formerly open questions)
These were decided on 2026-10-16 for RFC-0025, with the same test as RFC-0024: what serves developers, agent users and readers best.

1. **Invoker Commands: a tiny first-party shim plus the link fallback.**
   - The runtime carries a shim of about 30 lines for the three built-ins we use (`show-modal`, `close`, `toggle-popover`). It loads only on pages with overlays, and only when `HTMLButtonElement.prototype.commandForElement` is missing.
   - `fallbackHref` stays for readers without JavaScript.
   - Readers on older browsers keep the experience, and no third-party script is needed.
2. **Safari: ship now with runtime fallbacks.** Backdrop-click closing (in place of `closedby`) and focus/hover tooltips (in place of `popover="hint"` and `interestfor`) are small runtime additions. They are removed once Safari ships the features.
3. **Hide on scroll: a small script by default, CSS where available.**
   - The motion module sets `data-ch-scroll-dir`. On Chrome, `scroll-state(scrolled)` does the same without script.
   - It is off under reduced motion and at motion `none`, so the header is then simply sticky.
4. **Footer freedom: yes, one optional surface region.**
   - `footer.region` holds a surface, built and checked like any surface content (for example a sign-up card or a map), rendered above the columns.
   - The structured parts (landmarks, legal row, social links) stay guaranteed.
   - The header gets no free region: its accessibility (focus, disclosure, height) depends on staying structured.
5. **Consent: `none` by default, with `notice` suggested when needed.**
   - Cloudhal's analytics is cookieless, so most sites need nothing.
   - When a site uses third-party embeds (video, maps), `get_design` and `render_page` suggest `notice` or `choices`. A person sets it (approval), since it is a legal choice.
   - Default texts ship in English and Turkish, written by the theme, editable by the owner.

## Caveats
- **Firefox:** there are reports that it still does not animate `display` for top-layer exits; the exit animation is cosmetic, so overlays work anyway.
- **iOS Safari:** there are reports that `overflow: hidden` on `<html>` does not fully stop background scrolling. The fallback is `overscroll-behavior` plus the dialog's own inertness.
- **Builder catalogs:** the Tailwind Plus category counts come from a page behind a login, and the Framer "scroll variants" details are from third-party summaries.

## Sources
- **Platform (MDN):**
  - Dialog: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog
  - `closedby`: https://caniuse.com/mdn-html_elements_dialog_closedby
  - Popover API: https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using
  - `popover="hint"`: https://caniuse.com/mdn-html_global_attributes_popover_hint
  - Invoker Commands: https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API
  - `overlay`: https://developer.mozilla.org/en-US/docs/Web/CSS/overlay
  - `scroll-padding-top`: https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top
  - `overscroll-behavior`: https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior
- **Platform (vendors):**
  - Invoker Commands, Baseline December 2025: https://web.dev/blog/web-platform-12-2025
  - Anchor positioning, Baseline January 2026: https://web.dev/blog/web-platform-01-2026
  - Interest Invokers (Chrome 142): https://developer.chrome.com/release-notes/142
  - Scroll-state queries: https://developer.chrome.com/blog/css-scroll-state-queries
  - Exclusive accordions: https://developer.chrome.com/docs/css-ui/exclusive-accordion
  - Interop 2026: https://webkit.org/blog/17818/announcing-interop-2026/
  - CSS for Web Vitals: https://web.dev/articles/css-web-vitals
- **Accessibility:**
  - Disclosure navigation: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
  - Modal dialog: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
  - Landmarks: https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
  - Focus Not Obscured: https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured
  - Link + disclosure navigation: https://adrianroselli.com/2019/06/link-disclosure-widget-navigation.html
  - Toasts: https://adrianroselli.com/2020/01/defining-toast-messages.html
- **Builders (vendor pages):**
  - Wix header scroll effects: https://support.wix.com/en/article/studio-editor-adding-header-scroll-effects
  - Webflow menu button: https://help.webflow.com/article/menu-button
  - Squarespace transparent header: https://www.bigcatcreative.com/blog/transparent-header-menu-squarespace
  - Tailwind Plus blocks: https://tailwindcss.com/plus/ui-blocks
  - Relume components: https://www.relume.ai/components


---
title: "Starter themes: references and gaps"
description: "Research for strengthening starters/blog (and a possible newsroom starter) before the first public demo. Collected 2026-10-15. Visitor-facing sites use the theme system, not Kumo; DESIGN.md does not apply here."
url: https://cloudhal.dev/docs/design/starter-references
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/design/starter-references.md
---
# Starter themes: references and gaps

Research for strengthening `starters/blog` (and a possible newsroom starter) before the first public demo. Collected 2026-10-15. Visitor-facing sites use the theme system, not Kumo; DESIGN.md does not apply here.

Constraints every idea below respects: sites ship **no client JavaScript** except Cloudhal's first-party scripts (analytics, comments, the video player), the CSP is `script-src 'self'`, and everything a theme shows comes from the graph through `@cloudhal/astro-renderer`.

## 1. What competing themes ship

| Feature | Ghost Source | Ghost Headline | Ghost Casper | Newspack | AstroPaper | Fuwari | Substack / Beehiiv | **Cloudhal blog today** |
|---|---|---|---|---|---|---|---|---|
| Homepage lead / hero | 4 header styles (Landing, Highlight, Magazine, Search) | "Latest" grid of 7 | publication cover | Homepage Posts blocks | intro + featured + recent | banner | Feature / Magazine / Newspaper | hero text + title list |
| Topic sections on home | – | primary grid + secondary lists by tag | – | blocks filtered by category/tag | – | – | by section | `contentList` with `filter` (titles only) |
| List ↔ grid feed | setting | – | Classic / Grid / List | per block | – | – | list / grid | list only |
| Kicker (primary category) | yes | yes | yes | yes | – | yes | – | breadcrumb only |
| Dek / subtitle | excerpt | excerpt | excerpt | subtitle | description | – | – | `summary` |
| Byline + avatar | yes | yes | yes | + author bios | – | – | co-authors | **no** (JSON-LD only) |
| Reading time | yes | – | yes | – | – | – | – | **no** |
| Cover image caption | yes | – | yes | – | – | – | – | caption from asset |
| Table of contents | – | – | – | – | yes | yes | – | **no** (headings have no ids) |
| Related / more | 4 | yes | 3 | prev/next | prev/next | – | – | yes (`RELATED_POSTS`) |
| Newsletter CTA | yes | yes | yes | plugin | – | – | core | **no** |
| Tag / author archives | yes / yes | yes / yes | yes / yes | yes | tags + years | tags + categories | archive page | categories + tags / **no authors** |
| Search | built in | yes | yes | yes | Pagefind (JS) | Pagefind (JS) | – | **no** |
| Dark mode | – | – | Light / Dark / Auto | – | toggle (JS) | toggle (JS) | – | **no** |
| Generated OG images | – | – | – | – | yes | – | – | **no** |
| Article JSON-LD + `article:*` | ghost_head | ghost_head | ghost_head | Yoast | yes | – | – | **yes** (Article, author, section, keywords, breadcrumbs) |
| Corrections log | – | – | – | yes | – | – | – | **no** (snapshots exist) |
| RSS / sitemap | core | core | core | core | yes | yes | yes | **yes** (+ per term feeds) |

Sources: Ghost [Source](https://github.com/TryGhost/Source), [Headline](https://github.com/TryGhost/Headline), [Casper](https://github.com/TryGhost/Casper) (templates and `package.json` custom settings), [Ghost custom settings](https://docs.ghost.org/themes/custom-settings/), [Newspack posts](https://help.newspack.com/themes/posts), [Newspack corrections](https://help.newspack.com/?p=15444), [AstroPaper](https://github.com/satnaing/astro-paper), [Fuwari](https://github.com/saicaca/fuwari), [Substack homepage layouts](https://pubstacksuccess.substack.com/p/new-layouts-yay-for-homepages-on), [Beehiiv pages](https://www.beehiiv.com/support/article/33699539470615-using-pages-in-the-website-builder).

## 2. Homepage patterns

**Blog**
- Intro hero (with a signup) then the list — Ghost Source "Landing", Casper.
- One featured post, then a list or grid — Substack "Feature", AstroPaper.
- Card grid with images — Casper Grid, Source `post_feed_style`.

**Newsroom**
- **Lead + rails:** one large lead story, 3 secondary stories beside it, then more (Source "Highlight", "Magazine"; Substack "Newspaper").
- **Topic sections:** a grid per primary topic, compact text lists for secondary topics (Headline).
- **Latest river** with read times, paginated rather than "load more" ([Rest of World](https://restofworld.org/)).
- **Section modules:** one featured card plus 2–3 text links per series or region ([ProPublica](https://www.propublica.org/), [The Markup](https://themarkup.org/)).

## 3. Article anatomy (consensus order)

1. Kicker (primary category, linked)
2. Title
3. Dek (summary)
4. Byline: author, published date, "Updated" date when it differs, reading time — dates must match the structured data ([Google: byline dates](https://developers.google.com/search/docs/appearance/publication-dates))
5. Cover image with caption and credit
6. Table of contents for long pieces
7. Body
8. Corrections / updates note
9. Tags, share links
10. Author card
11. Newsletter CTA
12. Comments
13. Related posts

## 4. Settings competitors expose

Ghost allows at most 20 settings (select, boolean, color, image, text) grouped as site-wide, homepage and post, and recommends settings with a visible effect.
- **Source:** navigation layout (logo left/middle/stacked), background, header/footer color, title font, body font, homepage `header_style`, feed list/grid, feed images/author/date toggles, drop caps, related articles.
- **Headline:** header style (light/accent/dark), fonts, signup text, homepage primary/secondary tag slugs.
- **Casper:** navigation layout, fonts, cover, feed layout (Classic/Grid/List), color scheme (Light/Dark/Auto), post image style (Wide/Full/Small/Hidden).

Cloudhal's `src/settings.ts` already holds brand, link, background, text, typeface and corners (RFC-0017 7a), so these map onto the same mechanism.

## 5. Priorities for Cloudhal

Grouped by where the work lands.

**Theme only (`starters/*`, no contract or renderer change)**
1. Wider, responsive layout: reading column for articles, wide grid for home and archives; skip link; real header and footer.
2. Homepage layout setting: `list`, `grid`, `lead` (lead + rails) — a `contentList` override in `theme.ts` with cover images, kicker, date.
3. Article header: kicker, dek, byline (author name, published, updated, reading time).
4. Color scheme setting: Light / Dark / Auto through `prefers-color-scheme` (no toggle, no JS).
5. Title and body typeface settings, header style setting.
6. Archive cards with images and dates; first item larger on newsroom layouts.

**Renderer (`@cloudhal/astro-renderer`, additive)**
7. Heading ids in rendered markdown, so themes can build a table of contents with no JS.
8. A reading-time helper next to `entryArticleParts`.
9. Author archives (`/author/<id>`) and author cards — needs an author profile source first.
10. Server-rendered search (`/search?q=`) on the Site Worker; Pagefind is out (needs JS and `wasm-unsafe-eval`).
11. Generated OG images per entry.

**Contract / RFC**
12. Corrections and updates log per entry — fits snapshots and diffs; needs fields and a rendering rule.
13. Newsletter signup — builds on email delivery (ADR-0025).
14. Live updates entries (`LiveBlogPosting`) — verify Google's current guidance first.

Already ahead of most competitors: Article JSON-LD with section, keywords and breadcrumbs; per-term RSS; redirects and 410s; typed blocks; first-party comments; cache-tag purges.

## 6. Local development note

Tailwind v4 detects sources automatically from the project. For a project inside a git-ignored folder of another repository (`examples/` here), the scanner walked up the file system and the first CSS request never finished. The starter therefore names its sources: `@import "tailwindcss" source("..");` in `src/styles/global.css` (the path is relative to that file, so the import stays there; the rules live in `src/styles/features/`).


---
title: "Code structure and size rules"
description: "Status: binding for new code from 2026-10-17. Enforced by pnpm size:check (part of pnpm check and CI), Biome complexity warnings and the clippy lints in Cargo.toml."
url: https://cloudhal.dev/docs/engineering/code-structure
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/engineering/code-structure.md
---
# Code structure and size rules

Status: binding for new code from 2026-10-17. Enforced by `pnpm size:check` (part of `pnpm check`
and CI), Biome complexity warnings and the clippy lints in `Cargo.toml`. Data behind the numbers:
an internal code-size review (2026-10).

Cloudhal is written by humans and coding agents together. Both lose the thread in a 3 000-line
file: an agent reads it in slices and edits the wrong copy of a helper, a reviewer cannot see what a
diff touches, two parallel sessions conflict on the same file every day. Small modules with one job
are the cheapest way to keep parallel work safe. These rules say how small, and how we get there
without a big-bang refactor.

## 1. What mature projects use

| Source | File | Function | Params | Nesting | Complexity |
| --- | --- | --- | --- | --- | --- |
| ESLint core defaults (`max-lines`, `max-lines-per-function`, `max-params`, `max-depth`, `complexity`) | 300 | 50 | 3 | 4 | 20 (cyclomatic) |
| Biome 2.5 defaults (`noExcessiveLinesPerFile`, `noExcessiveLinesPerFunction`, `useMaxParams`, `noExcessiveCognitiveComplexity`) | 300 | 50 | 4 | — | 15 (cognitive) |
| Airbnb JS style | no file/function cap; `max-len` 100 | — | — | — | off |
| Google TypeScript style | no numeric caps; "one concept per file", named exports, no default exports | — | — | — | — |
| Clippy (`too_many_lines` pedantic, `too_many_arguments`, `cognitive_complexity`, `excessive_nesting`) | — | 100 | 7 | off by default | 25 (cognitive) |
| SonarSource cognitive complexity | — | — | 7 | — | 15 |
| McCabe (1976) | — | — | — | — | 10 |

Two lessons: tools ship tight defaults (300/50) that real codebases switch off because they are
noisy, and style guides that do not cap size (Google, Airbnb) rely on review instead. A rule only
helps if it is loud enough to fire on a real problem and quiet enough that nobody disables it. So
Cloudhal sets **soft limits** near the tool defaults (review guidance, editor warnings) and **hard
limits** about twice as high (CI fails), and freezes today's oversized code in a baseline that may
only shrink.

## 2. The numbers

Physical lines, comments and blanks included (what you scroll through).

| Measure | Soft (warn, review) | Hard (CI fails) | Enforced by |
| --- | ---: | ---: | --- |
| `.ts`/`.tsx`/`.js` file | 400 | 800 | `size:check`; Biome `noExcessiveLinesPerFile` warns at 800 |
| `.astro` component | 250 | 500 | `size:check` |
| `.css` file | 400 | 800 | `size:check` |
| `.rs` file (inline `#[cfg(test)]` modules) | 500 | 1000 | `size:check` |
| Test file (`*.test.ts`, `test/`, `testing*.ts`, `fixtures.ts`) | 800 | 1500 | `size:check` |
| Function / method / component body | 80 | 150 | `size:check`; Biome `noExcessiveLinesPerFunction` 150; clippy `too_many_lines` 150 |
| Nesting depth (if/for/while/switch/try; `else if` does not nest) | 4 | 5 | `size:check`; clippy `excessive_nesting` 5 |
| Positional parameters | 3 | 4 | `size:check`; Biome `useMaxParams` 4; clippy `too_many_arguments` 5 |
| Cognitive complexity (Biome/Sonar) | 15 | 25 (warning) | Biome `noExcessiveCognitiveComplexity` 25; clippy `cognitive_complexity` 25 |
| One string literal / template (client code, SQL, help text) | 6 000 chars | 12 000 chars | `size:check` |
| Translation dictionary (`apps/studio/src/i18n/<locale>.ts`, `i18n/lazy/*`; one per registered language) | — | no line limit | Studio bundle budget (§8) |

Why these values:

- **400 / 800 lines.** Today 125 of ~670 TypeScript source files are over 400 and 41 over 800; the median
  module is ~150. 400 lines is roughly what one person (or one agent read) holds at once; at 800 a
  file nearly always mixes two jobs (§4). Higher for Rust because its tests live in the same file.
- **80 / 150 lines per function.** ESLint's 50 fires on every React component with a JSX tree; 80
  is a component with its hooks and markup on two screens. 143 functions are over 150 today; none of
  them is a single job.
- **3 / 4 parameters.** From four on, call sites become `fn(a, b, undefined, true)`. Beyond three,
  take one options object (`{ siteId, rev, by }`) — named, order-free and extensible without a
  breaking change. Hard limit 4 so that a fourth positional is a reviewed exception.
- **Depth 4 / 5.** Deeper code is easier to read as an early return, a helper or a lookup table.
  Only 18 functions reach depth 5 today, 2 reach 6.
- **Complexity** is only a warning: cognitive complexity flags real tangles (`primitiveHtml` has a
  cyclomatic complexity of 171) but also long, flat `switch` dispatchers that are fine to read. The
  fix for both is in §5.

Functions inside test files are exempt from the function limits: `describe`/`it` bodies are lists
of cases. Test files still have a file cap; split suites by behaviour (`store.publish.test.ts`,
`store.rollback.test.ts`), as `testing-*.ts` already does.

Generated and vendored code is never measured: `packages/core-contracts/src/generated`,
`crates/cloudhal-schema/src/generated`, `packages/core-ts/src/generated`,
`packages/ui/src/blocks/kumo`, `dist`, `node_modules`, `*.d.ts`, tool configs.

## 3. The ratchet

`scripts/size-baseline.json` lists every file, function and string that was over a hard limit on
2026-10-17 (40 files, 201 functions, 1 string), with its size then.

- A **new** file, function or string over a hard limit fails `pnpm size:check`.
- A **baselined** one may not grow. Changing it is fine; adding lines means moving at least as many
  lines out (to a new module) in the same change.
- When a refactor shrinks a baselined entry, run `node scripts/size-check.ts --update`. It only
  ever lowers numbers or drops entries, so it is always safe; `size:check` reminds you when the
  baseline is looser than the code.
- A genuine exception (rare: a generated-looking table, a vendored script) is
  `node scripts/size-check.ts --update --allow-growth`; the baseline diff makes it visible in review,
  and the PR says why.

Function baseline keys are `file::Outer>inner` names (anonymous callbacks are named after their
call, e.g. `createApi>app.get("/sites")(cb)`). Renaming a baselined function makes it "new"; split
it instead.

`pnpm size:report` prints the full tables (per package, functions, strings, switches, churn risk);
the analysis report is its output plus the split plans.

## 4. One responsibility per module

A module does one of these, and its name says which:

| Kind | Contains | Imports allowed | Examples |
| --- | --- | --- | --- |
| **Model / pure logic** | types, validation, transforms, decisions; no IO, no clock, no `fetch` | other pure modules, contracts | `surfaces/checks/*`, `schedules/recurrence`, `design` lint |
| **Store / IO adapter** | SQL, blob, HTTP, Browser Rendering, `fetch`; translates rows ↔ model | model, `@cloudhal/storage` | `sql/store.ts`, `render-chrome.ts` |
| **Service / orchestration** | one use case composed from model + IO (publish, build turn, deploy) | model, IO | `build-turn.ts`, `commands/deploy/*` |
| **Transport** | Hono routes, MCP tool tables, CLI commands: parse input, call a service, map errors | service, model | `routes/*`, `tools/*` |
| **Rendering** | HTML/Astro/React output from a model; no data fetching | model | `render/primitives/*`, Studio sections |
| **Runtime client code** | browser code shipped as a string (§7) | none at runtime | `*-client.ts` |

Signals that a file needs splitting: it has two of the rows above; its tests need two unrelated
setups; two sessions edit it for unrelated reasons in the same week (see churn in the report).

### Folders and stable public paths

When a file grows past the soft limit, move its parts into a folder with the same name and keep
the original file as the barrel. Importers, `package.json` `exports` (source and `publishConfig`)
and tests do not change:

```text
packages/core-ts/src/surfaces.ts      // barrel: the old public API, named re-exports only
packages/core-ts/src/surfaces/
  shared.ts                           // limits, tiny guards
  catalog/                            // primitive definitions, createCatalog
  bindings/                           // values, the function table, resolve
  checks/                             // checkSurface orchestrator + rule tables
  patch/                              // JSON Patch, patchPage
  prompt.ts                           // catalogPrompt
```

- Barrels only re-export, by name (`export { checkSurface } from "./surfaces/checks/index.ts";`);
  no logic, no side effects, so internal helpers do not leak into the public API. Inside a package
  import the concrete module, not the barrel, to avoid cycles.
- A new area that starts as a folder uses `index.ts` as its barrel.
- Prefer explicit named re-exports over `export *` in package entry points, so the public API is a
  list someone can read (`@cloudhal/ui`'s `export * from "@cloudflare/kumo"` is the documented
  exception).
- Worker-safety (AGENTS.md rule 5) is per module: a split must not pull a Node-only import into a
  barrel that a Worker reaches. Put Node-only parts behind their own subpath (`./node`).

Per-package conventions:

- `packages/core-ts`: one folder per domain area (`surfaces/`, `taxonomy/`, `menu/`, `assets/`),
  with `model.ts`, `checks.ts`, `sql.ts`/`store.ts`, `index.ts`. `store.ts` (`SiteGraphStore`)
  is a facade: method bodies live in per-area engines (`store/entries.ts`, `store/snapshots.ts`,
  `store/publish.ts`), like the existing `AssetEngine`/`TaxonomyEngine`/`MenuEngine`, sharing one
  `StoreContext`. The facade itself is a documented exception to the soft limit while its public
  method list stays flat.
- `packages/api`: `routes/<area>/index.ts` builds a Hono sub-app; handlers live next to it
  (`routes/<area>/<verb>.ts` once the area passes 400 lines); `app.route("/<area>", …)` mounts it.
- `packages/mcp-server`: one `tools/<area>.ts` per tool family, each exporting a tool table; the
  server registers tables, it does not define tools.
- `packages/cli`: `commands/<name>/` per command with a `{ name, help, run }` table in `cli.ts`.
- `packages/astro-renderer`: `surfaces/render/<primitive>.ts` renderers keyed in a table.
- `apps/studio`: see §8.
- `starters/blog`: `src/styles/features/<feature>.css` per feature, imported by `global.css` (§8).

## 5. Dispatch tables, not giant switches

A `switch` that maps a name to a behaviour (primitive → HTML, command → handler, function name →
implementation, A2UI kind → surface node) becomes a typed table:

```ts
type PrimitiveRenderer<K extends PrimitiveName> = (node: PrimitiveNode<K>, ctx: RenderContext) => string;

export const PRIMITIVE_RENDERERS: { [K in PrimitiveName]: PrimitiveRenderer<K> } = {
  Text: renderText,
  Image: renderImage,
  // …
};

export const primitiveHtml = (node: PrimitiveNode, ctx: RenderContext) =>
  (PRIMITIVE_RENDERERS[node.kind] as PrimitiveRenderer<typeof node.kind>)(node, ctx);
```

- The mapped type makes a missing entry a type error (the exhaustiveness a `switch` +
  `assertNever` gave).
- Each renderer is a small function in its own module, testable alone; adding a primitive touches
  one new file and one table line.
- Keep a `switch` for a handful of cases that share local state. Rule of thumb: more than ~10
  cases, or cases longer than ~10 lines each, is a table.

## 6. Naming, exports, comments, errors

Match what is already in the repo:

- **Files** kebab-case (`build-turn.ts`, `surface-interop.ts`); React components PascalCase
  (`PageEditorPage.tsx`); tests next to the code (`foo.test.ts`) or in `test/`.
- **Exports** named only; default exports only where a framework requires them (Astro/Vite
  configs, Workers' `export default { fetch }`). Export what other modules use, nothing for tests
  only — test through the public function or move the helper to its own module.
- **Comments** as the repo writes them: a module doc comment saying what the module is for, which
  RFC/ADR it implements and any non-obvious constraint (Worker-safety, versioned assets); short
  `/** … */` on exported API whose name is not enough; inline comments only for *why*. No
  commented-out code, no banners.
- **Errors**: throw typed errors from `@cloudhal/core-ts` (`ConflictError`, `NotFoundError`, …) in
  model/service code; map them to HTTP/MCP results only in the transport layer
  (`packages/api` error mapping, MCP `invariantHint`). Never swallow an error without a comment
  saying why; never `catch {}` around IO except to translate it.
- **Parameters**: more than three → one options object (§2).

## 7. Runtime client modules (`String.raw` code)

`packages/astro-renderer/src/*-client.ts` ship small browser modules as string constants (served
from `/_cloudhal/`, `script-src 'self'`, no eval). They stay that way, with limits:

- One module per behaviour (`motion`, `carousel`, `overlay`, `surface` …), one exported constant,
  versioned file name, a test pinning the hash (existing practice).
- **Size cap: 12 000 characters per string (hard), 6 000 soft.** `surface-client.ts` is at ~11 000
  and is the first to split (bindings / actions / toasts as separate modules loaded on demand).
- Shared helpers (pointer parsing, toast) live in one `client-shared.ts` constant concatenated by the
  module that needs it, not copied.
- A string over ~30 lines that is *checked code* (e.g. `RENDER_CHECK_SCRIPT` in
  `packages/mcp-server/src/render.ts`, 26 000 chars) should become a real `.js` module under
  `src/client/` read at build time or bundled as text, so Biome and the type checker see it.
- SQL in migrations is data and is exempt in spirit; keep each migration to one feature.

## 8. Studio screens and CSS

Studio (`apps/studio`):

- A route file (`src/routes/*Page.tsx`) is composition only: `PageLayout`, its `SectionCard`s and
  the data hooks. **Soft 250, hard 800 lines** (the file limit); the component function ≤ 150.
- Move each section into `src/components/<page>/<Section>.tsx` and data/mutation logic into
  `src/components/<page>/use<Thing>.ts` hooks (not under `routes/`: design-lint treats every
  `.tsx` there as a route that needs a template). The route file keeps what its template requires
  (`PageLayout`, `crumbs=`, `title=`, and `EditorLayout`/`SectionCard` for editors). Reusable visual
  patterns become a `packages/ui` block (AGENTS.md rule 7).
- Register a split screen's folder in `SCREEN_PARTS` (`apps/studio/test/design-rules.test.ts`): the
  design-rules tests then read the route and its folder as one screen (first done for
  `routes/PageEditorPage.tsx` → `components/page-editor/`).
- Modules imported only by a lazy route stay in its chunk; never import a heavy module from the
  shell (`apps/studio/bundle-budget.ts` `LAZY_ONLY`).
- `src/lib/api.ts` is split per resource (`lib/api/<area>.ts`); `lib/api.ts` stays as the barrel
  (137 files import it by that path).
- i18n dictionaries are data, not code, so they have **no line limit** (a long list of strings is
  not hard to read). What they cost is weight and merge conflicts, and the rules aim at those:
  - only the active language loads: `en.ts` is in the first load (the fallback), every other `<locale>.ts` arrives
    through `loadLocale` (`LAZY_ONLY` keeps it out of the first load);
    `apps/studio/bundle-budget.ts` (`initialGzipBytes`) is the guard, not `size:check`;
  - a new area's strings go in a lazy namespace (`src/i18n/lazy/<ns>.<locale>.ts`, DESIGN.md §1),
    loaded with its route; `en.ts`/`tr.ts` keep what the shell needs on first paint;
  - moving route-specific groups out of the eager files (and loading only the active language) is
    a bundle improvement, done for the user's sake, not to meet a line count.

CSS (`starters/blog`, themes): one file per feature (`styles/features/prose.css`,
`styles/features/surfaces.css`, `styles/features/comments.css` …), imported in cascade order by
`global.css`, which keeps only the Tailwind import (its `source("..")` is relative to that file),
`fonts.css` and the feature imports. CSS needs every `@import` before other rules, so tokens and
`@theme` live in `features/tokens.css`. The features stay unlayered (`layer(...)` would let
utilities beat component classes) and in order: later files override earlier ones at equal
specificity. Same 400/800 limits.

## 9. Workflow

1. Before writing: if the file you are about to change is over the soft limit, put the new code in
   a new module next to it.
2. `pnpm check` runs Biome (errors), `size:check`, typecheck and tests. `pnpm lint` also shows the
   complexity warnings; your editor shows them inline.
3. Refactors of baselined files follow the split plans in the analysis report, one file per PR,
   public import paths unchanged, behaviour unchanged (tests untouched or only moved), then
   `node scripts/size-check.ts --update`.


---
title: "Cloudhal threat model (alpha)"
description: "Cloudhal lets AI agents change websites. The central security promise: an agent can only do what its scopes allow, every change is recorded and reversible, and nothing goes live without a person."
url: https://cloudhal.dev/docs/security/threat-model
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/security/threat-model.md
---
# Cloudhal threat model (alpha)

Cloudhal lets AI agents change websites. The central security promise: **an agent can only do what its scopes allow, every change is recorded and reversible, and nothing goes live without a person.** This page lists who can do what, the controls behind each promise, and the risks we accept for the alpha. Report vulnerabilities as described in [SECURITY.md](https://github.com/cloudhal-dev/cloudhal/blob/main/SECURITY.md).

## Principals
Staff roles are named sets of scopes (RFC-0005, ADR-0018). A person's role is read from their single membership on every request; without one they have no scopes.

| Principal | How it authenticates | Can do |
|---|---|---|
| Owner | Better Auth session cookie (Studio) | Everything (`*`), including transferring ownership; exactly one per deployment |
| Administrator | Session cookie | Every non-wildcard scope: content, structure, publish, rollback, site settings and domains, members (non-Owner), invites up to Administrator, others' agent keys (revoke, end elevations) |
| Editor | Session cookie | Content, pages, taxonomies, redirects, publish, rollback, all Activity; invites Contributors and Authors |
| Author | Session cookie | Own articles in any status; publishes own-only change sets (anything wider becomes a request an Editor decides) |
| Contributor | Session cookie | Own never-published drafts (draft/review); proposes tags; never publishes |
| Agent | API key (`x-api-key` or `Authorization: Bearer`) with explicit scopes | MCP tools only, within its scopes narrowed to its creator's current role; publish/rollback/delete wait for a person |
| Local developer's agent | `cloudhal mcp` over stdio | All scopes on the local project; gated tools ask in the MCP client |
| Automation key | API key (`x-api-key` or `Authorization: Bearer`) minted for one automation by the person who created it (RFC-0008) | An agent key that works only inside its automation's run windows (outside them only `begin_run`, `get_mode` and `pause_automation` answer); narrowed to its owner's current role, capped by the automation's mode cap, never `bypass`; within budgets; read, label and hide only once its run reads visitor-supplied text |
| Scheduler | System actor (`sys_scheduler`) inside the admin Worker or the Node process; no credential | Publishes releases on behalf of the person who approved them, runs built-in jobs, opens and closes run windows (RFC-0008) |
| Operator | Deployment token (bearer) | Export/import whole sites (`cloudhal push/pull`); recover ownership (`cloudhal owner transfer`); export/import reader comments, with commenters' emails (`cloudhal comments export|import --remote`, RFC-0007); read the scheduler's status and run a tick (`cloudhal schedules status|list|run-due --remote`, RFC-0008) |
| Site visitor | — | Published pages; drafts only with a signed preview link; sends analytics beacons, which count only for published pages (RFC-0006); sends comments and reports, which are held for moderation (RFC-0007) |

## Promises and controls
1. **Agents stay inside their scopes, and an agent never exceeds the person whose key it uses.** Agent principals are refused on the REST API (403 everywhere except `/api/me`); MCP calls pass the policy engine (scopes × tool annotations × declared skill). A key's scopes must fit its creator's role when it is minted, and on every call they are narrowed to the creator's *current* role; a key whose creator is no longer a member is refused (401). Key modes and elevations are capped by the role (Contributor: `edits`); only the key's creator grants an elevation. Person-only scopes (`site:settings`, `members:*`, `agents:manage`, `audit:read`, `automations:manage`) never sit on a key. Keys cannot mint keys; permissions are server-only, and Better Auth's own `/api/auth/api-key/*`, `/api/auth/organization/*` and `/api/auth/admin/*` endpoints answer 404. Per-key rate limit 600/min.
2. **Nothing goes live without a person, unless the owner chose otherwise.** Publish, rollback and delete create a pending approval that a signed-in person decides in Studio (ADR-0014). The only exception is a key the owner put in `auto` mode, permanently or for a bounded time (5 min to 24 h, ADR-0016): it may publish article-only changes (nothing removed, at most 20) without a person (ADR-0015). Rollback and delete always wait. Modes are owner-only, never grant scopes, `bypass` is local only, and an elevation ends by itself because the mode is computed on every call. An agent may *ask* for an elevation (`request_elevation`), but only a signed-in owner of its key can grant it, for at most the time asked. Approvals are single-use and bound to the tool, exact arguments, the requesting agent and the content state; any change after the question voids them. Agents never receive a redeemable token. Scheduled publishes are approved by a person (or by an `auto`-mode key within its elevation window and 24 hours) against the exact pinned versions, re-checked when they run, executed at most once and never early; content scheduled for later is locked against edits and held back from ordinary publishes (RFC-0008).
3. **Every change is recorded and reversible.** Each MCP mutation snapshots the site; every tool call and decision is written to the audit log; rollback moves the published pointer to an ancestor snapshot.
4. **Agent-written content cannot run code. The only client scripts a site runs are Cloudhal's first-party scripts under `/_cloudhal/` (hashed, self-hosted, each switchable off): the analytics script; on pages with an open comment form, the comments module and its proof-of-work worker; on pages showing a video, the click-to-load player; and on pages with a live generative UI surface, the interaction runtime (RFC-0020 §4). The CSP allows no inline or third-party scripts; the one exception is Cloudflare Turnstile on comment pages, when the owner turns it on.** Agents write markdown only (no HTML sections, no edits to HTML bodies); markdown escapes raw HTML; links and image sources are limited to safe schemes. Site HTML on Cloudflare carries `script-src 'self'; connect-src 'self'; form-action 'self'` and `Referrer-Policy: strict-origin-when-cross-origin` (`cloudhal dev` and Node serve no CSP; see the accepted risks). The analytics script (`/_cloudhal/p.<hash>.js`, ≤ 1 KB gzipped, plus the sampled vitals module `/_cloudhal/v.<hash>.js` with `web-vitals`) is bundled at build time, served as an immutable static asset from the site's own origin and loads nothing from a third party. It is injected only into published `200` HTML while the site's setting is on, never into previews, errors or feeds (RFC-0006 §5.1). The comments module (`/_cloudhal/c.<hash>.js`, ≈ 2 KB gzipped, budget 4 KB) and its worker (`/_cloudhal/cw.<hash>.js`, ≈ 0.8 KB, pure-JS SHA-256, no WebAssembly) are built the same way, referenced only by pages whose thread is open, and store nothing on the device (no cookie, no `localStorage`). With Turnstile on, such a page carries its own policy adding `https://challenges.cloudflare.com` to `script-src` and `frame-src`; every other page keeps the default (RFC-0007 §7.6). `comments.available: false` in `cloudhal.json` removes the module and its endpoints from the deployment. The interaction runtime (`/_cloudhal/surface.<n>.js`, a constant module of ≈ 6 KB, ≈ 2 KB gzipped, versioned and hash-pinned by a test) is referenced only by surfaces with inputs or button actions. It reads the surface's data from an inert `<script type="application/json">` whose `<`, `>`, `&`, U+2028 and U+2029 are escaped, evaluates no code (bindings are JSON pointers, functions are Cloudhal's fixed set, the same as the server's), writes text only as `textContent`, refuses pointer segments that reach the prototype (`__proto__`, `prototype`, `constructor`), follows only same-site or https links, and talks to no server.
5. **Studio sessions are not usable cross-site.** State-changing `/api` requests must be same-origin; cookies are HttpOnly + SameSite=Lax; `/mcp` refuses foreign origins; a server without auth only answers localhost host names.
6. **A fresh deployment cannot be claimed by a stranger, and after the owner only invite links let people in.** The first (owner) account needs the one-time setup link printed by `cloudhal deploy`; afterwards sign-up is closed. Invites are `chinv_` + 256 random bits, stored only as a SHA-256 hash, shown once, delivered in the URL fragment, single use (one guarded statement), revocable, bound to one email and one role, and expire (7 days by default, 1 h–14 d, Administrator invites ≤ 72 h). The invite and reset endpoints take JSON only and are rate-limited per IP; accepting refuses while another user is signed in. Tokens and hashes never appear in audit rows.
7. **Drafts stay private.** Previews require signed, expiring, site-bound tokens, are never cached, and their HTML is sandboxed (CSP `sandbox`).
8. **People stay inside their role; the server decides, never the UI.** REST is default-deny: every route declares its requirement in `ROUTE_SCOPES` (`packages/api/src/scopes.ts`) and a test fails for any undeclared route. Own-limited roles may only touch entries they (or their agents) wrote; `author` is set by the server. An Author's publish goes live only when every public change is their own, otherwise it becomes a request someone with the full power decides. Only someone who could make a call right now may approve it, and nobody approves their own request. Membership changes go through audited routes only; demotion narrows keys at once, removal revokes sessions, disables keys, cancels invites and denies pending requests. Studio's gating is cosmetic.
9. **Media cannot become a vector (RFC-0004).** The server sniffs every file's type from its bytes and refuses a declared type or extension that disagrees, active content (HTML, XML, scripts), archives and executables. Photos lose Exif/GPS, XMP, IPTC and comments by default (lossless; only people may keep them); AVIF with metadata is refused. SVG is validated and rejected rather than sanitised (no DTD or entities, allowlisted elements and attributes, no handlers, script URLs or external references), only people may upload it, and it is served under `CSP sandbox`. Every media response carries `nosniff`; data files are attachments. Blob keys are derived from validated ids (`media/<siteId>/<sha256>`), every adapter checks keys and the filesystem adapter checks containment. A media URL serves only what the published snapshot (or a preview token's target) contains.
10. **The server never fetches into private networks.** `fetch_asset_url` and `cloudhal media import-urls` take https on port 443 only, no IP literals or internal names, check every resolved address (IPv4, IPv6, mapped and NAT64 forms) against private, loopback, link-local and metadata ranges, follow at most 3 redirects with each hop re-checked, enforce size, time and content-type limits, and honour a per-site host allowlist. On Node the connection is pinned to the checked address.
11. **Analytics store no personal data by default (RFC-0006, ADR-0021).** No cookies or device storage, no client identifier; no IP address, user agent, city or full referrer is ever stored, and the stored contract (`AnalyticsEvent`, `additionalProperties: false`) has no field for them. Opt-in unique visitors use a random daily salt that is deleted, and GPC and DNT are honoured (the view is counted, never hashed). People and agents see aggregates only. Controls and residual risks: [Site analytics](#site-analytics-rfc-0006).
12. **No reader comment becomes public without a person (RFC-0007, ADR-0022).** Every guest comment waits for approval; agents may label and hide but never approve or reply on the site's behalf; comment text is plain text everywhere and reaches agents only as quoted, untrusted data. No IP address is stored, emails are encrypted and visible only to Editors and above, and erasure is built in. Controls and residual risks: [Reader comments](#reader-comments-rfc-0007).
13. **Embargoes and expiries hold without a scheduler (RFC-0008, ADR-0023).** The published site checks every page's and entry's time gates on each request, keeps embargoed content out of every route, list, feed, sitemap and search output until its time, and never caches a page past the next gate. Unattended agent runs work only inside their window, within budgets, and lose the ability to write once they read visitor-supplied text. Controls and residual risks: [Schedules](#schedules-rfc-0008).

## Site analytics (RFC-0006)
A cached page view never runs the site Worker, so the browser reports it: one first-party beacon per view to `POST /__cloudhal/e`, which anyone can call. The goal is not to prove that a person sent it, but to keep inflation bounded and to make pollution unable to store free text. "Mitigated" is what the code does today; "Residual" is what remains.

| Threat | Mitigated | Residual |
|---|---|---|
| **Beacon spam and count inflation** | `Sec-Fetch-Site` must be `same-origin` when present; without it, the `Origin` (else `Referer`) host must equal `Host`. The request host must be one of the site's hosts (`Site.domains`, `CLOUDHAL_SITE_HOSTS`, the Worker's own `*.workers.dev` host). Body ≤ 2,048 bytes (`Content-Length` and a capped, strict UTF-8 read). A `User-Agent` is required (≤ 512 characters); bots, crawlers, headless browsers and HTTP libraries are dropped. Precompiled schema check. Per isolate, 30 page views and 30 vitals per client per minute, keyed by `HMAC(random per-isolate key, IP)` (no IP kept; at most 20,000 clients per isolate and minute, further ones dropped). With `analytics.rateLimit`, a Workers Rate Limiting binding adds a limit across isolates (120 beacons per client and minute by default, per Cloudflare location), keyed by an HMAC of the IP under a key derived from the deployment's purge token; it fails open. The client address is the one the runtime vouches for (Cloudflare's `CF-Connecting-IP` on the Site Worker, the socket address on Node), never a header a client sent. Vitals must carry the site's current sampling. Every outcome answers `204 no-store`, so the endpoint is no oracle. | Headers are forgeable outside a browser: a determined sender can inflate counts for real published pages. Without `analytics.rateLimit`, limits are per isolate, not global; with it, per Cloudflare location and eventually consistent (and its availability on Workers Free is unconfirmed, RFC-0006 A3). The "possible bot traffic" check (RFC-0006 §5.5) makes a flood visible — Studio's banner, REST `…/analytics/bots`, `get_analytics.botTraffic` — when the busiest hour of a period's last 7 days has ≥ 200 page views and ≥ 10× the median hour, with ≥ 80 % direct entrances or one browser family; it is a heuristic: a flood spread thin, with forged referrers and mixed user agents, stays below it, and a burst from chat apps (no referrer) can trip it. Accepted, as for every analytics product. |
| **Data poisoning (fake pages, wrong attribution)** | The beacon path is percent-decoded, lower-cased and resolved against the **published** snapshot (pages, entries, archives including `/page/n`); anything else is dropped, so drafts, previews and invented paths store nothing. The node id comes from that resolution: the beacon contract refuses client node ids and client identifiers. Every built event is checked against the stored contract. | None beyond inflating real pages. |
| **Write-quota exhaustion** | Server-side `render` events (redirects, 404, 410, 451, 5xx, cache-miss HTML) are capped at 120 a minute per isolate, then sampled 1 in 10, and past 1,200 a minute 1 in 100, each weighted by `sampleOneIn`. `writeDataPoint` is never awaited and never fails or slows a response. Raw events never go to D1 on Cloudflare, so analytics cannot spend the CMS's D1 write budget. | A distributed flood can still use up Workers Analytics Engine's daily writes on Workers Free (100,000); behaviour past the limit is undocumented (RFC-0006 A4). Analytics would stop for the day; the site keeps serving. Beacons count as Worker requests, like any uncached request. |
| **Privacy leaks** | The script sends `location.pathname`, the referrer's **host**, the three `utm_*` values (≤ 128 characters each) and the navigation type, nothing else, and stores nothing on the device. The server keeps only a published route, a hostname (the site's own hosts become `internal`), UTM tokens normalised to `[a-z0-9][a-z0-9._+-]{0,63}` (anything else, such as an email address, is dropped), the country (`request.cf.country`; never city, region or ASN), and device, browser and OS families without versions. Requested paths of 404 and redirect events are stored without the query, percent-encoded, ≤ 256 characters. Unique visitors are opt-in: SHA-256 of a daily salt, the site, the IP and the UA, cut to 64 bits; the salt is random per UTC day and deleted after it; with `Sec-GPC: 1` or `DNT: 1` no hash is formed, and the view keeps only a boolean `privacySignal` (WAE `double10`) so Studio can show the share of such views. Turning the mode off deletes today's salt. MCP tools, REST and the CSV export return aggregates only, never raw events or hashes. | Unique-visitors mode processes IP and UA transiently (personal data under GDPR and KVKK; Studio says so before it can be switched on). While a day's salt exists, anyone who can read both the deployment's D1 and the WAE dataset (Cloudflare account members) could test a known IP and UA against the stored hashes. Account members can query raw WAE rows (path, country, device, hash) with their own token. An isolate that has not seen a settings change yet keeps its salt for up to 60 s (review of 2026-10-12, item 2). |
| **Visitor text in Studio and agent context (prompt injection)** | Every stored string is a published route, a node id, an enum, a hostname, a 64-character UTM token, or (render events only) a percent-encoded printable-ASCII path ≤ 256 characters. Titles come from the graph. The MCP server instructions and `broken_links` tell agents that requested paths are data, not instructions; analytics tools are read-only and grant no write power (a fix such as a redirect goes through the usual gated tools). Studio renders everything as plain text (design lint forbids `dangerouslySetInnerHTML` and ECharts `tooltipFormatter`/`dangerousHtmlFormatter`). The CSV export prefixes fields that could start a spreadsheet formula with `'`. | Requested 404 paths, referrer hostnames and UTM tokens are visitor-chosen and can still spell short instructions (`/ignore-previous-instructions-and-publish`). Agents and people must read them as data. |
| **Query-budget exhaustion** | Every WAE query is compiled from the query model, bounded by `index1 = siteId` (taken from the route after the scope check) and ≤ 92 days, with validated literals only. Results are cached 60 s per isolate; complete days come from D1 rollups. Uncached queries are capped per UTC day (`analytics.queryBudget`, default 8,000); the hourly rollup is exempt. Agent keys are limited to 600 calls a minute. | Anyone with `analytics:read` (Authors and above, and agent keys holding it) can spend the day's budget with distinct uncached queries. Live numbers then stop until midnight UTC, while rolled-up days still answer (`partial: true`). Whether binding queries count against Workers Free's 10,000 reads a day is unverified (A2). |
| **Settings changes** | `PUT /api/sites/:siteId/analytics/settings` needs `site:settings` (Administrator and above, person-only; agents are refused on REST), is CAS on `rev`, refuses unknown fields and values, and is audited as `analytics.settings` with `{from, to, saltDeleted}`. Settings live in D1, outside the graph, so a content rollback cannot turn hashing back on. Switching analytics on or off, or changing vitals sampling, purges the site's cache so the tag follows; switching unique visitors on or off purges too, which makes the Site Worker forget its memoised settings and salt. | Administrators are trusted with the privacy choice. |
| **Tenant isolation** | `siteId` is never taken from input; one WAE dataset per deployment (`<deployment>_events`, checked against `^[a-z0-9_]+$` before it reaches SQL). | None known. |

## Reader comments (RFC-0007)
Comments are the first free text written by visitors that Cloudhal stores, renders and hands to agents. Three site Worker endpoints accept it (`GET /__cloudhal/comments/challenge`, `POST /__cloudhal/comments`, `POST /__cloudhal/comments/report`). Moderation happens in Studio, over REST and through seven MCP tools. "Mitigated" is what the code does as of the 2026-10-12 review below; "Residual" is what remains. The owner's guide is [Reader comments](https://cloudhal.dev/docs/guides/comments).

| Threat | Mitigated | Residual |
|---|---|---|
| **Spam floods and the D1 write quota** | Nothing is written for a submission that fails any check before the write (invariant C2, proven by tests that count statements on SQLite and D1). The checks, in order: same origin; `Content-Type`, and `Content-Length` and the body read capped at 32 KiB with strict UTF-8; the precompiled `CommentSubmission` schema; a published entry with an open thread; the honeypot; proof of work (a stateless HMAC challenge, MAC compared in constant time, 10-minute expiry, 3-second minimum fill time, 18 bits rising to 20 and 21 as the day fills) or Turnstile; rate limits per isolate (keyed by `HMAC(per-isolate key, network)`, an IPv6 address by its /64 like the D1 limits and the hash; requests without a client address share one separate bucket limited to 1 submission and 5 challenges a minute together), from D1 (5 stored an hour and 20 a day per client), and optionally across isolates (`COMMENTS_RL`); content rules; a per-site daily cap (1,000 stored a UTC day by default, about 7 % of D1 Free's writes); bans. A missing monthly salt is created inside the write's own batch. Proof is checked before rate limits, so unsolved requests cannot use up a real reader's allowance. Honeypot, bad proof, duplicates and bans are answered like a stored comment. | Every POST is a Worker request, so a distributed flood can still use up Workers Free's requests. A determined sender can fill the daily cap, which pauses comments (not the site) until midnight UTC. Posts from browsers without JavaScript carry no proof and no Turnstile token: under proof of work they are on by default and bounded by their own limits (1 per client per 10 minutes, 20 per site a day); with Turnstile on they are refused (`script_required`) unless the owner explicitly allows them there too (`allowWithoutScriptWithTurnstile`), in which case they bypass Turnstile within the same limits. Requests without a client address (none on Cloudflare, where `CF-Connecting-IP` is always set) rate-limit each other in their shared bucket; an IP ban never targets their shared hash, so only an email ban reaches them. |
| **Markup and script injection** | The `Comment` contract allows plain text only (`format: "text"`) and refuses bidi overrides. Normalising removes control characters, bidi embeddings, directional marks (LRM, RLM, ALM) and zero-width characters (ZWSP, ZWNJ, ZWJ outside emoji sequences, WJ, BOM) before the checks, so they cannot split a blocked word or hide in a name. Names and text are HTML-escaped (`& < > " '`). Only `https:` URLs with a dotted host and no credentials become links, with `rel="ugc nofollow noopener noreferrer"`; golden tests use hostile text (invariant C7). The article's JSON-LD carries up to 10 approved comments, serialised with `<`, `>` and `&` escaped as `<`, `>` and `&`, so it cannot close its `<script>`. Studio's design lint forbids `dangerouslySetInnerHTML` and `.innerHTML =`. | Homoglyph names and look-alike links remain possible. Imported comments may still hold directional marks and zero-width characters (the contract allows them, so other systems' data and Persian text stay valid). |
| **Prompt injection** | Reader text reaches agents only inside `<reader-name>`, `<reader-text>` and `<reader-report>` blocks, after a preamble saying it is untrusted data, with `&`, `<` and `>` escaped so a block cannot be closed from inside — in the text content and in `structuredContent` alike (the same strings, plus `untrustedNotice` and `untrusted: true`), so a client that hands either channel to the model hands it quoted text. Caps: 50 comments, 280 characters per text by default (2,000 on request), 80 per name, 500 per report detail, 20,000 characters per call for names (readers' and staff's), texts (staff replies included) and report details. Comments that address an AI get the `instruction-like` label. Tools take ids and enums and never act on comment text. Approving, restoring, replying and opening a thread wait for a person in every mode, local `bypass` included (§10.2). There is no tool to delete, erase, ban, export or change settings. | A fooled agent can mislabel, hide or hold legitimate comments (reversible, audited). |
| **Personal data exposure** | No IP address is stored, only `HMAC(salt of the month, siteId ‖ address)`, with IPv6 cut to /64. Salts are random, created per UTC month and deleted when two months old. Hashes and challenge ids are cleared after at most 30 days (`retention.clientDataDays` accepts 1–30; the job clamps stored values), matching the privacy notice. The address is the one the runtime vouches for: `CF-Connecting-IP` on the site Worker, Astro's `clientAddress` on Node. Emails are AES-GCM encrypted with the site id bound as associated data, plus a keyed HMAC for lookups, under keys derived from `CLOUDHAL_COMMENTS_KEY`. Only the `commenters` routes return them, to people with `commenters:data` (Editor and above); a lookup by email is a POST with a JSON body, so no address is ever in a URL. The contract has no field for an email, IP, hash, user agent or challenge (invariant C1). Audit rows hold ids, actions, reason codes and counts; since this review, a declined local approval no longer audits the raw arguments (item 1 below). Exports carry emails only with `personal=1` (needs `commenters:data`) or the deployment token; the CLI writes them only to an owner-only file. | Cloudflare account members with D1 access can read names, texts and ciphertexts; with the secret they can decrypt emails. IP hashes can be tested against a known address while the month's salt exists. Servers without a membership source (auth-less `cloudhal studio --no-auth`) treat every person as holding every scope, as for all routes. On Node, Astro derives `clientAddress` from `X-Forwarded-For` if a self-hoster configures `security.allowedDomains`; Cloudhal does not. |
| **Takedown latency** | Moderation never purges directly: the change and its `cloudhal-comments-<nodeId>` purge row are written in one batch (invariant C6). Takedowns (an approved comment hidden, marked spam, held, deleted or erased; a thread hidden) are flushed first, 2 s after the write, through the site Worker's purge endpoint. Normal purges wait 20 s and only while the last minute shows fewer than 3 purge requests, so publishing always finds room. Failures back off (30 s × 2^attempts, at most 5 min). After 2 minutes a waiting takedown raises a notification, with a last-resort "purge the whole site cache". The hourly job is the backstop; it runs behind an hourly watermark on the scheduler's minute tick (cron, or the `SchedulerClock` Durable Object alarm where the account has no free cron slot; RFC-0008). | Browsers and other caches may keep a copy. An empty purge bucket delays removal by up to a minute or two. Whether a 20 s `waitUntil` survives on Workers Free (V5) and the purge budget under real load (V1) are still to be verified live. |
| **Abuse of reports** | A report never changes a comment's status. Reports need the same proof as comments, are limited to 5 per client an hour and 200 per site a day, and only approved comments can be reported. Details are cut to 1,000 characters and shown as plain text. | A flood of reports can bury real ones; the limits bound it. |
| **Approval replay and stale decisions** | Approvals for comment tools are bound to a `cm1:` hash of the named comments (id, rev, status) and threads (rev, effective state) instead of the graph (invariant C4). Carrying out recomputes the hash as the approving person and answers 409 `state_changed` on a mismatch. The binding fails closed: if it cannot be computed when the agent asks, nothing is filed (or minted for a local question) and the call answers `state_unavailable`; a request without a computed binding, or one whose binding cannot be computed when the person decides, is denied with 409 `state_changed` and never carried out. Approvals are single use (`pending → approved → consumed`), and agents cannot redeem them. | A store outage at decision time closes the request; the agent must ask again. |
| **Cross-site posting** | `Sec-Fetch-Site` must be `same-origin` when present; otherwise the `Origin` (else `Referer`) host must equal `Host`, and `Host` must be one of the site's hosts (`Site.domains`, `CLOUDHAL_SITE_HOSTS`, the Worker's own `*.workers.dev` host). There are no cookies and no ambient authority to forge. The page to return to is computed by the server (no open redirect). | Headers are forgeable outside a browser (bounded by proof and limits). On Node every request host is accepted as a site host. |
| **Third-party script (Turnstile)** | Opt-in per site; the CSP is widened only on pages with an open form. `siteverify` gets the owner's secret (stored encrypted, write-only), `remoteip` and an idempotency key. The answer's hostname must be a site host and its action the form's kind. Any failure, an outage included, answers 503 (fails closed). | Cloudflare processes visitors' browser data while it is on; the privacy notice has a variant for it. Posts without JavaScript are off while it is on, unless the owner explicitly allows them (they then bypass it; see the first row). Whether a `workers.dev` hostname is accepted is unverified (V2). |
| **D1 limits per invocation** | Every export is paged, Studio's REST export (`GET …/comments/export`, also with `personal=1`) like the deploy-token one: 500 comments (10 reads) or 100 commenters (4 reads) per request, continued with `cloudhal-next-cursor`. A commenter's export reads their comments in one query. "Ban and hide past comments" hides at most 1,000 comments a request in set-based batches of 200 and answers `more` (Studio repeats it). Bulk moderation and erasure use set-based statements (≤ 5 per batch, whatever the number of comments). Tests count every query of a request on SQLite and D1 against 3,100 comments and 121 commenters. | Queries spent by authentication (session and membership reads) come on top; the measured requests leave more than half of the 50 free. |
| **Tenant isolation and keys** | The site Worker uses its own `CLOUDHAL_SITE_ID`, and REST uses the route's site after the scope check (invariant C14); every query is keyed by it. `CLOUDHAL_COMMENTS_KEY` is generated by `cloudhal deploy` (256 bits), kept in the 0600 secrets file and given to both Workers as a secret, never in a config. Without it (or shorter than 32 characters) comments are unavailable, never a crash. Proof-of-work, email, email-hash, secret and `COMMENTS_RL` rate-limit keys are derived from it by HKDF with distinct labels; the raw secret keys nothing. Imports take the site from the route, never from the file. | MCP tools take `siteId` from their arguments, like every MCP tool (roles are deployment-wide). Losing the secret makes stored emails and the Turnstile secret unreadable. |

## Schedules (RFC-0008)
Schedules add the first actions Cloudhal takes when nobody is at the keyboard: releases published by the scheduler, time gates the site enforces on its own, and agent runs started by external platforms with their own keys. "Mitigated" is what the code does as of 2026-10-13 (rollout steps 1–8, 10 and 12; built-in job bodies and Studio screens are still being built); "Residual" is what remains. The owner's guide is [Schedules](https://cloudhal.dev/docs/guides/schedules).

| Threat | Mitigated | Residual |
|---|---|---|
| **Embargo leak through a forgotten render path** | One helper (`isAvailable`, `@cloudhal/core-ts/availability`) applied by the snapshot source at one instant per request to every public path: pages, entries, lists, archives and their counts, related posts, menus, RSS, sitemap, JSON-LD and Open Graph, the comments endpoints and analytics lookups (invariant S9). Media whose every live referrer is embargoed inherit the earliest `from` and answer 404. A route sweep test renders every route of the blog starter at each gate −1 ms, exactly and +1 ms, in the renderer and on workerd, and fails on any gated id, title, path or media URL. Writers refuse `availability` (`409 gates_unsupported`) until the site Worker answers `GET /__cloudhal/features` with `{ "gates": 1 }` (S15). Static builds warn when a gate will change the site after the build. | A theme route that bypasses `GraphSource` can still leak. Previews shared by link show embargoed content by design. A static `cloudhal build` reflects the gates at build time. The `feed-check` self-check in production comes with the built-in jobs (rollout step 9). |
| **Early publication (clock, tzdata, DST)** | Wall-clock times are recomputed with current tzdata before running and only ever move later (`adjusted: "tzdata"`); a DST gap moves forward, an overlap runs at the first instant. `now` is injected everywhere; `temporal-polyfill/implementation` is the only Temporal entry, Biome refuses the global and shim entries and a repository test refuses `Temporal.Now` (S16). The site Worker compares instants only and never bundles the time-zone library (a test walks its imports). Minute granularity; releases get no jitter. | A wrong system clock on a self-hosted Node server. |
| **Double or partial publication** | A run's id is derived from its subject and occurrence; a claim is a CAS on the release's `rev` and state with a fresh lease token, and no other release of the site may be running (one at a time, D15). The effect is one guarded `batch()` of at most eight statements whose first statement flips the site pointer only while the site's `rev` and `hash` and the run's lease are unchanged; every later statement is guarded on the new site hash. A retry first looks for a snapshot whose metadata names the run. Proven by concurrent ticks on SQLite and Miniflare D1 (S3). | — |
| **Content changed after approval** | Items pin `rev` and content hash with the live base; the approval binds to `rl1:` (exactly those versions) and the request's arguments hash to the time. Every update and delete path refuses held nodes (`409 scheduled_locked`), ordinary publishes keep them at their live version and `publish` refuses a snapshot that would move them (S5). A changed node or base at run time holds the release as a conflict and writes nothing else (S4). A person's "Edit and re-approve" re-pins and re-approves in one act; agents cannot edit held nodes at all. | — |
| **Approval outliving the approver's rights** | Re-checked when the release runs (S7): a person's approval holds only while they are a member who could approve it now (`releases:publish`, or `:own` with own-only items); an `auto` approval only while the key exists, its creator is a member and its effective mode is still `auto` (D9). Otherwise the release expires (`approval_lost`, `creator_removed`, `auto_window_ended`). | A release approved minutes before a demotion runs if its time comes first. Automations are not yet marked `broken` when their owner is demoted or removed or their key is revoked (§11.8): their runs fail because the key is narrowed, disabled or revoked, but they still show as active. |
| **Silent late publication** | A release runs late at most once and only within one hour (S8); later it is `missed`, with a notification and "Publish now" for a person. A heartbeat raises "scheduler stalled" after 2 minutes (work due within 24 h) or 10 minutes; every admin request is a backstop that runs a tick when the heartbeat is stale. | A stalled scheduler delays releases by up to an hour before they are declared missed. An undecided release request expires the release when releases, the calendar or notifications are next read, not by the tick, so its nodes stay locked until then. |
| **Leaked automation key** | Outside an open run the key answers `outside_run` for every tool except `begin_run`, `get_mode` and `pause_automation`; a run works on its automation's site only; budgets end the run and pause the automation; the key is narrowed to its owner's current role and capped by the automation's current `modeCap` on every call (never `bypass`, S11); revoking it stops it at once. | Usable inside its window, up to its budget. Outside a window it can read its own mode and pause its own automation. |
| **Prompt injection in unattended runs** | Taint per run from the first tool that returns visitor-supplied text (`list_comments`, `get_comment_thread`, `broken_links`, `get_analytics`, `top_content`, `fetch_asset_url`); afterwards only read, label, hide and pause (S12). No egress in runs (`fetch_asset_url` refused). Automations declared to read visitor text cannot hold write, publish, schedule or asset scopes (refused when requested at creation, stripped on every call). Unattended runs publish nothing except `auto`-mode low-risk releases while untainted. More than 50 reductions or 10 refusals in a row kill the run and pause the automation. Run summaries reach other agents only as escaped `<run-summary>` blocks marked untrusted. `request_elevation` is refused in runs. | A fooled run can mislabel or hide comments (reversible, audited). Other people's drafts do not taint a run (RFC-0008 open question 4). |
| **Automation exhausting D1** | Per-run budgets (tool calls, writes, approval requests, minutes), a per-site daily cap on automation writes (200 by default, counted from audit rows), pause after three consecutive failures (S13). | An Administrator can raise the cap. The deployment switch `CLOUDHAL_AUTOMATIONS=off` comes from `cloudhal.json` `schedules.automations: false` and is written by every `cloudhal deploy` (on Node, from the environment). |
| **Downgrade releasing held or gated content** | `cloudhal deploy` compares the code's `cloudhal.schedulesLevel` with the deployment's and refuses to deploy older code while there are open releases or gated nodes; `cloudhal push` refuses while releases are open unless `--cancel-schedules`. | `--force-downgrade`. A deploy made with an older CLI runs no check. |
| **Purge budget exhaustion at popular release times** | A release's purge plan is computed when it is pinned and sent through the site Worker within the shared purge budget (`cache_purge_log`, source `schedules`); when the bucket is empty the tags go into the purge queue (`purge: "deferred"`). Gates need no purge: every published response's edge lifetime is capped at the next gate (S10; a 30 s cap was verified live). | A full bucket delays a release's cache update by a minute or two. |
| **Edge-cached API answers** | Workers Cache was seen caching GET answers without caching headers (live check, 2026-10-12): every API GET without its own header answers `cache-control: no-store`, and so do `/__cloudhal/features` and the operator routes. | — |
| **Tenant isolation** | REST takes the site from the route after the scope check; the scheduler takes it from the stored release or automation; an automation key's run is bound to its automation's site. | MCP tools take `siteId` from their arguments, like every MCP tool (roles are deployment-wide). |

## Accepted risks (alpha)
- **Skill narrowing is advisory.** A client that omits `_meta["cloudhal.skill"]` is limited only by its key's scopes. Bind skills to keys before treating them as a control.
- **Roles are deployment-wide.** A role applies to every site of the deployment; keys are not scoped to a site. Per-site roles come later (RFC-0005 open question 10).
- **Link invites leave the email unverified.** Whoever holds a link becomes the invitee; the account's email is marked unverified unless a mail sender delivered the link. A link pasted into a shared channel grants its role to whoever uses it first; links are single use, short-lived and revocable.
- **Administrators can demote or remove each other** (Ghost parity). Every change is audited and the affected person is notified.
- **Administrator-issued password reset links** (`chrst_…`, one hour, single use) let an Administrator take over a non-Owner account; they are audited, and never issued for the Owner.
- **The deployment token is root** for site data (read drafts, replace content). Keep `.cloudhal/deploy/secrets.json` private; rotation tooling is pending.
- **Preview tokens and agent keys do not expire by default** (preview links up to 7 days; keys until revoked). Revoke keys in Studio; shorter defaults are planned.
- **Approval prompts include agent-chosen titles** (shortened and quoted). Read the change list, not just the counts.
- **`auto` mode publishes without a person** within the low-risk rule. A wrong but small article change can go live; it is audited as auto-approved and one rollback away. Prefer a time-boxed elevation over a permanent `auto` key.
- **Local `cloudhal mcp` trusts the developer's MCP client** to ask the person (elicitation).
- **Workers cannot pin DNS.** On the admin Worker, `fetch_asset_url` checks names through DNS-over-HTTPS but `fetch` resolves again; a rebinding answer could differ. Cloudflare's egress has no route to the operator's private networks or cloud metadata, and every other rule still applies. Set a per-site host allowlist (`cloudhal.media.allowHosts`) for agents that fetch.
- **No malware scanning.** Uploads are type-checked, not scanned; data files are served as attachments. Attach a scanner to R2 event notifications if you need one.
- **A taken-down file may survive in browsers** that cached it under `immutable`; the edge copy is purged.
- **Analytics beacons can inflate counts for published pages** ([Site analytics](#site-analytics-rfc-0006)). They cannot create pages, target drafts or store free text.
- **Unique-visitors mode processes IP addresses and user agents** transiently into a daily hash. It is off by default and Administrator-only; owners should say so in their privacy policy ([guide](https://cloudhal.dev/docs/guides/analytics-privacy)).
- **Requested 404 paths, referrer hosts and UTM tokens are visitor-controlled text** shown to people and agents, within small alphabets and lengths.
- **The AI-crawler report and the request estimates are lower bounds or estimates.** Render events see cache misses only.
- **Proof of work raises the cost of spam but does not stop a determined sender** ([Reader comments](#reader-comments-rfc-0007)). Every guest comment waits for a person anyway, and the daily cap bounds what reaches D1.
- **IP bans end when the month's salt rotates** (at most about a month); email bans last until lifted.
- **Posting without JavaScript is a weaker path**: no proof and no Turnstile, bounded by its own limits and switchable off per site. With Turnstile on it is off unless the owner allows it explicitly.
- **A published page is a function of the snapshot and of live comments.** Rollback never touches comments, so a rolled-back article keeps its discussion.
- **`cloudhal dev` and Node serve site pages without a CSP.** Only the Cloudflare site Worker sets it; a Node self-host should add one at its proxy.
- **The cron trigger has no delivery guarantee** (RFC-0008). The request backstop, the heartbeat and the one-hour window make a missed tick visible and bounded; measured on Workers Paid (2026-10-12): 0 of 106 minutes missed, p99 delay 24.6 s. Not yet measured on Workers Free.
- **Workers Cache honouring short edge lifetimes is verified live, not by contract.** Embargoes and expiries rely on it instead of purges (a 30 s lifetime held on 2026-10-12). If it ever stops, gates still hold for uncached requests and the cache keeps a page at most until its lifetime ends.
- **Agents see embargoed drafts** as they see any draft (`content:read`). Embargoes keep content off the public site, not away from keys that may read content.
- **Live analytics depend on the Analytics SQL binding** being available on the account's plan (RFC-0006 A1, unverified on Workers Free). Without it, visits are still recorded and kept for 3 months, and Studio shows "can't read yet".

## Reviews
- 2026-10-08 — pre-launch review (Sprint 7): 1 critical, 3 high, 5 medium findings fixed (agents on REST, self-approval, approval replay, agent HTML/XSS, CSRF, owner claim, scoped CAS, audit rows, no-auth host check); low items tracked above.
- 2026-10-12 — site analytics (RFC-0006 step 11): the controls above checked against the code. Items found, and their status:
  1. **Mitigated.** Without the hourly cron trigger (`CLOUDHAL_ANALYTICS_CRON=off`, Workers Free accounts with no free trigger), past salts were deleted only when someone read analytics, so a salt could outlive its day. Now the first salt of a day deletes every earlier one in the same atomic `batch()` (`getOrCreateSalt`), so no salt outlives its day by more than the first hashed page view of the next; the cron and on-read rollups still delete them too.
  2. **Mitigated.** The site Worker kept the day's salt in isolate memory after "unique visitors" was switched off and its D1 row deleted, and reused it when the mode was switched on again the same day, linking hashes across the switch. Now the memoised salt is read again from D1 whenever the isolate re-reads its settings (every 60 s, or at once after a purge), and switching unique visitors on or off purges, which resets the memo; a deleted row means a new random salt. An isolate that the purge did not reach can use the old salt for at most the 60 s it already takes to see any settings change.
  3. **Mitigated.** Off Cloudflare (`cloudhal dev` with `analytics.dev`, a future Node host) the beacon handler trusted a client-sent `CF-Connecting-IP`, which defeated the per-client limit and fed the hash. Now the handler never reads the client address from a header: the caller passes it (`clientIp`) — the Site Worker passes `CF-Connecting-IP`, which Cloudflare's edge sets and overwrites; the Node middleware passes the socket address. The Rate Limiting binding is keyed from the same address.
  4. **Mitigated.** The optional Rate Limiting binding (`analytics.rateLimit`) is built, and so is the "possible bot traffic" banner (a heuristic over aggregates; see the Site analytics table).
- 2026-10-12 — reader comments (RFC-0007 step 10): the claims of RFC-0007's Security section and invariants C1–C14 checked against the code of steps 2–7 and 10. Most hold (see [Reader comments](#reader-comments-rfc-0007)). Items found, and their status:
  1. **Mitigated.** When a person declined a gated call in their own MCP client, the refusal's audit row stored the raw arguments, so a declined `draft_comment_reply` kept the reply text and a declined `moderate_comments` its note (against C8). The row now goes through the tool's `auditArgs` like every other row (test in `mcp-server/test/comments.test.ts`).
  2. **Mitigated.** Retention (pending, spam, deleted, IP hashes and challenge ids after 30 days) ran only on the admin Worker's cron. A deployment whose account had no free cron trigger never ran it, and neither did `cloudhal studio` on Node. Now `cloudhal deploy` keeps the trigger for comments even with analytics off; without a free slot it sets `CLOUDHAL_COMMENTS_CRON=off`, and the admin Worker then runs the hourly job after requests, at most hourly per isolate. `cloudhal studio` and `cloudhal mcp` run it on an hourly timer.
  3. **Mitigated.** If the `cm1:` binding could not be computed both when the agent asked and when the person decided, both sides read `"unbound"` and the comparison passed. Now a failed binding is never a value: the MCP server refuses to file a request or mint a confirmation for it (`state_unavailable`), and Studio's carry-out denies (409 `state_changed`) a request whose stored binding is missing or whose binding cannot be computed now (`isBoundState`; tests in `mcp-server/test/comments.test.ts` and the API suite on SQLite and D1).
  4. **Mitigated.** RFC-0007 §9.1 and §9.3 promise that IP hashes and challenge ids are kept 30 days, and the site's privacy notice (§9.6) says "up to 30 days", but `retention.clientDataDays` accepted 1–3,650. Now settings accept 1–30 (`MAX_CLIENT_DATA_DAYS`, 400 above it), and the retention job and the settings reader clamp a stored value to 30, so the notice stays true whatever an Administrator chooses.
  5. **Mitigated.** Posts without JavaScript skipped Turnstile as well as proof of work, and they were allowed by default (RFC D11), so an owner who turned on Turnstile could not expect every post to be verified. Now, while Turnstile is on, they are refused (`403 script_required`, nothing written) unless the owner also sets `allowWithoutScriptWithTurnstile` (default false; `withoutScriptAllowed` decides for the pipeline, the rendered form and `cloudhal comments status`). D11 is unchanged under proof of work. The guide explains the trade-off.
  6. **Mitigated.** The MCP tools also returned comments as `structuredContent` (marked `untrusted: true`, capped) with the reader text neither delimited nor escaped, so C8 held for the text content only. Now every reader name, text and report detail in structured content is the same escaped `<reader-…>` block as in the text content, results carry an `untrustedNotice` preamble, and one 20,000-character budget covers both channels (they carry the same strings). Tests feed fake tool calls, closing tags, chat-template tokens and pre-escaped tags through both channels (`mcp-server/test/comments.test.ts`).
  7. **Mitigated (availability).** Studio's REST export, its personal-data variant, "ban and hide past comments" and a commenter's export looped past D1 Free's 50 queries per invocation on large sites. Now Studio's export uses the deploy-token export's pages (`exportPage`, `cloudhal-next-cursor`), a page of commenters costs four reads whatever its size (`SqlCommentStore.commenters`), a commenter's export is one read (`commenterComments`), and hiding past comments is set-based and bounded (`hideApprovedOf`, ≤ 1,000 a request with `more`). The API suite counts every query per request on SQLite and D1 and asserts it stays under 50.
  8. **Mitigated.** `GET …/commenters?email=` (as RFC §12 specified) put an email address in a URL query string, where request logs can keep it. The lookup is now `POST …/commenters/lookup` with `{email}` or `{commentId}` in a JSON body (`commenters:data`, people only, in `ROUTE_SCOPES`); the GET variant is gone, so a query-string lookup has no declared route (default-deny). Studio's `findCommenter` sends the POST.
  9. **Mitigated (minor).** The isolate rate limiter keyed the full IPv6 address (the D1 limits and the hash use the /64); requests without a client address shared the ordinary `"unknown"` bucket and hash; the `COMMENTS_RL` key was an HMAC under the raw secret; staff names were not charged to the 20,000-character budget (reply texts were); directional marks and zero-width characters were kept. Now the limiter keys `clientNetwork` (IPv6 /64); requests without an address share `UNKNOWN_CLIENT_KEY` with stricter limits (1 submission and 5 challenges a minute together), and `ban` skips an IP ban of their shared hash; the binding's key is `rateLimitKey` under an HKDF-derived key (`cloudhal/comments/rl/v1`); staff names are charged; and normalising removes LRM, RLM, ALM, ZWSP, ZWNJ, WJ, BOM and ZWJ (kept only between two emoji in text). The contract still allows those characters, so imported data stays valid.
  10. **Mitigated (RFC wording).** §11.2 point 6 said CSV and JSON exports prefix formula-like cells with `'`. The comments export is JSON lines meant to be imported again, where a prefix would corrupt the data, and there is no CSV export of comments. The RFC now says "CSV exports"; the one CSV export (analytics) prefixes such cells, and a test pins that the JSON-lines export keeps formula-like text verbatim.
  11. **Mitigated (gap).** "Allow comments" (RFC §10.1) had no route: `ADDABLE_KEY_SCOPES` lacked `comments:read`, so owners widened access by creating new keys. Now `comments:read` can be added to an existing key under `analytics:read`'s rules (own keys or `agents:manage`, never beyond the creator's role, so never to a Contributor's key; audited `agent-key.scopes`). Write scopes are still fixed at creation.