@zerotal/arch 1.7.3 → 1.7.5

package/docs/seeding.md

@@ -57,7 +57,7 @@ Put your inserts here — create records through your models or factories exactl
 would in application code. Because seeders run through the ORM, casts, hooks, and
 relationships all behave normally:
 
-```ts
+```ts fragment
 // database/seeders/UserSeeder.ts
 import { Seeder } from "@zerotal/orm";
 import { User } from "../../app/models/User.ts";
@@ -83,7 +83,7 @@ failure still rolls back independently. Where there is no database connection
 bound at all — a seeder that writes fixtures to disk, say — the run is left
 alone rather than failing for want of a transaction it never needed.
 
-```ts
+```ts fragment
 // database/seeders/DatabaseSeeder.ts
 import { Seeder, DB } from "@zerotal/orm";
 import { UserSeeder } from "./UserSeeder.ts";
@@ -133,7 +133,7 @@ yourself (`await new UserSeeder().run()`) to set up just the rows that test need
 [Factories](/docs/orm/factories) are the cleanest way to generate seed records.
 Define them once, then call them from a seeder's `run()`:
 
-```ts
+```ts fragment
 // database/seeders/PostSeeder.ts
 import { Seeder } from "@zerotal/orm";
 import { UserFactory } from "../factories/UserFactory.ts";
@@ -165,7 +165,7 @@ helper.
 Set your suite up once as described in [Testing](/docs/testing). A seeder is a
 class with a `run()` method, so testing one is just calling it:
 
-```typescript
+```typescript fragment
 // tests/seeders/RoleSeeder.test.ts
 import { test } from "bun:test";
 import { assertDatabaseCount, assertDatabaseHas } from "@zerotal/testing";
