create-muten 0.0.1 → 0.0.3

package/README.md

@@ -1,14 +1,123 @@
 # create-muten
 
-Scaffold a new [Muten](https://www.npmjs.com/package/muten) app.
+The official scaffolder for **[Muten](https://www.npmjs.com/package/@muten/core)** — an AI-first
+frontend framework. One command bootstraps a complete, ready-to-run Muten app, so you never copy
+boilerplate by hand.
 
 ```sh
-npm create muten@latest      # or: npx create-muten
+npm create muten@latest
 ```
 
-It prompts for the **project name**, the **stylesheet** (CSS/SCSS) and the **package manager**
-(default = the one you invoked it with), then scaffolds and — unless you decline — runs
-`<pm> install` + `<pm> run dev`. CI flags: `--css|--scss`, `--pm <npm|pnpm|yarn|bun>`, `--no-install`.
+## Why this exists
 
-The engine (`@muten/core`) is a separate package the app installs as a dependency — the same split as
-`create-vue` ↔ `vue`. It's a Node CLI (not a shell script), so it behaves the same on Windows and macOS.
+Muten ships as **two** packages — the same split as `vue` ↔ `create-vue`:
+
+- **[`@muten/core`](https://www.npmjs.com/package/@muten/core)** — the engine (compiler + runtime +
+  Vite plugin). Your app installs it as a normal dependency and it stays up to date on its own.
+- **`create-muten`** (this package) — a tiny, **zero-dependency** CLI whose only job is to generate a
+  new project already wired to the engine: `index.html`, the Vite config, a `theme.muten`, a first
+  page and the right `package.json`.
+
+You run `create-muten` **once** to scaffold; after that you just work inside your project.
+
+## Quick start
+
+Every package manager has a `create` shortcut. `create-muten` detects which one you used and makes it
+the default for the rest of the prompts:
+
+```sh
+npm  create muten@latest        # npm
+pnpm create muten               # pnpm
+yarn create muten               # yarn
+bun  create muten               # bun
+```
+
+Prefer no install step? Run it on demand with **npx**, optionally naming the folder:
+
+```sh
+npx create-muten my-app
+```
+
+Or install it **globally** and reuse the command anywhere:
+
+```sh
+npm i -g create-muten
+create-muten my-app
+```
+
+Then start the app:
+
+```sh
+cd my-app
+npm install        # only if you skipped the auto-install
+npm run dev
+```
+
+## What it asks
+
+In an interactive terminal it prompts for a few things (defaults in parentheses):
+
+| Prompt | Options | Default |
+|---|---|---|
+| **Project name** | any valid folder name | `muten-app` |
+| **Stylesheet** | `css` / `scss` | `css` |
+| **Package manager** | `npm` / `pnpm` / `yarn` / `bun` | the one that launched it |
+| **Install deps and start dev now?** | `Y` / `n` | `Y` |
+
+If you accept the last prompt it runs `<pm> install` followed by `<pm> run dev` — your app is live in a
+single step. Choosing SCSS also adds `sass` and switches the stylesheet to `.scss` automatically.
+
+## Non-interactive (CI / scripts)
+
+Pass the answers as arguments and it skips every prompt (this is also what runs when there is no TTY,
+e.g. in CI):
+
+```sh
+create-muten my-app --scss --pm pnpm      # full control
+create-muten my-app --css --no-install    # just scaffold, decide later
+```
+
+| Flag | Effect |
+|---|---|
+| `<name>` | the project folder (positional argument) |
+| `--css` / `--scss` | pick the stylesheet (default: `css`) |
+| `--pm <npm\|pnpm\|yarn\|bun>` | package manager to use (default: detected) |
+| `--no-install` | scaffold only — don't install or start the dev server |
+| `--help` | print usage and exit |
+| `--version` | print the version and exit |
+
+## What you get
+
+A minimal, conventional Muten app:
+
+```
+my-app/
+├─ index.html              # entry — loads /src/app.muten through the Vite plugin
+├─ vite.config.mjs         # the @muten/core Vite plugin (dev server, HMR, routing)
+├─ theme.muten             # your design tokens: spacing, fonts, weights, breakpoints
+├─ package.json            # depends on @muten/core + vite
+└─ src/
+   ├─ app.muten            # the ROOT: routes (+ an optional persistent shell)
+   ├─ styles.css           # your look (.scss if you chose SCSS)
+   └─ pages/
+      └─ home/home.muten   # a page — the folder name is its route
+```
+
+There is **no hand-written `main.js`**: the Vite plugin compiles `src/app.muten` into the app's entry,
+so the whole app is `.muten` from the first line.
+
+## Requirements
+
+- **Node.js 18+**
+- One of: **npm**, **pnpm**, **yarn**, **bun**
+
+## Cross-platform
+
+`create-muten` is a Node CLI (not a shell script), so the **exact same command** works on **Windows,
+macOS and Linux** — npm generates the right launcher on each OS.
+
+## Links
+
+- Engine — [`@muten/core`](https://www.npmjs.com/package/@muten/core)
+- Source — [github.com/karttofer/create-muten](https://github.com/karttofer/create-muten)
+- License — MIT

package/index.js

@@ -1,86 +1,86 @@
 #!/usr/bin/env node
-// create-muten — scaffold a new Muten app. Zero runtime deps (Node built-ins only).
+// create-muten — scaffold a new Muten app, with modern interactive prompts (@clack/prompts).
 //
-//   npm create muten@latest [name]              (when published to npm)
-//   npx github:karttofer/create-muten [name]    (from GitHub, not yet public)
-//   create-muten [name] [--css|--scss] [--pm npm|pnpm|yarn|bun] [--no-install]
+//   npm create muten@latest [name]              (or: npx create-muten)
+//   create-muten [name] [--css|--scss|--tailwind] [--pm npm|pnpm|yarn|bun] [--no-install]
 //
-// Interactive in a TTY (prompts for name, stylesheet, package manager); flags / non-TTY make it
-// scriptable. The package manager defaults to the one that invoked us. Then it scaffolds and,
-// unless --no-install, runs `<pm> install` + `<pm> run dev`.
+// Interactive in a TTY (styled prompts: name, styling, package manager); flags / non-TTY make it
+// scriptable. It scaffolds and — unless declined — runs `<pm> install` + `<pm> run dev`.
 import { cpSync, existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
+import { intro, outro, text, select, confirm, isCancel, cancel, note } from '@clack/prompts';
+import color from 'picocolors';
 
 const SELF = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(SELF, 'template');
 const PKG = JSON.parse(readFileSync(join(SELF, 'package.json'), 'utf8'));
 const PMS = ['npm', 'pnpm', 'yarn', 'bun'];
-
-const BANNER = [
-  '',
-  '                  _',
-  '  _ __ ___  _   _| |_ ___ _ __',
-  " | '_ ` _ \\| | | | __/ _ \\ '_ \\",
-  ' | | | | | | |_| | ||  __/ | | |',
-  ' |_| |_| |_|\\__,_|\\__\\___|_| |_|',
-  '',
-  ' AI-first frontend framework',
-  '',
-].join('\n');
-
-// Which PM launched us? npm/pnpm/yarn/bun all set npm_config_user_agent (e.g. "pnpm/8.6 ...").
-// Detecting it is what create-vue/vite do — the idiomatic default, no guessing.
-const detectPM = () => {
-  const ua = process.env.npm_config_user_agent || '';
-  return PMS.find((p) => ua.startsWith(p + '/')) || 'npm';
+const STYLES = ['css', 'scss', 'tailwind'];
+
+// the starter reset — written by the CLI so the template stays pure .muten (no default styles file).
+const RESET = `/* Your look. Muten ships STRUCTURE + LAYOUT (style() tokens); the LOOK lives here, via class("…"). */
+* { box-sizing: border-box; }
+body { margin: 0; font: 15px/1.55 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; color: #111; }
+h1, h2, h3, h4, h5, h6, p { margin: 0; }
+h1 { font-size: 32px; font-weight: 700; letter-spacing: -.02em; }
+.stack { display: flex; flex-direction: column; }
+img { max-width: 100%; display: block; }
+a { color: inherit; text-decoration: none; }
+`;
+// Tailwind v4: one @import + the @tailwindcss/vite plugin (no config file). Preflight does the reset;
+// .stack is a Muten layout primitive Tailwind doesn't know about, so it stays.
+const TAILWIND_STYLES = `@import "tailwindcss";
+
+/* Muten layout primitive Tailwind doesn't define */
+.stack { display: flex; flex-direction: column; }
+`;
+const TAILWIND_VITE = `import muten from '@muten/core/vite-plugin-muten.js';
+import tailwindcss from '@tailwindcss/vite';
+
+export default {
+  plugins: [muten(), tailwindcss()],
 };
-
-// Safe folder name: starts alphanumeric, then [A-Za-z0-9._-]. Blocks path traversal / odd input.
+`;
+const TAILWIND_NOTE = `
+## Styling: Tailwind CSS v4 (installed)
+This app has Tailwind. Write the LOOK with \`class("…")\` using Tailwind utilities, e.g.
+\`class("flex gap-4 rounded-lg bg-zinc-900 text-white")\`. \`style()\` still owns Muten's layout/
+typography tokens — don't put Tailwind classes in \`style()\`, and don't put layout in \`class()\`.
+`;
+
+// Which PM launched us? npm/pnpm/yarn/bun set npm_config_user_agent — the idiomatic default.
+const detectPM = () => { const ua = process.env.npm_config_user_agent || ''; return PMS.find((p) => ua.startsWith(p + '/')) || 'npm'; };
 const validName = (n) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n);
-const die = (msg) => { console.error(msg); process.exit(1); };
+const keep = (v) => { if (isCancel(v)) { cancel('Cancelled.'); process.exit(0); } return v; };
 
 async function main() {
-  // args: one positional name + optional flags (so the CLI is also scriptable / CI-friendly)
   const argv = process.argv.slice(2);
   const has = (f) => argv.includes(f);
   const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
   if (has('-v') || has('--version')) { console.log(PKG.version); return; }
-  console.log(BANNER);
-  if (has('-h') || has('--help')) { console.log('  Usage: create-muten [name] [--css|--scss] [--pm npm|pnpm|yarn|bun] [--no-install]\n'); return; }
+  if (has('-h') || has('--help')) { console.log('Usage: create-muten [name] [--css|--scss|--tailwind] [--pm npm|pnpm|yarn|bun] [--no-install]'); return; }
 
   let name = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--pm')[0];
-  let style = has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;
+  let style = has('--tailwind') ? 'tailwind' : has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;
   let pm = val('--pm');
   let install = has('--no-install') ? false : undefined;
-
-  if (name && !validName(name)) die(`Invalid name: "${name}" (letters, digits, . _ -)`);
-  if (pm && !PMS.includes(pm)) die(`Unknown package manager: "${pm}" (${PMS.join(', ')})`);
-
+  if (name && !validName(name)) { console.error(`Invalid name: "${name}" (letters, digits, . _ -)`); process.exit(1); }
+  if (pm && !PMS.includes(pm)) { console.error(`Unknown package manager: "${pm}" (${PMS.join(', ')})`); process.exit(1); }
   const dpm = detectPM();
 
-  // Prompt only with a real TTY — piped/CI input drops lines through readline, so there we use
-  // flags + defaults instead of hanging on a prompt.
+  // Styled prompts only with a real TTY (piped/CI input would hang); otherwise use flags + defaults.
   if (process.stdin.isTTY) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const ask = async (q, def) => (await rl.question(q)).trim() || def;
-    const pick = async (q, opts, def) => {
-      for (;;) {
-        const v = (await ask(q, def)).toLowerCase();
-        if (opts.includes(v)) return v;
-        console.log(`  Choose: ${opts.join(', ')}.`);
-      }
-    };
-    while (!name) {
-      const a = await ask('Project name: (muten-app) ', 'muten-app');
-      if (validName(a)) name = a; else console.log('  Letters, digits, . _ - (start alphanumeric).');
-    }
-    if (!style) style = await pick('Stylesheet? [css/scss] (css) ', ['css', 'scss'], 'css');
-    if (!pm) pm = await pick(`Package manager? [${PMS.join('/')}] (${dpm}) `, PMS, dpm);
-    if (install === undefined) install = (await ask('Install deps and start the dev server now? [Y/n] ', 'y')).toLowerCase() !== 'n';
-    rl.close();
+    intro(color.bgCyan(color.black(' create-muten ')) + color.dim('  the AI-first frontend framework'));
+    if (!name) name = keep(await text({ message: 'Project name', placeholder: 'muten-app', defaultValue: 'muten-app', validate: (v) => (v && !validName(v)) ? 'Use letters, digits, . _ - (start alphanumeric).' : undefined }));
+    if (!style) style = keep(await select({ message: 'Styling', options: [
+      { value: 'css', label: 'Plain CSS', hint: 'zero deps' },
+      { value: 'scss', label: 'SCSS', hint: 'adds sass' },
+      { value: 'tailwind', label: 'Tailwind CSS', hint: 'utility classes via class("…") — fastest to style' },
+    ] }));
+    if (!pm) pm = keep(await select({ message: 'Package manager', initialValue: dpm, options: PMS.map((p) => ({ value: p, label: p })) }));
+    if (install === undefined) install = keep(await confirm({ message: 'Install dependencies and start the dev server now?' }));
   }
   name = name || 'muten-app';
   style = style || 'css';
@@ -88,24 +88,37 @@ async function main() {
   if (install === undefined) install = false;
 
   const target = resolve(name);
-  if (existsSync(target)) die(`"${name}" already exists.`);
+  if (existsSync(target)) { (process.stdin.isTTY ? cancel : console.error)(`"${name}" already exists.`); process.exit(1); }
 
-  // scaffold from ./template
+  // scaffold from ./template (pure .muten) + apply the styling choice
   cpSync(TEMPLATE, target, { recursive: true });
-  const ignore = join(target, '_gitignore');                        // npm strips a real .gitignore on publish
+  const ignore = join(target, '_gitignore');
   if (existsSync(ignore)) renameSync(ignore, join(target, '.gitignore'));
-  if (style === 'scss') renameSync(join(target, 'src', 'styles.css'), join(target, 'src', 'styles.scss')); // plugin auto-detects
 
   const pkgPath = join(target, 'package.json');
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   pkg.name = name;
-  if (style === 'scss') pkg.devDependencies = { ...(pkg.devDependencies || {}), sass: '^1.101.0' };
+  const addDev = (deps) => { pkg.devDependencies = { ...(pkg.devDependencies || {}), ...deps }; };
+
+  if (style === 'tailwind') {
+    writeFileSync(join(target, 'src', 'styles.css'), TAILWIND_STYLES);
+    writeFileSync(join(target, 'vite.config.mjs'), TAILWIND_VITE);
+    addDev({ tailwindcss: '^4.0.0', '@tailwindcss/vite': '^4.0.0' });
+    const agents = join(target, '.claude', 'AGENTS.md');                 // tell the AI Tailwind is available
+    if (existsSync(agents)) writeFileSync(agents, readFileSync(agents, 'utf8') + TAILWIND_NOTE);
+  } else {
+    writeFileSync(join(target, 'src', style === 'scss' ? 'styles.scss' : 'styles.css'), RESET);
+    if (style === 'scss') addDev({ sass: '^1.101.0' });
+  }
   writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 
-  console.log(`\n  Created ${name}  (${style}, ${pm})\n`);
-
-  if (!install) { console.log(`  cd ${name}\n  ${pm} install\n  ${pm} run dev\n`); return; }
+  if (!install) {
+    if (process.stdin.isTTY) { note(`cd ${name}\n${pm} install\n${pm} run dev`, 'Next steps'); outro(color.green(`Created ${name}  (${style})`)); }
+    else console.log(`\n  Created ${name} (${style}, ${pm})\n  cd ${name} && ${pm} install && ${pm} run dev\n`);
+    return;
+  }
 
+  if (process.stdin.isTTY) outro(color.green(`Created ${name} (${style}) — installing with ${pm}…`));
   // PMs are .cmd shims on Windows → spawn needs shell:true to find them.
   const run = (a) => spawnSync(pm, a, { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' });
   if (run(['install']).status === 0) run(['run', 'dev']);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-muten",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Scaffold a new Muten app.",
   "repository": {
     "type": "git",
@@ -14,6 +14,10 @@
   "bin": {
     "create-muten": "index.js"
   },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1"
+  },
   "keywords": ["muten", "create-muten", "scaffold", "starter", "cli", "frontend"],
   "files": ["index.js", "template"]
 }

package/template/.claude/AGENTS.md

@@ -0,0 +1,59 @@
+# Working in a Muten app — guide for AI agents
+
+This project uses **Muten**, an AI-first frontend framework. The UI is written in **`.muten` files**
+(a small declarative DSL) — **not** React, JSX, Vue, Svelte or hand-written HTML/JS. No model is
+trained on Muten yet, so **follow this guide instead of guessing**: never import React/Vue, never write
+`.jsx`/`.vue`, never add a JS bootstrap.
+
+> Full language reference (every primitive, prop, token, pattern): the **`muten` skill** at
+> [`skills/muten/SKILL.md`](skills/muten/SKILL.md).
+
+## Golden rules
+- UI → `.muten` files. App-global state → `.store` files. Both compile via the `@muten/core` Vite plugin.
+- **No `main.js`.** `src/app.muten` IS the entry (loaded by `index.html`). Never add a JS entry/bootstrap.
+- Primitives are **PascalCase** (`Stack`, `Text`, `Button`); control flow is lowercase (`when`, `each`).
+- **`style(...)`** = layout/typography tokens (Muten builds STRUCTURE). **`class("...")`** = your look
+  (your CSS / Tailwind). Muten ships no skin — appearance is yours.
+- State references use `@name`; interpolate in any string with `{expr}`: `Text "Hi, {user.name}"`.
+
+## File map
+```
+src/
+  app.muten                    ROOT — routes { /url -> page }  (+ optional shell { … slot … })
+  pages/<route>/<route>.muten  a page; the folder name IS the route
+  parts/<name>.muten           reusable component (composition, inlined at build)
+  components/<Name>.js          escape hatch (host JS) used via the `Custom` primitive
+theme.muten                    design tokens: space, font, weight, breakpoints
+src/styles.css                 your look (.scss if you picked SCSS)
+```
+
+## A page looks like this
+```
+screen home
+
+Page style(padding.lg, gap.md) {
+  Title "Hello"
+  Text "Body copy with reactive state: {user.name}"
+  Button "Save" -> save
+}
+```
+
+## Cheat-sheet
+- **Layout:** `Stack` (vertical), `Page` (`<main>`), `Header`/`Nav`/`Sidebar`/`Footer` (landmarks). Horizontal = `style(row)`.
+- **Content:** `Text`, `Title "x" h2`, `Span`, `Image "{src}" alt "…"` (alt required), `Link "x" -> /route`, `Button "x" -> action(arg)`.
+- **Data:** `DataTable @list columns(a, b)`, `Form bind @draft submit create`, `SearchField bind @q`.
+- **Control:** `when <expr> { … }`, `each <list> as item { … }`.
+- **State:** `state { q = "" : text  users = query listUsers : list<User> }` — query states expose `.loading/.error/.data`.
+- **Actions:** `action add mutates users <- item { users.push(item) }` — ops: `push/set/reset/remove`; branch with `if/else`.
+- **Tokens:** `gap.md padding.lg cols.3 text.lg row center between` — responsive prefix: `md:cols.2`.
+
+## Dependencies & limits
+- **CSS / Tailwind / SCSS: YES** — it's a Vite app; install them and use `class("…")` + your CSS.
+- **React / Vue / Svelte UI libraries: NO** — the UI is `.muten` (vanilla DOM, no JS framework runtime).
+  Need a JS widget? Wrap it in a `Custom` host component (`src/components/<Name>.js`).
+- Routing is **hash-based with static paths** (no `:id` params yet). Shell has no local state → use a
+  `.store`. No `toggle` op → `set(not x)`. `style()` is layout tokens only; visuals go in `class()`.
+- The full reference (stores, routing, theme, every primitive) is in [`skills/muten/SKILL.md`](skills/muten/SKILL.md).
+
+## Commands
+`npm run dev` (dev server + HMR) · `npm run build` (production) · `npm run lint` (validate `.muten`).

package/template/.claude/skills/muten/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: muten
+description: Read and write Muten — the AI-first frontend DSL this app is built in (.muten and .store files), NOT React/Vue/HTML. Use whenever creating or editing any .muten or .store file, app.muten routes, theme.muten, parts, components, stores, or deciding what can be installed. No model is trained on Muten, so consult this before writing any Muten code or adding a dependency. Assume the human will NOT read the code — you do everything.
+---
+
+# Muten — complete language reference
+
+Muten compiles `.muten` files to vanilla JS + fine-grained signals (no virtual DOM). The `@muten/core`
+Vite plugin does the compiling. You write a small declarative DSL — **never** React/JSX/Vue/Svelte/HTML.
+A page with no reactivity compiles to plain zero-runtime HTML; a reactive one ships ~1KB of signals.
+
+## Mental model & golden rules
+- **UI** → `.muten` files (pages, parts, the app root, the theme). **App-global state** → `.store` files.
+- **`src/app.muten` is the entry.** `index.html` loads it; the plugin boots it. **Never create `main.js`** or a `<script>` bootstrap.
+- Primitives are **PascalCase** (`Stack`, `Text`); keywords/control flow are **lowercase** (`when`, `each`, `state`).
+- `style(...)` = layout/typography **tokens** (Muten builds STRUCTURE). `class("...")` = **look** (your CSS / Tailwind). Muten ships no skin.
+- `@name` = a state reference. `{expr}` = interpolation inside any string: `Text "Hi, {user.name}"`.
+- Each page has **one root node**. Reactivity is automatic: reading a state in interpolation / `when` / `each` re-renders just that spot.
+
+## 1. What you CAN install / use
+This is a normal **Vite** project, so the whole Vite/npm ecosystem for **styling, build, and data** works:
+- **Tailwind CSS — YES.** Install it (`tailwindcss`, `postcss`, `autoprefixer`), add the config + the
+  `@tailwind` directives to `src/styles.css`, and use utilities via `class("flex gap-4 rounded")`.
+  `class()` emits raw class names, so any CSS framework (Tailwind, UnoCSS, Bootstrap CSS, your own CSS) works.
+- **Sass/SCSS** — supported out of the box if you scaffolded with SCSS (or add `sass`); use `src/styles.scss`.
+- **Any Vite plugin / PostCSS plugin** — add it to `vite.config.mjs` alongside `muten()`.
+- **Data / utility npm packages** — usable inside `.store` logic and inside `Custom` host components
+  (date libs, fetch wrappers, zod, etc.).
+- **Host UI via the `Custom` primitive** — write vanilla JS in `src/components/<Name>.js` (charts,
+  maps, a third-party widget) and mount it with `Custom`. See §Custom.
+
+## 2. What you CANNOT do
+- **No React / Vue / Svelte component libraries as UI.** There is no React/Vue runtime — the UI is
+  `.muten` compiled to vanilla DOM. You cannot drop in MUI, Chakra, Ant, shadcn, a React table, etc.
+  If you truly need a JS widget, wrap it yourself in a `Custom` component (vanilla JS).
+- **No JSX / `.jsx` / `.vue` / hand-written DOM in pages.** No `className`, no hooks, no lifecycle.
+- **No arbitrary inline CSS via `style()`** — `style()` only takes the layout/typography tokens below.
+  Visual styling (colors, borders, shadows) goes through `class("…")` + your CSS.
+
+## 3. Limitations (current)
+- **Routing is hash-based** (`#/path`) and **paths are static** — there are **no route params** yet
+  (no `/product/:id`). Model per-item views with state + `when`, or a query param read in host JS.
+- **Shell has no local state** — put shell/cross-page state in a `.store` (see the mobile-menu pattern).
+- **No `toggle` op** — flip a bool with `set(not x)`.
+- **Forms**: `Form` (auto-generated from an entity) and `SearchField` (single text input) are the
+  built-ins; richer custom inputs need a `Custom` component for now.
+- **Pages are single-root** (one top node per page).
+
+## 4. Files
+```
+src/app.muten                    routes (+ optional shell) — the ROOT; read it first
+src/pages/<route>/<route>.muten  one page; the folder name IS the route
+src/parts/<name>.muten           reusable component (inlined at build time)
+src/components/<Name>.js          host-JS escape hatch, mounted via Custom
+src/<domain>.store               app-global state slice (domain = file name)
+theme.muten                      token scale (space/font/weight/leading/breakpoints)
+src/styles.css                   reset + look (or styles.scss)
+index.html / vite.config.mjs     wired to @muten/core; don't hand-edit the boot
+```
+
+## 5. Declarations
+```
+screen <name>                    # page identity (first line of a page)
+
+entity User {                    # data shape + validation (implicit `id uuid`)
+  name  text  required           # constraints: required | min:N | max:N
+  email email required
+  role  admin | member           # `a | b | c` = enum
+}
+
+state {                          # page-LOCAL reactive state
+  q     = ""              : text
+  users = query listUsers : list<User>   # query → async; exposes @users.loading/.error/.data
+}
+
+const TAX = 0.21                 # compile-time immutable scalar (inlined, never reactive)
+
+action add mutates users <- item {   # mutation; `mutates` lists what it may change (enforced)
+  users.push(item)               # ops: push | set | reset | remove
+  if item.vip { rating.set(5) } else { rating.set(1) }   # if/else = the only branching in actions
+}
+
+mock    { listUsers: [ { name: "Ana", role: admin } ] }          # mock data for a query
+sources { listUsers: { url: "https://api…", at: "results" } }    # real data source for a query
+```
+
+## 6. Primitives
+A bare string is the node's main prop. `{ }` = children. Lay out with `style()`, skin with `class()`.
+
+| Primitive | Use | Example |
+|---|---|---|
+| `Stack` | vertical stack (flex column) | `Stack style(gap.md) { … }` |
+| `Page` | page root `<main>` (one per route) | `Page style(padding.lg) { … }` |
+| `Header`/`Nav`/`Sidebar`/`Footer` | landmarks | `Header style(row, between, center) { … }` |
+| `Text` | paragraph, interpolates | `Text "Hi, {user.name}"` |
+| `Title` | heading; level keyword | `Title "Dashboard" h2` |
+| `Span` | inline text | `Span "{cart.total}"` |
+| `Image` | `<img>`, **alt required** | `Image "{p.image}" alt "{p.title}"` |
+| `Link` | client-side nav | `Link "Catalog" -> /catalog` |
+| `Button` | runs an action | `Button "Save" -> save(draft)` |
+| `SearchField` | text input bound to state | `SearchField bind @q "Search…"` |
+| `Form` | auto-form from an entity draft | `Form bind @draft submit create "Save"` |
+| `DataTable` | reactive table over a list/query | `DataTable @users columns(name, email)` |
+| `RowAction` | a button inside each table row | `RowAction "Delete" -> remove(row.id)` |
+| `slot` | outlet inside `shell` | `slot` |
+| `Custom` | host-JS escape hatch | `Custom Chart inputs(data: @sales) on(pick: select)` |
+
+Horizontal layout = a region with `style(row)` (there is no `Row` primitive). Clickable card =
+`Button { … }` or `Link "" -> /x { … }` with children instead of a label.
+
+Modifiers (after a primitive): `style(tokens)` · `class("css")` · `bind @state` · `submit action` ·
+`where(clauses)` · `columns(a, b)` · `alt "…"` · `inputs(k: v)` · `on(event: action)`.
+
+## 7. Theme — how it works
+`theme.muten` supplies the **scale** (values); the engine owns only the **vocabulary** (token names).
+```
+theme {
+  space       { xs "4px"  sm "8px"  md "16px"  lg "24px"  xl "32px" }
+  font        { sm "13px"  md "15px"  lg "20px"  xl "28px" }
+  weight      { medium "500"  bold "700" }
+  leading     { tight "1.2"  normal "1.5" }
+  breakpoints { sm "640px"  md "768px"  lg "1024px" }
+}
+```
+A token like `gap.md` resolves to `gap: 16px` via `space.md`; `text.lg` → `font.lg`; `md:cols.2` uses
+`breakpoints.md`. **No CSS/reset goes in `theme.muten`** — the reset and the look live in `src/styles.css`.
+
+### Style tokens (`style(...)`)
+```
+row column wrap grid grow center between
+gap.sm|md|lg   padding.md|lg   padding.x.md   padding.y.md   margin.md
+cols.2|3|auto  rows.2
+text.sm|md|lg|xl   weight.medium|bold   leading.normal   italic   bold
+align.left|center|right   justify.center|between   items.center|start
+width.full   height.full
+```
+Responsive: prefix any token with a breakpoint → `md:cols.2`, `lg:cols.4` (`sm/md/lg/xl`).
+
+## 8. State, actions & reactivity
+- `state` cells are signals; reading them in interpolation / `when` / `each` auto-updates that spot.
+- `query` state is async → render with `when @x.loading { … }`, then use `@x.data`.
+- Mutate **only** through `action`s, and only the state in `mutates` (the linter enforces it):
+  - `list.push(x)` (append; auto-fills uuid fields) · `s.set(v)` · `s.reset()` · `list.remove(x => x.id == id)`
+  - There is no `toggle`: `flag.set(not flag)`.
+- Control flow in the tree: `when <expr> { … }` (mount/unmount), `each <list> as item { … }` (item is a scope var).
+- Expressions: `== != < > <= >=`, `and or not`, `contains` (case-insensitive substring / list membership),
+  `+ - * /`, ternary `c ? a : b`, parentheses, refs (`user.name`, `cart.total`, `$item.x`).
+
+## 9. Stores — app-global state
+A `.store` file = state shared across pages, **no prop drilling**. The file name is the domain.
+```
+# src/ui.store   → referenced everywhere as ui.<member>
+state  { menuOpen = false : bool }
+get    isOpen = menuOpen                 # derived/memoized value (read as ui.isOpen)
+action toggleMenu mutates menuOpen <- x { menuOpen.set(not menuOpen) }
+effect { /* runs whenever the store state it reads changes */ }
+```
+Use it from any page/shell by name: `when ui.menuOpen { … }`, `Button "☰" -> ui.toggleMenu`. The Vite
+plugin auto-detects every `.store` file. `get` = memoized; `effect` = reactive side-effect (Angular-style).
+
+## 10. Routing — how it works
+`src/app.muten` maps URLs to pages. It's a **hash router** (URLs look like `#/about`); the **first
+route is the default**. The folder under `src/pages/` must match the page name.
+```
+routes {
+  /         -> home               # src/pages/home/home.muten
+  /about    -> about              # static page → compiles to zero-runtime HTML
+  /cart     -> cart guard auth.loggedIn else /login    # guard: a store boolean; redirect if false
+  /login    -> login guard not auth.loggedIn else /     # guest-only page
+}
+```
+Guards read a **store boolean**; when it flips (login/logout) the active route re-renders automatically.
+Navigate with `Link "x" -> /path` (client-side, no reload). **No path params** (`:id`) yet.
+
+### Shell (persistent chrome)
+Wrap routes in a `shell { … slot … }` for a nav/footer around every page. `slot` is where the active
+page mounts. The shell has **no local state** → use a store for things like a mobile menu:
+```
+shell {
+  Header style(row, between, center) class("nav") {
+    Link "Home" -> /
+    Button "☰" -> ui.toggleMenu class("burger")
+  }
+  when ui.menuOpen { Stack class("mobile-menu") { Link "About" -> /about } }
+  slot
+  Footer { Span "© 2026" }
+}
+routes { / -> home }
+```
+
+## 11. Entities, forms & validation
+`entity` defines a shape + constraints. `Form bind @draft submit create` auto-renders one input per
+field and validates on submit (per-field `.field-error`), blocking the action if invalid.
+```
+entity Task { title text required  notes text  done bool }
+state  { draft = {} : Task  tasks = [] : list<Task> }
+action create mutates tasks, draft <- t { tasks.push(draft)  draft.reset() }
+# in the page:  Form bind @draft submit create "Add task"
+```
+
+## 12. Parts — reusable composition
+`part` = a reusable fragment, **inlined at build** (not a runtime component). Pass OBJECTS (`$x.field`)
+and ACTION callbacks (`-> $onPick(...)`).
+```
+# src/parts/feature.muten
+part Feature(item: Feature, onPick: action) {
+  Stack style(column, gap.sm) class("card") {
+    Title "{$item.title}" h3
+    Text  "{$item.body}"
+    Button "Choose" -> $onPick($item.id)
+  }
+}
+# use it:  Feature(item: f, onPick: select)
+```
+
+## 13. Custom — the host-JS escape hatch
+For anything Muten can't express (a chart, a 3rd-party widget), write vanilla JS in
+`src/components/<Name>.js` and mount it with `Custom`. It receives `inputs` (values/state) and wires
+DOM events to your actions via `on`. This is the ONLY way to use non-Muten UI code.
+```
+Custom Chart inputs(data: @sales) on(pointSelect: select)
+# → src/components/Chart.js exports a mount(el, { inputs, on }) that builds vanilla DOM.
+```
+
+## 14. Gotchas
+- It's NOT React: PascalCase primitives + `{ }` children; no JSX/hooks/`className`.
+- No `main.js`/`<script>` — `app.muten` is the entry.
+- `style()` (layout tokens) ≠ `class()` (look). No colors/borders in `style()`.
+- `Image` without `alt` fails validation (`alt ""` for decorative).
+- Actions may only touch their declared `mutates`.
+- Want a library? If it's CSS → `class()`. If it's a JS widget → `Custom`. If it's React/Vue UI → not possible.
+
+## 15. Minimal full app
+```
+# src/app.muten
+routes { / -> home }
+
+# src/pages/home/home.muten
+screen home
+state  { name = "" : text }
+action greet mutates name <- v { name.set(v) }
+
+Page style(padding.lg, gap.md) {
+  Title "Hello"
+  SearchField bind @name "Your name"
+  when name { Text "Hi, {name}!" }
+}
+```
+Validate anytime: `npm run lint`.

package/template/package.json

@@ -8,7 +8,7 @@
     "lint": "muten lint"
   },
   "dependencies": {
-    "@muten/core": "^0.0.1",
+    "@muten/core": "^0.0.3",
     "vite": "^8.0.16"
   }
 }

package/template/theme.muten

@@ -4,5 +4,6 @@ theme {
   space       { xs "4px"  sm "8px"  md "16px"  lg "24px"  xl "32px" }
   font        { sm "13px"  md "15px"  lg "20px"  xl "28px" }
   weight      { medium "500"  bold "700" }
+  leading     { tight "1.2"  normal "1.5"  loose "1.8" }
   breakpoints { sm "640px"  md "768px"  lg "1024px" }
 }

package/template/src/styles.css

@@ -1,9 +0,0 @@
-/* Your look. Muten ships STRUCTURE (semantic tags) + LAYOUT (style tokens); the LOOK lives here,
-   referenced from .muten via class("…"). This base reset is all a fresh app needs to start. */
-* { box-sizing: border-box; }
-body { margin: 0; font: 15px/1.55 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; color: #111; }
-h1, h2, h3, h4, h5, h6, p { margin: 0; }
-h1 { font-size: 32px; font-weight: 700; letter-spacing: -.02em; }
-.stack { display: flex; flex-direction: column; } /* the class Stack and column layouts emit */
-img { max-width: 100%; display: block; }
-a { color: inherit; text-decoration: none; }