@hozu/cli 0.18.2 → 0.20.0

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:
+```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` is a link to share, typing filters live): seed the machine from the URL
+  and read only the context. A GET form with `name="q"` sets it.
+```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,79 @@
+# 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 }, …)`.
+- Refresh controls (Pause / Resume / Refresh now): states `live` / `paused`, `refresh: () => [quotesTag()]` on
+  `RefreshNow` and on `live`'s `after: [{ ms: 30_000, target: 'live', … }]`; adds return with `done: 'previous'`.
+- 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'`.
+
+## 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`.
+
+## Dark mode
+- Following the system needs no code: Tailwind's `dark:` classes (`bg-white dark:bg-slate-900`).
+- A switch the visitor chooses: a client component (`hozu docs components`) puts `dark` on `<html>` and keeps the
+  choice in `localStorage`; `app.css` adds `@custom-variant dark (&:where(.dark, .dark *));`.

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.

package/skill/topics/testing.md

@@ -0,0 +1,82 @@
+# Testing
+
+- **Read a page without a server:** `hozu get /path --select 'button[aria-pressed=true]' --forms` (status, title,
+  visible text; `--forms` lists each form's fields and submit buttons). Endpoints: `hozu get '/api/items?x=1'`.
+- **Try one query or mutation without a page:** `hozu call notes.listNotes --input '{}' --session '{"user":"ada"}'`;
+  a mutation writes real data, so it needs `--write`. An endpoint too:
+  `hozu call api.who --input '{"room":"a"}' --header 'Authorization: Bearer t'` (a POST needs `--write`).
+- **Drive the app in a real browser, still without a server:**
+  `hozu browse / --session '{"user":"ada"}' --do 'fill New note=Milk' --do 'press Enter' --do 'click Pin in "Milk"'`.
+  - Steps: `fill <label>=<value>`, `select <label>=<option>`, `check` / `uncheck <label>`, `click <name>`,
+    `submit "<form>"`, `press <key>`, `wait <ms>`, `goto <path>`, `post <path> a=1&b=2`,
+    `remember <name> from url|<selector> [@attr]` (later steps read `$name`); a target may end with `in "<text>"`
+    (for fill and select, before or after `=value`).
+  - Labels are what `hozu get <page> --forms` lists; a missing one prints `Did you mean "…"?`. One `--do` may hold
+    several steps: `--do 'fill Title=Milk; press Enter'`.
+- **Other users, other pages, after a reload, after sign-out:** verify any such statement once, in one `browse`
+  chain. `--as <name>` starts an actor with its own browser; all actors share one app.
+  - A stale form (sent after the data changed elsewhere): `--do 'remember save from form:has([name=title]) @action'`,
+    change the data as another `--as`, then `--do 'post $save title=x'`. No server and no curl needed.
+- **The output** is per step only the lines added (`+`) or removed (`−`). A passing six-step run stays under 1.5 KB.
+  Exit code 1 when a step failed, the modes differ or an error was printed.
+- **A step that reloads the page** with JS on says `the page reloaded` (a form that should update in place);
+  `--full` adds `N elements replaced` (a region drawn again), `--json` has both as `document` / `replaced`.
+- **A pending state:** `--do 'hold notes.addNote'` keeps that effect's answer back; the next steps (and
+  `--screenshot`) see the busy UI; `--do 'release'` answers it.
+- `browse` runs the `npm start` app: what only `hozu dev` does (reload on edits, DevTools) is not in it.
+- In code: `const page = await testApp(app).get('/')` from `@hozu/testing` → `{ status, headers, html, text, payload }`.
+- A build with errors renders nothing: run `hozu check`.
+
+<!-- more -->
+
+- **`hozu get`** prints the status, redirect, `set-cookie` attributes (`HttpOnly`, `SameSite`), title, alerts and
+  visible text.
+  - `--forms` lists each form: fields with their defaults, checkbox / radio groups with every value (checked ones
+    marked ✓), controls that join through `form=` (marked `(form=)`), and submit buttons with their name and value.
+  - It needs no browser.
+- **`hozu call`** runs the effect through the app's own handler and prints the value or the declared error. With
+  `--write`, a mutation also prints the tags it invalidated and the queries they refresh. `runs: 'browser'` effects
+  need `hozu browse`.
+- **`hozu browse`:**
+  - It uses the installed Chrome / Chromium / Edge (`HOZU_CHROME=/path` to choose); without one it is a config
+    error. The app runs in-process, exactly as `npm start` serves it.
+  - `--js off` runs the steps with JS switched off, `--js both` side by side: for a page that must work without it.
+  - Steps in detail: a second fill of a repeated name fills the next field; `check` / `uncheck` set the state;
+    `click <name>` on a submit button posts with its name and value; `submit "<form>"` takes a form's `aria-label` or
+    its submit button text. Labels and names are what a user reads (aria-label, `<label>`, placeholder, button text,
+    `title`), or a field's `name`.
+  - `in "<text>"` picks the smallest list item, table row or form containing that text
+    (`click Delete in "Buy milk"`).
+  - A step with no native effect prints `js-only (<reason>)` in the off column, e.g. a `type=button` button.
+- **Actors:** the steps after an `--as <name>` are that actor's, and a later `--as <name>` switches back. `--session`
+  right after an `--as` signs that actor in. All actors share one data store and one session store, so what ada
+  writes is what bob reads.
+  - Signing out and in again inside one actor's chain also works (`click Sign out`, `fill Name=bob`, `press Enter`).
+  - `hozu browse /notes --as ada --session '{"user":"ada"}' --as bob --session '{"user":"bob"}' --as ada --do 'click Share in "Milk"' --as bob --do 'goto /inbox'`
+  - `--header 'Name: value'` adds a header to every request: before the first `--as` for every actor, after an
+    `--as` for that actor.
+  - **Another visitor's data:** `--as ada --do 'remember note from li a @href' --as bob --do 'goto $note'` (bob's page
+    should answer 403), or `--as bob --do 'post /notes/n1 text=x'`: a forged native post, as bob, without the page.
+    Each mode keeps its own remembered values.
+- **The output** is small on purpose: lines print once when both modes agree and per mode where they differ; a
+  navigation prints `→ <path>` and the new page's lines; a live update on another actor's page prints under the step
+  (`bob: + Milk`).
+  - `≠ DIFFERS` marks a step where both modes made a request and the resulting text differs: a no-JS/JS parity bug.
+  - Errors: uncaught exceptions, `console.error`s, CSP violations and failed requests, each with the page, the
+    resource type and the mode. A 400 re-render of an invalid native post is not an error, and a page answering
+    401, 403, 404 or 410 is the step's status (`→ /notes/n1 (403)`), so an access check exits 0.
+  - To forge a post, take the form's `action` from `hozu get <page> --forms` or `remember … @action` on a page the
+    server rendered (`goto` it first): forms the client renders after a change carry no `action`.
+  - Exit code 1 also when a client component failed. `--json` has every line; `--full` prints them all;
+    `--select <css>`, `--screenshot shot.png` (after the steps), `--viewport 390x844` (a phone; default 1280x800) and
+    `--reduced-motion`.
+  - It also prints the client components on the page (mounted, failed, size, canvases).
+- **`testApp`:** `app` is the default export of `app.ts`; `.post(path, fields)` submits a native form, with fields as
+  a record or as `[name, value]` pairs for repeated names. `testApp(app, { session: store })` may swap only the
+  session store (a test issuer). `testApp` reads no env files: pass `testApp(app, { env: process.env })` (or a record)
+  for the variables your resolvers need; `hozu get`, `call` and `browse` read `env.files` themselves.
+- `hozu get`, `hozu browse` and `testApp` build the app module; a build with errors exits 1 (throws).
+- Vitest: add `hozuTransform()` from `@hozu/transform/vite` to `plugins`.
+- Browser tests: wait for `html[data-hozu-ready]` (set after hydration) before clicking.
+- A person checks the result with `npm run dev` (`hozu dev`: reloads and Hozu DevTools); what they ask for from
+  there arrives as requests (`hozu docs requests`). The tools above stay the way you verify.

