@shaferllc/keel 0.83.4 → 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/dist/accounts/provider.js

@@ -15,7 +15,17 @@ import { defaultConfig, resolveConfig } from "./config.js";
 import { accountsMigration } from "./migration.js";
 import { registerAccountsRoutes } from "./routes.js";
 import { setAccountStore, tableStore } from "./store.js";
-const here = dirname(fileURLToPath(import.meta.url));
+function packageDir() {
+    try {
+        const url = import.meta.url;
+        if (!url)
+            return ".";
+        return dirname(fileURLToPath(url));
+    }
+    catch {
+        return ".";
+    }
+}
 export class AccountsServiceProvider extends PackageProvider {
     name = "accounts";
     config;
@@ -24,7 +34,7 @@ export class AccountsServiceProvider extends PackageProvider {
         this.config = resolveConfig();
         setAccountStore(tableStore(this.config.userTable));
         this.migrations([accountsMigration(this.config.userTable)]);
-        this.publishes({ [join(here, "accounts.config.stub")]: "config/accounts.ts" }, "accounts-config");
+        this.publishes({ [join(packageDir(), "accounts.config.stub")]: "config/accounts.ts" }, "accounts-config");
     }
     boot() {
         if (!this.config.routes.enabled)

package/dist/billing/provider.js

@@ -17,7 +17,17 @@ import { BillingManager, setBilling } from "./manager.js";
 import { registerDefaultGateways } from "./drivers/index.js";
 import { billingMigration } from "./migration.js";
 import { registerBillingRoutes } from "./routes.js";
-const here = dirname(fileURLToPath(import.meta.url));
+function packageDir() {
+    try {
+        const url = import.meta.url;
+        if (!url)
+            return ".";
+        return dirname(fileURLToPath(url));
+    }
+    catch {
+        return ".";
+    }
+}
 export class BillingServiceProvider extends PackageProvider {
     name = "billing";
     config;
@@ -31,7 +41,7 @@ export class BillingServiceProvider extends PackageProvider {
         this.app.instance(BillingManager, this.manager);
         // Default billable table is `users`.
         this.migrations([billingMigration("users")]);
-        this.publishes({ [join(here, "billing.config.stub")]: "config/billing.ts" }, "billing-config");
+        this.publishes({ [join(packageDir(), "billing.config.stub")]: "config/billing.ts" }, "billing-config");
     }
     boot() {
         this.routes((r) => registerBillingRoutes(r, this.config.webhook.path));

package/dist/mcp/cloud.d.ts

@@ -2,7 +2,8 @@
  * Keel Cloud MCP tools — registered only when KEEL_CLOUD_TOKEN is set.
  *
  * Talks to a Keel Cloud control plane over HTTP (Bearer token). Agents use these
- * to create sites, preview/publish, and manage secrets without leaving the IDE.
+ * to create sites, preview/publish, manage secrets/domains/billing, and export
+ * without leaving the IDE.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /** Register Cloud tools on an existing MCP server when a Cloud token is present. */

package/dist/mcp/cloud.js

@@ -2,7 +2,8 @@
  * Keel Cloud MCP tools — registered only when KEEL_CLOUD_TOKEN is set.
  *
  * Talks to a Keel Cloud control plane over HTTP (Bearer token). Agents use these
- * to create sites, preview/publish, and manage secrets without leaving the IDE.
+ * to create sites, preview/publish, manage secrets/domains/billing, and export
+ * without leaving the IDE.
  */
 import { z } from "zod";
 const PRESETS = ["minimal", "api", "app", "saas"];
@@ -42,18 +43,49 @@ function jsonText(data, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+function requireConfirm(confirm, action) {
+    if (confirm)
+        return null;
+    return jsonText({
+        error: `${action} requires confirm=true. Ask the user to confirm before calling again.`,
+    }, true);
+}
 /** Register Cloud tools on an existing MCP server when a Cloud token is present. */
 export function registerCloudTools(server) {
     if (!cloudConfig())
         return false;
     server.registerTool("keel_cloud_me", {
         title: "Keel Cloud — who am I",
-        description: "Return the Keel Cloud user authenticated by KEEL_CLOUD_TOKEN.",
+        description: "Return the Keel Cloud user authenticated by KEEL_CLOUD_TOKEN (plan, site_limit, team_id). Token binds to the user's first team.",
         inputSchema: {},
     }, async () => {
         const res = await cloudFetch("/api/v1/me");
         return jsonText(res.body, !res.ok);
     });
+    server.registerTool("keel_cloud_billing", {
+        title: "Keel Cloud — billing status",
+        description: "Current team plan (free|pro), site limits, custom-domain eligibility, and whether the caller is the owner.",
+        inputSchema: {},
+    }, async () => {
+        const res = await cloudFetch("/api/v1/billing");
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_billing_checkout", {
+        title: "Keel Cloud — Stripe checkout URL",
+        description: "Create a Stripe Checkout session for Keel Cloud Pro (owner only). Return the url for the user to open — do not scrape cards.",
+        inputSchema: {},
+    }, async () => {
+        const res = await cloudFetch("/api/v1/billing/checkout", { method: "POST", body: "{}" });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_billing_portal", {
+        title: "Keel Cloud — Stripe customer portal URL",
+        description: "Open the Stripe customer portal URL for the team (owner only) to update card / cancel. Return the url for the user.",
+        inputSchema: {},
+    }, async () => {
+        const res = await cloudFetch("/api/v1/billing/portal", { method: "POST", body: "{}" });
+        return jsonText(res.body, !res.ok);
+    });
     server.registerTool("keel_cloud_list_sites", {
         title: "Keel Cloud — list sites",
         description: "List sites on the current Keel Cloud team. Includes storage_path for local editing and hostnames.",
@@ -64,7 +96,7 @@ export function registerCloudTools(server) {
     });
     server.registerTool("keel_cloud_get_site", {
         title: "Keel Cloud — get site",
-        description: "Fetch one Keel Cloud site by id (paths, hostnames, status).",
+        description: "Fetch one Keel Cloud site by id (paths, hostnames, status, git).",
         inputSchema: {
             site_id: z.number().int().describe("Site id from keel_cloud_list_sites"),
         },
@@ -86,6 +118,36 @@ export function registerCloudTools(server) {
         });
         return jsonText(res.body, !res.ok);
     });
+    server.registerTool("keel_cloud_delete_site", {
+        title: "Keel Cloud — soft-delete site",
+        description: "Soft-delete a site (detaches hostnames; recoverable within retention). Requires confirm=true.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            confirm: z.boolean().describe("Must be true — ask the user before setting this"),
+        },
+    }, async ({ site_id, confirm }) => {
+        const blocked = requireConfirm(confirm, "Delete");
+        if (blocked)
+            return blocked;
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/delete`, {
+            method: "POST",
+            body: JSON.stringify({ confirm: true }),
+        });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_restore_site", {
+        title: "Keel Cloud — restore soft-deleted site",
+        description: "Restore a soft-deleted site within the retention window. Redeploy to reattach hostnames.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/restore`, {
+            method: "POST",
+            body: "{}",
+        });
+        return jsonText(res.body, !res.ok);
+    });
     server.registerTool("keel_cloud_preview", {
         title: "Keel Cloud — deploy preview",
         description: "Deploy the site's preview Worker (and attach preview hostname when Cloudflare is configured). Safe to call freely while iterating.",
@@ -106,11 +168,9 @@ export function registerCloudTools(server) {
                 .describe("Must be true to publish — ask the user before setting this"),
         },
     }, async ({ site_id, confirm }) => {
-        if (!confirm) {
-            return jsonText({
-                error: "Publish requires confirm=true. Ask the user to confirm before calling again.",
-            }, true);
-        }
+        const blocked = requireConfirm(confirm, "Publish");
+        if (blocked)
+            return blocked;
         const res = await cloudFetch(`/api/v1/sites/${site_id}/publish`, {
             method: "POST",
             body: JSON.stringify({ confirm: true }),
@@ -127,6 +187,16 @@ export function registerCloudTools(server) {
         const res = await cloudFetch(`/api/v1/sites/${site_id}/deploys`);
         return jsonText(res.body, !res.ok);
     });
+    server.registerTool("keel_cloud_list_secrets", {
+        title: "Keel Cloud — list secret keys",
+        description: "List vault key names for a site (values are never returned).",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/secrets`);
+        return jsonText(res.body, !res.ok);
+    });
     server.registerTool("keel_cloud_set_secret", {
         title: "Keel Cloud — set secret",
         description: "Store a secret in the site vault (never in git). Injected into the Worker on the next preview/publish.",
@@ -142,6 +212,45 @@ export function registerCloudTools(server) {
         });
         return jsonText(res.body, !res.ok);
     });
+    server.registerTool("keel_cloud_delete_secret", {
+        title: "Keel Cloud — delete secret",
+        description: "Remove a secret key from the site vault.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            key: z.string().min(1).describe("Secret key to remove"),
+        },
+    }, async ({ site_id, key }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/secrets?key=${encodeURIComponent(key)}`, { method: "DELETE" });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_set_custom_domain", {
+        title: "Keel Cloud — set custom domain",
+        description: "Set a Pro custom hostname (CNAME instructions returned). Optionally attach=true to verify DNS and attach to the production Worker.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            hostname: z.string().min(1).describe("Customer hostname, e.g. app.example.com"),
+            attach: z
+                .boolean()
+                .optional()
+                .describe("If true, verify DNS and attach Workers Custom Domain now"),
+        },
+    }, async ({ site_id, hostname, attach }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/custom-domain`, {
+            method: "PUT",
+            body: JSON.stringify({ hostname, attach: Boolean(attach) }),
+        });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_clear_custom_domain", {
+        title: "Keel Cloud — clear custom domain",
+        description: "Detach and clear the site's custom hostname (Pro).",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/custom-domain`, { method: "DELETE" });
+        return jsonText(res.body, !res.ok);
+    });
     server.registerTool("keel_cloud_export", {
         title: "Keel Cloud — export manifest",
         description: "Return the site's export manifest (paths, hostnames, Keel version, SQL dump URLs). Use storage_path / git_url for code; use keel_cloud_export_sql for data.",

package/dist/mcp/server.js

@@ -190,12 +190,14 @@ export async function createServer() {
             ? [
                 "",
                 "## Keel Cloud (token detected)",
-                "Cloud tools are enabled. Typical loop:",
+                "Cloud tools are enabled. Token binds to the user's first team.",
+                "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: keel_cloud_list_sites, keel_cloud_get_site, keel_cloud_set_secret, keel_cloud_deploys, keel_cloud_export.",
+                "Also: me, billing(+checkout/portal), list/get/delete/restore sites,",
+                "secrets (list/set/delete), custom domain (set/clear), deploys, export(+sql).",
             ]
             : []),
     ].join("\n");

package/dist/teams/provider.js

@@ -14,7 +14,17 @@ import { dirname, join } from "node:path";
 import { PackageProvider } from "../core/package.js";
 import { defaultConfig, resolveConfig } from "./config.js";
 import { teamsMigration } from "./migration.js";
-const here = dirname(fileURLToPath(import.meta.url));
+function packageDir() {
+    try {
+        const url = import.meta.url;
+        if (!url)
+            return ".";
+        return dirname(fileURLToPath(url));
+    }
+    catch {
+        return ".";
+    }
+}
 export class TeamsServiceProvider extends PackageProvider {
     name = "teams";
     config;
@@ -22,6 +32,6 @@ export class TeamsServiceProvider extends PackageProvider {
         this.mergeConfig("teams", defaultConfig);
         this.config = resolveConfig();
         this.migrations([teamsMigration(this.config.userTable)]);
-        this.publishes({ [join(here, "teams.config.stub")]: "config/teams.ts" }, "teams-config");
+        this.publishes({ [join(packageDir(), "teams.config.stub")]: "config/teams.ts" }, "teams-config");
     }
 }

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.4",
+  "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
 
@@ -62,18 +63,23 @@ 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:
+also registered. Create a token at `/tokens` on the control plane — the plaintext
+looks like `keel_<selector>.<verifier>`.
 
 | Tool | What it does |
 |------|--------------|
-| `keel_cloud_me` | Authenticated Cloud user |
-| `keel_cloud_list_sites` / `keel_cloud_get_site` | List or fetch a site (includes `storage_path`) |
+| `keel_cloud_me` | Authenticated Cloud user (plan, site limit, team) |
+| `keel_cloud_billing` | Team plan / limits / owner flag |
+| `keel_cloud_billing_checkout` / `_portal` | Stripe Checkout or Customer Portal URL (owner) |
+| `keel_cloud_list_sites` / `keel_cloud_get_site` | List or fetch a site (`storage_path`, hostnames, git) |
 | `keel_cloud_create_site` | Create from preset (`minimal` \| `api` \| `app` \| `saas`) |
+| `keel_cloud_delete_site` / `keel_cloud_restore_site` | Soft-delete (confirm) / restore |
 | `keel_cloud_preview` | Deploy preview Worker |
 | `keel_cloud_publish` | Publish production — requires `confirm: true` |
-| `keel_cloud_set_secret` | Vault a secret (injected on next deploy) |
-| `keel_cloud_deploys` / `keel_cloud_export` | Deploy history and export manifest |
-| `keel_cloud_export_sql` | Portable `.sql` dump (`local` \| `preview` \| `production`) |
+| `keel_cloud_deploys` | Deploy history + logs |
+| `keel_cloud_list_secrets` / `keel_cloud_set_secret` / `keel_cloud_delete_secret` | Vault keys (values never returned) |
+| `keel_cloud_set_custom_domain` / `keel_cloud_clear_custom_domain` | Pro custom hostname (+ optional attach) |
+| `keel_cloud_export` / `keel_cloud_export_sql` | Export manifest / portable `.sql` dump |
 
 ```json
 {
@@ -82,7 +88,7 @@ also registered:
       "command": "npx",
       "args": ["-y", "keel-mcp"],
       "env": {
-        "KEEL_CLOUD_TOKEN": "kc_…",
+        "KEEL_CLOUD_TOKEN": "keel_….…",
         "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
       }
     }
@@ -90,6 +96,8 @@ also registered:
 }
 ```
 
+The token binds to the user's **first team**. Switch teams in the dashboard before
+minting a token if you need a different team context.
 ### Resources
 
 - `keel://overview` — the same orientation text as `keel_overview`
@@ -108,8 +116,11 @@ also registered:
 
 1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
 2. Edit the returned `storage_path` (real Keel app + git)
-3. `keel_cloud_preview { site_id }`
-4. `keel_cloud_publish { site_id, confirm: true }` after the user approves
+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
+6. Optional Pro: `keel_cloud_set_custom_domain { hostname, attach: true }`
+7. Escape hatch anytime: `keel_cloud_export` + `keel_cloud_export_sql`
 
 ## `llms.txt` and `llms-full.txt`
 

package/docs/changelog.md

@@ -4,6 +4,27 @@ 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
+
+- **Full Keel Cloud MCP surface** — billing status/checkout/portal, soft-delete
+  and restore sites, list/delete secrets, set/clear custom domains. Documented in
+  [Building with AI](./docs/ai.md). Pairs with expanded `/api/v1` routes on Keel
+  Cloud.
+
+[0.83.5]: https://github.com/shaferllc/keel/releases/tag/v0.83.5
+
 ## [0.83.4] — 2026-07-13
 
 ### Added