npm - @zerotal/arch - Versions diffs - 1.7.4 → 1.8.0 - Mend

@zerotal/arch 1.7.4 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (126) hide show

package/CHANGELOG.md +86 -2
package/README.md +4 -2
package/api-surface.md +2 -0
package/docs/about.md +16 -16
package/docs/admin/actions.md +9 -9
package/docs/admin/auth.md +2 -2
package/docs/admin/dashboard.md +5 -5
package/docs/admin/extending-ui.md +12 -12
package/docs/admin/extending.md +16 -7
package/docs/admin/forms.md +4 -4
package/docs/admin/index.md +2 -2
package/docs/admin/operations.md +9 -9
package/docs/admin/resources.md +3 -3
package/docs/admin/structure.md +6 -6
package/docs/admin/tables.md +8 -8
package/docs/admin/testing.md +4 -4
package/docs/ai.md +118 -11
package/docs/application.md +12 -12
package/docs/arch.md +25 -3
package/docs/assets.md +11 -11
package/docs/audit.md +13 -13
package/docs/authentication.md +39 -39
package/docs/authorization.md +13 -13
package/docs/broadcasting/channels.md +2 -2
package/docs/broadcasting/client.md +2 -2
package/docs/broadcasting/events.md +9 -10
package/docs/broadcasting/index.md +1 -1
package/docs/broadcasting/testing.md +5 -5
package/docs/cache.md +15 -13
package/docs/carbon.md +35 -35
package/docs/changelog.md +268 -1
package/docs/client/index.md +13 -13
package/docs/commands.md +36 -4
package/docs/components.md +116 -115
package/docs/config-system.md +4 -4
package/docs/container.md +27 -27
package/docs/context.md +27 -27
package/docs/contributing.md +28 -0
package/docs/controllers.md +10 -10
package/docs/conventions.md +23 -15
package/docs/cookies.md +3 -3
package/docs/csrf.md +6 -6
package/docs/database.md +22 -17
package/docs/deployment.md +99 -2
package/docs/devtools.md +16 -16
package/docs/email-verification.md +8 -8
package/docs/encryption.md +7 -7
package/docs/errors.md +6 -6
package/docs/events.md +12 -11
package/docs/flow/components.md +32 -32
package/docs/flow/decorators.md +18 -18
package/docs/flow/events.md +16 -16
package/docs/flow/forms.md +17 -17
package/docs/flow/icons.md +5 -5
package/docs/flow/index.md +21 -21
package/docs/flow/layouts.md +99 -35
package/docs/flow/lifecycle.md +16 -16
package/docs/flow/models.md +9 -9
package/docs/flow/pagination.md +8 -8
package/docs/flow/performance.md +7 -7
package/docs/flow/references.md +3 -3
package/docs/flow/routing.md +26 -26
package/docs/flow/testing.md +20 -20
package/docs/getting-started.md +18 -13
package/docs/health.md +17 -8
package/docs/helpers.md +17 -17
package/docs/i18n.md +10 -10
package/docs/inertia/devtools.md +4 -4
package/docs/inertia/index.md +6 -6
package/docs/inertia/props.md +21 -21
package/docs/inertia/rendering.md +9 -9
package/docs/inertia/ssr.md +2 -2
package/docs/lifecycle.md +2 -2
package/docs/lock.md +11 -11
package/docs/logger.md +12 -12
package/docs/media.md +22 -22
package/docs/middleware.md +17 -17
package/docs/migrations.md +13 -13
package/docs/monitor.md +6 -6
package/docs/notifications.md +24 -24
package/docs/orm/casts.md +14 -14
package/docs/orm/factories.md +8 -8
package/docs/orm/index.md +22 -20
package/docs/orm/lifecycle.md +13 -13
package/docs/orm/queries.md +28 -28
package/docs/orm/relationships.md +16 -16
package/docs/orm/serialization.md +11 -11
package/docs/package-development.md +10 -10
package/docs/pagination.md +14 -14
package/docs/password-reset.md +6 -6
package/docs/providers.md +11 -11
package/docs/query-builder.md +18 -18
package/docs/queue.md +14 -12
package/docs/rate-limiting.md +6 -6
package/docs/responses.md +14 -14
package/docs/roles-and-2fa.md +9 -9
package/docs/routing.md +44 -44
package/docs/scaffolding.md +1 -1
package/docs/scheduler.md +10 -10
package/docs/seeding.md +6 -6
package/docs/session.md +16 -14
package/docs/social.md +14 -14
package/docs/storage.md +25 -13
package/docs/structure.md +2 -2
package/docs/support-policy.md +23 -10
package/docs/telemetry.md +12 -12
package/docs/tenancy.md +34 -40
package/docs/testing/browser.md +6 -6
package/docs/testing/console.md +3 -3
package/docs/testing/database.md +10 -10
package/docs/testing/flow-browser.md +6 -6
package/docs/testing/http.md +12 -12
package/docs/testing/index.md +29 -3
package/docs/testing/mocking.md +8 -8
package/docs/upgrade.md +1 -1
package/docs/validator.md +19 -19
package/docs/view.md +14 -14
package/package.json +4 -4
package/src/config.ts +8 -0
package/src/index.ts +25 -1
package/src/install/ArchInstallCommand.ts +46 -3
package/src/install/guidelines.ts +84 -0
package/src/install/shape.ts +177 -0
package/src/install/skills.ts +271 -0
package/src/provider/ArchProvider.ts +148 -0
package/src/tools/searchDocs.ts +7 -0

