@hozu/cli 0.18.1 → 0.19.0

package/skill/example/ui/field.ts

@@ -0,0 +1,20 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({
+  slots: { base: 'flex-1 space-y-1', label: 'sr-only', error: 'text-sm text-rose-600' },
+})
+
+export const Field = ui.component({
+  tag: 'div',
+  styles,
+  props: z.object({ for: z.string(), label: z.string(), error: z.string().nullable(), errorId: z.string() }),
+  slots: ['control'],
+  render: ({ props, slots, classes }) =>
+    ui.div({}, [
+      ui.label({ for: props.for, class: classes.label }, [props.label]),
+      slots.control,
+      ui.p({ id: props.errorId, class: classes.error }, [props.error]),
+    ]),
+})

package/skill/example/ui/input.ts

@@ -0,0 +1,33 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({ base: 'w-full rounded border px-3 py-2 aria-invalid:border-rose-500' })
+
+export const Input = ui.component({
+  tag: 'input',
+  styles,
+  props: z.object({
+    id: z.string(),
+    name: z.string(),
+    value: z.string(),
+    required: z.boolean().default(false),
+    minlength: z.number().optional(),
+    maxlength: z.number().optional(),
+    invalid: z.boolean().default(false),
+    describedby: z.string().optional(),
+  }),
+  events: ['input'],
+  render: ({ props, on }) =>
+    ui.input({
+      id: props.id,
+      name: props.name,
+      value: props.value,
+      required: props.required,
+      minlength: props.minlength,
+      maxlength: props.maxlength,
+      'aria-invalid': props.invalid,
+      'aria-describedby': props.describedby,
+      on: { input: on.input },
+    }),
+})

package/skill/example/ui/kit.ts

@@ -0,0 +1,7 @@
+import { ui } from '@hozu/core'
+import * as badge from './badge.ts'
+import * as button from './button.ts'
+import * as field from './field.ts'
+import * as input from './input.ts'
+
+export const kit = ui.kit({ id: 'ui', components: [button, input, field, badge] })

package/skill/example/ui/tv.ts

@@ -0,0 +1,12 @@
+import { createTV } from '@hozu/variants'
+
+// hozu:variants-config ui
+const twMergeConfig = {
+  extend: {
+    theme: {},
+    classGroups: {},
+  },
+}
+// /hozu:variants-config
+
+export const tv = createTV({ twMergeConfig })

package/skill/topics/auth.md

@@ -0,0 +1,56 @@
+# Sign-in, sessions, who may read and change what
+
+- **Start:** `hozu add feature notes --page / --with auth` (sign-in page, sign-out, `me`); set `SESSION_SECRET`.
+- `project({ session: z.object({ user: z.string() }) })`. `scope: 'user'` queries and mutations get `session`;
+  a mutation calls `setSession(value)` (`null` signs out).
+- **Every server-run user query and mutation says who may run it**, like `runs` (HZ088):
+  - `access: 'signedIn'`: any signed-in visitor; the resolver reads that visitor's data by `session`.
+  - `access: { owner: { row: (n) => n.owner, session: (s) => s.user } }`: the framework checks the output. One row
+    that is not the visitor's is `Forbidden` (a missing owner on either side never matches); a list holding such
+    rows is HZ091 (the resolver read too much).
+  - On a mutation, `{ owner: { load: getNote, input: (i) => ({ id: i.id }), row: (n) => n.owner, session: (s) =>
+    s.user } }` reads the row and checks it before the resolver runs; if `load` fails for any reason (`NotFound`
+    too), the answer is `Forbidden` and the resolver does not run.
+  - `access: { allow: ({ session, input }) => session.role === 'admin' }`.
+  - `access: 'anyone'`: sign-in, a newsletter. On user data it is HZ090.
+- **Refused** is the framework error `Forbidden`, before the resolver runs: optional in `failed` (otherwise
+  `Unexpected`). A page answers 403, or maps it: `head: { query: me, …, failed: { Forbidden: login } }`.
+- Check it as two visitors: `hozu call <effect> --session '{"user":"bob"}'`, or in one chain: `hozu browse /
+  --as ada --session '{"user":"ada"}' --do 'remember note from li a @href' --as bob --session '{"user":"bob"}'
+  --do 'goto $note'` (bob gets 403). `post <path> a=1` forges a native post as the current actor.
+
+<!-- more -->
+
+## Details
+- The scaffold writes `features/account` (sign-in page, sign-out, `me`), per-user resolvers, and a redirect to
+  `/login` when signed out. Replace the name-only sign-in with real credentials before production; production
+  without `SESSION_SECRET` refuses to start.
+- Public queries never receive `session`.
+- Sessions live on the server: the default store is `memorySessions()` (from `@hozu/runtime-server`); the cookie holds
+  only an opaque, signed, HttpOnly id, so `setSession(null)` revokes it and the session never reaches browser
+  JavaScript. It is per process: a restart signs everyone out, and an edge or multi-instance deployment passes a
+  shared store explicitly (`createHandler({ session })`).
+- `setSession` also applies in a failing mutation (expiry: `setSession(null)` then `fail('Expired', …)`).
+- After a sign-in or sign-out the page's queries are re-read with the new session; nothing from the old one stays.
+- A role on top of sign-in: `'signedIn'` plus a declared error (`NotAdmin`) mapped to 403 keeps "signed out → login"
+  apart from "not allowed → 403" (`failed: { Forbidden: login, NotAdmin: 403 }`); `{ allow }` answers Forbidden for both.
+- `access` is recorded in `hozu.lock.json`, so a change to it is reviewed like a transition.
+- `owner` needs the row to carry its owner field (HZ088 otherwise): add it to the output, or use `'signedIn'` and
+  read only the visitor's rows. In production a list's foreign rows are dropped and logged once.
+- Public queries never see the session, and a browser-run effect is guarded by the API it calls: `access` there is
+  HZ089.
+- **A token that expires:** keep it and its expiry in the session, and refresh it in `app({ refreshSession: async
+  (session, { env }) => session.expires > Date.now() ? undefined : { ...session, token: await renew(session) } })`.
+  It runs once per request before any resolver reads the session (queries stay read-only); the new value replaces
+  the old one in place (the cookie stays), `null` signs out, `undefined` keeps it. Requests of one session in one process share one call
+  (and its result for ten seconds); a sign-out while it runs wins; a throw keeps the session and reaches `onError`. Do not keep tokens in module variables: a restart or a second
+  instance loses them.
+- Calling another API with a token: a token your server holds goes in the session and is read in a `runs: 'server'`
+  resolver; a token that lives in the browser (OIDC / SSO, `localStorage`) is read in a `runs: 'browser'` effect
+  (`hozu docs fetch`) and never reaches your server.
+- `SESSION_SECRET` is at least 32 characters: `openssl rand -hex 32`. Keep it in a git-ignored `.env` and list
+  it in `.env.example` (`npx hozu env --example`).
+- **A refused page** renders the page's views with status 403 (the `<title>` falls back to the site name). For a
+  page of its own, map `Forbidden` (or a declared error) to a route: `failed: { Forbidden: login }`.
+- **Order on a mutation:** the input schema first (`Invalid` with field errors), then access (`Forbidden`), then the
+  resolver.

