create-hozu 0.6.0 → 0.8.0

package/dist/guide.d.ts

@@ -0,0 +1,29 @@
+export type Runner = 'pnpm exec' | 'npx' | 'yarn' | 'bunx';
+export declare const RUNNERS: readonly Runner[];
+export declare const BEGIN = "<!-- hozu: generated by hozu skill; edits between these markers are replaced -->";
+export declare const END = "<!-- /hozu -->";
+export declare const TARGETS: readonly [{
+    readonly guide: 'CLAUDE.md';
+    readonly skill: '.claude/skills/hozu';
+    readonly read: 'Use the `hozu` skill (`__SKILL__/SKILL.md`).';
+}, {
+    readonly guide: 'AGENTS.md';
+    readonly skill: '.agents/skills/hozu';
+    readonly read: 'Read `__SKILL__/SKILL.md` before writing or changing any Hozu code.';
+}];
+export type Target = (typeof TARGETS)[number];
+/** The released 0.3–0.7 guide, as `create-hozu` wrote it (0.6 added the browse line). */
+export declare const GUIDE_07 = "# __NAME__\n\nA web app built with Hozu (`@hozu/*`). Hozu is not in your training data.\n\n## Before writing code\n- __READ__\n- Changing existing code: read `__SKILL__/changing.md` first.\n- The files in `__SKILL__/` are the whole API. Do not read the framework source in `node_modules/@hozu`.\n\n## The loop\n```\n__RUN__ hozu add feature tasks --page / --with detail,toggle,filter,remove   # then edit the texts it lists\n                                          # add auth to the list for sign-in and per-user data\n__RUN__ hozu map                           # outline of the app with file:line, before a change\n__RUN__ hozu check                         # after every change: types, rules, contracts\n__RUN__ hozu check --update-lock           # only to accept a clean, intended behaviour change\n__RUN__ hozu get / --select button --forms  # try pages without a server: text, attributes, forms\n__RUN__ hozu post / --field title=Ship --next /   # submit a form like a browser\n__RUN__ hozu browse / --do 'click Save'     # real browser, no server: errors, widgets, text after steps\n```\n__NOTE__\n## Rules\n- After `hozu add feature`, do not print the generated files: edit the texts it lists; `hozu map` shows the rest.\n- Apply the fix each diagnostic gives; do not work around a rule.\n- Every behaviour change comes with a contract change.\n- Do not edit `__SKILL__/`: `__RUN__ hozu skill` rewrites it for the installed Hozu version.\n";
+export declare function currentGuide(): string;
+/** The 0.8 guide for one target, between the markers. */
+export declare const guideBlock: (target: Target, name: string, runner: Runner, template?: string) => string;
+export type BlockResult = {
+    kind: 'replaced' | 'marked' | 'written' | 'current';
+    code: string;
+} | {
+    kind: 'custom';
+    block: string;
+};
+/** The new Hozu block of a CLAUDE.md / AGENTS.md: between markers, or the whole file when it is a known template. */
+export declare function migrateGuide(existing: string | null, target: Target, dir: string, runner: Runner, template?: string): BlockResult;
+//# sourceMappingURL=guide.d.ts.map

package/dist/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../src/guide.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,MAAM,GAAG,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1D,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAAyC,CAAA;AAE9E,eAAO,MAAM,KAAK,qFAAqF,CAAA;AACvG,eAAO,MAAM,GAAG,mBAAmB,CAAA;AAEnC,eAAO,MAAM,OAAO;aAChB,KAAK,EAAE,WAAW;aAAE,KAAK,EAAE,qBAAqB;aAAE,IAAI,EAAE,8CAA8C;;aAEtG,KAAK,EAAE,WAAW;aAClB,KAAK,EAAE,qBAAqB;aAC5B,IAAI,EAAE,qEAAqE;EAErE,CAAA;AAEV,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAK7C,yFAAyF;AACzF,eAAO,MAAM,QAAQ,66CAyBpB,CAAA;AAqBD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,WAAY,MAAM,QAAQ,MAAM,UAAU,MAAM,8BACW,CAAA;AAElF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAErC,qHAAqH;AACrH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,QAAQ,SAAiB,GACxB,WAAW,CAkBb"}

