create-hozu 0.6.0 → 0.8.0

package/skill/example/features/bookmarks/views.ts

@@ -1,17 +1,14 @@
-import { contract, feature, ui } from '@hozu/core'
+import { contract, ui } from '@hozu/core'
 import { bookmarkPage, home } from '../../routes.ts'
 import {
   Add,
   addBookmark,
   bookmarksMachine,
-  bookmarksTag,
   Draft,
-  DUPLICATE,
   getBookmark,
   isEmpty,
   listBookmarks,
   ToggleRead,
-  toggleRead,
   visible,
 } from './model.ts'
 
@@ -132,16 +129,10 @@ export const Detail = ui.view({
           },
         },
       ),
-      ui.a({ href: ui.link(home, null, null), class: 'underline' }, ['Back']),
+      ui.a({ href: ui.link(home, null), class: 'underline' }, ['Back']),
     ]),
 })
 
-export const typesDraft = contract(bookmarksMachine, {
-  given: { state: 'idle' },
-  when: [{ send: Draft, payload: { text: 'Hozu' } }],
-  expect: { state: 'idle', changes: { draft: 'Hozu' } },
-})
-
 export const addsBookmark = contract(bookmarksMachine, {
   given: { state: 'idle' },
   when: [
@@ -158,87 +149,3 @@ export const addsBookmark = contract(bookmarksMachine, {
     ],
   },
 })
-
-export const rejectsDuplicate = contract(bookmarksMachine, {
-  given: { state: 'adding' },
-  when: [{ failed: addBookmark, error: 'Duplicate', data: { title: 'Hozu talk' } }],
-  expect: { state: 'idle', changes: { error: DUPLICATE } },
-})
-
-export const rejectsInvalidTitle = contract(bookmarksMachine, {
-  given: { state: 'adding' },
-  when: [
-    {
-      failed: addBookmark,
-      error: 'Invalid',
-      data: {
-        message: 'title: Use at least 2 characters',
-        fields: { title: 'Use at least 2 characters', kind: null },
-      },
-    },
-  ],
-  expect: { state: 'idle', changes: { fields: { title: 'Use at least 2 characters' } } },
-})
-
-export const addFails = contract(bookmarksMachine, {
-  given: { state: 'adding' },
-  when: [{ failed: addBookmark, error: 'Unexpected', data: { message: 'offline' } }],
-  expect: { state: 'idle', changes: { error: 'offline' } },
-})
-
-export const togglesRead = contract(bookmarksMachine, {
-  given: { state: 'idle' },
-  when: [
-    { send: ToggleRead, payload: { id: 'b1' } },
-    { done: toggleRead, result: { id: 'b1', title: 'A', kind: 'article', read: true } },
-  ],
-  expect: {
-    state: 'idle',
-    changes: { target: 'b1' },
-    effects: [{ effect: toggleRead, input: { id: 'b1' } }],
-  },
-})
-
-export const toggleMissing = contract(bookmarksMachine, {
-  given: { state: 'toggling' },
-  when: [{ failed: toggleRead, error: 'NotFound', data: { id: 'b9' } }],
-  expect: { state: 'idle' },
-})
-
-export const toggleFails = contract(bookmarksMachine, {
-  given: { state: 'toggling' },
-  when: [{ failed: toggleRead, error: 'Unexpected', data: { message: 'offline' } }],
-  expect: { state: 'idle', changes: { error: 'offline' } },
-})
-
-export const bookmarks = feature({
-  id: 'bookmarks',
-  intent: {
-    summary:
-      'A shared reading list: add bookmarks with a kind, mark them read, filter unread, one page each.',
-    invariants: ['Titles are unique, case-insensitive', 'New bookmarks are listed first'],
-  },
-  declarations: {
-    bookmarksTag,
-    Draft,
-    Add,
-    ToggleRead,
-    listBookmarks,
-    getBookmark,
-    addBookmark,
-    toggleRead,
-    visible,
-    isEmpty,
-    bookmarksMachine,
-    Board,
-    Detail,
-    typesDraft,
-    addsBookmark,
-    rejectsDuplicate,
-    rejectsInvalidTitle,
-    addFails,
-    togglesRead,
-    toggleMissing,
-    toggleFails,
-  },
-})

package/skill/example/hozu.config.ts

@@ -1,11 +1,13 @@
 import { project, ui } from '@hozu/core'
 import { zodAdapter } from '@hozu/schema-zod'
+import { bookmarks } from './features/bookmarks/feature.ts'
 import { getBookmark, listBookmarks } from './features/bookmarks/model.ts'
-import { Board, bookmarks, Detail } from './features/bookmarks/views.ts'
+import { Board, Detail } from './features/bookmarks/views.ts'
 import { bookmarkPage, home } from './routes.ts'
 
 export default project({
   schema: zodAdapter,
+  app: new URL('./app.ts', import.meta.url),
   styles: new URL('./app.css', import.meta.url),
   site: { url: 'http://localhost:3000', name: 'Bookmarks', lang: 'en' },
   routes: { home, bookmarkPage },
@@ -19,6 +21,7 @@ export default project({
       head: {
         query: getBookmark,
         input: (params) => ({ id: params.id }),
+        failed: { NotFound: 404 },
         render: (b) => ({ title: b.title, description: b.title, type: 'article' }),
       },
       entries: { query: listBookmarks, input: {}, params: (b) => ({ id: b.id }) },

package/skill/topics/auth.md

@@ -1,12 +1,16 @@
 # Sign-in, sessions, per-user data
 
 - **Start from the scaffold:** `hozu add feature notes --page / --with auth` writes `features/account` (sign-in page,
-  sign-out, `me`), the session cookie in `serve.ts`, per-user resolvers, and a redirect to `/login` when signed out.
-  Replace the name-only sign-in with real credentials before production; set `SESSION_SECRET` (and
-  `SESSION_SECURE=true` behind HTTPS).
+  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; set `SESSION_SECRET` (production without it refuses to start).
 - `project({ session: z.object({ user: z.string() }) })` declares the identity. Queries with `scope: 'user'` and all
   mutations receive `session`; public queries never do. A mutation calls `setSession(value)` (or `null` to sign out).
-- `createServer({ session: sessionCookie({ name: 'sid', secret }) })` (from `@hozu/runtime-server`): a signed,
-  HttpOnly cookie. The session never reaches browser JavaScript.
-- Guard pages: `head: { query: me, redirects: { Unauthorized: login }, … }`.
+- 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.
+- Guard pages: `head: { query: me, …, failed: { Unauthorized: login } }`; a role check answers 403 with
+  `failed: { Unauthorized: login, Forbidden: 403 }` (`hozu docs pages`).
 - Calling another API with a token: keep the token in the session (server side) and read it in the resolver.

package/skill/topics/content.md

@@ -1,7 +1,7 @@
 # Markdown, images, share images, fonts, preview, offline
 
 - **Markdown:** `@hozu/content`: `const posts = await loadCollection({ dir: new URL('./content/posts/', import.meta.url), schema })`
-  in `server.ts` gives `{ slug, data, html, headings }`; return it from query resolvers and render `ui.html(post.html)`.
+  in `app.ts` gives `{ slug, data, html, headings }`; return it 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). With `@hozu/image`, `hozu build` adds WebP `srcset` widths.
 - **Share images:** `head.render → image: ui.og({ title, subtitle })` (needs `og: ogImage` from `@hozu/image` in

package/skill/topics/contracts.md

@@ -1,11 +1,14 @@
 # Contracts
 
-A transition that **decides** needs a contract: a guard, a `navigate`, or a `fn()` in its values (HZ016 prints each
-missing one, ready to paste). Transitions that only copy values need none: `hozu.lock.json` records every transition
-in readable form, and a change shows as HZ018 `was: … now: …` until `hozu check --update-lock` accepts it.
+A transition that **decides** needs a contract: a guard, a `navigate`, or a `fn()`, a comparison or a computing
+operator (`+ - ?? ?: .length .includes`) in its values (HZ016 prints each missing one, ready to paste). Transitions that
+only copy values need none (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; then list the accepted
+`now:` lines in your summary. A deciding change also needs a contract that fails against the old behaviour (HZ018);
+renaming or copying a contract does not count.
 ```ts
 export const addsValid = contract(m, {
-  given: { state: 'idle' },                          // context defaults to initialContext
+  given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields
   when: [
     { send: Add, payload: { title: 'Milk' } },
     { done: addItem, result: { id: 'i9', title: 'Milk', done: false } },
@@ -17,5 +20,5 @@ export const addsValid = contract(m, {
   },
 })
 ```
-Add contracts to the feature's `declarations`. When a contract fails (HZ015), decide which is intended — the
+Export contracts from `views.ts` (or any module the feature lists). When a contract fails (HZ015), decide which is intended — the
 machine or the contract — before changing either.

package/skill/topics/data.md

@@ -4,8 +4,8 @@
 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' = per-session data (needs project({ session }))
-  freshness: 'static',              // | { revalidate: seconds } | { swr: seconds } | 'live'
+  scope: 'public',                  // 'user' = the session's data (needs project({ session }))
+  freshness: 'static',              // | 'request' | { revalidate: seconds } | { swr: seconds } | 'live'
   tags: () => [itemsTag()],          // optional; (input) => [...]
 })
 export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, scope: 'public',
@@ -15,21 +15,34 @@ export const addItem = mutation({
   errors: { Duplicate: z.object({ title: z.string() }) },          // optional: declared failures
   invalidates: () => [itemsTag()],                                  // refreshes queries with these tags
 })
-export const visible = fn({                   // computation: pure JS, self-contained (no imports, no helpers outside impl: HZ047)
+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),
 })
 ```
 - Call a `fn` from views or machines with data: `ui.each(visible({ items, show: ctx.show }), 'id', …)`.
+- 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.
-- **Resolvers** (`server.ts`, or `features/<name>/server.ts` from the scaffold):
+- Freshness: public data is `'static'` with tags unless it changes without a declared writer. `'request'` reads
+  once per request (any scope; a public one makes its page uncacheable). User data is `'request'` or `'live'` only
+  (HZ049). `'live'` is only for push updates and needs tags (HZ050).
+- `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 }`.
+- **Query resolvers only read.** Writes happen in mutation and endpoint resolvers: 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 `app.ts`, or `features/<name>/server.ts` from the scaffold, spread into it) get the
+  schema-parsed input (defaults and transforms applied):
 ```ts
-export const createResolvers = () => resolvers(project, (implement) => [
+export default app({ resolvers: resolvers(project, (implement) => [
   implement(listItems, () => items.map((i) => ({ ...i }))),
   implement(getItem, ({ id }, { fail }) => items.find((i) => i.id === id) ?? fail('NotFound', { id })),
   implement(addItem, ({ title }, { fail, session }) => /* … */ ),
-])
+]) })
 ```
 - 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

@@ -1,12 +1,16 @@
 # Deployment
 
-- **Node:** `npm start` (`node --import @hozu/transform/register serve.ts`). `hozu build` writes `dist/public/`,
-  `dist/manifest.json` and `dist/server/render.js`; serve with
-  `createServer({ build: buildProject(project, { manifest }), manifest, publicDir: 'dist/public', … })`.
+- **One app module:** `project({ app: new URL('./app.ts', import.meta.url) })`, and `app.ts` default-exports
+  `app({ resolvers: resolvers(project, (implement) => [...]), session?, widgets?, og?, csp?, onError?, preview? })`
+  from `@hozu/runtime-server`. `hozu serve`, `hozu check`, `hozu get`, `hozu browse` and `testApp(app)` all run this
+  module, so what the tools verify is what production serves. There is no wrapper position: headers go through
+  `project({ http })`, statuses through `head.failed` and endpoint `failed`, the language through the URL.
+- **Node:** `npm start` is `hozu serve`: adapter-node on `PORT` (and `HOST`), `process.env`, styles, images and
+  `public/`. `hozu build` writes `dist/public/`, `dist/manifest.json` and `dist/server/render.js`.
 - **Edge (Bun, Deno, Workers, Vercel):** bundle with `hozuTransform()` from `@hozu/transform/esbuild`, then
-  `createHandler({ build: buildProject(project, { manifest }), manifest, render, resolvers })` from
-  `@hozu/runtime-server`, `export default { fetch: handler.fetch }`, where `render` is `import * as render from
-  './dist/server/render.js'`.
-- **Static host (GitHub Pages):** `exportStatic({ build, styles, resolvers, outDir })` from `@hozu/adapter-static`
-  writes every page without per-request data plus the files they link to, and lists skipped routes.
-- Set `SESSION_SECRET` (and `SESSION_SECURE=true`) when the app has sessions.
+  `createHandler(app, { manifest, render, env })` from `@hozu/runtime-server` and
+  `export default { fetch: handler.fetch }`, where `render` is `import * as render from './dist/server/render.js'`.
+- **Static host (GitHub Pages):** `exportStatic({ build, styles, resolvers: appOptionsOf(app).resolvers, outDir })`
+  from `@hozu/adapter-static` writes every page without per-request data, and lists skipped routes.
+- Set `SESSION_SECRET` when the app has sessions (production refuses to start without it). The default store keeps
+  sessions in memory per process; an edge or multi-instance deployment passes a shared store as `app({ session })`.

package/skill/topics/diagnostics.md

@@ -7,7 +7,7 @@ around the rule.
 |---|---|---|
 | HZ001 | state unreachable | add a transition to it or delete it |
 | HZ002 | event handled nowhere | handle it in a state or remove it |
-| HZ003 / HZ007 | unknown effect / reference | add it to `feature({ declarations })`, or fix the name (the patch suggests one) |
+| HZ003 / HZ007 | 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` |
@@ -15,21 +15,21 @@ around the rule.
 | HZ009 | a guardless transition shadows later ones | put guarded transitions first |
 | HZ014 | wrong builder output, or a method called on data (`.map`, `.toUpperCase()`) | follow the builder signature; lists: `ui.each`; computation: a `fn()` |
 | HZ015 / HZ017 | 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`, `fn`) has no contract | add the contract from the snippet |
-| HZ018 | behaviour changed; the message shows `was: … now: …` | decision: update its contract; copy-only transition: `--update-lock` if intended |
-| HZ021 | a query or mutation without a resolver | `implement(...)` it in server.ts |
+| 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 |
+| 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 |
+| 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 |
-| HZ024 / HZ025 | route params mismatch (keys, or a schema that does not fit `:x?`/`:x+`/`:x*`) / page with params but no `entries` | align them / add `entries` |
+| HZ024 / HZ025 | 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 |
 | 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 written as a string | `ui.link(route, params)` |
-| HZ033 | DOM text into an enum, number or boolean field | a `<select>` with enum options / `valueAsNumber` / `checked` |
+| 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 | read its values with `ui.dom.form('name')` |
+| HZ036 | (warning) a form needs JavaScript | read its values with `ui.dom.form('name')` / `ui.dom.formAll('name')` |
 | 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 `createServer({ csp })`) |
 | HZ039 | `basePath` is not `''` or `/segment[/segment…]` | e.g. `'/shop'`, no trailing slash |
@@ -37,7 +37,24 @@ around the rule.
 | HZ041 | a machine uses a message, `ui.format` or `locale` | store a code in context; choose the message in the view |
 | 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 | `serve.ts` misses the widget bundle or the session store | add `widgets: await bundleWidgets(build)` / `session: sessionCookie(…)` |
-| HZ046 | an endpoint path is reserved, has params, or collides with a page, redirect or endpoint | use a static path such as `/api/…` (patch) |
-| HZ047 | a `fn` body uses a helper or constant defined outside `impl` (it is sent to the browser as source) | write the helper inside `impl`, or pass the value as input |
+| HZ045 | no `project({ app })`, its default export is not `app(…)`, or views use widgets and `app()` has none | `export default app({ resolvers, widgets: bundleWidgets })` |
+| HZ046 | an endpoint path is reserved, has params or collides; an error without a status; a form posting to it with another method or an undeclared field | a static path such as `/api/…` (patch); map every error in `failed` |
+| 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 widget or another view | as HZ055 |
+| HZ064 | two contracts with identical IR | remove one (patch) |
 | 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'`) |

package/skill/topics/endpoints.md

@@ -1,12 +1,24 @@
-# Endpoints (webhooks, JSON APIs, auth callbacks)
+# Endpoints (webhooks, JSON APIs, auth callbacks, downloads)
 
 ```ts
-export const orderHook = endpoint({ method: 'POST', path: '/api/hooks/order',
-  input: z.object({ id: z.string() }), output: z.object({ received: z.string() }) })   // in declarations
-implement(orderHook, ({ id }, { request, session, setSession, env }) => ({ received: id }))   // in resolvers
+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, POST input from a JSON or form body; invalid input answers 400
-  `{ message, fields }`. The output is validated and sent as JSON.
-- `output: 'response'`: return a web `Response` yourself (redirects, headers); `setSession(value)` adds the cookie.
-- Paths are static and outside pages, redirects and `/_hozu/` (HZ046, with a patch). Cross-site browser POSTs are
-  rejected; server-to-server calls (no `Origin`) are accepted. `hozu get /api/x` tries one without a server.
+- GET input comes from the query string (coerced by the schema), POST input from a JSON or form body. Invalid input
+  answers 400 `{ error: 'Invalid', message, fields }`; `fail(name, payload)` answers `failed[name]` with
+  `{ error, message, fields? }` (statuses 400 401 403 404 409 410 422 429; every declared error is mapped, HZ046).
+- `output` is one of: a schema (validated, sent as JSON); `'redirect'`, returning `redirect(ui.link(route, params))`
+  from the context (303, with basePath); `'response'`, a web `Response` 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.
+- `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).
+- Links: `ui.link(getEndpoint, input)` is the URL of a GET endpoint (flat scalar input, HZ035);
+  `ui.form({ method: 'post', action: ui.link(postEndpoint) }, [...])` posts a native form to a POST endpoint, whose
+  input declares every field name (HZ046). Another feature links to it only when it is in `exports` and imported (HZ006).
+- Paths are static and outside pages, redirects and `/_hozu/` (HZ046, with a patch). Responses carry `nosniff` and a
+  referrer policy. Cross-site browser POSTs are rejected; server-to-server calls (no `Origin`) are accepted.