package/skill/topics/components.md

@@ -0,0 +1,92 @@
+# Components (shared UI, kits, browser code)
+
+A UI piece used by several features is a component in a kit: `hozu add kit ui`, then `hozu add component ui Button`
+(`hozu add component <feature> <Name>` makes one private to that feature).
+```ts
+// ui/button.ts; ui/kit.ts lists it: ui.kit({ id: 'ui', components: [button, input] })
+const styles = tv({                                            // tv from ./tv.ts
+  base: 'inline-flex gap-2 rounded px-4 py-2 disabled:opacity-50 aria-busy:cursor-wait',
+  variants: { tone: { primary: 'bg-indigo-600 text-white', ghost: 'text-slate-700 hover:bg-slate-100' } },
+  defaultVariants: { tone: 'primary' },
+})
+export const Button = ui.component({
+  tag: 'button', styles, slots: ['icon'], children: true, events: ['press'],
+  props: z.object({ type: z.enum(['button', 'submit']).default('button'), busy: z.boolean().default(false) }),
+  render: ({ props, slots, children, on }) =>
+    ui.button({ type: props.type, 'aria-busy': props.busy, on: { click: on.press } }, [slots.icon, ...children]),
+})
+```
+```ts
+ui.use(Button, { variant: { tone: 'ghost' }, props: { busy: ctx.saving }, slots: { icon: ui.span({}, ['+']) },
+  on: { press: ui.send(Save, {}) }, class: 'w-full' }, ['Save'])           // in a view; its id is ui.Button
+```
+- **`ui.use` keys** (all optional): `variant` (literals only, HZ071), `props` (anything that changes while the page
+  runs), `slots`, `on`, `class`; children only with `children: true`.
+- **Render** reads only `props`, `slots`, `children`, `on` and `classes`; the caller passes sends, links and text
+  in (HZ070).
+- **`class`** may only add classes that set none of the component's properties (`w-full`, `md:hidden`); to change
+  one, declare a variant (HZ072–HZ077; one-offs: see --more).
+- Browser APIs or DOM libraries: a client component, `hozu add component <kit|feature> <Name> --client` (see --more).
+- `previews.ts` (`project({ previews })`) is for people: named component states and page screens in DevTools
+  Assets. It never ships; change it only when asked or when HZ092 names a line (see --more).
+
+<!-- more -->
+
+## Details
+- `hozu add kit ui` writes `ui/kit.ts`, `ui/tv.ts` and `project({ kits })`.
+- **Variants vs props:** a variant is a fixed look chosen in the view (HZ071 for data); anything that changes while
+  the page runs is a prop. Style a state through the attribute that announces it: `disabled:`, `aria-pressed:`,
+  `aria-busy:`, `aria-invalid:`, `aria-expanded:`, `open:`. `toggle` is for states without one.
+- **Render:** `classes` holds the other tv slots (`classes.label`). Hozu puts the root class on the root.
+- **Extension:** `class` may add classes that set none of the component's properties (`w-full`, `relative`,
+  `md:hidden`). To change one, declare a variant; a one-off ends with `!` (`rounded-lg!`) (HZ072–HZ077).
+  `hozu check` counts the `!` per component; `extend: false` refuses every class.
+- A view fragment that two features inline is a component, not a `part()` (HZ080).
+
+## Client components (browser APIs, DOM libraries)
+`hozu add component <kit|feature> <Name> --client` writes the declaration, the client module, the bundle in `app.ts`
+and the `@hozu/bundle` dependency.
+```ts
+export const Map = ui.component({ tag: 'div', props: z.object({ lat: z.number(), lng: z.number() }),
+  emits: { picked: z.object({ id: z.string() }) }, client: new URL('./map.client.ts', import.meta.url),
+  load: 'visible', render: () => ui.div({}, []) })                     // 'eager' | 'visible' | 'idle'
+ui.use(Map, { props: { lat: ctx.lat, lng: ctx.lng }, on: { picked: (d) => ui.send(Pick, { id: d.id }) },
+  class: 'h-96 w-full' })
+```
+```ts
+// map.client.ts: a type-only import of the declaration
+import { implement } from '@hozu/core/component'
+import type { Map } from './components.ts'
+export default implement<typeof Map>(({ el, props, emit, signal }) => {
+  const map = createMap(el, props)                          // any DOM library
+  map.on('pick', (id) => emit('picked', { id }))
+  return { update(next) { map.move(next) }, destroy() { map.remove() } }
+})
+```
+- The render is the server HTML the module takes over; with `children: true` the children stay as the no-JS
+  fallback. The root takes no attributes or `on`: put a role or label on a wrapping element.
+- `app.ts` passes `components: bundleComponents` (`@hozu/bundle`) to `app()` (HZ045 without it). A library's CSS
+  goes in `app.css`; a map or chart host needs a height class.
+- `hozu browse /` lists each one as mounted / failed / not mounted with its size and canvases; a mounted host has
+  `data-hozu-component="<id>"` and `data-hozu-component-state="mounted"`.
+
+## Look them up
+- `hozu docs components` (this topic, then the app's list), `hozu inspect ui.Button` (variants, props, owned
+  classes, every use), `hozu why ui.Button`.
+- `hozu render ui.Button --variant tone=ghost --props '{"busy":true}' --slot icon=+` renders it alone: HTML, root
+  class, owned properties, diagnostics.
+
+## Previews (for people, never shipped)
+- `project({ previews: new URL('./previews.ts', import.meta.url) })`; only `hozu dev` and `hozu check` load it. DevTools **Assets** shows every component × variant (props from the schema) plus these.
+- ```ts
+  import { previews } from '@hozu/core/preview'
+  export default previews((p) => [
+    p.component(Button, 'Long label', { variant: { tone: 'primary' }, children: 'Save every note' }),
+    p.page(home, 'No notes', [p.data(me, { name: 'ada' }), p.data(listNotes, [])]),
+    p.page(home, 'Failed', [p.fail(listNotes, 'Unexpected')]),
+  ])
+  ```
+- A page preview answers those queries under `hozu dev` only (Layers → Previews, or Assets → Screens), on every
+  page while it is on; other queries and mutations run as usual. HZ092: data off the output schema, an undeclared error, a route without a page, a use that
+  does not build.
+