package/dist/guide.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const RUNNERS = ['pnpm exec', 'npx', 'yarn', 'bunx'];
+export const BEGIN = '<!-- hozu: generated by hozu skill; edits between these markers are replaced -->';
+export const END = '<!-- /hozu -->';
+export const TARGETS = [
+    { 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.',
+    },
+];
+const BROWSE = "__RUN__ hozu browse / --do 'click Save'     # real browser, no server: errors, widgets, text after steps\n";
+/** The released 0.3–0.7 guide, as `create-hozu` wrote it (0.6 added the browse line). */
+export const GUIDE_07 = `# __NAME__
+
+A web app built with Hozu (\`@hozu/*\`). Hozu is not in your training data.
+
+## Before writing code
+- __READ__
+- Changing existing code: read \`__SKILL__/changing.md\` first.
+- The files in \`__SKILL__/\` are the whole API. Do not read the framework source in \`node_modules/@hozu\`.
+
+## The loop
+\`\`\`
+__RUN__ hozu add feature tasks --page / --with detail,toggle,filter,remove   # then edit the texts it lists
+                                          # add auth to the list for sign-in and per-user data
+__RUN__ hozu map                           # outline of the app with file:line, before a change
+__RUN__ hozu check                         # after every change: types, rules, contracts
+__RUN__ hozu check --update-lock           # only to accept a clean, intended behaviour change
+__RUN__ hozu get / --select button --forms  # try pages without a server: text, attributes, forms
+__RUN__ hozu post / --field title=Ship --next /   # submit a form like a browser
+${BROWSE}\`\`\`
+__NOTE__
+## Rules
+- After \`hozu add feature\`, do not print the generated files: edit the texts it lists; \`hozu map\` shows the rest.
+- Apply the fix each diagnostic gives; do not work around a rule.
+- Every behaviour change comes with a contract change.
+- Do not edit \`__SKILL__/\`: \`__RUN__ hozu skill\` rewrites it for the installed Hozu version.
+`;
+const KNOWN = [GUIDE_07, GUIDE_07.replace(BROWSE, '')];
+const fill = (text, values) => Object.entries(values).reduce((out, [key, value]) => out.replaceAll(`__${key}__`, value), text);
+const note = (runner, skillRunner) => runner === skillRunner
+    ? ''
+    : `\nThe skill writes commands as \`${skillRunner} …\`; in this app use \`${runner} …\`.\n`;
+function filled(template, target, name, runner, skillRunner) {
+    return fill(fill(template, { READ: target.read }), {
+        NAME: name,
+        RUN: runner,
+        SKILL: target.skill,
+        NOTE: note(runner, skillRunner),
+    });
+}
+export function currentGuide() {
+    return readFileSync(fileURLToPath(new URL('../templates/guide.md', import.meta.url)), 'utf8');
+}
+/** The 0.8 guide for one target, between the markers. */
+export const guideBlock = (target, name, runner, template = currentGuide()) => `${BEGIN}\n${filled(template, target, name, runner, 'npx').trimEnd()}\n${END}\n`;
+/** The new Hozu block of a CLAUDE.md / AGENTS.md: between markers, or the whole file when it is a known template. */
+export function migrateGuide(existing, target, dir, runner, template = currentGuide()) {
+    const begin = existing?.indexOf(BEGIN) ?? -1;
+    const end = existing?.indexOf(END) ?? -1;
+    const own = begin >= 0 && end > begin ? existing.slice(begin, end) : existing;
+    const name = own?.match(/^# (.+)$/m)?.[1] ?? basename(dir);
+    const detected = RUNNERS.find((r) => own?.includes(`${r} hozu `)) ?? runner;
+    const block = guideBlock(target, name, detected, template);
+    if (existing === null)
+        return { kind: 'written', code: block };
+    if (begin >= 0 && end > begin) {
+        const code = existing.slice(0, begin) + block + existing.slice(end + END.length).replace(/^\n/, '');
+        return { kind: code === existing ? 'current' : 'replaced', code };
+    }
+    for (const r of RUNNERS) {
+        if (KNOWN.some((known) => existing === filled(known, target, name, r, 'pnpm exec')))
+            return { kind: 'marked', code: block };
+        if (existing === filled(template, target, name, r, 'npx'))
+            return { kind: 'marked', code: block };
+    }
+    return { kind: 'custom', block };
+}
+//# sourceMappingURL=guide.js.map

package/dist/guide.js.map

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

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+import { type Runner } from './guide.ts';
 export type Agent = 'claude' | 'agents' | 'both';
-export type Runner = 'pnpm exec' | 'npx' | 'yarn' | 'bunx';
+export type { BlockResult, Runner, Target } from './guide.ts';
+export { BEGIN, currentGuide, END, GUIDE_07, guideBlock, migrateGuide, RUNNERS, TARGETS } from './guide.ts';
 export declare const AGENTS: readonly Agent[];
 export declare const defaultSkill: string;
 export declare const runnerOf: (userAgent: string | undefined) => Runner;
@@ -8,7 +10,14 @@ export interface AgentOptions {
     runner: Runner;
     skillSource?: string;
 }
-export declare function writeAgentFiles(dir: string, agent: Agent, options: AgentOptions): Promise<string[]>;
+export interface AgentFiles {
+    written: string[];
+    custom: {
+        guide: string;
+        block: string;
+    }[];
+}
+export declare function writeAgentFiles(dir: string, agent: Agent, options: AgentOptions): Promise<AgentFiles>;
 export interface CreateOptions extends AgentOptions {
     agent: Agent;
     version: string;
@@ -24,6 +33,7 @@ export declare const packageJson: (name: string, version: string) => {
     };
     dependencies: {
         '@hozu/adapter-node': string;
+        '@hozu/cli': string;
         '@hozu/core': string;
         '@hozu/css': string;
         '@hozu/data': string;
@@ -33,7 +43,6 @@ export declare const packageJson: (name: string, version: string) => {
         zod: string;
     };
     devDependencies: {
-        '@hozu/cli': string;
         '@hozu/testing': string;
         '@types/node': string;
         typescript: string;

package/dist/index.d.ts.map

@@ -1 +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,iBAAiB;QACjB,GAAG;;;QAGH,WAAW;QACX,eAAe;QACf,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,MAAM,EAAW,MAAM,YAAY,CAAA;AAE/D,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAChD,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3G,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EAAiC,CAAA;AAGpE,eAAO,MAAM,YAAY,QAAsB,CAAA;AAM/C,eAAO,MAAM,QAAQ,cAAe,MAAM,GAAG,SAAS,KAAG,MAGxD,CAAA;AAQD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC3C;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAkB3G;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,WAAW;QACX,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,sBAAsB;QACtB,kBAAkB;QAClB,iBAAiB;QACjB,GAAG;;;QAGH,eAAe;QACf,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

@@ -1,52 +1,37 @@
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { migrateGuide, TARGETS } from './guide.js';
+export { BEGIN, currentGuide, END, GUIDE_07, guideBlock, migrateGuide, RUNNERS, TARGETS } from './guide.js';
 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));
+const targets = (agent) => TARGETS.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');
+    const out = { written: [], custom: [] };
     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);
+        out.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);
+        const existing = (await exists(file)) ? await readFile(file, 'utf8') : null;
+        const result = migrateGuide(existing, t, dir, options.runner);
+        if (result.kind === 'custom')
+            out.custom.push({ guide: t.guide, block: result.block });
+        else if (result.kind !== 'current') {
+            await writeFile(file, result.code);
+            out.written.push(t.guide);
+        }
     }