package/skill/topics/feature.md

@@ -0,0 +1,79 @@
+# 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`.
+
+## 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 })
+```
+Relative imports end in `.ts`.
+
+## 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()] })
+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()] })
+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))`.

package/skill/topics/forms.md

@@ -1,8 +1,8 @@
 # Forms
 
-- **Works without JavaScript** when the submit payload reads only `ui.dom.form('name')`, literals, context, params
-  and search (else HZ036 warns): the server runs the same machine for a native post, then redirects or re-renders
-  with the result. Put every value the submit needs in a named field (a `<select name="kind">`).
+- **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): the server runs the same machine for a native post, then
+  redirects or re-renders with the result. Put every value the submit needs in a named field (a `<select name="kind">`).
 ```ts
 ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) } }, [
   ui.label({ for: 'title' }, ['Title']),
@@ -22,3 +22,14 @@ ui.p({ id: 'title-error', class: 'text-sm text-rose-600' }, [ctx.fields.title])
 - **Per-item actions without JS:** wrap each button in its own small form.
 - **Enum from a select:** `ui.dom.form('kind')` or `ui.dom.value` fills an enum field only when every literal
   option value is a member (HZ033).
+- **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. Keep limits out of the event payload (HZ061).

package/skill/topics/http.md

@@ -12,6 +12,6 @@ http: {
   headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // not cache-control (HZ038)
 },
 ```
