@zerotal/arch 1.14.1 → 1.14.3

package/docs/about.md

@@ -84,7 +84,7 @@ bun create zerotal my-app     # choose: API, Flow, React, Vue, or Minimal
 cd my-app
 cp .env.example .env         # APP_KEY is pre-generated for you
 bun zt migrate              # create the database schema (API template)
-bun run dev                  # dev server + hot reload at http://localhost:3000
+bun zt dev                  # dev server + hot reload at http://localhost:3000
 ```
 
 The scaffolder writes a fresh `APP_KEY` into `.env.example` and installs
@@ -95,7 +95,7 @@ dependencies. Pick a template at the prompt:
 - **React** / **Vue** — Inertia SPA (see [Inertia](#inertia-react-vue-spa)).
 - **Minimal** — one page with JSX views on the bare framework.
 
-There's **no build step**: `bun run dev` starts the server, `bun test` runs the suite,
+There's **no build step**: `bun zt dev` starts the server, `bun test` runs the suite,
 `bun run typecheck` type-checks. More in [Getting Started](/docs/getting-started).
 
 ## The shape of an app
@@ -631,7 +631,7 @@ bun zt migrate:rollback              # roll back last batch
 bun zt migrate:fresh                 # drop all + re-migrate
 bun zt key:generate                  # fresh APP_KEY
 bun zt queue:work                    # start the queue worker
-bun zt serve --dev                   # dev server (aliased by `bun run dev`)
+bun zt dev                           # dev server, hot reload (also `bun run dev`)
 bun zt list                          # every available command
 ```
 
@@ -658,7 +658,7 @@ The [README](../README.md) has a package-by-package table with links.
 
 - **The `zt` CLI is your control panel.** `bun zt list` shows everything —
   scaffolding, migrations, the dev server, the worker, and tests all run through it.
-- **No build, ever.** `bun run dev` / `bun test` / `bun run typecheck`. No compile
+- **No build, ever.** `bun zt dev` / `bun test` / `bun run typecheck`. No compile
   step to remember.
 - **Starters are the fastest way in.** `bun create zerotal my-app` scaffolds a working
   app from one of six starters — `api`, `admin`, `flow`, `react`, `vue`, or `minimal`.

package/docs/assets.md

@@ -12,20 +12,20 @@ View, Inertia) has its own pipeline and hot-reload behaviour; all three use
 
 Asset compilation is built into the framework — there's no package to install or
 provider to register for the pipeline itself. You only add Tailwind and wire up a
-static route, then `bun zt serve --dev` handles build-and-reload for you.
+static route, then `bun zt dev` handles build-and-reload for you.
 
 > **Note** — Projects ship a `zt.ts` entry and a `zt` package script,
-> so commands are written `bun zt <command>` (e.g. `bun zt serve --dev`).
+> so commands are written `bun zt <command>` (e.g. `bun zt dev`).
 
 ## Getting Started
 
 Asset building is part of `@zerotal/core` — nothing to install and no provider
-to register. `bun zt serve --dev` builds on change, and `bun zt css:build`
+to register. `bun zt dev` builds on change, and `bun zt css:build`
 produces a production bundle:
 
 ```bash
 # in your project root
-bun zt serve --dev     # watch and rebuild
+bun zt dev     # watch and rebuild
 bun zt css:build       # one production build
 ```
 
@@ -39,7 +39,7 @@ Pick by stack — the dev server runs the right pipeline automatically:
   production. Dev rebuilds are wired up by `FlowProvider`.
 - **Inertia** (React or Vue SPA, JS + CSS bundle): `bun zt inertia:build` for
   production. Dev rebuilds are wired up by `InertiaProvider`.
-- **Any stack, development**: `bun zt serve --dev` — initial build, file watch,
+- **Any stack, development**: `bun zt dev` — initial build, file watch,
   rebuild on save, and a browser reload over WebSocket.
 
 ## Tailwind CSS
