@zerotal/arch 1.15.2 → 1.15.3

package/docs/about.md

@@ -82,12 +82,11 @@ Add `FlowProvider`. The provider list is the feature manifest for your app.
 # in your project's parent directory
 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 zt dev                  # dev server + hot reload at http://localhost:3000
 ```
 
-The scaffolder writes a fresh `APP_KEY` into `.env.example` and installs
+The scaffolder writes a fresh `APP_KEY` into `.env` and installs
 dependencies. Pick a template at the prompt:
 
 - **API** — JSON REST API (core + ORM + auth + validation + testing). The default.

package/docs/changelog.md

@@ -27,6 +27,50 @@ 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.15.3 — 2026-10-23
+
+A patch for the first ten minutes with Zerotal. Scaffolding each starter, following its README
+and running it, the way a newcomer would, turned up four things that did not work as written,
+and a fifth where two guides told you to throw away your own key. All five are fixed here.
+
+Nothing here breaks. Safe to take directly.
+
+### Fixed
+
+- **A new app's README now says what it takes to run** (`create-zerotal`). The scaffolder
+  printed `bun zt migrate` (or `bun zt db:seed` for the admin starter) before `bun zt dev`,
+  while every README said `bun install` then `bun run dev`. The README is the copy that stays,
+  and following it on the API, Flow, React or Vue starter reached a running app with no `users`
+  table. Both are generated from one list now, so they cannot disagree again.
+
+- **The admin starter answers `/`.** The dev server prints `http://localhost:3000`, and the app
+  had nothing there: a bare JSON `E_NOT_FOUND`, with no hint that the panel is at `/admin`. The
+  bare origin now redirects to it.
+
+- **A new API starter passes `zt doctor`.** Its `config/app.ts` was a bare object where the other
+  five starters use `AppConfig`, which is what fills `allowedOrigins` from `url`. The doctor failed
+  an app with no code of its own, and told you to set a `url` that was already set. The config is
+  wrapped in `AppConfig` now, and reads `APP_KEY` the way the other starters do: it must be set.
+
+- **The Flow and React starters create `users.remember_token`.** Their `User` uses
+  `Authenticatable`, but the migration did not create the column, so `zt doctor` failed between
+  `migrate` and the first dev boot, until the boot step added it. The migration creates it now.
+
+- **[Getting Started](/docs/getting-started) and [About Zerotal](/docs/about) no longer tell you
+  to overwrite your key.** Both said to run `cp .env.example .env` and that the ready-made `APP_KEY` lives in
+  `.env.example`. The scaffolder writes the real key into `.env` and only a placeholder into the
+  example, so following them replaced a generated key with the placeholder. Both now describe
+  what the scaffolder writes.
+
+### Changed
+
+- **New apps start on a tilde range.** `bun create zerotal` wrote `^X.Y.Z` into every new app's
+  `zerotal` and `@zerotal/*` dependencies. Under the [versioning scheme](/docs/upgrade#versioning)
+  a minor is where a break lands, so a caret let the app's next install cross one without anyone
+  reading its notes. It writes `~X.Y.Z` now, which takes every patch and stops at the minor.
+  Apps already scaffolded keep what they have; change `^` to `~` in their `package.json` to get
+  the same protection.
+
 ## 1.15.2 — 2026-10-23
 
 A patch, and if you run Bun 1.4.4 or later it is the one to take: that Bun stopped accepting the

package/docs/database.md

@@ -199,7 +199,7 @@ The `ManualTransaction` handle returned by `DB.beginTransaction()`:
 | `t.commit()`    | Commit and release the transaction                     |
 | `t.rollback()`  | Roll back and release the transaction                  |
 
-> **Warning** — Prefer `DB.transaction(callback)`. Manual transactions require careful error handling to avoid leaving connections open.
+> **Warning** — Prefer `DB.transaction(callback)`. A handle you never commit or roll back keeps its connection inside the transaction: on SQLite every later transaction fails with "cannot start a transaction within a transaction", and on a pool it is a connection that never comes back. Settle the handle on every path. A `finally` that calls `t.rollback()` is safe after a commit, where it does nothing.
 
 ## Raw queries with DB
 

package/docs/getting-started.md

@@ -152,20 +152,17 @@ no manual registration.
 
 ## Environment setup
 
-The scaffolder generates `.env.example` with a ready-made `APP_KEY`. Copy it to
-`.env`:
-
-```bash
-# in your project root
-cp .env.example .env
-```
+The scaffolder writes a `.env` with a freshly generated `APP_KEY`, so a new app boots
+straight away; there is nothing to copy. `.env` is git-ignored. `.env.example` is the
+copy you commit, and it holds placeholders on purpose: on another machine, copy it to
+`.env` and run `bun zt key:generate` to fill the key in.
 
 ```ini
 # .env
 APP_ENV=development
-APP_KEY=base64:…              # pre-generated; rotate with `bun zt key:generate`
+APP_KEY=…                     # generated for you; rotate with `bun zt key:generate`
 DATABASE_URL=./database/db.sqlite
-SESSION_SECRET=change-me-in-production
+SESSION_SECRET=…              # API template: generated for you; set your own before deploying
 ```
 
 The database is configured with a single **`DATABASE_URL`** — SQLite uses a file

package/docs/upgrade.md

@@ -40,6 +40,8 @@ something, and puts the work where it is useful: reading the notes for each mino
 > hold exactly where you put it — a release you have certified, a machine you cannot
 > re-test quickly — pin the exact version with no range operator at all.
 
+> **Note** — `bun create zerotal` writes a tilde range into new apps for this reason. An app scaffolded earlier has a caret: change `^` to `~` in its `package.json` to get the same protection.
+
 > **Warning** — always upgrade the `@zerotal/*` packages together. Mixing versions across core, ORM, and feature packages leads to type and runtime mismatches.
 
 ## Upgrade steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.15.2",
+  "version": "1.15.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.15.2"
+    "@zerotal/core": "1.15.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.15.2"
+    "@zerotal/orm": "1.15.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": [