package/skill/topics/content.md

@@ -0,0 +1,37 @@
+# Markdown, images, share images, fonts, preview, offline
+
+- **Markdown:** `npm install @hozu/content` (not in the scaffold), then in `app.ts`
+  `const posts = await loadCollection({ dir: new URL('./content/posts/', import.meta.url), schema })`: one
+  `{ slug, data, html, headings }` per `.md` file. Return them from query resolvers and render `ui.html(post.html)`.
+- **Images:** `ui.img({ src: ui.asset(new URL('./hero.jpg', import.meta.url)), alt, width, height })` (HZ028 without
+  dimensions).
+
+<!-- more -->
+
+- **Collections in detail:**
+  - `slug` is the file name without `.md`.
+  - Only the folder's own files are read, not sub-folders; entries come in file-name order (sort them in the
+    resolver).
+  - `data` is the front matter parsed as YAML 1.2 and checked against `schema`. An unquoted date such as
+    `2026-09-12` stays a string, so `z.iso.date()` fits.
+  - A front matter error or a schema mismatch throws with the file name at startup.
+  - There are no conventional fields: a draft flag or an excerpt is a field in your schema.
+  - `html` is GFM; headings get ids, listed in `headings`.
+  - Style it with your own CSS for the container (the `prose` class needs the Tailwind typography plugin in
+    `app.css`, otherwise HZ026).
+
+- **Images:** with `@hozu/image`, `hozu build` adds WebP `srcset` widths.
+- **Share images:** `head.render → image: ui.og({ title, subtitle })` (needs `app({ og: ogImage })` with `ogImage`
+  from `@hozu/image`); on a static host use `image: ui.asset(new URL('./share.png', import.meta.url))`.
+- **Fonts:** prefer local font files: a local `@font-face` gets a size-matched fallback automatically. A remote font
+  is `@import url('https://fonts.googleapis.com/css2?family=…');` in `app.css` (moved to the top of the output) plus
+  its CSP sources: `app({ csp: { style: ['https://fonts.googleapis.com'], font: ['https://fonts.gstatic.com'] } })`.
+- **Page transitions:** links cross-fade (CSS view transitions, no JS); turn off with
+  `@view-transition { navigation: none; }` in `app.css`.
+- **Preview:** `app({ preview: { secret } })`; `/_hozu/preview?secret=…&path=/posts/a` turns it on; resolvers
+  read `ctx.preview`; preview responses are never cached.
+- **Offline:** `site.offline: route` (a static page) makes a service worker (HZ043).
+- **One collection per language:** a folder per locale (`content/en`, `content/de`), loaded by the query for the
+  page's locale (`head.input`'s second argument).
+- **Images named in front matter** (`cover: night.png`): serve them with a GET endpoint (`output: 'response'`) that
+  reads only the files some entry lists. There is no `public/` folder served at the root.

package/skill/topics/contracts.md

@@ -0,0 +1,36 @@
+# Contracts
+
+A transition that **decides** (a guard, a `navigate`, a `fn()`, a comparison or a computing operator in its values)
+needs a contract; HZ016 prints each missing one, ready to paste:
+`contract(m, { given: { state }, when: [{ send: Event, payload }], expect: { state, changes, effects } })`
+(full example: see --more). Export it from `views.ts`. After a behaviour change, run `hozu check --update-lock`
+and list the accepted `now:` lines in your summary. When a contract fails (HZ015), decide which is intended before
+changing either.
+
+<!-- more -->
+
+- Computing operators: `+ - ?? ?: .length .includes`. Transitions that only copy values need no contract (a contract
+  there is HZ058).
+- `hozu.lock.json` records every transition readably and must equal the computed lock: any difference is HZ057
+  until `hozu check --update-lock` accepts it.
+- A deciding change also needs a contract that fails against the old behaviour (HZ018); renaming or copying a
+  contract does not count.
+- A transition that stops deciding (its guard or `navigate` removed) needs only the lock: `hozu check
+  --update-lock`, then delete the contracts HZ058 names.
+- A transition to `'previous'` needs the state it returns to: `given: { state: 'adding', previous: 'editing' }`.
+- Contracts may be exported from any module the feature lists. When one fails, the choice is between the machine
+  and the contract.
+```ts
+export const addsValid = contract(m, {
+  given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields
+  when: [
+    { send: Add, payload: { title: 'Milk' } },
+    { done: addItem, result: { id: 'i9', title: 'Milk', done: false } },
+  ],                                                 // or { failed: addItem, error: 'Duplicate', data } / { elapse: ms }
+  expect: {
+    state: 'idle',
+    changes: { draft: '' },                          // only what changes; nested objects are patches
+    effects: [{ effect: addItem, input: { title: 'Milk' } }, { navigate: '/items/i9' }],  // default: none
+  },
+})
+```

