@zerotal/arch 1.7.2 → 1.7.4

package/api-surface.md

@@ -185,11 +185,11 @@ interface ToolContext = {
   root: string
 }
 
-type BlockOutcome = {    status: 'created';    text: string;} | {    status: 'updated';    text: string;} | {    status: 'unchanged';    text: string;} | {    status: 'conflict';    reason: string;}
+type BlockOutcome = { status: 'created'; text: string } | { status: 'updated'; text: string } | { status: 'unchanged'; text: string } | { status: 'conflict'; reason: string }
 
-type ConfigOutcome = {    status: 'created' | 'updated' | 'unchanged';    text: string;} | {    status: 'conflict';    reason: string;}
+type ConfigOutcome = { status: 'created' | 'updated' | 'unchanged'; text: string } | { status: 'conflict'; reason: string }
 
-type ProbeResult = {    ok: true;    data: unknown;} | {    ok: false;    message: string;}
+type ProbeResult = { ok: true; data: unknown } | { ok: false; message: string }
 
 type ProbeTopic = 'doctor' | 'routes' | 'schema' | 'app-info'
 
@@ -272,7 +272,7 @@ interface ToolOutcome = {
   text: string
 }
 
-type DecodedFrame = {    ok: true;    request: JsonRpcRequest;} | {    ok: false;    failure: JsonRpcFailure;}
+type DecodedFrame = { ok: true; request: JsonRpcRequest } | { ok: false; failure: JsonRpcFailure }
 
 type Era = 'modern' | 'legacy'
 

package/docs/about.md

@@ -43,7 +43,7 @@ a theme.
 
 ### 1. Bun-native, source-only
 
-Zerotal runs **only on Bun** (≥ 1.1) and leans on Bun's APIs throughout — `Bun.sql`
+Zerotal runs **only on Bun** (≥ 1.3.14) and leans on Bun's APIs throughout — `Bun.sql`
 for the database, `Bun.CryptoHasher` for hashing, `Bun.build` for bundling. Because
 Bun runs and type-strips TypeScript natively, packages ship as **`.ts` source with no
 compiled `dist/`**. You always read real source and get accurate types; there's
@@ -660,9 +660,9 @@ The [README](../README.md) has a package-by-package table with links.
   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
   step to remember.
