@eliottd/kleap 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kleap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# Kleap — website infrastructure for AI agents
+
+[![CI](https://github.com/Kleap-co/kleap/actions/workflows/ci.yml/badge.svg)](https://github.com/Kleap-co/kleap/actions/workflows/ci.yml)
+[![MCP](https://img.shields.io/badge/MCP-server-2563eb)](https://modelcontextprotocol.io)
+[![17 tools](https://img.shields.io/badge/tools-17-ff0055)](#tools)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+> **Your agent builds. Kleap ships it live.**
+> Let any AI agent — Claude, ChatGPT, Cursor — build, edit and **publish real,
+> live websites** for you. Hosting, database, auth and domains included.
+
+An alternative to Lovable / v0 / Bolt — except it's driven by **your** agent, and
+every publish comes with the **verified-live guarantee**: a site is only ever
+reported online once it is *provably serving* — never a hallucinated dead link.
+
+![A real, unedited run: an agent writes a page with write_files, publishes, and it is live and serving in seconds.](https://raw.githubusercontent.com/Kleap-co/kleap/main/assets/demo.gif)
+
+> *Above: a real run — your agent writes the code with `write_files`, `publish_app` builds & deploys it, and the page is live in seconds. Or just ask Kleap's AI in plain English.*
+
+This is a thin [Model Context Protocol](https://modelcontextprotocol.io) server
+that wraps Kleap's public REST API. **No secrets live in this package** — it reads
+your own `KLEAP_API_KEY` from the environment and talks only to `kleap.co`.
+
+---
+
+## Quick start
+
+### Easiest — connect with OAuth, no key
+
+Add the hosted connector and sign in. **Nothing to generate, nothing to paste** —
+you authorize Kleap in your browser like any other app. Works in Claude Desktop,
+ChatGPT and Cursor.
+
+```
+https://kleap.co/api/mcp
+```
+
+- **Claude Desktop** — Settings → Connectors → **Add custom connector** → paste the URL → **Connect** → sign in to Kleap.
+- **ChatGPT** — Settings → Connectors → add the URL → authorize with OAuth.
+- **Cursor** — Settings → **MCP** → Add server → paste the URL → authorize.
+
+That's it — same 17 tools, no API key. Skip straight to step 3.
+
+---
+
+### Or — local CLI, sign in with your browser (no key)
+
+Prefer a local stdio process? Sign in once — no key to generate or paste:
+
+```
+npx kleap auth login
+```
+
+This opens your browser, you authorize Kleap, and the token is saved to
+`~/.kleap/config.json`. After that, `npx -y kleap` just works. (`kleap auth
+logout` / `kleap auth status` are there too.) Then add a keyless stdio entry to
+your client, e.g. Claude Desktop `claude_desktop_config.json`:
+
+```json
+{ "mcpServers": { "kleap": { "command": "npx", "args": ["-y", "kleap"] } } }
+```
+
+---
+
+### Or — local CLI with an API key
+
+Prefer a key (e.g. for CI or scripting the REST API directly)?
+
+**1. Get an API key** — at [kleap.co](https://kleap.co) → **Settings → API key →
+MCP / API access → Generate MCP key** (`kleap_live_sk_...`).
+
+**2. Add Kleap to your AI client:**
+
+<details open>
+<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "kleap": {
+      "command": "npx",
+      "args": ["-y", "kleap"],
+      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cursor</b> — <code>.cursor/mcp.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "kleap": {
+      "command": "npx",
+      "args": ["-y", "kleap"],
+      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code</b> — one command</summary>
+
+```bash
+claude mcp add kleap -e KLEAP_API_KEY=kleap_live_sk_... -- npx -y kleap
+```
+</details>
+
+<details>
+<summary><b>Cline / Roo (VS Code)</b> — <code>cline_mcp_settings.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "kleap": {
+      "command": "npx",
+      "args": ["-y", "kleap"],
+      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "kleap": {
+      "command": "npx",
+      "args": ["-y", "kleap"],
+      "env": { "KLEAP_API_KEY": "kleap_live_sk_..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>ChatGPT &amp; hosted agents</b> — no local process</summary>
+
+Add the hosted connector at **`https://kleap.co/api/mcp`** and authorize with
+OAuth (or paste your `kleap_live_sk_` key). Same tools, no install.
+</details>
+
+> Every stdio config is identical — `npx -y kleap` + a `KLEAP_API_KEY` env var —
+> so any MCP client works.
+
+**Least-privilege keys:** when you generate a key, pick a scope — **Read-only**
+(inspect sites, no changes), **Build**, or **Full**. Buying domains is never
+included by default. Give a read-only agent a read-only key.
+
+**3. Restart the client and just ask:**
+
+> *"Build me a one-page site for my bakery, publish it, and give me the live URL."*
+> *"Add a contact form to my site and redeploy."*
+> *"Change the headline to 'Roasted slow' and publish."*
+
+Works with **any MCP-compatible agent**: Claude · ChatGPT · Cursor · Claude Code · Codex.
+
+---
+
+## Tools
+
+**Find & build** — `find_app` · `create_app` · `modify_app` · `read_files` · `write_files` · `rename_app` · `check_task` · `retry_task`
+**Publish & domains** — `publish_app` · `get_publish_status` · `search_domains` · `check_domain` · `connect_domain`
+**Account** — `list_apps` · `get_app` · `list_app_files` · `get_credits`
+
+| Tool | What it does |
+|------|--------------|
+| `find_app` | Resolve a domain / URL / slug → app_id in one call |
+| `create_app` | Create an Astro site from a prompt → returns a task (auto-deploys live) |
+| `modify_app` | Ask the app's AI to change it → returns a task |
+| `read_files` | Read the **current contents** of files so you can edit them safely (not blind) |
+| `write_files` | Write exact files directly (**your** code, deterministic) → then `publish_app` |
+| `rename_app` | Rename the display name (URL stays the same) |
+| `check_task` | Long-poll a create/modify task to completion (`wait` up to 50s) |
+| `retry_task` | Resume a failed/stalled build from partial state (new task_id) |
+| `publish_app` | Publish with verified-live (live-or-rollback, never a false "online") |
+| `get_publish_status` | Confirm a site is actually published + live |
+| `search_domains` | Find available domains (purchase stays user-confirmed in Kleap) |
+| `connect_domain` | Connect a domain you already own to a live app |
+| `check_domain` | A domain's connection / DNS status |
+| `list_apps` / `get_app` / `list_app_files` | Your apps, an app's details, its files (read-only) |
+| `get_credits` | Remaining credit balance + plan |
+
+App arguments are snake_case: `app_id`, `task_id`, `prompt`, `message`, `visibility`.
+
+## Recipes
+
+**Two ways to put code on a site — pick per task:**
+- **`write_files` (deterministic):** *your* model writes the exact file contents; you push them and Kleap builds + deploys as-is. No Kleap-AI step → no Kleap credits, never stalls. Then `publish_app`. Unlike Lovable/v0/Bolt, your agent can write the code itself.
+- **`modify_app` (Kleap's AI):** describe the outcome in plain English and Kleap's AI writes it. Like Lovable's message-passing — kept for when you'd rather it figure out the change.
+
+Either way Kleap hosts it (build, deploy, SSL, DB, auth, domains, verified-live).
+
+- **Edit existing files SAFELY (don't rewrite blind)** — `list_app_files(app_id)` → `read_files(app_id, ["src/components/Header.astro"])` → edit only what must change with your own model → `write_files(app_id, [{ path, content }])` → `publish_app(app_id)`. This read→edit→write loop is the reliable way to fix headers/footers, wrong phone numbers, broken links or dead forms without breaking the rest of the site.
+- **Edit a site named by its address** — `find_app("mysite.ch")` → `read_files(...)` → `write_files(...)` → `publish_app(...)`, or `modify_app(app_id, "…")` → `check_task(task_id, wait=45)`.
+- **Many pages (programmatic SEO) — BEST:** generate a dynamic route + a data file with your own model and push them in one `write_files`, then `publish_app`:
+  > `write_files(app_id, [{ path: "src/pages/[service]/[city].astro", content: … }, { path: "src/data/locations.json", content: … }])` → `publish_app(app_id)`
+  Deterministic, scales to thousands, no stall, no credits. (Or ask Kleap's AI to do the same in one `modify_app` — never loop one call per page.)
+- **Don't babysit a 5-15 min build** — `check_task` long-polls (default `wait=45`),
+  or pass a `webhook_url` to `create_app` / `modify_app` for a fully hands-off flow.
+- **A build failed** — `TASK_TIMEOUT`/`STALE_TASK` = transient, call `retry_task`; it
+  returns a **new** task_id — poll *that* one. `TASK_FAILED` = read the message, retry once.
+
+## The verified-live guarantee
+
+Most tools tell the agent "it's online" the moment a deploy is *requested*. Kleap
+reports a site as published **only once the new version is provably serving** at
+its live URL — otherwise it rolls back and reports "not confirmed live." Your
+agent can never hand a user a dead link.
+
+If `check_task` reports `failed` (a transient generation stall), call `retry_task`
+with that `task_id` to resume from where it stopped — it returns a **new** task_id
+to poll, and partial work is kept. Or skip the AI entirely and `write_files` the
+exact code yourself, then `publish_app`.
+
+## FAQ
+
+**Do I need an API key?** No. The easiest path is the OAuth connector
+(`https://kleap.co/api/mcp`) — you sign in with your browser and never copy a
+key. An API key is only needed for the local CLI / direct REST use.
+
+**Is it safe?** Yes. Whether you connect with OAuth or an API key, an agent can
+only ever touch *your own* Kleap apps. OAuth tokens and `kleap_live_sk_` keys are
+scoped, sent only to `kleap.co` over HTTPS, and revocable anytime in
+**Settings → API key**. Keys stay in your local client config; nothing else is
+written to disk.
+
+**How much does it cost?** Connecting is free. Builds and edits use Kleap credits
+(`get_credits` reports your balance) — see [pricing](https://kleap.co/pricing).
+
+**Which agents work?** Any MCP client: Claude Desktop, Claude Code, Cursor,
+ChatGPT (hosted connector), and others.
+
+## Requirements & run
+
+Node ≥ 18. Run it directly:
+
+```bash
+KLEAP_API_KEY=kleap_live_sk_... npx -y kleap
+# → [kleap-mcp] ready (stdio) → https://kleap.co. Tools: list_apps, ...
+```
+
+Override the API base with `KLEAP_API_URL` (default `https://kleap.co`).
+Missing key → the server exits with a clear message.
+
+## Links
+
+- Kleap: https://kleap.co · MCP & CLI page: https://kleap.co/mcp
+- Issues & security: https://github.com/Kleap-co/kleap/issues
+
+Maintained by the [Kleap](https://kleap.co) team. MIT © Kleap.

package/kleap-mcp-server.mjs

@@ -0,0 +1,655 @@
+#!/usr/bin/env node
+/**
+ * Kleap MCP server (v1 — stdio transport, API-key auth).
+ *
+ * Lets ANY MCP client (Claude Desktop, Cursor, or ChatGPT via a bridge) drive
+ * Kleap: create / list / inspect apps, edit them through Kleap's own AI, and
+ * PUBLISH with the verified-live guarantee. It does this by wrapping the
+ * existing public REST API (`/api/v1/*`) — the MCP is just another client onto
+ * the same backend, exactly like the web app or the WhatsApp integration. No
+ * new write path, so every Kleap convention/guardrail still applies server-side.
+ *
+ * Auth: a Kleap API key, sent as `Authorization: Bearer kleap_live_sk_...`.
+ * Transport: stdio (the client spawns this process).
+ *
+ * Run:
+ *   KLEAP_API_KEY=kleap_live_sk_... node mcp/kleap-mcp-server.mjs
+ *   (optional) KLEAP_API_URL=https://kleap.co   # default
+ *
+ * PHASE 2 (deliberately NOT here — see the agent-platform plan):
+ *   remote HTTP transport + OAuth (so users add it without a local process),
+ *   registry listing + one-click install, and metering/quota surfacing. This
+ *   file is the working keystone of the agent interface: it proves the whole
+ *   path (external agent → Kleap backend → verified-live publish) end to end.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const API_URL = (process.env.KLEAP_API_URL || "https://kleap.co").replace(
+  /\/$/,
+  "",
+);
+
+// Auth token used on every API call. Resolved at boot (below): an explicit
+// KLEAP_API_KEY env var wins; otherwise the OAuth token saved by
+// `kleap auth login`. Mutable so a refresh can swap it in.
+let AUTH_TOKEN = null;
+
+// ── Stored credentials (~/.kleap/config.json) ───────────────────────────────
+const CONFIG_DIR = join(homedir(), ".kleap");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+  try {
+    chmodSync(CONFIG_PATH, 0o600);
+  } catch {}
+}
+
+// ── OAuth (browser, PKCE + http loopback, RFC 8252) — `kleap auth login` ─────
+const OAUTH_SCOPES = "apps:read apps:create apps:update messages:create tasks:read";
+const b64url = (buf) =>
+  Buffer.from(buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+function openBrowser(url) {
+  const plat = process.platform;
+  const cmd = plat === "darwin" ? "open" : plat === "win32" ? "cmd" : "xdg-open";
+  const args = plat === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {}
+}
+async function oauthPost(path, payload) {
+  const res = await fetch(`${API_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {}
+  if (!res.ok) {
+    const msg = json?.error_description || json?.error || text.slice(0, 200);
+    throw new Error(`${path} → HTTP ${res.status}: ${msg}`);
+  }
+  return json || {};
+}
+async function authLogin() {
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const state = b64url(randomBytes(16));
+  // 1. bind a loopback server first so we know the redirect port
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
+  // 2. register a native client (Dynamic Client Registration) for that redirect
+  const reg = await oauthPost("/api/oauth/register", {
+    client_name: "Kleap CLI",
+    redirect_uris: [redirectUri],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+  });
+  const clientId = reg.client_id;
+  // 3. wait for the browser to redirect back with the code
+  const codePromise = new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      try {
+        server.close();
+      } catch {}
+      reject(new Error("login timed out after 5 minutes"));
+    }, 300000);
+    server.on("request", (req, res) => {
+      const u = new URL(req.url, redirectUri);
+      if (u.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const err = u.searchParams.get("error");
+      const code = u.searchParams.get("code");
+      const st = u.searchParams.get("state");
+      res.writeHead(err ? 400 : 200, {
+        "Content-Type": "text/html; charset=utf-8",
+      });
+      res.end(
+        `<!doctype html><meta charset="utf-8"><body style="font-family:system-ui,sans-serif;text-align:center;padding:64px;color:#111"><h2 style="color:${err ? "#cc0033" : "#16b364"}">${err ? "Sign-in failed" : "Kleap connected"}</h2><p>${err ? "Return to the terminal and try again." : "You can close this tab and return to the terminal."}</p></body>`,
+      );
+      clearTimeout(timer);
+      try {
+        server.close();
+      } catch {}
+      if (err) return reject(new Error(err));
+      if (st !== state) return reject(new Error("state mismatch (possible CSRF)"));
+      resolve(code);
+    });
+  });
+  // 4. open the browser to the authorize page
+  const authUrl =
+    `${API_URL}/api/oauth/authorize?response_type=code` +
+    `&client_id=${encodeURIComponent(clientId)}` +
+    `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+    `&scope=${encodeURIComponent(OAUTH_SCOPES)}` +
+    `&state=${state}&code_challenge=${challenge}&code_challenge_method=S256`;
+  console.error(
+    "[kleap] Opening your browser to sign in…\n[kleap] If it doesn't open, paste this URL:\n" +
+      authUrl +
+      "\n",
+  );
+  openBrowser(authUrl);
+  const code = await codePromise;
+  // 5. exchange the code for tokens (PKCE)
+  const tok = await oauthPost("/api/oauth/token", {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: verifier,
+  });
+  const cfg = readConfig();
+  cfg.oauth = {
+    client_id: clientId,
+    access_token: tok.access_token,
+    refresh_token: tok.refresh_token || null,
+    expires_at: tok.expires_in ? Date.now() + tok.expires_in * 1000 : null,
+    api_url: API_URL,
+  };
+  writeConfig(cfg);
+  console.error(
+    "[kleap] Signed in. Token saved to ~/.kleap/config.json — `npx kleap` now works with no API key.",
+  );
+}
+async function refreshIfNeeded(cfg) {
+  const o = cfg.oauth;
+  if (!o) return null;
+  if (!o.refresh_token || !o.expires_at) return o.access_token || null;
+  if (o.expires_at > Date.now() + 60000) return o.access_token; // still valid
+  try {
+    const tok = await oauthPost("/api/oauth/token", {
+      grant_type: "refresh_token",
+      refresh_token: o.refresh_token,
+      client_id: o.client_id,
+    });
+    o.access_token = tok.access_token;
+    if (tok.refresh_token) o.refresh_token = tok.refresh_token;
+    o.expires_at = tok.expires_in ? Date.now() + tok.expires_in * 1000 : null;
+    writeConfig(cfg);
+    return o.access_token;
+  } catch {
+    return o.access_token; // fall back; the server will 401 if it's truly dead
+  }
+}
+async function resolveToken() {
+  if (process.env.KLEAP_API_KEY) return process.env.KLEAP_API_KEY; // explicit key wins
+  const cfg = readConfig();
+  if (cfg.oauth?.access_token) return await refreshIfNeeded(cfg);
+  return null;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const safeJson = (t) => { try { return JSON.parse(t); } catch { return null; } };
+
+/**
+ * Thin REST caller — auth, timeout, bounded retry, JSON/HTML-aware errors.
+ * Retries transient failures (5xx / 429 / network / timeout) with backoff.
+ * Never surfaces raw HTML error pages to the agent; extracts error.code/message.
+ */
+async function api(method, path, body, { retries = 2, timeoutMs = 60000 } = {}) {
+  const url = `${API_URL}/api/v1${path}`;
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${AUTH_TOKEN}`,
+          Accept: "application/json",
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: ctrl.signal,
+      });
+      clearTimeout(t);
+
+      const ctype = res.headers.get("content-type") || "";
+      const text = await res.text();
+      const isJson = ctype.includes("application/json");
+      const parsed = isJson ? safeJson(text) : null;
+
+      if (!res.ok) {
+        if ((res.status >= 500 || res.status === 429) && attempt < retries) {
+          await sleep(400 * 2 ** attempt);
+          continue;
+        }
+        const detail =
+          parsed?.error?.message ||
+          parsed?.message ||
+          (isJson
+            ? JSON.stringify(parsed).slice(0, 300)
+            : `non-JSON ${ctype || "response"} (likely an unhandled route)`);
+        const code = parsed?.error?.code ? ` [${parsed.error.code}]` : "";
+        throw new Error(`Kleap API ${res.status}${code} on ${method} ${path}: ${detail}`);
+      }
+
+      if (!isJson) {
+        throw new Error(`Kleap API returned non-JSON (${ctype}) for ${method} ${path}`);
+      }
+      return parsed;
+    } catch (e) {
+      clearTimeout(t);
+      lastErr =
+        e?.name === "AbortError"
+          ? new Error(`Kleap API timeout after ${timeoutMs}ms on ${method} ${path}`)
+          : e;
+      const retryable =
+        e?.name === "AbortError" ||
+        e?.code === "ECONNRESET" ||
+        e?.code === "ETIMEDOUT" ||
+        /fetch failed|network/i.test(e?.message || "");
+      if (retryable && attempt < retries) {
+        await sleep(400 * 2 ** attempt);
+        continue;
+      }
+      throw lastErr;
+    }
+  }
+  throw lastErr;
+}
+
+const num = (description) => ({ type: "number", description });
+const str = (description) => ({ type: "string", description });
+const obj = (properties, required) => ({
+  type: "object",
+  properties: properties || {},
+  ...(required ? { required } : {}),
+  additionalProperties: false,
+});
+
+/**
+ * The tool surface. Each maps 1:1 to an existing /api/v1 endpoint.
+ *
+ * Tool names + argument names are kept IDENTICAL to the hosted remote server
+ * (/api/mcp) on purpose, so an agent (or a tutorial) written for one transport
+ * works verbatim on the other. Arguments are snake_case (app_id, task_id).
+ */
+const TOOLS = [
+  {
+    name: "list_apps",
+    description:
+      "List the Kleap apps (websites) owned by the authenticated account, newest first. Returns a `pagination` object {total, limit, offset, has_more, next_offset}: the server caps `limit` at 100, so when `has_more` is true, page with `next_offset`. To find ONE site by its domain / URL / slug, use find_app instead of paging through everything.",
+    inputSchema: obj({
+      limit: num("Max apps to return (default 50, server max 100)."),
+      offset: num("Pagination offset (default 0)."),
+      q: str("Optional filter on app name or slug (substring match)."),
+    }),
+    handler: ({ limit, offset, q } = {}) => {
+      const params = new URLSearchParams();
+      if (limit != null) params.set("limit", String(limit));
+      if (offset != null) params.set("offset", String(offset));
+      if (q) params.set("q", q);
+      const qs = params.toString();
+      return api("GET", `/apps${qs ? `?${qs}` : ""}`);
+    },
+  },
+  {
+    name: "find_app",
+    description:
+      "Resolve a website the user names by its ADDRESS — a custom domain (\"serrureriesk.ch\"), a kleap.io URL (\"mysite.kleap.io\"), or a bare slug (\"mysite\") — to one of your apps in ONE call. Use this FIRST whenever the user refers to a site by its domain/URL instead of an app id, then pass the returned app_id to get_app / modify_app / publish_app. Do not list every app and scan. Returns NOT_FOUND if no owned app matches (the site may not be on this account or not connected yet) — then fall back to list_apps.",
+    inputSchema: obj(
+      { query: str("A domain, URL, or slug, e.g. 'serrureriesk.ch'.") },
+      ["query"],
+    ),
+    handler: ({ query }) =>
+      api("GET", `/apps/resolve?q=${encodeURIComponent(query)}`),
+  },
+  {
+    name: "get_app",
+    description:
+      "Get one Kleap app's metadata: status, slug, production_url, published state. Use this for general app info at any time. To specifically confirm a deploy/publish, use get_publish_status.",
+    inputSchema: obj({ app_id: num("The app id.") }, ["app_id"]),
+    handler: ({ app_id }) => api("GET", `/apps/${app_id}`),
+  },
+  {
+    name: "list_app_files",
+    description:
+      "List the source file PATHS of a Kleap app (names only — no contents). Use it to inspect the project structure, then read_files to get the actual contents before editing. To CHANGE files: read_files → edit with your model → write_files → publish_app (deterministic), or modify_app (you describe the change and Kleap's AI writes it).",
+    inputSchema: obj({ app_id: num("The app id.") }, ["app_id"]),
+    handler: ({ app_id }) => api("GET", `/apps/${app_id}/files`),
+  },
+  {
+    name: "read_files",
+    description:
+      "Read the FULL CONTENTS of existing files so you can edit them SAFELY instead of rewriting blind (which risks breaking shared components/homepages). This closes the loop: list_app_files → read_files → edit the exact text with YOUR model → write_files → publish_app. Use it to fix headers/footers, wrong phone numbers, broken links, dead forms, etc. Pass one or many paths. Allowed with a Read-only key. Returns { files: [{ path, content, type, bytes }], missing: [paths not found] }.",
+    inputSchema: obj(
+      {
+        app_id: num("The app id."),
+        paths: {
+          type: "array",
+          description:
+            "Project-relative file paths to read, from list_app_files (e.g. ['src/components/Header.astro','src/components/Footer.astro']).",
+          items: { type: "string" },
+        },
+      },
+      ["app_id", "paths"],
+    ),
+    handler: ({ app_id, paths }) =>
+      api(
+        "GET",
+        `/apps/${encodeURIComponent(app_id)}/files?paths=${encodeURIComponent(
+          (Array.isArray(paths) ? paths : [paths]).join(","),
+        )}`,
+      ),
+  },
+  {
+    name: "write_files",
+    description:
+      "Write source files DIRECTLY — YOUR agent's model generates the code, Kleap just stores, builds and deploys it. No Kleap-AI generation step, so it is DETERMINISTIC, uses NO Kleap credits, and never stalls (unlike asking an AI to build). Use this to scaffold exact files/pages — e.g. programmatic-SEO routes — instead of relying on modify_app. Paths are project-relative; these are Astro sites (src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*). Overwrites by path. AFTER writing, call publish_app to build & go live. (Prefer modify_app when you'd rather Kleap's AI figure out the change.)",
+    inputSchema: obj(
+      {
+        app_id: num("The app id."),
+        files: {
+          type: "array",
+          description:
+            "Files to write/overwrite. Each is { path, content }. path is project-relative (e.g. 'src/pages/services/[city].astro'); content is the full file text.",
+          items: {
+            type: "object",
+            properties: {
+              path: { type: "string" },
+              content: { type: "string" },
+            },
+            required: ["path", "content"],
+          },
+        },
+      },
+      ["app_id", "files"],
+    ),
+    handler: ({ app_id, files }) =>
+      api("PUT", `/apps/${encodeURIComponent(app_id)}/files`, { files }),
+  },
+  {
+    name: "create_app",
+    description:
+      "Create a new Kleap website (an Astro site) from a natural-language prompt. Returns app_id + task_id immediately; poll check_task until status='completed' (~5-15 min). The site auto-builds and goes LIVE on completion — no separate publish needed for the first version.",
+    inputSchema: obj(
+      {
+        prompt: str("What the website should be."),
+        visibility: str("'public' (discoverable) or 'personal' (private)."),
+        webhook_url: str(
+          "Optional HTTPS URL that Kleap POSTs when the build finishes — use it for a hands-off flow instead of polling check_task.",
+        ),
+      },
+      ["prompt"],
+    ),
+    handler: ({ prompt, visibility, webhook_url }) =>
+      api("POST", "/apps", {
+        prompt,
+        visibility: visibility || "personal",
+        ...(webhook_url ? { webhook_url } : {}),
+      }),
+  },
+  {
+    name: "modify_app",
+    description:
+      "Ask a Kleap app's AI to change it — describe the OUTCOME you want (edit copy, add a section or page, fix a bug); the AI writes the files (you cannot write files yourself). Returns a task — poll check_task. For MANY similar pages (programmatic SEO), ask in ONE call for a single dynamic Astro route + a data file, NOT one page per call.",
+    inputSchema: obj(
+      {
+        app_id: num("The app id."),
+        message: str("The change to make."),
+        webhook_url: str(
+          "Optional HTTPS URL that Kleap POSTs when the edit finishes — for a hands-off flow instead of polling check_task.",
+        ),
+      },
+      ["app_id", "message"],
+    ),
+    handler: ({ app_id, message, webhook_url }) =>
+      api("POST", `/apps/${app_id}/messages`, {
+        message,
+        ...(webhook_url ? { webhook_url } : {}),
+      }),
+  },
+  {
+    name: "rename_app",
+    description:
+      "Rename an app's display name. This does NOT change its URL — the live address ({slug}.kleap.io) and any links to it stay intact. (There is no delete tool, by design.)",
+    inputSchema: obj(
+      { app_id: num("The app id."), name: str("The new display name.") },
+      ["app_id", "name"],
+    ),
+    handler: ({ app_id, name }) =>
+      api("PATCH", `/apps/${app_id}`, { name }),
+  },
+  {
+    name: "check_task",
+    description:
+      "Check an async create/modify task. By default it LONG-POLLS: the call holds for up to 'wait' seconds and returns the moment the task finishes — so you wait efficiently instead of hammering this every few seconds through a 5-15 min build. Just call it again if status is still queued/processing. status is one of: queued, processing, completed, failed. On 'completed' the change is built and LIVE (app_id + production_url available). On 'failed', error.code is TASK_TIMEOUT or STALE_TASK (the build STALLED — transient — call retry_task, which returns a NEW task_id to poll) or TASK_FAILED (generation failed — read error.message; retry_task once, and if it repeats, stop and tell the user). (Out-of-credits is not a task failure — create_app/modify_app reject up front with 402 INSUFFICIENT_CREDITS.)",
+    inputSchema: obj(
+      {
+        task_id: str("The task id."),
+        wait: num(
+          "Seconds to long-poll, 0-50 (default 45). The call returns early the instant the task reaches completed/failed. Use 0 for an immediate snapshot.",
+        ),
+      },
+      ["task_id"],
+    ),
+    handler: ({ task_id, wait }) => {
+      const w = wait == null ? 45 : Math.min(Math.max(Number(wait) || 0, 0), 50);
+      return api(
+        "GET",
+        `/tasks/${encodeURIComponent(task_id)}?wait=${w}`,
+        undefined,
+        { timeoutMs: (w + 15) * 1000 },
+      );
+    },
+  },
+  {
+    name: "retry_task",
+    description:
+      "Resume a failed/stalled create/modify task from where it stopped (partial files preserved). Use when check_task reports 'failed', instead of starting a brand-new create_app. Returns a NEW task_id — poll check_task on that NEW id (not the original). Budget: retry TASK_TIMEOUT/STALE_TASK up to TWICE; retry TASK_FAILED only ONCE; then stop and tell the user. NEVER retry a non-transient error (402 INSUFFICIENT_CREDITS, a rejected prompt) — it just fails again.",
+    inputSchema: obj({ task_id: str("The failed task id to resume.") }, [
+      "task_id",
+    ]),
+    handler: ({ task_id }) => api("POST", `/tasks/${task_id}/retry`, {}),
+  },
+  {
+    name: "publish_app",
+    description:
+      "Build & publish an app to its live URL, with the VERIFIED-LIVE guarantee: only reported live once provably serving (else 'not confirmed live' — never a false positive). REQUIRED after write_files (that stores files but does not deploy). NOT needed after create_app/modify_app (those auto-deploy on completion). Returns a deploy handle; poll get_publish_status. If it reports not-confirmed-live, keep polling get_publish_status — do not loop publish_app.",
+    inputSchema: obj({ app_id: num("The app id.") }, ["app_id"]),
+    handler: ({ app_id }) => api("POST", `/apps/${app_id}/publish`, {}),
+  },
+  {
+    name: "get_publish_status",
+    description:
+      "Confirm whether an app is actually published and live (production_url + published state) — use this to answer \"is it live yet?\", typically after publish_app. For general app metadata use get_app instead.",
+    inputSchema: obj({ app_id: num("The app id.") }, ["app_id"]),
+    handler: ({ app_id }) => api("GET", `/apps/${app_id}/publish`),
+  },
+  {
+    name: "get_credits",
+    description:
+      "Check the authenticated account's remaining credit balance and plan.",
+    inputSchema: obj(),
+    handler: () => api("GET", "/account/credits"),
+  },
+  {
+    name: "search_domains",
+    description:
+      "Search for available domains for a site (e.g. 'mybakery'). Returns available names across TLDs. NOTE: agents cannot buy a domain — purchase is confirmed by the user in Kleap. Use connect_domain for a domain the user already owns.",
+    inputSchema: obj(
+      {
+        query: str("Base name to search, without a TLD (e.g. 'mybakery')."),
+        tlds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional TLDs to check, e.g. ['.com', '.io', '.ch'].",
+        },
+      },
+      ["query"],
+    ),
+    handler: ({ query, tlds }) => api("POST", "/domains/search", { query, tlds }),
+  },
+  {
+    name: "check_domain",
+    description:
+      "Check a domain's connection / DNS status for a Kleap app.",
+    inputSchema: obj({ domain: str("The domain, e.g. 'mybakery.com'.") }, [
+      "domain",
+    ]),
+    handler: ({ domain }) =>
+      api("GET", `/domains/${encodeURIComponent(domain)}/check`),
+  },
+  {
+    name: "connect_domain",
+    description:
+      "Connect a domain the user ALREADY OWNS to a live Kleap app (sets up routing + automatic TLS). The app must be live first — a completed create_app/modify_app already counts as published, so you do NOT need to call publish_app first. The response includes a `dns_config` object with the exact A records the user must set at their registrar (+ propagation time) — relay those to the user. Does not buy anything.",
+    inputSchema: obj(
+      {
+        app_id: num("The app id (must be published)."),
+        domain: str("The domain to connect, e.g. 'mybakery.com'."),
+      },
+      ["app_id", "domain"],
+    ),
+    handler: ({ app_id, domain }) =>
+      api("POST", "/domains/connect", { app_id, domain }),
+  },
+];
+
+const INSTRUCTIONS = `Kleap builds and HOSTS real websites (Astro). You have TWO ways to put code on a site — pick per task:
+  • write_files (DETERMINISTIC, recommended when you know the code): YOUR model writes the exact file contents; push them with write_files(app_id, files); Kleap stores, builds and deploys them AS-IS. No Kleap-AI generation step → no Kleap credits, and it never stalls. Best for precise scaffolding: pages, components, data files, programmatic SEO. Then call publish_app to go live.
+  • modify_app (Kleap's AI does it): describe the OUTCOME in plain language and Kleap's AI writes the files. Best when you'd rather it figure out the change than write the code yourself.
+Either way KLEAP HOSTS the result — build, deploy, SSL, database, auth, forms, custom domains, and the verified-live guarantee. Use list_app_files first to see the project structure (paths only; these are Astro sites: src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*).
+
+TO EDIT AN EXISTING SITE SAFELY — never rewrite a file blind. Do: list_app_files → read_files(app_id, [paths]) to get the CURRENT contents → edit only what must change with your model → write_files the edited files → publish_app. This is the reliable way to fix shared components, headers/footers, wrong phone numbers, broken links, dead forms, etc. (read_files works with a Read-only key, so you can always inspect before changing.) Prefer this read→edit→write loop over modify_app when you need a precise, verifiable change — modify_app hands the edit to Kleap's AI and may not apply exactly what you intend.
+
+THE LOOP
+1. Find the site. If the user names it by address ("serrureriesk.ch", "mysite.kleap.io"), call find_app FIRST. If find_app returns NOT_FOUND, the site isn't on this account or isn't connected yet — fall back to list_apps (supports ?q=) or ask the user. Otherwise use list_apps.
+2. Build or change it — two paths:
+   - DETERMINISTIC (your code): write_files(app_id, [{path, content}, ...]) to push exact files, then publish_app(app_id) to build + deploy. No task, no stall. Best for adding/scaffolding pages you can write yourself.
+   - AI (Kleap writes it): create_app(prompt) for a brand-new site, or modify_app(app_id, message) to change one. These return a task_id. Call check_task(task_id) — it LONG-POLLS by default (holds up to 50s, default 45, and returns the instant the build finishes), so just call it again while status is queued/processing. A full build is ~5-15 min, NOT instant, so calling check_task ~10-20 times in a row through one build is EXPECTED — that is normal waiting, not a "loop" (the loop warnings below are only about retrying failed tasks). For a fully hands-off flow, create_app/modify_app also accept a webhook_url that is POSTed when the task finishes.
+3. When status="completed", the change is already BUILT AND LIVE at the production URL — create_app and modify_app auto-deploy. (publish_app + get_publish_status only force/verify a re-publish; you normally don't need them after a build.) connect_domain attaches a domain the user already owns (the app must be live first).
+
+ON FAILURE (check_task status="failed"): error.code is one of:
+  - TASK_TIMEOUT / STALE_TASK → the build STALLED (transient). Call retry_task(task_id); it returns a NEW task_id — poll check_task on THAT id. Retry up to twice.
+  - TASK_FAILED → generation failed. Read error.message; retry_task once. If it repeats, STOP and tell the user. Do NOT loop.
+
+ERRORS BEFORE A TASK STARTS (HTTP errors thrown by create_app/modify_app, with an error.code): 402 INSUFFICIENT_CREDITS (check get_credits and ask the user to top up — do NOT retry), 400 VALIDATION_ERROR (fix the input), 401 UNAUTHORIZED (bad/expired key), 429 RATE_LIMITED (back off, honor Retry-After), 404 NOT_FOUND (wrong app_id — use find_app).
+
+Send ONE coherent change per modify_app call.
+
+MANY PAGES / PROGRAMMATIC SEO — read this before you start:
+BEST (deterministic, no stall): use write_files. Generate, with YOUR own model, a dynamic Astro route + a data file, and push them in one write_files call, then publish_app. Example files: src/pages/[service]/[city].astro (a layout that maps over the data) + src/data/locations.json (your full list). One write_files + one publish_app ships every page, scales to thousands, costs no Kleap credits, and cannot stall. This is THE recommended path — especially since asking the AI to scaffold new pages can stall.
+ALTERNATIVE (let Kleap's AI do it): ONE modify_app call asking for "a dynamic route src/pages/[service]/[city].astro driven by src/data/locations.json with <your list>, plus a /services index linking them." Never make N create/modify calls (one per page) — that stalls.
+
+rename_app changes only the display name — the live URL never changes. There is no delete tool, by design.
+
+KEYS & SCOPES: this server can't manage API keys. Users create and SCOPE keys in Kleap (Settings -> MCP / API access): pick Read-only, Build, or Full. Read-only allows only the read tools (list_apps, find_app, get_app, list_app_files, read_files, get_publish_status, check_domain, search_domains, get_credits) and a write tool with a read-only key returns 401/403; Build/Full additionally allow create_app, modify_app, write_files, rename_app, publish_app, connect_domain. So for a read-only agent, tell the user to generate a Read-only key there. Buying domains is never included by default.`;
+
+const server = new Server(
+  { name: "kleap", version: "1.0.10" },
+  { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find((t) => t.name === req.params.name);
+  if (!tool) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+    };
+  }
+  try {
+    const result = await tool.handler(req.params.arguments || {});
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (e) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error: ${e?.message || e}` }],
+    };
+  }
+});
+
+// ── CLI dispatch ────────────────────────────────────────────────────────────
+// `kleap auth <login|logout|status>` runs and exits; no args = the MCP server.
+const cmd = process.argv.slice(2);
+if (cmd[0] === "auth") {
+  const sub = cmd[1];
+  if (sub === "login") {
+    await authLogin();
+    process.exit(0);
+  }
+  if (sub === "logout") {
+    const c = readConfig();
+    delete c.oauth;
+    writeConfig(c);
+    console.error("[kleap] Signed out (cleared ~/.kleap/config.json).");
+    process.exit(0);
+  }
+  if (sub === "status") {
+    const t = await resolveToken();
+    if (!t) {
+      console.error("[kleap] Not signed in. Run `npx kleap auth login`.");
+      process.exit(1);
+    }
+    console.error(
+      process.env.KLEAP_API_KEY
+        ? "[kleap] Authenticated via KLEAP_API_KEY (env)."
+        : "[kleap] Signed in via OAuth (~/.kleap/config.json).",
+    );
+    process.exit(0);
+  }
+  console.error("[kleap] Usage: kleap auth <login|logout|status>");
+  process.exit(1);
+}
+
+// Default: run the stdio MCP server. Resolve auth first.
+AUTH_TOKEN = await resolveToken();
+if (!AUTH_TOKEN) {
+  console.error(
+    "[kleap-mcp] Not signed in. Run `npx kleap auth login` (opens your browser, no API key needed),\n" +
+      "             or set KLEAP_API_KEY=kleap_live_sk_... (https://kleap.co/settings/api-key).",
+  );
+  process.exit(1);
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `[kleap-mcp] ready (stdio) → ${API_URL}. Tools: ${TOOLS.map((t) => t.name).join(", ")}`,
+);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@eliottd/kleap",
+  "version": "1.1.0",
+  "description": "Website infrastructure for AI agents. Drive Kleap from any MCP client (Claude, ChatGPT, Cursor) — create, edit and publish real websites, with the verified-live guarantee.",
+  "type": "module",
+  "bin": {
+    "kleap": "kleap-mcp-server.mjs"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "start": "node kleap-mcp-server.mjs"
+  },
+  "files": [
+    "kleap-mcp-server.mjs",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kleap",
+    "ai-agent",
+    "website-builder",
+    "claude",
+    "chatgpt",
+    "cursor",
+    "ai",
+    "publish"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kleap-co/kleap.git"
+  },
+  "homepage": "https://kleap.co/mcp",
+  "bugs": {
+    "url": "https://github.com/Kleap-co/kleap/issues"
+  },
+  "license": "MIT",
+  "author": "Kleap"
+}

package/skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: kleap
+description: >-
+  Build, edit and publish real websites with Kleap from inside this agent, via
+  the Kleap MCP server. Use when the user wants to create a website or web app,
+  change a site they made on Kleap, connect a domain, or take a site live —
+  especially when they want it actually hosted and online, not just code. Kleap
+  provides the hosting, database, auth, domains and a verified-live publish.
+---
+
+# Driving Kleap
+
+Kleap is website infrastructure for agents: you describe a site, Kleap builds it
+(hosting + database + auth included), connects a domain, and publishes it with a
+**verified-live guarantee**. You drive it through the Kleap MCP tools
+(`create_app`, `modify_app`, `check_task`, `publish_app`, etc.).
+
+## The golden rule: never claim a site is live until Kleap confirms it
+
+A deploy being *started* is NOT the same as a site being *online*. Only state
+that a site is live after `get_publish_status` (or `check_task`) returns
+`status: "published"` with a `production_url`. If it isn't confirmed, say so
+plainly — never invent a working URL.
+
+## Core flow — create a site
+
+1. `create_app({ prompt })` — give a detailed description. Returns `{ app_id, task_id }`.
+2. Poll `check_task({ task_id })` every ~10–15s until `status` is `completed` or `failed`. Building usually takes a couple of minutes (up to ~15 for complex sites) — check_task long-polls so you don't babysit it.
+3. If `failed` (transient stalls happen): call `retry_task({ task_id })` with the
+   SAME task_id — it resumes from partial state and preserves files already
+   written. Do not start a brand-new `create_app`. Then poll `check_task` on the
+   new task_id. Retry once or twice before giving up.
+4. `publish_app({ app_id })` → then poll `get_publish_status({ app_id })` until
+   `status: "published"`. Report the `production_url` only then.
+
+## Edit an existing site
+
+`modify_app({ app_id, message })` with a clear, specific instruction (e.g.
+"Change the headline to X and make the background charcoal"). It returns a task —
+poll `check_task`, then `publish_app` to push the change live. Editing is
+reliable; prefer it over recreating.
+
+## Domains
+
+- `search_domains({ query })` — find available names. **You cannot buy a domain**
+  — purchase is confirmed by the user in Kleap. Tell the user to complete the
+  purchase there, then continue.
+- `connect_domain({ app_id, domain })` — connect a domain the user ALREADY owns
+  to a published app (the app must be published first). The user points the
+  domain's A record to Kleap; TLS is automatic.
+- `check_domain({ domain })` — DNS / connection status.
+
+## Conventions
+
+- Arguments are snake_case: `app_id`, `task_id`, `prompt`, `message`, `visibility`.
+- `visibility` is `"personal"` (private, default) or `"public"` (discoverable).
+- Use `get_credits` if a create/modify fails for quota reasons.
+- One app per site. Keep the user's `app_id` to make later edits.
+
+## What good looks like
+
+> User: "Make me a landing page for my bakery and put it online."
+> You: create_app → poll check_task → publish_app → poll get_publish_status →
+> "It's live at your-bakery.kleap.io ✅" (only after it's confirmed serving).