package/skill/topics/data.md

@@ -0,0 +1,74 @@
+# Data: queries, mutations, tags, fn, resolvers
+
+**First: whose data is it?** It decides `runs`, `scope` and where it is stored. When the request does not say, ask.
+
+| The data | `runs` / `scope` | Stored in |
+|---|---|---|
+| the visitor's own, no sign-in (a watchlist, favourites, settings) | `'browser'` / `'user'` | `localStorage`, in `fetch.ts` (`hozu docs recipes`) |
+| a signed-in user's, on every device | `'server'` / `'user'` + `access` | the app's database |
+| everyone's (posts, a shared board) | `'server'` / `'public'` + a deliberate `access` | the app's database |
+| a public third-party API (quotes, weather) | `'either'` / `'public'` | nowhere: read it |
+
+The arrays in Hozu's examples and scaffolds are stand-ins that keep them short: one list for every visitor, gone on
+restart. Never ship one; replace it with the store above.
+
+```ts
+export const itemsTag = tag({ param: null })                    // tag({ param: z.string() }) → itemTag(id)
+export const listItems = query({
+  input: z.object({}), output: z.array(Item),
+  scope: 'public',                  // 'user' = the session's data (needs project({ session }))
+  freshness: 'static',              // | 'request' | { revalidate: s } | { swr: s } | 'live' | { poll: s }
+  tags: () => [itemsTag()],          // optional; (input) => [...]
+  runs: 'server',                   // where the implementation lives: 'server' | 'browser' | 'either' (required); hozu docs fetch
+})
+export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, scope: 'public',
+  freshness: 'static', tags: (k) => [itemTag(k.id)], runs: 'server' })
+export const addItem = mutation({
+  input: z.object({ title: z.string().min(2, 'Use at least 2 characters') }), output: Item,
+  errors: { Duplicate: z.object({ title: z.string() }) },          // optional: declared failures
+  invalidates: () => [itemsTag()],                                  // refreshes queries with these tags
+  runs: 'server',
+  access: 'anyone',                 // who may run it (required on the server; user queries too): hozu docs auth
+})
+export const visible = fn({                   // computation: pure JS; may call const/function helpers of this module
+  input: z.object({ items: z.array(Item), show: Show }), output: z.array(Item),
+  impl: ({ items, show }) => items.filter((i) => show === 'all' || !i.done),
+})
+```
+```ts
+export default app({ resolvers: resolvers(project, (implement) => [
+  implement(listItems, () => db.items.list()),                     // db: the app's database client
+  implement(getItem, async ({ id }, { fail }) => (await db.items.get(id)) ?? fail('NotFound', { id })),
+  implement(addItem, ({ title }, { fail, session }) => /* … */ ),
+]) })
+```
+- `runs` is required on every query and mutation. `'server'` resolvers live in `app.ts` (or `features/<name>/server.ts`)
+  and get the schema-parsed input; `'browser'` / `'either'` live in `fetch.ts` (`hozu docs fetch`).
+- **Query resolvers only read;** writes happen in mutation and endpoint resolvers (see --more).
+- User data (`scope: 'user'`) is `freshness: 'request'`, `'live'` or `{ poll }` only (HZ049); `'live'` needs tags (HZ050).
+- **Changes on its own** (quotes, a feed): `freshness: { poll: 30 }` reads it again every 30 s (5 to 86400) while a page
+  shows it, also from the browser. `'live'` is for data your own mutations change.
+- Call a `fn` from views or machines: `ui.each(visible({ items, show: ctx.show }), 'id', …)`.
+
+<!-- more -->
+
+## Details
+- A `fn` body may call functions and JSON constants declared in the same module; they are sent to the browser with
+  it. Imported names and `let` state are not (HZ047): pass them as input.
+- Rendering is derived: `scope` and `freshness` decide static, ISR, SWR, streamed or client rendering;
+  `scope: 'user'` data never reaches a cached page (HZ022). A mutation's tags can read only its input.
+- Freshness describes how the data changes, not where it is read; choose it per query. `'static'` (with tags) is
+  for data only your own declared writers change; `'request'` reads every time it is needed (on the server per
+  request, in the browser on mount and on tags; a public one makes its page uncacheable). `'live'` is only for push
+  updates.
+- `invalidates` drives the refresh: after a mutation or endpoint, cached pages and entries with those tags are
+  dropped and the page's queries with those tags are re-read. `endpoint({ …, invalidates: (input) => [tag()] })`
+  applies when it succeeds (use POST; a GET write is HZ062).
+- Writes from outside (a webhook, a job): `await server.revalidate([itemsTag()])` → `{ entries, pages }`.
+- **Why queries only read:** a query that creates a row on read runs again on every request, on prefetch and after a
+  delete (the account comes back). Keep two helpers: `listOf(user)` returns the stored list or `[]` for queries;
+  `ownListOf(user)` creates it, for mutations only.
+- Resolvers in `features/<name>/server.ts` (from the scaffold) are spread into `app.ts`; the input they get has
+  defaults and transforms applied.
+- Every mutation also has `Invalid` = `{ message, fields }` (input failing its schema, or
+  `fail('Invalid', { message, fields: { title: 'Taken' } })`); never declare `Invalid` or `Unexpected` yourself.