package/docs/responses.md CHANGED Viewed

@@ -27,7 +27,7 @@ import type { HttpContext } from "zerotal";
 ## JSON
-```typescript
+```typescript fragment
 // in a controller
 ctx.json(data); // 200 OK  — Content-Type: application/json
 ctx.json(data, 201); // 201 Created
@@ -44,7 +44,7 @@ JSON-serialisable is accepted: plain objects, arrays, ORM models, `null`.
 `view()` accepts either pre-rendered markup, or a view component plus its props.
 It prepends `<!DOCTYPE html>` and sets `Content-Type: text/html`:
-```typescript
+```typescript fragment
 // in a controller
 import { WelcomePage } from "../../resources/views/WelcomePage.tsx";
@@ -69,7 +69,7 @@ once for the whole project, and already present in scaffolded apps. See the
 For htmx, Turbo Streams, or any partial render — no DOCTYPE prepended:
-```typescript
+```typescript fragment
 // in a controller
 ctx.html('<p class="alert">Saved!</p>');
 ctx.html(renderPartial(data), 200);
@@ -81,7 +81,7 @@ Render a Markdown string to a full HTML page using Bun's built-in
 `Bun.markdown.html()`. Tables, strikethrough, tasklists, autolinks, and heading
 IDs are enabled by default:
-```typescript
+```typescript fragment
 // in a controller
 const content = await Bun.file("./docs/guide.md").text();
 ctx.markdown(content);
@@ -93,7 +93,7 @@ falling back to `"Docs"`.
 ## Redirects
-```typescript
+```typescript fragment
 // in a controller
 ctx.redirect("/dashboard"); // 302 Found
 ctx.redirect("/dashboard", 303); // 303 See Other  ← use after POST/PUT
@@ -120,7 +120,7 @@ points to a different origin.
 Return a `Response` directly with the appropriate headers:
-```typescript
+```typescript fragment
 // in a controller
 const file = Bun.file("./exports/report.csv");