@@ -183,7 +183,7 @@ test("seeds the three baseline roles", async () => {
 a deploy runs on every release — must not double its rows. This is the failure
 seeders actually have:
 
-```typescript
+```typescript fragment
 // tests/seeders/RoleSeeder.test.ts
 test("running twice does not duplicate rows", async () => {
   await new RoleSeeder().run();
@@ -199,7 +199,7 @@ If that fails, the seeder needs `updateOrCreate` rather than `create`.
 seeder can assert the all-or-nothing behaviour directly — make a late child throw
 and check that the earlier one left nothing behind:
 
-```typescript
+```typescript fragment
 // tests/seeders/DatabaseSeeder.test.ts
 test("a failing child rolls the whole run back", async () => {
   await expect(new DatabaseSeeder().run()).rejects.toThrow();

package/docs/session.md

@@ -113,7 +113,7 @@ registered. Both `ctx.session` and `Session` expose the same methods (see the
 
 ## Reading and writing
 
-```typescript
+```typescript fragment
 // in a controller
 import type { HttpContext } from "zerotal";
 
@@ -149,7 +149,7 @@ Flash stores a value for **one subsequent request only** — it is automatically
 swept after the next request. The canonical use case is POST-Redirect-GET status
 messages.
 
-```typescript
+```typescript fragment
 // in a controller — survives exactly one redirect
 ctx.session.flash("success", "Post created!");
 ctx.session.flash("errors", { title: ["Required"] });
@@ -164,7 +164,7 @@ Session.flash("success", "Post created!");
 
 Read on the next request:
 
-```typescript
+```typescript fragment
 // in a controller
 const msg = ctx.flashed<string>("success");
 const errors = ctx.flashed<Record<string, string[]>>("errors");
@@ -172,7 +172,7 @@ const errors = ctx.flashed<Record<string, string[]>>("errors");
 
 Full POST-Redirect-GET pattern:
 
-```typescript
+```typescript fragment
 // in a controller
 async store(ctx: HttpContext) {
   await Post.create(await ctx.body());
@@ -191,7 +191,7 @@ async index(ctx: HttpContext) {
 Always regenerate the session ID after a privilege change (login, logout, password
 change) to prevent session-fixation attacks:
 
-```typescript
+```typescript fragment
 // in a controller
 ctx.session.regenerate(); // issues a new session ID; data is preserved
 // or: Session.regenerate();
@@ -228,7 +228,9 @@ import { SessionConfig } from "@zerotal/session";
 import { env } from "zerotal";
 
 export default SessionConfig({
-  driver: env("SESSION_DRIVER", "cookie"),
+  // One of 'cookie' | 'redis', written literally: the field is that union and
+  // `env()` returns a plain string.
+  driver: "cookie",
   // …
 });
 ```
@@ -243,7 +245,7 @@ export default SessionConfig({
 Unlike `SessionMiddleware`, it is **not** auto-registered — add it after the session
 middleware, typically in the `web` middleware group:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts (or wherever you register middleware)
 import { SessionMiddleware, CsrfMiddleware } from "@zerotal/session";
 
@@ -279,7 +281,7 @@ it as a header:
 <meta name="csrf-token" content="${CsrfMiddleware.token()}" />
 ```
 
-```typescript
+```typescript fragment
 // in your client JS
 const token = document.querySelector('meta[name="csrf-token"]')?.getAttribute("content");
 
@@ -326,7 +328,7 @@ session itself prefer the facade.
 reads `session.get("user_id")`, looks the user up with a callback you supply, and
 attaches the result to `ctx.user` for the rest of the request.
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { AuthSessionMiddleware, CookieDriver } from "@zerotal/session";
 import { env } from "zerotal";
@@ -346,7 +348,7 @@ app.use(
 Pre-seed session data with `withSession()`, then assert on the response with
 `assertSessionHas()`:
 
-```typescript
+```typescript fragment
 // in a test
 import { createTestApp } from "@zerotal/testing";
 
@@ -355,7 +357,7 @@ const res = await testApp.withSession({ locale: "fr", cart: [1, 2, 3] }).get("/c
 res.assertOk();
 ```
 
-```typescript
+```typescript fragment
 // in a test
 const res = await testApp.post("/locale", { locale: "fr" });
 
@@ -363,7 +365,7 @@ res.assertSessionHas("locale");
 res.assertSessionHas("locale", "fr");
 ```
 
-```typescript
+```typescript fragment
 // in a test — assert a flash key was written before a redirect
 const res = await testApp.actingAs(user).post("/posts", { title: "Hello" });
 
@@ -424,7 +426,7 @@ stores the whole session in the cookie itself, so putting a user object — or a
 flash message with a stack trace — into the session overflows a hard browser
 limit:
 
-```typescript
+```typescript fragment
 // in a controller
 import { SessionCookieOverflowError } from "@zerotal/session";
 
@@ -433,7 +435,7 @@ try {
 } catch (error) {
   if (error instanceof SessionCookieOverflowError) {
     // Keep a key in the session, the payload somewhere with room.
-    const id = await Cache.put(hugeObject);
+    const id = await Cache.set(hugeObject);
     http.session.put("reportId", id);
   } else throw error;
 }

package/docs/social.md

@@ -96,7 +96,7 @@ Each provider entry accepts the following fields:
 The driver handles CSRF state, session storage, and code extraction. Your
 controller is a few lines per action — read the provider from `ctx.params`:
 
-```typescript
+```typescript fragment
 // app/controllers/SocialController.ts
 import { Social } from "@zerotal/auth";
 import type { HttpContext } from "zerotal";
@@ -148,7 +148,7 @@ mechanism used by `@zerotal/flow` (`Router.flow`) and `@zerotal/inertia`
 (`Router.inertia`). Once `SocialProvider` is in your bootstrap, the macro is
 available in every route file with no additional import:
 
-```typescript
+```typescript fragment
 // routes/auth.ts
 import { Router } from "zerotal";
 import { SocialController } from "../app/controllers/SocialController.ts";
@@ -162,7 +162,7 @@ Router.social("/auth", SocialController);
 
 Or register routes individually for full control:
 
-```typescript
+```typescript fragment
 // routes/auth.ts
 import { Router } from "zerotal";
 import { SocialController } from "../app/controllers/SocialController.ts";
@@ -196,7 +196,7 @@ call the provider's API on the user's behalf later.
 
 Default scopes: `read:user user:email`.
 
-```typescript
+```typescript fragment
 // config/social.ts
 github: {
   clientId:     env("GITHUB_CLIENT_ID", ""),
@@ -218,7 +218,7 @@ primary email before returning `SocialUser` — no extra code in your controller
 
 Default scopes: `openid profile email`.
 
-```typescript
+```typescript fragment
 // config/social.ts
 google: {
   clientId:     env("GOOGLE_CLIENT_ID", ""),
@@ -250,7 +250,7 @@ Sign in with Apple has three quirks — all handled internally by `AppleDriver`:
 credentials and the driver signs the JWT automatically using the Web Crypto API.
 No extra dependency needed:
 
-```typescript
+```typescript fragment
 // config/social.ts
 apple: {
   clientId:    'com.myapp.service',          // your Service ID
@@ -264,7 +264,7 @@ apple: {
 **Option B — pre-sign the JWT yourself** (e.g. with `apple-signin-auth`) and pass
 it as `clientSecret`. Useful if you rotate the JWT externally:
 
-```typescript
+```typescript fragment
 // config/social.ts
 apple: {
   clientId:     'com.myapp.service',
@@ -291,7 +291,7 @@ auto-registered from `config/social.ts` by their key — just supply credentials
 | `linkedin`  | `LinkedInDriver`  | `openid profile email`           | OpenID Connect userinfo (`sub` is the id).                           |
 | `gitlab`    | `GitLabDriver`    | `read_user`                      | Targets gitlab.com.                                                  |
 
-```typescript
+```typescript fragment
 // config/social.ts — same shape as github/google/apple
 discord: {
   clientId:     env("DISCORD_CLIENT_ID", ""),
@@ -310,7 +310,7 @@ Scopes can be set per-provider in `config/social.ts`, but you can also add or
 replace them fluently at redirect time. `.scopes()` merges with the configured /
 default scopes; `.setScopes()` replaces them outright:
 
-```typescript
+```typescript fragment
 // Ask for extra GitHub scopes on top of the defaults
 Social.driver("github").scopes(["repo", "read:org"]).redirect();
 
@@ -322,7 +322,7 @@ Use `.with()` to append provider-specific query parameters to the authorization
 URL. This is how you request a refresh token from Google — Google only returns one
 when you ask for offline access and force the consent screen:
 
-```typescript
+```typescript fragment
 Social.driver("google").with({ access_type: "offline", prompt: "consent" }).redirect();
 
 // On callback, socialUser.refreshToken is now populated.
@@ -337,7 +337,7 @@ If your client already holds an access token — for example a mobile app that r
 its own native OAuth SDK — skip the code exchange and fetch the profile directly
 with `userFromToken()`:
 
-```typescript
+```typescript fragment
 const socialUser = await Social.driver("github").userFromToken(accessToken);
 ```
 
@@ -350,7 +350,7 @@ When you're building an API backend for an SPA or mobile app, you may receive a
 raw `code` from the client without a session. Call `.stateless()` to skip CSRF
 state verification and pass the code directly to `.user()`:
 
-```typescript
+```typescript fragment
 // app/controllers/SocialApiController.ts — POST /auth/callback { provider, code }
 import { Social } from "@zerotal/auth";
 import type { HttpContext } from "zerotal";
@@ -386,7 +386,7 @@ async callback(ctx: HttpContext) {
 `user()` returns a canned profile. Build that profile with `fakeSocialUser()`,
 overriding only the fields your test cares about:
 
-```typescript
+```typescript fragment
 import { Social, fakeSocialUser } from "@zerotal/auth";
 
 test("logs a user in via GitHub", async () => {
@@ -445,7 +445,7 @@ export class TwitterDriver extends OAuth2Driver {
 Register it via the `Social` facade — typically in an `AppProvider`'s `onBooted`
 hook, since the `"social"` singleton is bound during `onRegister`:
 
-```typescript
+```typescript fragment
 // app/providers/AppProvider.ts
 import { ServiceProvider } from "zerotal";
 import { Social } from "@zerotal/auth";

package/docs/storage.md

@@ -65,7 +65,7 @@ A disk outside `storage/public` can still be exposed — with `signed: true`, so
 every request carries a signature you issued. Serving one openly throws
 `UnsafePublicMountError` **at boot**, before the server accepts a request:
 
-```ts
+```ts fragment
 // config/storage.ts — refused
 invoices: { driver: "local", root: "./storage/invoices", serve: { path: "/invoices" } }
 //                                                              ^ no `signed`
@@ -100,7 +100,7 @@ A disk is reachable over the network only if it declares `serve`. The default
 `public` disk does; the default `local` disk does not, which is what makes it a
 sensible place for private uploads.
 
-```ts
+```ts fragment
 // config/storage.ts
 export default StorageConfig({
   disks: {
@@ -145,6 +145,8 @@ guessing paths; a `404` tells them nothing.
 
 ```ts
 // in a controller
+import { Storage } from "zerotal/storage";
+
 const url = await Storage.disk("invoices").temporaryUrl("2026-q1.pdf", 900);
 // → /invoices/2026-q1.pdf?expires=1769990400&signature=…
 ```
@@ -188,7 +190,7 @@ export default StorageConfig({
 
 Each disk is either a local or an S3 disk:
 
-```ts
+```ts fragment
 // config/storage.ts — disk shapes
 local: { driver: "local", root: "./storage/app", url: "/storage" /* optional */ }
 s3:    { driver: "s3", key, secret, region, bucket, endpoint?, url? }
@@ -230,7 +232,7 @@ Storage.disk("s3"); // S3 disk
 
 `put()` accepts a string, `Uint8Array`, or `Blob`:
 
-```ts
+```ts fragment
 function put(
   path: string,
   content: string | Uint8Array | Blob,
@@ -238,7 +240,7 @@ function put(
 ): Promise<void>;
 ```
 
-```ts
+```ts fragment
 // in a controller
 import { Storage } from "zerotal/storage";
 
@@ -281,6 +283,8 @@ const bytes = await Storage.disk().getBuffer("uploads/invoice.pdf");
 
 ```ts
 // in a service
+import { Storage } from "zerotal/storage";
+
 const exists = await Storage.disk().exists("avatars/alice.jpg"); // boolean
 ```
 
@@ -288,6 +292,8 @@ const exists = await Storage.disk().exists("avatars/alice.jpg"); // boolean
 
 ```ts
 // in a service
+import { Storage } from "zerotal/storage";
+
 await Storage.disk().delete("avatars/old.jpg");
 ```
 
@@ -299,6 +305,8 @@ Both operate within the same disk:
 
 ```ts
 // in a service
+import { Storage } from "zerotal/storage";
+
 // Copy
 await Storage.disk().copy("avatars/alice.jpg", "backups/alice-2026.jpg");
 
@@ -310,6 +318,8 @@ await Storage.disk().move("tmp/upload.jpg", "avatars/alice.jpg");
 
 ```ts
 // in a service
+import { Storage } from "zerotal/storage";
+
 const size = await Storage.disk().size("avatars/alice.jpg"); // bytes | null
 const modified = await Storage.disk().lastModified("avatars/alice.jpg"); // ms epoch | null
 ```
@@ -350,8 +360,10 @@ the panel's own 404, which looks like a broken upload and is not one.
 
 Branch instead of catching when a disk may legitimately have no URL:
 
-```ts
+```ts fragment
 // in a view
+import { Storage } from "zerotal/storage";
+
 const src = Storage.isServed("public") ? await Storage.publicUrl(path, { disk: "public" }) : null;
 ```
 
@@ -390,7 +402,7 @@ const localSigned = await Storage.disk("invoices").temporaryUrl("2026-q1.pdf", 9
 Serving the disk with `signed: true` validates the link for you — no route to
 write. Reach for the verifiers only when you are serving the file yourself:
 
-```ts
+```ts fragment
 Router.get("/files/:path*", async ({ params, request, response }) => {
   const path = params.path;
   // Reads ?expires= & ?signature= off the request URL and checks them against `path`.
@@ -498,7 +510,7 @@ Stores files in any S3-compatible service, powered by Bun's native `S3Client` (n
 
 **Cloudflare R2:**
 
-```ts
+```ts fragment
 // config/storage.ts — a disk inside disks: { … }
 r2: {
   driver:   "s3",
@@ -513,7 +525,7 @@ r2: {
 
 **MinIO (self-hosted):**
 
-```ts
+```ts fragment
 // config/storage.ts — a disk inside disks: { … }
 minio: {
   driver:   "s3",
@@ -530,7 +542,7 @@ minio: {
 Set your suite up once as described in [Testing](/docs/testing). Storage ships
 two assertions, and they take either a disk name or a driver instance:
 
-```typescript
+```typescript fragment
 // tests/http/avatars.test.ts
 import { test } from "bun:test";
 import { assertStoredFile, assertMissingFile } from "@zerotal/testing";
@@ -552,7 +564,7 @@ test("uploading an avatar writes it to the disk", async () => {
 reason. Configure a temp directory in `tests/helpers.ts` and clear it between
 runs:
 
-```typescript
+```typescript fragment
 // tests/helpers.ts
 .useConfig({
   storage: { default: "local", disks: { local: { driver: "local", root: "./storage/tmp-test" } } },
@@ -563,7 +575,7 @@ runs:
 that removes a file — a delete endpoint returning `204` proves the route ran, not
 that the bytes are gone:
 
-```typescript
+```typescript fragment
 // tests/http/avatars.test.ts
 (await app.actingAs(user).delete("/avatar")).assertNoContent();
 
@@ -573,7 +585,7 @@ await assertMissingFile("local", `avatars/${user.id}.jpg`);
 **For a unit test, pass a driver instead of a disk name** — no application, no
 config, no container:
 
-```typescript
+```typescript fragment
 // tests/services/ReportWriter.test.ts
 import { LocalDriver } from "zerotal/storage";
 

package/docs/structure.md

@@ -101,7 +101,7 @@ self-register on import. No manual wiring — see
 **`bootstrap/app.ts`** — the application singleton. Wires together exception
 handling, global middleware, and opt-in conventions:
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 import { Application } from "zerotal";
 import { DevtoolsInjectionMiddleware } from "@zerotal/devtools";
@@ -158,7 +158,7 @@ with `Router.static('/assets', './public/assets')` in `routes/index.ts`.
 All explicit route registrations. This file runs after file-based routes are
 scanned, so explicit routes take precedence over file routes for the same path.
 
-```ts
+```ts fragment
 // routes/index.ts
 import { Router } from "zerotal";
 import { PostController } from "../app/controllers/PostController.ts";

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.
@@ -70,9 +70,9 @@ dependency order, from CI. Never mix versions across packages.
 - **One exception, while the 1.x line is young:** a breaking change may land in a
   minor or a patch when leaving it in place would cost more than the migration
   does. It is called out in the release notes as **BREAKING**, with the reason and
-  the migration steps, and it is never silent. Two have shipped so far — the
-  `ComponentWith` / `BaseModelWith` removal in 1.3.0 and Flow's `socket:` listener
-  prefix in 1.7.2. This carve-out is a consequence of the project's age, not a
+  the migration steps, and it is never silent. Three have shipped so far — the
+  `ComponentWith` / `BaseModelWith` removal in 1.3.0, Flow's `socket:` listener
+  prefix in 1.7.2, and the removal of Flow's `this.title(…)` in 1.7.3. This carve-out is a consequence of the project's age, not a
   standing policy; it will be withdrawn, with a version named here, once adoption
   makes the cost of a break real.
 - **Provenance:** packages are published with npm provenance, so you can verify
@@ -100,6 +100,34 @@ 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` held `beta` with the same date, was reviewed ahead of it, and is
+`stable` — the release that carried the promotion is the one its
+[changelog](/docs/changelog) names. Its surface was narrowed first — the writers behind
+`arch:install` are `@internal` now, because they had no caller outside the package
+and freezing them would have promised the shape of `.mcp.json` writing to nobody.
+
+`@zerotal/ai` is not in the `zerotal` meta-package and nothing `stable` depends on
+it, so the cost of its label falling due is ours and not yours. Neither is `arch`,
+still: `arch:install` writes configuration and instruction files into a project,
+which is an opinion about someone's toolchain and stays their choice to invite.
+
+That table used to be the whole of the commitment, which meant the version could
+sail past it and the only consequence would be this paragraph quietly becoming
+untrue. The review release now lives in each package's `package.json` as
+`maturityReview`, and the package-conventions gate fails once the version reaches
+it — so the deadline is a build failure rather than a promise.
+
 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/docs/telemetry.md

@@ -99,7 +99,7 @@ export default TelemetryConfig({
 `TelemetryProvider`; if no tracer is registered the callback still runs with a no-op
 span — no error is thrown, no import guard needed.
 
-```typescript
+```typescript fragment
 // in a service or controller
 import { withSpan } from "@zerotal/telemetry";
 
@@ -123,7 +123,7 @@ The span is automatically:
 
 Pass `kind` and initial `attributes` as a third options argument:
 
-```typescript
+```typescript fragment
 // in a service
 await withSpan(
   "http.outbound",
@@ -142,7 +142,7 @@ The `Span` passed to your callback is fluent — every mutator returns the span.
 
 Attribute values must be `string | number | boolean`.
 
-```typescript
+```typescript fragment
 // inside a withSpan() callback
 span.setAttribute("db.table", "orders"); // single
 span.setAttributes({ "db.rows": 5, "cache.hit": true }); // batch
@@ -153,7 +153,7 @@ span.setAttributes({ "db.rows": 5, "cache.hit": true }); // batch
 The default status is `'unset'`; the exporter treats it the same as `'ok'`.
 `setStatus()` accepts only `'ok'` or `'error'`:
 
-```typescript
+```typescript fragment
 // inside a withSpan() callback
 span.setStatus("ok");
 span.setStatus("error", "payment gateway timeout");
@@ -164,7 +164,7 @@ span.setStatus("error", "payment gateway timeout");
 Events are timestamped log lines attached to a span — useful for recording
 significant moments inside a long operation.
 
-```typescript
+```typescript fragment
 // inside a withSpan() callback
 span.addEvent("cache.miss");
 span.addEvent("db.query", { table: "orders", rows: 5 });
@@ -175,7 +175,7 @@ span.addEvent("db.query", { table: "orders", rows: 5 });
 `recordException()` adds an `exception` event carrying the error's type, message,
 and stack:
 
-```typescript
+```typescript fragment
 // inside a withSpan() callback
 try {
   await chargeCard(amount);
@@ -196,7 +196,7 @@ Child spans created inside a `withSpan()` callback automatically inherit the par
 trace ID and attach as children — no manual wiring. Context flows through the async
 call stack via `AsyncLocalStorage`.
 
-```typescript
+```typescript fragment
 // in a request handler
 await withSpan("handle-request", async () => {
   // These nested spans automatically become children:
@@ -242,7 +242,7 @@ tracing shows the same signal the panel does, with no extra instrumentation. Cor
 never depends on telemetry; telemetry subscribes to core. You can install the bridge
 manually onto any tracer:
 
-```typescript
+```typescript fragment
 import { installEventBridge } from "@zerotal/telemetry";
 
 const dispose = installEventBridge(tracer); // returns an unsubscribe fn
@@ -257,7 +257,7 @@ to trace work that _isn't_ already a framework event.
 request. Register it near the top of the middleware stack, after
 `LoggerMiddleware`:
 
-```typescript
+```typescript fragment
 // bootstrap/middleware.ts (or where the stack is declared)
 import { TelemetryMiddleware } from "@zerotal/telemetry";
 
@@ -282,7 +282,7 @@ A status of `500` or higher sets the span status to `error`. The span name defau
 to `"METHOD /pathname"` (e.g. `"GET /api/users"`). Override it with a custom
 function:
 
-```typescript
+```typescript fragment
 // where you register the middleware
 TelemetryMiddleware.with({
   spanName: (ctx) => `${ctx.request.method} ${ctx.params.route ?? ctx.url.pathname}`,
@@ -356,7 +356,7 @@ export default TelemetryConfig({
 For advanced scenarios — testing, multi-tracer setups, or libraries — create and
 use a `Tracer` instance directly instead of the global one.
 
-```typescript
+```typescript fragment
 // in a library or test
 import { Tracer, ConsoleExporter } from "@zerotal/telemetry";
 
@@ -377,7 +377,7 @@ await tracer.withSpan("my-op", async (span) => {
 Use `startSpan()` for fire-and-forget work, or when the span lifetime doesn't map
 neatly to a single async function. The caller owns the lifecycle:
 
-```typescript
+```typescript fragment
 // in a stream/queue worker
 const span = tracer.startSpan("stream-processor", { kind: "consumer" });
 span.setAttribute("queue", "orders");