-- **Reference apps are the best teacher.** Full working apps under `apps/` exercise the
-  framework end-to-end — a Flow-based finance app and a Flow + Auth + ORM starter
-  are the most complete real-world examples. Read them alongside the docs.
+- **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`.
+  Read the generated code alongside the docs.
 - **Conventions are documented, not magic.** When something "just works" (a model you
   never registered, a policy suddenly enforced), [Conventions](/docs/conventions)
   explains exactly what the framework discovered and why.

package/docs/changelog.md

@@ -17,12 +17,128 @@ summary across the suite.
 Each version lists changes under three headings:
 
 - **Added** — new features and APIs (safe to adopt incrementally).
-- **Changed** — behavior changes; **breaking** ones are called out explicitly and
-  appear only in major releases.
+- **Changed** — behavior changes; **breaking** ones are called out explicitly, in
+  bold, as **BREAKING**.
 - **Fixed** — bug fixes.
 
-Patch and minor releases are backward compatible. Before taking a **major** release,
-read its section here and apply each migration note.
+Breaking changes belong in major releases, and while the 1.x line is young they may
+also land in a minor or a patch — always labelled, always with migration steps. Read
+the section for every version you cross and apply its migration notes, not only the
+majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
+when that carve-out ends.
+
+## 1.7.4 — 2026-08-21
+
+A debug panel that was reaching production, a column type MySQL would not index, and
+2,060 icons.
+
+### Fixed
+
+- **DevTools no longer appears on a production page.** The provider is gated on the
+  environment, so in production its routes are absent — and the browser client took that as
+  permission to start anyway and "connect to nothing". It did not: it mounted the panel first
+  and discovered the absence afterwards, so an app calling `DevTools.start()` unconditionally
+  served a floating DevTools bar to every visitor, its tabs reading
+  `Could not read the map — HTTP 404`.
+
+  `start()` now probes for the routes and builds nothing unless they answer — no shell, no
+  shadow root, no `EventSource`, no listeners. Any failure (404, offline, CSP) is read as
+  absent. **If your app calls `DevTools.start()`, take this release.**
+
+- **A string column could not carry an index on MySQL.** `table.string()` compiled to `TEXT`
+  on every engine and discarded its `length`, and MySQL refuses to key a TEXT column without
+  a prefix length — so `table.string("email").unique()` failed at `CREATE TABLE`. MySQL now
+  gets `VARCHAR(length)`; SQLite and PostgreSQL keep `TEXT`. `char()` had the same bug and the
+  same fix. Found by the new MySQL suite on its first run against a real server.
+
+### Added
+
+- **`<Icon name="inbox" />` — 2,060 icons, bundled, typed by name.** The set ships inside
+  `@zerotal/flow-ui`, so there is nothing to install and no generator to run: a fresh app gets
+  autocomplete over every name and a compile error on a typo. Rendered on the server as inline
+  SVG, so there is no icon font, no sprite, no request per glyph, and nothing for a strict CSP
+  to block. Four icons are drawn for sign-in flows the set has no name for — `passkey`,
+  `two-factor`, `otp`, `magic-link` — and three brand marks ship for the social-login providers
+  `@zerotal/auth` supports. See [Icons](/docs/flow/icons).
+
+- **The ORM suite runs against MySQL 8 in CI, and the job blocks merges.** The same smoke
+  suite that covers PostgreSQL — schema DDL and `ALTER`, identity columns, CRUD, type
+  round-trips, unique and NOT NULL enforcement, row locks, transaction rollback. MySQL moves
+  from _experimental_ to _supported, hardening_; see the
+  [Support Policy](/docs/support-policy).
+
+### Changed
+
+- **The starters link by route name.** Every hard-coded `href="/about"` in the React and Vue
+  templates now goes through `route()`, and the templates ship the generated route table so a
+  freshly scaffolded app type-checks before its first `zt dev`.
+
+### Documented
+
+- **The HTTP client guide is one page.** Eight pages became one, written from where the
+  package is used — your app calling somebody else's service — with straight URLs instead of
+  a route map threaded through every example. See [HTTP Client](/docs/client).
+
+- **`route()` in Inertia**, for links and for form submissions, including the one thing Inertia
+  adds: a page renders in two processes, so `defineRoutes()` has to run in the SSR entry too.
+  See [Building URLs](/docs/inertia/rendering#building-urls-with-route).
+
+- **Every package changelog has the release headings it was missing.** `[Unreleased]` had
+  accumulated four releases of shipped work — `@zerotal/flow-ui`'s newest heading read
+  `[1.5.0]` while 1.7.3 was on npm. Cutting a release now moves them.
+
+## 1.7.3 — 2026-08-20
+
+Two fields that accepted input and threw it away, and a CI job that was testing nothing.
+
+### Fixed
+
+- **A boolean column could not hold a boolean on PostgreSQL.** `table.boolean()` compiled to
+  `INTEGER` on every engine — right for SQLite, which has no boolean type, and rejected by
+  PostgreSQL, which has a real one:
+
+  ```text
+  column "active" is of type integer but expression is of type boolean   (42804)
+  ```
+
+  Every insert of `true` failed, and so did every `where("active", true)`. The storage type
+  now comes from the dialect, as the auto-increment column already did. SQLite and MySQL are
+  unchanged — MySQL's `BOOLEAN` is a synonym for `TINYINT(1)` and `INTEGER` takes 0/1 either
+  way, so there was nothing broken there to fix.
+
+  **Existing PostgreSQL tables keep their integer columns.** New tables get `BOOLEAN`; a table
+  already created needs an `ALTER` if you want the column converted:
+
+  ```sql
+  ALTER TABLE posts ALTER COLUMN active TYPE boolean USING active <> 0;
+  ```
+
+- **A bound password field discarded every keystroke.** Flow's client-writable set was
+  `fillable` minus `hidden`, which conflates two allow-lists answering different questions:
+  `fillable` governs what may be _written_, `hidden` governs what may be _shown_. A password
+  is in both, so subtracting made it unwritable — `<input type="password"
+value={this.user.password} blur />` accepted typing and dropped it on arrival.
+
+  `hidden` is no longer subtracted. It is still never sent: the stored hash does not leave the
+  server and the field arrives empty. A hidden value **the client supplied** survives until
+  save; one **the server produced** is never echoed back, and a half-typed one is stripped
+  from the durable snapshot before it is persisted.
+
+### Changed
+
+- **The PostgreSQL CI job blocks merges.** It had been running the ORM suite beside a Postgres
+  container without connecting to it, so it reported success without testing anything. A smoke
+  suite now exercises schema DDL, identity columns, CRUD, type round-trips, row locks and
+  transaction rollback against a real PostgreSQL 16, and a failure fails the build. The
+  boolean defect above is what it found on its first real run.
+
+### Documented
+
+- **Flow pages take their model from the route, not from a query.** The docs opened every
+  model example by fetching the record in `onMount()`, which predates a route being able to
+  hand a component the record. `models.md` leads with the bound form; `lifecycle.md` no longer
+  presents the old id-plus-`onHydrate`-re-query as the correct pattern. The old shape still
+  works — it is simply two fields and a query doing what one field now does.
 
 ## 1.7.2 — 2026-08-18
 
@@ -50,7 +166,7 @@ saying so.
 - **Flow bundles the socket client into its runtime.** A page that declares a `socket:`
   listener is live with no script of your own. Flow apps own no bundle entry, so the contract
   used to be "publish `window.Socket` yourself" — and when you didn't, the listeners were
-  *silently inert*: no error, no warning, no subscription, so a live feature with no script
+  _silently inert_: no error, no warning, no subscription, so a live feature with no script
   looked exactly like a live feature that was never written. An app that needs a configured
   client still assigns `window.Socket` before the runtime loads and that one is used as-is; a
   page with no listeners opens no connection at all.
@@ -60,7 +176,7 @@ saying so.
 - **A patch no longer writes back into a file input.** A file input's `value` belongs to the
   user agent, and assigning anything but `""` throws `InvalidStateError`. The write was legal
   while the bound property was empty and threw on the very patch carrying an upload's result
-  — and the throw escaped the frame handler, so the DOM never updated *and* the action's ack
+  — and the throw escaped the frame handler, so the DOM never updated _and_ the action's ack
   never resolved. Since frames are chained per component, every later action queued behind a
   promise that would never settle: the page rendered correctly and ignored every click for
   the rest of its life.

package/docs/client/index.md

@@ -1,35 +1,39 @@
 ---
-title: API Client
-description: Call your HTTP API with full TypeScript inference of params, body, query, and response shapes.
+title: HTTP Client
+description: Call another service from your app — requests, auth, timeouts, retries, errors, and a circuit breaker.
 ---
 
-# API Client
+# HTTP Client
 
-A type-safe HTTP client bound to a route map. The TypeScript compiler infers
-request body types, path parameters, query parameters, and response shapes directly
-from the map — no casting required.
+Your application calling somebody else's: charging a card, sending a message,
+looking up an address. `@zerotal/client` is the outbound HTTP client — a thin,
+expressive wrapper over `fetch` that adds what every real integration ends up
+needing anyway and that is tedious to get right by hand.
 
-This is the **frontend/SPA** client for calling _your own_ typed API. For
-**server-to-server** outgoing HTTP from inside your app, reach for core's `Http`
-facade ([HTTP Client helpers](/docs/context)) instead — it's the fluent,
-fakeable, server-side HTTP client. Same protocol, different jobs.
+```ts
+import { Client } from "@zerotal/client";
+
+const charge = await Client.post("https://api.stripe.com/v1/charges", {
+  amount: 2000,
+  currency: "usd",
+  source: token,
+});
+```
+
+Timeouts, retries with backoff, bearer tokens, a circuit breaker for the upstream
+that has started failing, and errors you can branch on.
+
+> **For requests coming _into_ your app**, see [Routing](/docs/routing). This page is
+> only about requests going out.
 
-## Getting Started
+## Install and register
 
 ```bash