-Server options: `createServer({ build, styles, resolvers, session?, widgets?, onError?, csp?, images?, og?, preview? })`.
+Server options live in the app module: `app({ resolvers, session?, widgets?, onError?, csp?, og?, preview? })`.
 A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { script: ['https://…'] }` adds sources.
 There are no rewrites: one URL has one owner. For your own HTTP routes, see `hozu docs endpoints`.

package/skill/topics/i18n.md

@@ -1,11 +1,16 @@
 # Languages
 
-- `site: { lang: 'en', locales: ['en', 'zh-TW'], … }`: every URL gets a locale prefix (`/en/posts/a`); routes and
-  `ui.link` stay locale-free; `/` redirects by `Accept-Language`. `<html lang>`, hreflang and the sitemap are derived.
-- `export const text = ui.messages('en', { en: { saved: '{count} saved' }, 'zh-TW': { saved: '已儲存 {count} 筆' } })`
-  in the feature's `declarations`; use `text.title` or `text.saved({ count })` in views and `head.render`. Every locale
+- **The URL holds the language.** Reload, sign-in and sign-out keep it, because every link and `navigate` resolves
+  `ui.link` in the page's locale. Do not add a cookie, a session field or a server rewrite for the language.
+- `site: { lang: 'en', locales: ['en', 'de'], … }`: the default locale keeps its URLs (`/posts/a`), the others are
+  prefixed (`/de/posts/a`); `/en/posts/a` answers 308 `/posts/a`. There is no `Accept-Language` redirect: a new visit
+  to an unprefixed URL shows `site.lang`. Routes and `ui.link` stay locale-free; contracts expect the default URLs.
+  `<html lang>`, hreflang and the sitemap are derived. A page route starting with a locale segment is HZ060.
+- A language switch is a link: `ui.a({ href: ui.alternate('de') }, ['Deutsch'])`, or
+  `locale === 'en' ? ui.alternate('de') : ui.alternate('en')`.
+- `export const text = ui.messages('en', { en: { saved: '{count} saved' }, de: { saved: '{count} gespeichert' } })`
+  exported from a module the feature lists; use `text.title` or `text.saved({ count })` in views and `head.render`. Every locale
   needs every key with the same `{placeholders}` (HZ040). Plurals: `'{n, plural, =0 {none} one {# item} other {# items}}'`.
 - Machines never hold translated text (HZ041): store a code and choose the message in the view.
 - `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; `ui.alternate('zh-TW')` links the
