@zerotal/arch 1.7.3 → 1.7.4

package/docs/flow/icons.md

@@ -0,0 +1,199 @@
+---
+title: Icons
+description: 2,060 icons bundled with Flow's component library — typed by name, rendered on the server, nothing to install.
+---
+
+# Icons
+
+`<Icon>` draws an icon by name. The set ships inside `@zerotal/flow-ui`, so this
+works in a new app with nothing installed and nothing configured:
+
+```tsx
+import { Icon } from "@zerotal/flow-ui";
+
+<Icon name="inbox" />
+<Icon name="chevron-right" />
+<Icon name="trash-2" class="size-5 text-red-600" />
+```
+
+The name is a union of every bundled icon, so a typo is a compile error rather
+than a blank space nobody notices until it is in front of a user:
+
+```text
+Type '"inbxo"' is not assignable to type 'IconName'. Did you mean '"inbox"'?
+```
+
+That works on install — there is no generator to run first. The icons belong to
+the framework, so the names are known before your app exists.
+
+## Props
+
+`IconProps` — anything else you pass lands on the rendered `<svg>`.
+
+| Prop    | Type       | Description                                                                    |
+| ------- | ---------- | ------------------------------------------------------------------------------ |
+| `name`  | `IconName` | Which icon. Checked at compile time against the bundled and registered names.  |
+| `label` | `string`   | Accessible name. Omit for decoration — the icon is hidden from screen readers. |
+| `class` | `string`   | Merged with the defaults rather than replacing them.                           |
+
+## Sizing and colour
+
+An icon is `1em` square and painted in `currentColor`, so by default it matches
+the text it sits beside — size, weight of colour, and all. Override with classes
+rather than attributes:
+
+```tsx
+<p class="text-sm text-slate-600">
+  <Icon name="info" /> Saved a moment ago
+</p>
+
+<Icon name="triangle-alert" class="size-8 text-amber-500" />
+```
+
+Sizing through CSS is what lets an icon line up with a label without either being
+measured. `class="size-5"` sets both dimensions; `text-red-600` on the icon — or
+on anything above it — colours it.
+
+## Labelling
+
+An icon is decoration by default and hidden from screen readers, which is right
+when it sits next to text that already says the same thing. Announcing it there
+would read the meaning out twice.
+
+An icon that is the **only** content of a control is not decoration. Without a
+label, that button has no accessible name at all:
+
+```tsx
+<button onClick={this.remove}>
+  <Icon name="trash-2" label="Delete order" />
+</button>
+```
+
+## A name that isn't known until runtime
+
+A name from a database column or a URL segment is not a literal, so it does not
+satisfy the union. `isIconName()` narrows it:
+
+```tsx
+import { Icon, isIconName } from "@zerotal/flow-ui";
+
+override async render() {
+  const glyph = this.status.icon; // string, from a row
+  return isIconName(glyph) ? <Icon name={glyph} /> : <Icon name="circle-help" />;
+}
+```
+
+It is a shape check, not an existence check — it says the string could name an
+icon, not that anything answers to it. An icon that resolves to nothing renders
+nothing rather than throwing, because taking a page down over a missing glyph is
+the worse failure.
+
+## Drawn for the gaps
+
+Four names are drawn here rather than coming from the set, because the flows they
+label are ones Zerotal ships and the set has no icon for as a concept:
+
+| Name         | For                                                            |
+| ------------ | -------------------------------------------------------------- |
+| `passkey`    | WebAuthn sign-in — a fingerprint that ends in a key            |
+| `two-factor` | TOTP — a second device that has to agree                       |
+| `otp`        | An emailed one-time code — the separate slots it is typed into |
+| `magic-link` | Passwordless sign-in by link                                   |
+
+The set has `key-round`, `fingerprint` and `shield-check` — the parts — and a login
+page needs the whole. They are drawn on the same 24×24 stroke grid, so they sit
+beside the other 2,060 without announcing themselves.
+
+Nearly everything else that looked missing was there under a name that reads
+differently: `git-branch` not `branch`, `file-json` not `json`, `paperclip` not
+`attachment`, `venetian-mask` for impersonation. Search before you draw.
+
+## Brand marks
+
+Three sign-in providers ship as brand marks, because `@zerotal/auth` has a code
+path for each and a sign-in button wants the provider's actual logo:
+
+```tsx
+<button><Icon name="brand-google" /> Continue with Google</button>
+<button><Icon name="brand-github" /> Continue with GitHub</button>
+<button><Icon name="brand-apple" /> Continue with Apple</button>
+```
+
+They come from [Simple Icons](https://simpleicons.org) (**CC0-1.0**, public
+domain), so the paths are the real ones rather than approximations — an
+approximated logo reads as a forgery, not as an icon.
+
+The `brand-` prefix is deliberate: the bundled set has its own stroke-style
+`github` and `apple`, and prefixing means neither silently shadows the other, so a
+page picks a style rather than inheriting one. There is no plain `google` — the
+set never had one, which is what made this worth doing.
+
+Unlike the rest, brand marks are **solid**: each body carries its own
+`fill="currentColor"`, so it still takes its colour from the text around it.
+
+> **CC0 covers copyright, not trademark.** The marks belong to their owners.
+> Labelling a sign-in button with one is nominative use and what brand guidelines
+> contemplate; using one as your own logo is not. For a provider not listed here,
+> `registerIcons()` keeps that decision — and its licence — yours.
+
+## Your own icons
+
+A wordmark, a product glyph, a shape nobody has drawn: register it once, from a
+provider's `register()`, and it is available everywhere `<Icon>` is.
+
+```ts
+import { registerIcons } from "@zerotal/flow-ui";
+
+registerIcons({
+  "acme-wordmark": {
+    body: '<path fill="currentColor" d="M4 4h16v16H4z"/>',
+  },
+});
+```
+
+Each entry is an `IconBody` — the markup that goes **inside** the `<svg>`, plus an
+optional `width`/`height` when it was drawn against a box other than 24×24. A name
+you register shadows a bundled one, which is how you substitute your own drawing
+without renaming every call site.
+
+Registering supplies the body; the compiler needs telling separately. Declare the
+names on `CustomIconRegistry` and they join the same union as the bundled ones —
+`IconName` widens, and `CustomIconName` is the set you added:
+
+```ts
+declare module "@zerotal/flow-ui" {
+  interface CustomIconRegistry {
+    "acme-wordmark": true;
+  }
+}
+```
+
+> **The body is inserted as markup, not text.** Register only SVG you control.
+> A body built from user input is the same hole as any other unescaped HTML.
+
+### Matching the set
+
+Icons drawn to a different grid look wrong beside ones that aren't. The bundled
+set is 24×24 **stroke**: no fills, `stroke="currentColor"`, `stroke-width="2"`,
+round caps and joins. Copy the shape of an existing icon rather than exporting
+from a design tool, which will hand you absolute fills on a half-pixel grid.
+
+## What ships, and why it can
+
+The bundled set is [Lucide](https://lucide.dev), which is ISC-licensed — the
+reason it can be shipped inside the package at all. Redistributing it carries a
+notice (`LICENSE-ICONS.md` in `@zerotal/flow-ui`) and asks nothing of your
+application's UI.
+
+Most sets are not so simple. Font Awesome Free is CC BY 4.0 — usable, and only
+with attribution _you_ would have to display — and Font Awesome Pro may not be
+redistributed at any price. Bundling either would relicense someone else's artwork
+on behalf of every app that installed Flow. If you are entitled to a set we cannot
+ship, `registerIcons()` is how you bring it: your artwork, your licence.
+
+## Cost
+
+None on the client. Flow renders on the server, so an icon reaches the browser as
+markup that is already in the page — no icon font, no sprite sheet, no request per
+glyph, and nothing for a strict [Content Security Policy](/docs/flow/performance)
+to block. The set is read once per process and never sent.

package/docs/inertia/index.md

@@ -162,7 +162,7 @@ export default function Dashboard({ posts, auth }: Props) {
       <h1>Dashboard</h1>
       {auth.user && <p>Welcome back, {auth.user.name}</p>}
       {posts.map((post) => (
-        <Link key={post.id} href={`/posts/${post.slug}`}>
+        <Link key={post.id} href={route("posts.show", { slug: post.slug })}>
           {post.title}
         </Link>
       ))}
@@ -176,6 +176,11 @@ Note `auth` is available without the controller passing it — see
 [`make:page`](/docs/inertia/build#generating-a-page) and bundle them with
 [`inertia:build`](/docs/inertia/build#building-assets).
 
+`route("posts.show", { slug })` builds the URL from the route's **name** rather than
+hard-coding the path, so renaming a route updates every link to it and a typo fails
+the build. Prefer it over a literal `href` anywhere you link — see
+[Building URLs](/docs/inertia/rendering#building-urls-with-route).
+
 ## Testing
 
 Set your suite up once as described in [Testing](/docs/testing). An Inertia route

package/docs/inertia/props.md

@@ -339,7 +339,7 @@ export default function Page() {
   return (
     <>
       {flash.success && <div className="toast">{flash.success}</div>}
-      {auth.user ? <span>{auth.user.name}</span> : <a href="/login">Sign in</a>}
+      {auth.user ? <span>{auth.user.name}</span> : <a href={route("login")}>Sign in</a>}
     </>
   );
 }

package/docs/inertia/rendering.md

@@ -147,6 +147,85 @@ array** directly as a shorthand. To use both, pass props third and middleware fo
 Router.inertia("/admin", "Admin/Dashboard", { title: "Admin" }, [AuthMiddleware]);
 ```
 
+## Building URLs with route()
+
+A hard-coded `href="/posts/hello"` is a string nothing checks. Rename the route and
+every link to it keeps compiling and starts 404ing — a bug that surfaces when
+someone clicks, not when someone builds.
+
+Name the route instead, and let the URL be derived:
+
+```tsx
+import { Link } from "@inertiajs/react";
+
+<Link href={route("posts.show", { slug: post.slug })}>{post.title}</Link>
+<Link href={route("posts.index", {}, { page: 2 })}>Next</Link>
+```
+
+No import for `route` — `defineRoutes()` installs it globally, and the names are
+checked against the same registry your controllers use, so `route("posts.shwo")`
+fails the build. [Routing](/docs/routing#route-in-the-browser) owns the mechanics:
+the generated table, wiring your entry point, typing, and `route.dynamic()` for a
+name only known at runtime.
+
+### Forms submit to a name too
+
+A form's action is the same kind of string as a link's `href`, and gets the same
+treatment. `useForm()` and `router` both take a URL, so hand them one that was built
+from the route name:
+
+```tsx
+import { useForm, router } from "@inertiajs/react";
+
+export default function Edit({ post }: Props) {
+  const form = useForm({ title: post.title, body: post.body });
+
+  const submit = (e: React.FormEvent) => {
+    e.preventDefault();
+    form.put(route("posts.update", { slug: post.slug }));
+  };
+
+  const destroy = () => {
+    router.delete(route("posts.destroy", { slug: post.slug }));
+  };
+
+  return (
+    <form onSubmit={submit}>
+      <input value={form.data.title} onChange={(e) => form.setData("title", e.target.value)} />
+      {form.errors.title && <span>{form.errors.title}</span>}
+      <button disabled={form.processing}>Save</button>
+      <button type="button" onClick={destroy}>
+        Delete
+      </button>
+    </form>
+  );
+}
+```
+
+The names follow the same convention the router generates: a `POST` is
+`posts.store`, `PUT`/`PATCH` is `posts.update`, `DELETE` is `posts.destroy`. So the
+name in the component and the route the controller is mounted on cannot drift apart
+silently — change the URL and both ends move together.
+
+This matters more for a form than for a link. A broken link 404s where someone can
+see it; a form posting to a stale URL fails **after** the user has filled it in, and
+the data goes with it.
+
+Build the URL the same way for [Precognition](/docs/inertia/props#precognition), so
+live validation and the real submit cannot end up aimed at different routes — the
+failure there is a form that validates clean and then rejects on save.
+
+### One thing Inertia adds: define the routes in _both_ entries
+
+An Inertia page renders twice — once in the SSR process, once in the browser — so a
+component calling `route()` runs in both. A table defined in only one of them throws
+in the other: miss the SSR entry and `POST /__ssr` answers `500` with
+`[Inertia] SSR render failed` in the log, for a page the browser then renders
+perfectly well.
+
+Call `defineRoutes(ROUTES)` in your browser entry **and** in your
+[SSR entry](/docs/inertia/ssr). Same static import, same table.
+
 ## Redirects
 
 After a non-GET action (a form POST/PUT/DELETE), redirect as usual — return a 302 and

package/docs/support-policy.md

@@ -49,11 +49,11 @@ course?", so this is it:
 
 ## Databases
 
-| Database   | Status                                                                                                                                                                                                                                                                                                                                 |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                                                                                                                                                            |
-| PostgreSQL | Supported. A smoke suite runs against a real PostgreSQL 16 on every merge — schema DDL, identity columns, CRUD, type round-trips, row locks and transaction rollback — and the job blocks a merge when it fails. The bulk of the ORM suite still runs on SQLite, so coverage of the Postgres path is narrower than of the default one. |
-| MySQL      | Experimental. The ORM ships a MySQL dialect and the scaffolder can configure it, but no CI suite runs against a real MySQL server yet — treat it as unverified until it joins the tested matrix.                                                                                                                                       |
+| Database   | Status                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                                                                                                                                                                                                       |
+| PostgreSQL | Supported. A smoke suite runs against a real PostgreSQL 16 on every merge — schema DDL and `ALTER`, identity columns, CRUD, type round-trips, unique and NOT NULL enforcement, row locks and transaction rollback — and the job blocks a merge when it fails. The bulk of the ORM suite still runs on SQLite, so the Postgres path is covered more narrowly than the default one. |
+| MySQL      | Supported, hardening. The same smoke suite runs against a real MySQL 8 on every merge and blocks on failure. It is newer than the Postgres job and has found one defect already (`string()` was not indexable), so treat MySQL as verified in the paths the suite covers and less proven than PostgreSQL outside them.                                                            |
 
 Redis-backed drivers (cache, session, queue, broadcasting) build on
 `Bun.RedisClient` and are tested against the protocol surface it provides.
@@ -100,6 +100,21 @@ a contract, not a mood:
 - **experimental** — no compatibility promise. The API may change or the package
   may be absorbed into another in any release. Build on it with your eyes open.
 
+### A label below stable carries a review date
+
+An honest "experimental" is useful once and corrosive indefinitely: a package that
+has worn the label for a year is not being cautious, it is unowned. So each one
+below `stable` names the release by which it is reviewed, and the review has three
+outcomes — promote, keep with a new date and the reason, or withdraw.
+
+| Package         | Now            | Reviewed by |
+| --------------- | -------------- | ----------- |
+| `@zerotal/ai`   | `experimental` | **1.9.0**   |
+| `@zerotal/arch` | `beta`         | **1.9.0**   |
+
+Neither is in the `zerotal` meta-package and nothing `stable` depends on either,
+so the cost of the label falling due is ours and not yours.
+
 A package is never more mature than what it is built on: a stable package whose
 foundation can change under it is not stable, whatever its own label says. So
 `@zerotal/admin` and `@zerotal/monitor` cannot pass `@zerotal/flow`, and the

package/package.json

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

package/docs/client/auth.md

@@ -1,113 +0,0 @@
----
-title: Client Authentication
-description: Bearer tokens, CSRF, and refreshing credentials on a 401.
----
-
-# Authentication & CSRF
-
-The client supports the two ways a browser app proves who it is, and the choice is
-usually made for you by where the API lives:
-
-- **Bearer tokens** suit APIs on another origin, mobile clients, and anything where
-  the caller holds a credential it can attach itself.
-- **Session cookies** suit an API served from your own domain, where the browser
-  already carries the session and CSRF protection is the concern instead.
-
-## Bearer tokens
-
-Attach a bearer token (string or a resolver, sync or async) without writing an interceptor —
-update it at runtime with `setToken()`:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  token: () => authStore.accessToken, // re-read on every request
-});
-api.setToken(freshToken); // or update imperatively
-```
-
-Prefer the resolver form. A plain string is captured once at construction, so a
-token refreshed later never reaches the client; a function is consulted on every
-request and always sees the current value.
-
-Calling `setToken()` with no argument clears the token, which is what a logout
-should do — otherwise the next request still carries the credential of the user who
-just signed out.
-
-> **Note** — The `token` is only applied when no `Authorization` header is already
-> present on the request, so a per-request override always wins.
-
-## Session cookies and CSRF
-
-For session/cookie (SPA) auth, set `withCredentials` to send cookies, which also turns on CSRF:
-the client reads the `XSRF-TOKEN` cookie and sends it as `X-XSRF-TOKEN` on mutating requests
-(matching the session/CSRF middleware). Customize the names with `csrf`:
-
-```ts
-// app/api/client.ts
-createApiClient<Routes>({
-  withCredentials: true, // credentials: 'include' + CSRF on
-  csrf: { cookie: "XSRF-TOKEN", header: "X-XSRF-TOKEN" }, // defaults shown
-});
-```
-
-Enabling `withCredentials` turns CSRF on by default, so the two travel together and
-neither needs configuring in the common case. Set `csrf: false` to opt out, or pass
-an object to rename the cookie and header to match a server that uses different
-ones.
-
-The token is attached only to mutating requests — `POST`, `PUT`, `PATCH`, `DELETE`.
-A `GET` is exempt because it should not change state, so it needs no protection
-from being triggered cross-site. If a `GET` in your API does change something, that
-is the thing to fix; adding a CSRF header to it would only hide the problem.
-
-The header is skipped when the request already carries one, so a caller that sets
-its own value keeps it.
-
-## 401 / token refresh
-
-`onUnauthorized` is called when any request receives a 401 response. It receives
-the error and a `retry` function. Call `retry()` — optionally with header overrides
-— to re-execute the failed request. The retry is limited to **one attempt**.
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-
-  onUnauthorized: async (err, retry) => {
-    const newToken = await authStore.refresh();
-    return retry({ Authorization: `Bearer ${newToken}` });
-  },
-});
-```
-
-If `onUnauthorized` is not provided or does not call `retry`, the 401 error is
-thrown normally.
-
-The single-attempt limit is deliberate: a refresh that itself returns 401 would
-otherwise retry forever, turning an expired session into an endless loop of
-requests. When the retry also fails, the error is thrown and the app can send the
-user to the login screen.
-
-One case the hook does not solve on its own is a page that fires several requests
-at once. Each 401 calls `onUnauthorized` separately, so a naive handler triggers
-several concurrent refreshes and the losers of that race may invalidate the winner's
-token. Have the refresh itself de-duplicate — cache the in-flight promise in your
-auth store and hand the same one to every caller until it settles:
-
-```ts
-// app/api/authStore.ts
-let inflight: Promise<string> | null = null;
-
-export function refresh(): Promise<string> {
-  inflight ??= requestNewToken().finally(() => (inflight = null));
-  return inflight;
-}
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Error handling](/docs/client/errors) — the errors a rejected request throws.
-- [CSRF protection](/docs/csrf) — the server side of the cookie and header pair.

package/docs/client/errors.md

@@ -1,139 +0,0 @@
----
-title: Client Error Handling
-description: What a failed request throws, and how to tell the failure modes apart.
----
-
-# Error handling
-
-Non-2xx responses throw `ApiClientError`:
-
-```ts
-// in any frontend module
-import { ApiClientError } from "@zerotal/client";
-
-try {
-  await api.post("/api/users", { name: "", email: "bad" });
-} catch (err) {
-  if (err instanceof ApiClientError) {
-    console.log(err.status); // 422
-    console.log(err.statusText); // 'Unprocessable Entity'
-    console.log(err.body); // raw response text (the error message truncates it to 200 chars)
-  }
-}
-```
-
-## Telling the failure modes apart
-
-Two very different things can go wrong, and only one of them produces an
-`ApiClientError`:
-
-| What happened                    | What is thrown                      |
-| -------------------------------- | ----------------------------------- |
-| The server answered with non-2xx | `ApiClientError`                    |
-| A 422 in the validator's shape   | `ValidationError`                   |
-| The circuit breaker is open      | `CircuitBreakerOpenError`           |
-| No answer at all                 | The platform's own error, unwrapped |
-
-That last row is the one worth internalising. A DNS failure, a dropped connection,
-a CORS rejection, or an aborted request never reaches the point where a status
-exists, so `fetch` rejects with its own error and the client passes it through
-untouched. An `instanceof ApiClientError` check therefore does _not_ catch an
-offline user — and a `catch` block that assumes `err.status` exists throws a second
-error while handling the first.
-
-```ts
-try {
-  await api.get("/api/users");
-} catch (err) {
-  if (err instanceof ValidationError) showFieldErrors(err.errors);
-  else if (err instanceof ApiClientError) showStatus(err.status);
-  else showOffline(); // no response: network, CORS, timeout, or abort
-}
-```
-
-Timeouts and cancellations land in that final branch too, since both abort the
-request rather than producing a response.
-
-## Reading response headers
-
-`ApiClientError` carries the response headers when there were any, which is where
-rate limiters and throttles put the information you need to react well:
-
-```ts
-// in any frontend module
-if (err instanceof ApiClientError && err.status === 429) {
-  const waitMs = err.retryAfterMs; // parsed Retry-After, or null
-  if (waitMs !== null) scheduleRetry(waitMs);
-  console.log(err.headers?.get("X-RateLimit-Remaining"));
-}
-```
-
-`retryAfterMs` handles both forms the header takes — a delta in seconds and an
-HTTP-date — and returns milliseconds, or `null` when the header is absent or
-cannot be parsed.
-
-## Global handlers
-
-The `onError` callback fires for every non-2xx response before the error is thrown.
-Use it for global side-effects (toasts, logging) without needing try/catch at every
-call site:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-  onError: (err) => {
-    toast.error(`${err.status}: ${err.statusText}`);
-    logger.error("api_error", { status: err.status, body: err.body });
-  },
-});
-```
-
-> **Warning** — `onError` fires for every non-2xx error including 401, even when `onUnauthorized` is also configured. To suppress the global error callback for 401 during token refresh, guard by status inside `onError`.
-
-Because `onError` only ever sees responses, it does not report the network failures
-described above. Reporting that should also cover "the request never arrived"
-belongs in the caller, or in a wrapper around it.
-
-### Typed validation errors
-
-A `422` response whose body matches the framework's validation shape (`{ message, errors }`,
-as produced by [`@zerotal/validator`](/docs/validator)) throws a `ValidationError` — an
-`ApiClientError` subclass with the field errors already parsed:
-
-```ts
-// in any frontend module
-import { ValidationError } from "@zerotal/client";
-
-try {
-  await api.post("/api/users", form);
-} catch (err) {
-  if (err instanceof ValidationError) {
-    setFieldErrors(err.errors); // { email: ["…"], password: ["…"] }
-    err.has("email"); // boolean
-    err.first("email"); // first message, or undefined
-    err.fields(); // ["email", "password"]
-    err.validationMessage; // "The given data was invalid."
-  }
-}
-```
-
-Check for `ValidationError` before `ApiClientError`. It is a subclass, so the
-broader check also matches it and would swallow the parsed field errors.
-
-A 422 whose body does not match that shape stays a plain `ApiClientError`, so an
-endpoint returning its own error format still surfaces as an ordinary failure
-rather than quietly producing an empty `errors` object.
-
-`onForbidden` is the 403 counterpart of `onUnauthorized`:
-
-```ts
-// app/api/client.ts
-createApiClient<Routes>({ onForbidden: () => router.push("/403") });
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Resilience](/docs/client/resilience) — retries, timeouts, and the circuit breaker.
-- [Authentication](/docs/client/auth) — the 401 refresh hook.