@shaferllc/keel 0.83.5 → 0.83.7

package/AGENTS.md

@@ -5,10 +5,12 @@ 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). To deploy on
+> `*.keeljs.cloud` from MCP, see [`docs/keel-cloud.md`](./docs/keel-cloud.md).
+> For deep lookups, connect the MCP server and call `keel_overview`, then
+> `keel_search_docs` / `keel_search_api`.
 
 ---
 
@@ -167,3 +169,13 @@ Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
 - [`docs/architecture.md`](./docs/architecture.md) — a request from socket to response
 - [`docs/container.md`](./docs/container.md) — the DI core everything rests on
 - [`llms-full.txt`](./llms-full.txt) — every guide in one file, for a fresh context
+
+## Learned User Preferences
+
+- Do not reference peer frameworks (Fastify, Laravel, Koa, etc.) in docs, comments, changelogs, or marketing; keep Hono as the only named HTTP foundation.
+
+## Learned Workspace Facts
+
+- Keel Cloud (control plane) lives in the sibling `keel-cloud` repo, not inside this framework repo; this package supplies `@shaferllc/keel/gates`, `@shaferllc/keel/hosting`, and MCP `keel_cloud_*` tools that call Cloud’s API.
+- `create-keeljs` plus self-managed Cloudflare and optional Keel Cloud hosting are alternative paths — do not mix both for the same app; see [`docs/from-install-to-deploy.md`](./docs/from-install-to-deploy.md).
+- Cloud MCP tools register when `KEEL_CLOUD_TOKEN` is set (optional `KEEL_CLOUD_URL`, production default `https://app.keeljs.cloud`).

package/README.md

@@ -61,19 +61,32 @@ 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).
+
+**Deploy on `*.keeljs.cloud` from your IDE** (same `keel-mcp` + a Cloud token):
+[Keel Cloud — deploy from MCP](./docs/keel-cloud.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 +94,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
 
@@ -124,13 +133,16 @@ ships a machine-readable surface that stays generated-in-sync, never stale:
 
 - **An MCP server.** `keel-mcp` exposes Keel's docs, its full public API (380+
   exports), the generators, and its conventions to any [MCP](https://modelcontextprotocol.io)
-  client. Connect it in Claude Code:
+  client — and with `KEEL_CLOUD_TOKEN`, **deploys sites to `*.keeljs.cloud`**
+  (`create_site` → preview → publish). See [Keel Cloud](./docs/keel-cloud.md).
+  Connect it in Claude Code:
   ```bash
   claude mcp add keel -- npx -y keel-mcp
+  # Cloud: add -e KEEL_CLOUD_TOKEN=… -e KEEL_CLOUD_URL=https://app.keeljs.cloud
   ```
   Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
-  `keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
-  `keel://llms-full`, `keel://docs/<slug>`.
+  `keel_list_generators`, `keel_scaffold`, plus `keel_cloud_*` when a token is set.
+  Resources: `keel://overview`, `keel://llms-full`, `keel://docs/<slug>`.
 - **[`AGENTS.md`](./AGENTS.md).** The agent playbook — the one import rule, the
   folder map, the container/provider model, a "how to add X" table, and the
   guardrails. `CLAUDE.md` points to it.
@@ -192,7 +204,10 @@ 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 |
+| [Keel Cloud](./docs/keel-cloud.md) | Deploy `*.keeljs.cloud` from `keel-mcp` (create → preview → publish) |
+| [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/dist/mcp/server.js

@@ -190,14 +190,15 @@ export async function createServer() {
             ? [
                 "",
                 "## Keel Cloud (token detected)",
-                "Cloud tools are enabled. Token binds to the user's first team.",
+                "Cloud tools are enabled — deploy to *.keeljs.cloud from this MCP server.",
+                "Guide: keel_read_doc { slug: \"keel-cloud\" }",
                 "Typical loop:",
                 "1. keel_cloud_create_site { name, preset }",
                 "2. Edit files at the returned storage_path (real Keel app)",
-                "3. keel_cloud_preview { site_id }",
-                "4. keel_cloud_publish { site_id, confirm: true } after user approval",
-                "Also: me, billing(+checkout/portal), list/get/delete/restore sites,",
-                "secrets (list/set/delete), custom domain (set/clear), deploys, export(+sql).",
+                "3. keel_cloud_preview { site_id } → preview-{slug}.keeljs.cloud",
+                "4. keel_cloud_publish { site_id, confirm: true } → {slug}.keeljs.cloud",
+                "Also: secrets, custom domains (Pro), billing, export(+sql), delete/restore.",
+                "Token binds to the user's first team.",
             ]
             : []),
     ].join("\n");

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.5",
+  "version": "0.83.7",
   "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",
@@ -229,6 +236,13 @@
       "path": "docs/inertia.md",
       "example": "docs/examples/inertia.ts"
     },