package/skill/topics/views.md

@@ -0,0 +1,53 @@
+# Views
+
+```ts
+export const Board = ui.view({
+  machine: m,        // optional: without it, no ctx / when / events, and 0 JS
+  route: home,       // optional: render gets { params, search } typed by the route
+  seed: ({ search }) => ({ q: search.q }),   // optional, with machine + route: context fields from the URL
+  render: ({ ctx, when, is, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
+})
+```
+- **Elements:** `ui.<tag>(attrs, children)` for every HTML and SVG element; void tags (`input`, `img`) take only attrs.
+  Children are nodes, strings, numbers, data values, and `null` / `false` (render nothing).
+- **Classes:** `class` is a static string of Tailwind classes that must exist (HZ026); conditional classes:
+  `toggle: { 'bg-indigo-600 text-white': ctx.tab === t }`. No `style`.
+- **Conditions:** `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`, `item.done ? 'done' : 'open'`.
+  By machine state: `when(['adding', 'saving'], [ui.p({}, ['Saving…'])])`; as a value (attributes): `disabled: is(['saving'])`.
+- **Dialogs, popovers, menus:** native, no machine state: `ui.button({ commandfor: 'd', command: 'show-modal' })` +
+  `ui.dialog({ id: 'd', closedby: 'any' }, [...])`, `popover` / `popovertarget`, `ui.details`.
+- **Lists:** `ui.each(items, 'id', (item) => ui.li({}, [item.title]))`. Never `.map` over data.
+- **Numbers and dates:** `ui.format.number(q.price, { style: 'currency', currency: 'USD' })`, `ui.format.date(x,
+  { dateStyle: 'medium' })`, `ui.format.relative(n, 'day')`, `ui.format.list(xs)` (Intl, the page's locale).
+- **Events:** `on: { click: ui.send(Event, payload) }`; payload fields are literals, data, `ui.dom.value`,
+  `ui.dom.form('name')` (submit; `hozu docs forms`).
+- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032).
+- **Data:** `ui.query(listItems, input, { ready: (items) => …, failed: { NotFound: () => …, Unexpected: () => … } })`;
+  `failed` lists every declared error plus `Unexpected`.
+- **Shared UI** (buttons, inputs, fields): `ui.use(Button, { variant, props, on }, ['Save'])` of a kit component
+  (`hozu docs components`).
+
+<!-- more -->
+
+- **Attributes:** HTML names in lower case (`for`, `minlength`, `aria-pressed`, `data-x`), typed per tag. Values are
+  literals or data: `'aria-pressed': ctx.show === 'all'`, `title: ctx.error ?? 'OK'`.
+- **CSS variables:** `vars: { '--hue': item.hue }`.
+- **More conditions:** `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`; a `?:` / `&&` branch may be a list:
+  `open ? [a, b] : null`. A query branch or an each item returns one node: wrap several in an element (HZ014).
+  With an enter/leave animation: `ui.if(cond, [then], [else], 'fade')` (the motion name is required).
+- **More lists:** `ui.each(tags, null, (t) => …)` for primitives. `.map` only over constants:
+  `['a', 'b'].map((k) => ui.option({ value: k }, [k]))`.
+- **Text:** template strings work: `` `${n} items` ``.
+- **Reuse:** `export const row = part((item: Item) => ui.li({}, [item.done ? 'Done' : item.title]))`, called as
+  `row(item)`; it is inlined, so the IR equals the inline form. A plain function that receives data is HZ059.
+- **Shared UI:** use the kit component, not a styled `ui.button` per page (`example/` uses a kit).
+- **More events:** any DOM event name plus `visible` (entered the viewport). Payload fields also:
+  `ui.dom.formAll('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. `ui.dom.value` / `ui.dom.form`
+  fill an enum field only from a `<select>`, radios or submit buttons whose literal values are all members (HZ033).
+- **Search in links:** the third argument of `ui.link` is optional and exists only when the route declares `search`:
+  omitted means every default, and a search lists only the fields that differ: `ui.link(home, null, { show: 'done' })`.
+- **More data:** `pending: ui.p({}, ['Loading…'])` is optional; a branch may return `null` to render nothing.
+  Server-fetched data is sent with the page and never fetched again; after a mutation, queries whose tags it
+  invalidates refresh in place.
+- **Also:** `ui.html(post.html)` (trusted HTML from query data only, HZ030), `ui.asset(new URL('./x.png',
+  import.meta.url))`, `ui.window({ on })` / `ui.document({ on })`, `ui.embed(OtherView)`.

package/templates/guide.md

@@ -0,0 +1,16 @@
+# __NAME__
+
+A web app built with Hozu (`@hozu/*`). Hozu is not in your training data.
+
+## Before writing code
+- __READ__ It has the change loop, the commands and the rules no diagnostic checks.
+- The files in `__SKILL__/` are the whole API. Do not read the framework source in `node_modules/@hozu`.
+__NOTE__
+## Rules
+- After `hozu add feature`, do not print the generated files: edit the texts it lists; `hozu map` shows the rest.
+- Apply the fix each diagnostic gives; do not work around a rule.
+- `__RUN__ hozu get` and `__RUN__ hozu browse` run the same app as `npm start`; do not start a server to check.
+- Asked to do the Hozu requests (from DevTools under `npm run dev`): `__RUN__ hozu requests --full`, then follow
+  `__RUN__ hozu docs requests`.
+- Do not edit `__SKILL__/` or the text between the `hozu` markers: `__RUN__ hozu skill` rewrites both for the
+  installed Hozu version.