@shaferllc/keel 0.83.1 → 0.83.2

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.1",
+  "version": "0.83.2",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -52,7 +52,7 @@
       "title": "Billing",
       "summary": "Keel Billing is a subscription-billing layer for charging customers, managing subscriptions, and reconciling gateway state through webhooks.",
       "path": "docs/billing.md",
-      "example": null
+      "example": "docs/examples/billing.ts"
     },
     {
       "slug": "broadcasting",
@@ -115,7 +115,7 @@
       "title": "CORS",
       "summary": "Cross-Origin Resource Sharing lets browsers on other origins call your API.",
       "path": "docs/cors.md",
-      "example": null
+      "example": "docs/examples/cors.ts"
     },
     {
       "slug": "database",
@@ -192,7 +192,7 @@
       "title": "Built on Hono",
       "summary": "Keel's HTTP layer is Hono — an ultrafast, web-standard router that runs on Node, Cloudflare Workers, Deno, Bun, and more.",
       "path": "docs/hono.md",
-      "example": null
+      "example": "docs/examples/hono.ts"
     },
     {
       "slug": "hooks",
@@ -269,21 +269,21 @@
       "title": "OpenAPI",
       "summary": "Keel OpenAPI generates an OpenAPI 3 spec from your routes and serves Swagger UI to explore it.",
       "path": "docs/openapi.md",
-      "example": null
+      "example": "docs/examples/openapi.ts"
     },
     {
       "slug": "orm",
       "title": "ORM",
       "summary": "Keel's ORM is a compact active record over the query builder: a model is a class pointed at a table, and its rows come back as typed objects with methods.",
       "path": "docs/orm.md",
-      "example": null
+      "example": "docs/examples/orm.ts"
     },
     {
       "slug": "packages",
       "title": "Packages",
       "summary": "A package is a redistributable slice of a Keel app — routes, a UI, config, migrations, console commands — that installs with a single app.register(...).",
       "path": "docs/packages.md",
-      "example": null
+      "example": "docs/examples/packages.ts"
     },
     {
       "slug": "pages",
@@ -304,7 +304,7 @@
       "title": "Query Builder",
       "summary": "Keel's driver-agnostic query builder — build and run SQL by chaining methods off db(table).",
       "path": "docs/query-builder.md",
-      "example": null
+      "example": "docs/examples/query-builder.ts"
     },
     {
       "slug": "queues",
@@ -353,7 +353,7 @@
       "title": "Securing SSR apps",
       "summary": "Two middlewares harden server-rendered apps: securityHeaders() sets the defensive HTTP headers browsers act on, and csrf() blocks cross-site form submissions.",
       "path": "docs/security.md",
-      "example": null
+      "example": "docs/examples/security.ts"
     },
     {
       "slug": "sessions",
@@ -367,14 +367,14 @@
       "title": "Social authentication",
       "summary": "\"Sign in with GitHub / Google / Discord\" — OAuth 2.0, without an SDK.",
       "path": "docs/social-auth.md",
-      "example": null
+      "example": "docs/examples/social-auth.ts"
     },
     {
       "slug": "starter-kits",
       "title": "Starter kits",
       "summary": "",
       "path": "docs/starter-kits.md",
-      "example": null
+      "example": "docs/examples/starter-kits.ts"
     },
     {
       "slug": "static-files",
@@ -456,9 +456,9 @@
     {
       "slug": "watch",
       "title": "Watch",
-      "summary": "Keel Watch is a debug dashboard — a Telescope for Keel.",
+      "summary": "Keel Watch is a debug dashboard for Keel apps.",
       "path": "docs/watch.md",
-      "example": null
+      "example": "docs/examples/watch.ts"
     }
   ],
   "api": [

package/docs/billing.md

@@ -205,6 +205,46 @@ resolveBillableUsing(async (customerId) => {
 });
 ```
 
+## A complete flow
+
+From "user signs up" to "they're subscribed", with the fake gateway for tests:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+} from "@shaferllc/keel/billing";
+
+class User extends Billable(Model) {
+  static table = "users";
+  declare email: string;
+}
+
+// In a test bootstrap:
+const fake = new FakeGateway();
+const manager = new BillingManager({
+  default: "fake",
+  currency: "usd",
+  billableModel: "User",
+  webhook: { path: "billing/webhook" },
+  gateways: { stripe: { key: "", webhookSecret: "" }, paddle: { key: "", webhookSecret: "" }, fake: {} },
+});
+manager.register("fake", () => fake);
+setBilling(manager);
+
+const user = await User.create({ email: "ada@example.com" });
+await user.newSubscription("default", "price_pro").trialDays(14).create();
+
+await user.subscribed(); // true
+fake.calls.some((c) => c.method === "createSubscription"); // true
+```
+
+In production you skip the fake manager — `BillingServiceProvider` wires the
+real gateway from `config/billing.ts` and `.env`.
+
 ## Gateway differences
 
 | Concern | Stripe | Paddle |

package/docs/changelog.md

@@ -4,6 +4,24 @@ All notable changes to Keel are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
 adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.83.2] — 2026-07-12