+    {
+      "slug": "keel-cloud",
+      "title": "Keel Cloud (deploy from MCP)",
+      "summary": "Keel Cloud hosts your Keel apps on .keeljs.cloud — preview and production Workers, D1, secrets vault, and full export (git + SQL).",
+      "path": "docs/keel-cloud.md",
+      "example": null
+    },
     {
       "slug": "locks",
       "title": "Locks",

package/docs/ai.md

@@ -5,8 +5,11 @@ 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). To **deploy on
+`*.keeljs.cloud` from your IDE**, see [Keel Cloud (deploy from MCP)](./keel-cloud.md).
+Then point your agent at the [MCP server](#the-mcp-server) and call
+`keel_overview` first.
 
 ## Why this exists
 
@@ -62,8 +65,12 @@ package, so it always matches your installed version.
 | `keel_scaffold` | Generate a controller/provider/middleware/factory/seeder/job/notification/transformer stub. Returns code + target path — it does **not** write to disk. |
 
 When `KEEL_CLOUD_TOKEN` (and optional `KEEL_CLOUD_URL`) is set, Cloud tools are
-also registered. Create a token at `/tokens` on the control plane — the plaintext
-looks like `keel_<selector>.<verifier>`.
+also registered — **create, preview, and publish sites on `*.keeljs.cloud`** from
+the same MCP server. Step-by-step:
+**[Keel Cloud (deploy from MCP)](./keel-cloud.md)**.
+
+Create a token at `/tokens` on [app.keeljs.cloud](https://app.keeljs.cloud) — the
+plaintext looks like `keel_<selector>.<verifier>`.
 
 | Tool | What it does |
 |------|--------------|
@@ -113,11 +120,13 @@ minting a token if you need a different team context.
 
 ### A typical Keel Cloud loop
 
+Full walkthrough: [Keel Cloud (deploy from MCP)](./keel-cloud.md).
+
 1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
 2. Edit the returned `storage_path` (real Keel app + git)
 3. `keel_cloud_set_secret` for env the Worker needs
-4. `keel_cloud_preview { site_id }`
-5. `keel_cloud_publish { site_id, confirm: true }` after the user approves
+4. `keel_cloud_preview { site_id }` → `preview-{slug}.keeljs.cloud`
+5. `keel_cloud_publish { site_id, confirm: true }` → `{slug}.keeljs.cloud`
 6. Optional Pro: `keel_cloud_set_custom_domain { hostname, attach: true }`
 7. Escape hatch anytime: `keel_cloud_export` + `keel_cloud_export_sql`
 

package/docs/changelog.md

@@ -4,6 +4,26 @@ 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.7] — 2026-07-13
+
+### Documentation
+
+- **[Keel Cloud (deploy from MCP)](./docs/keel-cloud.md)** — advertise and walk
+  through creating / previewing / publishing sites on `*.keeljs.cloud` from
+  `keel-mcp`. Linked from the install guide, AI guide, README, and MCP overview.
+
+[0.83.7]: https://github.com/shaferllc/keel/releases/tag/v0.83.7
+
+## [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,157 @@
+# 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 (`*.keeljs.cloud`)
+
+Ship without owning a Cloudflare account: **Keel Cloud** creates the site,
+runs preview/production Workers on `*.keeljs.cloud`, vaults secrets, and lets
+you export git + SQL anytime — driven from the **same `keel-mcp`** you already
+use for docs.
+
+**Dedicated guide:** [Keel Cloud (deploy from MCP)](./keel-cloud.md).
+
+Quick path:
+
+1. Sign up at [app.keeljs.cloud](https://app.keeljs.cloud) → mint a token at `/tokens`
+2. Add `KEEL_CLOUD_TOKEN` (+ `KEEL_CLOUD_URL`) to your MCP config
+3. Agent: `keel_cloud_create_site` → edit `storage_path` → `keel_cloud_preview` →
+   `keel_cloud_publish { confirm: true }`
+
+Use Cloud when you want the platform to own deploys and hostnames. Skip it when
+you already have Cloudflare / your own pipeline (§4). Don’t mix Cloud and
+self-host for the same app.
+
+## 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 on `*.keeljs.cloud` via MCP | [Keel Cloud](./keel-cloud.md) |
+| 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
+
+- [Keel Cloud (deploy from MCP)](./keel-cloud.md) — create / preview / publish
+  on `*.keeljs.cloud` from `keel-mcp`
+- [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