create-hozu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 olevatorr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# create-hozu
+
+Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md.
+
+Part of [Hozu](https://github.com/olevatorr/Hozu#readme), an AI-first web framework. It creates an app and sets it up for a coding agent:
+
+```sh
+npm create hozu@latest my-app -- --agent claude   # CLAUDE.md + .claude/skills/hozu
+npm create hozu@latest my-app -- --agent agents   # AGENTS.md + .agents/skills/hozu (Codex, Cursor, Copilot…)
+npm create hozu@latest my-app -- --agent both
+```
+
+Without `--agent` it asks.
+
+```sh
+npm create hozu@latest my-app
+```
+
+Requires Node 22.18 or newer. Documentation: the [README](https://github.com/olevatorr/Hozu#readme) and the
+agent skill that `create-hozu` writes into each app.
+
+MIT © olevatorr

package/bin/create-hozu.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../dist/bin.js'
+
+process.exitCode = await main(process.argv.slice(2))

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"AAkBA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmD1D"}

package/dist/bin.js

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { AGENTS, createApp, runnerOf } from './index.js';
+const usage = `Usage: create-hozu [directory] [--agent claude|agents|both]
+
+  --agent claude   CLAUDE.md + .claude/skills/hozu (Claude Code)
+  --agent agents   AGENTS.md + .agents/skills/hozu (Codex, Cursor, Copilot and other agents)
+  --agent both     both
+`;
+const supported = () => {
+    const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+    return major > 22 || (major === 22 && minor >= 18);
+};
+export async function main(argv) {
+    if (!supported()) {
+        process.stderr.write(`Hozu needs Node 22.18 or newer (this is ${process.versions.node}).\n`);
+        return 1;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { agent: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+    });
+    if (values.help) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const interactive = process.stdin.isTTY === true;
+    const ask = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+    try {
+        let dir = positionals[0];
+        if (!dir) {
+            if (!ask)
+                throw new Error('Give a directory: create-hozu my-app --agent claude');
+            dir = (await ask.question('Project directory (my-hozu-app): ')).trim() || 'my-hozu-app';
+        }
+        let agent = values.agent;
+        if (agent && !AGENTS.includes(agent))
+            throw new Error(`--agent must be one of ${AGENTS.join(', ')}`);
+        if (!agent) {
+            if (!ask)
+                throw new Error('Choose the coding agent: --agent claude|agents|both');
+            const answer = (await ask.question('Which coding agent will work on this app?\n  1) Claude Code (CLAUDE.md)\n  2) Other agents (AGENTS.md)\n  3) Both\nChoose 1-3 (1): ')).trim();
+            agent = AGENTS[Number(answer || '1') - 1] ?? 'claude';
+        }
+        const target = resolve(dir);
+        const version = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
+        const runner = runnerOf(process.env.npm_config_user_agent);
+        await createApp(target, { name: basename(target), agent, version, runner });
+        const install = runner === 'npx' ? 'npm install' : runner === 'bunx' ? 'bun install' : `${runner.split(' ')[0]} install`;
+        process.stdout.write(`\nCreated ${basename(target)} for ${agent === 'both' ? 'Claude Code and other agents' : agent === 'claude' ? 'Claude Code' : 'other agents'}.\n\n  cd ${dir}\n  ${install}\n  ${runner === 'pnpm exec' ? 'pnpm' : runner === 'npx' ? 'npm' : runner.split(' ')[0]} start\n\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`create-hozu: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        ask?.close();
+    }
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+export type Agent = 'claude' | 'agents' | 'both';
+export type Runner = 'pnpm exec' | 'npx' | 'yarn' | 'bunx';
+export declare const AGENTS: readonly Agent[];
+export declare const defaultSkill: string;
+export declare const runnerOf: (userAgent: string | undefined) => Runner;
+export interface AgentOptions {
+    name: string;
+    runner: Runner;
+    skillSource?: string;
+}
+export declare function writeAgentFiles(dir: string, agent: Agent, options: AgentOptions): Promise<string[]>;
+export interface CreateOptions extends AgentOptions {
+    agent: Agent;
+    version: string;
+}
+export declare const packageJson: (name: string, version: string) => {
+    name: string;
+    private: boolean;
+    type: string;
+    scripts: {
+        check: string;
+        start: string;
+        build: string;
+    };
+    dependencies: {
+        '@hozu/adapter-node': string;
+        '@hozu/core': string;
+        '@hozu/css': string;
+        '@hozu/data': string;
+        '@hozu/runtime-server': string;
+        '@hozu/schema-zod': string;
+        zod: string;
+    };
+    devDependencies: {
+        '@hozu/cli': string;
+        '@types/node': string;
+        typescript: string;
+    };
+    engines: {
+        node: string;
+    };
+};
+export declare function createApp(dir: string, options: CreateOptions): Promise<string[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAChD,MAAM,MAAM,MAAM,GAAG,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1D,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EAAiC,CAAA;AAGpE,eAAO,MAAM,YAAY,QAAsB,CAAA;AAiB/C,eAAO,MAAM,QAAQ,cAAe,MAAM,GAAG,SAAS,KAAG,MAGxD,CAAA;AAWD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBzG;AAYD,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,MAAM;;;;;QAKrD,KAAK;QACL,KAAK;QACL,KAAK;;;QAGL,oBAAoB;QACpB,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,sBAAsB;QACtB,kBAAkB;QAClB,GAAG;;;QAGH,WAAW;QACX,aAAa;QACb,UAAU;;;QAED,IAAI;;CACf,CAAA;AAEF,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBtF"}

package/dist/index.js

@@ -0,0 +1,104 @@
+import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const AGENTS = ['claude', 'agents', 'both'];
+const root = fileURLToPath(new URL('../', import.meta.url));
+export const defaultSkill = join(root, 'skill');
+const templates = join(root, 'templates');
+const targets = (agent) => [
+    {
+        guide: 'CLAUDE.md',
+        skill: '.claude/skills/hozu',
+        read: 'Use the `hozu` skill (`__SKILL__/SKILL.md`).',
+    },
+    {
+        guide: 'AGENTS.md',
+        skill: '.agents/skills/hozu',
+        read: 'Read `__SKILL__/SKILL.md` before writing or changing any Hozu code.',
+    },
+].filter((_, i) => agent === 'both' || (agent === 'claude' ? i === 0 : i === 1));
+export const runnerOf = (userAgent) => {
+    const name = userAgent?.split('/')[0];
+    return name === 'npm' ? 'npx' : name === 'yarn' ? 'yarn' : name === 'bun' ? 'bunx' : 'pnpm exec';
+};
+const exists = (path) => stat(path).then(() => true, () => false);
+const fill = (text, values) => Object.entries(values).reduce((out, [key, value]) => out.replaceAll(`__${key}__`, value), text);
+export async function writeAgentFiles(dir, agent, options) {
+    const written = [];
+    const guide = await readFile(join(templates, 'guide.md'), 'utf8');
+    for (const t of targets(agent)) {
+        const skill = join(dir, t.skill);
+        await rm(skill, { recursive: true, force: true });
+        await mkdir(dirname(skill), { recursive: true });
+        await cp(options.skillSource ?? defaultSkill, skill, { recursive: true });
+        written.push(t.skill);
+        const file = join(dir, t.guide);
+        if (await exists(file))
+            continue;
+        const values = {
+            NAME: options.name,
+            RUN: options.runner,
+            SKILL: t.skill,
+            NOTE: options.runner === 'pnpm exec'
+                ? ''
+                : `\nThe skill writes commands as \`pnpm exec …\`; in this app use \`${options.runner} …\`.\n`,
+        };
+        await writeFile(file, fill(fill(guide, { READ: t.read }), values));
+        written.push(t.guide);
+    }
+    return written;
+}
+async function files(dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await files(path)));
+        else
+            out.push(path);
+    }
+    return out;
+}
+export const packageJson = (name, version) => ({
+    name,
+    private: true,
+    type: 'module',
+    scripts: {
+        check: 'tsc --noEmit -p . && hozu validate',
+        start: 'node serve.ts',
+        build: 'hozu build',
+    },
+    dependencies: {
+        '@hozu/adapter-node': `^${version}`,
+        '@hozu/core': `^${version}`,
+        '@hozu/css': `^${version}`,
+        '@hozu/data': `^${version}`,
+        '@hozu/runtime-server': `^${version}`,
+        '@hozu/schema-zod': `^${version}`,
+        zod: '^4.6.5',
+    },
+    devDependencies: {
+        '@hozu/cli': `^${version}`,
+        '@types/node': '^22.20.4',
+        typescript: '^7.0.2',
+    },
+    engines: { node: '>=22.18' },
+});
+export async function createApp(dir, options) {
+    if ((await exists(dir)) && (await readdir(dir)).length)
+        throw new Error(`${dir} is not empty. Choose a new directory name.`);
+    const app = join(templates, 'app');
+    const written = [];
+    for (const source of await files(app)) {
+        const rel = relative(app, source);
+        const target = join(dir, rel === 'gitignore' ? '.gitignore' : rel);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, fill(await readFile(source, 'utf8'), { NAME: options.name }));
+        written.push(relative(dir, target));
+    }
+    await writeFile(join(dir, 'package.json'), `${JSON.stringify(packageJson(options.name, options.version), null, 2)}\n`);
+    written.push('package.json');
+    written.push(...(await writeAgentFiles(dir, options.agent, options)));
+    return written;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-hozu",
+  "version": "0.1.0",
+  "description": "Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md",
+  "keywords": [
+    "hozu",
+    "framework",
+    "ai",
+    "agents",
+    "ssr",
+    "islands",
+    "typescript"
+  ],
+  "homepage": "https://github.com/olevatorr/Hozu/tree/main/packages/create-hozu#readme",
+  "bugs": {
+    "url": "https://github.com/olevatorr/Hozu/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olevatorr/Hozu.git",
+    "directory": "packages/create-hozu"
+  },
+  "license": "MIT",
+  "author": "olevatorr",
+  "type": "module",
+  "bin": {
+    "create-hozu": "./bin/create-hozu.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: hozu
+description: Build or change an app with the Hozu framework (packages @hozu/*, files like hozu.config.ts, features/*/model.ts, views.ts). Use it before writing any Hozu code. It is the complete authoring reference, so you do not need to read the framework source.
+---
+
+# Hozu authoring guide
+
+Hozu is not in your training data. These files are the whole API; do not read `node_modules/@hozu`.
+- **Changing an app:** read `changing.md` first, then only the app's own files.
+- **Building an app:** read this file and `patterns.md`, then copy the shape of `example/` (a verified app).
+- **`reference.md`** when the task needs it: routes, DOM fields, no-JS forms, `head`, 404/500, field errors,
+  sessions, languages, env, HTTP, Markdown, images, preview, PWA, page tests, deployment.
+- **A diagnostic you do not understand:** `diagnostics.md`.
+
+## Mental model
+- The app is **data**: builders record an IR that is validated, then rendered. Only machine views ship JS.
+- **References are recorded, not evaluated.** In `render`, `states`, `assign` and `guard`, `ctx.x`, `item.title`,
+  `params.id` are placeholders: never use `if`, `?:`, `&&`, `.filter()`, `.map()`, `===` or template strings on
+  them. Use `op.*` for comparisons and updates, `ui.if` / `ui.each` for structure, and a `fn()` for anything else.
+  Plain JS on *constants* is fine: `['a', 'b'].map((k) => ui.option(...))`.
+- **Side effects only through `query` / `mutation`.** Queries render with `ui.query`; a mutation runs when the
+  feature's one machine *enters* a state whose `invoke` calls it, and returns as `done` / `failed`.
+- **Every transition needs a contract.** A behaviour change without a contract change is an error.
+- **Absent means absent.** Optional fields are omitted, never `null`. Only `route({ params, search })` and
+  `ui.link(route, params, search)` spell "none" as `null`.
+
+## Files
+```
+hozu.config.ts        project(): schema adapter, site, routes, pages, features
+routes.ts              route() declarations
+server.ts              resolvers(project, implement => [...]): query/mutation implementations
+serve.ts               createServer({ build, styles, resolvers }).listen(PORT)
+app.css                @import "tailwindcss";
+features/<name>/
+  model.ts             schemas, events, query / mutation / tag / fn, the machine
+  views.ts             views, contracts, feature()
+```
+Relative imports end in `.ts`. Any other split works too.
+
+## Checks (from the app directory)
+```
+pnpm exec tsc --noEmit -p .  # types
+pnpm exec hozu validate  # all rules + contracts; --json adds patches
+pnpm exec hozu validate --update-lock  # accept a clean, intended behaviour change
+PORT=4700 node serve.ts & echo $!  # run it; stop it with kill <pid>, not pkill -f
+```
+Each diagnostic has a `file:line`, a cause and a fix: apply the fix, do not work around the rule.
+
+## model.ts
+```ts
+export const Item = z.object({ id: z.string(), title: z.string(), read: z.boolean() })
+export const Add = event({ payload: z.object({ title: z.string() }) })
+
+export const itemsTag = tag({ param: null })  // or tag({ param: z.string() }) → itemsTag(x)
+export const listItems = query({
+  input: z.object({}), output: z.array(Item),
+  scope: 'public',  // 'user' = per-session data (needs project session)
+  freshness: 'static',  // | { revalidate: s } | { swr: s } | 'live'
+  tags: () => [itemsTag()],  // optional; (input) => [...]
+})
+export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, … })
+export const addItem = mutation({
+  input: z.object({ title: z.string().min(2, 'Use at least 2 characters') }), output: Item,
+  errors: { Duplicate: z.object({ title: z.string() }) },  // optional: declared failures
+  invalidates: () => [itemsTag()],  // refreshes queries with these tags
+})
+export const unread = fn({  // pure JS, self-contained: no imports or closures
+  input: z.object({ items: z.array(Item) }), output: z.array(Item),
+  impl: ({ items }) => items.filter((i) => !i.read),
+})
+
+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(Draft, { target: 'idle', assign: (e) => [op.set(ctx.draft, e.text)] }),
+        on(Add, { target: 'adding', guard: (e) => op.neq(e.title, ''),  // first matching guard wins
+                  assign: (e) => [op.set(ctx.draft, e.title), op.set(ctx.error, null)] }),
+      ],
+    },
+    adding: {
+      ignore: [Draft, Add],  // events dropped while busy (HZ005)
+      invoke: invoke(addItem, {  // runs on entering the state
+        input: { title: ctx.draft },
+        done: [{ target: 'idle', assign: () => [op.set(ctx.draft, '')],
+                 navigate: (r) => ui.link(itemPage, { id: r.id }) }],  // optional
+        failed: {  // every declared error + Unexpected
+          Duplicate: [{ target: 'idle', assign: () => [op.set(ctx.error, 'Already exists')] }],
+          Unexpected: [{ target: 'idle', assign: (e) => [op.set(ctx.error, e.message)] }],
+        },
+      }),
+    },
+    flash: { after: [{ ms: 3000, target: 'idle' }] },  // timers; `final: true` for terminal states
+  }),
+})
+```
+- `op.set`, `op.append(list, item)`, `op.inc(n, by)`, `op.removeWhere(list, 'key', value)`.
+- Guards: `op.eq / neq / lt / lte / gt / gte`, `op.and(...)`, `op.or(...)`, `op.not(g)`, or a boolean `fn`. The
+  reference goes on the left: `op.eq(ctx.tab, 'design')`.
+- A transition to the same state re-enters it and re-runs its `invoke`; busy states `ignore` instead.
+
+## views.ts
+```ts
+export const Board = ui.view({
+  machine: m,  // optional: without it, no ctx / when / events, 0 JS
+  route: home,  // optional: render gets { params, search } typed by the route
+  render: ({ ctx, when, search }) =>
+    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,
+                   on: { input: ui.send(Draft, { text: ui.dom.value }) } }),
+        ui.button({ type: 'submit' }, ['Add']),
+      ]),
+      ui.if(op.neq(ctx.error, null), [ui.p({ role: 'alert' }, [ctx.error])], []),
+      when(['adding'], [ui.p({ 'aria-busy': 'true' }, ['Adding…'])]),
+      ui.query(listItems, {}, {
+        ready: (items) => ui.ul({}, [ui.each(items, 'id', (i) =>
+          ui.li({}, [ui.a({ href: ui.link(itemPage, { id: i.id }) }, [i.title])]))]),
+        pending: ui.p({}, ['Loading…']),  // or null
+        failed: { Unexpected: () => ui.p({ role: 'alert' }, ['Unavailable']) },
+      }),
+    ]),
+})
+```
+- `ui.<tag>(attrs, children)`; attribute values are literals, references or guards.
+- `class` is a static string of Tailwind classes that must exist (HZ026). Conditional classes:
+  `toggle: { 'bg-indigo-600 text-white': op.eq(ctx.tab, t) }`. CSS variables: `vars: { '--hue': item.hue }`.
+- Events: `on: { click: ui.send(Event, payload) }`. Payload fields: literals, references, `ui.dom.value`,
+  `ui.dom.form('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`.
+- `ui.each(list, 'id', (item) => node)` (key `null` for primitives).
+- Links: `ui.link(route, params, search)`, never a string path (HZ032). The third argument exists only when the
+  route declares `search` (`null` = all defaults). Filters that belong in the URL are `search` links, not context.
+- A form whose submit reads only `ui.dom.form(...)`, literals, context, params and search also works without JS.
+
+### Contracts
+```ts
+export const adds = contract(m, {
+  given: { state: 'idle' },  // context: optional, defaults to initialContext
+  when: [
+    { send: Add, payload: { title: 'A' } },
+    { done: addItem, result: { id: 'i9', title: 'A', read: false } },
+  ],  // or { failed: addItem, error: 'Duplicate', data } / { elapse: ms }
+  expect: {
+    state: 'idle',
+    changes: { error: null },  // only what changes; every other field must stay equal
+    effects: [{ effect: addItem, input: { title: 'A' } }, { navigate: '/items/i9' }],  // optional: none
+  },
+})
+```
+Cover each `on`, `done`, `failed` and `after` once. `given.context` sets up a full context; nested objects in
+`changes` are patches too, arrays are replaced. HZ016 prints each missing contract ready to paste.
+
+### Feature
+```ts
+export const items = feature({
+  id: 'items',
+  intent: { summary: 'A reading list', invariants: ['Titles are unique'] },  // invariants optional
+  declarations: { Add, Draft, itemsTag, listItems, getItem, addItem, unread, m, Board, Detail, adds },
+})
+```
+Every declaration goes in `declarations` once, under its name. Optional: `imports: [otherFeature]`,
+`exports: [Event, query, …]` (all other features may use), `styles: [new URL('./x.css', import.meta.url)]`.
+
+## hozu.config.ts
+```ts
+export default project({
+  schema: zodAdapter,
+  styles: new URL('./app.css', import.meta.url),
+  site: { url: 'http://localhost:3000', name: 'Items', lang: 'en' },
+  routes: { home, itemPage },
+  pages: [
+    ui.page(home, { views: [Board], head: { render: () => ({ title: 'Items', description: 'All items.' }) } }),
+    ui.page(itemPage, {
+      views: [Detail],
+      head: {
+        query: getItem,  // its failure sets the status (NotFound → 404)
+        input: (params) => ({ id: params.id }),
+        render: (item) => ({ title: item.title, description: item.title, type: 'article' }),
+      },
+      entries: { query: listItems, input: {}, params: (item) => ({ id: item.id }) },  // sitemap
+    }),
+  ],
+  features: [items],
+})
+```
+```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 })
+```
+
+## server.ts
+```ts
+export const createResolvers = () => resolvers(project, (implement) => [
+  implement(getItem, ({ id }, { fail }) => items.find((i) => i.id === id) ?? fail('NotFound', { id })),
+  implement(addItem, ({ title }, { fail }) => /* … */ fail('Duplicate', { title })),  // → failed.Duplicate
+])
+```
+Input failing its schema returns the error `Invalid` (`{ message, fields }`; see `reference.md`).

package/skill/changing.md

@@ -0,0 +1,40 @@
+# Changing a Hozu app
+
+Keep the loop short: read once, edit everything, check once, verify once.
+
+## 1. Read
+- The change request.
+- The app: `features/<name>/*.ts`, `server.ts`, `routes.ts`, `hozu.config.ts`. Below, *model* is where the
+  app keeps schemas, events, effects and the machine (`model.ts` in the recommended layout), and *views* is
+  where it keeps views, contracts and `feature()`.
+- Nothing else. The API is in `SKILL.md`; open `patterns.md` only for a pattern you have not seen in the app,
+  and `reference.md` only for a topic it lists.
+
+## 2. Where each kind of change goes
+| Change | Touch, in this order |
+|---|---|
+| New data field (e.g. `priority`) | model: the domain and input schemas → `server.ts` (seed data, store it) → views: show it, also in the detail view if there is one. If the user picks it in a form: a `<select name="…">` inside the form, sent with the submit as `ui.dom.form('…')` (HZ033 checks the options), plus the matching field in the event payload and the mutation input. |
+| New server action (e.g. "clear done") | model: a `mutation` with `invalidates`, an event, and `on(Event)` into a new busy state that `invoke`s the mutation, with `done` and every `failed` handled and the same `ignore` list as the other busy states → views: the control, the contracts, and both new declarations in `feature({ declarations })` → `server.ts`: `implement(...)` it. |
+| New UI-only state (a filter, a tab) | model: the context field, its initial value, an event and an `on` that `op.set`s it (add the event to every busy state's `ignore`) → views: the control, a contract, the event in `declarations`. |
+| New page | `routes.ts` (`params`, `search`) → a view with `route`, added to `declarations` → `ui.page(...)` in `hozu.config.ts` (with `head`, and `entries` when the route has params). |
+| New filter / sort / page number that should be in the URL | the route's `search` schema (with a default) → links with `ui.link(route, params, { key: value })` → read `search.key` in the view. No machine change. |
+
+Whenever the machine changes:
+- Add one contract per new transition; HZ016 prints each missing one ready to paste. A new context field needs
+  no change to existing contracts: `given` defaults to the initial context and `changes` lists only what changes.
+- Every busy state `ignore`s every event its visible controls can send. HZ005 prints the missing `ignore` entries.
+
+## 3. Check (once, after all edits)
+```
+pnpm exec tsc --noEmit -p . && pnpm exec hozu validate
+```
+Fix what they report. When the behaviour change is intended and everything is clean, run
+`pnpm exec hozu validate --update-lock`. HZ018 asks for this.
+
+## 4. Verify (once)
+Start the server with `PORT=4700 node serve.ts & echo $!`, then use one curl script:
+- pages: `curl -s localhost:4700/…`;
+- mutations:
+  `curl -s -X POST localhost:4700/_hozu/effect -H 'content-type: application/json' -d '{"effect":"<feature>.<mutation>","input":{…},"keys":[]}'`.
+
+Stop the server with `kill <pid>`, not `pkill -f` (that kills your own shell).

package/skill/diagnostics.md

@@ -0,0 +1,39 @@
+# 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.
+
+| 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 / HZ007 | unknown effect / reference | add it to `feature({ 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 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` |
+| HZ008 | a path does not exist in the schema | fix the property name |
+| HZ009 | a guardless transition shadows later ones | put guarded transitions first |
+| HZ014 | wrong builder output | follow the builder signature |
+| 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 without a contract | add the contract from the snippet |
+| HZ018 | behaviour changed without a contract change | update the contracts, then `--update-lock` |
+| HZ021 | a query or mutation without a resolver | `implement(...)` it in server.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` |
+| 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` |
+| 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')` |
+| 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 |
+| 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 |
+| HZ043 | `site.offline` has params, no page, or per-request data | point it at a static page, or remove `offline` |
+| 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/example/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";