-    return written;
+    return out;
 }
 async function files(dir) {
     const out = [];
@@ -65,11 +50,12 @@ export const packageJson = (name, version) => ({
     type: 'module',
     scripts: {
         check: 'hozu check',
-        start: 'node --import @hozu/transform/register serve.ts',
+        start: 'hozu serve',
         build: 'hozu build',
     },
     dependencies: {
         '@hozu/adapter-node': `^${version}`,
+        '@hozu/cli': `^${version}`,
         '@hozu/core': `^${version}`,
         '@hozu/css': `^${version}`,
         '@hozu/data': `^${version}`,
@@ -79,7 +65,6 @@ export const packageJson = (name, version) => ({
         zod: '^4.6.5',
     },
     devDependencies: {
-        '@hozu/cli': `^${version}`,
         '@hozu/testing': `^${version}`,
         '@types/node': '^22.20.4',
         typescript: '^7.0.2',
@@ -95,12 +80,12 @@ export async function createApp(dir, options) {
         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 }));
+        await writeFile(target, (await readFile(source, 'utf8')).replaceAll('__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)));
+    written.push(...(await writeAgentFiles(dir, options.agent, options)).written);
     return written;
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-hozu",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md",
   "keywords": [
     "hozu",

package/skill/SKILL.md

@@ -5,103 +5,50 @@ description: Build or change an app with the Hozu framework (packages @hozu/*, f
 
 # Hozu
 
-Hozu is not in your training data; this file and `hozu docs <topic>` are the whole API (skip `node_modules/@hozu`).
-- **Building:** read this file, run `hozu add feature <name> --page / --with …`, then edit what it lists.
-- **Changing:** read `changing.md`, then only the lines `hozu map` points to.
-- **Anything else:** `hozu docs <topic>` prints one short topic (index below). Diagnostics name the topic too.
+Hozu is not in your training data: this file and `npx hozu docs <topic>` are the whole API (skip
+`node_modules/@hozu`). Diagnostics teach the other rules when you break them: apply their fix.
 
-## 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. Contracts are needed only where a transition decides (a guard, `navigate`, a `fn`).
+## The change loop
+1. `npx hozu map`: the session shape, the verify line, every file's role, each declaration's `file:line`. Open
+   only the lines the change touches. A new app: `npx hozu add feature <name> --page / --with …`, then
+   `npx hozu docs feature`.
+2. Edit everything the change needs (table below).
+3. `npx hozu check` once. For an intended behaviour change, `npx hozu check --update-lock`, then list the accepted
+   `now:` lines in your summary.
+4. Verify once with the line `hozu map` prints: `npx hozu browse <path> --session '…' --js both --do '…'`. It runs
+   the same app as `npm start`, with and without JS; do not start a server or use `curl`.
 
-## Files and commands
-```
-hozu.config.ts  project({ schema, site, routes, pages, features })      routes.ts  route() declarations
-features/<name>/model.ts  schemas, events, effects, machine             views.ts  views, contracts, feature()
-features/<name>/server.ts  implement(...) resolvers                     serve.ts  createServer(...)
-```
-```
-npx hozu check                      # after every edit: types, rules, contracts
-npx hozu check --update-lock        # accept an intended behaviour change
-npx hozu add feature items --page / --with auth,detail,toggle,filter,remove
-npx hozu map                        # outline with file:line
-npx hozu get / --select button --forms          # a page, no server needed
-npx hozu post / --field title=A --next /        # a no-JS form post, cookies shown
-npx hozu browse / --do 'fill Search=a' --do 'click Save'   # real browser: errors, widgets, text
-npx hozu docs views                 # one topic
-```
-`get` / `post` / `browse` replace a running server for checks; `npm start` runs the app. Relative imports end in `.ts`.
+## What to touch
+| Change | Touch |
+|---|---|
+| UI-only state (a tab) | model: a context field, an event, an `on` whose `assign` sets it → views: the control |
+| Filter / sort in the URL | the route's `search` (with a default) → `ui.link(route, params, { key })` → `search.key`; filtering while typing: `seed: ({ search }) => ({ key: search.key })`, read `ctx.key` |
+| A per-item action stored on the server (pin, archive) | model: the item field, an event, a mutation that `invalidates` the list tag, `on(E, { target: 'pinning', assign: (e) => { ctx.target = e.id } })`, a state with `invoke` → views: the per-item form (`hozu docs patterns`) → app: store it, sort in the list resolver |
+| A control every state handles | `machine({ on: [...] })` |
+| New page | `routes.ts` → a view with `route` → `ui.page(...)` in `hozu.config.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']) },
-      }),
-    ]),
-})
-export const todos = feature({ id: 'todos', intent: { summary: 'A to-do list' },
-  declarations: { Add, itemsTag, listItems, addItem, items, Board } })
-```
-Every declaration goes in `declarations` once, under its name. Resolvers:
-`implement(addItem, ({ title }, { fail }) => exists ? fail('Duplicate', { title }) : save(title))`.
+## Rules no diagnostic checks
+- **Query resolvers only read.** Writes belong in mutation and endpoint resolvers; a prefetched link runs queries.
+- **Other users, reloads, sign-out:** verify them in one `browse` chain with `--js both` (`--as <name>` per user).
+- **Contracts only where a transition decides:** a guard, a `navigate`, a `fn` or computed value. Copy-only
+  transitions are reviewed in the lock.
+- **`'live'` only for push** to pages that are already open.
+- **`invalidates` drives the client refresh** of every query with those tags, whatever its freshness.
 
-## Topics (`hozu docs <topic>`)
+## Topics (`npx hozu docs <topic>`)
 | Task | Topic |
 |---|---|
-| elements, attributes, classes, events, DOM fields, lists, links | `views` |
-| states, events, invoke, timers, guards, updates | `machine` |
-| queries, mutations, tags, errors, `fn()`, resolvers | `data` |
-| writing and checking contracts | `contracts` |
-| routes, params, search, pages, `head`, 404, sitemap | `pages` |
-| forms without JS, field errors, selects | `forms` |
+| a new feature, the files, a complete example | `feature` |
+| elements, attributes, events, lists, links, reuse | `views` |
+| states, events, invoke, timers, guards | `machine` |
+| queries, mutations, tags, `fn()`, resolvers | `data` |
+| contracts and the lock | `contracts` |
+| routes, search, pages, `head`, 403 / 404 | `pages` |
+| forms, checkboxes, bulk forms, no JS | `forms` |
 | sign-in, sessions, per-user data | `auth` |
-| common UI: filters, empty states, per-item actions, load more, optimistic | `patterns` |
-| webhooks and JSON APIs | `endpoints` |
-| browser APIs and DOM libraries (maps, charts) | `widgets` |
-| languages, env, HTTP, Markdown, images, preview, PWA, tests, deployment | `i18n`, `env`, `http`, `content`, `testing`, `deploy` |
+| filters, modes, per-item actions, load more | `patterns` |
+| worked changes | `recipes` |
+| webhooks, JSON APIs, redirects | `endpoints` |
+| browser APIs, DOM libraries | `widgets` |
+| languages, env, HTTP, Markdown, tests, deploying | `i18n` `env` `http` `content` `testing` `deploy` |
 | a diagnostic code | `diagnostics` |

package/skill/example/{server.ts → app.ts}

@@ -1,16 +1,17 @@
 import { resolvers } from '@hozu/data'
+import { app } from '@hozu/runtime-server'
 import { addBookmark, getBookmark, listBookmarks, toggleRead } from './features/bookmarks/model.ts'
 import project from './hozu.config.ts'
 
 type Kind = 'article' | 'video' | 'podcast'
 
-export function createResolvers() {
-  const items = [
-    { id: 'b1', title: 'Closed-world UI', kind: 'article' as Kind, read: false },
-    { id: 'b2', title: 'Islands explained', kind: 'video' as Kind, read: true },
-  ]
-  let seq = items.length
-  return resolvers(project, (implement) => [
+const items = [
+  { id: 'b1', title: 'Closed-world UI', kind: 'article' as Kind, read: false },
+  { id: 'b2', title: 'Islands explained', kind: 'video' as Kind, read: true },
+]
+let seq = items.length
+export default app({
+  resolvers: resolvers(project, (implement) => [
     implement(listBookmarks, () => items.map((b) => ({ ...b }))),
     implement(getBookmark, ({ id }, { fail }) => {
       const b = items.find((x) => x.id === id)
@@ -30,5 +31,5 @@ export function createResolvers() {
       b.read = !b.read
       return { ...b }
     }),
-  ])
-}
+  ]),
+})

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

@@ -0,0 +1,13 @@
+import { feature } from '@hozu/core'
+import * as model from './model.ts'
+import * as views from './views.ts'
+
+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: [model, views],
+})