package/skill/topics/deploy.md

@@ -0,0 +1,73 @@
+# Deployment
+
+- **One app module:** `project({ app: new URL('./app.ts', import.meta.url) })`; `app.ts` default-exports
+  `app({ resolvers, session?, components?, … })` from `@hozu/runtime-server`. `hozu serve`, `hozu check`, `hozu get`,
+  `hozu browse` and `testApp(app)` all run it, so what the tools verify is what production serves.
+- **Which host:** nobody marks pages static. `npx hozu export` writes every page for a static host (GitHub Pages,
+  Netlify, Cloudflare Pages, Vercel) to `dist/` and exits 1 naming each page or effect that needs a server; then
+  use Node (`npm start`, a Docker image) or Cloudflare Workers.
+- **Node:** `npm start` is `hozu serve` (adapter-node on `PORT`, `HOST`). Docker: `node:22-slim`, `npm ci
+  --omit=dev`, `CMD ["npx", "hozu", "serve"]`.
+- Set `SESSION_SECRET` when the app has sessions: `npm start` (`hozu serve`) runs as production unless `NODE_ENV` is set, and production refuses to start without it. `hozu dev`, `get`, `browse` and `call` do not need it.
+- Workers, several instances, sessions in KV, upgrading: see --more.
+
+<!-- more -->
+
+## Details
+- **App options:** `app({ resolvers: resolvers(project, (implement) => [...]), session?, components?, og?, csp?,
+  onError?, preview? })`. There is no wrapper position: headers go through `project({ http })`, statuses through
+  `head.failed` and endpoint `failed`, the language through the URL.
+- **Node:** adapter-node serves `process.env`, styles and every `ui.asset` (hashed under `/_hozu/a/`). There is no
+  `public/` folder served at the root: a file the page shows is a `ui.asset(new URL(...))`; a file named in data
+  (a cover in front matter) is served by a GET endpoint with `output: 'response'`. `hozu build` writes
+  `dist/public/`, `dist/manifest.json` and `dist/server/render.js`. It compresses answers as they stream (gzip),
+  and framework files with brotli or gzip from the `.br` / `.gz` that `hozu build` writes. Live streams are not
+  compressed. The edge handler leaves compression to the platform.
+- **Edge (Cloudflare Workers, Bun, Deno):** `hozu build --out build` (git-ignore `build/`), then bundle an entry with esbuild and
+  `hozuTransform()` from `@hozu/transform/esbuild` (it gives each app file its own `import.meta.url`, which a
+  Worker lacks). The entry creates the handler on the first request, when the platform's `env` is known:
+  `handler ??= createHandler(app, { manifest, render, env })` from `@hozu/runtime-server`, with
+  `import * as render from './build/server/render.js'`. Serve `build/public` as static assets (wrangler
+  `[assets] directory`). Workers keep no memory between requests: data goes in a database.
+- **Static host:** `npx hozu export [--out dist]` (`@hozu/adapter-static`, in new apps) empties the folder, writes
+  every page without per-request server data plus `.nojekyll`, and prints what it skipped. Pages whose data runs in
+  the browser (`runs: 'browser'` / `'either'`) export completely; a page that calls a server effect is listed
+  (HZ082). A GitHub project site sets `project({ http: { basePath: '/<repo>' } })` and uploads `dist/<repo>`.
+  In code: `exportStatic({ build, styles, resolvers, outDir })`.
+- **Edge and fetch.ts:** a host without `import()` of files passes `createHandler(app, { fetches: async (f) =>
+  modules[f] })` for `runs: 'either'` effects.
+- **Sessions:** the default store keeps sessions in memory per process. Several instances or Workers share
+  `kvSessions(kv, { secret })` (`@hozu/runtime-server`; `kv` has Cloudflare KV's `get` / `put(key, value,
+  { expirationTtl })` / `delete`, so a KV binding fits as is; wrap Redis in those three). On Workers pass it to the
+  handler: `createHandler(app, { manifest, render, env, session: kvSessions(env.SESSIONS, { secret:
+  env.SESSION_SECRET }) })`. Cloudflare KV may take up to a minute to show a sign-out in other regions.
+- **Another store:** implement `SessionStore` (`read`, `write`, `issue`) and pass it as `app({ session })` or the
+  handler's `session`; keep the cookie an opaque signed id (ADR 0043 B).
+
+## Caches and many instances
+- **Bounded caches:** public query results and cached pages are LRU caches, at most 10,000 entries and 5,000 pages
+  per process. Change the bounds with `app({ dataCache: memoryDataCache({ maxEntries }) })` (`@hozu/data`) and
+  `app({ cache: memoryCache({ maxPages }) })` (`@hozu/runtime-server`). `server.stats()` reports
+  `{ dataEntries, pages, evictions }`.
+- **More than one instance:** each instance caches on its own, so a mutation on one must tell the others. Pass
+  `app({ bus: httpBus({ peers: [every instance's base URL, this one included], secret: process.env.BUS_SECRET }) })`
+  (`@hozu/runtime-server`; signed `POST /_hozu/invalidate`, 32+ character secret). The others drop the tagged pages
+  and data and push to their live clients. Messages carry tags, never data.
+- **A broker instead of peer URLs:** implement `InvalidationBus` (`publish(tags)`, `subscribe(onTags)`):
+  ```ts
+  const pub = createClient({ url }); const sub = pub.duplicate()   // e.g. redis
+  await Promise.all([pub.connect(), sub.connect()])
+  const bus: InvalidationBus = {
+    publish: (tags) => void pub.publish('hozu', JSON.stringify(tags)),
+    subscribe: (onTags) => {
+      void sub.subscribe('hozu', (m) => onTags(JSON.parse(m)))
+      return () => void sub.unsubscribe('hozu')
+    },
+  }
+  ```
+- `app({ staticTtl: 300 })` re-reads `'static'` data and pages after 300 s, in case a bus message is lost; off by
+  default.
+
+## Upgrading Hozu
+`npx -p @hozu/cli@latest hozu migrate` (preview with `--dry-run`), then run the `next:` lines it prints: install, and
+`npx hozu migrate` again, which checks the IR is unchanged and runs `hozu check`. Never raise `@hozu/*` by hand.

package/skill/topics/diagnostics.md

@@ -0,0 +1,99 @@
+# Hozu diagnostics
+
+Every diagnostic carries `file:line`, a cause and a fix, and often a snippet or patch. Apply the fix; do not work
+around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and the topic to read.
+
+- Errors fail `hozu check`. Warnings (HZ010, HZ019, HZ025, HZ036, HZ056, HZ058, HZ061, HZ062, HZ063, HZ075, HZ076, HZ077, HZ080, HZ083, HZ084, HZ086, HZ087, HZ089, HZ090) do not, but each one names something to decide.
+- A warning you keep on purpose goes in `project({ accept: [{ code, at, reason }] })`; errors cannot be accepted.
+
+<!-- more -->
+
+| Code | Meaning | Usual fix |
+| --- | --- | --- |
+| HZ001 | state unreachable | add a transition to it or delete it |
+| HZ002 | event handled nowhere | handle it in a state or remove it |
+| HZ003 | unknown effect / reference | export it from a module the feature lists in `declarations`, or fix the name (the patch suggests one) |
+| HZ004 | a declared error is not handled | add every `failed` key, plus `Unexpected`, in `invoke` and `ui.query` |
+| HZ005 | a node sends an event in a state (without `invoke`) that does not handle it | `ignore: [Event]` in that state, or show the node only via `when` |
+| HZ006 | crossing a feature boundary | import the feature and use its `exports` |
+| HZ007 | unknown effect / reference | export it from a module the feature lists in `declarations`, or fix the name (the patch suggests one) |
+| HZ008 | a path does not exist in the schema | fix the property name |
+| HZ009 | a guardless transition shadows later ones | put guarded transitions first |
+| HZ010 (warning) | a state has no way out (not final; no `on`, `invoke` or `after`) | mark it `final: true` or add a transition out of it |
+| HZ011 | building twice gave different IR | keep time, randomness and mutable state out of builder callbacks |
+| HZ012 | a schema from another library than the project's adapter | write it with the project's schema library (`project({ schema })`) |
+| HZ013 | a declaration registered twice: a second machine (or messages) in a feature, or a name another feature already declares | keep one; reach the other feature through `imports` and its `exports` |
+| HZ014 | wrong builder output, or a method called on data (`.map`, `.toUpperCase()`) | follow the builder signature; lists: `ui.each`; computation: a `fn()` |
+| HZ015 | a contract fails / contract data does not match its schema | fix the machine or the contract (decide the intended behaviour first) |
+| HZ016 | a transition that decides (guard, `navigate`, a `fn`, comparison or `+ - ?? ?: .length .includes` in a value) has no contract | add the contract from the snippet |
+| HZ017 | a contract fails / contract data does not match its schema | fix the machine or the contract (decide the intended behaviour first) |
+| HZ018 | a deciding transition changed (fields first, then `was:` / `now:`) and no covering contract fails against the old behaviour | change or add a contract that specifies the new behaviour; renaming or copying one does not count |
+| HZ019 (warning) | `invalidates` names a tag no query carries | tag the affected query, or remove the invalidation |
+| HZ020 | user-scoped data, but the project declares no session | declare `project({ session })`, or make the query public |
+| HZ021 | a query, mutation or endpoint without a resolver | `implement(...)` it in the resolvers of `app.ts` |
+| HZ022 | user data in a cacheable region | keep `scope: 'user'` queries out of cached pages |
+| HZ023 | a page's `assert` does not hold for its derived render plan | change the data's scope or freshness, or the assertion |
+| HZ024 | route params mismatch (keys, or a schema that does not fit `:x?`/`:x+`/`:x*`) / page with params but no `entries` (a user-scoped head is private: no sitemap, no warning) | align them / add `entries` |
+| HZ025 (warning) | route params mismatch (keys, or a schema that does not fit `:x?`/`:x+`/`:x*`) / page with params but no `entries` (a user-scoped head is private: no sitemap, no warning) | align them / add `entries` |
+| HZ026 | a class produces no CSS | fix the Tailwind class |
+| HZ027 | a DOM field used outside an event, or wrong for this event | read `ui.dom.*` only in `ui.send` payloads |
+| HZ028 | `img` without width/height | add both |
+| HZ029 | a client component's module is missing, or a handler for an event it does not emit | create the module (`hozu add component … --client`); handle declared `emits` only |
+| HZ030 | `ui.html` of untrusted data | render text instead |
+| HZ031 | a literal not allowed by its schema | use an allowed value (the patch suggests one) |
+| HZ032 | internal link or form action written as a string | `ui.link(route, params)` / `ui.link(endpoint)` |
+| HZ033 | DOM text into an enum, number or boolean field | a `<select>`, radios or submit buttons with enum values; in a form, a flag through `ui.dom.formAll` and numbers parsed in the mutation input |
+| HZ034 | a state both handles and ignores an event | remove it from one of the two |
+| HZ035 | search schema is not a flat object of scalars with defaults | `z.object({ key: scalar.default(…) })` |
+| HZ036 (warning) | a form needs JavaScript: it reads other DOM values, or starts a `runs: 'browser'` mutation | read its values with `ui.dom.form('name')` / `ui.dom.formAll('name')`; a browser mutation needs JS by design |
+| HZ037 | a redirect is not a path, hides a page or another redirect, or targets an unknown route | change or remove the `from` key; point `to` at `ui.link(...)` |
+| HZ038 | `http.headers` sets a header the framework owns, or an invalid name/value | remove it (`cache-control` is derived; CSP is `app({ csp })`) |
+| HZ039 | `basePath` is not `''` or `/segment[/segment…]` | e.g. `'/shop'`, no trailing slash |
+| HZ040 | a locale lacks a message, or uses other `{placeholders}` | add/translate the key in that locale |
+| HZ041 | a machine uses a message, `ui.format` or `locale` | store a code in context; choose the message in the view |
+| HZ042 | `site.locales` empty / missing `site.lang` / not a canonical tag, or `ui.alternate` of an undeclared locale | fix the list (`'zh-TW'`, not `'zh_tw'`) |
+| HZ043 | `site.offline` has params, no page, or per-request data | point it at a static page, or remove `offline` |
+| HZ044 | a feature file was loaded without the Hozu transform | run node with `--import @hozu/transform/register` (`npm start` does), or add `hozuTransform()` to Vite / Vitest |
+| HZ045 | no `project({ app })`, its default export is not `app(…)`, or views use client components and `app()` has no bundle | `export default app({ resolvers, components: bundleComponents })` |
+| HZ046 | an endpoint path is reserved, has params or collides; an error without a status, or with one an endpoint error cannot answer; a form posting to it with another method or an undeclared field | a static path such as `/api/…` (patch); map every error in `failed` to 400, 401, 403, 404, 409, 410, 422 or 429 |
+| HZ047 | a `fn` body uses an imported name or `let` state (it is sent to the browser as source) | pass the value as input, or write it as a `const` helper in the module |
+| HZ048 | `seed` names a field the context lacks, has no machine or route, or two views on one page seed a machine | seed top-level context fields, on one view per page |
+| HZ049 | a `scope: 'user'` query is cached (`'static'`, `revalidate`, `swr`) | `freshness: 'request'` (patch), or `'live'` for push |
+| HZ050 | a `'live'` query has no tags | add the tags its writers invalidate, or use `'request'` |
+| HZ051 | `head.failed` misses a declared error of the head query, or maps another one | choose per error: a route (303), `403`, `404` or `410` (an intent decision: no patch) |
+| HZ052 | a route that no page renders | link to the endpoint with `ui.link(endpoint, input)` (patch), or add its `ui.page` |
+| HZ053 | (runtime) an endpoint answered `text/html`: a 500 | make it a `ui.page`; statuses and redirects go through `head.failed` |
+| HZ054 | `ui.dom.form` reads one value of a list field or of a repeated name | `ui.dom.formAll('name')` (patch) |
+| HZ055 | a form read names no control of the form | the name it suggests (patch), or add the control |
+| HZ056 (warning) | a submit button also sends on click | `name`/`value` on the button, read in submit; or `type: 'button'` |
+| HZ057 | `hozu.lock.json` differs from the computed lock (new, removed or copy-only changes, contract maps, a missing or 0.7 file) | if intended, `hozu check --update-lock`, then list the accepted `now:` lines in your summary |
+| HZ058 (warning) | contracts that fire only copy-only transitions and evaluate no guard | none needed: the lock entries it names review those transitions |
+| HZ059 | data reached plain JavaScript: a plain helper, a global (`Boolean`, `Object.keys`, `String`…), `typeof`, a spread or `in` | make the helper a `part()`; for a global use an operator or a `fn()` |
+| HZ060 | a page route starts with a locale segment (`/de/…` under `site.locales`) | rename the route (patch); the locale prefix is added for you |
+| HZ061 (warning) | a form-fed event payload declares limits | move them to the mutation input |
+| HZ062 (warning) | a GET endpoint declares `invalidates` | `method: 'POST'`, or keep it on purpose (e-mail links) |
+| HZ063 (warning) | as HZ055, in a form holding `ui.html`, a client component or another view | as HZ055 |
+| HZ064 | two contracts with identical IR | remove one (patch) |
+| HZ070 | a component's render references a declaration (event, query, route, message…) | pass a `Send` through `on`, an `Href` prop, text as a prop or slot |
+| HZ071 | a variant from data | make it a prop, styled through an attribute (`aria-pressed:`, `data-[x=y]:`) |
+| HZ072 | a caller's `class` sets a property the component owns | declare a variant; a one-off ends with `!` (snippet) |
+| HZ073 | `!` inside a component / a leading `!x` | remove it (patch in the tv config, snippet in the render) / write `x!` (patch) |
+| HZ074 | `!` inside a component / a leading `!x` | remove it (patch in the tv config, snippet in the render) / write `x!` (patch) |
+| HZ075 (warning) | a caller's inherited class (colour, font) is hidden by an inner element | a variant, or style the inner element |
+| HZ076 (warning) | a component owns a margin | remove it (patch); outer spacing is the caller's |
+| HZ077 (warning) | `!` on a property the component does not own | remove the `!` (patch) |
+| HZ078 | the kit's `tv.ts` config differs from the design system | `hozu add kit <id> --sync` |
+| HZ079 | two classes of one element set the same property | the patch: a complementary toggle, or remove the one that never wins |
+| HZ080 (warning) | a `part()` view inlined by two features | the snippet: the same `ui.component` in a kit |
+| HZ081 | an effect's `runs` and `fetch.ts` disagree: no export, an extra one, a `'server'` effect in it, `'either'` with user data, a Node-only import | export the effect in `fetch.ts`, or `runs: 'server'` with a resolver (`hozu docs fetch`) |
+| HZ082 | browser data where only the server can go (a page `head`, `entries`), or a browser mutation invalidating a server-cached tag | the patch: `runs: 'server'`; or `freshness: 'request'` on the cached query |
+| HZ083 (warning) | fetch.ts calls an origin (an absolute URL in it) that the feature's `connect` does not list: the browser's CSP blocks it | add the origin to `feature({ connect })` (the fix lists the whole line); `{ env: 'NAME' }` for a URL from public env |
+| HZ084 (warning) | a public env variable named like a secret (`SECRET`, `TOKEN`, `PASSWORD`, `PRIVATE`, `…_KEY`): public values reach the browser | move it to `env.server`; only a value made to be published (a publishable key) stays public, named `PUBLIC_…` |
+| HZ085 | `env.internal` maps a name that is not a public variable, or to one that is not a server variable; or `site.url: { env }` names an undeclared variable | declare both: the public URL in `env.public`, the internal one in `env.server` |
+| HZ086 (warning) | an env file listed in `env.files` exists and git does not ignore it | add it to `.gitignore`; commit `.env.example` (`npx hozu env --example`) instead |
+| HZ087 (warning) | an entry of `project({ accept })` matches no warning, names an error, or has no reason | remove the entry when the warning is gone; fix an error instead of accepting it; give every entry a reason |
+| HZ088 | a server-run `scope: 'user'` query or a server-run mutation without `access`, or an access rule that reads a field the output or session does not have | say who may run it: `access: 'signedIn'`, `{ owner: { row, session } }`, `{ allow: ({ session }) => … }`, or `'anyone'` |
+| HZ089 (warning) | `access` on a public query or a browser-run effect, where the server cannot enforce it | remove it: a public query never sees the session, and a browser-run effect is guarded by the API it calls |
+| HZ090 (warning) | `access: 'anyone'` on a `scope: 'user'` query: every visitor, signed in or not, may read it | say who may read it (`'signedIn'`, `{ owner: { row, session } }`), or accept the warning with a reason |
+| HZ091 | a query with `owner` access returned rows the visitor does not own (reported at run time) | read only the visitor's rows in the resolver (filter by the session); production drops the extra rows and logs this |
+| HZ092 | a preview in `project({ previews })` no longer fits the app: data off its query output schema, an error the query does not declare, a route without a page, or a component use that does not build | update the preview to the current schema, error, page or component (previews are for people: they never ship) |

package/skill/topics/endpoints.md

@@ -0,0 +1,39 @@
+# Endpoints (webhooks, JSON APIs, auth callbacks, downloads)
+
+```ts
+export const exportNotes = endpoint({ method: 'GET', path: '/api/export',        // exported from model.ts
+  input: z.object({ format: z.enum(['json', 'csv']).default('json') }), output: z.object({ notes: z.array(Note) }),
+  errors: { Unauthorized: z.object({ message: z.string() }) }, failed: { Unauthorized: 401 } })
+implement(exportNotes, (input, { session, fail }) =>                             // in the app's resolvers
+  session ? { notes: notesOf(session.user) } : fail('Unauthorized', { message: 'Sign in' }))
+```
+- GET input comes from the query string (coerced by the schema), POST input from a JSON or form body; invalid input
+  answers 400. `fail(name, payload)` answers `failed[name]`; every declared error is mapped (HZ046).
+- `output`: a schema (sent as JSON), `'redirect'` (return `redirect(ui.link(route, params))` from the context, 303) or
+  `'response'` (a web `Response`, for files). Never HTML: a page is a `ui.page` (HZ053).
+- Links: `ui.link(getEndpoint, input)` is the URL of a GET endpoint; `ui.form({ method: 'post', action:
+  ui.link(postEndpoint) }, [...])` posts a native form, whose fields the input declares (HZ046).
+- Paths are static and outside pages, redirects, `/_hozu/` and the derived `/sitemap.xml`, `/robots.txt` and
+  `/manifest.webmanifest` (HZ046).
+
+<!-- more -->
+
+- Error bodies: invalid input is `{ error: 'Invalid', message, fields }`; a `fail` is `{ error, message, ...every field its error schema declares }`
+  (statuses 400 401 403 404 409 410 422 429).
+- `'redirect'` keeps the basePath. `'response'` is for files and protocol bodies that are neither JSON nor HTML. A
+  `text/html` response is a 500 with HZ053: a page is a `ui.page` with `head.failed`.
+- `input: 'raw'` (POST only) skips parsing and gives the resolver `bytes` (a `Uint8Array`), for signed webhooks.
+- Headers and the raw request: the resolver's context has `request` (a web `Request`). A bearer token:
+  `implement(postItem, (input, { request, fail }) => request.headers.get('authorization') === `Bearer ${token}` ? … : fail('Unauthorized', {}))`
+  with `errors: { Unauthorized: z.object({}) }, failed: { Unauthorized: 401 }`. Try it from the DevTools API drawer
+  (Endpoints: path, body and your own headers) or `curl`. Queries and mutations read no headers: identity is the session.
+- `setSession(value)` works on GET too (auth callbacks); OIDC form_post callbacks use `output: 'redirect'`.
+- `invalidates: (input) => [itemsTag()]` refreshes like a mutation's when the endpoint succeeds. A GET endpoint with
+  `invalidates` is HZ062 (warning).
+- A GET endpoint link takes flat scalar input (HZ035). Another feature links to an endpoint only when it is in
+  `exports` and imported (HZ006).
+- HZ046 for a path comes with a patch. Responses carry `nosniff` and a referrer policy. Cross-site browser POSTs are
+  rejected; server-to-server calls (no `Origin`) are accepted.
+- **What an endpoint cannot do yet:** methods are GET and POST; paths are static (a variable part goes in the
+  input: `POST /api/bookings/cancel` with `{ id }`); a success answers 200; an error answers its status with
+  `{ error, ...data }` (nested objects are fine, `error` is reserved); there are no custom response headers.