@hozu/cli 0.18.2 → 0.20.0

package/skill/topics/deploy.md

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

package/skill/topics/diagnostics.md

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

package/skill/topics/endpoints.md

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

package/skill/topics/env.md

@@ -0,0 +1,44 @@
+# Environment
+
+```ts
+project({
+  env: {
+    files: ['.env', '.env.local'],                          // read by the CLI; a later file wins, the shell wins over all
+    server: z.object({ DB_URL: z.string(), API_INTERNAL: z.string().url().optional() }),
+    public: z.object({ SUPPORT_EMAIL: z.string().email(), API_URL: z.string().url() }),
+    internal: { API_URL: 'API_INTERNAL' },                  // on the server, 'either' effects call the internal URL
+  },
+})
+```
+- **Parsed at startup:** a missing value stops startup.
+- **Who reads what:** resolvers `ctx.env` (the `server` variables only); views `ui.env(PublicEnv).SUPPORT_EMAIL`;
+  fetch.ts `env` (public); machines cannot read env (HZ041). A server resolver that needs a URL the browser also
+  uses declares it in `server` too.
+- **Public values are sent to the browser.** Secrets go in `server`; a public name that looks secret (`…_SECRET`,
+  `…_TOKEN`, `…_KEY`) is HZ084.
+- Keep `.env` and `.env.local` out of git.
+
+<!-- more -->
+
+- **Parsing:** defaults and `z.coerce` apply; a variable set to the empty string counts as unset.
+- **Public values** reach page payloads and a static export (written into the pages at export time). Rename a
+  secret-looking name `PUBLIC_…` only if it is meant to be public.
+- **`internal`:** for an API the browser reaches at its public URL and the server reaches inside the network.
+  - fetch.ts keeps reading `env.API_URL`;
+  - on the server it gets `API_INTERNAL` when that is set, and the public value otherwise;
+  - the browser and CSP `connect` only ever see the public one;
+  - a mapping to undeclared variables is HZ085;
+  - it applies to fetch.ts only. A `runs: 'server'` resolver reads its own `server` variables:
+    `ctx.env.API_INTERNAL ?? ctx.env.API_URL` with both declared in `server`.
+- **`files`** are read by `hozu dev`, `serve`, `check`, `get`, `call`, `browse`, `build` and `env`. On the edge
+  (`createHandler`) and on hosting platforms, set the variables in the platform.
+- The files are read after `hozu.config.ts` is imported: a value the config itself reads at import time (rare)
+  comes from the shell. Resolvers, views and fetch.ts read the parsed env and see the files.
+- **`npx hozu env`** lists every variable: its side, whether it is required, its default, whether it is set now,
+  and its internal mapping. `--example` writes `.env.example`.
+- **Reserved by Hozu:**
+  - `PORT` (hozu dev also uses `PORT + 1`);
+  - `HOST`;
+  - `SESSION_SECRET` (required in production with sessions);
+  - `NODE_ENV`;
+  - `HOZU_TRANSFORM_CACHE=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,66 @@
+# 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).
+- **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
+
+- **Submitted values:** read them with `ui.dom.form('name')` / `ui.dom.formAll('name')` (plus literals, context,
+  params, search), so a submit before the page has loaded still arrives (HZ036 otherwise). Name every 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:** 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()`).
+- **An invalid native post:** 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,83 @@
+# 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`).
+- An `on` without `target` stays: its timers keep running and an `invoke` keeps going. Naming the state enters it
+  again (timers restart, `invoke` re-runs): a debounce, or a timer that repeats.
+- `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.
+- **refresh** reads the page's queries with those tags again: `on(RefreshNow, { refresh: () => [quotesTag()] })`;
+  every 30 s while live: `live: { after: [{ ms: 30_000, target: 'live', refresh: () => [quotesTag()] }] }` (Pause is
+  another state). **copy** writes text to the clipboard: `on(CopyLink, { copy: (e) => e.url })` (on an event: the
+  browser allows it only right after a click).
+
+<!-- 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: { on: [on(Add, { target: 'adding' })], after: [{ ms: 3000, target: 'idle' }] },   // a toast; the page stays usable
+  }),
+})
+```
+- **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).
+- 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.