flet-box 1.1.2 → 1.1.3

package/AGENTS_FOR_CODE_GEN.md

@@ -0,0 +1,284 @@
+# AGENTS_FOR_CODE_GEN.md
+
+The contract for an agent that **writes FletBox code**. It holds in an app built
+with `flet-box create` and in the framework's own source.
+
+`AGENTS.md` is the contract for *maintaining the framework*. This one is for
+*producing code with it*: what may be written, what may not, and how it is
+proved.
+
+---
+
+## 0. The golden rule
+
+> **If a widget or a prop is not in `.fletbox/api/cheatsheet.md`, it does not
+> exist.**
+
+An invented prop throws nothing. The engine ignores it, the layout breaks
+quietly, and nobody finds it for weeks. If the cheatsheet does not hold what
+the task needs, **ask** — do not invent.
+
+| What I need | Where it lives | How it is produced |
+| --- | --- | --- |
+| Which widgets exist and which props each one takes | `.fletbox/api/cheatsheet.md` | `flet-box check-api --emit-api` — runs before `npm run dev` |
+| The same surface as data: one entry per prop, with its engine target, default, aliases and a sample value | `.fletbox/api/api.json` | `flet-box unpack --all --md` |
+| Everything one widget accepts, and whether each prop is really wired | `flet-box unpack <Widget>` | — |
+| A call I can paste as-is | `flet-box unpack <Widget> --example` | — |
+| The real props of one widget | `npm run check -- --props <Widget>` | — |
+
+Both files are **generated output**: never hand-edit them, regenerate after
+upgrading `flet-box`.
+
+---
+
+## 1. Five things you may never do
+
+1. **No runtime dependency.** FletBox has zero runtime dependencies and the app
+   is offline: no `react`, `vue`, `svelte`, `lit`, `jquery`, `tailwindcss`, no
+   CDN `<script>`, no `.jsx`/`.tsx`. Plain ESM `.js`, with the `.js` extension
+   in every import.
+2. **No hardcoded color.** Every fill, ink and border is a `colors.*` token.
+   A hex literal in a screen is reported as `RAW_COLOR`.
+3. **No hand-written DOM.** Build with widgets and props — never with
+   `innerHTML`, `createElement` or a template string. (The engine uses
+   `innerHTML` internally for rich text; app code does not.)
+4. **No widget or prop outside the cheatsheet**, and no positional arguments:
+   `Text({ text: "Hi" })`, never `Text("Hi")`.
+5. **No API change without deprecation.** Renaming or removing a prop is a
+   breaking change: keep the old name working, mark it, and write the
+   "from X to Y" line in the migration guide.
+
+---
+
+## 2. Ten rules that survive a review
+
+Each cites the numbered rule in `skills/fletbox-design/SKILL.md`, which is
+where the longer argument lives.
+
+1. **Numbers, not pixels.** `padding: 16` is a framework unit and scales with
+   the reader's font; `padding: "16px"` does not. (03, 07)
+2. **Tokens, not colors.** `bgColor: colors.surface`. One brand color per
+   screen; the accent is the reader's to choose, never a hex in a widget. (03, 28)
+3. **Hierarchy in three seconds.** One type size per element, one weight per
+   role. A label and its value that look alike mean the hierarchy is broken. (08)
+4. **Space carries meaning.** 16 inside a card, 16 or 24 between cards, 24
+   between sections. Never mix padding and gap on the same list. (07)
+5. **Depth is a scale.** `elevation` picks the level; a hand-written shadow is
+   noise. (10)
+6. **Every control has a name.** An icon-only button needs `aria-label`, a
+   field needs a label. The gate reports `ICON_ONLY_CONTROL` and
+   `UNLABELED_FIELD`. (11)
+7. **Tap targets are 40 or more**, reached with `height`, not with padding. (11)
+8. **Every interaction has four states.** hover, focus, active and disabled
+   come from the engine's props — do not re-implement them per widget. (12)
+9. **The phone range is the test device.** From 320×568 to 430×932 nothing
+   overflows, nothing is clipped, nothing scrolls sideways. (16)
+10. **One screen per file, one component per file.** A file exporting two
+    widgets is a file nobody finds later.
+
+---
+
+## 3. Examples
+
+### Good
+
+```js
+import { Button, Container, Row, Text, colors, useState } from "flet-box";
+
+export const StatsScreen = () => {
+  const [period, setPeriod] = useState("stats-period", "week");
+
+  return Container({
+    direction: "column",
+    gap: 16,
+    padding: 24,
+    bgColor: colors.background,
+    children: [
+      Text({ text: "This week", size: 24, weight: 600, color: colors.text }),
+      Row({
+        gap: 12,
+        children: [
+          Button({ text: "Week", onPress: () => setPeriod("week"), variant: "outlined" }),
+          Button({ text: "Month", onPress: () => setPeriod("month"), variant: "outlined" }),
+        ],
+      }),
+      Button({
+        icon: "refresh",
+        "aria-label": "Refresh stats",
+        onPress: refresh,
+        bgColor: colors.primary,
+        height: 40,
+      }),
+    ],
+  });
+};
+```
+
+Every widget and prop there is in the cheatsheet, every length is a number, and
+every color is a token.
+
+### Bad
+
+```js
+import { Card } from "react";                       // 1. foreign framework
+```
+
+```js
+import { Button, Text } from "flet-box";
+
+const el = document.createElement("div");           // 3. hand-written DOM
+el.innerHTML = `<b>${name}</b>`;
+
+Text({ text: "Total", color: "#4f46e5", size: 13 }); // 2. hex + off-scale size
+Text("Total");                                       // 4. positional argument
+Button({ icon: "save", onPress: save });             // 6. a control with no name
+Button({ text: "Save", onPress: save, bgColor: "#4f46e5" }); // 2. hardcoded color
+```
+
+---
+
+## 4. The verification protocol
+
+```bash
+npm run verify     # every gate, one report, one exit code
+```
+
+1. Run it after every edit, before saying the task is done.
+2. Fix **only** the error the report names. Do not rewrite the file to make it
+   pass — a check that fails on line 12 is a line 12 problem.
+3. **At most two attempts.** If the same error survives the second attempt,
+   revert the change and hand the report back with what you tried.
+4. A warning may stay only when you can justify it in one sentence.
+
+`npm run verify` is `flet-box verify`: it parses every module first (`node
+--check`, the parser the runtime uses — a missing `)` is reported as
+`file:line:column` with the offending line, a caret under the character and a
+hint), then runs the anti-hallucination gate (invented widgets, positional
+arguments, foreign imports, broken imports), the type gate (the app's own
+`jsconfig.json` through TypeScript: a widget declared as a bare `HTMLElement`
+makes the documented `widget.update()` an error, and a prop the declaration
+forgot is one too), the design gate (tokens, the scale,
+tap targets, labels, contrast), the structural gate (a cycle between two of the
+app's own modules, a module outside the project's folders, markup written by
+hand) and the prop contract (a prop the widget reads but nothing declares), and
+prints one report with one exit code. A project that declares its own `test`,
+`test:browser` or `test:visual` script gets those run too; a generated app
+declares none, so that step is skipped there. `flet-box verify --watch` re-runs
+the fast gates on every edit, and `flet-box run --verify` does the same while the
+dev server runs.
+
+A mistyped name is mechanical, not creative: `npm run fix` rewrites what it
+can prove (`chilldren` → `children`, `bgColr` → `bgColor`, a relative path that
+does not resolve) and leaves anything ambiguous for you to decide. Read the
+diff.
+
+Lost before the first gate answers? `flet-box report` names every file of the
+project with its verdict and a ranked next step, and `flet-box tools` is the
+catalogue that maps a question to the command. Both read; neither repairs, and
+neither appends a metrics row.
+
+Then look at it: `npm run dev` and use the screen. A green report proves the
+code is legal, not that it is right.
+
+---
+
+## 5. The surgical protocol
+
+The report names a line. The edit touches that line, and nothing else.
+
+1. **Fix only what is named.** Every finding carries a file, a line and a code.
+   Change that line. A file that fails on three lines gets three edits — not a
+   rewrite of the file, and never a rewrite of the screen around it.
+2. **Let the tool repair first.** A mistyped prop, a wrong relative path and a
+   missing import are mechanical, and the repair is the tool's job:
+   `npm run verify -- --fix` rewrites what it can prove and re-runs the gates
+   on the result. Read the diff it prints before you write anything.
+3. **Do not widen the blast radius.** No reformatting, no renaming, no
+   "while I was here". A diff that touches a line the report did not name is a
+   diff you have to justify — and usually it is one you should not make.
+4. **A new finding is a decision, not noise.** If the fix makes a gate report
+   somewhere else, that is the next thing to look at. Do not silence it by
+   loosening the value that caused it.
+5. **Two attempts, then revert.** The same error surviving the second attempt
+   means the diagnosis was wrong, not that the third attempt will be luckier.
+   Revert and hand back the report with what you tried.
+6. **Say what you did not touch.** The handoff names the files you changed and
+   the ones the report named but you left alone, with one sentence of why.
+
+---
+
+## 6. What gets rejected, and why
+
+A change comes back when it breaks one of these. Each row names who says so,
+so "it was rejected" is never a matter of taste.
+
+| It comes back when | Who says so | What to write instead |
+| --- | --- | --- |
+| A widget, a prop or an export that does not exist | `UNKNOWN_EXPORT`, `UNKNOWN_PROP` | look it up in the cheatsheet; if it is not there, ask |
+| A positional call | `POSITIONAL_ARG` | `Text({ text: "Hi" })` |
+| An import that does not resolve | `MODULE_NOT_FOUND`, `MISSING_EXPORT` | `npm run fix`, or the path the file really has |
+| A prop the widget reads but no type declares | `INVENTED_PROP` | declare it, so an editor finds it |
+| A prop that no type declares and nothing reads | `DEAD_PROP` | wire it in the widget, or drop the declaration |
+| A hex where a token belongs | `RAW_COLOR` | `colors.primary` |
+| A length that is not on the scale | `OFF_SCALE_SPACING`, `OFF_SCALE_RADIUS`, `OFF_SCALE_TYPE` | the number the scale holds |
+| A control smaller than the tap target | `SMALL_TAP_TARGET` | `height: 40` |
+| A control with no name | `UNLABELED_FIELD`, `ICON_ONLY_CONTROL` | a label, or an `aria-label` |
+| A cycle, a file from outside the project, markup written by hand | `CIRCULAR_IMPORT`, `SOURCE_OUTSIDE_ROOT`, `HAND_WRITTEN_DOM` | import the file that owns it; build with widgets |
+| A rename or a removal with no deprecation | a review | keep the old name working, mark it, write the "from X to Y" line |
+| A diff that touches lines the report did not name | a review | revert the extra lines |
+| A claim with no measurement | a review | measure it, or say that it is unmeasured |
+| A baseline moved to quiet a gate | a review | a baseline moves when the framework moves |
+
+The last four rows are not gates: no tool can prove them, and a reader has to.
+A machine can say that a prop does not exist; only a person can say that a
+diff does more than the task asked.
+
+And two things are **not** a reason to send anything back: a warning you can
+justify in one sentence, and a fix that lands exactly on the line the report
+named. Both are in the two sections above.
+
+---
+
+## 7. The log of what keeps coming back
+
+Every `npm run verify` run appends a row to `.fletbox/metrics/generations.md` —
+when it happened, whether the gates were green, which gates failed, which codes
+they reported. **Every** run, green or not: a log that keeps only the
+successes cannot tell a correction from a first try.
+
+```bash
+npm run metrics      # the north metric and the failures that recur
+```
+
+A **generation** is a run of failing rows closed by the first green one, and the
+**north metric** is the share of generations whose *first* run was green — the
+share of code that passed the gate with no correction at all. That is the number
+worth raising, and it moves only when the code changes, not when the report gets
+softer.
+
+The same command prints the three failures that recur most often and the rule
+each one should belong to. **That list is the loop.** A code that keeps coming
+back and has no rule behind it is a rule that has not been written yet — and the
+command fails when it finds one, so the gap cannot be forgotten.
+
+A code that keeps coming back *with* a rule behind it is a different problem,
+and the command names it: the rule is not landing. That is a stronger rule, a
+stronger place to put it, or an agent that did not read it.
+
+So when you see the same code twice in the log, do not only fix the line it
+names: write the rule that would have prevented it, where it belongs (the
+design skill, the rules skill, or the gate itself), and prove it with a check
+that fails without the fix.
+
+---
+
+## 8. If you are working on the framework itself
+
+`AGENTS.md` in the framework root is the contract for engine work: one
+rendering engine, the rem contract, the widget structure, the gates that guard
+each of them. This file still applies to anything you write there: real APIs
+only, tokens only, no new rendering system, and every rule you break gets a
+guard that fails before the fix.
+
+When you find a defect in the framework, fix it **upstream** and prove it with
+a check that fails without the fix. Never patch `node_modules`.

