@hozu/cli 0.18.2 → 0.19.0

package/skill/topics/feature.md

@@ -0,0 +1,90 @@
+# A new feature: the files and a complete example
+
+Start with `npx hozu add feature <name> --page / --with auth,detail,toggle,filter,remove` and edit the texts it
+lists. It writes the files below and the first `hozu.lock.json`.
+
+Files: `features/<name>/model.ts`, `views.ts`, `feature.ts`; resolvers in `app.ts`. Relative imports end in
+`.ts`. Callbacks are ordinary TypeScript, but methods on data (`.map`…) are not: use `ui.each` and a `fn()`.
+
+## A feature in one screen
+```ts
+// model.ts
+export const Item = z.object({ id: z.string(), title: z.string(), done: z.boolean() })
+export const Add = event({ payload: z.object({ title: z.string() }) })
+export const itemsTag = tag({ param: null })
+export const listItems = query({ input: z.object({}), output: z.array(Item), scope: 'public',
+  freshness: 'static', tags: () => [itemsTag()], runs: 'server' })        // resolvers in app.ts
+export const addItem = mutation({ input: z.object({ title: z.string().min(2, 'Too short') }), output: Item,
+  errors: { Duplicate: z.object({ title: z.string() }) }, invalidates: () => [itemsTag()], runs: 'server',
+  access: 'anyone' })                                                  // who may run it: hozu docs auth
+export const items = machine({
+  context: z.object({ draft: z.string(), error: z.string().nullable() }),
+  initialContext: { draft: '', error: null },
+  initial: 'idle',
+  states: ({ ctx }) => ({
+    idle: { on: [on(Add, { target: 'adding', assign: (e) => { ctx.draft = e.title; ctx.error = null } })] },
+    adding: {
+      invoke: invoke(addItem, {
+        input: { title: ctx.draft },
+        done: { target: 'idle', assign: () => { ctx.draft = '' } },
+        failed: {
+          Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already listed' } },
+          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+        },
+      }),
+    },
+  }),
+})
+// views.ts
+export const Board = ui.view({
+  machine: items,
+  render: ({ ctx, when }) =>
+    ui.main({ class: 'mx-auto max-w-xl' }, [
+      ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title') }) } }, [
+        ui.input({ name: 'title', required: true, value: ctx.draft }),
+        ui.button({ type: 'submit' }, ['Add']),
+      ]),
+      ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error]),
+      when(['adding'], [ui.p({ 'aria-busy': 'true' }, [`Adding ${ctx.draft}…`])]),
+      ui.query(listItems, {}, {
+        ready: (list) => ui.ul({}, [ui.each(list, 'id', (i) => ui.li({}, [i.title, i.done ? ' ✓' : '']))]),
+        failed: { Unexpected: () => ui.p({ role: 'alert' }, ['Unavailable']) },
+      }),
+    ]),
+})
+// feature.ts
+import * as model from './model.ts'
+import * as views from './views.ts'
+export const todos = feature({ id: 'todos', intent: { summary: 'A to-do list' }, declarations: [model, views] })
+```
+Every declaration a listed module exports is registered under its name; schemas and helpers are ignored. Resolvers:
+`implement(addItem, ({ title }, { fail }) => exists ? fail('Duplicate', { title }) : save(title))`.
+
+<!-- more -->
+
+## How it works
+- A feature is **declarations**: events, queries / mutations (the only side effects), one machine, views,
+  contracts. Builders record them as data (an IR) that is validated, then rendered on the server. Only views bound
+  to the machine ship JS.
+- **Callbacks are ordinary TypeScript** (`render`, `guard`, `assign`, `navigate`, `ui.each` / `ui.query`
+  callbacks): `===`, `!==`, `<`, `&&`, `||`, `!`, `??`, `c ? a : b`, template strings, `+`, `-`, `.length`, and in
+  `assign`, `ctx.x = v`, `ctx.n += 1`, `ctx.list.push(v)`, `ctx.list = ctx.list.filter((i) => i.id !== e.id)`.
+  Methods on data (`.map`, `.toUpperCase()`…) are not: use `ui.each` for lists and a `fn()` for computation.
+- A mutation runs when the machine **enters** a state whose `invoke` calls it; that state drops other events, and
+  `done` / `failed` leave it.
+- A filter in the URL starts the machine: `seed: ({ search }) => ({ q: search.q })` on the view, then read `ctx.q`.
+  `machine({ on })` holds transitions every idle state shares; `fn` bodies may call helpers from the same module.
+- Reusable view logic is a `part((…) => …)`, inlined where it is used (`hozu docs views`).
+
+## Files
+```
+hozu.config.ts  project({ schema, app, site, routes, pages, features })  routes.ts  route() declarations
+features/<name>/model.ts  schemas, events, effects, fns, machine        views.ts  views, contracts
+features/<name>/feature.ts  feature({ declarations: [model, views] })    app.ts  app({ resolvers })
+ui/kit.ts  ui.kit({ id: 'ui', components }) — Button, Input, Field…      ui/*.ts  one component each
+```
+Relative imports end in `.ts`. The example above uses plain elements so it runs in any app; with a kit the input
+and button are `ui.use(Input, …)` and `ui.use(Button, …)`, as in `example/` (`hozu docs components`).
+- **Sharing with another feature:** the owner lists what it shares, `exports: [listRooms, roomsTag]`, next to
+  `declarations`; the user lists the owner, `imports: [bookings]`. Imports go one way (each `feature.ts` imports
+  the other's module): when two features need each other's data, one of them owns it and exports it.

package/skill/topics/fetch.md

@@ -0,0 +1,67 @@
+# Where effects run: runs and fetch.ts
+
+Every query and mutation declares `runs` (required, no default): what its implementation needs.
+
+| `runs` | The implementation needs | Implemented in |
+|---|---|---|
+| `'server'` | a database, a server secret, the session | `app.ts` / `features/<name>/server.ts` resolvers |
+| `'browser'` | the visitor's own data in the browser (a list in `localStorage`), or browser credentials (a token, an OIDC library, the API's own cookies) | `features/<name>/fetch.ts` |
+| `'either'` | nothing special: a public API, or your own API with CORS | `features/<name>/fetch.ts` |
+
+```ts
+// fetch.ts: one export per effect, under its name; the model import is type-only
+import { implement } from '@hozu/core/fetch'
+import type * as model from './model.ts'
+export const searchRepos = implement<typeof model.searchRepos>(async ({ q }, { fail, signal, env }) => {
+  const r = await fetch(`${env.API_URL}/search/repositories?q=${encodeURIComponent(q)}`, { signal })
+  return r.ok ? (await r.json()).items : fail('Unavailable', {})
+})
+export const myRepos = implement<typeof model.myRepos>(async (_, { fail, signal }) => {
+  const token = localStorage.getItem('gh-token')
+  if (!token) return fail('Unauthorized', {})
+  const r = await fetch('https://api.github.com/user/repos', { headers: { authorization: `Bearer ${token}` }, signal })
+  return r.status === 401 ? fail('Unauthorized', {}) : r.json()
+})
+```
+- The feature names the module: `feature({ …, fetch: new URL('./fetch.ts', import.meta.url) })`; `app()` needs
+  `components: bundleComponents` (HZ045). A missing or extra export is HZ081.
+- Browser-held data (`localStorage`, a token, the API's own cookies) is `scope: 'user'`; `'either'` needs
+  `scope: 'public'` (HZ081).
+- fetch.ts runs in the browser: no Node-only imports, no secrets; `env` is the public env only.
+- Every other origin fetch.ts calls goes in `feature({ connect: ['https://api.github.com', { env: 'API_URL' }] })`
+  (HZ083); the API must allow the page's origin (CORS), otherwise use `runs: 'server'`.
+
+<!-- more -->
+
+## The model side
+```ts
+// model.ts
+export const searchRepos = query({ input: z.object({ q: z.string() }), output: Repos,
+  errors: { Unavailable: z.object({}) }, scope: 'public', freshness: 'request', runs: 'either' })
+export const myRepos = query({ input: z.object({}), output: Repos, errors: { Unauthorized: z.object({}) },
+  scope: 'user', freshness: 'request', tags: () => [reposTag()], runs: 'browser' })
+export const star = mutation({ input: z.object({ repo: z.string() }), output: z.object({}),
+  invalidates: () => [reposTag()], runs: 'browser' })
+// feature.ts
+export const repos = feature({ id: 'repos', intent, declarations: [model, views],
+  fetch: new URL('./fetch.ts', import.meta.url) })
+```
+
+## Details
+- **What runs where:** `'either'` is server-rendered on first paint (data in the HTML, cached per `freshness`), and
+  later in-page reads and mutations call the API from the browser, never through the server. `'browser'` renders its
+  `pending` branch on the server and reads after hydration. `'server'` always goes through the server.
+- **Checked at the boundary:** inputs and outputs are checked against their schemas in the browser too; a wrong
+  output is `Unexpected` with its path, `fail(Name, data)` is the declared error.
+- `env` is the parsed `public` environment; server env and the session never reach fetch.ts.
+- **fetch.ts runs in the browser** (and on the server for `'either'`). A token read in the browser is sent only to
+  the API, never to your own server.
+- **CSP:** Hozu adds every `connect` origin to the page's CSP `connect-src` (an `{ env }` entry reads that public env
+  variable's URL at startup). An absolute URL in fetch.ts that `connect` does not list is HZ083; a call blocked at
+  run time shows in `hozu browse`.
+- The bundle (`bundleComponents`) carries fetch.ts for the browser.
+- **Rules:** HZ081 (a missing or extra export, or `'either'` with user data), HZ082 (a `'browser'` query in a page
+  `head` or `entries`; a browser mutation that invalidates a tag a server-cached query reads), HZ036 (a form that
+  starts a `'browser'` mutation needs JS).
+- **Static host:** pages with only `'browser'` / `'either'` data export completely; `exportStatic` lists in
+  `needsServer` the server effects a page would still call.

package/skill/topics/forms.md

@@ -0,0 +1,47 @@
+# Forms
+
+- **Works without JavaScript** when the submit payload reads only `ui.dom.form('name')`, `ui.dom.formAll('name')`,
+  literals, context, params and search (else HZ036 warns). Put every value the submit needs in a named field.
+```ts
+ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) } }, [
+  ui.label({ for: 'title' }, ['Title']),
+  ui.input({ id: 'title', name: 'title', required: true, minlength: 2, value: ctx.draft,
+    'aria-invalid': ctx.fields.title !== null, 'aria-describedby': 'title-error',
+    on: { input: ui.send(Draft, { text: ui.dom.value }) } }),
+  ui.select({ name: 'kind', 'aria-label': 'Kind' }, kinds.map((k) => ui.option({ value: k, selected: ctx.kind === k }, [k]))),
+  ui.button({ type: 'submit' }, ['Add']),
+])
+ui.p({ id: 'title-error', class: 'text-sm text-rose-600' }, [ctx.fields.title])
+```
+- **Field errors:** context `fields: z.object({ title: z.string().nullable() })`, reset on submit
+  (`ctx.fields = { title: null }`), and `failed.Invalid: { target: 'idle', assign: (e) => { ctx.fields = e.fields } }`.
+  Limits live in the mutation's input schema (`z.string().min(2, '…')`), never in the event payload (HZ061).
+- **Server error:** a declared error sets `ctx.error`; show `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`.
+- **Enum from a select:** fills an enum field only when every literal option value is a member (HZ033).
+
+<!-- more -->
+
+- **Without JavaScript,** the server runs the same machine for a native post, then redirects or re-renders with the
+  result (e.g. a `<select name="kind">` carries the kind).
+- **With the app's kit** (as in `example/`): a `Field` with a `control` slot holds the label, the input and its error.
+```ts
+ui.use(Field, { props: { for: 'title', label: 'Title', error: ctx.fields.title, errorId: 'title-error' },
+  slots: { control: ui.use(Input, { props: { id: 'title', name: 'title', value: ctx.draft, required: true,
+    invalid: ctx.fields.title !== null, describedby: 'title-error' }, on: { input: ui.send(Draft, { text: ui.dom.value }) } }) } }),
+ui.use(Button, { props: { type: 'submit' } }, ['Add']),
+```
+- **Limit messages:** `z.string().min(2, 'Use at least 2 characters')`.
+- **Clear after success:** bind `value: ctx.draft` and reset it in `done`.
+- **Per-item actions without JS:** wrap each button in its own small form.
+- **Enum source:** `ui.dom.form('kind')` or `ui.dom.value`.
+- **Several values:** `ui.dom.formAll('ids')` is every value of the name in tree order (`[]` when none) for checkbox
+  groups, `select multiple` and controls inside `ui.each`, into a list field; `ui.dom.form(name)` is the first (HZ054).
+- **Which button:** give submit buttons `name` and a literal `value` and read `ui.dom.form('action')` in the form's
+  submit; JS and no-JS read the same value. Into an enum only when every submit button of the form has that name and
+  a member value, else make the field nullable (HZ033). No `on.click` on a submit button (HZ056).
+- **Controls outside the form** (forms cannot nest): `const bulk = ui.formRef()` at module level,
+  `ui.form({ ref: bulk, … })`, `ui.input({ form: bulk, … })`; a string `form` is HZ014, a name no control has HZ055.
+- **A flag or a number:** a checkbox posts `'on'` only while checked: `ui.dom.formAll('remember')` into
+  `z.array(z.string())`, or a radio pair. Send numbers as text and parse them in the mutation input (`z.coerce.number()`).
+- **Invalid without JS:** a native post whose payload or mutation input fails re-renders with 400 through
+  `failed.Invalid`, like the JS submit.

package/skill/topics/http.md

@@ -0,0 +1,21 @@
+# HTTP
+
+Without `http`, the site is served at `/` without trailing slashes (`/about/` answers 308 → `/about`).
+`project({ http: { basePath, trailingSlash, redirects, headers } })` changes that (see --more). There are no
+rewrites: one URL has one owner. Your own HTTP routes: `hozu docs endpoints`.
+
+<!-- more -->
+
+```ts
+http: {
+  basePath: '/shop',                   // every URL and /_hozu/* move under it (HZ039)
+  trailingSlash: 'always',             // or 'never'; the other form answers 308
+  redirects: {                         // keyed by the old path; never a path a page owns (HZ037)
+    '/blog/:slug': { to: (p) => ui.link(post, { slug: p.slug }), permanent: true },
+    '/docs': { to: 'https://docs.example.com', permanent: false },
+  },
+  headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // not cache-control (HZ038)
+},
+```
+Server options live in the app module: `app({ resolvers, session?, components?, onError?, csp?, og?, preview? })`.
+A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { script: ['https://…'] }` adds sources.

package/skill/topics/i18n.md

@@ -0,0 +1,34 @@
+# Languages
+
+- **The URL holds the language:** `site: { lang: 'en', locales: ['en', 'de'], … }` keeps `/posts/a` for `en` and
+  prefixes the others (`/de/posts/a`). Routes and `ui.link` stay locale-free. No cookie, session field or rewrite.
+- Switch: `ui.a({ href: ui.alternate('de') }, ['Deutsch'])`.
+- `export const text = ui.messages('en', { en: { saved: '{count} saved' }, de: { saved: '{count} gespeichert' } })`
+  in a listed module; `text.saved({ count })` in views. Every locale needs every key (HZ040).
+- Machines never hold translated text (HZ041): store a code.
+- **Data per language:** `locale` (in every view, and the second argument of `head.input` / `head.render`) goes into
+  the query input: `ui.query(listPosts, { locale })`; `head: { input: (params, locale) => ({ slug: params.slug,
+  locale }) }`. It is typed `string`: declare the input `z.string()`, or narrow it with `locale as Locale`.
+
+<!-- more -->
+
+## Details
+- Reload, sign-in and sign-out keep the language, because every link and `navigate` resolves `ui.link` in the
+  page's locale.
+- `/en/posts/a` answers 308 `/posts/a`. There is no `Accept-Language` redirect: a new visit to an unprefixed URL
+  shows `site.lang`. Contracts expect the default URLs. `<html lang>`, hreflang and the sitemap are derived. A page
+  route starting with a locale segment is HZ060.
+- A toggle: `locale === 'en' ? ui.alternate('de') : ui.alternate('en')`.
+- Messages: use `text.title` or `text.saved({ count })` in views and `head.render`; every locale needs the same
+  `{placeholders}` (HZ040). Plurals: `'{n, plural, =0 {none} one {# item} other {# items}}'`.
+- Machines store a code and the view chooses the message.
+- `ui.format.number(x, { style: 'currency', currency: 'EUR' })`, `ui.format.date(x, { dateStyle: 'medium' })`,
+  `ui.format.relative(n, 'day')`, `ui.format.list(xs)`. `locale` is in every view.
+- Resolvers have no locale of their own; it reaches them only through the input. The sitemap lists one entry per
+  `entries` input in every locale.
+- `ui.format.date` takes an ISO string or a timestamp and formats it in the page's locale, in the time zone of the
+  machine that renders it. A date without a time (`'2026-09-12'`) is midnight UTC: pass `{ timeZone: 'UTC' }` so
+  every server and browser shows the same day.
+- A form's `Invalid` messages come from the schema in one language: store `invalid: true` (or a code) in context and
+  choose the text in the view.
+

package/skill/topics/machine.md

@@ -0,0 +1,78 @@
+# Machine (one per feature)
+
+```ts
+export const m = machine({
+  context: z.object({ draft: z.string(), error: z.string().nullable() }),
+  initialContext: { draft: '', error: null },
+  initial: 'idle',
+  states: ({ ctx }) => ({
+    idle: { on: [on(Add, { target: 'adding', assign: (e) => { ctx.draft = e.title } })] },
+    adding: {
+      invoke: invoke(addItem, {
+        input: { title: ctx.draft },
+        done: { target: 'idle', assign: () => { ctx.draft = '' } },
+        failed: { Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } } },
+      }),
+    },
+  }),
+})
+```
+- Events: `export const Add = event({ payload: z.object({ title: z.string() }) })`.
+- **assign** writes context: `ctx.x = v`, `ctx.n += 1`, `ctx.list.push(item)`,
+  `ctx.list = ctx.list.filter((i) => i.id !== e.id)`.
+- **guard** returns a condition: `on(Add, { target: 'adding', guard: (e) => e.title.length >= 2 })`; the first
+  matching guard wins.
+- **invoke** runs a mutation on entry; the state drops events it does not handle. `failed` lists every declared error
+  of the mutation plus `Unexpected` (`Invalid` optional, `hozu docs forms`).
+- Do not handle the busy event in the busy state: a transition to the same state re-runs its `invoke`.
+- `target: 'previous'` (or `done: 'previous'`) returns to the state the machine came from, so a busy state entered
+  from two modes (viewing, editing) needs no copy per mode.
+
+<!-- more -->
+
+The full form: shared transitions, guards, `navigate`, errors, a timer.
+
+```ts
+export const m = machine({
+  context: z.object({ draft: z.string(), error: z.string().nullable(), target: z.string() }),
+  initialContext: { draft: '', error: null, target: '' },
+  initial: 'idle',
+  on: ({ ctx }) => [on(Draft, { assign: (e) => { ctx.draft = e.text } })],   // shared by every state without invoke
+  states: ({ ctx }) => ({
+    idle: {
+      on: [
+        on(Add, { target: 'adding', guard: (e) => e.title.length >= 2 }),   // first matching guard wins
+        on(Add, { target: 'idle', assign: () => { ctx.error = 'Too short' } }),
+        on(Remove, { target: 'removing', assign: (e) => { ctx.target = e.id } }),
+      ],
+    },
+    adding: {                                   // runs addItem on entry; drops events it does not handle
+      invoke: invoke(addItem, {
+        input: { title: ctx.draft },
+        done: { target: 'idle', assign: () => { ctx.draft = '' }, navigate: (r) => ui.link(itemPage, { id: r.id }) },
+        failed: {                               // every declared error + Unexpected (+ optional Invalid)
+          Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already exists' } },
+          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+        },
+      }),
+    },
+    removing: { invoke: invoke(removeItem, { input: { id: ctx.target }, done: 'idle', failed: { Unexpected: 'idle' } }) },
+    flash: { after: [{ ms: 3000, target: 'idle' }], ignore: [Add] },    // timers; ignore only without invoke
+  }),
+})
+```
+- **assign** values are event (`e`), result (`r`) or error fields, context, literals, operators and `fn()` calls.
+- **guard** conditions: a field (`() => ctx.auto`), comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
+- **navigate** sends the browser to `ui.link(route, params, search?)` after the transition. It returns one link: to
+  choose between links, write one guarded transition per link (`[{ guard: () => …, navigate: … }, { navigate: … }]`);
+  a `?:` inside `navigate` is HZ014.
+- `done` and each `failed` entry take a state name, one transition, or a list of guarded transitions.
+- **Shared transitions:** `machine({ on })` entries are copied into every state that has no `invoke`, is not final,
+  and neither handles nor ignores the event itself. Without `target` they stay in the state they fire in; one
+  contract covers every copy.
+- **Start from the URL:** a view with a `route` may declare `seed: ({ params, search }) => ({ q: search.q })`; the
+  page's machine then starts with those context fields (server render, hydration and no-JS posts alike). One view
+  per page may seed a machine (HZ048).
+- A transition to the same state re-enters it. In an app with `site.locales`, machines never hold
+  translated text (HZ041): store a code (`ctx.error = 'duplicate'`) and choose the message in the view. The
+  scaffold does this in every app.

package/skill/topics/pages.md

@@ -0,0 +1,69 @@
+# Routes and pages
+
+```ts
+// routes.ts
+export const home = route({ path: '/', params: null, search: z.object({ show: Show.default('all') }) })
+export const itemPage = route({ path: '/items/:id', params: z.object({ id: z.string() }), search: null })
+export const docs = route({ path: '/docs/:path+', params: z.object({ path: z.array(z.string()).min(1) }), search: null })
+```
+- `:x` one segment, `:x?` optional (nullable), `:x+` / `:x*` one-or-more / zero-or-more (string[]) (HZ024).
+- `search`: flat scalars or enums, each with a default or nullable (HZ035).
+- **Pages** go in `project({ routes: { home, itemPage }, pages: [...] })` (the whole config: see --more):
+  `ui.page(home, { views: [Board], head: { render: () => ({ title: 'Items' }) } })`.
+- **Head from a query:** `head: { query: getItem, input: (params, locale) => ({ id: params.id }), render: (item) => ({ title:
+  item.title }), failed: { NotFound: 404 } }`. `failed` maps every declared error of the query (HZ051) to a route
+  without params (303) or to `403`, `404` or `410`.
+- `head.render` fields: `title`, `description`, `type` (`'website' | 'article'`), `image`, `published`, `noindex`;
+  any other is HZ014 (Open Graph, `twitter:card` and the JSON-LD are derived from these).
+- A route no page renders is HZ052.
+
+<!-- more -->
+
+- URLs are canonical (keys sorted, defaults left out). Changing `search` is a navigation: a filter in the URL is a
+  plain `ui.link`, no machine.
+
+```ts
+// hozu.config.ts
+export default project({
+  schema: zodAdapter, app: new URL('./app.ts', import.meta.url), styles: new URL('./app.css', import.meta.url),
+  site: { url: 'https://example.com', name: 'Items', lang: 'en' },
+  routes: { home, itemPage }, notFound: missing,           // notFound / error: routes rendered for 404 / 500
+  pages: [
+    ui.page(home, { views: [Board], head: { render: () => ({ title: 'Items' }) } }),
+    ui.page(itemPage, {
+      views: [Detail],
+      head: {
+        query: getItem,
+        input: (params) => ({ id: params.id }),
+        render: (item) => ({ title: item.title, description: item.title, type: 'article' }),
+        failed: { NotFound: 404 },                         // every declared error of the query (HZ051)
+      },
+      entries: { query: listItems, input: {}, params: (item) => ({ id: item.id }) },   // sitemap + static export
+    }),
+  ],
+  kits: [kit],                                             // shared UI (hozu docs components)
+  features: [items],
+})
+```
+- `image` is a URL, `ui.asset(...)` or `ui.og({ title })`. The share card is derived: `og:image:width` / `height`
+  from the file, `og:image:alt` from the title, `twitter:card` large from 600 px wide. Use a 1200×630 image.
+- `entries.lastmod: (item) => item.updatedAt` (an ISO date) adds `<lastmod>` to the sitemap.
+- `site.url: { env: 'SITE_URL' }` reads the origin at startup from a variable declared in `env.public` (HZ085).
+- Check the head without a server: `hozu get / --select 'meta[property^="og:"]'`; `--select script` prints the JSON-LD.
+- `head.failed` example: `failed: { Unauthorized: login, Forbidden: 403 }`. `Unexpected` is always 500.
+  It maps declared errors only: a head query that always fails is not a redirect.
+  When the head query fails, no head field is computed: the `<title>` is `site.name`, with no description.
+- **Which redirect** (one per purpose):
+
+| Need | Form |
+|---|---|
+| a static path moved | `http.redirects` (`hozu docs http`) |
+| this visitor may not see the page | `head.failed` |
+| a decision on success, e.g. `/` by session | a GET endpoint with `output: 'redirect'` (`hozu docs endpoints`) |
+| after a machine transition | `navigate` |
+
+- For a route no page renders (HZ052), link to an endpoint with `ui.link(endpoint, input)` instead.
+- A detail view: `ui.view({ route: itemPage, render: ({ params }) => ui.query(getItem, { id: params.id }, { ready,
+  failed: { NotFound: () => ui.p({}, ['Not found']), Unexpected: () => … } }) })`.
+- A page loads JS only when a machine-bound part renders on it (`hozu plan <route or path>`). Every link loads a document;
+  state across pages lives in the URL (`seed`), on the server (queries) or in a client component's own storage.

package/skill/topics/patterns.md

@@ -0,0 +1,85 @@
+# Common UI patterns
+
+The controls are plain elements; in an app with a kit, use its components (`ui.use(Button, …)`,
+`hozu docs components`).
+
+- **Busy state:** render every control once; the state with `invoke` drops repeated submits. Progress:
+  `when(['adding'], [ui.p({ 'aria-busy': 'true' }, ['Saving…'])])`. Do not duplicate controls under `when`.
+- **Optimistic item:** `when(['adding'], [ui.li({ class: 'opacity-50' }, [ctx.draft])])`; leaving the state removes it
+  and the refreshed query shows the real item.
+- **Refresh after a mutation:** tag the query, list the tag in the mutation's `invalidates`.
+- **Go to what was just created:** `done: { target: 'idle', navigate: (r) => ui.link(itemPage, { id: r.id }) }`.
+- **Per-item action** (toggle, pin, delete): each item gets its own small form, so it works without JS:
+```ts
+ui.form({ on: { submit: ui.send(Toggle, { id: ui.dom.form('id') }) } }, [
+  ui.input({ type: 'hidden', name: 'id', value: item.id }),
+  ui.button({ type: 'submit' }, [item.done ? 'Reopen' : 'Done']),
+])
+// machine: on(Toggle, { target: 'toggling', assign: (e) => { ctx.target = e.id } })
+// toggling: { invoke: invoke(toggleItem, { input: { id: ctx.target }, done: 'idle', failed: { Unexpected: 'idle' } }) }
+```
+- **Filter in the URL** (shareable, no JS): `search` on the route, options as
+  `ui.a({ href: ui.link(home, null, { show: s.value }), 'aria-current': search.show === s.value }, [s.label])`.
+- **Filter as you type, empty state:** context `search: z.string()`, `on: { input: ui.send(Search, { text:
+  ui.dom.value }) }`, filter and test emptiness with a `fn` (see --more).
+- **Detail page with a 404:** `hozu docs pages`.
+
+<!-- more -->
+
+Each pattern is complete here; there is no need to open other files.
+
+- **Per-item action, tried without a server:** `hozu browse / --do 'fill Title=x' --do 'press Enter' --do 'click Done in "x"'`.
+- **Filter and empty state** (in context): one helper, two `fn`s over the list:
+```ts
+const shows = (i: Item, show: Show) => show === 'all' || (show === 'done') === i.done   // sent with the fns
+export const visible = fn({ input: z.object({ items: z.array(Item), show: Show }), output: z.array(Item),
+  impl: ({ items, show }) => items.filter((i) => shows(i, show)) })
+export const isEmpty = fn({ input: z.object({ items: z.array(Item), show: Show }), output: z.boolean(),
+  impl: ({ items, show }) => !items.some((i) => shows(i, show)) })
+// view
+isEmpty({ items, show: ctx.show })
+  ? ui.p({ class: 'text-slate-500' }, ['No items'])
+  : ui.ul({}, [ui.each(visible({ items, show: ctx.show }), 'id', (i) => ui.li({}, [i.title]))])
+```
+- **Search as you type:** context `search: z.string()`; `ui.input({ type: 'search', 'aria-label': 'Search', value:
+  ctx.search, on: { input: ui.send(Search, { text: ui.dom.value }) } })`; `on(Search, { target: 'idle', assign: (e) =>
+  { ctx.search = e.text } })`; filter with a `fn({ input: z.object({ items, text: z.string() }), … })`.
+- **Toggle buttons:** for each option of a constant list,
+  `ui.button({ type: 'button', 'aria-pressed': ctx.show === s.value, on: { click: ui.send(SetShow, { show: s.value }) } }, [s.label])`.
+- **In the URL and as you type** (`/?q=park` works without JS, typing filters live): seed the machine from the URL
+  and read only the context. A GET form with `name="q"` submits it without JS.
+```ts
+export const Board = ui.view({ machine: m, route: home, seed: ({ search }) => ({ q: search.q, district: search.district }),
+  render: ({ ctx }) => ui.form({ method: 'get' }, [
+    ui.input({ type: 'search', name: 'q', 'aria-label': 'Search', value: ctx.q, on: { input: ui.send(Search, { q: ui.dom.value }) } }),
+    /* … */ ui.each(visible({ items, q: ctx.q, district: ctx.district }), 'id', (s) => …) ]) })
+```
+- **A mode with shared controls** (a tour, an edit mode): put what every mode handles the same way in
+  `machine({ on: [on(Search, { assign: (e) => { ctx.q = e.q } })] })` (no `target`: stays in its state); each state
+  lists only what differs.
+- **Select many, then act** (bulk delete): checkboxes in the list join one form through a formRef; the invoke
+  state drops events, so the checkboxes are disabled while it runs:
+```ts
+const bulk = ui.formRef()   // module level; context { selected: z.array(z.string()), busy: z.boolean() }
+ui.form({ ref: bulk, on: { submit: ui.send(Bulk, { ids: ui.dom.formAll('ids'), action: ui.dom.form('action') }) } }, [
+  ui.button({ type: 'submit', name: 'action', value: 'delete' }, ['Delete selected']),
+  ui.button({ type: 'submit', name: 'action', value: 'pin' }, ['Pin selected']),
+])
+ui.each(items, 'id', (item) => ui.li({}, [ui.input({ type: 'checkbox', form: bulk, name: 'ids', value: item.id,
+  'aria-label': `Select ${item.text}`, checked: ctx.selected.includes(item.id), disabled: ctx.busy,
+  on: { change: ui.send(Select, { id: item.id, checked: ui.dom.checked }) } }), item.text]))
+// on(Select, { target: 'idle', guard: (e) => e.checked === true, assign: (e) => { ctx.selected.push(e.id) } }),
+// on(Select, { target: 'idle', assign: (e) => { ctx.selected = ctx.selected.filter((id) => id !== e.id) } }),
+// on(Bulk, { target: 'removingMany', guard: (e) => e.action === 'delete', assign: (e) => { ctx.selected = e.ids; ctx.busy = true } }),
+// removingMany: invoke(removeNotes, { input: { ids: ctx.selected }, done/failed: reset selected and busy })
+```
+  The mutation input holds the limit (`z.array(z.string()).min(1, 'Select at least one note')`).
+- **Sorted or pinned first:** sort in the resolver (the list query returns items in display order), or in a `fn`.
+- **UI kept across links** (a cart, a player): list the same machine view on each page, in the same order.
+- **Load more:** context `{ cursors: [null], last: null }`;
+  `ui.each(ctx.cursors, null, (cursor) => ui.query(listPage, { cursor }, { ready: (page) => … }))`; on the last page
+  (`cursor === ctx.last && page.next !== null`) a sentinel `on: { visible: ui.send(More, { cursor: page.next }) }`;
+  `More` pushes the cursor, guarded by `e.cursor !== null && e.cursor !== ctx.last`.
+- **A link starts the page again:** every internal link is a document navigation, so a machine's context starts
+  from `initialContext` (or `seed`). Keep what must survive in the URL: put both filters in `search` and `seed` the
+  context from it, instead of one in the URL and one in context.

package/skill/topics/recipes.md

@@ -0,0 +1,73 @@
+# Recipes for common changes
+
+Names follow `hozu add feature items`: `Item`, `NewItem`, `Add`, `addItem`, `itemsMachine`, `ItemsBoard`. The controls are plain elements; with a
+kit, use its components instead. More recipes (an action over many items, a field on the detail page, a detail page): see --more.
+
+## A personal list without sign-in (a watchlist, favourites)
+The list is the visitor's own: it lives in their browser, so two visitors never share it (`examples/watchlist`).
+- **model:** `myList` query `scope: 'user'`, `freshness: 'request'`, `tags: () => [listTag()]`, `runs: 'browser'`;
+  `addSymbol` / `removeSymbol` mutations `invalidates: () => [listTag()]`, `runs: 'browser'` (no `access`).
+- **fetch.ts:** `localStorage`, one export per effect:
+  ```ts
+  const read = (): string[] => JSON.parse(localStorage.getItem('watchlist:symbols') ?? '[]')
+  export const myList = implement<typeof model.myList>(async () => read())
+  export const addSymbol = implement<typeof model.addSymbol>(async ({ symbol }, { fail }) => {
+    if (read().includes(symbol)) return fail('Duplicate', { symbol })
+    localStorage.setItem('watchlist:symbols', JSON.stringify([...read(), symbol]))
+    return {}
+  })
+  ```
+- **feature.ts:** `fetch: new URL('./fetch.ts', import.meta.url)`; `app.ts`: `components: bundleComponents`.
+- **Data about the items** (quotes, prices) is public: a `runs: 'server'` (or `'either'`) query inside the list's
+  `ready` branch, `ui.query(quotes, { symbols }, …)`.
+- The form needs JavaScript (HZ036): `project({ accept: [{ code: 'HZ036', at: 'watchlist.Add', reason: … }] })`.
+- Across devices the list needs sign-in and a database instead (`hozu docs auth`).
+
+## A field chosen in the add form (an enum)
+- **model:**
+  - `export const Priority = z.enum(['low', 'normal', 'high'])`;
+  - add `priority: Priority` to `Item`, `NewItem` and the `Add` payload;
+  - context: `priority: Priority`, with `priority: 'normal'` in `initialContext`;
+  - `fields` gets `priority: z.string().nullable()`, with `priority: null` in `initialContext` and in the `Add`
+    assign that resets it;
+  - the `Add` assign also gets `ctx.priority = e.priority`, and the add `invoke` input becomes
+    `{ title: ctx.draft, priority: ctx.priority }`.
+- **views:**
+  - the form's submit sends `{ title: ui.dom.form('title'), priority: ui.dom.form('priority') }`;
+  - inside the form add
+    `ui.select({ name: 'priority', 'aria-label': 'Priority', class: 'rounded border px-2' }, ['low', 'normal', 'high'].map((p) => ui.option({ value: p, selected: p === 'normal' }, [p])))`;
+  - in the item: `ui.span({ class: 'text-xs' }, [item.priority])`.
+- **Contracts:** if the app has contracts that send `Add` or return an item, add `priority` to their payloads,
+  inputs and results. These transitions only copy values, so they need no new contract.
+- **server:** store `priority` where the items live (the scaffold's `demoItems` stand-in, or the database) and return it.
+
+<!-- more -->
+
+With a kit: `ui.use(Button, { variant: { tone: 'quiet' } }, ['Clear done'])`.
+
+## An action button that works on many items (e.g. "Clear done")
+- **model:**
+  - `export const ClearDone = event({ payload: z.object({}) })`;
+  - `export const clearDone = mutation({ input: z.object({}), output: z.object({ removed: z.number() }), invalidates: () => [itemsTag()], runs: 'server', access: 'anyone' })`;
+  - in `idle`: `on(ClearDone, { target: 'clearing', assign: () => { ctx.error = null } })`;
+  - a state
+    `clearing: { invoke: invoke(clearDone, { input: {}, done: 'idle', failed: { Unexpected: { target: 'idle', assign: () => { ctx.error = 'unexpected' } } } }) }`
+    (busy states drop events they do not handle, so no `ignore`).
+- **views:** the control
+  `ui.form({ on: { submit: ui.send(ClearDone, {}) } }, [ui.button({ type: 'submit', class: 'text-sm underline' }, ['Clear done'])])`.
+- The new transitions only copy values, so they need no contract (the feature lists `model`, so both are registered).
+- **server:**
+  `implement(clearDone, () => { const before = demoItems.length; demoItems.splice(0, demoItems.length, ...demoItems.filter((i) => !i.done)); return { removed: before - demoItems.length } })` (with a database: one delete of the done rows).
+- **Try it:** `hozu browse / --do 'click Clear done'` (with and without JS).
+
+## A field shown on the detail page
+In the detail view's `ready`: `ui.p({}, ['Priority: ', item.priority])`. The detail query already returns the whole
+item.
+
+## A detail page, when the feature has none
+Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts it prints:
+- the route with params;
+- the `get` query and its resolver;
+- the detail view;
+- the link in the list;
+- `ui.page(...)` with `head` and `entries`.

package/skill/topics/requests.md

@@ -0,0 +1,41 @@
+# Requests from Hozu DevTools
+
+- **Read every open one in one call:** `npx hozu requests --full` prints them as one prompt (saved under
+  `.hozu/requests/`, or pasted to you).
+- **Each item:** `Want` (the person's words), `Where` (`file:line:column` and the view), `Scope`, `Style`, `Text`,
+  `Mind` (where a plain edit goes wrong), `Locate` (the IR pointer).
+- **Do it:** edit at `Where`; when the lines moved, `npx hozu why <pointer>` finds the node again. Style: replace the
+  named class with the given utility; never a `style` attribute. A behaviour change that decides needs a contract
+  (`hozu docs contracts`).
+- **Finish:** `npx hozu check`, then `npx hozu requests done <n> --result "<one line: what changed>"` for each one;
+  it removes the file. Do not edit request files. Report the result lines to the person.
+- **Show the person what changed:** `npx hozu show <views.ts:line | a Locate id | page:<route>> --note "<what changed,
+  in their words>"` frames that part on their page under `npm run dev`; `--in "<text>"` picks one row of a list. A
+  reply comes back as a request. `npx hozu show` lists the notes (a `STALE` one names a part that moved: re-add it),
+  `--done <n>` removes one, `--clear` all.
+
+<!-- more -->
+
+- **The person's language:** DevTools may show their own translation (`hozu dev --devtools-messages <file>`,
+  `HOZU_DEVTOOLS_MESSAGES`); the request Markdown you read is always English.
+- **Where they come from:** under `npm run dev` (`hozu dev`) a person selects parts of the running app, describes the
+  change, tries styles or text, and saves a request to `.hozu/requests/NNNN-<title>.md` or pastes it to you.
+  `npx hozu requests` lists the numbers and places.
+- **The other fields:**
+  - `Scope`: only this one, every item of a list, or every use of a component;
+  - `Style`: the class to replace and the theme utility to use;
+  - `Text`: wording the person tried;
+  - `Shown when`, and `preview <state>` on the page line: the state the person was looking at.
+- **More on doing it:**
+  - A component use: `class` at the use for this one (a property the component owns needs a trailing `!`), the
+    variant in the kit for every use (`npx hozu why <ui.X>` lists them).
+  - An arbitrary value (`px-[22px]`) only when the line says no theme step fits.
+  - A message text changes in every locale; text from data changes the data or its formatting.
+- **Notes (`hozu show`):** numbered in the order you add them, so several make a tour (Back / Next in the dock's Agent
+  panel). The target is anything `hozu why` takes; `--page /path` says where it is when the target is not on the page
+  the person has open. Notes live in `.hozu/notes.json` and never reach production.
+- **The API drawer** (the dock's API button) lists the queries the page reads and the mutations its machines start,
+  with `runs`, freshness, errors and the `file:line` that implements each, and runs them with an input the person
+  edits (mutations ask first: they write development data; the page then re-reads in place). A request may carry a
+  `npx hozu call …` line or a `curl` command (the requests a call sent out) copied from it. When a request says "this query returns X", reproduce it with
+  `npx hozu call <feature>.<effect> --input '…'` before changing the resolver.