-  current page in another language.
+  `ui.format.relative(n, 'day')`, `ui.format.list(xs)`. `locale` is in every view.

package/skill/topics/machine.md

@@ -5,10 +5,10 @@ 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(Draft, { target: 'idle', assign: (e) => { ctx.draft = e.text } }),
         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 } }),
@@ -33,8 +33,14 @@ export const m = machine({
   `ctx.list = ctx.list.filter((i) => i.id !== e.id)`. Values are event (`e`), result (`r`) or error fields,
   context, literals, operators and `fn()` calls.
 - **guard** returns a condition: comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
-- **navigate** sends the browser to `ui.link(route, params, search)` after the transition.
+- **navigate** sends the browser to `ui.link(route, params, search?)` after the transition.
 - `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 and re-runs its `invoke`: do not handle the busy event in the busy
   state. Machines never hold translated text (store a code, choose the message in the view).
 - Events: `export const Add = event({ payload: z.object({ title: z.string() }) })`.

package/skill/topics/pages.md

@@ -21,9 +21,10 @@ export default project({
     ui.page(itemPage, {
       views: [Detail],
       head: {
-        query: getItem,                                    // its failure sets the status (NotFound → 404)
+        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
     }),
@@ -32,8 +33,21 @@ export default project({
 })
 ```
 - `head.render` fields: `title`, `description`, `type` (`'website' | 'article'`), `image` (a URL, `ui.asset(...)`
-  or `ui.og({ title })`), `published`, `noindex`. `head.redirects: { Unauthorized: login }` maps errors to routes.
+  or `ui.og({ title })`), `published`, `noindex`.
+- `head.failed` maps each declared error of the head query to a route without params (303) or to `403`, `404` or
+  `410`: `failed: { Unauthorized: login, Forbidden: 403 }`. It is exhaustive (HZ051); `Unexpected` is always 500.
+  It maps declared errors only: a head query that always fails is not a redirect.
+- **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` |
+
+- A route no page renders is 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>`). A view with a machine listed
-  on several pages, in the same order, keeps its DOM and state across links when it never reads `params` / `search`.
+- A page loads JS only when a machine-bound part renders on it (`hozu plan <route>`). Every link loads a document;
+  state across pages lives in the URL (`seed`), on the server (queries) or in a widget's own storage.