create-muten 0.0.3 → 0.0.4

package/README.md

@@ -60,10 +60,29 @@ In an interactive terminal it prompts for a few things (defaults in parentheses)
 | Prompt | Options | Default |
 |---|---|---|
 | **Project name** | any valid folder name | `muten-app` |
+| **Template** | `basic` / `routing` / `full` | `basic` |
 | **Stylesheet** | `css` / `scss` | `css` |
+| **Add Tailwind CSS?** | `Y` / `n` (CSS only) | `n` |
+| **Add DaisyUI?** | `Y` / `n` (needs Tailwind) | `n` |
 | **Package manager** | `npm` / `pnpm` / `yarn` / `bun` | the one that launched it |
 | **Install deps and start dev now?** | `Y` / `n` | `Y` |
 
+Tailwind is an optional add-on **on top of** CSS (the look layer; you still style via `class("…")`) — it
+wires `@tailwindcss/vite` + an `@import "tailwindcss"` and notes the setup in the app's `.claude/` guide.
+
+## Templates
+
+| Template | What you get |
+|---|---|
+| **basic** | one page — the minimal starter |
+| **routing** | a persistent shell (navbar + footer) + multiple real-path routes + a static `about` page |
+| **full** | routing + a `.store` + an `api` block + a source-backed products page + Tailwind — a real data app |
+
+When **Tailwind or DaisyUI** is selected, `theme.muten` is centralized to **match Tailwind's scale** (so
+`style()` tokens and Tailwind utilities share one scale, e.g. `style(gap.md)` == `gap-4`); plain CSS/SCSS
+keeps the default scale. **DaisyUI** adds component classes (`btn`, `card`, `modal`) usable in `class("…")` —
+the closest fit to shadcn that works in Muten (pure classes, no React; behavior is Muten state + `on()`).
+
 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.
 
@@ -80,7 +99,10 @@ create-muten my-app --css --no-install    # just scaffold, decide later
 | Flag | Effect |
 |---|---|
 | `<name>` | the project folder (positional argument) |
+| `--template <basic\|routing\|full>` | which starter (default: `basic`; `full` implies Tailwind) |
 | `--css` / `--scss` | pick the stylesheet (default: `css`) |
