@shaferllc/keel 0.83.5 → 0.83.6

package/AGENTS.md

@@ -5,10 +5,11 @@ house framework for Node.js — or an app built on it. Humans: this is also a fa
 orientation. For prose guides see [`docs/`](./docs); for a machine-readable
 surface, run the [MCP server](#mcp-server-recommended).
 
-> **The fastest path:** connect the Keel MCP server (below) and call
-> `keel_overview` first. It returns conventions, the folder map, every doc
-> topic, and the generators. Then `keel_search_docs` / `keel_read_doc` for
-> depth, `keel_search_api` to find exports, `keel_scaffold` to generate code.
+> **The fastest path:** follow
+> [`docs/from-install-to-deploy.md`](./docs/from-install-to-deploy.md)
+> (create-keeljs → local → Cloudflare or optional Keel Cloud). For deep
+> lookups, connect the MCP server and call `keel_overview`, then
+> `keel_search_docs` / `keel_search_api`.
 
 ---
 

package/README.md

@@ -61,19 +61,29 @@ export class HomeController {
 - **Thin and legible.** The whole framework is a few hundred lines in
   `src/core/`. No magic you can't read.
 
-## Two repos: the framework and your app
+## Two pieces: the framework and your app
 
-Keel is distributed the same way most frameworks are — a **library** you install,
-plus an **app** that depends on it:
+Keel is a **library** you install. New apps come from the generator (templates
+ship inside the package so they cannot lag the framework):
+
+```bash
+npm create keeljs@latest my-app
+cd my-app && npm install && npm run dev
+```
+
+End-to-end (local → Cloudflare or optional Keel Cloud):
+[From install to deploy](./docs/from-install-to-deploy.md).
 
 | Repo | Role |
 |------|------|
 | [`shaferllc/keel`](https://github.com/shaferllc/keel) (this repo) | The framework. Published as `@shaferllc/keel`. |
-| [`shaferllc/keel-app`](https://github.com/shaferllc/keel-app) | The starter app — clone it to build something. Gets core updates via `npm update`. |
+| Your app (via `create-keeljs`) | Routes, models, views — depends on `@shaferllc/keel`. |
 
 ## Install in your app
 
 ```bash
+npm create keeljs@latest my-app
+# or, into an existing project:
 npm install @shaferllc/keel
 ```
 
@@ -81,24 +91,20 @@ npm install @shaferllc/keel
 import { Application, Router, config } from "@shaferllc/keel/core";
 ```
 
-Or clone the [starter app](https://github.com/shaferllc/keel-app) and start
-from a working skeleton.
-
 ## Hack on the framework itself
 
 ```bash
 git clone https://github.com/shaferllc/keel.git
 cd keel
 npm install
-npm test               # 740 tests
-npm run typecheck      # src + tests
-npm run build          # compile the package to dist/
-npm run verify:release # build from what's committed — what a consumer's install runs
+npm test
+npm run typecheck
+npm run build
+npm run verify:release
 ```
 
-This repo is **the framework, and only the framework** — there is no app in it. To
-run one, clone the [starter app](https://github.com/shaferllc/keel-app) and point it
-at your checkout (`"@shaferllc/keel": "file:../keel"`).
+Point a generated kit at your checkout with
+`"@shaferllc/keel": "file:../keel"` while developing.
 
 ## The console
 
@@ -192,7 +198,9 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 
 | Guide | What it covers |
 |-------|----------------|
-| [Getting Started](./docs/getting-started.md) | Install, run, first route and controller |
+| [Getting Started](./docs/getting-started.md) | First route, controller, view, config |
+| [From install to deploy](./docs/from-install-to-deploy.md) | create-keeljs → local → Cloudflare or Keel Cloud |
+| [Starter kits](./docs/starter-kits.md) | Presets (`minimal` / `api` / `app` / `saas`) |
 | [The Service Container](./docs/container.md) | Binding and resolving services, DI |
 | [Service Providers](./docs/providers.md) | Plugin system: register/boot lifecycle, options |
 | [Configuration](./docs/configuration.md) | `config/*.ts`, dot-notation, `env()` |

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.5",
+  "version": "0.83.6",
   "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",
@@ -159,6 +159,13 @@
       "path": "docs/factories.md",
       "example": "docs/examples/factories.ts"
     },
+    {
+      "slug": "from-install-to-deploy",
+      "title": "From install to deploy",
+      "summary": "One path from zero to a live Keel app — locally, on Cloudflare yourself, or on Keel Cloud with an AI agent.",
+      "path": "docs/from-install-to-deploy.md",
+      "example": null
+    },
     {
       "slug": "gates",
       "title": "Gates",

package/docs/ai.md

@@ -5,8 +5,9 @@ AI-facing surface: an MCP server, machine-readable docs (`llms.txt` /
 `llms-full.txt`), an agent playbook (`AGENTS.md`), and code generators an agent
 can drive directly.
 
-If you only read one thing: point your agent at the [MCP server](#the-mcp-server)
-and have it call `keel_overview` first.
+If you only read one thing: follow
+[From install to deploy](./from-install-to-deploy.md), then point your agent at
+the [MCP server](#the-mcp-server) and have it call `keel_overview` first.
 
 ## Why this exists
 

package/docs/changelog.md

@@ -4,6 +4,16 @@ 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.6] — 2026-07-13
+
+### Documentation
+
+- **[From install to deploy](./docs/from-install-to-deploy.md)** — end-to-end
+  guide: `create-keeljs` → local dev → Cloudflare self-deploy → optional Keel
+  Cloud + MCP. Getting Started and the README now lead with the generator.
+
+[0.83.6]: https://github.com/shaferllc/keel/releases/tag/v0.83.6
+
 ## [0.83.5] — 2026-07-13
 
 ### Added

package/docs/from-install-to-deploy.md

@@ -0,0 +1,186 @@
+# From install to deploy
+
+One path from zero to a live Keel app — locally, on Cloudflare yourself, or on
+**Keel Cloud** with an AI agent. Pick the track that matches how you want to
+ship; everything else is optional.
+
+```text
+  create-keeljs  →  npm run dev  →  (optional MCP)  →  deploy
+                                              ↘
+                                         Keel Cloud (optional)
+```
+
+## Requirements
+
+- Node.js **≥ 22**
+- npm
+- For self-hosted edge deploys: a [Cloudflare](https://dash.cloudflare.com) account
+  and [Wrangler](https://developers.cloudflare.com/workers/wrangler/) (ships with
+  the kits as a devDependency)
+- For Keel Cloud: an invite / allowlisted email at [app.keeljs.cloud](https://app.keeljs.cloud)
+  during private alpha
+
+## 1. Create an app
+
+```bash
+npm create keeljs@latest my-app                 # full-stack "app" preset (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
+cp .env.example .env                            # if the kit didn't already
+```
+
+| Preset | Use when |
+|--------|----------|
+| `minimal` | Hello-world / learning — routes, a view, Tailwind. No database. |
+| `api` | JSON API — models, migrations, token auth, OpenAPI, tests. |
+| `app` *(default)* | Product with views, sessions, register/login, password reset, 2FA. |
+| `saas` | Multi-tenant product — teams, roles, invitations, billing. |
+
+Templates live **inside** `@shaferllc/keel`, so the kit version matches the
+framework version you just installed. Details: [Starter kits](./starter-kits.md).
+
+## 2. Run it locally
+
+```bash
+npm run migrate          # if the preset has a database (api / app / saas)
+npm run dev              # http://localhost:3000 — Node + local SQLite
+```
+
+Useful next commands:
+
+```bash
+npm run keel -- routes                 # what is mounted
+npm run keel -- make:controller Post   # scaffold, then wire a route
+npm test
+npm run typecheck
+```
+
+Local tip: `DB_CONNECTION` defaults to a SQLite file. Switching drivers later is
+config only — see [Database](./database.md) and [Starter kits](./starter-kits.md).
+
+For a guided first hour inside the codebase (routes, controllers, views, config),
+read [Getting Started](./getting-started.md).
+
+## 3. Optional — AI agents (local)
+
+Keel is designed to be written with an agent. Point Cursor / Claude Code at the
+MCP server that ships with the package:
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"]
+    }
+  }
+}
+```
+
+Then have the agent call `keel_overview` first. It can search docs, look up the
+public API, and scaffold controllers/jobs/… without inventing imports.
+
+Full map: [Building with AI](./ai.md).
+
+## 4. Deploy yourself (Cloudflare Workers)
+
+Every kit includes `wrangler.jsonc`, a `worker.ts` entry, and `npm run deploy`.
+You own the Cloudflare account and the hostname.
+
+```bash
+# one-time
+npx wrangler login
+npx wrangler d1 create my-app          # paste database_id into wrangler.jsonc
+
+# ship
+npm run deploy                         # css:build + wrangler deploy
+```
+
+Migrations against remote D1 use the HTTP driver from your laptop / CI — the
+binding only exists inside the Worker. Set Cloudflare API credentials as
+documented in [Database](./database.md) (D1 HTTP) and your kit’s README.
+
+Edge preview without deploying:
+
+```bash
+npm run dev:edge                       # wrangler + local D1
+```
+
+Hosting helpers (hostname utils, SQL dump, secrets encryption) live in
+[`@shaferllc/keel/hosting`](./hosting.md) if you build your own control plane.
+
+## 5. Optional — Keel Cloud
+
+[Keel Cloud](https://app.keeljs.cloud) is a hosted control plane: pick a preset,
+edit real source, preview and publish Workers for you, vault secrets, and export
+git + SQL anytime. Free tier is limited (typically one site); Pro adds more sites
+and custom domains.
+
+Use Cloud when you want the platform to own deploys and hostnames. Skip it when
+you already have Cloudflare / your own pipeline (§4).
+
+### Sign up and mint a token
+
+1. Open [app.keeljs.cloud](https://app.keeljs.cloud) (invite code or allowlisted
+   email during alpha).
+2. Create a personal access token at **`/tokens`**. The plaintext looks like
+   `keel_<selector>.<verifier>` — copy it once.
+3. Wire it into your MCP client (same `keel-mcp` binary as local):
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"],
+      "env": {
+        "KEEL_CLOUD_TOKEN": "keel_….…",
+        "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
+      }
+    }
+  }
+}
+```
+
+Reload MCP. When the token is set, `keel_cloud_*` tools appear alongside the
+docs tools. The token binds to your **first team**.
+
+### Agent loop on Cloud
+
+1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
+2. Edit files at the returned `storage_path` (real Keel app + git)
+3. `keel_cloud_set_secret` for anything the Worker needs at runtime
+4. `keel_cloud_preview { site_id }` — iterate freely
+5. `keel_cloud_publish { site_id, confirm: true }` — only after you approve
+6. Optional Pro: `keel_cloud_set_custom_domain { hostname, attach: true }`
+7. Escape hatch anytime: `keel_cloud_export` + `keel_cloud_export_sql`
+
+You can also drive the same flow from the dashboard at `/sites`. Billing for Pro
+is at `/billing` (or `keel_cloud_billing` / `_checkout` / `_portal` via MCP).
+
+Tool reference: [Building with AI](./ai.md#the-mcp-server).
+
+## Which path should I pick?
+
+| Goal | Path |
+|------|------|
+| Learn Keel / ship a side project on your CF account | §§1–4 |
+| Build with an agent in your IDE, deploy yourself | §§1–4 + §3 |
+| Let the platform host preview/prod + secrets + export | §§1–2 + §5 (Cloud creates the app for you) |
+| Multi-tenant SaaS with billing | Preset `saas`, then §4 or §5 |
+
+Cloud **create_site** scaffolds a kit the same way `create-keeljs` does — you do
+not need both for the same app. Use `create-keeljs` for apps you own end-to-end;
+use Cloud when you want hosted preview/publish under `*.keeljs.cloud`.
+
+## Where next
+
+- [Getting Started](./getting-started.md) — first route, controller, view
+- [Starter kits](./starter-kits.md) — presets and the Node/edge seam
+- [Building with AI](./ai.md) — MCP tools (local + Cloud)
+- [Hosting](./hosting.md) — Cloudflare / dump / secrets primitives
+- [Accounts](./accounts.md) · [Teams](./teams.md) · [Billing](./billing.md) — what
+  `app` / `saas` already mount

package/docs/getting-started.md

@@ -15,32 +15,20 @@ Keel targets modern Node and web-standard APIs, so a current runtime matters —
 
 ## Install
 
-Keel ships as two repos: the **framework** (`@shaferllc/keel`, published to
-npm) and a **starter app** (`shaferllc/keel-app`) you build on. Which path you
-take depends on whether you're starting fresh or bolting Keel onto something
-that already exists. See [Architecture](./architecture.md#two-repos-library-and-starter)
-for why it's split this way.
-
-### From the starter (recommended)
-
-The fastest route to a running app is the starter — a working skeleton with the
-folders, config, and scripts already wired:
+The fastest path to a running app is the generator — it copies a curated kit
+from the same `@shaferllc/keel` version you install, so the template cannot lag
+the framework:
 
 ```bash
-git clone https://github.com/shaferllc/keel-app.git my-app
+npm create keeljs@latest my-app
 cd my-app
 npm install
+npm run dev        # http://localhost:3000
 ```
 
-The starter depends on `@shaferllc/keel`, so you pick up framework updates with
-an ordinary `npm update @shaferllc/keel` — your app code in `app/` stays put.
-
-A fresh checkout ships with a working `.env`. To start from the template
-instead:
-
-```bash
-cp .env.example .env
-```
+For the full journey (presets, Cloudflare deploy, optional Keel Cloud + MCP),
+see **[From install to deploy](./from-install-to-deploy.md)**. Kit details:
+[Starter kits](./starter-kits.md).
 
 ### Into an existing app
 
@@ -57,22 +45,24 @@ import { Application, Router, config } from "@shaferllc/keel/core";
 ```
 
 You supply the four convention folders yourself — `app/`, `config/`, `routes/`,
-`bootstrap/` — plus an entry that calls `createApplication()`. The starter's
+`bootstrap/` — plus an entry that calls `createApplication()`. A generated kit’s
 `bootstrap/app.ts` is the reference; copy it and trim to taste.
 
 ### Hacking on the framework itself
 
-To work on Keel proper, clone the framework repo — it carries an example app you
-can run directly:
+To work on Keel proper, clone the framework repo:
 
 ```bash
 git clone https://github.com/shaferllc/keel.git
 cd keel
 npm install
-npm run dev        # example app on http://localhost:3000
-npm run build      # compile the package to dist/
+npm test
+npm run typecheck
 ```
 
+Generate a disposable app against your checkout with
+`npm create keeljs@latest …` and point its dependency at `file:../keel`.
+
 ## Run the server
 
 ```bash
@@ -267,9 +257,10 @@ unsure what's mounted. [The Console](./console.md) lists every command.
 ## Where to go next
 
 You now have the shape of a Keel app: routes point at controllers, controllers
-render views and read config, and the console scaffolds the pieces. The deep
-guides pick up from here:
+render views and read config, and the console scaffolds the pieces.
 
+- **[From install to deploy](./from-install-to-deploy.md)** — presets, Cloudflare,
+  optional Keel Cloud + MCP
 - [Architecture](./architecture.md) — how boot, the container, and the request
   lifecycle fit together
 - [The Service Container](./container.md) — how dependency injection works
@@ -284,6 +275,7 @@ guides pick up from here:
   the active-record layer on top of it
 - [Configuration](./configuration.md) and [The Console](./console.md) — settings
   and commands
+- [Building with AI](./ai.md) — MCP docs + Cloud tools
 
 When something isn't documented, open the source — the whole framework is a few
 hundred readable lines in `src/core/`, and [Built on Hono](./hono.md) explains

package/docs/starter-kits.md

@@ -5,7 +5,8 @@ npm create keeljs@latest my-app -- --preset saas
 ```
 
 Four curated applications. Each is a complete, working app — not a scaffold you have
-to finish.
+to finish. For the full path from this command through Cloudflare or Keel Cloud,
+see [From install to deploy](./from-install-to-deploy.md).
 
 | Preset | What you get |
 | --- | --- |

package/llms-full.txt

@@ -7,6 +7,199 @@ https://github.com/shaferllc/keel/blob/main/docs. Generated by `npm run build:ai
 
 
 
+---
+
+<!-- source: docs/from-install-to-deploy.md -->
+
+# From install to deploy
+
+One path from zero to a live Keel app — locally, on Cloudflare yourself, or on
+**Keel Cloud** with an AI agent. Pick the track that matches how you want to
+ship; everything else is optional.
+
+```text
+  create-keeljs  →  npm run dev  →  (optional MCP)  →  deploy
+                                              ↘
+                                         Keel Cloud (optional)
+```
+
+## Requirements
+
+- Node.js **≥ 22**
+- npm
+- For self-hosted edge deploys: a [Cloudflare](https://dash.cloudflare.com) account
+  and [Wrangler](https://developers.cloudflare.com/workers/wrangler/) (ships with
+  the kits as a devDependency)
+- For Keel Cloud: an invite / allowlisted email at [app.keeljs.cloud](https://app.keeljs.cloud)
+  during private alpha
+
+## 1. Create an app
+
+```bash
+npm create keeljs@latest my-app                 # full-stack "app" preset (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
+cp .env.example .env                            # if the kit didn't already
+```
+
+| Preset | Use when |
+|--------|----------|
+| `minimal` | Hello-world / learning — routes, a view, Tailwind. No database. |
+| `api` | JSON API — models, migrations, token auth, OpenAPI, tests. |
+| `app` *(default)* | Product with views, sessions, register/login, password reset, 2FA. |
+| `saas` | Multi-tenant product — teams, roles, invitations, billing. |
+
+Templates live **inside** `@shaferllc/keel`, so the kit version matches the
+framework version you just installed. Details: [Starter kits](./starter-kits.md).
+
+## 2. Run it locally
+
+```bash
+npm run migrate          # if the preset has a database (api / app / saas)
+npm run dev              # http://localhost:3000 — Node + local SQLite
+```
+
+Useful next commands:
+
+```bash
+npm run keel -- routes                 # what is mounted
+npm run keel -- make:controller Post   # scaffold, then wire a route
+npm test
+npm run typecheck
+```
+
+Local tip: `DB_CONNECTION` defaults to a SQLite file. Switching drivers later is
+config only — see [Database](./database.md) and [Starter kits](./starter-kits.md).
+
+For a guided first hour inside the codebase (routes, controllers, views, config),
+read [Getting Started](./getting-started.md).
+
+## 3. Optional — AI agents (local)
+
+Keel is designed to be written with an agent. Point Cursor / Claude Code at the
+MCP server that ships with the package:
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"]
+    }
+  }
+}
+```
+
+Then have the agent call `keel_overview` first. It can search docs, look up the
+public API, and scaffold controllers/jobs/… without inventing imports.
+
+Full map: [Building with AI](./ai.md).
+
+## 4. Deploy yourself (Cloudflare Workers)
+
+Every kit includes `wrangler.jsonc`, a `worker.ts` entry, and `npm run deploy`.
+You own the Cloudflare account and the hostname.
+
+```bash
+# one-time
+npx wrangler login
+npx wrangler d1 create my-app          # paste database_id into wrangler.jsonc
+
+# ship
+npm run deploy                         # css:build + wrangler deploy
+```
+
+Migrations against remote D1 use the HTTP driver from your laptop / CI — the
+binding only exists inside the Worker. Set Cloudflare API credentials as
+documented in [Database](./database.md) (D1 HTTP) and your kit’s README.
+
+Edge preview without deploying:
+
+```bash
+npm run dev:edge                       # wrangler + local D1
+```
+
+Hosting helpers (hostname utils, SQL dump, secrets encryption) live in
+[`@shaferllc/keel/hosting`](./hosting.md) if you build your own control plane.
+
+## 5. Optional — Keel Cloud
+
+[Keel Cloud](https://app.keeljs.cloud) is a hosted control plane: pick a preset,
+edit real source, preview and publish Workers for you, vault secrets, and export
+git + SQL anytime. Free tier is limited (typically one site); Pro adds more sites
+and custom domains.
+
+Use Cloud when you want the platform to own deploys and hostnames. Skip it when
+you already have Cloudflare / your own pipeline (§4).
+
+### Sign up and mint a token
+
+1. Open [app.keeljs.cloud](https://app.keeljs.cloud) (invite code or allowlisted
+   email during alpha).
+2. Create a personal access token at **`/tokens`**. The plaintext looks like
+   `keel_<selector>.<verifier>` — copy it once.
+3. Wire it into your MCP client (same `keel-mcp` binary as local):
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"],
+      "env": {
+        "KEEL_CLOUD_TOKEN": "keel_….…",
+        "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
+      }
+    }
+  }
+}
+```
+
+Reload MCP. When the token is set, `keel_cloud_*` tools appear alongside the
+docs tools. The token binds to your **first team**.
+
+### Agent loop on Cloud
+
+1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
+2. Edit files at the returned `storage_path` (real Keel app + git)
+3. `keel_cloud_set_secret` for anything the Worker needs at runtime
+4. `keel_cloud_preview { site_id }` — iterate freely
+5. `keel_cloud_publish { site_id, confirm: true }` — only after you approve
+6. Optional Pro: `keel_cloud_set_custom_domain { hostname, attach: true }`
+7. Escape hatch anytime: `keel_cloud_export` + `keel_cloud_export_sql`
+
+You can also drive the same flow from the dashboard at `/sites`. Billing for Pro
+is at `/billing` (or `keel_cloud_billing` / `_checkout` / `_portal` via MCP).
+
+Tool reference: [Building with AI](./ai.md#the-mcp-server).
+
+## Which path should I pick?
+
+| Goal | Path |
+|------|------|
+| Learn Keel / ship a side project on your CF account | §§1–4 |
+| Build with an agent in your IDE, deploy yourself | §§1–4 + §3 |
+| Let the platform host preview/prod + secrets + export | §§1–2 + §5 (Cloud creates the app for you) |
+| Multi-tenant SaaS with billing | Preset `saas`, then §4 or §5 |
+
+Cloud **create_site** scaffolds a kit the same way `create-keeljs` does — you do
+not need both for the same app. Use `create-keeljs` for apps you own end-to-end;
+use Cloud when you want hosted preview/publish under `*.keeljs.cloud`.
+
+## Where next
+
+- [Getting Started](./getting-started.md) — first route, controller, view
+- [Starter kits](./starter-kits.md) — presets and the Node/edge seam
+- [Building with AI](./ai.md) — MCP tools (local + Cloud)
+- [Hosting](./hosting.md) — Cloudflare / dump / secrets primitives
+- [Accounts](./accounts.md) · [Teams](./teams.md) · [Billing](./billing.md) — what
+  `app` / `saas` already mount
+
+
+
 ---
 
 <!-- source: docs/getting-started.md -->
@@ -28,32 +221,20 @@ Keel targets modern Node and web-standard APIs, so a current runtime matters —
 
 ## Install
 
-Keel ships as two repos: the **framework** (`@shaferllc/keel`, published to
-npm) and a **starter app** (`shaferllc/keel-app`) you build on. Which path you
-take depends on whether you're starting fresh or bolting Keel onto something
-that already exists. See [Architecture](./architecture.md#two-repos-library-and-starter)
-for why it's split this way.
-
-### From the starter (recommended)
-
-The fastest route to a running app is the starter — a working skeleton with the
-folders, config, and scripts already wired:
+The fastest path to a running app is the generator — it copies a curated kit
+from the same `@shaferllc/keel` version you install, so the template cannot lag
+the framework:
 
 ```bash
-git clone https://github.com/shaferllc/keel-app.git my-app
+npm create keeljs@latest my-app
 cd my-app
 npm install
+npm run dev        # http://localhost:3000
 ```
 
-The starter depends on `@shaferllc/keel`, so you pick up framework updates with
-an ordinary `npm update @shaferllc/keel` — your app code in `app/` stays put.
-
-A fresh checkout ships with a working `.env`. To start from the template
-instead:
-
-```bash
-cp .env.example .env
-```
+For the full journey (presets, Cloudflare deploy, optional Keel Cloud + MCP),
+see **[From install to deploy](./from-install-to-deploy.md)**. Kit details:
+[Starter kits](./starter-kits.md).
 
 ### Into an existing app
 
@@ -70,22 +251,24 @@ import { Application, Router, config } from "@shaferllc/keel/core";
 ```
 
 You supply the four convention folders yourself — `app/`, `config/`, `routes/`,
-`bootstrap/` — plus an entry that calls `createApplication()`. The starter's
+`bootstrap/` — plus an entry that calls `createApplication()`. A generated kit’s
 `bootstrap/app.ts` is the reference; copy it and trim to taste.
 
 ### Hacking on the framework itself
 
-To work on Keel proper, clone the framework repo — it carries an example app you
-can run directly:
+To work on Keel proper, clone the framework repo:
 
 ```bash
 git clone https://github.com/shaferllc/keel.git
 cd keel
 npm install
-npm run dev        # example app on http://localhost:3000
-npm run build      # compile the package to dist/
+npm test
+npm run typecheck
 ```
 
+Generate a disposable app against your checkout with
+`npm create keeljs@latest …` and point its dependency at `file:../keel`.
+
 ## Run the server
 
 ```bash
@@ -280,9 +463,10 @@ unsure what's mounted. [The Console](./console.md) lists every command.
 ## Where to go next
 
 You now have the shape of a Keel app: routes point at controllers, controllers
-render views and read config, and the console scaffolds the pieces. The deep
-guides pick up from here:
+render views and read config, and the console scaffolds the pieces.
 
+- **[From install to deploy](./from-install-to-deploy.md)** — presets, Cloudflare,
+  optional Keel Cloud + MCP
 - [Architecture](./architecture.md) — how boot, the container, and the request
   lifecycle fit together
 - [The Service Container](./container.md) — how dependency injection works
@@ -297,6 +481,7 @@ guides pick up from here:
   the active-record layer on top of it
 - [Configuration](./configuration.md) and [The Console](./console.md) — settings
   and commands
+- [Building with AI](./ai.md) — MCP docs + Cloud tools
 
 When something isn't documented, open the source — the whole framework is a few
 hundred readable lines in `src/core/`, and [Built on Hono](./hono.md) explains
@@ -304,6 +489,116 @@ what you inherit from the layer underneath.
 
 
 
+---
+
+<!-- source: docs/starter-kits.md -->
+
+# Starter kits
+
+```bash
+npm create keeljs@latest my-app -- --preset saas
+```
+
+Four curated applications. Each is a complete, working app — not a scaffold you have
+to finish. For the full path from this command through Cloudflare or Keel Cloud,
+see [From install to deploy](./from-install-to-deploy.md).
+
+| Preset | What you get |
+| --- | --- |
+| `minimal` | Routes, a controller, a JSX view, Tailwind. No database. |
+| `api` | JSON only — models, migrations, validation, tests. No views. |
+| `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
+else — no model or query changes, because they talk to a `Connection`, not a driver.
+
+| | |
+| --- | --- |
+| **D1** | The default for deploys. Inside the Worker Keel uses the binding; migrations and scripts reach the same database over [the HTTP API](./database.md), so `keel migrate` works from your laptop and from CI. |
+| **SQLite** (libSQL) | A local file. What `npm run dev` uses — no account, no wrangler. |
+| **Turso** | libSQL over the network. |
+| **Postgres** | For when you want it. |
+
+Local and production are both SQLite dialects, so one schema and one set of
+migrations serve both.
+
+```bash
+npm run dev            # Node, SQLite file, no setup
+npm run dev:edge       # wrangler, local D1
+npm run deploy         # wrangler deploy
+```
+
+To deploy:
+
+```bash
+wrangler d1 create my-app     # paste the id into wrangler.jsonc
+npm run deploy
+```
+
+## What's in the box
+
+`app` and `saas` mount [accounts](./accounts.md), so password reset, email
+verification, and two-factor already work — the flows live in the framework, tested
+once, rather than being copy-pasted into each new app. `saas` also mounts
+[teams](./teams.md) and [billing](./billing.md).
+
+In `saas`, a tenant-owned model is one word:
+
+```ts
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Project extends TenantModel {
+  static table = "projects";
+}
+
+await Project.all();                  // only the current team's. Always.
+await Project.create({ name: "Hi" }); // stamped with the current team
+```
+
+Another team's project isn't merely hidden from a list — `Project.find(id)` returns
+`null`. You never write `.where("team_id", …)`, which is what makes it impossible to
+forget.
+
+## Why a generator, and not a template repo
+
+Because a second repo rots. The old starter sat pinned to `0.78.2` while the
+framework was on `0.79.0`, and nothing noticed.
+
+The templates live **inside the framework package**, so the version a kit is
+generated from is, by construction, the version it was written for. And CI generates
+all four on every push, then typechecks, migrates, boots, serves a request, bundles
+the Worker, and runs their tests — so a breaking change fails in the pull request
+that caused it, not in your `npm create` three weeks later.
+
+## The Node/edge seam
+
+Each kit has two provider lists. `bootstrap/providers.ts` runs under Node;
+`bootstrap/providers.edge.ts` runs in the Worker and deliberately **omits the
+database provider** — it reaches for `pg`, which needs `net`/`tls`, and wrangler
+cannot bundle a TCP driver for the edge. `worker.ts` binds D1 before the app boots,
+so nothing on the edge needs to open a connection.
+
+If you add a provider that touches a Node-only module, add it to the Node list only.
+
+
+
 ---
 
 <!-- source: docs/architecture.md -->
@@ -4669,8 +4964,9 @@ AI-facing surface: an MCP server, machine-readable docs (`llms.txt` /
 `llms-full.txt`), an agent playbook (`AGENTS.md`), and code generators an agent
 can drive directly.
 
-If you only read one thing: point your agent at the [MCP server](#the-mcp-server)
-and have it call `keel_overview` first.
+If you only read one thing: follow
+[From install to deploy](./from-install-to-deploy.md), then point your agent at
+the [MCP server](#the-mcp-server) and have it call `keel_overview` first.
 
 ## Why this exists
 
@@ -17957,115 +18253,6 @@ const gitlab = social.driver(
 
 
 
----
-
-<!-- source: docs/starter-kits.md -->
-
-# Starter kits
-
-```bash
-npm create keeljs@latest my-app -- --preset saas
-```
-
-Four curated applications. Each is a complete, working app — not a scaffold you have
-to finish.
-
-| Preset | What you get |
-| --- | --- |
-| `minimal` | Routes, a controller, a JSX view, Tailwind. No database. |
-| `api` | JSON only — models, migrations, validation, tests. No views. |
-| `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
-else — no model or query changes, because they talk to a `Connection`, not a driver.
-
-| | |
-| --- | --- |
-| **D1** | The default for deploys. Inside the Worker Keel uses the binding; migrations and scripts reach the same database over [the HTTP API](./database.md), so `keel migrate` works from your laptop and from CI. |
-| **SQLite** (libSQL) | A local file. What `npm run dev` uses — no account, no wrangler. |
-| **Turso** | libSQL over the network. |
-| **Postgres** | For when you want it. |
-
-Local and production are both SQLite dialects, so one schema and one set of
-migrations serve both.
-
-```bash
-npm run dev            # Node, SQLite file, no setup
-npm run dev:edge       # wrangler, local D1
-npm run deploy         # wrangler deploy
-```
-
-To deploy:
-
-```bash
-wrangler d1 create my-app     # paste the id into wrangler.jsonc
-npm run deploy
-```
-
-## What's in the box
-
-`app` and `saas` mount [accounts](./accounts.md), so password reset, email
-verification, and two-factor already work — the flows live in the framework, tested
-once, rather than being copy-pasted into each new app. `saas` also mounts
-[teams](./teams.md) and [billing](./billing.md).
-
-In `saas`, a tenant-owned model is one word:
-
-```ts
-import { TenantModel } from "@shaferllc/keel/teams";
-
-class Project extends TenantModel {
-  static table = "projects";
-}
-
-await Project.all();                  // only the current team's. Always.
-await Project.create({ name: "Hi" }); // stamped with the current team
-```
-
-Another team's project isn't merely hidden from a list — `Project.find(id)` returns
-`null`. You never write `.where("team_id", …)`, which is what makes it impossible to
-forget.
-
-## Why a generator, and not a template repo
-
-Because a second repo rots. The old starter sat pinned to `0.78.2` while the
-framework was on `0.79.0`, and nothing noticed.
-
-The templates live **inside the framework package**, so the version a kit is
-generated from is, by construction, the version it was written for. And CI generates
-all four on every push, then typechecks, migrates, boots, serves a request, bundles
-the Worker, and runs their tests — so a breaking change fails in the pull request
-that caused it, not in your `npm create` three weeks later.
-
-## The Node/edge seam
-
-Each kit has two provider lists. `bootstrap/providers.ts` runs under Node;
-`bootstrap/providers.edge.ts` runs in the Worker and deliberately **omits the
-database provider** — it reaches for `pg`, which needs `net`/`tls`, and wrangler
-cannot bundle a TCP driver for the edge. `worker.ts` binds D1 before the app boots,
-so nothing on the edge needs to open a connection.
-
-If you add a provider that touches a Node-only module, add it to the Node list only.
-
-
-
 ---
 
 <!-- source: docs/static-files.md -->

package/llms.txt

@@ -30,6 +30,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Errors & Exceptions](https://github.com/shaferllc/keel/blob/main/docs/errors.md): Throw an exception anywhere — a handler, middleware, or a service deep in the container — and Keel's HTTP kernel turns it into the right response.
 - [Events](https://github.com/shaferllc/keel/blob/main/docs/events.md): A tiny event emitter for decoupling — fire an event in one place, handle it in another.
 - [Factories & Seeders](https://github.com/shaferllc/keel/blob/main/docs/factories.md): Populate the database with realistic fixtures for tests and demos.
+- [From install to deploy](https://github.com/shaferllc/keel/blob/main/docs/from-install-to-deploy.md): One path from zero to a live Keel app — locally, on Cloudflare yourself, or on Keel Cloud with an AI agent.
 - [Gates](https://github.com/shaferllc/keel/blob/main/docs/gates.md): Keel Gates is a signup gate for private alpha / waitlist apps: an email allowlist, invite codes with use limits and expiry, and a single check that answers "may this person register?".
 - [Getting Started](https://github.com/shaferllc/keel/blob/main/docs/getting-started.md): Keel is a house framework for Node.js — a small, legible MVC layer over Hono.
 - [Hashing & Encryption](https://github.com/shaferllc/keel/blob/main/docs/hashing.md): Password hashing and value encryption, both built on the Web Crypto API — so they run identically on Node and the edge, with no native bindings (no bcrypt to compile).

package/package.json

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