@zerotal/arch 1.13.2 → 1.13.4

package/docs/changelog.md

@@ -27,6 +27,125 @@ 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.13.4 — 2026-09-01
+
+**Take this one if you are on 1.13.3.** The site gate shipped a staff bypass that failed
+open, and a type error that landed on apps not using it. Both found by a team upgrading,
+within a day.
+
+### Fixed
+
+- **The gate's staff bypass was a denylist, and let the public in.** 1.13.3 admitted any
+  authenticated user whose role was not literally `"customer"`. In an app whose roles are
+  `user` and `admin` — which is most of them — that is every signed-in visitor, so a
+  private preview showed the site to anyone with an account. A gate that fails open is
+  worse than no gate, because it reports success while doing nothing.
+
+  It is an allowlist now: `gate.staffRoles`, defaulting to `["admin"]`. An app whose staff
+  role is named something else gets no bypass and notices, which is the safe direction to
+  be wrong in. The token path is unchanged.
+
+  Worth naming the mistake, because this release cycle already contained its lesson: the
+  1.11.0 notes describe an app that wrote its own "is this error permanent" check as a
+  denylist and found it was a latent outage, and the fix was an allowlist. The same shape
+  went into the gate three releases later.
+
+- **The same line broke `tsc` for apps that do not use the gate.** `role !== "customer"`
+  is a type error when an app's role union has no such member (`TS2367`), and the
+  framework ships TypeScript source, so the error arrived on a feature the app never
+  touched — failing its build. The role is read as `string` now, because the framework
+  cannot know an app's role names and must not narrow to them.
+
+### Documented
+
+- **A tilde still crosses a patch, and under this scheme a patch carries features.**
+  `~1.13.2` is `>=1.13.2 <1.14.0`, so it takes 1.13.3 without asking — which is exactly
+  how 1.13.3 reached the app that found the bugs above. That is the right default for most
+  apps, and it is weaker protection than the same range gives under strict semver, where a
+  patch is only ever a bug fix. [The upgrade guide](/docs/upgrade#versioning) now says so,
+  and says to pin the exact version when you need it to hold.
+
+## 1.13.3 — 2026-08-31
+
+Two things an app cannot see about itself, from two field reports. Both are the same
+shape as most of this month's work: state that is real, consequential, and invisible from
+inside the process that would want to know it.
+
+### Added
+
+- **A site gate — maintenance, and private preview.**
+  [Guide](/docs/site-gate) · `zt down` · `zt preview` · `zt up` · `zt gate:status`
+
+  Proposed by a team running a hand-edited `basic_auth` block in their reverse proxy,
+  deliberately kept out of version control so it could not be deployed and forgotten into
+  a live shop. That precaution is the feature request: the gate belongs where the app can
+  reason about it.
+
+  Two states that look alike and are not. **Maintenance** means the site is down —
+  everyone refused, staff included, because the usual reason a site is down is that its
+  database is being changed underneath it. **Private preview** means the site is up and
+  working, for the people invited to it, for weeks.
+
+  The details that make it framework work rather than app work:
+
+  - **Maintenance is always `503` with `Retry-After`, and is not configurable.** A
+    maintenance page served at `200` tells a search engine the apology is your homepage,
+    and it will index it as such.
+  - **A preview token is stripped from the URL on first use**, by redirecting to a
+    cookie. Left in the address bar it travels into `Referer` on every outbound link,
+    into analytics, and into screenshots.
+  - **Webhook paths must be declared** in `gate.allow`. A payment provider posting a
+    settlement into a maintenance window otherwise gets a 503 — a retry, a dropped
+    callback, or a payment your books never learn about.
+  - **The state is a file, and the token is stored hashed.** A flag in the database is
+    unreadable exactly when the database is what you are working on; a token in a file
+    is a credential in something every backup copies.
+  - **It covers `Router.raw()` routes.** Found by running it: this framework's own docs
+    site serves every `/docs/*` page from a raw route, so an early build gated the front
+    page — which is what a person checks — and left all the content public.
+  - **The state file is gitignored** by the scaffold, which is the entire point.
+
+- **Worker liveness — `zt doctor` can tell whether anything is running your background
+  work.** [Schedules](/docs/scheduler#is-anything-actually-running-them) ·
+  [Queue](/docs/queue#is-a-worker-running)
+
+  An app could say what it _registered_ and nothing could say whether any of it ever
+  _ran_. The reported failure: a team shipped to production with no worker process, and
+  every scheduled task silently did not execute for weeks. No hold was released, no
+  reminder was sent, nothing logged — from the web process's point of view nothing was
+  wrong, and they found it by going looking.
+
+  ```
+  ✖ Scheduler — 3 schedule(s) registered, and no worker has ever checked in.
+    Nothing is running them.
+      fix: Start the worker process: `bun zt worker`.
+  ```
+
+  The beat lives in the **cache**, because the process reading `doctor` is not the process
+  running the work and often not the same machine — and your cache driver already decides
+  what shared state can see. On `memory`, which is private to each process, the check
+  **says it cannot tell** rather than reporting a missing worker: a check that cried wolf
+  on every app using that driver is one people would learn to skip, and then it would not
+  be there for the case it exists for.
+
+  `@zerotal/core/heartbeat` exposes the primitive if you want the same signal on an ops
+  page.
+
+### Fixed
+
+- **`secureHeaders: false` no longer empties the kernel middleware.** It set the layer to
+  `[]`, which was the same thing as removing the headers right up until the site gate
+  joined it — at which point opting out of security headers would silently have taken the
+  gate with it. One feature's opt-out disabling another's is precisely what the gate is
+  otherwise about.
+
+### Documented
+
+- **Minting `APP_KEY` without the code.** `key:generate` is part of the application, so it
+  exists only once a release is installed — awkward when preparing `.env` first, since
+  `migrate` wants the file and the file wants a key. `openssl rand -base64 32` produces
+  exactly what `key:generate` writes; the [deployment guide](/docs/deployment) now says so.
+
 ## 1.13.2 — 2026-08-31
 
 From a production field report at 1.12.0 — an Inertia + React app on SQLite, 117 routes,

package/docs/deployment.md

@@ -213,6 +213,19 @@ DATABASE_URL=postgres://user:pass@db-host:5432/app
 and a `base64:`-prefixed one are accepted. Generate it **on the server** — a key carried
 from a laptop is a key that has been in a shell history and a scrollback buffer.
 
+**On a first deploy you do not have to wait for the code.** `key:generate` is part of the
+application, so it only exists once the release is installed — which is awkward if you are
+preparing `.env` before that, since `migrate` wants the file and the file wants a key.
+There is nothing framework-specific about the value:
+
+```bash fragment
+openssl rand -base64 32
+```
+
+That is exactly what `key:generate` produces — 32 random bytes, base64 — so a key minted
+this way is indistinguishable from one it wrote. Use whichever fits the order you deploy
+in.
+
 `APP_ENV` accepts deployment names like `production` and `staging`; they all normalize to
 the `web` runtime mode — they describe _where_ the app runs, not _how_. See
 [Configuration](/docs/config-system).

package/docs/index.md

@@ -40,7 +40,7 @@ cd my-app && bun dev
 | See what's running in production   | [Logger](/docs/logger) · [Monitor](/docs/monitor) · [Telemetry](/docs/telemetry) · [Health](/docs/health)                                         |
 | Debug what it just did             | [DevTools](/docs/devtools) · [Errors](/docs/errors)                                                                                               |
 | Work with a coding agent           | [Agent Surface](/docs/arch)                                                                                                                       |
-| Ship it                            | [Deployment](/docs/deployment) · [Commands](/docs/commands)                                                                                       |
+| Ship it                            | [Deployment](/docs/deployment) · [Site gate](/docs/site-gate) · [Commands](/docs/commands)                                                        |
 
 ## Choosing a frontend
 

package/docs/inertia/ssr.md

@@ -9,22 +9,7 @@ By default Inertia renders the first page on the client. Server-side rendering (
 renders the initial HTML on the server instead — better Time-to-First-Byte and
 crawlable content — while subsequent navigations keep using the fast JSON path.
 
-Zerotal offers two approaches: the **`/__ssr` endpoint** (standard Inertia SSR) and
-**streaming SSR** via `inertiaStream()`.
-
-## Which should I use?
-
-- **Endpoint SSR** (`ssr: true`) — the standard Inertia SSR contract. Turn it on
-  globally and the Inertia client renders the first page through `POST /__ssr`. Use
-  this when you want crawlable, server-rendered HTML across the whole app with no
-  per-controller change.
-- **Streaming SSR** (`inertiaStream()`) — swap `inertia()` for `inertiaStream()` in
-  the controllers whose initial document you want streamed for the fastest TTFB. Use
-  it selectively on heavy landing pages; everything else stays on `inertia()`.
-
-## Endpoint SSR
-
-Enable the SSR endpoint in config:
+Turn `ssr` on and every first page load is server-rendered. That is the whole of it:
 
 ```ts
 // config/inertia.ts
@@ -34,21 +19,70 @@ import { env } from "zerotal";
 export default InertiaConfig({
   htmlTemplate: "./resources/app.html",
   version: env("ASSET_VERSION", "1"),
-  ssr: true, // registers POST /__ssr — requires a server renderer
+  ssr: true,
 });
 ```
 
-When `ssr: true`, `InertiaProvider` registers `POST /__ssr`, which accepts
-`{ component, props, url }` and returns `{ body, head }` — the same contract as the
-Inertia Node SSR server. On a first-page load the server renders the component into
-the template instead of shipping an empty root `<div>`; subsequent navigations use
-the normal JSON path. Pages render with the framework they're authored in: React
-`.tsx` via `react-dom/server`, or Vue `.vue` via `@inertiajs/vue3` +
-`vue/server-renderer` — install the server renderer for the framework(s) your app uses.
+No controller changes. `Inertia.render()` renders the component into the root, injects
+the page's `<Head>` tags into the document head, and marks the root
+`data-server-rendered` so the client **hydrates** that markup instead of throwing it
+away and painting again. The scaffolded `app.tsx` already does the hydrating half:
+
+```tsx fragment
+setup({ el, App, props }) {
+  const app = <App {...props} />;
+  if (el.hasAttribute("data-server-rendered")) {
+    hydrateRoot(el, app);
+  } else {
+    createRoot(el).render(app);
+  }
+}
+```
+
+Subsequent navigations are unaffected — an `X-Inertia` XHR gets the page object as JSON
+either way, because server rendering is about the _first_ arrival.
+
+> **Before 1.13.4, `ssr: true` did not do this.** It registered `POST /__ssr` and nothing
+> in the request path consulted it, so an app that set the flag and read this page got
+> exactly the empty root it had before, and server rendering was reachable only by
+> rewriting each route to `inertiaStream()`. If you worked around that with a per-route
+> switch, you can delete it.
 
-## Streaming SSR
+Pages render with the framework they are authored in: React `.tsx` via
+`react-dom/server`, Vue `.vue` via `@inertiajs/vue3` + `vue/server-renderer`. Install the
+server renderer for the framework your app uses.
 
-`inertiaStream()` is a drop-in async alternative to `inertia()` that uses React 18's
+**A page that fails to server-render still works.** The failure is logged and the
+client-rendered document is served instead, because taking a route down because an
+_optimisation_ failed would make `ssr: true` a liability rather than an improvement.
+
+## What `POST /__ssr` is for
+
+`ssr: true` also registers it. It accepts `{ component, props, url }` and returns
+`{ body, head }` — the same contract as the Inertia Node SSR server — and it exists for
+an **external** caller: a separate renderer process, or a deployment that renders
+somewhere other than the web process.
+
+You do not need it for the switch above, which renders in-process. It is throttled and
+loopback-gated; see `ssrSecret` for reaching it from another host.
+
+## Streaming SSR — a different question
+
+`inertiaStream()` is **not** how you turn SSR on — that is the config flag. Streaming is
+about **time to first byte**: the document goes out in pieces as the component renders,
+rather than being buffered and sent whole.
+
+That is a trade, which is why it stays a per-route choice rather than an app-wide one. A
+streamed response starts arriving sooner and finishes no earlier, and on a page that is
+mostly shell the buffering costs nothing worth reclaiming. Reach for it on a heavy
+landing page; leave everything else on `Inertia.render()`.
+
+Both render the component and both mark the root for hydration. The only difference is
+whether the bytes are streamed.
+
+### How it streams
+
+It uses React 18's
 `renderToReadableStream` to improve TTFB. Instead of buffering the whole render, it
 streams the React output between the template's HTML prefix and suffix:
 
@@ -82,14 +116,17 @@ export class PostController {
 
 ### inertia vs. inertiaStream
 
-| Criterion      | `inertia()`              | `inertiaStream()`                  |
-| -------------- | ------------------------ | ---------------------------------- |
-| Return type    | `Promise<void>`          | `Promise<void>`                    |
-| Rendering      | None — empty root + JSON | Streaming `renderToReadableStream` |
-| Response body  | Fully buffered string    | Streaming `ReadableStream`         |
-| TTFB           | Immediate                | After the shell is ready           |
-| Page `<Head>`  | Client only              | Collected into the served `<head>` |
-| XHR navigation | JSON (the normal path)   | JSON — the same page object        |
+| Criterion      | `inertia()`                             | `inertiaStream()`                  |
+| -------------- | --------------------------------------- | ---------------------------------- |
+| Return type    | `Promise<void>`                         | `Promise<void>`                    |
+| Rendering      | Server-rendered when `ssr: true`        | Always server-rendered             |
+| Response body  | Fully buffered string                   | Streaming `ReadableStream`         |
+| TTFB           | After the render                        | As the component renders           |
+| Page `<Head>`  | In the served `<head>` when `ssr: true` | Collected into the served `<head>` |
+| XHR navigation | JSON (the normal path)                  | JSON — the same page object        |
+
+With `ssr: false` — the default — `inertia()` serves an empty root and the page object,
+and the browser does all the rendering.
 
 **Both implement the whole protocol.** An `X-Inertia: true` request gets the page
 object as JSON from either one; the streaming half applies to the first arrival,
@@ -152,8 +189,9 @@ Two things it does not do:
 
 ## What a crawler sees
 
-`inertia()` — the default — **does not server-render the component at all.** Its
-response body is the template with an empty root and the page object beside it:
+**With `ssr: false` — the default — `inertia()` does not server-render the component at
+all.** Its response body is the template with an empty root and the page object beside
+it:
 
 ```html
 <body>
@@ -179,10 +217,11 @@ readers of your site run JavaScript and which do not:
 So the link preview a page produces is decided entirely by its `<head>` — which is
 the template's, identically, on every page, unless you do one of these:
 
-1. **Switch the page to `inertiaStream()`.** The component is rendered, `<Head>` is
-   collected, and the served `<head>` is the page's own. This is the smallest change
-   and the one to reach for on pages that get shared.
-2. **Turn on endpoint SSR** (`ssr: true`) for the whole app.
+1. **Turn on `ssr: true`.** One line, every page: the component is rendered, `<Head>` is
+   collected, and the served `<head>` is the page's own. This is the change to reach for
+   unless you have a reason not to.
+2. **Switch a single page to `inertiaStream()`**, if you want that and streaming on one
+   route without turning rendering on everywhere.
 3. **Set the tags in middleware**, if the metadata is server-side data the component
    does not otherwise need.
 

package/docs/queue.md

@@ -353,6 +353,24 @@ needed, so chaining works with any driver.
 
 ## Processing jobs
 
+### Is a worker running?
+
+Jobs waiting with nothing to run them is the same failure as an unrun schedule, one layer
+over: the queue fills, nothing errors, and you find out when a customer asks where their
+email went.
+
+`zt doctor` reports it, keyed on the **pending depth** rather than on whether any job
+class exists — an app with an empty queue and no worker may be perfectly fine:
+
+```
+✖ Queue worker — 4102 job(s) waiting, and no worker has ever checked in.
+    fix: Start the worker process: `bun zt worker`.
+```
+
+The same shared-cache caveat applies as for [schedules](/docs/scheduler#is-anything-actually-running-them):
+the beat lives in the cache, so a `memory` driver means the check stands aside rather
+than guessing.
+
 ### Dedicated worker process
 
 The standard way to process jobs in production is a long-running worker process:

package/docs/scheduler.md

@@ -301,6 +301,69 @@ Scheduled tasks (2)
   Next run     2026-06-22T06:00:00.000Z
 ```
 
+## Is anything actually running them?
+
+Schedules register in the `worker` and `console` environments, not in `web`. That is the
+right design — HTTP instances should not run cron — and it means **a second process is
+required.** The framework starts happily without one.
+
+An app shipped to production with no worker, and every scheduled task silently did not
+execute for weeks. No hold was released, no reminder was sent, nothing logged, because
+from the web process's point of view nothing was wrong. They found it by going looking.
+
+`zt doctor` now looks for you:
+
+```
+✖ Scheduler — 3 schedule(s) registered, and no worker has ever checked in. Nothing is
+  running them. This is silent by nature — the web process has no way to notice, and
+  the work simply does not happen.
+    fix: Start the worker process: `bun zt worker`. It is a second process; the web
+         server does not run this.
+```
+
+The worker records a check-in every minute while it runs. A check-in older than fifteen
+minutes is a warning rather than a failure, because a worker mid-restart is not a
+missing worker.
+
+### It needs a shared cache to mean anything
+
+The beat is written to the cache, because the process reading `doctor` is not the
+process running the schedules — and often not the same machine. Your cache driver
+decides what that can see:
+
+| Driver             | Sees a worker on…                       |
+| ------------------ | --------------------------------------- |
+| `sqlite` (default) | another process on the same box         |
+| `redis`            | another machine                         |
+| `memory`           | nothing — it is private to each process |
+
+On `memory` the check **stands aside and says so** rather than reporting a missing
+worker. A check that cried wolf on every app using the memory driver is one people would
+learn to skip, and then it would not be there for the case it exists for.
+
+### Reading it yourself
+
+The primitive is `@zerotal/core/heartbeat`, if you want the same signal on an ops page:
+
+```ts
+import { Heartbeat } from "@zerotal/core/heartbeat";
+
+const seen = await Heartbeat.lastSeen("scheduler");
+// { status: "seen", ageSeconds, beat } | { status: "never" } | { status: "unknown", reason }
+```
+
+| Name                  | Description                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `Heartbeat`           | `beat()` records a check-in, `start()` beats on an interval and returns a stopper, `lastSeen()` reads one. |
+| `Beat`                | What a check-in records — `at`, `pid`, `detail`.                                                           |
+| `BeatLookup`          | The three answers: `seen`, `never`, and `unknown` with a reason.                                           |
+| `workerLivenessCheck` | Builds the doctor check above for a worker kind.                                                           |
+| `describeBeat`        | Renders a `BeatLookup` as the prose used in the report.                                                    |
+
+`unknown` is a distinct answer from `never` on purpose, and every consumer has to keep
+them apart: one means nothing is running, the other means this process cannot see whether
+anything is.
+
 ## Run history
 
 Every completed execution — success or failure — is recorded to a capped JSONL

package/docs/site-gate.md

@@ -0,0 +1,190 @@
+---
+title: Site gate
+description: Maintenance mode and private preview — take a site down correctly, or open it only to the people you invite.
+---
+
+# Site gate
+
+Two states a site can be in that are not "serving the public", and they are not the
+same thing.
+
+**Maintenance** — the site is _down_. Nobody may use it, staff included, because the
+usual reason a site is down is that its database is being changed underneath it, and
+letting one person in is letting them into that. Minutes, not weeks. Every request is
+answered `503` with `Retry-After`.
+
+**Private preview** — the site is _up and working perfectly_, for the people invited to
+it. Not down, not broken, not public yet. Weeks. An invited visitor gets the real site
+at `200` and can transact on it; the public gets a holding page.
+
+Building one and calling it both is the usual mistake, and it is why a pre-launch site
+ends up behind a `503` that search engines take seriously.
+
+## Turning it on
+
+```bash
+bun zt down --retry=120          # maintenance
+bun zt preview                   # private preview; prints the link
+bun zt preview --until=2026-09-30
+bun zt up                        # open again
+bun zt gate:status               # what is it doing
+```
+
+`zt preview` generates the token when you do not pass one, because a token typed by a
+person is the only thing between the public and an unlaunched site and nothing
+rate-limits guesses at it. **Keep the link it prints** — only a hash is stored, so the
+token cannot be read back.
+
+These four commands need no application and are registered in every environment. A
+maintenance command that only works when the app boots is one you cannot reach at the
+moment you need it.
+
+## From your own console
+
+The framework's job is the primitive; the button is yours.
+
+```ts
+import { Gate } from "@zerotal/core/gate";
+
+await Gate.preview({ token, until: "2026-09-30", by: user.name });
+await Gate.maintenance({ retryAfter: 120, by: user.name });
+await Gate.open();
+
+Gate.status(); // { mode, since, until, by, expired } — never the token
+```
+
+## Getting in
+
+**A secret link.** `https://example.com/?preview=<token>`. The gate recognises the
+token, sets a signed `HttpOnly` `SameSite=Lax` cookie, and **redirects to the same URL
+with the parameter removed.**
+
+That redirect is not tidiness. A token left in the address bar travels into `Referer`
+on every outbound link, into analytics, into screenshots, and into the message where
+somebody shares "the page I was looking at". Stripping it on first use leaves the
+secret in a cookie and nowhere else.
+
+**A signed-in staff account.** A request whose authenticated user holds a role on the
+allowlist is admitted without a token, so an app that already has staff accounts does not
+need a second secret for the same people. It defaults to `["admin"]`:
+
+```ts
+// config/gate.ts
+export default { staffRoles: ["admin", "editor"] };
+```
+
+An **allowlist**, and it matters. 1.13.3 shipped the inverse — "anyone whose role is not
+`customer`" — which in an app whose roles are `user` and `admin` admitted every signed-in
+visitor and let the public straight through. A gate that fails open is worse than no gate,
+because it reports success while doing nothing. An app whose staff role is named something
+this does not list gets no bypass and notices, which is the safe direction to be wrong in.
+
+The cookie lasts seven days. A preview cookie with no lifetime means an ex-tester keeps
+access to a site that has since gone live with real customer data.
+
+**Rotating revokes.** `zt preview --token=<new>` invalidates every cookie issued under
+the previous token, because the way a preview leaks is a tester forwarding the link to
+somebody who has left.
+
+## What stays reachable
+
+These are open whatever the gate is doing:
+
+| Path                                           | Why                                                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/__zerotal/*`                                 | The health endpoint. Otherwise the uptime monitor pages the on-call about a planned window, and a deploy gate that polls health fails its own release. |
+| `/css/*`, `/js/*`, `/assets/*`, `/favicon.ico` | A maintenance page that 503s its own stylesheet is an unstyled apology.                                                                                |
+
+**Your webhooks are not on that list, and this is the one that costs money.**
+
+A payment provider posting a settlement into a maintenance window gets a `503`, and
+depending on the provider that is a retry, a dropped callback, or a payment your books
+never learn about. Nothing can infer which of your routes a third party calls, so it
+has to be declared:
+
+```ts
+// config/gate.ts
+export default {
+  allow: ["/webhooks/", "/api/callbacks/"],
+};
+```
+
+## What the public gets during a preview
+
+`200` with a holding page by default, which is right for a pre-launch site collecting
+an email address. Set `publicResponse: "notFound"` when the site's existence is itself
+not public:
+
+```ts
+// config/gate.ts
+export default { publicResponse: "notFound" };
+```
+
+Both are legitimate and the framework does not pick. **Maintenance is always `503`** and
+is not configurable, because that one is not a preference: a maintenance page served at
+`200` tells a search engine that "we will be back shortly" is the content of your
+homepage, and it will index it as such. Sites have lost their rankings to a two-hour
+window served at the wrong status code.
+
+## Where the state lives
+
+`storage/framework/gate.json`, not the database.
+
+A flag in the database is unreadable exactly when the database is the thing you are
+working on, so a maintenance mode kept there works only on the days you did not need
+it. The file is also why the gate survives a restart — an in-memory flag would be
+lifted by the very deploy it was supposed to run behind.
+
+The preview token is stored as a **hash**. The file sits on disk, readable by anything
+on the box and copied by every backup, and putting a live credential in it would be the
+same mistake as an `.env.example` carrying a working key.
+
+A file the gate cannot parse reads as **open**, deliberately. Failing closed would take
+a site down because a JSON file lost a brace, and "the site is up" is the safer error
+for a mechanism whose whole purpose is to be turned off again.
+
+## It covers raw routes too
+
+`Router.raw()` bypasses the middleware pipeline by design — that is what it is for. It
+does **not** bypass the gate.
+
+A gate that covered only the pipeline would be the worst kind, because it gates the
+homepage and therefore looks like it works. This framework's own documentation site
+serves every `/docs/*` page from a raw route: with an early build of the gate on, the
+front page said "coming soon" and every page of content stayed public.
+
+Raw routes get no staff bypass, since no session has been resolved by then — the token
+cookie is the only way through.
+
+## `zt doctor` reports it
+
+A gate is the most reversible thing in the framework and the easiest to forget, because
+when it is working nothing complains: the people who would notice are the ones being
+kept out, and they have no way to tell you.
+
+- **Maintenance in production** is reported as a failure. It is an outage.
+- **A preview in production** is a warning naming who set it and when, since a
+  pre-launch gate is usually deliberate.
+- **A preview whose `until` has passed** is its own warning: the file says the site is
+  gated and it is not, so what a reader believes and what visitors get have come apart.
+
+## Reference
+
+| Name                 | Description                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `Gate`               | Read and write the gate: `maintenance()`, `preview()`, `open()`, `status()`. |
+| `GateStatus`         | What `Gate.status()` returns. Never includes the token.                      |
+| `MaintenanceOptions` | `retryAfter`, `by`.                                                          |
+| `PreviewOptions`     | `token`, `until`, `by`.                                                      |
+| `GateMiddleware`     | The kernel middleware that answers for a closed site.                        |
+| `GateState`          | The shape written to `storage/framework/gate.json`.                          |
+| `GateMode`           | `"maintenance"                                                               | "preview"`. |
+| `readGate`           | Read the state file, or `null` when the site is open.                        |
+| `gateExpired`        | Whether a preview's `until` has passed.                                      |
+| `GATE_FILE`          | Path of the state file, relative to the project root.                        |
+| `GATE_COOKIE`        | Name of the cookie the gate issues.                                          |
+| `GATE_QUERY`         | The query parameter that carries a token — `preview`.                        |
+| `bun zt down`        | `DownCommand` — maintenance on.                                              |
+| `bun zt preview`     | `PreviewCommand` — private preview on, prints the link.                      |
+| `bun zt up`          | `UpCommand` — open the site.                                                 |
+| `bun zt gate:status` | `GateStatusCommand` — what the gate is doing.                                |

package/docs/upgrade.md

@@ -33,6 +33,13 @@ something, and puts the work where it is useful: reading the notes for each mino
 > install 1.11.0, and its breaking change, without asking. Read the notes for every
 > minor you cross, or pin with a tilde (`~1.10.0`) and cross them deliberately.
 
+> **Warning** — **a tilde still crosses a patch**, and under this scheme a patch carries
+> features. `~1.13.2` means `>=1.13.2 <1.14.0`, so it takes 1.13.3 without asking. That is
+> the right default for most apps and it is weaker protection than the same range gives
+> under strict semver, where a patch is only ever a bug fix. If you need the version to
+> 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.
+
 > **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.13.2",
+  "version": "1.13.4",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.13.2"
+    "@zerotal/core": "1.13.4"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.13.2"
+    "@zerotal/orm": "1.13.4"
   },
   "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": [