@@ -136,7 +136,7 @@ ctx.response = new Response(file as unknown as BodyInit, {
 Set `ctx.response` to any `Response` object — the pipeline sends it verbatim:
-```typescript
+```typescript fragment
 // in a controller
 ctx.response = new Response("pong", { status: 200 });
@@ -157,7 +157,7 @@ ctx.response = new Response(stream, {
 Every helper assigns a fresh `Response` to `ctx.response`. To add a header,
 rebuild it from the existing one:
-```typescript
+```typescript fragment
 // in a controller, after setting ctx.response via any helper
 const existing = ctx.response!;
 const headers = new Headers(existing.headers);
@@ -175,7 +175,7 @@ Flash a message and redirect in one step — the flashed value is available via
 `ctx.flashed()` on the next request. Flashing requires an active session
 (see [Session](/docs/session)) and silently no-ops without one:
-```typescript
+```typescript fragment
 // in a controller
 ctx.flash("success", "Post created!");
 ctx.redirect("/posts", 303);
@@ -190,7 +190,7 @@ redirects.
 Use `wantsJson()` (true when the client sends `Accept: application/json`) to
 respond differently based on what the client accepts:
-```typescript
+```typescript fragment
 // in a controller
 async destroy(ctx: HttpContext): Promise<void> {
   await post.delete();
@@ -211,7 +211,7 @@ the controller entirely with `Router.view()`. A static props object is evaluated
 once at registration; a factory function receives the `HttpContext` per request
 and may be async:
-```typescript
+```typescript fragment
 // routes/web.ts
 import { Router } from "zerotal";
@@ -244,7 +244,7 @@ sentence you would have written in a comment.
 **Assert the status by meaning, not by number**, so a failure says what went
 wrong rather than what integer it saw:
-```typescript
+```typescript fragment
 // tests/http/posts.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -268,7 +268,7 @@ reach for `assertStatus(n)` only when the code has no name.
 how a broken route passes. `assertRedirect` checks the `Location` header;
 `assertJson` parses the body:
-```typescript
+```typescript fragment
 // tests/http/posts.test.ts
 res.assertRedirect("/posts/hello"); // 3xx + Location
 res.assertJson({ id: 1, title: "Hello" }); // exact body match
@@ -283,7 +283,7 @@ field is added, which trains people to update tests without reading them.
 **Headers and cookies are part of the response contract** when a client depends
 on them:
-```typescript
+```typescript fragment
 // tests/http/downloads.test.ts
 res.assertHeader("Content-Type", "text/csv");
 res.assertHeader("Content-Disposition");

package/docs/roles-and-2fa.md CHANGED Viewed

@@ -80,7 +80,7 @@ export default AuthConfig({
 2FA stores three columns on the user. Add a migration:
-```typescript
+```typescript fragment
 // database/migrations/003_add_two_factor_to_users.ts
 export default class AddTwoFactorToUsers extends Migration {
   async up(schema: Schema): Promise<void> {
@@ -102,7 +102,7 @@ export default class AddTwoFactorToUsers extends Migration {
 Then expose them on the model:
-```typescript
+```typescript fragment
 // app/models/User.ts
 @(table("users").withTimestamps())
 export class User extends AuthUser {
@@ -124,7 +124,7 @@ Enrolment is a two-step flow: generate a secret and show its QR code, then verif
 the user's first code before persisting. `TwoFactor.verifyCode()` and
 `TwoFactor.generateRecoveryCodes()` are synchronous.
-```typescript
+```typescript fragment
 // app/controllers/TwoFactorController.ts
 import { TwoFactor } from "@zerotal/auth";
@@ -191,7 +191,7 @@ After login, the challenge controller verifies a TOTP code (falling back to a
 recovery code) and marks the session as confirmed. `verifyRecoveryCode()` returns
 the remaining codes synchronously so you can persist the consumed set:
-```typescript
+```typescript fragment
 // app/controllers/TwoFactorChallengeController.ts
 import { TwoFactor, TWO_FACTOR_SESSION_KEY } from "@zerotal/auth";
@@ -242,7 +242,7 @@ export class TwoFactorChallengeController extends Controller {
 Add `TwoFactorMiddleware` **after** `AuthMiddleware` in any group that should
 require 2FA:
-```typescript
+```typescript fragment
 // routes/web.ts
 import { AuthMiddleware, TwoFactorMiddleware } from "@zerotal/auth";
@@ -276,7 +276,7 @@ TwoFactorMiddleware.challengeRoute = "/auth/2fa";
 `getQrCodeSvg()` returns the scannable code as an inline `<svg>`, drawn in your
 process. Inline it — do not fetch it, and do not log it:
-```tsx
+```tsx fragment
 // in a Flow page
 const qr = TwoFactor.getQrCodeSvg(user.email, secret, { size: 220 });
@@ -303,14 +303,14 @@ anyone enrolling on the device that holds the authenticator needs another way in
 — the secret in readable blocks to type, or the `otpauth://` URI from
 `getQrCodeUrl()` as a link, which opens the authenticator app directly:
-```tsx
+```tsx fragment
 <a href={TwoFactor.getQrCodeUrl(user.email, secret)}>Open in my authenticator</a>
 ```
 To draw the code yourself — to a canvas, a PNG, or your own markup — `encodeQr()`
 returns the module matrix and `qrSvg()` renders one:
-```ts
+```ts fragment
 import { encodeQr } from "@zerotal/auth";
 const matrix = encodeQr(TwoFactor.getQrCodeUrl(user.email, secret));
@@ -359,7 +359,7 @@ test("a recovery code verifies once and is then consumed", () => {
 what an authenticator app would show, so the test exercises the TOTP path rather
 than working around it:
-```typescript
+```typescript fragment
 // tests/http/two-factor.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";

package/docs/routing.md CHANGED Viewed

@@ -25,7 +25,7 @@ import { Router, route } from "zerotal";
 Register a `GET` route to a controller action, or to an inline closure:
-```typescript
+```typescript fragment
 // routes/index.ts
 import { Router } from "zerotal";
@@ -53,7 +53,7 @@ rules.
 ### HTTP verbs
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/users", UserController, "index");
 Router.post("/users", UserController, "store");
@@ -64,7 +64,7 @@ Router.delete("/users/:id", UserController, "destroy");
 Each call returns a `RouteRegistration` you can chain:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/posts/:slug", PostController, "show").name("posts.show").bind("post", Post);
 ```
@@ -73,7 +73,7 @@ Router.get("/posts/:slug", PostController, "show").name("posts.show").bind("post
 Pass middleware classes as the fourth argument:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/dashboard", DashboardController, "index", [AuthMiddleware]);
 Router.post("/posts", PostController, "store", [AuthMiddleware, ThrottleMiddleware]);
@@ -102,7 +102,7 @@ Router.get("/posts/:slug", (ctx: HttpContext<{ slug: string }>) =>
 Middleware is passed as the **third** argument in closure form (there's no action
 name), and the returned `RouteRegistration` still chains `.name()` / `.bind()`:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/admin", (ctx) => ctx.json({ ok: true }), [AuthMiddleware]);
 Router.get("/posts/:post", (ctx: HttpContext<{ post: Post }>) =>
@@ -118,7 +118,7 @@ Router.get("/posts/:post", (ctx: HttpContext<{ post: Post }>) =>
 `Router.resource()` registers all seven RESTful actions in one call:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.resource("posts", PostController);
 ```
@@ -138,7 +138,7 @@ are accepted.
 #### Filtering actions
-```typescript
+```typescript fragment
 // routes/index.ts
 // Register only these actions
 Router.resource("photos", PhotoController).only(["index", "show"]);
@@ -149,7 +149,7 @@ Router.resource("tags", TagController).except(["create", "edit"]);
 #### Resource middleware
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.resource("comments", CommentController, [AuthMiddleware]);
 ```
@@ -159,7 +159,7 @@ Router.resource("comments", CommentController, [AuthMiddleware]);
 Register a GET route that renders a `@zerotal/core` JSX component directly —
 no controller class needed for simple pages:
-```typescript
+```typescript fragment
 // routes/index.ts
 import { AboutPage } from "../resources/views/AboutPage.tsx";
 import { DashboardPage } from "../resources/views/DashboardPage.tsx";
@@ -182,7 +182,7 @@ Router.view("/settings", SettingsPage, (ctx) => ({ user: ctx.user }), [AuthMiddl
 The route chains `.name()` and `.withLayout()`:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.view("/about", AboutPage).name("about").withLayout(AppLayout);
 ```
@@ -191,7 +191,7 @@ Router.view("/about", AboutPage).name("about").withLayout(AppLayout);
 Serve a local directory under a URL prefix:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.static("/assets", "./public/assets");
 Router.static("/uploads", "public/uploads");
@@ -211,7 +211,7 @@ is pre-registered at boot as a static `Response` (zero JS per request); pass
 Serve a directory of `.md` files as rendered HTML pages:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.markdown("/docs", "./docs");
@@ -232,7 +232,7 @@ Register a handler that receives the raw `Request` and bypasses the entire globa
 middleware pipeline — no `HttpContext`, no session, no auth. Useful for internal
 health checks or asset endpoints:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.raw("GET", "/__ping", () => new Response("pong"));
 Router.raw("GET", "/health", async () => {
@@ -252,7 +252,7 @@ Router.raw("GET", "/health", async () => {
 Added by the `@zerotal/flow` package:
-```typescript
+```typescript fragment
 // routes/index.ts
 import { Router } from "zerotal";
@@ -267,7 +267,7 @@ See the [Flow](/docs/flow) guide for full details.
 Groups apply a shared prefix and/or middleware stack to a set of routes. Groups
 nest — prefix and middleware accumulate.
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.group({ prefix: "/api/v1" }, () => {
   Router.get("/users", UserController, "index");
@@ -276,7 +276,7 @@ Router.group({ prefix: "/api/v1" }, () => {
 });
 ```
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.group({ prefix: "/api/v1", middleware: AuthMiddleware }, () => {
   Router.resource("posts", PostController);
@@ -294,7 +294,7 @@ routes declared after it.
 Define a group of middleware classes under a string key, then reference it by
 name:
-```typescript
+```typescript fragment
 // in a ServiceProvider or bootstrap
 Router.middlewareGroup("api", [ThrottleMiddleware, JsonMiddleware]);
 Router.middlewareGroup("web", [SessionMiddleware, CsrfMiddleware]);
@@ -316,7 +316,7 @@ it everywhere that group is used instead of requiring an edit at every call site
 ### Nested groups
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.group({ prefix: "/admin" }, () => {
   Router.group({ middleware: [AuthMiddleware, AdminMiddleware] }, () => {
@@ -345,7 +345,7 @@ group.
 The `domain` option scopes a group of routes to a specific host. Dynamic `:label`
 segments are captured and exposed on the context via `ctx.subdomains`.
-```typescript
+```typescript fragment
 // routes/index.ts
 import { Router } from "zerotal";
@@ -360,7 +360,7 @@ Router.group({ domain: ":tenant.app.com" }, () => {
 });
 ```
-```typescript
+```typescript fragment
 // app/controllers/DashboardController.ts
 class DashboardController {
   index(ctx: HttpContext) {
@@ -383,7 +383,7 @@ time.
 `@zerotal/tenancy`'s `SubdomainResolver` resolves the tenant _model_ from the same
 subdomain a domain group captures, so the two compose directly:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.group({ domain: ":tenant.app.com" }, () => {
   Router.get("/dashboard", DashboardController, "index");
@@ -397,7 +397,7 @@ Configuring the resolver is covered in [Multi-tenancy](/docs/tenancy).
 Assign a name and generate URLs from it:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/posts/:slug", PostController, "show").name("posts.show");
@@ -436,7 +436,7 @@ route("docs.show", { "*": ["guides", "intro"] }); // → '/docs/guides/intro'
 Run `bun zt route:types` and the names above stop being strings the compiler has
 to take on faith:
-```typescript
+```typescript fragment
 route("psots.show", { slug }); // ✗ not assignable to RouteName
 route("posts.show"); // ✗ Expected 2 arguments, but got 1
 route("posts.show", {}); // ✗ Property 'slug' is missing
@@ -475,7 +475,7 @@ it always did — every name accepted, nothing checked.
 **When the name is not known at compile time** — read from config, chosen by a
 package — use the escape hatch, which does the same work with no checking:
-```typescript
+```typescript fragment
 route.dynamic(config("app.home_route"), { id });
 ```
@@ -506,7 +506,7 @@ server renders — a `view` build's `href` attributes and form actions included.
 A browser bundle is a different process with no router to read, so there it needs
 the table handed to it once, at your entry point:
-```typescript
+```typescript fragment
 // resources/js/app.js
 import { defineRoutes } from "zerotal/routes";
 import { ROUTES } from "../../types/routes.generated";
@@ -516,7 +516,7 @@ defineRoutes(ROUTES);
 From there the call is the one you already know:
-```typescript
+```typescript fragment
 route("posts.show", { slug }); // → '/posts/hello'
 route("posts.index", {}, { page: 2 }); // → '/posts?page=2'
 ```
@@ -532,7 +532,7 @@ type-checks in a controller type-checks in a component.
 `defineRoutes()` also puts `route()` on `globalThis`, so a page, a component or a
 controller calls it with nothing at the top of the file:
-```tsx
+```tsx fragment
 // no import line
 <a href={route("posts.show", { slug })}>{post.title}</a>
 ```
@@ -585,7 +585,7 @@ Nothing to install, and the names are the same ones the server rendered with.
 `route()` gives you a URL. A form needs two things — where to send the request
 and how — and a URL alone leaves the second one to be typed out beside it:
-```typescript
+```typescript fragment
 // The URL is generated; the verb is a guess that happens to be right today.
 form.post(route("posts.comments.store", { post: id }));
 ```
@@ -593,7 +593,7 @@ form.post(route("posts.comments.store", { post: id }));
 `bun zt route:types` also writes a `METHODS` table, so the verb can come from
 the same place the URL does. `action()` returns both:
-```typescript
+```typescript fragment
 // resources/js/app.js
 import { defineRouteMethods, defineRoutes } from "zerotal/routes";
 import { METHODS, ROUTES } from "../../types/routes.generated";
@@ -602,7 +602,7 @@ defineRoutes(ROUTES);
 defineRouteMethods(METHODS);
 ```
-```typescript
+```typescript fragment
 import { action } from "zerotal/routes";
 const endpoint = action("posts.comments.store", { post: id });
@@ -634,7 +634,7 @@ Opt in with `app.fileBasedRouting()` in `bootstrap/app.ts`, passing a map of
 named route groups (each `web`/`api` group brings its own default prefix and
 middleware) to directories:
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Application, basePath } from "zerotal";
 import providers from "./providers";
@@ -667,7 +667,7 @@ segment); `index` becomes the directory URL.
 A file may export handlers for one or more HTTP verbs:
-```typescript
+```typescript fragment
 // app/routes/users/[id].ts
 import type { HttpContext } from "zerotal";
@@ -725,7 +725,7 @@ Place a `_middleware.ts` file in any directory to protect all routes under it.
 The scanner walks from the root down to the file's directory and stacks
 middleware outermost-first:
-```typescript
+```typescript fragment
 // app/routes/api/v2/me/_middleware.ts
 import { RequireAuthMiddleware } from "../../../middleware/RequireAuthMiddleware.ts";
@@ -762,7 +762,7 @@ When `@zerotal/flow` is installed, the file scanner recognises Flow
 configuration. Verb handlers (`POST`, `DELETE`, etc.) in the same file still
 register normally alongside the page:
-```typescript
+```typescript fragment
 // app/flow/pages/(protected)/dashboard.tsx
 import type { HttpContext } from "zerotal";
@@ -789,7 +789,7 @@ route param whose name matches a model resolves to a loaded instance with no
 configuration. `:user` resolves via `User`, `:post` via `Post`, `:blogPost` via
 `BlogPost` (and a plural `:users` resolves to `User` too, via singularization).
-```typescript
+```typescript fragment
 // routes/index.ts — nothing to declare:
 Router.get("/users/:user", UserController, "show");
@@ -811,7 +811,7 @@ A model that resolves by something other than its primary key says so once, on t
 model, rather than at every route that mentions it. Declare
 `static resolveRouteBinding` and it is used wherever that model binds:
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -852,7 +852,7 @@ controller**. That ordering is a guarantee, not an implementation detail:
 Two static properties on the model control implicit binding:
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -879,7 +879,7 @@ There are exactly two ways to change how a param resolves, and they differ only
 scope: put it on the **model** when it is how that model always resolves, or on the
 **route** when it belongs to that one route.
-```typescript
+```typescript fragment
 // in a controller — either way, it is already resolved
 async show(ctx: HttpContext) {
   const user = ctx.model<User>('user');  // no DB call needed here
@@ -894,7 +894,7 @@ controller runs.
 Overrides the model's own resolution for a single route:
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.get("/posts/:post", PostController, "show").name("posts.show").bind("post", Post);
@@ -909,7 +909,7 @@ Router.get("/articles/:article", ArticleController, "show").bind("article", (val
 The resolved instance is available two ways — via `ctx.model()`, or on
 `ctx.params` under the param's name:
-```typescript
+```typescript fragment
 // in a controller — via ctx.model()
 async show(ctx: HttpContext) {
   const post = ctx.model<Post>('post');
@@ -945,7 +945,7 @@ keys — registering the same path twice overwrites the first.
 For resource routes, register literal paths **before** dynamic ones when there is
 a naming conflict:
-```typescript
+```typescript fragment
 // routes/index.ts
 // Correct — /posts/create is matched before /posts/:slug
 Router.get("/posts/create", PostController, "showCreate");
@@ -994,7 +994,7 @@ Both forms boot the app, so a route a provider registers is included.
 ### Programmatic inspection
-```typescript
+```typescript fragment
 // anywhere after boot
 Router.routes; // ReadonlyMap<string, RouteDefinition>
 Router.namedRoutes; // ReadonlyMap<string, string>  (name → path)
@@ -1008,7 +1008,7 @@ Router.middlewareFor("GET", "/dashboard"); // MiddlewareClass[]
 Use `HttpContext.fake()` to unit-test controllers and route handlers without a
 running server:
-```typescript
+```typescript fragment
 // src/tests/PostController.test.ts
 import { HttpContext } from "zerotal";
@@ -1022,7 +1022,7 @@ await new PostController().show(ctx);
 For full integration tests, boot the real app with `createTestApp()` from
 `@zerotal/testing` and exercise it over real requests:
-```typescript
+```typescript fragment
 // src/tests/PostTest.ts
 import { beforeAll, afterAll, it } from "bun:test";
 import { createTestApp, type TestApp } from "@zerotal/testing";

package/docs/scaffolding.md CHANGED Viewed

@@ -269,7 +269,7 @@ The underlying codemod utilities are exported from `zerotal` for use in your
 own generators, install scripts, or migration tools. Each is idempotent — a no-op
 when the change is already present.
-```ts
+```ts fragment
 // in your own generator or script
 import {
   addImport,

package/docs/scheduler.md CHANGED Viewed

@@ -80,7 +80,7 @@ cadence with either a `cron` string or the fluent `frequency()` method. Every
 `Schedule` subclass under `app/schedules/` is discovered and registered
 automatically — no manual wiring, no central list.
-```typescript
+```typescript fragment
 // app/schedules/SendDailyReports.ts
 import { Schedule } from "@zerotal/scheduler";
 import { Queue } from "@zerotal/queue";
@@ -100,7 +100,7 @@ export class SendDailyReports extends Schedule {
 Prefer the fluent frequency builder over a raw cron string when it reads better —
 override `frequency()` and return a configured task:
-```typescript
+```typescript fragment
 // app/schedules/WarmCache.ts
 import { Schedule, type SchedulerBuilder } from "@zerotal/scheduler";
@@ -152,7 +152,7 @@ Every setting is an optional property (or method) on your `Schedule` subclass:
 > Discovery warns at boot when it sees static schedule config, and
 > `bun zt doctor` reports it.
-```typescript
+```typescript fragment
 // app/schedules/NightlyBackup.ts
 import { Schedule, type SchedulerBuilder } from "@zerotal/scheduler";
@@ -213,7 +213,7 @@ expose fluent cadence methods. Each returns the configured task.
 For quick, in-code definitions (e.g. inside a provider) use the `Scheduler` facade,
 which exposes the underlying manager fluently:
-```typescript
+```typescript fragment
 // in a provider's onBooted()
 import { Scheduler } from "@zerotal/scheduler";
@@ -228,7 +228,7 @@ Scheduler.add("rotate-logs", "0 */6 * * *", () => rotateLogs());
 `ScheduledTask`, so you can chain the same fluent tuning the class form exposes
 declaratively:
-```typescript
+```typescript fragment
 // in a provider's onBooted()
 Scheduler.job("nightly-backup", () => runBackup())
   .dailyAt("02:30")
@@ -332,7 +332,7 @@ is configured (Redis or SQLite via the [lock primitive](/docs/lock)) — also ta
 machines. Cross-process locking is **on by default**; pass `{ crossProcess: false }`
 to guard within this process only:
-```typescript
+```typescript fragment
 // app/schedules/RebuildSearchIndex.ts
 withoutOverlapping = { expiresAfterMinutes: 30 }; // cross-process (default)
 // withoutOverlapping = { crossProcess: false };        // in-process guard only
@@ -370,7 +370,7 @@ Anything the task writes to `console.log` can be persisted or emailed:
 > **Note** — `sendOutputTo` is a facade-only tuning method; on a `Schedule`
 > subclass, use the `appendOutputTo` or `emailOutputTo` properties.
-```typescript
+```typescript fragment
 // app/schedules/GenerateSitemap.ts
 import { Schedule } from "@zerotal/scheduler";
@@ -404,7 +404,7 @@ ScheduledTask.outputMailer = async (email, subject, body) => {
 Every run emits a framework event you can listen for to feed metrics, logs, or
 alerts. Subscribe in a provider's `onBooted()`:
-```typescript
+```typescript fragment
 // in a provider's onBooted()
 import { FrameworkEvents } from "zerotal";
 import { TaskRan, TaskFailed, TaskSkipped } from "@zerotal/scheduler";
@@ -446,7 +446,7 @@ as data. To keep the scheduler but drop the section, set
 `ScheduledTask` exposes introspection getters and a `runNow()` that executes the
 handler immediately, bypassing the cron/time-window guards — ideal in tests:
-```typescript
+```typescript fragment
 // in a test
 import { Scheduler } from "@zerotal/scheduler";
@@ -474,7 +474,7 @@ bun zt worker       # starts the queue worker + scheduler
 For simpler deployments, `AppServiceProvider.onStarted()` can run inline polling
 instead of a dedicated worker process (skip it when this IS the worker):
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts (onStarted)
 override async onStarted(): Promise<void> {
   if (Bun.env.APP_ENV === "worker") return; // dedicated worker handles it