+| `--tailwind` | add Tailwind CSS v4 on top of CSS (forces `--css`) |
+| `--daisyui` | add DaisyUI component classes (implies `--tailwind`) |
 | `--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 |

package/index.js

@@ -2,10 +2,10 @@
 // create-muten — scaffold a new Muten app, with modern interactive prompts (@clack/prompts).
 //
 //   npm create muten@latest [name]              (or: npx create-muten)
-//   create-muten [name] [--css|--scss|--tailwind] [--pm npm|pnpm|yarn|bun] [--no-install]
+//   create-muten [name] [--template basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--pm npm|pnpm|yarn|bun] [--no-install]
 //
-// 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`.
+// Stylesheet (CSS or SCSS) is the base; Tailwind is an optional add-on ON TOP of CSS (it's a styling
+// library, not a stylesheet replacement). Interactive in a TTY; flags / non-TTY make it scriptable.
 import { cpSync, existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,9 +15,10 @@ import color from 'picocolors';
 
 const SELF = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(SELF, 'template');
+const OVERLAYS = join(SELF, 'overlays');   // additive layers per template variant (routing, full)
+const TEMPLATES = ['basic', 'routing', 'full'];
 const PKG = JSON.parse(readFileSync(join(SELF, 'package.json'), 'utf8'));
 const PMS = ['npm', 'pnpm', 'yarn', 'bun'];
-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("…"). */
@@ -29,9 +30,9 @@ h1 { font-size: 32px; font-weight: 700; letter-spacing: -.02em; }
 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";
+// CSS + Tailwind v4: one @import + the @tailwindcss/vite plugin. Preflight does the reset, so this stays
+// minimal — only `.stack` (a Muten layout primitive Tailwind doesn't know). You style via class("…").
+const tailwindStyles = (daisyui) => `@import "tailwindcss";${daisyui ? '\n@plugin "daisyui";' : ''}
 
 /* Muten layout primitive Tailwind doesn't define */
 .stack { display: flex; flex-direction: column; }
@@ -43,11 +44,33 @@ export default {
   plugins: [muten(), tailwindcss()],
 };
 `;
+// When Tailwind/DaisyUI is chosen, the Muten token scale is centralized to MATCH Tailwind's defaults, so
+// style() tokens and Tailwind utilities share one scale (e.g. style(gap.md) == gap-4 == 1rem). Plain
+// css/scss keeps the default theme.muten. (DaisyUI builds on Tailwind's scale; its colors come via @plugin.)
+const TAILWIND_THEME = `# Token SCALE aligned with Tailwind's defaults — style() tokens + Tailwind utilities share one scale.
+theme {
+  space       { xs "0.25rem"  sm "0.5rem"  md "1rem"  lg "1.5rem"  xl "2rem" }
+  font        { sm "0.875rem"  md "1rem"  lg "1.125rem"  xl "1.25rem" }
+  weight      { medium "500"  semibold "600"  bold "700" }
+  leading     { tight "1.25"  normal "1.5"  loose "2" }
+  breakpoints { sm "640px"  md "768px"  lg "1024px"  xl "1280px" }
+}
+`;
 const TAILWIND_NOTE = `
 ## Styling: Tailwind CSS v4 (installed)
-This app has Tailwind. Write the LOOK with \`class("…")\` using Tailwind utilities, e.g.
+This app has Tailwind ON TOP of CSS. 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()\`.
+You can still add your own rules in \`src/styles.css\` below the \`@import "tailwindcss";\`.
+`;
+// DaisyUI = component CLASSES on top of Tailwind (no React). The "shadcn for Muten": pre-styled components
+// you drop into class("…"); behavior (open/close) you build with Muten state + class(when) + on(…).
+const DAISY_NOTE = `
+## DaisyUI (installed)
+DaisyUI adds **component classes** on top of Tailwind — use them in \`class("…")\`: \`class("btn btn-primary")\`,
+\`class("card bg-base-100 shadow-xl")\`, \`class("badge")\`, \`class("alert")\`. Pure classes, no React.
+\`@plugin "daisyui";\` is already in \`src/styles.css\`. Interactive behavior (toggle a modal/dropdown) you build
+with Muten: \`state\` + \`class(active when isOpen)\` + \`on(click: …)\`.
 `;
 
 // Which PM launched us? npm/pnpm/yarn/bun set npm_config_user_agent — the idiomatic default.
@@ -60,13 +83,17 @@ async function main() {
   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; }
-  if (has('-h') || has('--help')) { console.log('Usage: create-muten [name] [--css|--scss|--tailwind] [--pm npm|pnpm|yarn|bun] [--no-install]'); return; }
+  if (has('-h') || has('--help')) { console.log('Usage: create-muten [name] [--template basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--pm npm|pnpm|yarn|bun] [--no-install]'); return; }
 
-  let name = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--pm')[0];
-  let style = has('--tailwind') ? 'tailwind' : has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;
+  let name = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--pm' && argv[i - 1] !== '--template')[0];
+  let template = val('--template') || (has('--full') ? 'full' : has('--routing') ? 'routing' : has('--basic') ? 'basic' : undefined);
+  let style = has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;     // the base stylesheet
+  let tailwind = has('--tailwind') ? true : undefined;                        // optional add-on (CSS only)
+  let daisyui = has('--daisyui') ? true : undefined;                          // component classes on Tailwind
   let pm = val('--pm');
   let install = has('--no-install') ? false : undefined;
   if (name && !validName(name)) { console.error(`Invalid name: "${name}" (letters, digits, . _ -)`); process.exit(1); }
+  if (template && !TEMPLATES.includes(template)) { console.error(`Unknown template: "${template}" (${TEMPLATES.join(', ')})`); process.exit(1); }
   if (pm && !PMS.includes(pm)) { console.error(`Unknown package manager: "${pm}" (${PMS.join(', ')})`); process.exit(1); }
   const dpm = detectPM();
 
@@ -74,24 +101,37 @@ async function main() {
   if (process.stdin.isTTY) {
     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' },
+    if (!template) template = keep(await select({ message: 'Template', options: [
+      { value: 'basic', label: 'Basic', hint: 'one page' },
+      { value: 'routing', label: 'Routing', hint: 'shell + multiple pages' },
+      { value: 'full', label: 'Routing + store + API + Tailwind', hint: 'a real data app' },
+    ] }));
+    if (template === 'full') tailwind = true;   // the full template implies Tailwind
+    // Tailwind is an add-on on top of CSS (Tailwind v4 is CSS-native; Sass isn't recommended).
+    if (!style && !tailwind) style = keep(await select({ message: 'Stylesheet', options: [
+      { value: 'css', label: 'CSS', hint: 'plain, 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?' }));
+    if (tailwind === undefined) tailwind = style === 'css' ? keep(await confirm({ message: 'Add Tailwind CSS? (utility classes via class("…"))', initialValue: false })) : false;
+    if (tailwind && daisyui === undefined) daisyui = keep(await confirm({ message: 'Add DaisyUI? (component classes: btn, card, modal…)', initialValue: template === 'full' }));
   }
   name = name || 'muten-app';
+  template = template || 'basic';
+  if (template === 'full') tailwind = true;     // full implies Tailwind
+  if (daisyui) tailwind = true;                 // DaisyUI is a Tailwind plugin
   style = style || 'css';
+  if (tailwind === undefined) tailwind = false;
+  if (daisyui === undefined) daisyui = false;
+  if (tailwind) style = 'css';            // Tailwind implies a CSS base (not SCSS)
   pm = pm || dpm;
   if (install === undefined) install = false;
 
   const target = resolve(name);
   if (existsSync(target)) { (process.stdin.isTTY ? cancel : console.error)(`"${name}" already exists.`); process.exit(1); }
 
-  // scaffold from ./template (pure .muten) + apply the styling choice
+  // scaffold from ./template (the basic base) + layer the chosen variant's overlay + the stylesheet/add-ons
   cpSync(TEMPLATE, target, { recursive: true });
+  if (template !== 'basic') cpSync(join(OVERLAYS, template), target, { recursive: true });  // routing / full overlay
   const ignore = join(target, '_gitignore');
   if (existsSync(ignore)) renameSync(ignore, join(target, '.gitignore'));
 
@@ -100,25 +140,28 @@ async function main() {
   pkg.name = name;
   const addDev = (deps) => { pkg.devDependencies = { ...(pkg.devDependencies || {}), ...deps }; };
 
-  if (style === 'tailwind') {
-    writeFileSync(join(target, 'src', 'styles.css'), TAILWIND_STYLES);
+  if (tailwind) {
+    writeFileSync(join(target, 'src', 'styles.css'), tailwindStyles(daisyui));
     writeFileSync(join(target, 'vite.config.mjs'), TAILWIND_VITE);
+    writeFileSync(join(target, 'theme.muten'), TAILWIND_THEME);          // scale centralized to Tailwind's
     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);
+    if (daisyui) addDev({ daisyui: '^5.0.0' });
+    const agents = join(target, '.claude', 'AGENTS.md');                 // tell the AI what styling is available
+    if (existsSync(agents)) writeFileSync(agents, readFileSync(agents, 'utf8') + TAILWIND_NOTE + (daisyui ? DAISY_NOTE : ''));
   } else {
     writeFileSync(join(target, 'src', style === 'scss' ? 'styles.scss' : 'styles.css'), RESET);
-    if (style === 'scss') addDev({ sass: '^1.101.0' });
   }
+  if (style === 'scss') addDev({ sass: '^1.101.0' });
   writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 
+  const desc = `${template}, ${style}${tailwind ? ' + Tailwind' : ''}${daisyui ? ' + DaisyUI' : ''}`;
   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`);
+    if (process.stdin.isTTY) { note(`cd ${name}\n${pm} install\n${pm} run dev`, 'Next steps'); outro(color.green(`Created ${name}  (${desc})`)); }
+    else console.log(`\n  Created ${name} (${desc}, ${pm})\n  cd ${name} && ${pm} install && ${pm} run dev\n`);
     return;
   }
 
-  if (process.stdin.isTTY) outro(color.green(`Created ${name} (${style}) — installing with ${pm}…`));
+  if (process.stdin.isTTY) outro(color.green(`Created ${name} (${desc}) — 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/overlays/full/src/app.muten

@@ -0,0 +1,21 @@
+# The app ROOT. `api` is the backend config (one place: base URL + default headers) — every `sources`
+# inherits it. The shell's navbar reads the cart store (global) and shows a live count.
+api {
+  base: "https://fakestoreapi.com"
+}
+
+shell {
+  Header style(row, between, center) class("p-4 shadow bg-white") {
+    Link "Shop" -> / class("text-xl font-bold")
+    Nav "Main" style(row, gap.md, center) {
+      Link "Products" -> /products
+      Span "🛒 {cart.count}" class("font-medium")
+    }
+  }
+  slot
+}
+
+routes {
+  /         -> home
+  /products -> products
+}

package/overlays/full/src/cart.store

@@ -0,0 +1,9 @@
+# An app-global store (any `*.store` under src/). State is shared across pages + the shell, no imports.
+# `get` is a derived value; `action`s are the only way to mutate.
+store { items = [] : list<text> }
+
+get count = items.length
+
+action add mutates items <- id {
+  items.push(id)
+}

package/overlays/full/src/pages/products/products.muten

@@ -0,0 +1,26 @@
+# A real data page: `query` state backed by a `sources` URL (relative → joined to the app's `api.base`).
+# `muten build` fetches it at build and bakes the rows into the HTML (SSG); the runtime then takes over.
+# Clicking "Add" calls the cart store action — the navbar count updates reactively.
+screen products
+
+meta { title "Products" }
+
+entity Product { title text  price text }
+
+state { products = query products : list<Product> }
+
+sources { products: "/products" }
+
+Page style(padding.lg, gap.md) {
+  Title "Products" class("text-2xl font-bold")
+  when products.loading { Text "Loading…" class("opacity-60") }
+  each products as p {
+    Stack style(gap.sm) class("p-4 rounded-lg shadow bg-white") {
+      Text "{p.title}" class("font-semibold")
+      Stack style(row, between, center) {
+        Span "$ {p.price}" class("text-lg")
+        Button "Add to cart" -> cart.add(p.id) class("px-3 py-1 rounded bg-black text-white")
+      }
+    }
+  }
+}

package/overlays/routing/src/app.muten

@@ -0,0 +1,19 @@
+# The app ROOT. A persistent `shell { … slot … }` wraps every page (navbar here); `slot` is where the
+# active page mounts. `routes` maps a real-path URL to a page (the folder under src/pages/).
+shell {
+  Header style(row, between, center) class("nav") {
+    Link "Home" -> /
+    Nav "Main" {
+      Link "About" -> /about
+    }
+  }
+  slot
+  Footer style(padding.md) {
+    Text "Built with Muten"
+  }
+}
+
+routes {
+  /      -> home
+  /about -> about
+}

package/overlays/routing/src/pages/about/about.muten

@@ -0,0 +1,15 @@
+# A second page. `meta { … }` sets the <head> title/description (og:* auto-derived) — applied on
+# navigation and baked into the static HTML at build. This page has no reactivity, so `muten build`
+# pre-renders it to zero-JS HTML (crawlable).
+screen about
+
+meta {
+  title "About"
+  description "About this Muten app."
+}
+
+Page style(padding.lg, gap.md) {
+  Title "About"
+  Text "Static pages compile to zero-JS HTML at build — crawlable and instant."
+  Link "← Home" -> /
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-muten",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Scaffold a new Muten app.",
   "repository": {
     "type": "git",
@@ -19,5 +19,5 @@
     "picocolors": "^1.0.1"
   },
   "keywords": ["muten", "create-muten", "scaffold", "starter", "cli", "frontend"],
-  "files": ["index.js", "template"]
+  "files": ["index.js", "template", "overlays"]
 }

package/template/.claude/AGENTS.md

@@ -43,7 +43,12 @@ Page style(padding.lg, gap.md) {
 - **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 { … }`.
+- **Interactivity:** reactive class `class(active when isOpen)`; events on any element `on(keydown: act, mouseenter: act)`; a `/404` route catches unmatched paths.
 - **State:** `state { q = "" : text  users = query listUsers : list<User> }` — query states expose `.loading/.error/.data`.
+- **Backend:** `sources { x: { url, method?, headers?, body?, at? } }` feeds a `query`. Shared base+auth go in `api { base, headers }` (app.muten, named clients via `{ api: "shop" }`) — relative source urls join to `base`. GET sources pre-render at build (SSG).
+- **Writes:** a source-backed list gets `create`/`update`/`delete` in an action (`orders.create(draft)` → POST/PUT/DELETE the resource, optimistic + updates the list). The action is async with reactive `name.pending`/`name.error` for UX. Local-only mutations stay `push`/`set`/`reset`/`remove`.
+- **Refetch:** re-run a query with N params (search / paginate / filter): `products.refetch(q: term, page: n)` in an action → builds `?q=&page=` and reloads the list.
+- **Escape hatch:** non-RESTful API? `post`/`put`/`delete` a `"client:/path"` (interpolated) with optional `body` in an action: `post "shop:/orders" body item`. Uses the client's base+headers; `mutates` is optional for pure commands.
 - **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`.
 
@@ -51,7 +56,7 @@ Page style(padding.lg, gap.md) {
 - **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
+- Routing uses **real paths** (`/path`, History API; deploy serves `index.html` for any path); route params work (`/product/:id` → `param id`). SEO: `meta { title "…" description "…" }` per page → `<head>` tags (og auto-derived). 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).
 

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

@@ -13,7 +13,7 @@ A page with no reactivity compiles to plain zero-runtime HTML; a reactive one sh
 - **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.
+- `style(...)` = layout/typography **tokens** (Muten builds STRUCTURE). `class("...")` = **look** (your CSS / Tailwind); toggle reactively with `class(active when isOpen)`. 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.
 
@@ -38,8 +38,10 @@ This is a normal **Vite** project, so the whole Vite/npm ecosystem for **styling
   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.
+- **Routing uses real paths** (`/path`, History API). Route params ARE supported: `/product/:id` → declare `param id`
+  in the page (see §10). `muten build` pre-renders pages to real HTML (SSG) so content is crawlable —
+  static pages ship zero JS; reactive pages get their content (lists, `each`, interpolation from mock data)
+  baked into the HTML, then the runtime boots for interactivity. No special syntax needed.
 - **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
@@ -84,6 +86,88 @@ mock    { listUsers: [ { name: "Ana", role: admin } ] }          # mock data for
 sources { listUsers: { url: "https://api…", at: "results" } }    # real data source for a query
 ```
 
+A `sources` entry is a complete HTTP request — a bare URL, or `{ url, method?, headers?, body?, at? }`:
+```
+sources {
+  products: "https://api.shop.com/products"                              # GET, response is the array
+  orders:   { url: "https://api…/orders", headers: { Authorization: "Bearer KEY" }, at: "data" }
+  search:   { url: "https://api…/graphql", method: "POST", body: { query: "…" }, at: "data" }
+}
+```
+- `at` reads the array out of `json[at]` — dotted for nested envelopes (`"data.posts"`). Else the response IS the array. `body` is JSON-encoded (sets `content-type`).
+- At build (`muten build`), **GET** sources are fetched and baked into the HTML (SSG); non-GET run only client-side (no build side-effects).
+- **Headers ship to the client** like any browser fetch — use public keys or a per-user token, never a server secret.
+
+**Don't repeat the backend — `api { }` in `src/app.muten`** sets the base URL + default headers for ALL sources:
+```
+# src/app.muten
+api { base: "https://api.shop.com/v1"  headers: { Authorization: "Bearer KEY" } }
+```
+```
+# any page — only what differs
+sources {
+  products: { url: "/products", at: "data" }     # → https://api.shop.com/v1/products, with the Authorization header
+  orders:   { url: "/orders",   at: "data" }
+}
+```
+A **relative** source url is joined to `base`; an **absolute** one (`https://…`) ignores it (other host). Source headers override the api defaults. Define the backend once.
+
+**Multiple backends** — name the clients, pick one per source with `{ api: "name" }`:
+```
+# src/app.muten
+api {
+  shop: { base: "https://api.shop.com/v1", headers: { Authorization: "Bearer KEY" } }
+  cms:  { base: "https://cms.io/api" }
+}
+```
+```
+sources {
+  products: { api: "shop", url: "/products", at: "data" }
+  posts:    { api: "cms",  url: "/posts",    at: "data.posts" }
+}
+```
+No `api` field → the client named `default`. The flat `api { base, headers }` form is just a single default client.
+
+**Writing to the backend (POST/PUT/DELETE)** — a source-backed list gets `create`/`update`/`delete` in an action, fired by an event; each hits the resource endpoint (reusing the source's `api` base + headers) and updates the list reactively:
+```
+state { orders = query orders : list<Order> }
+sources { orders: { api: "shop", url: "/orders", at: "data" } }
+
+action buy  mutates orders <- item { orders.create(item) }   # POST   /orders       → append the result
+action edit mutates orders <- item { orders.update(item) }   # PUT    /orders/{id}  → replace by id
+action drop mutates orders <- item { orders.delete(item) }   # DELETE /orders/{id}  → remove by id
+
+Button "Buy" -> buy(product)
+```
+The write action is **async** and exposes reactive **`buy.pending`** (true while in flight) and **`buy.error`** — use them for UX:
+```
+when buy.pending { Text "Saving…" }
+when buy.error { Text "Could not save: {buy.error}" }
+```
+`create`/`update`/`delete` are **optimistic** — the list changes instantly, reconciles with the server response, and **reverts** if the request fails (with `.error` set). REST convention: create = POST to the collection, update/delete target `/{item.id}`. Local-only mutations stay `push`/`set`/`reset`/`remove`; `create/update/delete` talk to the server.
+
+**Re-running a query — `refetch` (search / pagination / filters)** — call it in an action with **N named params**; they become the query string (`?q=…&page=…`, url-encoded) and the list reloads. Works for any web-app, not just lists:
+```
+state { q = "" : text  page = 1 : number  products = query products : list<Product> }
+sources { products: { url: "/products", at: "data" } }
+
+action search mutates products <- term { products.refetch(q: term, page: 1) }
+action next   mutates products         { page.set(page + 1)  products.refetch(q: q, page: page) }
+
+SearchField bind q
+Button "Search" -> search(q)
+Button "Next"   -> next
+```
+Pass as many params as you need (`q`, `page`, `sort`, `category`, …). The query's `.loading`/`.error` reflect the refetch.
+
+**Escape hatch — explicit request** (when the API isn't RESTful): `post`/`put`/`delete` a `"client:/path"` (interpolated) with an optional `body`, in an action:
+```
+action buy    <- item { post "shop:/orders" body item }        # any method, any path
+action cancel <- o    { delete "shop:/orders/{o.id}/cancel" }   # custom path, interpolated
+action ping           { post "shop:/health" }                   # no body, no `mutates` needed
+```
+It uses the named client's base + headers; the action is async with `.pending`/`.error`. Prefer `create`/`update`/`delete` when the API is RESTful (those also update the list); reach for `post`/`put`/`delete` only when the convention doesn't fit.
+
 ## 6. Primitives
 A bare string is the node's main prop. `{ }` = children. Lay out with `style()`, skin with `class()`.
 
@@ -110,6 +194,8 @@ Horizontal layout = a region with `style(row)` (there is no `Row` primitive). Cl
 
 Modifiers (after a primitive): `style(tokens)` · `class("css")` · `bind @state` · `submit action` ·
 `where(clauses)` · `columns(a, b)` · `alt "…"` · `inputs(k: v)` · `on(event: action)`.
+`class()` also toggles reactively (`class(active when isOpen)`); `on(event: action)` works on **any** element
+(keydown, mouseenter, change, blur, …) and calls the action — use `Button -> action(arg)` when you need an arg.
 
 ## 7. Theme — how it works
 `theme.muten` supplies the **scale** (values); the engine owns only the **vocabulary** (token names).
@@ -159,8 +245,9 @@ Use it from any page/shell by name: `when ui.menuOpen { … }`, `Button "☰" ->
 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.
+`src/app.muten` maps URLs to pages. It uses **real paths** (`/about`, History API — client-side nav, no
+reload); the **first route is the default**. The folder under `src/pages/` must match the page name.
+*(Deploy: the host must serve `index.html` for any path — standard SPA fallback.)*
 ```
 routes {
   /         -> home               # src/pages/home/home.muten
@@ -170,7 +257,23 @@ routes {
 }
 ```
 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.
+A route named `/404` catches any unmatched path (otherwise the first route is shown).
+Navigate with `Link "x" -> /path` (client-side, no reload).
+
+**Route params:** a `:seg` in the route captures a URL value. The page declares it with `param <name>`,
+then uses it as a read-only string in interpolation / `when` / expressions (it can't be mutated):
+```
+# app.muten
+routes { /product/:id -> product }
+# src/pages/product/product.muten
+screen product
+param id
+Page { Title "Product {id}" }
+```
+Navigating `/product/1` → `/product/2` re-mounts the page with the new `id` (re-fetch the new item).
+
+**`<head>` meta (SEO):** a page declares `meta { title "…" description "…" }` → `<title>` + `<meta>` tags
+(`og:title`/`og:description` auto-derived). Applied on navigation and baked into the SSG HTML at build.
 
 ### Shell (persistent chrome)
 Wrap routes in a `shell { … slot … }` for a nav/footer around every page. `slot` is where the active