@@ -113,7 +113,7 @@ returned HTML:
 
 ```bash
 # in your project root
-bun zt serve --dev
+bun zt dev
 ```
 
 When `resources/css/app.css` exists, `FlowProvider.onBooted()` registers a
@@ -296,7 +296,7 @@ Inertia Vue plugin so `.vue` single-file components compile.
 
 ```bash
 # in your project root
-bun zt serve --dev
+bun zt dev
 ```
 
 `InertiaProvider.onBooted()` registers Inertia's build routine under its own
@@ -409,14 +409,14 @@ stylesheet stays small and the fonts load in parallel. The other accepted values
 
 ## Hot reload
 
-Both pipelines above are driven by the same dev process. `bun zt serve --dev`
+Both pipelines above are driven by the same dev process. `bun zt dev`
 builds once, spawns the server as a child process, and watches the filesystem;
 what happens on a change depends on which directory the change landed in:
 
 ```text
-# bun zt serve --dev process model
+# bun zt dev process model
 ┌──────────────────────────────────────────────────────┐
-│  bun zt serve --dev                                 │
+│  bun zt dev                                 │
 │                                                      │
 │  Process 1: DevOrchestrator                          │
 │  ├─ Initial build (CSS or JS+CSS)                    │
@@ -699,7 +699,7 @@ test("a stale bundle is told to reload", async () => {
 | Command                             | Effect                                          |
 | ----------------------------------- | ----------------------------------------------- |
 | `bun zt serve`                      | Serve the app; assets are built once at boot    |
-| `bun zt serve --dev`                | Dev server with hot reload                      |
+| `bun zt dev`                        | Dev server with hot reload                      |
 | `bun zt css:build`                  | Production CSS build (Flow/View)                |
 | `bun zt inertia:build`              | Development JS+CSS build (Inertia)              |
 | `bun zt inertia:build --production` | Production JS+CSS build (Inertia)               |

package/docs/changelog.md

@@ -27,6 +27,75 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
 
+## 1.14.3 — 2026-09-01
+
+Consistency pass on the documentation, and two bugs it uncovered.
+
+Everything is written `bun zt <command>` now. The scaffold still adds a `dev` script, so
+`bun run dev` keeps working — the docs simply lead with the form that is the same in every
+project, including one that never ran the scaffolder.
+
+### Fixed
+
+- **Twenty pages taught a retired command.** `serve --dev` was retired in
+  [1.13.0](#1130--2026-08-31), and that release updated the runner, the codemod,
+  `docs/commands.md` and `docs/upgrade.md` — leaving the form in the getting-started guide,
+  the assets guide, two Flow pages, the logger page, and both READMEs. For three weeks the
+  front door told newcomers to run a command that exits 1.
+
+  A gate now scans every page against the upgrade codemods' own list of retired forms, so
+  what the docs teach cannot drift from what the framework accepts. Only _shipped_
+  retirements count: a codemod for 2.0 describes a rename that has not happened, and
+  flagging correct prose is how a gate becomes something people add exclusions to rather
+  than read.
+
+- **`zt upgrade` never offered the 1.13.0 migrations.** The `deprecated-aliases` codemod
+  bundled `serve --dev` and `routes:types` — retired in 1.13.0 — with the `BaseModel`
+  rename, which has not shipped and is scheduled for 2.0. A codemod carries one version, so
+  it took the later one: `zt upgrade --to 1.13.0` selected **nothing**, and the migration
+  for the release that broke `serve --dev` was unreachable by every app crossing it.
+
+  Split into `deprecated-aliases` at 1.13.0 and `base-model-rename` at 2.0.0. An app moving
+  to any 1.13+ release gets the command rewrites; one crossing to 2.0 no longer has
+  `BaseModel` renamed as a side effect of a command alias.
+
+  Found by the new gate, which flagged `extends BaseModel` in the ORM docs — correct prose,
+  and the reason it was reported was that the codemod claimed a rename that had not
+  happened.
+
+## 1.14.2 — 2026-09-01
+
+**`bun run dev` was broken in every app scaffolded since 1.13.0.** Take this one.
+
+Found by starting the adoption release the obvious way — scaffolding a fresh app and
+walking the first-run path as a newcomer would, rather than reasoning about it.
+
+### Fixed
+
+- **The scaffold templates shipped a retired command.** Every template's `package.json`
+  carried `"dev": "bun zt.ts serve --dev"`, and `serve --dev` was retired in
+  [1.13.0](#1130--2026-08-31) — deliberately failing loudly rather than silently starting a
+  plain server with no watcher. So the first command a new user runs exited 1 and told them
+  to use something else.
+
+  Retiring an alias meant updating the runner, the documentation and the `zt upgrade`
+  codemod. It did not occur to me to update the thing that _writes new apps_, which is the
+  one place a retired form is guaranteed to keep appearing.
+
+  A test now checks the scaffolder against the codemod's own list of retired forms, so what
+  generates apps cannot fall behind what migrates them. It is driven by the codemod rather
+  than a second list, because two lists disagree.
+
+- **`zt upgrade` did not rewrite `zt.ts serve --dev` either.** The codemod anchored on `zt`
+  followed by whitespace, matching `zt serve --dev` and missing `bun zt.ts serve --dev` —
+  the form in every scaffolded `package.json`. So an app running `zt upgrade` to migrate off
+  the alias was told there was nothing to do, on the file that needed it most.
+
+  Worth naming as its own failure: the first version of the new scaffolder test passed with
+  the bug deliberately planted, because it was driven by that same pattern. A gate is only
+  worth what it catches, and the way to know is to break the thing on purpose and watch it
+  fail.
+
 ## 1.14.1 — 2026-09-01
 
 Clearing the deferred list. Three of the four are fixed; the other two were sized and moved

package/docs/commands.md

@@ -181,7 +181,7 @@ that cannot cost you anything.
 Nothing prompts when there is no terminal to answer, which covers CI, containers,
 and anything reading `serve`'s output from a pipe. There it fails with the same
 explanation, so use `--force` or `--auto-port` to say up front which way you want
-it decided. Both flags work with a plain `serve` and with `serve --dev`.
+it decided. Both flags work with `serve` and with `dev`.
 
 The dev server is a special case worth knowing about: on every restart it waits a
 few seconds for its own previous process to let go of the socket rather than
@@ -192,8 +192,13 @@ is about to free itself anyway.
 
 `bun zt dev` starts the server, the file watcher, and every process a provider or
 your app registered — a queue worker, a type-checker, a Stripe listener — in one
-terminal, each in its own tab. It is `serve --dev` with those extra tabs and the
-keys to drive them, so anything true of one is true of the other.
+terminal, each in its own tab. It subclasses `serve`, so it is the same supervisor,
+the same port resolution and the same restart behaviour, plus the flags that only
+make sense with a deck on screen — anything true of `serve` is true of it.
+
+`serve --dev` was the old spelling and was retired in 1.13.0; it now fails with a
+message rather than starting a plain server. The scaffold's `dev` script runs this,
+so `bun run dev` and `bun zt dev` are the same thing.
 
 An app with a queue no longer needs a second terminal:
 

package/docs/flow/index.md

@@ -46,7 +46,7 @@ Registering the provider switches on the following (in lifecycle order):
 
 - `onRegister` — registers the `Router.flow()` macro and the file-route resolver so Flow pages can be declared and auto-discovered.
 - `onBooting` — builds the client runtime bundle (Alpine + the Flow bridge) and mounts the routes under `/__flow` (the WebSocket endpoint, `runtime.js`, the upload endpoint, and the session-relay endpoint).
-- `onBooted` — wires `serve --dev` rebuild hooks for `resources/css/app.css` and `resources/js/app.js` (a no-op when those entry points are absent).
+- `onBooted` — wires `zt dev` rebuild hooks for `resources/css/app.css` and `resources/js/app.js` (a no-op when those entry points are absent).
 - `onStarting` — AOT-compiles and validates every registered page's `render()` method.
 
 ### Configuration

package/docs/flow/performance.md

@@ -186,7 +186,7 @@ The cache is small (a handful of recent pages) and short-lived, same-origin only
 
 ### Fast refresh in dev
 
-When you edit a component under `serve --dev`, the server restarts (quickly) and the client **re-renders each mounted component from its held snapshot with the new code — keeping its state**, instead of a full reload that would reset everything. Because component state is a signed snapshot and your `APP_KEY` doesn't change across a restart, that snapshot still verifies against the fresh server; the browser also refetches the stylesheet, so a newly-used Tailwind class shows up too. Increment a counter, tweak its template, save — the counter keeps its value and the change appears in place.
+When you edit a component under `zt dev`, the server restarts (quickly) and the client **re-renders each mounted component from its held snapshot with the new code — keeping its state**, instead of a full reload that would reset everything. Because component state is a signed snapshot and your `APP_KEY` doesn't change across a restart, that snapshot still verifies against the fresh server; the browser also refetches the stylesheet, so a newly-used Tailwind class shows up too. Increment a counter, tweak its template, save — the counter keeps its value and the change appears in place.
 
 Two things to know:
 
@@ -199,7 +199,7 @@ Two things to know:
 
 ### Time-travel devtools
 
-Because the engine signs and delta-encodes the **full component state** on every round-trip, the client already holds an exact, verifiable history of everything each component has been. Under `serve --dev`, Flow records that stream: one frame per applied patch,
+Because the engine signs and delta-encodes the **full component state** on every round-trip, the client already holds an exact, verifiable history of everything each component has been. Under `zt dev`, Flow records that stream: one frame per applied patch,
 plus the initial mount. You can then **scrub back to any frame**.
 
 Jumping re-applies that frame's snapshot _and_ its HTML to the live component, so
@@ -225,7 +225,7 @@ use. Recording is capped to the most recent frames and runs **only** under the d
 
 ### Dev error overlay
 
-When an **unexpected** error is thrown, `serve --dev` shows a **full-screen
+When an **unexpected** error is thrown, `zt dev` shows a **full-screen
 overlay** carrying the error class, message, and stack. It covers both a server
 action and the initial `GET` render (`onMount` / `render`).
 

package/docs/getting-started.md

@@ -193,11 +193,14 @@ bun zt migrate
 
 ```bash
 # in your project root
-bun dev          # → bun zt serve --dev
+bun zt dev
 ```
 
+Every command in these docs is written `bun zt <command>`. The scaffold also adds a
+`dev` script, so `bun run dev` does the same thing — reach for whichever you prefer.
+
 Your app is now running at **http://localhost:3000** with hot reload enabled —
-`--dev` watches your files and hot-swaps routes without dropping connections. The
+`dev` watches your files and hot-swaps routes without dropping connections. The
 generated `package.json` also gives you `bun start` (production serve) and
 `bun test`.
 

package/docs/logger.md

@@ -292,7 +292,7 @@ level you can filter and in a file you can ship. Nothing writes to the terminal
 behind the logger's back, which means a `daily` channel captures the framework's
 own account of a boot, not just your application's.
 
-The one deliberate exception is the CLI itself. `serve --dev`'s banner and its
+The one deliberate exception is the CLI itself. `zt dev`'s banner and its
 `[zerotal:dev]` build/restart lines come from the supervisor process that watches
 your files, not from the application, and they are interactive terminal output
 rather than a record of anything. They stay on stdout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.14.1",
+  "version": "1.14.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.14.1"
+    "@zerotal/core": "1.14.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.14.1"
+    "@zerotal/orm": "1.14.3"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [