@madojs/mado 0.5.0 → 0.6.0

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
 
@@ -247,6 +251,28 @@ component("x-child", ({ host }) => {
 });
 ```
 
+### 13. Component registration imports
+
+Custom elements are global after registration, but the browser never imports a
+component file automatically.
+
+```ts
+import "./components/app-shell.js";
+
+render(html`<x-app-shell>${router.view}</x-app-shell>`, app);
+```
+
+The import runs `customElements.define("x-app-shell", ...)`. After that,
+`<x-app-shell>` works anywhere in the current document.
+
+Rules:
+
+- App shell / global providers → import in `main.ts`.
+- Components used only by one page → import in that page.
+- Components shared by a feature → import in the feature entry/page.
+- Tiny leaf components used everywhere → importing in `main.ts` is acceptable.
+- Do **not** bulk-import every component "just in case".
+
 ## SOFT GUIDELINES — recommended, but not critical
 
 - **TypeScript strict.** Use `noUncheckedIndexedAccess`-aware code (with `!` or a type guard).
@@ -263,10 +289,29 @@ src/
 ├── main.ts           ← entry: mount to #app
 ├── pages/            ← one page = one file
 ├── components/       ← reusable x-* components
-├── layouts/          ← layout for nested routes
+├── layouts/          ← optional route layout modules (`page({ child })`)
 └── 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 |
@@ -276,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,193 @@
 # Changelog
 
+## Unreleased
+
+Nothing yet.
+
+## 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.
+
+### Fixed
+
+- Generated starter apps can now run `mado dev` / `mado serve` from the app
+  root instead of assuming the framework repository layout.
+- The CRUD starter shell is a real Web Component again, using Shadow DOM and
+  `<slot>` for route projection.
+- Feature components in the CRUD starter are imported by the pages that render
+  them, avoiding a confusing "import everything in main" pattern.
+- The minimal starter counter tag registration now matches the rendered
+  `<x-app-counter>` tag.
+- The router default 404 view is rendered through `html` templates, not dynamic
+  `innerHTML`.
+- `npm run bundle` defaults to the existing showcase entry instead of the old
+  removed `examples/main.ts`.
+
+### Changed
+
+- Starter packages include `npm run dev` and generated `.gitignore` defaults.
+- README and docs clarify that Mado works with browser primitives rather than
+  replacing the platform.
+- Form documentation now describes `useForm()` as schema-based validation close
+  to HTML constraints, matching the implementation.
+- Shadow DOM / Light DOM docs now explain layout components, `<slot>`, and
+  component registration imports.
+- Deep imports are documented as internal/unstable before v1.
+- CI workflows use Node24-based GitHub actions and the obsolete Cloudflare
+  showcase deploy workflow was removed.
+- The release workflow updates npm before publish and creates GitHub releases
+  through the GitHub CLI.
+- Browser regression now runs on a weekly schedule as well as manually.
+
 ## 0.5.0
 
 First public release preparation for Mado.

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

@@ -19,6 +19,11 @@
 
 > A small native-web SPA framework you can read in an evening.
 
+[![npm](https://img.shields.io/npm/v/@madojs/mado.svg)](https://www.npmjs.com/package/@madojs/mado)
+[![CI](https://github.com/madojs/mado/actions/workflows/ci.yml/badge.svg)](https://github.com/madojs/mado/actions/workflows/ci.yml)
+[![Browser Regression](https://github.com/madojs/mado/actions/workflows/browser.yml/badge.svg)](https://github.com/madojs/mado/actions/workflows/browser.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
 Mado is a thin TypeScript framework on top of the browser platform: Web
 Components, signals, tagged-template `html`, a router, resources, forms,
 context, persisted state and static prerender. No runtime dependencies, no
@@ -27,6 +32,12 @@ required bundler, no hidden build pipeline: `tsc → browser`.
 Mado (`窓`) means “window” in Japanese: a calm native-web window into an app,
 without dragging a whole frontend factory into the room.
 
+Mado does not try to replace the browser platform. The browser already gives
+us modules, custom elements, attributes, events, forms, CSS, URLs, history,
+fetch and the DOM. Mado's job is to make those primitives comfortable enough
+for small and serious applications, without taking away your understanding of
+what is happening.
+
 ```txt
 Runtime budget after build:
   native ESM graph: ~60 KB raw, ~24 KB gzip across separate modules
@@ -80,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 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 admin-style example with
-`resource()`, `mutation()`, `useForm()`, `each()` and `queryParam()`:
+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
@@ -140,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)
@@ -170,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:
 
@@ -314,8 +342,19 @@ html`
 `;
 ```
 
-Validation is based on native HTML constraint validation plus optional custom
-`validate(values)`.
+Validation is schema-based and intentionally close to native HTML constraints:
+`required`, `min`, `max`, `pattern`, `type=email/url/number`, plus optional
+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:
+
+```ts
+import { html, component, signal } from "@madojs/mado";
+```
+
+Deep imports may exist in the package for tooling and generated files, but they
+are internal and can change before v1.
 
 ## Static HTML Without Hydration
 
@@ -326,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,13 +13,41 @@ 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
 
 - 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.
-- Release hygiene: npm provenance, GitHub repo metadata, tags and changelog.
+- Public exports audit: root import is stable; deep imports must either become
+  explicit public subpaths or remain clearly unsupported before v1.
+- Release hygiene: npm provenance / Trusted Publishing, GitHub repo metadata,
+  tags and changelog.
 - Size reporting command or CI summary with ESM and bundled/minified budgets.
+- Public demo site built with Mado: docs, CRUD starter and showcase as a live
+  proof instead of another README claim.
 - Real commercial app test: validate auth, forms, tables, resources, route
   transitions and long-lived sessions outside toy examples.
 
@@ -43,8 +72,10 @@ readable and reliable under real application pressure.
 | 2026-06-03 | v0.3 hardening | Nested template cleanup, stale async route guard, Shadow DOM link/prefetch tests, scroll behavior, `warnOnce`, component reconnect/style tests. |
 | 2026-06-05 | v0.4 showcase max | `examples/showcase` became a SaaS CRM pressure app with accounts, deals, activity, nested routes, context services and browser regression. |
 | 2026-06-06 | v0.5 project shape | Unified `mado` CLI, dev server logs, docs language skeleton, examples cleanup (`basic`, `tickets`, `showcase`, `cloudflare`). |
-| 2026-06-06 | Mado rebrand | Public package/import name `madojs`, CLI `mado`, brand/docs/examples updated, internal legacy markers cleaned. |
+| 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