-# in your project root
 bun add @zerotal/client
 ```
 
-You can use the client two ways: create instances yourself with `createApiClient()`
-(typical for the browser/frontend), or register `ClientProvider` to resolve a shared,
-config-driven client from the container (typical for server-side and console code).
-
-## Register the provider
-
-Registering the provider is optional — it gives you one container-bound `client`
-built from `config/client.ts`. Add `ClientProvider` to the providers array in
-`bootstrap/providers.ts`:
+Add `ClientProvider` to `bootstrap/providers.ts` to get one shared, configured
+client from the container:
 
 ```ts
 // bootstrap/providers.ts
@@ -43,26 +47,68 @@ const providers = [
 export default providers;
 ```
 
-Registering the provider switches on the following:
+It binds a client under the `client` key in the `web`, `console`, `worker`, `test`
+and `repl` environments — so a queued job calling a gateway uses the same client a
+controller does — and exposes it as the `Client` facade.
 
-- `onRegister` — binds an `ApiClient` as a lazy singleton under the `client` key, built from the `client` config namespace.
-- `onBooted` — pre-resolves that async singleton so the `Client` facade can be accessed synchronously after boot.
+## Making requests
 
-The provider is active in the `web`, `console`, `worker`, `test`, and `repl`
-environments. Resolve the shared client via the container or the `Client` facade:
+Five methods, each taking a URL. Pass an absolute URL, or set a `baseUrl` in config
+and pass a path:
 
 ```ts
-// in a controller or service
 import { Client } from "@zerotal/client";
 
-const users = await Client.get("/api/users");
+await Client.get("https://api.example.com/v1/invoices");
+await Client.post("https://api.example.com/v1/invoices", { customer: "cus_123" });
+await Client.put("https://api.example.com/v1/invoices/in_9", { memo: "Paid" });
+await Client.patch("https://api.example.com/v1/invoices/in_9", { memo: "Paid" });
+await Client.delete("https://api.example.com/v1/invoices/in_9");
+```
+
+The response body is decoded for you — JSON when the response is JSON, text
+otherwise. A 2xx returns; anything else throws, which [Errors](#errors) covers.
+
+### Query parameters
+
+```ts
+await Client.get("https://api.example.com/v1/charges", undefined, {
+  query: { limit: 25, status: "succeeded", created: { gte: 1_700_000_000 } },
+});
 ```
 
-## Configuration
+Nested objects and arrays are serialized with bracket notation, so
+`{ created: { gte: 1 } }` becomes `created[gte]=1`.
 
-Create `config/client.ts` with the `ClientConfig()` helper (or `satisfies
-ClientConfigShape`) so every field stays type-checked. The shape extends
-[`ApiClientConfig`](/docs/client/references) — every client option below is valid here:
+### Request bodies
+
+A plain object or array is JSON-encoded with the matching `Content-Type`. Anything
+`fetch` understands natively — `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`,
+a raw string — passes straight through, so the runtime sets the header itself
+(including multipart boundaries):
+
+```ts
+// Form-encoded, which several gateways still require
+await Client.post(
+  "https://api.example.com/v1/charges",
+  new URLSearchParams({ amount: "2000", currency: "usd" }),
+);
+```
+
+### Headers
+
+Per request, merged over the client's defaults:
+
+```ts
+await Client.post("https://api.example.com/v1/messages", payload, {
+  headers: { "Idempotency-Key": crypto.randomUUID() },
+});
+```
+
+## Authentication
+
+Most APIs want a bearer token. Set it once and every request carries
+`Authorization: Bearer …`:
 
 ```ts
 // config/client.ts
@@ -70,59 +116,220 @@ import { ClientConfig } from "@zerotal/client";
 import { env } from "zerotal";
 
 export default ClientConfig({
-  baseUrl: env("API_BASE_URL", "https://api.example.com"),
+  baseUrl: "https://api.example.com",
+  token: env("PAYMENTS_API_KEY", ""),
   headers: { Accept: "application/json" },
 });
 ```
 
-| Field             | Required | Default | Description                                                    |
-| ----------------- | -------- | ------- | -------------------------------------------------------------- |
-| `baseUrl`         | no       | `""`    | Base URL prepended to every request path.                      |
-| `headers`         | no       | `{}`    | Default headers sent with every request.                       |
-| `token`           | no       | —       | Bearer token (string or resolver) attached as `Authorization`. |
-| `withCredentials` | no       | `false` | Send cookies (`credentials: 'include'`); also turns CSRF on.   |
-| `csrf`            | no       | —       | CSRF cookie/header names, or a boolean to force on/off.        |
-| `timeout`         | no       | —       | Default per-request timeout in ms (`0`/omitted = none).        |
-| `retry`           | no       | —       | Default retry policy (number of attempts or `RetryOptions`).   |
+A `token` may also be a function, including an async one, which is how credentials
+that expire are handled — it is resolved per request:
 
-> **Note** — The provider carries no framework-level defaults of its own; `ApiClient`
-> applies its own internal defaults. The config file is just typed input.
+```ts
+export default ClientConfig({
+  token: async () => await currentAccessToken(),
+});
+```
 
-## Create a client directly
+Change it at runtime with `setToken(token)`, or pass `null` to clear it. Its type is
+`TokenSource`.
 
-In the browser (or anywhere you want a standalone instance), build a client with
-`createApiClient<Routes>()`:
+For an API that wants something other than a bearer token, set the header directly:
 
 ```ts
-// app/api/client.ts
-import { createApiClient } from "@zerotal/client";
-import { env } from "zerotal";
-import type { Routes } from "./api-types.ts";
+export default ClientConfig({
+  headers: { "X-Api-Key": env("PARTNER_API_KEY", "") },
+});
+```
 
-export const api = createApiClient<Routes>({
-  baseUrl: env("API_BASE_URL", "https://api.example.com"),
-  headers: { Accept: "application/json" },
+### Refreshing on a 401
+
+`onUnauthorized` receives the error and a `retry` function, so a token can be
+refreshed and the original request replayed once:
+
+```ts
+export default ClientConfig({
+  onUnauthorized: async (error, retry) => retry({ Authorization: `Bearer ${await refresh()}` }),
+});
+```
+
+## Timeouts
+
+There is no timeout by default, because the right one depends on the upstream. Set a
+default and override per request:
+
+```ts
+export default ClientConfig({ timeout: 10_000 });
+
+// This one is slow and we accept that
+await Client.post("https://api.example.com/v1/reports", body, { timeout: 60_000 });
+```
+
+`timeout: 0` disables it. Pass your own `signal` to cancel for any other reason; it
+is combined with the timeout rather than replacing it.
+
+## Retries
+
+A network blip or a `503` is worth trying again; a `422` never is. `retry` retries
+idempotent requests on network errors, 5xx and 429 with exponential backoff, and
+honours a `Retry-After` header when the server sends one:
+
+```ts
+export default ClientConfig({ retry: 2 });
+
+await Client.post("https://api.example.com/v1/charges", body, { retry: false });
+```
+
+Turning retries **off** for a charge is the deliberate part: retrying a payment you
+cannot prove failed is how a customer gets billed twice. Send an idempotency key if
+you want both. Pass `RetryOptions` instead of a number to tune the delays and which
+statuses qualify.
+
+## Errors
+
+A non-2xx throws `ApiClientError`, carrying what you need to decide what happened:
+
+```ts
+import { ApiClientError } from "@zerotal/client";
+
+try {
+  await Client.post("https://api.example.com/v1/charges", body);
+} catch (error) {
+  if (error instanceof ApiClientError) {
+    error.status; // 402
+    error.body; // raw response text
+    error.headers; // Headers, when available
+    error.retryAfterMs; // parsed Retry-After, or null
+  }
+  throw error;
+}
+```
+
+A `422` carrying a field-error body throws `ValidationError`, a subclass that reads
+those fields for you — `has(field)`, `first(field)`, `all()`, `fields()`, and
+`validationMessage` for the top-level message.
+
+`onError` fires for every non-2xx before the throw and `onForbidden` for a 403 —
+both good places to log or alert without wrapping each call site.
+
+## Circuit breaker
+
+When an upstream is down, continuing to call it wastes your own capacity and slows
+everything queued behind it. A `CircuitBreaker` stops after a threshold of
+consecutive failures, fails fast for a cooldown, then lets a single request through
+to test the water:
+
+```ts
+export default ClientConfig({
+  circuitBreaker: { threshold: 5, cooldownMs: 30_000 },
 });
 ```
 
-> **Tip** — Don't instantiate `ApiClient` directly; `createApiClient<Routes>(config)`
-> binds the route map type for you.
+While it is open, calls throw `CircuitBreakerOpenError` **without** a request being
+made — catch that specifically to fall back to a cached answer or a queued retry.
+`state` reports the `CircuitState` (`closed`, `open`, `half-open`), `failures` the
+current count, and `reset()` closes it by hand.
+
+Pass a shared `CircuitBreaker` instance instead of options when several clients talk
+to the same upstream and should trip together.
+
+## Files
+
+Upload with `FormData`; download by asking for the body you want:
+
+```ts
+const form = new FormData();
+form.append("file", Bun.file("./invoice.pdf"));
+await Client.post("https://api.example.com/v1/documents", form);
+
+const pdf = await Client.get("https://api.example.com/v1/documents/doc_1", undefined, {
+  responseType: "blob",
+});
+```
+
+`responseType` takes `auto` (the default), `json`, `text`, `blob` or `arrayBuffer`.
+
+## Interceptors
+
+`onRequest` runs before every request and can rewrite the outgoing `RequestConfig`;
+`onResponse` runs after every 2xx with the `ResponseContext`. Both take one function
+or an array:
+
+```ts
+export default ClientConfig({
+  onRequest: (config) => {
+    config.headers["X-Request-Id"] = crypto.randomUUID();
+    return config;
+  },
+});
+```
+
+To read the status or headers of a single response without a global interceptor,
+pass `meta` in the request options.
+
+## Testing
+
+The client calls `fetch`, so a test replaces `fetch`:
+
+```ts
+import { test, expect } from "bun:test";
+
+test("charges the card", async () => {
+  globalThis.fetch = async () => Response.json({ id: "ch_1", paid: true });
+
+  const charge = await Client.post("https://api.example.com/v1/charges", { amount: 2000 });
+  expect(charge.paid).toBe(true);
+});
+```
+
+Return a non-2xx `Response` to cover the failure paths, and throw from the stub to
+exercise retries and the breaker. For requests your app _receives_ in tests, see
+[Testing](/docs/testing).
+
+## Configuration reference
+
+Every field of `ClientConfigShape` (which extends `ApiClientConfig`) is optional:
+
+| Field             | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `baseUrl`         | Prepended to every request path. Omit it and pass absolute URLs.            |
+| `headers`         | Default headers for every request.                                          |
+| `token`           | Bearer token — a string, or a (possibly async) resolver called per request. |
+| `timeout`         | Default per-request timeout in ms. `0` disables.                            |
+| `retry`           | Default retry policy — a count, or `RetryOptions`.                          |
+| `circuitBreaker`  | A `CircuitBreaker` instance to share, or options for a dedicated one.       |
+| `withCredentials` | Send cookies (`credentials: 'include'`), and turn CSRF on.                  |
+| `csrf`            | CSRF cookie/header names, or a boolean.                                     |
+| `onRequest`       | Interceptor(s) run before every request.                                    |
+| `onResponse`      | Interceptor(s) run after every 2xx.                                         |
+| `onError`         | Called for every non-2xx before the error is thrown.                        |
+| `onUnauthorized`  | Called on 401, with a `retry` function.                                     |
+| `onForbidden`     | Called on 403.                                                              |
+
+Per-request options — `RequestOptions`, plus `query` on `GetOptions` and
+`params`/`query` on `MutationOptions` — override the client's defaults: `headers`,
+`timeout`, `retry`, `responseType`, `signal`, `init` and `meta`.
+
+## Calling your own API
+
+Everything above treats a URL as a string, which is the right trade for a service
+you hit a handful of endpoints on. Nobody should describe someone else's API in
+types to send three requests to it.
+
+If you are calling **your own** API repeatedly, `createApiClient<Routes>(config)`
+binds a route map, so paths, params, query and response types are inferred and a
+renamed endpoint becomes a build error. It returns the same `ApiClient` with a
+narrower type; the `Client` facade above is bound to the base map and answers
+`unknown`. The route-map types are listed in the [API reference](/docs/api).
 
-## The rest of the guide
+## Realtime
 
-| Page                                       | What it covers                                                                 |
-| ------------------------------------------ | ------------------------------------------------------------------------------ |
-| [Requests](/docs/client/requests)          | The typed route map, making requests, and shaping them with interceptors.      |
-| [Authentication](/docs/client/auth)        | Bearer tokens, CSRF, and refreshing credentials on a 401.                      |
-| [Error Handling](/docs/client/errors)      | What a failed request throws, and how to tell the failure modes apart.         |
-| [Resilience](/docs/client/resilience)      | Timeouts, retries, and the circuit breaker that spares a failing upstream.     |
-| [File Transfers](/docs/client/files)       | Uploading and downloading binary payloads.                                     |
-| [Testing the Client](/docs/client/testing) | Stub the global fetch, cover the failure paths, and drive the circuit breaker. |
-| [References](/docs/client/references)      | Every ApiClient method, config key, and error type in one table.               |
+This package also ships `Socket`, `Channel` and `PresenceChannel` — a WebSocket
+client speaking Zerotal's broadcast protocol. Different job, documented where it is
+used: [Broadcasting → Client](/docs/broadcasting/client).
 
 ## Next steps
 
-- [Rate Limiting](/docs/rate-limiting) — throttle outbound and inbound traffic.
-- [Authentication](/docs/authentication) — issue the tokens your interceptors attach.
-- [Validator](/docs/validator) — the server side that produces the `ValidationError` body.
-- [Telemetry](/docs/telemetry) — observe request failures and circuit state.
+- [Rate Limiting](/docs/rate-limiting) — throttle what you send and what you accept.
+- [Telemetry](/docs/telemetry) — trace outbound calls and watch circuit state.
+- [Queues](/docs/queue) — where a slow or flaky integration usually belongs.

package/docs/contributing.md

@@ -8,7 +8,7 @@ description: Get the Zerotal monorepo running locally and pass the checks your c
 Zerotal is a Bun-native monorepo of composable packages. This guide covers getting the
 repo running locally, the project layout, and the checks your change needs to pass.
 
-> **Warning** — Bun ≥ 1.1 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
+> **Warning** — Bun ≥ 1.3.14 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
 
 ## Getting set up
 
@@ -32,7 +32,7 @@ packages/        # the framework — one directory per @zerotal/* package
   auth/  cache/  queue/  …  # feature packages
   testing/       #   factories, fakes, test app harness
   create-zerotal/ #   the `bun create zerotal` scaffolder
-apps/            # example apps used for end-to-end testing and the docs site
+apps/            # applications in this workspace
   docs/          #   this documentation site
 docs/            # the markdown documentation (what you're reading)
 ```
@@ -149,6 +149,24 @@ that keeps it complete.
 The same rule governs a page's own length: a section that has grown into a second
 subject is a sign it wants to be its own page, or to move to the one that owns it.
 
+## Changelogs
+
+Each package keeps its own `CHANGELOG.md`. Add what you changed under
+`## [Unreleased]` in the package you changed — that is where in-flight work
+belongs, and the entry travels with the code rather than being reconstructed later.
+
+Cutting a release moves those entries under the version, which is a step and not an
+automatic consequence:
+
+```bash
+bun run changelog:release 1.7.4
+```
+
+Skipping it is how `[Unreleased]` came to hold four releases of shipped work —
+`@zerotal/flow-ui`'s newest heading read `[1.5.0]` while 1.7.3 was on npm. Someone
+upgrading reads "Unreleased" and concludes none of it is in the version they are
+taking, when all of it is.
+
 ## Pull requests
 
 - Keep PRs focused — one logical change per PR.