@zerotal/arch 1.15.1 → 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,108 @@ 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
+way the ORM hands it SQL, so most of what the ORM sent to the database failed. Three smaller
+faults ride with it, found running a live app on Zerotal, each of which that app had been
+working round in its own code.
+
+Nothing here breaks. Safe to take directly.
+
+### Fixed
+
+- **The ORM runs on Bun 1.4.4** (`@zerotal/orm`, with `@zerotal/notifications` and
+  `@zerotal/testing`). Bun's `sql` function refuses a template object whose `raw` property
+  is enumerable — "so it is not a template object" — and the ORM built every statement it
+  assembled from a string that way: the string form of `DB.raw()`, the query builder,
+  schema and migration DDL, the `SAVEPOINT` a nested transaction issues, the validator's
+  `unique` and `exists` rules. 1.4.4 is the first Bun known to refuse it, and on that version
+  and later none of those statements ran. They now come from one helper that builds the
+  object the way the language does. An app on Bun 1.4.2 or earlier was never affected, and
+  nothing about its behaviour changes.
+
+- **A production build ships React's production build** (`@zerotal/core`). The browser
+  build's defines stated `import.meta.env` but not `process.env.NODE_ENV`, which is the
+  switch React and most of npm read — and the bundler left that expression to whatever the
+  shell happened to have. An app that ran `inertia:build --production` without `NODE_ENV`
+  in its environment shipped React's development build: a 522 KB vendor chunk where 322 KB
+  would do, the DevTools notice in every visitor's console, and full hydration diffs. The
+  define now states `NODE_ENV` from the same flag, so the build no longer depends on the
+  shell it ran in.
+
+- **`back()` works behind a proxy that terminates TLS** (`@zerotal/core`). A redirect back
+  to the previous page accepted a `Referer` only from the request's own origin. Behind a
+  reverse proxy the request reaches the app as `http://…` while every browser sends
+  `https://…`, so every `Referer` was refused and "back" was always `/`. That is not only
+  `ctx.back()`: `validate()`'s redirect on failure, `FormRequest`, the intended-URL helpers
+  and Flow all use the same check, so a form with one mistake in it sent the user to the
+  home page with its errors flashed to a page that never shows them. The origin of the
+  configured `app.url` now counts as the app's own as well. Every other site is still
+  refused, and with no `app.url` set the behaviour is exactly what it was.
+
+- **`SmtpDriver` transfer-encodes text and HTML parts** (`@zerotal/notifications`). Both
+  went on the wire raw, with no `Content-Transfer-Encoding`. A body line over the 998-octet
+  limit of RFC 5322 was cut by a relay wherever the limit fell — a single-line HTML email
+  reached a customer reading "sup pliers" — and a non-ASCII body was sent as undeclared
+  8-bit on a connection that never negotiates `8BITMIME`. A part that is plain ASCII with
+  lines of 78 characters or fewer is still sent as written, now declared `7bit`; anything
+  else is quoted-printable, which keeps ASCII readable where base64 would not. A test that
+  asserts on the raw bytes the driver sent will see the new header, and for a long or
+  non-ASCII body, encoded text to decode before comparing.
+
+### Changed
+
+- **Three runtime dependencies move to newer minimums.** `alpinejs` and its seven plugins
+  (`@zerotal/flow`) are now `^3.17.4`, `@simplewebauthn/server` (`@zerotal/auth`) is now
+  `^13.3.3`, and `tailwind-merge` (`@zerotal/flow-ui`) is now `^3.7.0`. Each stays within
+  the major it was already on, and nothing in Zerotal's own API moves. The rest of the
+  weekly dependency update is development tooling and does not reach an installed app.
+
 ## 1.15.1 — 2026-09-13
 
 A patch, and its headline is an ORM bug as old as the option it breaks: a model keyed on

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