package/CONTRIBUTING.md

@@ -0,0 +1,238 @@
+# Contributing to FletBox
+
+FletBox is a vanilla-JS UI framework: ESM only, zero runtime dependencies, no
+build step. This file is the map of the repository for whoever adds code to it.
+
+Two contracts live next to it, and they are not the same document:
+
+| File | It is the contract for |
+| --- | --- |
+| [AGENTS.md](AGENTS.md) | **maintaining the framework** — the architecture, the rem contract, the widget structure, the gates that guard each of them |
+| [AGENTS_FOR_CODE_GEN.md](AGENTS_FOR_CODE_GEN.md) | **producing code with it** — what may be written, what gets rejected, how the work is proved. It ships inside every app `flet-box create` builds |
+
+## The branch, the commits, the release
+
+The work happens on `refactory`. A commit message is one line: a conventional
+prefix, a scope, an imperative subject — `feat(theme): …`, `fix(stack): …`,
+`docs(widget): …`, `chore(release): …`. The body carries the *why* when the
+subject cannot: the measurement that decided a value, the defect a fix closes.
+
+Never publish by hand. `npm run release -- --patch` bumps the version,
+rebuilds the bundle, commits and tags; CI publishes the tag. `npm publish` in a
+terminal is the one command that must never appear in a handoff.
+
+## The gates
+
+| Command | What it proves | When |
+| --- | --- | --- |
+| `npm run verify` | one report, one exit code: every module is parsed first, then the anti-hallucination gate, the design gate, the structural gate and the prop contract run, and then the project's own suites (`test`, `test:browser`, `test:visual`) | after every edit |
+| `npm test` | the static checkers: the widget contract, the scale, the shared helpers, accessibility, the error boundary, the API contract, the bundle budget, the image tooling, the docs, the skills, **the gates' own selftest** and the snippets | before you commit |
+| `npm run selftest` | the gates bite: each of the seven gates runs on a clean fixture and on one with a known defect, and must name the exact code on the exact line | after changing a checker |
+| `npm run test:browser` | the behavioural harnesses in `tests/`, driven in a real Chrome | when the change touches runtime behaviour |
+| `npm run test:visual` | the gallery measured in light and dark against `scripts/visual-baseline.json` | when the change touches how a widget paints |
+| `npm run metrics` | the north metric: the share of generations whose first run was already green | to know whether the rules are landing |
+
+CI runs the first three on every pull request and on every push to `refactory`
+and `main`, as three parallel jobs. Nothing is published from a pull request:
+the publish workflow reacts to a version tag and to nothing else.
+
+## Prove it twice
+
+Every rule in this repository is proven twice: once by breaking it and once by
+obeying it. A check that only proves the happy path proves nothing — a gate
+that stopped matching would report a clean repository forever. So a new gate
+arrives with a mutation that makes it fail and a case that makes it pass, and
+`npm test` is where both live.
+
+The same is true of a baseline. `scripts/visual-baseline.json` and
+`scripts/bundle-budget.json` are promises about how the framework paints and
+how heavy it is. They move when the framework moves, never to quiet a gate. A
+baseline that shrinks is a good day; a baseline that moves because a
+measurement was wrong is a defect.
+
+## What gets rejected
+
+The full list is in
+[AGENTS_FOR_CODE_GEN.md §6](AGENTS_FOR_CODE_GEN.md#6-what-gets-rejected-and-why),
+and it is short: a widget or a prop that does not exist, a positional call, an
+import that does not resolve, a hex where a token belongs, a length off the
+scale, a tap target under 40, a control with no name, a cycle, markup written
+by hand, an API change without a deprecation, a diff wider than the task, and
+a claim with no measurement.
+
+## Fix it upstream
+
+When an app cannot do what the contract says, the defect is in the framework.
+Fix it here, prove it with a check that fails without the fix, and never patch
+`node_modules`.
+
+## Project areas
+
+```text
+src/core/           Runtime, mounting, PWA, and HMR
+src/widgets/        UI widgets
+src/widget-factory/ Widget creation and prop processing
+src/navigations/    Scaffold, drawer, tabs, and router
+src/services/       Browser storage and HTTP helpers
+src/tools/          State and general-purpose tools
+src/utils/          Themes, parsing, effects, units, and validation
+src/helpers/        Shared helpers — one home per behaviour, and no imports
+bin/                CLI and project generators
+scripts/            The static checkers and the browser drivers (dev only)
+skills/             What the framework knows about designing an app
+tests/              The browser harnesses
+docs/               User and API documentation
+```
+
+## Before changing code
+
+1. Read the owning module and its nearest tests or examples.
+2. Check `src/index.js` to understand the public export.
+3. Check `src/index.d.ts` when changing public types.
+4. Search for existing aliases and related widgets.
+5. Keep unrelated refactors out of the change.
+
+## Adding a widget
+
+A widget should normally include:
+
+- A file under `src/widgets/`.
+- An export in `src/widgets/index.js`.
+- An export in `src/index.js`.
+- A prop interface and function declaration in `src/index.d.ts`.
+- Basic, everyday, and full examples.
+- A documentation page under `docs/widget/`.
+- Accessibility notes when it is interactive.
+- Cleanup for timers, listeners, observers, and subscriptions.
+
+Use the existing `WidgetFactory` patterns instead of creating a second
+rendering system, and follow
+[docs/guides/widget-structure.md](docs/guides/widget-structure.md): one factory
+root, `widgetName` on it, `composeUpdate()` instead of overwriting
+`container.update`, and every resource released through an idempotent
+`onUnmount` disposer.
+
+## Adding a prop
+
+When adding a public prop:
+
+1. Implement it in the widget.
+2. Add its TypeScript type.
+3. Add its default value and behavior documentation.
+4. Add an example that proves the behavior.
+5. Check whether it should have a friendly alias.
+6. Test both the preferred name and aliases when aliases are intentional.
+
+FletBox supports developer-friendly aliases, but each alias must have one
+clear meaning. **An alias is a feature, not a duplicate**: never "dedupe" two
+names that both work.
+
+## The generated files — never hand-edited
+
+| File | Regenerate it with |
+| --- | --- |
+| `docs/widget/*.md` | `python3 scripts/generate_widget_docs.py` |
+| `tools/snippets-creator-flet-box/*.json` | `python3 tools/snippets-creator-flet-box/build_snippets.py` |
+| `.fletbox/api/cheatsheet.md` and `api.json` | `flet-box check-api --emit-api`, `flet-box unpack --all --md` |
+| `www/` and `dist/` | `npm run build` |
+
+The shape of a widget page is the generator's, not yours: the page is built
+from `src/index.d.ts` and the curated examples in `scripts/_docdata/`.
+
+## Runtime and types must agree
+
+A public API is not complete until these three surfaces agree:
+
+```text
+runtime implementation
+src/index.js exports
+src/index.d.ts declarations
+```
+
+If a function is declared but not exported, or exported but not typed, do not
+ship it as stable: fix the source of truth. `scripts/check-api-surface.mjs`
+enforces it — it imports `src/index.js` for real, so it fails when a runtime
+export has no declaration, when a declared value does not exist at runtime,
+when an `interface`/`type` is not `export`ed (a consumer could not
+`import type` it), or when the barrel re-exports a name that no longer
+exists. It also fails when the package stops being importable in Node, so
+never touch `window` / `document` at module scope — guard with
+`typeof window !== "undefined"`.
+
+## Deprecating a prop
+
+A rename is not a breaking change, and it is not a silent one either. It has
+five parts, and they belong in the same change:
+
+1. The new name is declared and documented **first**.
+2. The old name keeps working, marked `@deprecated` in `src/index.d.ts`.
+3. The old name lands in `src/widget-factory/deprecations.js` — the one table
+   the guide, the codemod and the contract test all read.
+4. The old name is listed in [the migration guide](docs/guides/migration.md) as
+   a "de X a Y" row, under the version that renamed it.
+5. The old name is removed in the next **major**, and that major's section says
+   so.
+
+`scripts/check-migrations.mjs` proves the four surfaces agree, and
+`flet-box release --major` refuses to publish a version the guide does not
+cover. The codemod that applies the table is `flet-box audit-fix --only
+migrations`: it renames a key only when the widget declares both names and the
+call does not already carry the new one, and it removes a key the table marks as
+removed. Anything it cannot prove stays untouched, under "Left for you to
+decide".
+
+The guide is a chapter of the book, so a rename also touches the book's
+indexes and the neighbouring chapter's links.
+
+## Cleanup rules
+
+Components that register resources must release them:
+
+- `window` and `document` listeners.
+- Timers and animation frames.
+- `ResizeObserver` and `MutationObserver`.
+- Router subscriptions.
+- Storage subscriptions.
+- WebSocket connections.
+
+Use the widget cleanup lifecycle when available.
+
+## Validation checklist
+
+Before you open the pull request:
+
+```bash
+npm run verify
+npm test
+npm run test:browser
+node --check path/to/changed-file.js
+python3 -m py_compile scripts/generate_widget_docs.py
+```
+
+`npm run test:browser` drives the harnesses in `tests/` in a real Chrome:
+
+- `/tests/index.html` — the widget-factory regression contract
+- `/tests/smoke.html` — instantiates every widget
+- `/tests/motion.html` — the motion contract
+- `/tests/a11y.html` — the accessibility contract
+- `/tests/regression.html` — a guard for every bug this repository has fixed
+- `/tests/errorboundary.html` — a throw never takes the screen with it
+- `/tests/doccheck.html` and `/tests/doccheck-all.html` — documented behavior
+
+Each harness writes a global (`window.__TESTS`, `window.__SMOKE`,
+`window.__MOTION`, `window.__A11Y`, `window.__REGRESSION`) and must pass with 0
+failures. Serve the repo with `npm run dev` to open one by hand.
+
+## Pull request guidance
+
+A good pull request explains:
+
+- What user problem it solves.
+- Which files changed.
+- Which public API changed.
+- Whether types and docs were updated.
+- Which commands or tests were run.
+- Any remaining compatibility or migration concern.
+
+Avoid committing generated output, secrets, local databases, APKs, logs, or
+credentials.

package/README.md

@@ -54,7 +54,7 @@ straight from the registry, and the project it writes declares `flet-box` as a
 normal dependency.
 
 Cloning the repository and `npm link`ing it is still how you *develop the framework
-itself* — see [CONTRIBUTING](docs/CONTRIBUTING.md).
+itself* — see [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Quick start
 
@@ -173,7 +173,7 @@ And the book itself is an app: **[`flet-box-docs`](https://www.npmjs.com/package
 - [SQLite and the API server](docs/server/data-services.md) — where your data lives + a full SQLite API example
 - [Mobile and platforms](docs/guides/mobile-and-platforms.md) — Android, iOS, PWA, and desktop
 - [Architecture](docs/arquitectura.md) — the widget contract and the single rendering engine
-- [Contributing](docs/CONTRIBUTING.md) — how to add code and docs
+- [Contributing](CONTRIBUTING.md) — how to add code and docs
 
 ## Support & sponsorship
 

package/bin/cli.js

@@ -15,6 +15,10 @@ import path from "path";
 import { createProject } from "./commands/create.js";
 import { checkApi } from "./commands/checkApi.js";
 import { checkUi } from "./commands/checkUi.js";
+import { verify, watchVerify, formatReport } from "./commands/verify.js";
+import { metrics } from "./commands/metrics.js";
+import { report } from "./commands/report.js";
+import { tools } from "./commands/tools.js";
 import { auditFix } from "./commands/auditFix.js";
 import { toPng } from "./commands/toPng.js";
 import { images } from "./commands/images.js";
@@ -91,8 +95,22 @@ ${cmd("check-ui", "Clean-UI gate: tokens, 8-based scale, tap targets, WCAG contr
 ${cmd("   └─ --tokens", "print the measured contrast of every color token")}
 ${cmd("   └─ --strict", "fail on contrast warnings too")}
 ${cmd("   └─ alias", "ui | checkUi")}
+${cmd("verify", "Every gate at once: one report, one exit code")}
+${cmd("   └─ --only <gate>", "syntax | api | types | ui | structure | surface | tests")}
+${cmd("   └─ --no-tests", "the static gates only; the project's suites run alone")}
+${cmd("   └─ --fix", "the mechanical repair first, then the gates")}
+${cmd("   └─ --json", "the report as data")}
+${cmd("   └─ alias", "check-all")}
+${cmd("report", "Read-only diagnosis: a verdict per file and what to do next")}
+${cmd("   └─ --json | --md", "the same facts as data or Markdown")}
+${cmd("   └─ --html [--out <file>]", "one self-contained page (.fletbox/reports/report.html)")}
+${cmd("   └─ --tests", "also run the project's own suites")}
+${cmd("tools [--emit]", "The read-only toolkit: one question, one command")}
+${cmd("mcp", "Serve that toolkit over MCP stdio (read-only)")}
+${cmd("metrics", "The north metric: code that passed with no correction")}
+${cmd("   └─ --log <file>", "read another project's log")}
 ${cmd("audit-fix", "Rewrite broken imports, missing imports and misspelled props")}
-${cmd("   └─ --only imports|props", "run one repair instead of both")}
+${cmd("   └─ --only imports|props|migrations", "run one repair instead of the others")}
 ${cmd("   └─ alias", "fix-imports | fix-path-imports | auditFix")}
 ${cmd("to-png [dir]", "Convert JPEG/BMP/GIF images to PNG, no dependencies")}
 ${cmd("   └─ --replace", "remove each source after its PNG was written and read back")}
@@ -124,6 +142,7 @@ ${cmd("--version | --help", "Version and this help")}
 ${section("⚙️", "OPTIONS")}
 ${opt("--port <n>, -p <n>", "Port (default 8000) — asked if not provided")}
 ${opt("--hot", "Hot reload with run")}
+${opt("--verify", "Run the gates on every edit while the server runs")}
 ${opt("--quiet", "No request logging")}
 ${opt("--dry-run | --list", "kill-server: just list, do not kill")}
 
@@ -167,6 +186,7 @@ const parseFlags = () => {
     logRequests: true,
     hot: false,
     dryRun: false,
+    verify: false,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -187,6 +207,8 @@ const parseFlags = () => {
       flags.logRequests = false;
     } else if (arg === "--hot" || arg === "--hot-reload") {
       flags.hot = true;
+    } else if (arg === "--verify") {
+      flags.verify = true;
     } else if (arg === "--dry-run" || arg === "--list" || arg === "--check") {
       flags.dryRun = true;
     }
@@ -242,6 +264,24 @@ async function main() {
     switch (command) {
       case "create":
       case "new":
+        // `flet-box create --help` must print the help, not scaffold a folder
+        // named `--help`: that stray clone lands inside the project and the
+        // structure gate starts reporting SOURCE_OUTSIDE_ROOT for every module
+        // in it.
+        if (projectName && projectName.startsWith("-")) {
+          if (projectName === "--help" || projectName === "-h") {
+            showHelp();
+            break;
+          }
+          console.error(c("red", `❌ Unknown option: ${projectName}`));
+          console.log(
+            c(
+              "gray",
+              "Usage: flet-box create <project-name> [--adaptive|--blank|--full|--sidebar|--template <name>|--repo user/repo]",
+            ),
+          );
+          process.exit(1);
+        }
         if (!projectName) {
           console.error(c("red", "❌ Error: Project name required"));
           console.log(
@@ -328,6 +368,40 @@ async function main() {
         break;
       }
 
+      case "verify":
+      case "check-all": {
+        const { exitCode } = await verify(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "metrics": {
+        const { exitCode } = await metrics(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "report": {
+        const { exitCode } = await report(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "tools":
+      case "toolkit": {
+        const { exitCode } = await tools(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "mcp": {
+        // Lazy: the stdio server takes over the process, and nothing else in
+        // the CLI should pay for loading it.
+        const { serveStdio } = await import("./mcp.js");
+        serveStdio();
+        break;
+      }
+
       case "audit-fix":
       case "auditFix":
       case "fix-imports":
@@ -410,6 +484,19 @@ async function main() {
         // which are devDependencies: a consumer installing `flet-box` from npm
         // has neither, so loading them at module scope would break every CLI
         // command for them. Import them when a server is actually started.
+        if (flags.verify) {
+          console.log(
+            c("dim", "🔎 verify is watching src/ — every edit is checked against the gates"),
+          );
+          watchVerify({
+            root: process.cwd(),
+            onReport: (report) => {
+              console.log("");
+              for (const line of formatReport(report)) console.log(line);
+              console.log("");
+            },
+          });
+        }
         await (await import("./commands/runServer.js")).runDevServer({
           spaMode: false,
           hotReload: flags.hot,