@madojs/mado 0.5.1 → 0.6.1

package/AGENTS.md

@@ -2,6 +2,10 @@
 
 > This file is read by AI agents in IDEs (Cursor, Cline, Copilot, Continue, etc.).
 > Goal: prevent them from generating React-like code where Mado should be used.
+>
+> The v0.6 product-surface push is archived in
+> [`MADO_V1_PLAN.md`](./MADO_V1_PLAN.md). New work should follow `ROADMAP.md`
+> / `TODO.md` unless the user explicitly resumes that tracker.
 
 ## Project at a glance
 
@@ -289,6 +293,25 @@ src/
 └── lib/              ← API client, contexts, pure logic
 ```
 
+## App architecture for LLM
+
+When generating an app, prefer the blessed production shape from
+`docs/en/10-app-architecture.md` and the `starters/admin/` example:
+
+- `src/main.ts` mounts `routesApi.view` and imports only global styles,
+  providers, and tiny shared components.
+- `src/routes.ts` exports both `manifest` and `default routes(manifest, ...)`.
+- Put route wrappers in `src/layouts/` via `layout()`, not ad-hoc shell logic
+  inside every page.
+- Put backend access in `src/lib/api.ts` and auth/session logic in
+  `src/lib/auth.ts`; guards call auth helpers, pages call API helpers.
+- Put one page per file under `src/pages/`; a page imports the feature
+  components it renders.
+- Use `resource()` for reads, `mutation(..., { invalidates })` for writes,
+  and `useForm()` for form state/validation.
+- Use `mado release` as the production path. `out/` is the only deploy
+  artifact; `dist/` is internal build output.
+
 ## Where to find specific answers
 
 | Question | File |
@@ -298,6 +321,9 @@ src/
 | How does the router work? | `src/router.ts` (~530 lines) |
 | How does resource + cache work? | `src/resource.ts` (297 lines) |
 | How do forms work? | `src/forms.ts` (212 lines) |
+| How should an app be structured? | `docs/en/10-app-architecture.md` |
+| How should errors be handled? | `docs/en/15-error-handling.md` |
+| How should bake be used? | `docs/en/16-bake-cookbook.md` |
 | When something goes wrong | `docs/en/07-llm-pitfalls.md` |
 
 ## Before committing

package/CHANGELOG.md

@@ -1,5 +1,270 @@
 # Changelog
 
+## Unreleased
+
+Nothing yet.
+
+## 0.6.1
+
+Starter & release-pipeline hardening pass. No public API breaks.
+Identified from a lab pressure-test on `/admin/lab` plus a deep audit of the
+starter / bundle / bake / dev-server contour. All fixes verified by
+regression tests added in this release.
+
+### Fixed
+- **Starters**: every `index.html` in `starters/{admin,crud,minimal}/` now
+  uses root-absolute paths in the importmap and entry `<script>` tag
+  (`/node_modules/@madojs/mado/...`, `/dist/main.js`). Relative paths
+  (`./node_modules/...`, `./dist/main.js`) broke hard-refresh of any nested
+  route (`/admin/orders/42` → browser fetched
+  `/admin/orders/dist/main.js` → 404 → blank page). Inline comments in each
+  file explain the trap so it does not get reverted.
+- **Starters/admin**: `pages/admin/order-detail.ts` now uses `each(items,
+  key, render)` instead of `o.items.map(...)`, matching `llms.txt` rule #3
+  and the framework's own pitfalls documentation.
+- **`scripts/bundle.mjs`**: cleans stale hashed assets before every build.
+  Previously each `mado bundle` / `mado release` left old `main-<hash>.js`
+  and `chunk-<hash>.js` in `out/assets/`; the rewriter then emitted
+  `<link rel="modulepreload">` for every leftover `.js` it found, so
+  production HTML shipped dead-code preloads without SRI. In app-mode the
+  whole assets directory is wiped; in repo-mode only recognisable hashed
+  files are removed so unrelated repo artifacts stay put.
+- **`src/router/manifest.ts`**: opens a fresh component lifecycle scope
+  around every `page.view()` / layout `view()` call and disposes the
+  previous one on navigation (and on `router.dispose()`). `resource()`,
+  `effect()` and `persisted()` created inside `page.view()` now register
+  cleanup with that scope automatically — no more
+  `[mado:resource-outside-lifecycle]` warnings on the framework's own
+  canonical examples, and no more invalidator-subscription leaks across
+  route changes.
+- **`src/resource.ts`**: guards against stale responses overwriting fresh
+  data on rapid key changes. The previous `AbortController` defence worked
+  only if the user-supplied fetcher honored `AbortSignal` — for fetchers
+  that ignore cancellation, a slow stale resolution for an old key could
+  win over a fast fresh one. Both then/catch branches now also check
+  `if (key !== lastKey) return`.
+- **`server/serve.mjs`**: falls back to `./public/*` when a file is not
+  found at the project root, mirroring what `mado release` does to `out/`.
+  `favicon.svg`, `robots.txt`, `og-image.png` etc. no longer 404 in dev.
+- **`server/serve.mjs`**: prints an actionable hint on `EPERM`/`EACCES`
+  pointing at `mado dev --host 127.0.0.1` (the default host changed from
+  the implicit `0.0.0.0` to `localhost`, which is friendlier in sandboxed
+  environments).
+- **`scripts/preview.mjs`**: serves prerendered HTML from `<out>/baked/`
+  with priority over the SPA shell. Previously `mado preview` only looked
+  at `out/` and never saw bake's output, so prerendered routes returned
+  the empty SPA shell — looking like a "blank page" bug even when bake
+  had succeeded.
+
+### Added
+- **`mado dev` / `mado serve` flag pass-through**: `cli.mjs` now splits
+  positional arguments from flags via `splitDevArgs()`, so calls like
+  `mado dev --host 127.0.0.1`, `mado dev showcase --port 6000` and
+  `mado dev -- --host 0.0.0.0` all work. Previously the CLI mistook the
+  flag for an example name and exited with `unknown example`.
+- **`server/serve.mjs`**: tiny argv parser supporting `--host`, `--port`
+  and `--host=value` forms; HOST and PORT also fall back to environment
+  variables and `mado.config.json` (`dev.host`, `dev.port`).
+- **`scripts/preview.mjs`**: same `--host` / `--port` flags as the dev
+  server, plus a startup banner showing `url:` / `out:` / `baked:` so it
+  is obvious which directories preview is serving from.
+- **`scripts/bake.mjs`**: fails loudly when the manifest exists but no
+  page declares `bake: { paths, data }`. The previous behaviour produced
+  `0 pages + sitemap.xml` silently with exit code 0, making `mado
+  release` look successful while shipping only the SPA shell with no
+  SEO-friendly HTML. The new warning prints the skipped routes, a
+  worked example bake snippet, and exits non-zero. Override with
+  `MADO_BAKE_ALLOW_EMPTY=1` for intentional SPA-only deploys.
+- **`scripts/bake.mjs`**: clearer "missing dev dep" errors — when
+  `linkedom` or `esbuild` is missing the message now tells the user
+  exactly which packages to `npm i -D`.
+- **Starter landing pages**: `home.ts` in all three starters now declares
+  `bake: { paths: () => [{}], data: () => ({}) }` and a `head()` so
+  `mado release` actually prerenders the landing page out of the box.
+- **Starter `devDependencies`**: `linkedom` and `esbuild` added to
+  `starters/{admin,crud,minimal}/package.json` so `mado release` works
+  immediately after `mado init <app>` + `npm install`, without manual
+  follow-up installs.
+- **Regression tests** (`test/`):
+  - `starter-html-paths.test.mjs` — asserts every starter `index.html`
+    uses root-absolute paths in both the importmap and the entry script.
+  - `bundle-cleanup.test.mjs` — end-to-end: runs `mado bundle` twice on
+    a synthesized temp project (mutating source between runs) and
+    asserts there is exactly one `main-<hash>.js` in `out/assets/`
+    afterwards.
+  - `resource.test.mjs` (2 new cases) — stale-response races: a fetcher
+    that ignores `AbortSignal` with key=1 slower than key=2, plus a
+    rapid 3-way key thrash where the final key is the slowest fetch.
+    Both assert `data()` reflects the latest key, not the fastest
+    response.
+
+### Changed
+- **`server/serve.mjs`** default host is now `localhost` (was implicitly
+  `0.0.0.0`). LAN exposure is opt-in via `mado dev --host 0.0.0.0` or
+  `HOST=0.0.0.0`. The startup banner shows both the bound host and a
+  click-friendly URL (`localhost` substituted when bound to `0.0.0.0`).
+
+### Notes
+- No public API changes; no migrations required. Apps that previously
+  worked on a fresh-out-of-the-box `mado init` did so only because
+  someone manually fixed the starter's relative paths and dev deps —
+  this release closes those gaps so the documented "happy path" actually
+  is happy.
+- If you intentionally deploy SPA-only (no prerendered HTML), drop
+  `mado bake` from your release pipeline or set
+  `MADO_BAKE_ALLOW_EMPTY=1`; otherwise bake will now fail your
+  CI with a clear pointer to the missing config.
+- Test count: 137 pass, 0 fail, 3 skipped (Playwright e2e — unchanged).
+
+## 0.6.0
+
+Product-surface release: app-mode defaults, blessed admin starter, release
+pipeline, core hardening and v1 recipe docs.
+
+Phase 1 — Repo-vs-app split:
+
+### Added
+- `MADO_V1_PLAN.md` — executable tracker for the v1 push.
+- `scripts/_config.mjs` — single configuration loader (defaults < `mado.config.json`
+  < CLI flags). Exports `loadConfig`, `detectContext`, `parseFlags`,
+  `resolveProjectPath`. [v1 F1.1]
+- `mado release` command: one-shot `typecheck + build + bundle + bake + copy
+  public/ → out/` pipeline so apps have exactly one command to ship. [v1 F1.3]
+- `mado.config.json` shipped in the `minimal` and `crud` starters with the
+  default app-mode layout (`src/routes.ts`, `index.html`, `out/`). [v1 F1.4]
+- Tests: `test/config-loader.test.mjs`, `test/bake-cli.test.mjs` (11 + 3
+  cases covering context detection, config precedence, flag parsing, bake
+  flags, and the no-more-silent-`[object Object]` contract). [v1 F1.6]
+
+### Changed
+- `scripts/bake.mjs` now reads configuration from `mado.config.json` and
+  accepts `--entry`, `--template`, `--out`, `--base-url` flags. In app-mode
+  defaults are `src/routes.ts` + `index.html` + `out/baked/`; the
+  `@madojs/mado → src/index.ts` alias is repo-only. [v1 F1.2]
+- `scripts/bake.mjs` no longer renders unsupported values as `[object Object]`;
+  it raises a loud, file/route-targeted error with a hint instead. [v1 F1.2]
+- `scripts/cli.mjs` detects repo-vs-app context, advertises `mado release`,
+  and ships a redesigned `mado help` that explains the dev / build / release
+  / preview pipeline. [v1 F1.3]
+- Starter `package.json` scripts go through the `mado` CLI exclusively
+  (`mado build`, `mado dev`, `mado bundle`, `mado bake`, `mado release`,
+  `mado preview`). [v1 F1.4]
+- `docs/en/02-project-layout.md` rewritten around the canonical `src/` /
+  `dist/` / `public/` / `out/` model plus a `mado.config.json` one-screen
+  reference. [v1 F1.5]
+- `ROADMAP.md`, `TODO.md`, `AGENTS.md` now distinguish the completed
+  `MADO_V1_PLAN.md` archive from future roadmap/TODO work. [v1 F0]
+
+Phase 2 — One blessed way:
+
+### Added
+- `layout()` factory in `src/page.ts` (alias of `nested()`) plus `Guard` and
+  `GuardResult` types. Exported from the public API. [v1 F2.1 / F2.3]
+- Route guards: nested groups and individual pages accept `guard: Guard | Guard[]`.
+  Verdicts: void (pass), `{ halt: true }`, or `{ redirect, replace? }`. Async-aware
+  with a sync fast path; throwing guards are treated as `halt`. [v1 F2.2]
+- New starter `starters/admin/`: nested manifest with `/`, `/login`, `/admin`
+  groups; blessed `lib/api.ts` (`createApiClient`, `ApiError`, single-flight
+  401-refresh) and `lib/auth.ts` (`accessToken`, `restoreSession`, `requireAuth`,
+  `login`, `logout`); `layouts/{app,auth}.ts` with a real admin shell; tiny
+  `x-button`/`x-input` design-token components; dashboard + orders + order-detail
+  pages; `mado.config.json` with a dev `/api` proxy; `public/favicon.svg`. [v1 F2.4]
+- CLI advertises `mado init <name> --starter admin` and lists it in `mado help`.
+  [v1 F2.5]
+- `docs/en/11-layouts.md` — the canonical layout recipe (nested routes) plus
+  two acceptable alternatives with caveats. [v1 F2.6]
+- `docs/en/12-auth-and-api.md` — the blessed `api`/`auth` recipes, backend
+  contract, and dev-proxy hint. [v1 F2.7]
+- `test/guards-layouts.test.mjs` — 7 cases covering the public `layout()`
+  alias, sync pass/halt/redirect, async guards, parent→page guard order, and
+  throwing-guard fallback. [v1 F2.8]
+
+Phase 3 — Bake first-class + Release pipeline:
+
+### Added
+- `mado release` writes `_redirects` (`/* /index.html 200`) and `_headers`
+  (immutable for `/assets/*`, no-cache for HTML) into `out/` when they do not
+  exist, so Cloudflare Pages / Netlify deploys "just work". [v1 F3.7]
+- `docs/en/13-deployment.md` — VPS + nginx, Cloudflare Pages, S3/CloudFront,
+  Netlify and GitHub Pages recipes; cache-control matrix; GitHub Actions
+  release sketch; troubleshooting (deep-link 404, HTML caching, `[object Object]`).
+  [v1 F3.8 / F3.9]
+- `test/release-pipeline.test.mjs` — end-to-end test: scaffold a temp app,
+  symlink the local framework, run `mado release`, assert that `out/index.html`,
+  `out/baked/index.html`, `out/baked/sitemap.xml`, `out/_redirects`, `out/_headers`,
+  and copied `public/` assets are all present. [v1 F3.10]
+
+### Changed
+- `scripts/preview.mjs` now reads `mado.config.json` (`build.out`, `dev.port`),
+  refuses to auto-build by default in app-mode, and asks the user to run
+  `mado release` first. Legacy auto-build is opt-in via `PREVIEW_AUTOBUILD=1`
+  for the framework repo. [v1 F3.3]
+- `scripts/bundle.mjs` is now app-mode aware: reads `mado.config.json` for
+  defaults, accepts `--entry/--html/--out` flags, and writes hashed bundles
+  into `out/assets/` so the new nginx / Cloudflare cache rules apply. The old
+  `examples/showcase` defaults are kept only in repo-mode for dogfooding.
+  [v1 F3.10]
+- `server/serve.mjs` honors `dev.proxy` from `mado.config.json` and forwards
+  matching prefixes (e.g. `/api → http://localhost:3000`) without external
+  dependencies. The startup banner prints the active proxy table. [v1 F3.6]
+
+### Deferred to v0.7
+- `mado dev` does not yet serve baked routes inline. Workaround: run
+  `mado release && mado preview`. [v1 F3.2]
+- `mado check` (bake-safety scan over `bake:` routes) is not exposed yet.
+  The loud-error contract in `scripts/bake.mjs` covers the regression case.
+  [v1 F3.5]
+
+Phase 4 — Core hardening:
+
+### Added
+- `computed(fn, { equals })` option to suppress subscriber reruns when an
+  observed computed recomputes to an equal value. [v1 F4.3]
+- HTML directives: `unsafeHTML()`, `ref()`, `classMap()` and `styleMap()` are
+  exported from the public API. Runtime bindings enforce valid positions and
+  clean up stale classes/styles/refs on updates and disposal. Bake can serialize
+  the static directive shapes it can safely represent. [v1 F4.4]
+- `useForm()` now supports async validators via form-level `validateAsync`,
+  field-level `validateAsync`, `validating` / `validatingFields`, and explicit
+  `validate()` / `validateField()` methods. [v1 F4.5]
+- `useForm().array(name)` adds a small field-array helper with dotted path names
+  (`items.0.title`) and wildcard schema validation (`items.*.title`). [v1 F4.5]
+- `test/signal-cycle.test.mjs` covers self-triggering effect cycle detection.
+  [v1 F4.2]
+- `test/html-directives.test.mjs` covers directive rendering, cleanup and
+  invalid child-position usage. [v1 F4.4]
+- `test/forms.test.mjs` covers async validator races, async submit blocking,
+  and field-array wildcard validation. [v1 F4.5]
+- Phase 4 now has an explicit coverage audit tying every core-hardening task to
+  its regression tests. [v1 F4.9]
+
+### Changed
+- `computed()` now releases dependency subscriptions after unobserved reads and
+  after the last subscriber is disposed, avoiding long-lived stale subscriptions
+  in the signal graph. [v1 F4.1]
+- The effect scheduler now detects runaway self-triggering cycles and emits a
+  clear diagnostic instead of flushing forever. [v1 F4.2]
+- Runtime head management now clears Mado-managed tags on every navigation,
+  including pages without `head()` and pages whose `head()` throws, so stale
+  baked/runtime SEO tags cannot leak across routes. [v1 F4.8]
+- Router navigation now saves/restores scroll positions for back/forward,
+  scrolls new navigations to the top, and moves focus to the main content
+  landmark after navigation. [v1 F4.6]
+- `routes()` now supports a global `errorPage(err, params)` route boundary for
+  lazy loader, `load()` and `view()` errors, while local `page.errorView` still
+  wins. [v1 F4.7]
+
+Phase 5 — Documentation:
+
+### Added
+- `docs/en/10-app-architecture.md`, `14-testing.md`, `15-error-handling.md`
+  and `16-bake-cookbook.md` complete the v1 English recipe set. [v1 F5.1-F5.4]
+- `AGENTS.md` now includes an "App architecture for LLM" section and `llms.txt`
+  links the v1 architecture, layout, auth/API, deployment, testing,
+  error-handling and bake docs. [v1 F5.5-F5.6]
+- Russian, French and Ukrainian documentation now includes localized versions of
+  the v1 recipe docs `10` through `16`. [v1 F5.7]
+
 ## 0.5.1
 
 Patch release focused on first-user DX after the public npm launch.

package/MADO_V1_PLAN.md

@@ -0,0 +1,179 @@
+# MadoJS — Road to v1 (completed v0.6 tracker)
+
+> Completed tracker for the v0.6 product-surface push. The work agreed during
+> the v1 audit is now closed and squash-merged into `main` as
+> `feat: add v1 product surface`.
+>
+> Convention: every commit/PR that advances v1 references task IDs in its message,
+> e.g. `[v1 F1.2] bake.mjs: app-mode defaults + --entry/--template/--out flags`.
+> When a task is completed, tick its box here in the same commit.
+
+---
+
+## 0. Mental model (write this into docs first)
+
+Three artifact states. One deploy artifact. End of story.
+
+| Folder      | What it is                                                     | Who writes        | Who reads                  | Deployed?         |
+|-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
+| `src/`      | your source (TS)                                               | you               | `tsc`, `esbuild`           | no                |
+| `dist/`     | `tsc` output (native ESM JS for the browser)                   | `mado build`      | `mado dev`, dev browser    | no (internal)     |
+| `public/`   | static assets (favicons, images, robots.txt)                   | you               | `mado bundle` copies it    | as part of `out/` |
+| `out/`      | **the only deploy artifact**: SPA shell + bundles + baked HTML | `mado release`    | nginx / CDN / CF / VPS     | ✅ yes            |
+
+One-liner for users:
+> Develop with `mado dev`. To deploy: run `mado release`, then upload `out/` anywhere.
+
+`mado release` = `typecheck` + `build` + `bundle` + `bake` + copy `public/*` → `out/`.
+One command. One artifact. Zero questions about where things live.
+
+---
+
+## 1. Problem map (consolidated)
+
+### Layer A — Core (from the audit)
+- **A1** Computed leaks: no refcount/owner; once read, computed stays subscribed to deps forever.
+- **A2** No cycle-detection in `effect` (e.g. `effect(() => x.set(x()+1))` runs forever).
+- **A3** No `equals` option on `computed`.
+- **A4** No template directives: `unsafeHTML`, `ref`, `classMap`, `styleMap`.
+- **A5** `useForm`: no async validators, no field-arrays.
+- **A6** `resource`/`invalidate`: no typed key relationship; pattern miss is silent.
+- **A7** Router: no scroll restoration / focus management / error boundary.
+- **A8** `head()`: not obvious how dedup/cleanup happens across navigation.
+
+### Layer B — DX, tooling, product surface (from dogfooding)
+- **B1** CLI/bake hardcoded to `examples/` and alias `@madojs/mado → src/index.ts` — repo-mode leaks into user apps.
+- **B2** No single blessed way for **layouts** (LLM and humans both guess).
+- **B3** No blessed way for **auth + API client + dev-proxy**.
+- **B4** No single config file (`mado.config.json`); everything is env vars.
+- **B5** Unclear model for `dist/` vs `out/` vs `public/`.
+- **B6** No `mado release` (one deploy artifact).
+- **B7** Bake silently renders `[object Object]` for `each()`.
+- **B8** Bake lives "next to" the app instead of inside `mado dev`.
+- **B9** No route guard API.
+- **B10** `crud` starter looks like raw scaffold; no admin-template.
+- **B11** Docs missing: app-architecture, layouts, auth-and-api, deployment, testing, error-handling, bake-cookbook.
+- **B12** Starter scaffolds contain `examples/` legacy.
+
+---
+
+## 2. Phases (deliver in order; phase 5 runs in parallel)
+
+### 🟦 Phase 1 — Repo-vs-app split (P0)
+
+Goal: kill `examples/` leakage; make app-mode the default.
+
+### 🟩 Phase 2 — One blessed way (P0)
+
+Goal: conventions over flexibility. Layouts, guards, auth, api — one recipe each.
+
+### 🟨 Phase 3 — Bake first-class + Release pipeline (P0)
+
+Goal: pragmatic path from `mado dev` to production on VPS / Cloudflare / static CDN.
+
+### 🟪 Phase 4 — Core hardening (P1)
+
+Goal: long-term correctness of signals, html, router, forms, head.
+
+### 🟫 Phase 5 — Documentation (P0/P1, in parallel)
+
+Goal: a backender can ship an admin app reading only the docs.
+
+---
+
+## 3. Acceptance scenario for v1
+
+```bash
+npm exec --package @madojs/mado@latest -- mado init dashboard --starter admin
+cd dashboard
+npm install
+mado dev
+# / → public landing
+# /admin → redirected to /login (guard works)
+# log in → admin shell with sidebar / topbar / dashboard / orders table
+
+mado release
+rsync -avz out/ user@vps:/var/www/dashboard/
+# done
+```
+
+If a backend developer reaches production **without reading `bake.mjs`,
+without setting env vars, without asking "where does layout live?",
+and without an `examples/` folder in their app** — v1 is done.
+
+---
+
+## 4. Tracker
+
+### Phase 1 — Repo-vs-app split ✅
+- [x] **F1.1** `mado.config.json` schema + loader (`scripts/_config.mjs`)
+- [x] **F1.2** `scripts/bake.mjs`: flags `--entry/--template/--out/--base-url`, app-mode defaults, no `examples/` alias in app-mode, loud errors instead of silent `[object Object]`
+- [x] **F1.3** `scripts/cli.mjs`: detect repo vs app, read `mado.config.json`, redesigned help, new `mado release` command
+- [x] **F1.4** Starters cleanup: `mado.config.json` and blessed CLI scripts in `starters/minimal` and `starters/crud`; no `examples/` references
+- [x] **F1.5** `docs/en/02-project-layout.md` rewritten around the canonical `src/`/`dist/`/`public/`/`out/` model and `mado.config.json`
+- [x] **F1.6** `test/config-loader.test.mjs` + `test/bake-cli.test.mjs`.
+
+### Phase 2 — One blessed way ✅
+- [x] **F2.1** `layout()` factory (alias of `nested()`) exported from `src/page.ts`; flatten propagates layouts outer → inner.
+- [x] **F2.2** `Guard` type + guard chain in `src/router/manifest.ts`. Verdicts: void / `{ halt: true }` / `{ redirect, replace? }`. Async-aware with sync fast path; throwing guard is treated as `halt` with a `console.error`.
+- [x] **F2.3** `layout`, `Guard`, `GuardResult`, `nested`, `navigate` exported from `src/index.ts`.
+- [x] **F2.4** New starter `starters/admin/` with `layouts/{app,auth}.ts`, `lib/{api,auth}.ts`, `components/{x-button,x-input}.ts`, `pages/{home,login,not-found,admin/{dashboard,orders,order-detail}}.ts`, `styles/global.ts`, `mado.config.json`, `public/favicon.svg`. End-to-end scaffold + typecheck + build verified locally.
+- [x] **F2.5** CLI advertises `--starter admin` (`mado init my-app --starter admin`) and adds it to the help screen.
+- [x] **F2.6** Doc `docs/en/11-layouts.md` (one path + 2 alternatives with caveats).
+- [x] **F2.7** Doc `docs/en/12-auth-and-api.md` (blessed `api`/`auth` recipes, backend contract, dev-proxy hint).
+- [x] **F2.8** `test/guards-layouts.test.mjs` covers the public `layout()` alias, sync pass/halt/redirect verdicts, async guards, parent→page guard order, and throwing-guard fallback (7 tests, all green).
+
+### Phase 3 — Bake first-class + Release pipeline ✅ (core)
+- [x] **F3.1** `mado release` command: typecheck + build + bundle + bake + copy `public/` → `out/` + write `_headers` / `_redirects` (`scripts/cli.mjs`).
+- [x] **F3.2** Deferred to v0.7: `mado dev` serves baked routes inline. Current v1 path is `mado release && mado preview`.
+- [x] **F3.3** `mado preview` reads `mado.config.json`, refuses to auto-build in app-mode (opt in with `PREVIEW_AUTOBUILD=1`), and emulates nginx fallback (`scripts/preview.mjs`).
+- [x] **F3.4** Bake raises a loud, file/route-targeted error on unsupported render values (e.g. `each()` directive objects). Covered by `test/bake-cli.test.mjs`.
+- [x] **F3.5** Deferred to v0.7: `mado check` runs bake-safety scan on `bake:` routes. Current v1 coverage is the loud-error contract from F3.4.
+- [x] **F3.6** Dev-proxy in `server/serve.mjs`: reads `dev.proxy` from `mado.config.json` and forwards matching prefixes to the upstream backend without external deps.
+- [x] **F3.7** `mado release` generates `out/_redirects` (`/* /index.html 200`) and `out/_headers` (immutable for `/assets/*`, no-cache for `/*.html`) when those files do not exist.
+- [x] **F3.8** Doc `docs/en/13-deployment.md` (VPS + nginx, Cloudflare Pages, S3/CloudFront, Netlify, GitHub Pages, CI sketch, cache matrix, troubleshooting).
+- [x] **F3.9** Production `nginx.conf` next to the docs (already shipped, with `gzip_static`, immutable hashed bundles, SPA fallback). Verified referenced from the deployment doc.
+- [x] **F3.10** `test/release-pipeline.test.mjs`: end-to-end CLI test scaffolds an app, runs `mado release`, and asserts `out/index.html`, `out/baked/index.html`, `out/_headers`, `out/_redirects`, public-asset copy, and sitemap. Also `scripts/bundle.mjs` is app-mode aware (no `examples/`-leak when run from a user app).
+
+### Phase 4 — Core hardening
+- [x] **F4.1** Refcount/GC for `computed` in `src/signal.ts` + tests (`computed` releases dep subscriptions after unobserved reads and after the last subscriber is disposed).
+- [x] **F4.2** Cycle-detection in `effect` + `test/signal-cycle.test.mjs`
+- [x] **F4.3** `equals` option on `computed`
+- [x] **F4.4** Directives: `unsafeHTML`, `ref`, `classMap`, `styleMap` in `src/html/bindings.ts` + public exports + `test/html-directives.test.mjs`.
+- [x] **F4.5** `useForm`: async validators (`validateAsync`, field-level `validateAsync`, `validating`) + field arrays (`form.array()`, dotted paths, wildcard schema) + tests.
+- [x] **F4.6** Router: scroll restoration + focus management
+- [x] **F4.7** Router: `errorPage:` in manifest + error boundary
+- [x] **F4.8** `src/head.ts`: guaranteed cleanup on navigation (`data-mado-head` removed before re-applying)
+- [x] **F4.9** Tests for everything above: `test/computed-lazy.test.mjs` (F4.1/F4.3), `test/signal-cycle.test.mjs` (F4.2), `test/html-directives.test.mjs` (F4.4), `test/forms.test.mjs` (F4.5), `test/router-isolation.test.mjs` (F4.6), `test/router-error-boundary.test.mjs` (F4.7), `test/head.test.mjs` (F4.8). Final `typecheck + build + test` pass verified.
+
+### Phase 5 — Documentation (parallel to phases 2-4)
+English docs for project layout, layouts, auth/API and deployment exist now.
+The remaining work is deeper recipes plus translation sync.
+
+- [x] **F5.1** `docs/en/10-app-architecture.md` (end-to-end admin)
+- [x] **F5.2** `docs/en/14-testing.md`
+- [x] **F5.3** `docs/en/15-error-handling.md`
+- [x] **F5.4** `docs/en/16-bake-cookbook.md`
+- [x] **F5.5** `AGENTS.md`: section "App architecture for LLM"
+- [x] **F5.6** `llms.txt`: new anchors
+- [x] **F5.7** ru/fr/uk translations for new docs (`10` through `16`)
+
+---
+
+## 5. Working loop
+
+1. Pick the first unchecked box.
+2. Implement it (small, focused change).
+3. Run `npm test` (and `npm run typecheck` when touching `src/`).
+4. Tick the box in this file in the same commit.
+5. Add a one-line entry under "Unreleased" in `CHANGELOG.md`.
+6. After each phase finishes, pause and review.
+
+## 6. Context-loss safety
+
+- This file = ground truth on disk.
+- `task_progress` in chat = current phase/task.
+- Git commits tagged `[v1 Fx.y]` = time machine.
+
+If future work resumes from this plan, treat it as archive context. New tasks
+belong in `ROADMAP.md`, `TODO.md`, or a fresh tracker.

package/README.md

@@ -91,12 +91,20 @@ enough for serious admin apps while remaining small and readable.
 npm exec --package @madojs/mado@latest -- mado init my-app
 cd my-app
 npm install
-npm run build
-npm run serve
+npm run dev
 ```
 
-Use the CRUD starter when you want a compact admin-style example with
-`resource()`, `mutation()`, `useForm()`, `each()` and `queryParam()`:
+Use the admin starter when you want the blessed production shape out of the box:
+layouts, guards, auth/API client, dev proxy, forms and a small admin shell.
+
+```bash
+npm exec --package @madojs/mado@latest -- mado init dashboard --starter admin
+cd dashboard
+npm install
+npm run dev
+```
+
+Use the CRUD starter when you want a compact resource/mutation/forms example:
 
 ```bash
 npm exec --package @madojs/mado@latest -- mado init my-app --starter crud
@@ -151,17 +159,19 @@ The developer convenience CLI is available as `mado`:
 
 ```bash
 mado init my-app
+mado init dashboard --starter admin
 mado init my-app --starter crud
+mado dev
 mado build
 mado typecheck
 mado test
+mado release
+mado preview
 mado serve basic
 mado dev showcase
 mado examples
 ```
 
-The CLI is useful before v1, but its command polish may still change.
-
 ## Documentation
 
 - [Language index](./docs/README.md)
@@ -181,6 +191,13 @@ Core topics:
 - [For backenders](./docs/en/06-for-backenders.md)
 - [LLM pitfalls](./docs/en/07-llm-pitfalls.md)
 - [Shadow DOM vs Light DOM](./docs/en/09-shadow-vs-light-dom.md)
+- [App architecture](./docs/en/10-app-architecture.md)
+- [Layouts](./docs/en/11-layouts.md)
+- [Auth and API](./docs/en/12-auth-and-api.md)
+- [Deployment](./docs/en/13-deployment.md)
+- [Testing](./docs/en/14-testing.md)
+- [Error handling](./docs/en/15-error-handling.md)
+- [Bake cookbook](./docs/en/16-bake-cookbook.md)
 
 AI-agent entrypoints:
 
@@ -327,7 +344,8 @@ html`
 
 Validation is schema-based and intentionally close to native HTML constraints:
 `required`, `min`, `max`, `pattern`, `type=email/url/number`, plus optional
-custom `validate(values)`.
+custom `validate(values)`. Async validators and field arrays are available via
+`validateAsync`, `validateField()` and `form.array("items")`.
 
 Only the root import is the stable public API:
 
@@ -347,16 +365,16 @@ Cloudflare Worker edge-prerender PoC in [`examples/cloudflare`](./examples/cloud
 
 ## Production Bundle
 
-Native ESM is the default development and demo path. When a bundled production
-artifact is useful, run:
+Native ESM is the default development path. For production, use the one-command
+release pipeline:
 
 ```bash
-npm run bundle
-npm run preview
+mado release
+mado preview
 ```
 
-`bundle` uses optional `esbuild` for code splitting, SRI, `.gz` and `.br`
-outputs. `preview` emulates the provided `nginx.conf` with `node:http`.
+`release` runs typecheck, build, bundle, bake and public asset copy, then writes
+the deployable artifact into `out/`. `preview` serves `out/` like a static host.
 
 ## Tests
 

package/ROADMAP.md

@@ -1,7 +1,8 @@
 # Roadmap
 
-Mado is pre-v1. The goal is not to grow sideways, but to keep the runtime small,
-readable and reliable under real application pressure.
+Mado is still pre-1.0, but the v0.6 product-surface push is complete. The goal
+from here is not to grow sideways, but to keep the runtime small, readable and
+reliable under real application pressure.
 
 ## Current Focus
 
@@ -12,12 +13,31 @@ readable and reliable under real application pressure.
 - Keep English as the public/default project language, with localized docs in
   `docs/ru`, `docs/fr` and `docs/uk`.
 
-## Before v1
+## Completed in v0.6
+
+- **Phase 1 — Repo-vs-app split.** Kill `examples/`-leakage from CLI and bake;
+  introduce `mado.config.json`; app-mode becomes the default for `mado bake`,
+  `mado bundle`, `mado preview`.
+- **Phase 2 — One blessed way.** First-class `layout()` + nested manifest;
+  `Guard` API with `redirect`/`halt`; blessed `--starter admin` starter with
+  blessed `api`/`auth` recipes; docs for layouts and auth-and-api.
+- **Phase 3 — Bake first-class + Release pipeline.** `mado release` as the
+  single deploy command (`dist` internal, `out` deployed); `mado dev` serves
+  baked routes inline; bake stops silently rendering `[object Object]`;
+  deployment doc with VPS / Cloudflare Pages / static-CDN recipes.
+- **Phase 4 — Core hardening.** Computed GC + cycle-detection in `effect`;
+  template directives (`unsafeHTML`, `ref`, `classMap`, `styleMap`); async
+  validators and field-arrays in `useForm`; scroll restoration, focus
+  management and error boundary in the router; head cleanup on navigation.
+- **Phase 5 — Documentation (parallel).** `10-app-architecture.md`,
+  `11-layouts.md`, `12-auth-and-api.md`, `13-deployment.md`, `14-testing.md`,
+  `15-error-handling.md`, `16-bake-cookbook.md`; AGENTS.md app-architecture
+  section; ru/fr/uk translations.
+
+The detailed completed tracker lives in [`MADO_V1_PLAN.md`](./MADO_V1_PLAN.md).
+
+## Remaining Before 1.0
 
-- Generated app DX: `mado dev`/`serve`/starter scripts should feel as polished
-  outside the framework repo as they do inside it.
-- Generated app production story: `mado bundle` and `mado preview` should work
-  from a starter app without repository-only assumptions.
 - Browser compatibility pass across current Chrome, Edge, Firefox and Safari.
 - Accessibility pass for examples and common component patterns.
 - Public API audit: names, warnings, lifecycle rules, docs coverage.
@@ -55,6 +75,7 @@ readable and reliable under real application pressure.
 | 2026-06-06 | Mado rebrand | Public package/import name `@madojs/mado`, CLI `mado`, brand/docs/examples updated, internal legacy markers cleaned. |
 | 2026-06-06 | Public polish | English public surface, localized docs, translated code comments/examples/templates/GitHub files. |
 | 2026-06-07 | First npm release | Published `@madojs/mado@0.5.0` with the `mado` CLI, minimal/crud starters, CI and release workflow. |
+| 2026-06-09 | v0.6 product surface | App-mode CLI/config split, admin starter, release pipeline, core hardening, v1 recipe docs and localized docs. |
 
 ## Future Ideas