@zerotal/arch 1.8.0 → 1.9.0

package/docs/admin/actions.md

@@ -177,6 +177,21 @@ When the model uses the ORM `SoftDeletes` mixin, the List page gains an
 **Active / All / Trashed** switch and the row + bulk actions gain Restore and
 Force-delete automatically — no extra configuration.
 
+## Types
+
+| Type                                   | What it is                                                               |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| `ActionItem`                           | One action as the panel holds it, after `action()` has built it.         |
+| `ActionHandler`                        | The callback an action runs, given its `ActionContext`.                  |
+| `ActionContext`                        | What that callback receives — the record or selection, and the page.     |
+| `ActionVisible`                        | The predicate deciding whether an action appears for this record at all. |
+| `ActionColor`                          | The emphasis it is drawn with.                                           |
+| `ConsoleAction`, `ConsoleHeaderAction` | The console's own row and header actions.                                |
+
+**`ActionVisible` hides, it does not authorize.** An action absent from the UI is still
+reachable by anyone who can form the request, so the authorization check belongs in the handler
+as well — see [Authorization](/docs/authorization).
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/auth.md

@@ -83,6 +83,16 @@ Panel.configure({
 `adminTokensCss()` the `:root`/`.dark` custom properties — feed both into your own
 `tailwind.config` so a compiled stylesheet renders identically.
 
+## Types
+
+| Type                          | What it is                                                                                                                                                              |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AdminAuthConfig`             | Who may reach the panel and how they sign in.                                                                                                                           |
+| `AdminAuthorizer`             | The check run before a page renders.                                                                                                                                    |
+| `AuthRolesOptions`            | How panel access maps onto the app's roles.                                                                                                                             |
+| `AdminThemeConfig`            | Panel theming.                                                                                                                                                          |
+| `EnvironmentIndicatorOptions` | The banner naming which deployment you are looking at — worth setting, because the panel looks identical in staging and production and that is exactly when it matters. |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/dashboard.md

@@ -149,6 +149,18 @@ Custom pages and anything contributed by a package sit in the same sidebar, sort
 and grouped by the same rules — a page's group heading is just a string, so a page
 and a resource that name the same group land together.
 
+## Types
+
+| Type                                      | What it is                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------------- |
+| `DashboardWidget`                         | One widget as declared.                                                     |
+| `WidgetContribution`                      | A widget pushed in by another package.                                      |
+| `WidgetTone`                              | Its good/warn/bad colouring.                                                |
+| `StatsResolver`                           | Supplies a stat widget's numbers for the selected range.                    |
+| `ChartResolver`, `ChartData`              | The same for a chart, and the shape it returns.                             |
+| `TableWidgetColumn`                       | A column in a table widget — narrower than a resource table's.              |
+| `DashboardLayout`, `DashboardLayoutStore` | An arrangement of widgets, and where a user's own arrangement is persisted. |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/extending-ui.md

@@ -221,6 +221,20 @@ the table — the search term, each filter, the trashed scope — and each chip
 its own undo. A table showing four of two hundred rows for no visible reason is
 the most common way a panel misleads someone; the chips are the fix.
 
+## Types
+
+The contribution shapes another package pushes into the panel:
+
+| Type                                                               | What it is                                                               |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `NavItem`, `NavGroup`, `NavContribution`                           | A sidebar entry, a heading it sits under, and a contributed one.         |
+| `PageContribution`                                                 | A whole page added to the panel.                                         |
+| `UserMenu`, `UserMenuItem`, `UserMenuContribution`                 | The account menu and its entries.                                        |
+| `TopbarSlot`                                                       | Where something may be placed in the top bar.                            |
+| `RenderHookName`                                                   | Every point the panel can be extended at — the enumeration of the slots. |
+| `RenderHookContext`                                                | What a hook receives when it runs.                                       |
+| `ConsoleContribution`, `ConsoleColumn`, `ConsoleRow`, `ConsoleTab` | Contributions to the console page.                                       |
+
 ## Next steps
 
 - [Tables](/docs/admin/tables) — columns, filters and the query builder.

package/docs/admin/forms.md

@@ -149,6 +149,21 @@ section("Line items").schema([
 ]),
 ```
 
+## Types
+
+| Type               | What it is                                                                        |
+| ------------------ | --------------------------------------------------------------------------------- |
+| `FormComponent`    | Anything that can appear in a form — a field, a layout block, a custom component. |
+| `FormBlock`        | A grouping: a section, a tab, a fieldset.                                         |
+| `FieldMode`        | Whether a field is editable, read-only or hidden in this context.                 |
+| `FieldPredicate`   | The condition behind a conditional field.                                         |
+| `FormModeConfig`   | How the form differs between create and edit.                                     |
+| `UploadedFileLike` | What a file field hands your handler.                                             |
+
+Infolists — the read-only counterpart — use `InfolistComponent`, with `EntryKind`,
+`EntryDisplay`, `EntrySize` and `EntryWeight` describing one entry's type and presentation.
+`PrimeKind` is the leading entry a record view opens with.
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/operations.md

@@ -217,6 +217,18 @@ A coloured strip across the top names the environment — red for production, am
 staging. It returns nothing in local development, so registering it unconditionally is
 the intended usage; there is nothing to switch off per environment.
 
+## Types
+
+| Type                                        | What it is                                             |
+| ------------------------------------------- | ------------------------------------------------------ |
+| `HistoryOptions`, `HistoryChange`           | Record history: what is tracked, and one entry of it.  |
+| `ImportRecordsPayload`                      | What the import action hands your handler.             |
+| `AdminNotification`, `StoredNotification`   | A panel notification, and the persisted form.          |
+| `DatabaseNotificationOptions`               | Where those are stored.                                |
+| `StoreMediaOptions`, `DatabaseMediaOptions` | Media handling and its database backing.               |
+| `SearchHit`, `PanelSearchProvider`          | One global-search result, and where results come from. |
+| `CalloutTone`                               | The emphasis a callout is drawn with.                  |
+
 ## Next steps
 
 - [Panel Structure](/docs/admin/structure) — clusters, nested resources, multiple panels.

package/docs/admin/resources.md

@@ -125,6 +125,12 @@ including on create.
 Both save hooks receive the `mode`, so one implementation can branch on `"create"`
 versus `"edit"` instead of duplicating the resource.
 
+## Types
+
+`AdminModel` is what a resource's `model` accepts, and `AdminQuery` the query it builds — the
+seam where the panel hands off to the ORM. `ListOptions` configures the list page,
+and `RelationKind` names the relation types a relation manager understands.
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/tables.md

@@ -179,6 +179,27 @@ How the table renders — grid instead of rows, striping, sticky headers, densit
 and where the filters sit are covered in
 [Extending the UI](/docs/admin/extending-ui#table-presentation).
 
+## Types
+
+What a column, filter and query rule are made of. All exported, so a helper that builds a
+column set for several resources can be typed rather than repeated.
+
+| Type                                                       | What it is                                                                                          |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `ColumnKind`                                               | Which column type this is — text, badge, boolean, date, and the rest.                               |
+| `ColumnOption`                                             | One column's settings.                                                                              |
+| `CellAlign`                                                | `start` / `center` / `end`.                                                                         |
+| `ColumnSummary`, `SummaryKind`, `SummaryResult`            | A footer aggregate: what to compute, and what comes back.                                           |
+| `BadgeTone`                                                | The colouring a badge column maps a value to.                                                       |
+| `EmptyState`                                               | What the table shows instead of rows when there are none.                                           |
+| `PivotColumn`                                              | A column reading a pivot table's own attributes on a many-to-many.                                  |
+| `FilterOption`, `FilterType`, `FilterApply`                | A filter's declaration, its kind, and how it modifies the query.                                    |
+| `ConstraintKind`, `ConstraintOperator`, `ConstraintOption` | The query-builder constraints behind advanced filtering.                                            |
+| `QueryRule`, `Conjunction`, `QueryModifier`                | One rule, how rules combine (`and` / `or`), and a raw modifier for what the builder cannot express. |
+| `SavedView`, `SavedViewProvider`                           | A stored filter set, and where those are kept.                                                      |
+| `TableRowsResolver`                                        | Supplying rows yourself instead of letting the resource query.                                      |
+| `ExportFormat`                                             | What the export action writes.                                                                      |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/audit.md

@@ -359,6 +359,11 @@ app.container.singleton(
 | `auditLog`  | `(event: AuditEvent, payload?: InstanceAuditPayload) => Promise<void>` | Log a custom event against this instance.   |
 | `auditLogs` | `() => ModelQueryBuilder<AuditLog>`                                    | Chainable query of this instance's history. |
 
+## Types
+
+`AuditableOptions` is what `Model.using(Auditable)` accepts — which columns are tracked and
+which are ignored. `AuditConfigShape` is the `audit` config namespace.
+
 ## Next steps
 
 - [ORM Lifecycle](/docs/orm/lifecycle) — the model hooks the audit system listens to.

package/docs/authentication.md

@@ -94,7 +94,12 @@ export class User extends AuthUser {
 }
 ```
 
-`AuthUser` provides `getAuthId()` (returns `this.id`) and `getAuthPassword()` (returns `this.password`). Make `Auth.user()` return your concrete type by augmenting `UserModel` once:
+`AuthUser` provides `getAuthId()` (returns `this.id`) and `getAuthPassword()` (returns `this.password`).
+
+### Bind the type — a required step
+
+Do this once, or every `Auth.user()` in the app returns the framework's minimal `UserModel`
+and reading your own columns off it is a type error:
 
 ```typescript fragment
 // bootstrap/app.ts (or any file imported at boot)
@@ -105,6 +110,17 @@ declare module "@zerotal/auth" {
 }
 ```
 
+`AuthenticatableUser` in `@zerotal/core/contracts` is the same seam one layer down: `@zerotal/core`
+has to talk about "the user" without depending on `@zerotal/auth`, so it declares an empty
+interface for apps to augment, and `UserModel` extends it. Augmenting either resolves to the same
+shape — augment `UserModel`, which is the one the auth docs and examples use.
+
+**The empty body is the point.** The interface is not being given members — it is being
+pointed at your class, so that everywhere the framework says `UserModel` it means `User`.
+That is not a shape anyone guesses, which is why it is here in setup rather than filed
+under advanced usage. Put it somewhere that is imported at boot and leave a comment saying
+what it is for; it looks like dead code otherwise.
+
 ## How it works
 
 On every request `PersistUserMiddleware` reads `user_id` from the session and populates `ctx.user`. If `user_id` is present but the user no longer exists, the stale key is cleared.
@@ -133,6 +149,20 @@ await Auth.login(user); // write user_id to session, set ctx.user
 await Auth.logout(); // clear user_id from session, unset ctx.user
 ```
 
+> **`Auth.user()` throws for a guest, and the name does not telegraph that.** It is the right
+> call behind `AuthMiddleware`, where a user is guaranteed — that guarantee is what makes its
+> non-optional return type honest. It is the wrong call on any route a signed-out person can
+> reach. Plenty of audited things happen with nobody signed in: a storefront checkout, a
+> customer approving a change from a tokenised link, an incoming webhook. On those routes an
+> audit line that reaches for `Auth.user()` turns into a 401 on a public page, and the 401 is
+> about the audit line rather than about the request.
+>
+> ```typescript fragment
+> // A guest is a normal outcome here, not a failure.
+> const actor = Auth.userOrNull();
+> await Audit.record("checkout.completed", { actorId: actor?.getAuthId() ?? null });
+> ```
+
 `Auth.attempt()` rolls credential lookup, password verification, and login into one call:
 
 ```typescript fragment
@@ -939,8 +969,87 @@ res.assertOk();
 res.assertSee("Welcome back");
 ```
 
+## Passkeys
+
+A passkey replaces the password with a key pair held by the device: the private half never
+leaves the authenticator, so there is nothing on your server worth stealing and nothing for a
+user to reuse across sites. `PasskeyService` implements both WebAuthn ceremonies.
+
+You supply where credentials are stored — the service does not assume a schema:
+
+```typescript fragment
+import { PasskeyService } from "@zerotal/auth";
+
+const passkeys = new PasskeyService({
+  rpName: "Acme",
+  rpId: "acme.test", // the domain, no scheme and no port
+  origin: "https://acme.test", // or an array, for staging alongside production
+  store: {
+    findUserCredentials: (userId) => Credential.where("user_id", userId).all(),
+    findCredential: (credentialId) => Credential.where("credential_id", credentialId).first(),
+    saveCredential: (credential) => Credential.create(credential),
+    updateCounter: (id, counter) => Credential.where("id", id).update({ counter }),
+  },
+});
+```
+
+Each ceremony is two calls — options out, response verified in. The challenge you hand back to
+`verify…` is the one you issued, which is what stops a replay:
+
+| Call                                                 | What it does                                                                                                                                          |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registrationOptions(user, existing?)`               | Options for enrolment. Pass the user's existing credentials so the browser refuses to register the same authenticator twice.                          |
+| `verifyRegistration(user, response, challenge, ctx)` | Verifies enrolment and stores the credential.                                                                                                         |
+| `authenticationOptions(userId?)`                     | Options for sign-in. Omit `userId` for a usernameless flow, where the authenticator offers the account.                                               |
+| `verifyAuthentication(assertion, challenge, ctx)`    | Returns `{ credential, userId }`, or the string `"passkey.invalid"` — a value rather than a throw, because a failed assertion is an ordinary outcome. |
+
+`PasskeyUser` is the minimum the ceremonies need (`id`, `name`, `email`); `PasskeyCredential` is
+what your store holds.
+
+> **`requireUserVerification` defaults to `true`, and that is what makes a passkey a second
+> factor.** With it off, an assertion succeeds on possession of an unlocked authenticator alone
+> — whoever picks up the phone is the user. Turn it off only for a deliberate "the device is the
+> credential" flow, and then do not count the passkey as a second factor.
+
+`rpId` is the domain alone — no scheme, no port — and it must match the site the browser is on
+or the ceremony fails with an error that does not say why. `origin` takes an array when the same
+deployment answers on more than one.
+
 ## References
 
+### Types
+
+Every middleware and broker takes an options shape, exported so a helper that builds one can be
+typed:
+
+| Type                                | Configures                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `AuthOptions`                       | `AuthMiddleware` — `redirectTo`, `mustVerifyEmail`, `verifyRedirectTo`. |
+| `GuestOptions`                      | `GuestMiddleware` — where a signed-in visitor is sent instead.          |
+| `BasicAuthOptions`                  | HTTP Basic auth.                                                        |
+| `ConfirmPasswordOptions`            | `ConfirmPasswordMiddleware`, including the confirmation window.         |
+| `AuthenticateSessionOptions`        | Session-guard behaviour on a password change elsewhere.                 |
+| `RememberMeOptions`                 | The persistent-login cookie.                                            |
+| `TwoFactorOptions`                  | The second-factor gate.                                                 |
+| `LoginThrottleOptions`              | Sign-in rate limiting.                                                  |
+| `EmailOtpOptions`                   | Passwordless codes by email.                                            |
+| `MagicLinkBrokerOptions`            | Magic-link sign-in.                                                     |
+| `PasskeysOptions`                   | `PasskeyService`, above.                                                |
+| `CompromisedCheckOptions`           | The have-i-been-pwned style check on a chosen password.                 |
+| `JwtGuardOptions`, `JwtSignOptions` | The JWT guard and how tokens are minted.                                |
+| `QrSvgOptions`                      | The 2FA enrolment QR code.                                              |
+
+What the brokers and guards hand back: `PasswordBrokerResult`, `MagicLinkBrokerResult` and
+`MagicLinkUser` for the link flows, `JwtPayload` and `TokenBundle` for JWT, and
+`PasskeyCredential` / `PasskeyUser` for passkeys.
+
+### Events
+
+Emitted on `FrameworkEvents`, so an app can audit or react without wrapping the calls that
+raise them: `EmailVerified`, `PasswordConfirmed`, `PasswordResetLinkSent`, `PasswordResetEvent`
+and `CurrentDeviceLogout`. `LoginSucceeded`, `LoggedOut` and `OtherDeviceLogout` are documented
+above with the calls that emit them.
+
 ### Commands
 
 `@zerotal/auth` ships two commands:

package/docs/broadcasting/references.md

@@ -77,6 +77,23 @@ Notifications can be delivered over a broadcast channel in real time — add `'b
 notification's `channels()` and implement `toBroadcast()`. See
 [Notifications → Broadcasting](/docs/notifications#broadcast).
 
+## Types
+
+Channel and event types, most of which are inferred from your channel declarations:
+
+| Type                                                      | What it is                                                                              |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `StaticChannels`, `ParameterizedChannels`                 | Channels with fixed names, and those taking params.                                     |
+| `ChannelParams`, `ChannelParamRecord`                     | What a parameterised channel captures.                                                  |
+| `ChannelAuthFn`                                           | The authorization callback for a private channel.                                       |
+| `PresenceAuthFn`, `PresenceMemberData`                    | The same for presence, plus what a member publishes to the others.                      |
+| `AuthorizeResult`                                         | What an auth callback may return — a refusal, or the member data.                       |
+| `TypedBroadcastEvent`, `EventsOf`, `PayloadOf`            | An event on a channel, the events a channel carries, and one event's payload.           |
+| `BroadcastsModelEventsOptions`, `ModelBroadcastEventName` | Broadcasting a model's own lifecycle, and the event names it produces.                  |
+| `BroadcastRecord`                                         | A queued broadcast as stored.                                                           |
+| `WsConnectionData`                                        | What the server holds per connection.                                                   |
+| `PusherPresenceResolver`                                  | Resolving presence members when running against Pusher rather than the built-in server. |
+
 ## Next steps
 
 - [Broadcasting overview](/docs/broadcasting) — the guide's front page and the rest of the sections.

package/docs/cache.md

@@ -381,6 +381,11 @@ does.
 > `CacheSerializationError` at write time. It is a bug in the caller rather than
 > a cache fault, so let it surface in development instead of swallowing it.
 
+## Types
+
+`IdempotencyOptions` configures `Cache.idempotent()` — the key, the window, and what happens to
+a second identical request that arrives while the first is still running.
+
 ## Next steps
 
 - [Query Builder](/docs/query-builder) — the queries you'll most often wrap in `remember()`.

package/docs/carbon.md

@@ -823,6 +823,11 @@ test("survives a DST spring-forward", () => {
 | `forHumans`                     | `forHumans(options?: { join?: string; short?: boolean }): string` | Human-readable description.                           |
 | `toISO`                         | `toISO(): string`                                                 | ISO 8601 duration string (`toJSON` alias).            |
 
+## Types
+
+`DurationLike` is what the arithmetic methods accept — `add`, `subtract` and their kin — so a
+duration can be built once and passed around rather than spelled out at each call site.
+
 ## Next steps
 
 - [Casts & Mutators](/docs/orm/casts) — `datetime` columns hydrate to Carbon automatically.

package/docs/changelog.md

@@ -27,9 +27,167 @@ 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.9.0 — 2026-08-29
+
+The gaps an app was filling in for itself: one Bun per project, a database backup that is not
+`cp`, a release gate the pipeline will actually call, a boundary between a model and a page
+prop, and helpers that work on both sides of the wire.
+
+**Two things to know before upgrading.** Both are new refusals or new noise, and both are quiet
+if they do not apply to you.
+
+- **`zt` now refuses to run when a project has two Bun runtimes in it** — the shell's `bun` and
+  a different one in `node_modules`. If it fires, pick one: `bun update bun` moves the installed
+  copy to match your shell, or run everything through `node_modules/.bin/bun`. To boot anyway
+  while you sort it out, set `ZT_ALLOW_RUNTIME_MISMATCH=1`. Most projects never see this,
+  because most have no `bun` in `node_modules` to disagree with.
+- **Passing an ORM model straight into an Inertia page prop now warns in development**, once per
+  model class, if that model declares neither `hidden` nor `visible`. Declaring either silences
+  it — and is the fix, not the silencer. Production is unaffected.
+
+### Added
+
+- **One project, one Bun.** `engines.bun` is a floor and nothing enforced it, so an app could be
+  served by one runtime and tested on another — the shell's `bun` and a `node_modules/bun` put
+  there by a transitive peer dependency nobody declared. A green suite is then evidence about a
+  binary the app is not served by. `startZerotal()` refuses on a mismatch, and `zt test` spawns
+  the binary running it rather than a name `PATH` resolves.
+
+- **`zt db:backup`** — a verified snapshot of the SQLite database, using `VACUUM INTO` rather
+  than `cp`. Copying a live SQLite file can capture a half-written page and produce a backup
+  that restores as a corrupt database, months later, from the one file you were relying on.
+  Every snapshot is opened and integrity-checked as it is written, `--require-rows` fails a
+  backup whose business tables are empty, `--rehearse` performs the actual restore, and every
+  failure path exits non-zero — a backup timer that reports success while writing nothing is
+  worse than no timer at all. See [Deployment](/docs/deployment#back-up-the-database).
+
+- **`DeployTarget.preflight`** — a slot for the app's own release gate, run after the config
+  validators and `doctor` and before anything is built or migrated. A command named
+  `release:check` is found by convention, with nothing to wire up. A declared name that is not
+  registered **fails** the deploy rather than being skipped: a gate nothing calls is a comment.
+
+- **`zerotal/shared`** — the helpers with no server in them, importable from a browser bundle:
+  `pluralize`, `Str`, and new `formatMoney` / `formatNumber` / `formatDate`. A total that reads
+  `R 39 147` on screen and `R39,147.00` on the invoice looks like two different numbers to the
+  person paying it, and maintaining that in two files is how it happens. See
+  [Helpers](/docs/helpers#sharing-helpers-with-the-browser--zerotalshared).
+
+- **`<form data-enhance>`** — a plain server-rendered page, with no Flow component on it, can
+  submit without the page flashing. It posts through `fetch` and the matching form in the
+  response replaces it in place, so a validation error lands where the person is looking. Its
+  own dependency-free bundle at `/__flow/enhance.js`, added with `flowEnhanceTag()` in the
+  layout. Every path degrades: a network failure re-submits natively, a redirect is followed and
+  `pushState`d, and no JavaScript at all is an ordinary form post.
+
+- **Three new `doctor` checks.** A rate limiter that cannot tell two people apart behind a proxy
+  — where the socket address is the proxy's for every request, so one attacker can lock out
+  everybody. Auth columns missing from a table a migration built without them, which otherwise
+  surfaces as `no such column` in tests that have nothing to do with email. And migrations that
+  have not run, named, before a request finds out.
+
+### Changed
+
+- **A model reaching Inertia page props says what it is safe to publish.** Page props are page
+  source, and `return inertia("Trips/Show", { trip })` ships every column of the row — the
+  internal cost, the margin, the note about the customer, on the customer's own screen. The
+  ORM's `hidden` / `visible` lists were already honoured and nothing said so. See the upgrade
+  note above and [Inertia props](/docs/inertia/props#page-props-are-page-source).
+
+- **A bound field the model will not accept says so.** `flow:model` on a column missing from
+  `fillable` was dropped in silence: the form submitted, nothing was written, nothing failed.
+  The drop stays — the same path receives whatever a browser sends — but a developer's typo no
+  longer produces the same silence as a hostile payload. Development only, once per field.
+
+- **INTERNAL: 116 exports leave the recorded API surface** across `core`, `orm`, `flow`,
+  `admin`, `flow-ui` and `monitor`. **Nothing is removed and nothing breaks** — they are still
+  exported and still work; what changes is the promise. The dev orchestrator, the ORM's
+  connection wiring and dialect layer, the admin panel's page machinery and Flow's
+  wire-protocol frame types are not things an app constructs, and naming them in a `stable`
+  surface implied a guarantee about a protocol that is free to change. Each package's own
+  changelog lists its share.
+
+- **A minor breaks nothing that can wait.** The roadmap used to say a minor never breaks
+  anything, which was false when written — three breaks had already shipped in minors, each
+  deliberately, each with a note, exactly as the [support policy](/docs/support-policy) has
+  always described. An absolute rule the project knowingly broke is worse than an honest one.
+
+### Documented
+
+- **Every promised export is documented — 100%, up from 60%.** `maturity: stable` means an
+  export keeps its shape for the rest of the 1.x line, and the gate measuring how much of that
+  promise was written down stood at 798 gaps. It is zero.
+
+  Four features turned out to have shipped and been invisible. **Passkeys** — `PasskeyService`
+  has been here since 1.7.0 with no page at all, including that `requireUserVerification`
+  defaults to `true` because that is what makes a passkey a second factor rather than one.
+  **`@zerotal/core/env`**, a typed environment schema that reports every bad variable at once
+  rather than one per restart. **The outbound `Http` client**, which the testing guide had been
+  linking to a page that did not describe it. And **`@zerotal/monitor`'s Export JSON**, where the
+  button was documented and the forty-odd row types it hands you were not.
+
+  Also named for the first time: `@zerotal/flow-ui`'s sixty-one component prop types, which a
+  wrapper component cannot be written without.
+
+  The gate itself could not see `.tsx` files: with `jsx` unset, TypeScript declines to pull such
+  a module into the program rather than failing to parse it, so every symbol in one was
+  invisible. It had been inflating exactly the TSX-heavy packages.
+
+### Fixed
+
+- **A rebuilt Inertia bundle no longer 404s on a chunk the browser asks for.**
+  `resources/js/app.tsx` builds to `/assets/app.js` under that name every time, while
+  `splitting: true` names each chunk after its content. A rebuild therefore rewrites `app.js` to
+  import `chunk-NEW.js` and prunes `chunk-OLD.js` — and a browser holding a cached `app.js` asks
+  for the pruned one:
+
+      GET /assets/chunk-hrnspqda.js  status=404
+
+  from a page that renders and a server that is healthy, with nothing in that line leading back
+  to the template.
+
+  The template hardcodes `/assets/app.js` rather than calling `asset()`, so the version token the
+  rest of the framework appends never reached it — and cache-busting had only ever been
+  implemented for `serve --dev`. It now applies in every environment: the file's mtime in dev,
+  where a rebuild happens without a restart, and the boot-derived asset version otherwise. An
+  unchanged asset keeps a stable URL and stays cached, which is why the token is derived rather
+  than random.
+
+## 1.8.1 — 2026-08-26
+
+DevTools showed you the wrong request, accurately.
+
+### Fixed
+
+- **A page keeps the DevTools panel while its own assets load.** Opening `/login` selected
+  `/login`, then `/favicon.ico` a few milliseconds later, then `/css/app.css`. Live mode
+  selected every trace as it arrived and a page's sub-resources arrive right behind it, so the
+  bar named a request nobody asked about, the detail below described that request's headers
+  and its empty session, and the page you were inspecting had scrolled into the list. Nothing
+  shown was wrong; it was all about the wrong request.
+
+  Traces are now classified into three kinds rather than two, because "not the document" would
+  have suppressed the form post and the Inertia visit — the requests most worth watching. What
+  gets skipped over is narrower: a sub-resource the browser fetched on its own initiative. The
+  browser is asked rather than the URL, since an app may serve an API from a `.js` route and a
+  build that hashes its asset names has no extension to read; what was actually served is the
+  fallback, so a page fetched by `curl` still reads as a page. Anything unclassifiable counts
+  as app traffic, never as an asset — being wrong there decides whether a request is skipped,
+  and skipping the wrong one is how the panel stops showing what you came to see.
+
+  An asset still takes the selection when nothing else has it, so a panel opened mid-load
+  shows a request rather than an empty pane. A paused panel still counts assets toward its
+  pending badge.
+
+### Added
+
+- **A `kind` facet on the DevTools All tab**, beside method and status. Assets were never the
+  problem, only their claim on the selection, so they are not hidden: pick `page` and `api`
+  for a list without fifty stylesheet fetches in it, or `asset` alone for what the browser
+  pulled in, what it cost and which of it 404'd — which was not visible anywhere before.
+
 ## 1.8.0 — 2026-08-24
 
-The first render mode, the codemod runner 2.0 depends on, and four failures that
+The first render mode, the codemod runner 2.0 depends on, and five failures that
 each looked like something other than what they were.
 
 ### Added

package/docs/client/index.md

@@ -328,6 +328,23 @@ This package also ships `Socket`, `Channel` and `PresenceChannel` — a WebSocke
 client speaking Zerotal's broadcast protocol. Different job, documented where it is
 used: [Broadcasting → Client](/docs/broadcasting/client).
 
+## Types
+
+The typed client derives its shape from your app's routes, so most of these are inferred rather
+than written by hand — but a helper that wraps a call needs to name them:
+
+| Type                                         | What it is                                                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ApiRouteMap`                                | The generated route table the client is typed against.                                                                   |
+| `RouteShape`                                 | One route's method, params, body and response.                                                                           |
+| `PathsFor<M>`                                | Every path answering a given method — what makes an unknown path a compile error.                                        |
+| `PathParams`, `ParamRecord`                  | The params a path captures.                                                                                              |
+| `BodyOf<P>`, `QueryOf<P>`, `ResponseOf<P>`   | One route's request body, query and response types.                                                                      |
+| `ResponseMeta`                               | Status, headers and timing carried alongside a response.                                                                 |
+| `RequestInterceptor`, `ResponseInterceptor`  | Hooks running before a request leaves and after one returns — auth headers, retry, logging.                              |
+| `CircuitBreakerOptions`                      | When the client stops calling an endpoint that keeps failing, and when it tries again.                                   |
+| `SocketOptions`, `SocketState`, `SocketLike` | The realtime socket: how it connects, where it is in its lifecycle, and the minimum interface a substitute must satisfy. |
+
 ## Next steps
 
 - [Rate Limiting](/docs/rate-limiting) — throttle what you send and what you accept.

package/docs/commands.md

@@ -370,10 +370,16 @@ can gate a deploy.
 | `bun zt migrate:status`       | Show the status (run / pending / batch) of each migration file |
 | `bun zt migrate:generate`     | Auto-generate a migration from model schema changes            |
 | `bun zt db:seed`              | Run all seeders from `database/seeders/`                       |
+| `bun zt db:backup`            | Take a verified SQLite snapshot with `VACUUM INTO`             |
 
 > **Danger** — `migrate --fresh` and `migrate:fresh` drop every table before
 > re-running migrations. Never run them against a production database.
 
+`db:backup` is the counterpart to everything above it: those commands all assume the database
+file will still be there. It verifies every snapshot it writes and exits non-zero on any
+failure, so it is safe to run from a timer — see
+[Deployment](/docs/deployment#back-up-the-database) for the flags and a systemd unit.
+
 ### Generators
 
 | Command                                              | Creates                                                                    |