+
+### Added
+
+- **More runnable doc examples.** Billing, ORM, query builder, CORS, security,
+  social auth, OpenAPI, Watch, packages, Hono, and starter kits now have
+  typechecked harnesses under `docs/examples/` — the same ones
+  `npm run typecheck:docs` compiles against the published surface.
+- **Worked examples in the guides** — a complete billing subscribe flow (with
+  `FakeGateway`), an ORM CRUD+eager-load walkthrough, a production CORS recipe,
+  and a clearer starter-kit picker.
+
+### Changed
+
+- Watch no longer describes itself by another product's name.
+
+[0.83.2]: https://github.com/shaferllc/keel/releases/tag/v0.83.2
+
 ## [0.83.0] — 2026-07-12
 
 ### Added

package/docs/cors.md

@@ -21,6 +21,34 @@ router.group(() => { /* … */ }).use(cors({ origin: ["https://app.example.com"]
 With no options, `cors()` reflects the caller's origin — convenient in
 development. **Lock it down in production** with an explicit allowlist.
 
+## A production API group
+
+Typical setup for a JSON API served from `api.example.com` and called from a
+SPA on `app.example.com`:
+
+```ts
+// app/Http/Kernel.ts
+import { cors } from "@shaferllc/keel/core";
+
+this.use(
+  cors({
+    origin: ["https://app.example.com"],
+    credentials: true,          // cookies / Authorization
+    exposeHeaders: ["X-Request-Id"],
+  }),
+);
+```
+
+During local development, allow any localhost port with a predicate:
+
+```ts
+cors({
+  origin: (origin) =>
+    origin.startsWith("http://localhost:") || origin === "https://app.example.com",
+  credentials: true,
+});
+```
+
 ## Options
 
 ```ts

package/docs/examples/billing.ts

@@ -0,0 +1,128 @@
+// Type-check harness for docs/billing.md. Compile-only — never executed.
+import { Model, listen } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingServiceProvider,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+  resolveBillableUsing,
+  type CheckoutSession,
+  type GatewayCharge,
+} from "@shaferllc/keel/billing";
+
+export class User extends Billable(Model) {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+  declare name: string;
+}
+
+declare const user: User;
+declare const paymentMethodId: string;
+declare const successUrl: string;
+declare const cancelUrl: string;
+
+export const providers = [BillingServiceProvider];
+
+/* -------------------------------- customers ------------------------------- */
+
+export async function customers() {
+  await user.createAsCustomer();
+  user.hasBillingId();
+  await user.getCustomerId();
+}
+
+/* ------------------------------ subscriptions ----------------------------- */
+
+export async function subscribe() {
+  await user
+    .newSubscription("default", "price_pro")
+    .trialDays(14)
+    .quantity(3)
+    .create(paymentMethodId);
+
+  const session: CheckoutSession = await user
+    .newSubscription("default", "price_pro")
+    .checkout({ successUrl, cancelUrl });
+  return session;
+}
+
+export async function status() {
+  await user.subscribed();
+  await user.subscribedToPrice("price_pro");
+  await user.onTrial();
+  const sub = await user.subscription();
+  if (!sub) return;
+
+  sub.active();
+  sub.onTrial();
+  sub.recurring();
+  sub.canceled();
+  sub.onGracePeriod();
+  sub.ended();
+  sub.paused();
+  sub.valid();
+  sub.hasIncompletePayment();
+
+  await sub.swap("price_enterprise");
+  await sub.updateQuantity(10);
+  await sub.incrementQuantity(2);
+  await sub.decrementQuantity();
+  await sub.cancel();
+  await sub.resume();
+  await sub.cancelNow();
+  await sub.endTrial();
+  await sub.extendTrial(new Date("2026-01-01"));
+}
+
+/* -------------------------------- charges --------------------------------- */
+
+export async function charges() {
+  const charge: GatewayCharge = await user.charge(2000, {
+    paymentMethod: "pm_1",
+    description: "Credits",
+  });
+  await user.refund(charge.id);
+  await user.refund(charge.id, 500);
+  await user.checkout("price_onetime", { successUrl, cancelUrl });
+  await user.createSetupIntent();
+  await user.paymentMethods();
+  await user.invoices();
+}
+
+/* -------------------------------- webhooks -------------------------------- */
+
+export function webhooks() {
+  listen("billing.subscription.updated", (e) => {
+    void e.gateway;
+    void e.subscriptionId;
+  });
+  listen("billing.webhook.received", (e) => {
+    void e.gateway;
+    void e.type;
+  });
+  resolveBillableUsing(async (customerId, _gateway) => {
+    return { id: user.id, type: "User" };
+  });
+}
+
+/* --------------------------------- testing -------------------------------- */
+
+export function fakeGateway() {
+  const fake = new FakeGateway();
+  const manager = new BillingManager({
+    default: "fake",
+    currency: "usd",
+    billableModel: "User",
+    webhook: { path: "billing/webhook" },
+    gateways: {
+      stripe: { key: "", webhookSecret: "" },
+      paddle: { key: "", webhookSecret: "" },
+      fake: {},
+    },
+  });
+  manager.register("fake", () => fake);
+  setBilling(manager);
+  return fake;
+}

package/docs/examples/cors.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/cors.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import { cors, type CorsOptions } from "@shaferllc/keel/core";
+
+export function kernel(): MiddlewareHandler {
+  return cors();
+}
+
+export function apiGroup(): MiddlewareHandler {
+  return cors({ origin: ["https://app.example.com"] });
+}
+
+export function production(): MiddlewareHandler {
+  const options: CorsOptions = {
+    origin: ["https://app.example.com"],
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+    headers: true,
+    exposeHeaders: ["X-Request-Id"],
+    credentials: true,
+    maxAge: 86400,
+  };
+  return cors(options);
+}
+
+export function dynamicOrigin(): MiddlewareHandler {
+  return cors({
+    origin: (origin) => origin.endsWith(".example.com") || origin.startsWith("http://localhost"),
+  });
+}

package/docs/examples/hono.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/hono.md. Compile-only — never executed.
+import type { Ctx } from "@shaferllc/keel/core";
+import { Router, json } from "@shaferllc/keel/core";
+
+export function withContext(router: Router) {
+  router.get("/users/:id", async (c: Ctx) => {
+    const id = c.req.param("id");
+    const q = c.req.query("q");
+    const auth = c.req.header("authorization");
+    void q;
+    void auth;
+    return c.json({ id });
+  });
+
+  router.get("/ping", (c) => c.text("pong"));
+  router.get("/go", (c) => c.redirect("/"));
+}
+
+export function ambientHelpers() {
+  return json({ ok: true });
+}
+
+export function keelContext(c: Ctx) {
+  return {
+    app: c.get("app"),
+    route: c.get("route"),
+    subdomains: c.get("subdomains"),
+  };
+}

package/docs/examples/openapi.ts

@@ -0,0 +1,35 @@
+// Type-check harness for docs/openapi.md. Compile-only — never executed.
+import { z } from "zod";
+import { Application, Router, validateRequest, type Ctx } from "@shaferllc/keel/core";
+import { OpenApiServiceProvider, apiDoc, OpenApi } from "@shaferllc/keel/openapi";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+const UserShape = z.object({ id: z.number(), email: z.string().email() });
+
+class Users {
+  store(_c: Ctx) {
+    return { id: 1, email: "a@b.com" };
+  }
+}
+
+export function install() {
+  const app = new Application();
+  app.register(OpenApiServiceProvider);
+  OpenApi.auth((c) => c.req.header("x-docs-key") === "secret");
+  return app;
+}
+
+export function document(router: Router) {
+  router
+    .post("/users", [Users, "store"])
+    .name("users.store")
+    .config(
+      apiDoc({
+        summary: "Create a user",
+        tags: ["users"],
+        request: { body: NewUser },
+        responses: { 201: { description: "The created user", schema: UserShape } },
+      }),
+    )
+    .middleware([validateRequest({ body: NewUser })]);
+}

package/docs/examples/orm.ts

@@ -0,0 +1,30 @@
+// Type-check harness for docs/orm.md. Compile-only — never executed.
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static override table = "posts";
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+}
+
+export class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() {
+    return this.hasMany(Post);
+  }
+}
+
+export async function map() {
+  const user = await User.find(1);
+  if (!user) return;
+  await user.posts();
+  await User.with("posts").where("email", user.email).first();
+  await User.create({ email: "ada@example.com" });
+  user.email = "grace@example.com";
+  await user.save();
+  await user.delete();
+}

package/docs/examples/packages.ts

@@ -0,0 +1,26 @@
+// Type-check harness for docs/packages.md. Compile-only — never executed.
+import { PackageProvider, type Router, type Migration, type PackageCommand } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+declare const createInvoicesTable: Migration;
+declare const syncInvoicesCommand: PackageCommand;
+declare function registerBillingRoutes(r: Router): void;
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing";
+
+  register(): void {
+    this.mergeConfig("billing", { enabled: true, path: "billing" });
+    this.migrations([createInvoicesTable]);
+    this.publishes({ [join(here, "config.stub")]: "config/billing.ts" }, "billing-config");
+    this.commands([syncInvoicesCommand]);
+  }
+
+  boot(): void {
+    this.assets("billing/assets", join(here, "ui/dist"), { maxAge: 3600 });
+    this.routes((r: Router) => registerBillingRoutes(r), { prefix: "billing", as: "billing" });
+  }
+}

package/docs/examples/query-builder.ts

@@ -0,0 +1,118 @@
+// Type-check harness for docs/query-builder.md. Compile-only — never executed.
+import { db, type Row } from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const name: string;
+declare const id: number;
+declare const now: number;
+declare const search: string | undefined;
+declare const includeArchived: boolean;
+declare const key: string;
+declare const value: string;
+
+export async function retrieving() {
+  await db("users").get();
+  await db("users").where("id", 1).first();
+  await db("users").where("id", 1).firstOrFail();
+  await db("users").find(1);
+  await db("users").where("email", email).sole();
+  await db("users").where("id", 1).value("email");
+  await db("posts").pluck("title");
+  await db("tags").orderBy("name").implode("name", ", ");
+
+  await db("users")
+    .orderBy("id")
+    .chunk(500, async (rows) => {
+      for (const _row of rows) {
+        /* process */
+      }
+    });
+}
+
+export async function aggregates() {
+  await db("orders").count();
+  await db("orders").where("paid", true).sum("total");
+  await db("orders").avg("total");
+  await db("orders").min("total");
+  await db("orders").max("total");
+  await db("users").where("email", email).exists();
+  await db("users").where("banned", true).doesntExist();
+}
+
+export async function selectsAndWheres() {
+  db("users").select("id", "email");
+  db("users").select("id").addSelect("email");
+  db("orders").selectRaw("SUM(total) AS revenue");
+  db("users").distinct().select("country");
+
+  db("users").where("votes", 100);
+  db("users").where("votes", ">=", 100);
+  db("users").where("name", "like", "T%");
+  db("users").where("votes", 100).orWhere("name", "John");
+  db("users").whereNot("status", "cancelled");
+  db("users").whereIn("id", [1, 2, 3]).whereNotIn("id", [4]);
+  db("users").whereNull("deleted_at").whereNotNull("email_verified_at");
+  db("products").whereBetween("price", [10, 100]).whereNotBetween("stock", [0, 5]);
+  db("posts").whereLike("title", "%keel%");
+  db("events").whereColumn("updated_at", ">", "created_at");
+  db("users").whereRaw("score >= ? AND score <= ?", [10, 90]);
+
+  await db("users")
+    .where("active", true)
+    .where((q) => q.where("role", "admin").orWhere("role", "owner"))
+    .get();
+}
+
+export async function orderingJoinsWhen() {
+  db("users").orderBy("name").orderByDesc("created_at");
+  db("posts").latest();
+  db("posts").oldest();
+  db("posts").orderByRaw("LENGTH(title) DESC");
+  db("users").inRandomOrder();
+  db("users").reorder("name");
+  db("users").limit(10).offset(20);
+  db("users").take(10).skip(20);
+  db("users").forPage(3, 15);
+
+  await db("orders")
+    .select("user_id")
+    .selectRaw("SUM(total) AS spent")
+    .groupBy("user_id")
+    .having("spent", ">", 1000)
+    .get();
+
+  await db("posts")
+    .join("users", "posts.user_id", "users.id")
+    .leftJoin("images", "images.post_id", "posts.id")
+    .select("posts.title", "users.name")
+    .get();
+
+  await db("users")
+    .when(search, (q, term) => q.whereLike("name", `%${term}%`))
+    .unless(includeArchived, (q) => q.whereNull("archived_at"))
+    .get();
+}
+
+export async function writes() {
+  await db("users").insert({ email, name });
+  await db("users").insertGetId({ email, name });
+  await db("logs").insertOrIgnore({ key, value });
+  await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
+
+  await db("users").where("id", id).update({ name: "Grace" });
+  await db("users").updateOrInsert({ email }, { name });
+  await db("posts").where("id", id).increment("views");
+  await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+  await db("counters").incrementEach({ hits: 1, misses: 2 });
+
+  await db("sessions").where("expires_at", "<", now).delete();
+  await db("cache").truncate();
+}
+
+export async function typed() {
+  type User = { id: number; email: string };
+  const row: User | null = await db<User>("users").where("id", 1).first();
+  const rows: User[] = await db<User>("users").get();
+  const raw: Row[] = await db("users").get();
+  return { row, rows, raw };
+}

package/docs/examples/security.ts

@@ -0,0 +1,31 @@
+// Type-check harness for docs/security.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import {
+  securityHeaders,
+  csrf,
+  csrfField,
+  csrfToken,
+  sessionMiddleware,
+} from "@shaferllc/keel/core";
+
+export function headers(): MiddlewareHandler[] {
+  return [
+    securityHeaders(),
+    securityHeaders({
+      csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+      hsts: { maxAge: 15552000, includeSubDomains: true },
+      frameGuard: "DENY",
+    }),
+  ];
+}
+
+export function csrfStack(): MiddlewareHandler[] {
+  return [sessionMiddleware(), csrf(), csrf({ except: ["/billing/webhook/*"] })];
+}
+
+export function forms() {
+  return {
+    field: csrfField(),
+    token: csrfToken(),
+  };
+}

package/docs/examples/social-auth.ts

@@ -0,0 +1,76 @@
+// Type-check harness for docs/social-auth.md. Compile-only — never executed.
+import {
+  social,
+  session,
+  redirect,
+  request,
+  auth,
+  ForbiddenException,
+  Model,
+  config,
+} from "@shaferllc/keel/core";
+
+class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string | null;
+  declare name: string | null;
+  declare github_id: string;
+  declare twitter_id: string;
+}
+
+const github = social.github({
+  clientId: config("services.github.id") as string,
+  clientSecret: config("services.github.secret") as string,
+  redirectUri: "https://app.example.com/auth/github/callback",
+});
+
+const twitter = social.twitter({
+  clientId: config("services.twitter.key") as string,
+  clientSecret: config("services.twitter.secret") as string,
+  redirectUri: "https://app.example.com/auth/twitter/callback",
+});
+
+export function redirectToGithub() {
+  const state = social.state();
+  session().put("oauth_state", state);
+  return redirect(github.redirect({ state }));
+}
+
+export async function githubCallback() {
+  const state = String(request.query("state") ?? "");
+  if (state !== session().pull("oauth_state")) {
+    throw new ForbiddenException("Invalid OAuth state");
+  }
+
+  const code = String(request.query("code") ?? "");
+  const gh = await github.user(code);
+  const existing = await User.query().where("github_id", gh.id).first();
+  const user =
+    existing ??
+    (await User.create({ github_id: gh.id, email: gh.email, name: gh.name }));
+
+  auth().login(user.id as number);
+  return redirect("/dashboard");
+}
+
+export async function twitterFlow() {
+  const requestToken = await twitter.requestToken();
+  session().put("twitter_secret", requestToken.tokenSecret);
+  const toProvider = redirect(twitter.redirect(requestToken));
+
+  const tw = await twitter.user(
+    String(request.query("oauth_token") ?? ""),
+    String(request.query("oauth_verifier") ?? ""),
+    String(session().pull("twitter_secret") ?? ""),
+  );
+  const user = await User.firstOrCreate({ twitter_id: tw.id }, { name: tw.name });
+  auth().login(user.id as number);
+  return { toProvider, user };
+}
+
+export async function tokenReuse() {
+  const code = String(request.query("code") ?? "");
+  const token = await github.exchangeCode(code);
+  return github.userFromToken(token);
+}

package/docs/examples/starter-kits.ts

@@ -0,0 +1,14 @@
+// Type-check harness for docs/starter-kits.md. Compile-only — never executed.
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Project extends TenantModel {
+  static override table = "projects";
+  declare id: number;
+  declare name: string;
+}
+
+export async function tenantScoped() {
+  await Project.all();
+  await Project.create({ name: "Hi" });
+  await Project.find(1); // null if another team's
+}

package/docs/examples/watch.ts

@@ -0,0 +1,10 @@
+// Type-check harness for docs/watch.md. Compile-only — never executed.
+import { Application } from "@shaferllc/keel/core";
+import { WatchServiceProvider, Watch } from "@shaferllc/keel/watch";
+
+export function install() {
+  const app = new Application();
+  app.register(WatchServiceProvider);
+  Watch.auth((c) => c.req.header("x-watch-key") === "secret");
+  return app;
+}

package/docs/orm.md

@@ -55,3 +55,42 @@ The ORM is deliberately small — enough for CRUD, relationships, and the common
 query shapes without an ORM dependency. For a gnarly one-off report, reach for
 the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
 model layer never gets in the way.
+
+## A worked example
+
+A blog with authors and posts — enough to see CRUD, a relation, and eager loading
+together:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+
+  author() { return this.belongsTo(User); }
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const ada = await User.create({ email: "ada@example.com" });
+await ada.posts().create({ title: "Notes on engines", body: "…" });
+
+const withPosts = await User.with("posts").where("id", ada.id).first();
+for (const post of (withPosts as User & { posts: Post[] }).posts) {
+  console.log(post.title);
+}
+```
+
+For the full surface — casts, soft deletes, scopes, polymorphic relations —
+see [Models](./models.md).
+

package/docs/starter-kits.md

@@ -14,6 +14,20 @@ to finish.
 | `app` *(default)* | Full-stack: views, sessions, register/login, password reset, two-factor. |
 | `saas` | `app` plus teams, roles, invitations, billing, and multi-tenancy. |
 
+## Pick a kit
+
+```bash
+npm create keeljs@latest my-app                 # app (default)
+npm create keeljs@latest my-api  -- --preset api
+npm create keeljs@latest my-saas -- --preset saas
+npm create keeljs@latest bare    -- --preset minimal
+cd my-app && npm install && npm run dev
+```
+
+Then open `http://localhost:3000`. The SaaS kit already has a team switcher,
+invites, and a billing stub wired through [teams](./teams.md) and
+[billing](./billing.md) — start by editing `app/Models` and `routes/web.ts`.
+
 ## Every database, Cloudflare first
 
 Each kit ships with all four drivers wired. Switching is `DB_CONNECTION` and nothing

package/docs/watch.md

@@ -1,6 +1,6 @@
 # Watch
 
-Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+Keel Watch is a debug dashboard for Keel apps. It records the requests,
 queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
 scheduled tasks flowing through your app, and shows them in a single-page UI at
 `/watch`, with every request linked to the queries and logs it produced.

package/llms-full.txt

@@ -5764,6 +5764,46 @@ resolveBillableUsing(async (customerId) => {
 });
 ```
 
+## A complete flow
+
+From "user signs up" to "they're subscribed", with the fake gateway for tests:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+} from "@shaferllc/keel/billing";
+
+class User extends Billable(Model) {
+  static table = "users";
+  declare email: string;
+}
+
+// In a test bootstrap:
+const fake = new FakeGateway();
+const manager = new BillingManager({
+  default: "fake",
+  currency: "usd",
+  billableModel: "User",
+  webhook: { path: "billing/webhook" },
+  gateways: { stripe: { key: "", webhookSecret: "" }, paddle: { key: "", webhookSecret: "" }, fake: {} },
+});
+manager.register("fake", () => fake);
+setBilling(manager);
+
+const user = await User.create({ email: "ada@example.com" });
+await user.newSubscription("default", "price_pro").trialDays(14).create();
+
+await user.subscribed(); // true
+fake.calls.some((c) => c.method === "createSubscription"); // true
+```
+
+In production you skip the fake manager — `BillingServiceProvider` wires the
+real gateway from `config/billing.ts` and `.env`.
+
 ## Gateway differences
 
 | Concern | Stripe | Paddle |
@@ -7611,6 +7651,34 @@ router.group(() => { /* … */ }).use(cors({ origin: ["https://app.example.com"]
 With no options, `cors()` reflects the caller's origin — convenient in
 development. **Lock it down in production** with an explicit allowlist.
 
+## A production API group
+
+Typical setup for a JSON API served from `api.example.com` and called from a
+SPA on `app.example.com`:
+
+```ts
+// app/Http/Kernel.ts
+import { cors } from "@shaferllc/keel/core";
+
+this.use(
+  cors({
+    origin: ["https://app.example.com"],
+    credentials: true,          // cookies / Authorization
+    exposeHeaders: ["X-Request-Id"],
+  }),
+);
+```
+
+During local development, allow any localhost port with a predicate:
+
+```ts
+cors({
+  origin: (origin) =>
+    origin.startsWith("http://localhost:") || origin === "https://app.example.com",
+  credentials: true,
+});
+```
+
 ## Options
 
 ```ts
@@ -14934,6 +15002,44 @@ query shapes without an ORM dependency. For a gnarly one-off report, reach for
 the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
 model layer never gets in the way.
 
+## A worked example
+
+A blog with authors and posts — enough to see CRUD, a relation, and eager loading
+together:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+
+  author() { return this.belongsTo(User); }
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const ada = await User.create({ email: "ada@example.com" });
+await ada.posts().create({ title: "Notes on engines", body: "…" });
+
+const withPosts = await User.with("posts").where("id", ada.id).first();
+for (const post of (withPosts as User & { posts: Post[] }).posts) {
+  console.log(post.title);
+}
+```
+
+For the full surface — casts, soft deletes, scopes, polymorphic relations —
+see [Models](./models.md).
+
 
 
 ---
@@ -17630,6 +17736,20 @@ to finish.
 | `app` *(default)* | Full-stack: views, sessions, register/login, password reset, two-factor. |
 | `saas` | `app` plus teams, roles, invitations, billing, and multi-tenancy. |
 
+## Pick a kit
+
+```bash
+npm create keeljs@latest my-app                 # app (default)
+npm create keeljs@latest my-api  -- --preset api
+npm create keeljs@latest my-saas -- --preset saas
+npm create keeljs@latest bare    -- --preset minimal
+cd my-app && npm install && npm run dev
+```
+
+Then open `http://localhost:3000`. The SaaS kit already has a team switcher,
+invites, and a billing stub wired through [teams](./teams.md) and
+[billing](./billing.md) — start by editing `app/Models` and `routes/web.ts`.
+
 ## Every database, Cloudflare first
 
 Each kit ships with all four drivers wired. Switching is `DB_CONNECTION` and nothing
@@ -21244,7 +21364,7 @@ Vite's `manifest.json`, as produced by the build. You rarely touch it directly
 
 # Watch
 
-Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+Keel Watch is a debug dashboard for Keel apps. It records the requests,
 queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
 scheduled tasks flowing through your app, and shows them in a single-page UI at
 `/watch`, with every request linked to the queries and logs it produced.

package/llms.txt

@@ -72,7 +72,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Validation](https://github.com/shaferllc/keel/blob/main/docs/validation.md): validate() parses request input against a schema and returns typed data.
 - [Views](https://github.com/shaferllc/keel/blob/main/docs/views.md): Keel renders HTML with Hono JSX — type-safe components that run identically on Node and on Cloudflare Workers (no filesystem templating, so it ports anywhere).
 - [Vite](https://github.com/shaferllc/keel/blob/main/docs/vite.md): Wire a modern frontend build — bundling, hashed filenames, hot module reload — to Keel's server-rendered HTML, the way modern full-stack frameworks do.
-- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard — a Telescope for Keel.
+- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard for Keel apps.
 
 ## Examples
 
@@ -82,6 +82,7 @@ Every topic has a runnable, type-checked example:
 - [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
 - [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
 - [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)
+- [Billing example](https://github.com/shaferllc/keel/blob/main/docs/examples/billing.ts)
 - [Broadcasting example](https://github.com/shaferllc/keel/blob/main/docs/examples/broadcasting.ts)
 - [Service Broker example](https://github.com/shaferllc/keel/blob/main/docs/examples/broker.ts)
 - [Cache example](https://github.com/shaferllc/keel/blob/main/docs/examples/cache.ts)
@@ -89,6 +90,7 @@ Every topic has a runnable, type-checked example:
 - [The Console example](https://github.com/shaferllc/keel/blob/main/docs/examples/console.ts)
 - [The Service Container example](https://github.com/shaferllc/keel/blob/main/docs/examples/container.ts)
 - [Controllers example](https://github.com/shaferllc/keel/blob/main/docs/examples/controllers.ts)
+- [CORS example](https://github.com/shaferllc/keel/blob/main/docs/examples/cors.ts)
 - [Database example](https://github.com/shaferllc/keel/blob/main/docs/examples/database.ts)
 - [Debugging example](https://github.com/shaferllc/keel/blob/main/docs/examples/debugging.ts)
 - [Request Decorators example](https://github.com/shaferllc/keel/blob/main/docs/examples/decorators.ts)
@@ -98,6 +100,7 @@ Every topic has a runnable, type-checked example:
 - [Hashing & Encryption example](https://github.com/shaferllc/keel/blob/main/docs/examples/hashing.ts)
 - [Health Checks example](https://github.com/shaferllc/keel/blob/main/docs/examples/health.ts)
 - [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
+- [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
 - [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
 - [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
 - [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
@@ -108,15 +111,22 @@ Every topic has a runnable, type-checked example:
 - [Migrations example](https://github.com/shaferllc/keel/blob/main/docs/examples/migrations.ts)
 - [Models example](https://github.com/shaferllc/keel/blob/main/docs/examples/models.ts)
 - [Notifications example](https://github.com/shaferllc/keel/blob/main/docs/examples/notification.ts)
+- [OpenAPI example](https://github.com/shaferllc/keel/blob/main/docs/examples/openapi.ts)
+- [ORM example](https://github.com/shaferllc/keel/blob/main/docs/examples/orm.ts)
+- [Packages example](https://github.com/shaferllc/keel/blob/main/docs/examples/packages.ts)
 - [Pages example](https://github.com/shaferllc/keel/blob/main/docs/examples/pages.ts)
 - [Service Providers example](https://github.com/shaferllc/keel/blob/main/docs/examples/providers.ts)
+- [Query Builder example](https://github.com/shaferllc/keel/blob/main/docs/examples/query-builder.ts)
 - [Queues & Jobs example](https://github.com/shaferllc/keel/blob/main/docs/examples/queues.ts)
 - [Rate Limiting example](https://github.com/shaferllc/keel/blob/main/docs/examples/rate-limiting.ts)
 - [Redis example](https://github.com/shaferllc/keel/blob/main/docs/examples/redis.ts)
 - [Request & Response example](https://github.com/shaferllc/keel/blob/main/docs/examples/request-response.ts)
 - [Routing example](https://github.com/shaferllc/keel/blob/main/docs/examples/routing.ts)
 - [Task Scheduling example](https://github.com/shaferllc/keel/blob/main/docs/examples/scheduling.ts)
+- [Securing SSR apps example](https://github.com/shaferllc/keel/blob/main/docs/examples/security.ts)
 - [Sessions example](https://github.com/shaferllc/keel/blob/main/docs/examples/sessions.ts)
+- [Social authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/social-auth.ts)
+- [Starter kits example](https://github.com/shaferllc/keel/blob/main/docs/examples/starter-kits.ts)
 - [Static Files example](https://github.com/shaferllc/keel/blob/main/docs/examples/static-files.ts)
 - [Storage example](https://github.com/shaferllc/keel/blob/main/docs/examples/storage.ts)
 - [Teams example](https://github.com/shaferllc/keel/blob/main/docs/examples/teams.ts)
@@ -128,6 +138,7 @@ Every topic has a runnable, type-checked example:
 - [Validation example](https://github.com/shaferllc/keel/blob/main/docs/examples/validation.ts)
 - [Views example](https://github.com/shaferllc/keel/blob/main/docs/examples/views.tsx)
 - [Vite example](https://github.com/shaferllc/keel/blob/main/docs/examples/vite.ts)
+- [Watch example](https://github.com/shaferllc/keel/blob/main/docs/examples/watch.ts)
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.1",
+  "version": "0.83.2",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",