appilot-mcp 0.2.1 → 0.3.0

package/dist/index.bundle.js

@@ -21821,7 +21821,7 @@ var SERVER_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    SERVER_VERSION = "0.2.1";
+    SERVER_VERSION = "0.3.0";
   }
 });
 
@@ -21859,6 +21859,9 @@ function localized(entity, field) {
   if (Array.isArray(rows) && rows.length) return fromTranslationRows(rows, field);
   return fromBaseAndI18n(entity[field], entity[`${field}_i18n`], entity.source_locale);
 }
+function credentialAdvice(hasToken) {
+  return hasToken ? "The credential was rejected. Check it in the Backoffice under Service tokens: it may be revoked, expired, or scoped to another app. A token narrowed to one app is refused on every other app in the organization." : 'No credential is set. Put a service token in APPILOT_PAT in the MCP client environment and restart the client. Mint one in the Backoffice under Service tokens: "Inspect only" to read and audit, "Edit configuration" to write, "Set up integrations" to create apps, domains and widget keys.';
+}
 function safeJson(text) {
   try {
     return JSON.parse(text);
@@ -22007,8 +22010,9 @@ var init_client = __esm({
         const text = await res.text();
         const body = text ? safeJson(text) : void 0;
         if (!res.ok) {
+          const credential = res.status === 401 || res.status === 403 ? ` ${credentialAdvice(!!this.conn.token)}` : "";
           throw new AppilotApiError(
-            `${init.method ?? "GET"} ${path} failed: ${describeError(body, res)}`,
+            `${init.method ?? "GET"} ${path} failed: ${describeError(body, res)}${credential}`,
             res.status,
             body
           );
@@ -22112,6 +22116,16 @@ var init_client = __esm({
       listProvisioned() {
         return this.request("/provision/apps");
       }
+      /**
+       * The org's widget keys, prefixes only.
+       *
+       * A caller that cannot see the keys it already minted asks for another every
+       * run, and each one is a live credential.
+       */
+      async listWidgetKeys() {
+        const body = await this.request("/provision/widget-keys");
+        return Array.isArray(body?.widgetKeys) ? body.widgetKeys : [];
+      }
       provisionApp(body) {
         return this.request("/provision/app", { method: "POST", body: JSON.stringify(body) });
       }
@@ -22128,6 +22142,21 @@ var init_client = __esm({
         const url2 = /^https?:\/\//i.test(domain) ? domain : `https://${domain}`;
         return this.request(`/domain/check?url=${encodeURIComponent(url2)}`);
       }
+      /**
+       * The TXT record a domain needs, and where its verification stands.
+       *
+       * These two live on the apps router rather than under `/provision`, and that
+       * router authenticates an organization SESSION. A service token is refused
+       * there today, which is why `verify_domain` falls back to the provisioning
+       * dry run for the status and says plainly what it could not do.
+       */
+      domainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verification`);
+      }
+      /** Ask Appilot to look for the TXT record now. */
+      triggerDomainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verify`, { method: "POST" });
+      }
       /** Who this credential is: org, app narrowing, scopes. Never a secret. */
       whoami() {
         return this.request("/config/whoami");
@@ -22180,6 +22209,10 @@ var init_client = __esm({
           read("knowledge", () => this.listKnowledge(appId), mapKnowledge),
           expectedLocales?.length ? Promise.resolve(expectedLocales) : this.resolveLocales(appId)
         ]);
+        if (knowledge.length === 0 && !gaps.some((g) => g.entity === "knowledge")) {
+          const refusal = await this.credentialRefusal();
+          if (refusal) gaps.push({ entity: "knowledge", reason: refusal });
+        }
         return {
           expectedLocales: locales,
           views,
@@ -22192,6 +22225,28 @@ var init_client = __esm({
           ...gaps.length ? { gaps } : {}
         };
       }
+      /**
+       * Why an empty read should not be believed, or null when the credential is
+       * fine and the app genuinely has nothing.
+       *
+       * Only a 401 or a 403 counts. An instance too old to answer `whoami` at all
+       * says nothing about the token, and reporting a gap on that would be a
+       * confident false alarm on every on-premise deployment behind cloud.
+       */
+      async credentialRefusal() {
+        if (!this.conn.token) {
+          return `No service token is set, so the knowledge read was anonymous and answered an empty list rather than refusing. ${credentialAdvice(false)}`;
+        }
+        try {
+          await this.whoami();
+          return null;
+        } catch (err) {
+          if (err instanceof AppilotApiError && (err.status === 401 || err.status === 403)) {
+            return `The knowledge read returned nothing and the credential failed its own self-check, so the empty result is not evidence of an empty knowledge base. ${credentialAdvice(true)}`;
+          }
+          return null;
+        }
+      }
       /**
        * Which locales this app's configuration is expected to cover: the union of
        * its domains' configured languages. Falls back to the trilingual baseline
@@ -23024,6 +23079,10 @@ function planMarkers(plan) {
 function localizedValues(text) {
   return Object.values(text).filter((v) => typeof v === "string");
 }
+function authoredFormValues(plan) {
+  const raw = plan.form_values;
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
 function lintMarkers(snap) {
   const controlIds = new Set(snap.controls.map((c) => c.semantic_id));
   const formIds = new Set(snap.forms.map((f) => f.semantic_id));
@@ -23041,7 +23100,7 @@ function lintMarkers(snap) {
         recommendation: "Each step needs exactly one executable marker resolving to a known control/form; values never go in the marker."
       });
     }
-    for (const [formId, entry] of Object.entries(plan.form_values)) {
+    for (const [formId, entry] of Object.entries(authoredFormValues(plan))) {
       if (!formIds.has(formId)) {
         findings.push({
           severity: "high",
@@ -23051,8 +23110,19 @@ function lintMarkers(snap) {
         });
         continue;
       }
+      const authored = entry;
+      if (!authored || !Array.isArray(authored.fields)) {
+        findings.push({
+          severity: "high",
+          category: "markers",
+          entity: `action_plan:${plan.semantic_id}`,
+          message: `form_values["${formId}"] is not in the authored shape { fields: [{ control_id, value }] }.`,
+          recommendation: "Write an empty fields array when there are no authored defaults."
+        });
+        continue;
+      }
       const fields = fieldsByForm.get(formId) ?? /* @__PURE__ */ new Set();
-      for (const f of entry.fields) {
+      for (const f of authored.fields) {
         if (!fields.has(f.control_id)) {
           findings.push({
             severity: "high",
@@ -23075,7 +23145,7 @@ function lintActionability(snap) {
     const markers = planMarkers(plan);
     const hasFormStep = markers.some((m) => m.kind === "form");
     const hasSetValue = markers.some((m) => m.kind === "set_value" || m.kind === "select");
-    const hasFormValues = Object.keys(plan.form_values).length > 0;
+    const hasFormValues = Object.keys(authoredFormValues(plan)).length > 0;
     const entersValue = hasFormStep || hasSetValue || hasFormValues;
     const looksLikeCreate = localizedValues({ ...plan.name, ...plan.description }).some((v) => CREATE_INTENT.test(v)) || CREATE_INTENT.test(plan.semantic_id);
     const formFieldIds = new Set(snap.forms.flatMap((f) => f.field_ids));
@@ -23093,7 +23163,7 @@ function lintActionability(snap) {
       if (!form.submit_control_id) continue;
       const clicksSubmit = markers.some((m) => m.kind === "click" && m.id === form.submit_control_id);
       if (!clicksSubmit) continue;
-      const fillsForm = markers.some((m) => m.kind === "form" && m.id === form.semantic_id) || (plan.form_values[form.semantic_id]?.fields?.length ?? 0) > 0;
+      const fillsForm = markers.some((m) => m.kind === "form" && m.id === form.semantic_id) || (authoredFormValues(plan)[form.semantic_id]?.fields?.length ?? 0) > 0;
       if (!fillsForm) {
         findings.push({
           severity: "high",
@@ -23441,6 +23511,17 @@ async function planManifest(client, manifest, resolveAppId) {
   }
   return { planToken: manifestDigest(manifest), provisioning, config: config2, notes };
 }
+function provisioningChanges(preview) {
+  const changes = [];
+  if (preview.app.action !== "reused") changes.push(`the app "${preview.app.name}" (${preview.app.action})`);
+  for (const domain of preview.domains) {
+    if (domain.action !== "reused") changes.push(`the domain ${domain.domain} (${domain.action})`);
+  }
+  if (preview.widgetKey && preview.widgetKey.action !== "reused") {
+    changes.push(`a widget key (${preview.widgetKey.action})`);
+  }
+  return changes;
+}
 async function applyManifest(client, manifest, options) {
   const expected = manifestDigest(manifest);
   if (options.planToken !== expected) {
@@ -23449,7 +23530,23 @@ async function applyManifest(client, manifest, options) {
     );
   }
   const notes = [];
-  const provisioning = await client.provisionApp(provisionRequest(manifest, false));
+  const preview = await client.provisionApp(provisionRequest(manifest, true));
+  const changes = provisioningChanges(preview);
+  if (changes.length > 0 && options.provisionRefusal) {
+    throw new Error(
+      `${options.provisionRefusal}
+This manifest would change ${changes.join(", ")}, so the apply cannot proceed without it. A manifest whose app, domains and keys already exist applies with config:write alone.`
+    );
+  }
+  let provisioning;
+  if (changes.length === 0) {
+    provisioning = preview;
+    notes.push(
+      "Provisioning wrote nothing: the app, its domains and its keys already matched the manifest, so this apply needed only config:write. The provisioning block below is the preview, which is why it reports dryRun true."
+    );
+  } else {
+    provisioning = await client.provisionApp(provisionRequest(manifest, false));
+  }
   let config2;
   if (manifest.config) {
     const appId = provisioning.app.id;
@@ -23487,6 +23584,32 @@ var init_manifest = __esm({
 });
 
 // src/scaffold.ts
+function publicKeyIdiom(framework) {
+  switch (framework) {
+    case "next":
+      return {
+        envName: "NEXT_PUBLIC_APPILOT_WIDGET_KEY",
+        expr: "process.env.NEXT_PUBLIC_APPILOT_WIDGET_KEY"
+      };
+    case "sveltekit":
+      return {
+        envName: "PUBLIC_APPILOT_WIDGET_KEY",
+        expr: "publicEnv.PUBLIC_APPILOT_WIDGET_KEY",
+        importLine: "import { env as publicEnv } from '$env/dynamic/public';"
+      };
+    default:
+      return {
+        envName: "VITE_APPILOT_WIDGET_KEY",
+        expr: "import.meta.env.VITE_APPILOT_WIDGET_KEY"
+      };
+  }
+}
+function localDevelopmentNotes(idiom) {
+  return [
+    "Local development, first choice: run the app on a hostname that resolves to 127.0.0.1 (myapp.lvh.me:3000, or an /etc/hosts entry such as myapp.local) and register THAT hostname as a domain of the app. The page then resolves its tenant by its own hostname, no widget key is needed at all, DNS verification is not required for this path, and the turn gets the full app context: views, controls, forms, action plans and knowledge.",
+    `Local development, fallback: on bare localhost no domain resolves, so the page needs a wk_test_ key in ${idiom.envName}. The turn gets the organization and the signed-in user and NO app context, because there is no domain to resolve it from. Use this only where the hostname above is impossible.`
+  ];
+}
 function relayFetchHandler(namespace) {
   return `import { createWidgetTokenHandler } from 'appilot-server';
 
@@ -23508,36 +23631,70 @@ export const POST = createWidgetTokenHandler({
 `;
 }
 function relayNodeHandler(namespace, framework) {
-  const mount = framework === "express" ? `app.post('/api/widget/token', relay);` : `fastify.post('/api/widget/token', (request, reply) => relay(request.raw, reply.raw));`;
-  return `import { createNodeWidgetTokenHandler } from 'appilot-server/node';
+  const head = `import type { IncomingMessage } from 'node:http';
+import { createNodeWidgetTokenHandler } from 'appilot-server/node';
+
+/** What your session middleware puts on the request. Yours will differ. */
+type RequestWithSession = IncomingMessage & {
+  session?: { user?: { id: string | number; name?: string } };
+};
 
 // resolveUser is the security boundary. Derive the user from a credential you
 // trust (req.session, req.user). Never from the request body.
 const relay = createNodeWidgetTokenHandler({
-  apiUrl: process.env.APPILOT_API_URL,
-  widgetKey: process.env.APPILOT_WIDGET_KEY,
-  widgetSecret: process.env.APPILOT_WIDGET_SECRET,   // server-side only
+  apiUrl: process.env.APPILOT_API_URL!,
+  widgetKey: process.env.APPILOT_WIDGET_KEY!,
+  widgetSecret: process.env.APPILOT_WIDGET_SECRET!,   // server-side only
   resolveUser: req => {
-    const user = req.session?.user;                  // your auth, unchanged
-    if (!user) return null;                          // 401 IDENTITY_REQUIRED
+    const user = (req as RequestWithSession).session?.user;  // your auth, unchanged
+    if (!user) return null;                                  // 401 IDENTITY_REQUIRED
     return { externalId: \`${namespace}:\${user.id}\`, displayName: user.name };
   },
 });
+`;
+  if (framework === "express") {
+    return `${head}
+import type { Express } from 'express';
+
+export function mountWidgetToken(app: Express): void {
+  app.post('/api/widget/token', relay);
+}
+`;
+  }
+  return `${head}
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 
-${mount}
+export function mountWidgetToken(fastify: FastifyInstance): void {
+  fastify.post('/api/widget/token', async (request: FastifyRequest, reply: FastifyReply) => {
+    // The relay answers the raw response itself, so Fastify has to be told it
+    // no longer owns the reply. Without hijack() it reports "Reply was already
+    // sent" on every call.
+    reply.hijack();
+    await relay(request.raw, reply.raw);
+  });
+}
 `;
 }
 function bootFile(options) {
-  const lines = [
-    "import { bootAppilotWidget } from 'appilot';",
+  const idiom = publicKeyIdiom(options.framework);
+  const lines = ["import { bootAppilotWidget } from 'appilot';"];
+  if (idiom.importLine) lines.push(idiom.importLine);
+  lines.push(
+    "",
+    "// The widget key is publishable: it names the app to Appilot and is meant to",
+    "// sit in the page. The widget SECRET is a server credential and never appears",
+    `// in this file. Leave ${idiom.envName} unset when the page runs on a hostname`,
+    "// you registered as a domain: the tenant then resolves from the hostname and",
+    "// the turn gets the full app context.",
+    `const widgetKey = ${idiom.expr};`,
     "",
     "// Call once, after your app knows the user is signed in. The widget",
-    "// requires an identified user; the relay below mints that identity.",
+    "// requires an identified user; the relay mints that identity.",
     "export function startAppilot() {",
     "  bootAppilotWidget({",
-    `    widgetScriptUrl: '${options.widgetScriptUrl}',`
-  ];
-  if (options.widgetKey) lines.push(`    widgetKey: '${options.widgetKey}',`);
+    `    widgetScriptUrl: '${options.widgetScriptUrl}',`,
+    "    widgetKey,"
+  );
   if (options.apiUrl) lines.push(`    appilotApiUrl: '${options.apiUrl}',`);
   lines.push(
     "    tokenEndpoint: '/api/widget/token',",
@@ -23546,8 +23703,142 @@ function bootFile(options) {
   );
   return lines.join("\n") + "\n";
 }
+function rawExchangeFiles(namespace, apiUrl) {
+  return [
+    {
+      path: "appilot/widget-token.sh",
+      language: "bash",
+      contents: `# The whole relay, as one call. Run it from your BACKEND, never a browser:
+# the widget secret authenticates the exchange and must never leave the server.
+curl -sS -X POST '${apiUrl}/widget/token' \\
+  -H 'Content-Type: application/json' \\
+  -H "X-Widget-Key: $APPILOT_WIDGET_KEY" \\
+  -H "X-Widget-Secret: $APPILOT_WIDGET_SECRET" \\
+  -d '{"externalId":"${namespace}:4711","displayName":"Ada Lovelace"}'
+
+# 200 -> {"token":"...","expiresIn":900}. Return that body to the page as-is.
+`
+    },
+    {
+      path: "appilot/widget_token.py",
+      language: "python",
+      contents: `"""Appilot identity relay, Django view. Flask and FastAPI differ only in the
+decorator and the response helper.
+
+The user is resolved from the session the host already trusts. Never from the
+request body: the body is client-supplied, so reading an id from it would let
+any caller ask for any user's token.
+"""
+
+import os
+import json
+import urllib.request
+
+APPILOT_API_URL = os.environ["APPILOT_API_URL"]
+WIDGET_KEY = os.environ["APPILOT_WIDGET_KEY"]
+WIDGET_SECRET = os.environ["APPILOT_WIDGET_SECRET"]  # server-side only
+NAMESPACE = "${namespace}"
+
+
+def widget_token(request):
+    from django.http import JsonResponse
+
+    user = getattr(request, "user", None)
+    if user is None or not user.is_authenticated:
+        return JsonResponse({"code": "IDENTITY_REQUIRED"}, status=401)
+
+    payload = json.dumps(
+        {
+            "externalId": f"{NAMESPACE}:{user.pk}",
+            "displayName": user.get_full_name() or user.get_username(),
+        }
+    ).encode()
+
+    req = urllib.request.Request(
+        f"{APPILOT_API_URL}/widget/token",
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "X-Widget-Key": WIDGET_KEY,
+            "X-Widget-Secret": WIDGET_SECRET,
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as response:
+            body = json.load(response)
+    except Exception:
+        # Never forward the upstream message: it is not yours to surface.
+        return JsonResponse({"code": "WIDGET_TOKEN_EXCHANGE_FAILED"}, status=502)
+
+    return JsonResponse({"token": body["token"], "expiresIn": body["expiresIn"]})
+`
+    },
+    {
+      path: "appilot/widget_token_controller.rb",
+      language: "ruby",
+      contents: `# Appilot identity relay, Rails controller.
+#
+# current_user comes from the session Rails already established. Never from
+# params: those are client-supplied, and reading an id from them would let any
+# caller ask for any user's token.
+require "net/http"
+require "json"
+
+class WidgetTokenController < ApplicationController
+  NAMESPACE = "${namespace}".freeze
+
+  def create
+    return render(json: { code: "IDENTITY_REQUIRED" }, status: :unauthorized) unless current_user
+
+    uri = URI("#{ENV.fetch('APPILOT_API_URL')}/widget/token")
+    request = Net::HTTP::Post.new(uri)
+    request["Content-Type"] = "application/json"
+    request["X-Widget-Key"] = ENV.fetch("APPILOT_WIDGET_KEY")
+    request["X-Widget-Secret"] = ENV.fetch("APPILOT_WIDGET_SECRET") # server-side only
+    request.body = {
+      externalId: "#{NAMESPACE}:#{current_user.id}",
+      displayName: current_user.name
+    }.to_json
+
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 10) do |http|
+      http.request(request)
+    end
+
+    unless response.is_a?(Net::HTTPSuccess)
+      # Never forward the upstream message.
+      return render(json: { code: "WIDGET_TOKEN_EXCHANGE_FAILED" }, status: :bad_gateway)
+    end
+
+    body = JSON.parse(response.body)
+    render json: { token: body["token"], expiresIn: body["expiresIn"] }
+  end
+end
+`
+    }
+  ];
+}
+function rawBootFile(options) {
+  const keyAttr = options.widgetKey ? `
+  data-api-key="${options.widgetKey}"` : "";
+  const apiAttr = options.apiUrl ? `
+  data-api-url="${options.apiUrl}"` : "";
+  return {
+    path: "appilot/widget-snippet.html",
+    language: "html",
+    contents: `<!-- Paste into the layout template your signed-in pages render.
+     The relay above must answer at /api/widget/token on the same origin. -->
+<script
+  src="${options.widgetScriptUrl}"${keyAttr}${apiAttr}
+  async
+></script>
+`
+  };
+}
 function scaffoldIntegration(options) {
   const namespace = options.idNamespace ?? "app";
+  const apiUrl = options.apiUrl ?? "https://api.appilot.space";
+  const idiom = publicKeyIdiom(options.framework);
   const files = [];
   switch (options.framework) {
     case "next":
@@ -23584,18 +23875,21 @@ export const action = ({ request }: { request: Request }) => handler(request);
         language: "typescript",
         contents: `import { createWidgetTokenHandler } from 'appilot-server';
 import { env } from '$env/dynamic/private';
+import type { RequestHandler } from './$types';
 
 const handler = createWidgetTokenHandler({
-  apiUrl: env.APPILOT_API_URL,
-  widgetKey: env.APPILOT_WIDGET_KEY,
-  widgetSecret: env.APPILOT_WIDGET_SECRET,
+  // $env/dynamic/private is Record<string, string | undefined>, so each value is
+  // asserted here rather than handed to the relay as possibly-undefined.
+  apiUrl: env.APPILOT_API_URL!,
+  widgetKey: env.APPILOT_WIDGET_KEY!,
+  widgetSecret: env.APPILOT_WIDGET_SECRET!,
   resolveUser: async request => {
     const user = await getUserFromCookies(request.headers.get('cookie'));
     return user ? { externalId: \`${namespace}:\${user.id}\`, displayName: user.name } : null;
   },
 });
 
-export const POST = ({ request }) => handler(request);
+export const POST: RequestHandler = ({ request }) => handler(request);
 `
       });
       break;
@@ -23628,38 +23922,95 @@ export const widgetToken = new Hono().post('/api/widget/token', c => handler(c.r
         contents: relayNodeHandler(namespace, options.framework)
       });
       break;
+    case "other":
+      files.push(...rawExchangeFiles(namespace, apiUrl));
+      break;
+  }
+  if (options.framework === "other") {
+    files.push(rawBootFile(options));
+  } else {
+    files.push({ path: "src/appilot/boot.ts", language: "typescript", contents: bootFile(options) });
+    files.push({
+      path: "src/appilot/actions.ts",
+      language: "typescript",
+      contents: CLIENT_ACTION_EXAMPLE
+    });
+  }
+  const serverEnv = [
+    `APPILOT_API_URL=${apiUrl}`,
+    `APPILOT_WIDGET_KEY=${options.widgetKey ?? "wk_test_..."}`,
+    "APPILOT_WIDGET_SECRET=wsk_secret_...   # server-side only, never in a client bundle"
+  ];
+  if (options.framework !== "other") {
+    serverEnv.push(
+      `${idiom.envName}=${options.widgetKey ?? "wk_test_..."}   # the same publishable key, this time for the page`
+    );
+  }
+  const notes = [
+    "The widget secret must never appear in a client bundle or a public env var. In Next.js that means no NEXT_PUBLIC_ prefix; in Vite, keep it out of VITE_.",
+    "resolveUser is the security boundary: derive the user from a credential you trust, never from the request body.",
+    ...localDevelopmentNotes(idiom),
+    "Call verify_integration once this is wired to confirm the relay answers and the widget actually boots."
+  ];
+  if (options.framework === "other") {
+    notes.unshift(
+      "appilot-server is a Node package, so this host implements the exchange itself. It is one authenticated POST to {apiUrl}/widget/token carrying X-Widget-Key and X-Widget-Secret, and the response body goes back to the page unchanged."
+    );
   }
-  files.push({ path: "src/appilot/boot.ts", language: "typescript", contents: bootFile(options) });
-  files.push({
-    path: "src/appilot/actions.ts",
-    language: "typescript",
-    contents: CLIENT_ACTION_EXAMPLE
-  });
   return {
     framework: options.framework,
     files,
-    install: "npm install appilot appilot-server",
-    env: [
-      `APPILOT_API_URL=${options.apiUrl ?? "https://api.appilot.space"}`,
-      `APPILOT_WIDGET_KEY=${options.widgetKey ?? "wk_live_..."}`,
-      "APPILOT_WIDGET_SECRET=wsk_secret_...   # server-side only, never in a client bundle"
-    ].join("\n"),
-    notes: [
-      "The widget secret must never appear in a client bundle or a public env var. In Next.js that means no NEXT_PUBLIC_ prefix; in Vite, keep it out of VITE_.",
-      "resolveUser is the security boundary: derive the user from a credential you trust, never from the request body.",
-      "Call verify_integration once this is wired to confirm the relay answers and the widget actually boots."
-    ]
+    install: options.framework === "other" ? "No package to install. The relay is one HTTPS call and the widget loads from the script tag above." : "npm install appilot appilot-server",
+    env: serverEnv.join("\n"),
+    notes
   };
 }
+function toolNameFrom(slug) {
+  return IDENTIFIER_KINDS.tool_name.normalize(slug) || "do_the_thing";
+}
+function semanticSlugFrom(slug) {
+  return IDENTIFIER_KINDS.semantic_id.normalize(slug) || "the-thing";
+}
+function planSections(shape, capability, ids, viewPath) {
+  if (shape === "read") return null;
+  if (shape === "navigate") {
+    return [
+      {
+        view_path: viewPath,
+        steps: [`Open [${capability}]({{click:${ids.open}}}).`]
+      }
+    ];
+  }
+  return [
+    {
+      view_path: viewPath,
+      steps: [
+        `Open the form with [${capability}]({{click:${ids.open}}}).`,
+        `Fill in [the ${capability.toLowerCase()} form]({{form:${ids.form}}}).`,
+        `Submit it with [Save]({{click:${ids.submit}}}).`
+      ]
+    }
+  ];
+}
 function scaffoldAgentFirst(options) {
-  const { capability, slug, appId } = options;
-  const method = options.endpoint?.method?.toUpperCase() ?? "POST";
+  const { capability, appId } = options;
+  const shape = options.shape ?? "create";
+  const viewPath = options.viewPath ?? "/";
+  const toolName = toolNameFrom(options.slug);
+  const slug = semanticSlugFrom(options.slug);
+  const ids = {
+    open: `btn-${slug}`,
+    form: `form-${slug}`,
+    submit: `submit-${slug}`
+  };
+  const method = options.endpoint?.method?.toUpperCase() ?? (shape === "read" ? "GET" : "POST");
   const pathTemplate = options.endpoint?.path ?? `/api/${slug}`;
-  const tool = {
+  const trigger = `Use when the user wants to ${capability.toLowerCase()}.`;
+  const tool = options.clientSide ? null : {
     app_id: appId,
-    tool_name: slug,
+    tool_name: toolName,
     title: capability,
-    description: `Use when the user wants to ${capability.toLowerCase()}.`,
+    description: trigger,
     parameters: {
       type: "object",
       properties: {},
@@ -23674,22 +24025,17 @@ function scaffoldAgentFirst(options) {
     title_i18n: {},
     description_i18n: {}
   };
-  const actionPlan = {
+  const sections = planSections(shape, capability, ids, viewPath);
+  const actionPlan = sections && {
     app_id: appId,
-    semantic_id: `plan-${slug}`,
+    semantic_id: IDENTIFIER_KINDS.plan_id.normalize(`plan-${slug}`),
     name: capability,
-    description: `Use when the user wants to ${capability.toLowerCase()}.`,
-    sections: [
-      {
-        title: capability,
-        steps: [
-          { text: `Open the form: [${capability}]({{click:btn-${slug}}})` },
-          { text: `Fill it in: [the ${slug} form]({{form:form-${slug}}})` },
-          { text: `Submit: [Save]({{click:btn-${slug}-submit}})` }
-        ]
-      }
-    ],
-    form_values: { [`form-${slug}`]: {} },
+    description: trigger,
+    sections,
+    // Keyed by form id, and each entry carries a `fields` array of
+    // { control_id, value }. The empty array is the authored default: the
+    // user supplies the values at runtime.
+    form_values: shape === "create" ? { [ids.form]: { fields: [] } } : {},
     step_narratives_i18n: {},
     is_active: false
   };
@@ -23711,6 +24057,7 @@ function scaffoldAgentFirst(options) {
   };
   const files = [];
   if (options.clientSide) {
+    const registerName = toolName.replace(/(^|_)([a-z])/g, (_m, _s, c) => c.toUpperCase());
     files.push({
       path: `src/appilot/${slug}.ts`,
       language: "typescript",
@@ -23720,11 +24067,11 @@ function scaffoldAgentFirst(options) {
 //
 // This runs in the page, in the user's own session, so it inherits their
 // permissions and needs no credential of its own. Anything the backend must
-// authorize belongs in the HTTP-proxy tool instead.
-export function register${slug.replace(/(^|[-_])([a-z])/g, (_m, _s, c) => c.toUpperCase())}() {
+// authorize belongs in an HTTP-proxy tool instead.
+export function register${registerName}() {
   const handle = registerTool({
-    name: '${slug}',
-    description: 'Use when the user wants to ${capability.toLowerCase()}.',
+    name: '${toolName}',
+    description: '${trigger}',
     inputSchema: { type: 'object', properties: {}, required: [] },
     // Omit readOnlyHint, or set it false, when this changes something: the
     // agent confirms with the user before calling a mutating action.
@@ -23738,31 +24085,83 @@ export function register${slug.replace(/(^|[-_])([a-z])/g, (_m, _s, c) => c.toUp
 `
     });
   }
+  const order = [];
+  if (sections) {
+    order.push(
+      `1. Create the controls the plan names (${Object.values(ids).slice(0, shape === "create" ? 3 : 1).join(", ")}), with stable locators. inspect_page gives you candidates.`
+    );
+    if (shape === "create") {
+      order.push(`2. Create the form ${ids.form}, naming those controls as entry, submit and required fields.`);
+    }
+  }
+  order.push(
+    options.clientSide ? "Register the client action in the page. It runs in the user's session, so it needs no credential." : "Create the tool. path_template is a path on the host origin, not an absolute URL, and the executor rejects an absolute one. If it calls an authenticated backend, set auth_secret in the same call, because a tool with no stored credential runs in the page and cannot be used as session preflight."
+  );
+  if (sections) {
+    order.push("Create the action plan. Run validate_action_plan on the sections first.");
+  }
+  order.push("Create the knowledge article, and keep the procedure out of it.");
+  order.push("Activate the plan and the article once validate_config is clean.");
+  const notes = [
+    "The test for agent-first is whether a user could complete this capability end to end through the assistant alone. If not, it has a screen and nothing else.",
+    "Both the plan description and the tool description are how the agent finds them. Write the trigger, in the user's words, and localize it.",
+    "is_active is false on the plan and the article on purpose. Turn them on after validate_config passes, not before."
+  ];
+  if (shape === "read") {
+    notes.push(
+      "No action plan is emitted for a read capability. A plan whose only step opens a screen does nothing, and the health contract reports it. The tool answers the question and the knowledge article explains what the answer means."
+    );
+  }
+  if (options.clientSide) {
+    notes.push(
+      "No HTTP-proxy tool is emitted, because the operation runs in the page. Add one only if a second, server-authorized path to the same capability is genuinely needed."
+    );
+  }
+  notes.push(
+    `The plan's steps run on view_path "${viewPath}". Pass viewPath when the screen is somewhere else; the value must match a registered View.`
+  );
+  return { capability, shape, tool, actionPlan, knowledge, files, order, notes };
+}
+function integrationSnippet(options) {
+  const idiom = publicKeyIdiom(options.framework ?? "other");
+  const keyAttr = options.widgetKey ? `
+  data-api-key="${options.widgetKey}"` : "";
+  const apiAttr = options.apiUrl ? `
+  data-api-url="${options.apiUrl}"` : "";
+  const bootLines = ["import { bootAppilotWidget } from 'appilot';", "", "bootAppilotWidget({"];
+  bootLines.push(`  widgetScriptUrl: '${options.widgetScriptUrl}',`);
+  bootLines.push(`  widgetKey: ${idiom.expr},`);
+  if (options.apiUrl) bootLines.push(`  appilotApiUrl: '${options.apiUrl}',`);
+  bootLines.push("  tokenEndpoint: '/api/widget/token',", "});");
   return {
-    capability,
-    tool,
-    actionPlan,
-    knowledge,
-    files,
-    order: [
-      "1. Create the controls the plan names, with stable locators. inspect_page gives you candidates.",
-      "2. Create the form, naming those controls as entry, submit and required fields.",
-      "3. Create the tool. path_template is a path on the host origin, not an absolute URL, and the executor rejects an absolute one. If it calls an authenticated backend, set auth_secret in the same call, because a tool with no stored credential runs in the page and cannot be used as session preflight.",
-      "4. Create the action plan. Run validate_action_plan first; a plan that only opens an element does nothing.",
-      "5. Create the knowledge article, and keep the procedure out of it.",
-      "6. Activate the plan and the article once validate_config is clean."
-    ],
+    apiUrl: options.apiUrl ?? null,
+    scriptTag: `<script
+  src="${options.widgetScriptUrl}"${keyAttr}${apiAttr}
+  async
+></script>`,
+    bootSnippet: bootLines.join("\n"),
+    tokenEndpointHint: "Serve /api/widget/token from your backend with createWidgetTokenHandler from appilot-server. The widget requires an identified user, and the widget secret must never reach a browser.",
+    publicEnvName: idiom.envName,
     notes: [
-      "The test for agent-first is whether a user could complete this capability end to end through the assistant alone. If not, it has a screen and nothing else.",
-      "Both the plan description and the tool description are how the agent finds them. Write the trigger, in the user's words, and localize it.",
-      "is_active is false on the plan and the article on purpose. Turn them on after validate_config passes, not before."
+      "The script tag is the no-build form and carries the key as an attribute. The boot call is the bundled form and reads it from the public variable, which is what survives a key rotation.",
+      ...localDevelopmentNotes(idiom)
     ]
   };
 }
-var CLIENT_ACTION_EXAMPLE;
+var SCAFFOLD_FRAMEWORKS, CLIENT_ACTION_EXAMPLE;
 var init_scaffold = __esm({
   "src/scaffold.ts"() {
     "use strict";
+    init_validation();
+    SCAFFOLD_FRAMEWORKS = [
+      "next",
+      "express",
+      "fastify",
+      "hono",
+      "remix",
+      "sveltekit",
+      "other"
+    ];
     CLIENT_ACTION_EXAMPLE = `import { registerTool } from 'appilot';
 
 // A client action is an operation your PAGE performs, in the user's own
@@ -24045,7 +24444,7 @@ function createAppilotServer(conn) {
     if (!granted || granted.includes(scope)) return null;
     return errorText(
       new Error(
-        `This connection was granted ${granted.length ? granted.join(", ") : "no scopes"}, which does not include ${scope}. Reconnect and approve that scope, using a service token that carries it.`
+        `This connection was granted ${granted.length ? granted.join(", ") : "no scopes"}, which does not include ${scope}. Reconnect and approve that scope, using a service token that carries it. ` + HOW_TO_GRANT[scope]
       )
     );
   }
@@ -24327,24 +24726,25 @@ ${JSON.stringify(bundle, null, 2)}`);
     "create_app",
     {
       title: "Create an app, its domains, and a widget key",
-      description: "Provision an Appilot app in one call: the app, the domains it runs on, and optionally a widget key, plus the exact script tag and boot snippet to paste into the host application. Idempotent: re-running converges on the existing app rather than creating a second one. Pass dryRun to preview. The widget key and its secret are returned EXACTLY ONCE, at creation; store the secret in the host backend only. Requires a provision:write service token.",
+      description: "Provision an Appilot app in one call: the app, the domains it runs on, and optionally a widget key, plus the exact script tag and boot snippet to paste into the host application. Idempotent: re-running converges on the existing app rather than creating a second one. Pass dryRun to preview. The widget key and its secret are returned EXACTLY ONCE, at creation; store the secret in the host backend only. Working on your own machine: do NOT pass localhost or 127.0.0.1 as a domain, because they name every developer's machine and are refused. Either run the app on a hostname that resolves to 127.0.0.1 (myapp.lvh.me) and register THAT, which gives the turn full app context and needs no key, or pass isTest true with no domains for a loopback-bound wk_test_ key, which gives the tenant and the user and no app context. Requires a provision:write service token.",
       inputSchema: {
         name: external_exports.string().min(1),
         description: external_exports.string().optional(),
         domains: external_exports.array(external_exports.string()).optional(),
         widgetKeyName: external_exports.string().optional(),
-        isTestKey: external_exports.boolean().optional(),
+        isTest: external_exports.boolean().optional(),
+        allowedDomains: external_exports.array(external_exports.string()).optional(),
         dryRun: external_exports.boolean().optional()
       }
     },
-    async ({ name, description, domains, widgetKeyName, isTestKey, dryRun }) => {
+    async ({ name, description, domains, widgetKeyName, isTest, allowedDomains, dryRun }) => {
       const refusal = scopeRefusal("provision:write");
       if (refusal) return refusal;
       try {
         const result = await client.provisionApp({
           app: { name, description },
           domains: (domains ?? []).map((domain) => ({ domain })),
-          widgetKey: widgetKeyName || isTestKey !== void 0 ? { name: widgetKeyName, isTest: isTestKey } : void 0,
+          widgetKey: widgetKeyName || isTest !== void 0 || allowedDomains ? { name: widgetKeyName, isTest, allowedDomains } : void 0,
           dryRun: dryRun === true
         });
         return text(redactForTransport(result, conn.transport));
@@ -24353,11 +24753,138 @@ ${JSON.stringify(bundle, null, 2)}`);
       }
     }
   );
+  server.registerTool(
+    "list_apps",
+    {
+      title: "List the apps this organization has provisioned",
+      description: `The apps this credential reaches, with each app's registered domains and their verification status. Call it before create_app so "which apps do I have" has an answer, and to find the app id and the domain id every other provisioning tool takes. Carries no secret. Reads the provisioning surface, so it needs a provision:write service token even though it writes nothing.`,
+      inputSchema: {}
+    },
+    async () => {
+      const refusal = scopeRefusal("provision:write");
+      if (refusal) return refusal;
+      try {
+        return text(await client.listProvisioned());
+      } catch (err) {
+        return errorText(err);
+      }
+    }
+  );
+  server.registerTool(
+    "list_widget_keys",
+    {
+      title: "List the widget keys this organization holds",
+      description: "The organization's widget keys by label, prefix, allowed domains and active state. No raw key and no secret: both are shown exactly once, at creation. Call it before create_app so a re-run recognises the key it already minted instead of asking for another, because every extra key is another live credential. Requires a provision:write service token.",
+      inputSchema: {}
+    },
+    async () => {
+      const refusal = scopeRefusal("provision:write");
+      if (refusal) return refusal;
+      try {
+        return text(await client.listWidgetKeys());
+      } catch (err) {
+        return errorText(err);
+      }
+    }
+  );
+  server.registerTool(
+    "verify_domain",
+    {
+      title: "Check or trigger a domain's DNS verification",
+      description: "Where a domain's verification stands, and the exact TXT record it needs. Pass trigger to ask Appilot to look for the record now. A live widget key needs a verified domain, and this is what closes that loop: create_app reports the key as blocked and names the record, and this reports whether the record is visible yet. Requires a provision:write service token.",
+      inputSchema: {
+        domain: external_exports.string().min(1),
+        appId: external_exports.number().int().optional(),
+        trigger: external_exports.boolean().optional()
+      }
+    },
+    async ({ domain, appId, trigger }) => {
+      const refusal = scopeRefusal("provision:write");
+      if (refusal) return refusal;
+      try {
+        const wanted = domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/[/:].*$/, "");
+        const provisioned = await client.listProvisioned();
+        const scoped = appId != null ? provisioned.filter((a) => Number(a.id) === appId) : provisioned;
+        const owner = scoped.find((a) => a.domains.some((d) => String(d.domain).toLowerCase() === wanted));
+        const row = owner?.domains.find((d) => String(d.domain).toLowerCase() === wanted);
+        if (!owner || !row) {
+          return errorText(new Error(
+            `${wanted} is not a registered domain of ${appId != null ? `app ${appId}` : "any app in this organization"}. list_apps shows what is registered, and create_app adds a domain. A loopback name (localhost, 127.0.0.1) is never registrable: run the app on a hostname that resolves to 127.0.0.1 instead.`
+          ));
+        }
+        const result = {
+          app: { id: owner.id, name: owner.name },
+          domain: row.domain,
+          domainId: row.id,
+          verificationStatus: row.verification_status
+        };
+        try {
+          result.record = await client.domainVerification(Number(row.id));
+        } catch {
+          try {
+            const preview = await client.provisionApp({
+              app: { name: owner.name },
+              domains: [{ domain: row.domain }],
+              dryRun: true
+            });
+            const previewed = preview.domains.find((d) => d.domain.toLowerCase() === wanted);
+            if (previewed?.dns_record_name) {
+              result.record = {
+                dns_record_name: previewed.dns_record_name,
+                dns_record_value: previewed.dns_record_value,
+                verification_status: previewed.verification_status
+              };
+            }
+          } catch (err) {
+            result.recordUnavailable = err instanceof Error ? err.message : String(err);
+          }
+        }
+        if (trigger && row.verification_status !== "verified") {
+          try {
+            result.checked = await client.triggerDomainVerification(Number(row.id));
+          } catch (err) {
+            result.triggerRefused = `${err instanceof Error ? err.message : String(err)} Triggering the check authenticates an organization session rather than a service token today, so run it from the Backoffice under Domains once the TXT record is published.`;
+          }
+        }
+        return text(result);
+      } catch (err) {
+        return errorText(err);
+      }
+    }
+  );
+  server.registerTool(
+    "integration_snippet",
+    {
+      title: "Get the script tag and boot call for an app that already exists",
+      description: "The two forms of the widget boot for an app you already provisioned: the no-build script tag, and the bundled bootAppilotWidget call reading the key from the framework's public variable. Use it instead of re-running create_app, which is a provisioning write, when all you lost was the snippet. It composes the answer locally, writes nothing, and needs no scope. Pass the publishable widget key to have it appear in the script tag; the widget SECRET never belongs here.",
+      inputSchema: {
+        appId: external_exports.number().int().optional(),
+        widgetKey: external_exports.string().optional(),
+        widgetScriptUrl: external_exports.string().optional(),
+        framework: external_exports.enum(SCAFFOLD_FRAMEWORKS).optional()
+      }
+    },
+    async ({ appId, widgetKey, widgetScriptUrl, framework }) => {
+      try {
+        return text({
+          appId: appId ?? conn.defaultAppId ?? null,
+          ...integrationSnippet({
+            widgetScriptUrl: widgetScriptUrl ?? DEFAULT_WIDGET_SCRIPT_URL,
+            apiUrl: conn.baseUrl || null,
+            widgetKey: widgetKey ?? null,
+            framework
+          })
+        });
+      } catch (err) {
+        return errorText(err);
+      }
+    }
+  );
   server.registerTool(
     "plan_manifest",
     {
       title: "Preview an app manifest (writes nothing)",
-      description: "Diff an appilot.app-manifest against the live instance and return what would change: provisioning actions per app/domain/key, the config-bundle import diff, and the health findings over the resulting state. Writes nothing. Returns a planToken that apply_manifest requires, so an apply always follows a preview of the exact same manifest. Keep the manifest in the repository under version control.",
+      description: "Diff an appilot.app-manifest against the live instance and return what would change: provisioning actions per app/domain/key, the config-bundle import diff, and the health findings over the resulting state. Writes nothing. Returns a planToken that apply_manifest requires, so an apply always follows a preview of the exact same manifest. Keep the manifest in the repository under version control. A complete example ships with this package at examples/app.appilot.json and is also in the docs. Which half is revisioned: the CONFIG half gets a pre_restore revision on every commit, so a wrong import is undone by restoring it; the PROVISIONING half is not revisioned, so a domain or a key it creates is undone by hand.",
       inputSchema: { manifest: external_exports.union([external_exports.record(external_exports.any()), external_exports.string()]) }
     },
     async ({ manifest }) => {
@@ -24379,7 +24906,7 @@ ${JSON.stringify(bundle, null, 2)}`);
     "apply_manifest",
     {
       title: "Apply a previously planned app manifest",
-      description: "Provision and configure an app from an appilot.app-manifest. Requires the planToken returned by plan_manifest for the SAME manifest: a mismatch means the manifest changed after it was previewed, and the apply is refused. Pass expectedCurrentHash from the plan so a concurrent config edit is a 409 rather than a silent overwrite. mode=replace makes the config match the bundle exactly, including deletions. Requires provision:write, and config:write when the manifest carries a config bundle.",
+      description: "Provision and configure an app from an appilot.app-manifest. Requires the planToken returned by plan_manifest for the SAME manifest: a mismatch means the manifest changed after it was previewed, and the apply is refused. Pass expectedCurrentHash from the plan so a concurrent config edit is a 409 rather than a silent overwrite. mode=replace makes the config match the bundle exactly, including deletions. Needs config:write when the manifest carries a config bundle, and provision:write only when the provisioning half would actually change something: a manifest whose app, domains and keys already exist applies with config:write alone.",
       inputSchema: {
         manifest: external_exports.union([external_exports.record(external_exports.any()), external_exports.string()]),
         planToken: external_exports.string(),
@@ -24389,15 +24916,19 @@ ${JSON.stringify(bundle, null, 2)}`);
       }
     },
     async ({ manifest, planToken, mode, expectedCurrentHash, allowUnhealthy }) => {
-      const refusal = scopeRefusal("provision:write") ?? scopeRefusal("config:write");
-      if (refusal) return refusal;
       try {
         const parsed = parseManifest(manifest);
+        if (parsed.config) {
+          const configRefusal = scopeRefusal("config:write");
+          if (configRefusal) return configRefusal;
+        }
+        const provisionRefusal = scopeRefusal("provision:write");
         const result = await applyManifest(client, parsed, {
           planToken,
           mode,
           expectedCurrentHash,
-          allowUnhealthy
+          allowUnhealthy,
+          provisionRefusal: provisionRefusal ? provisionRefusal.content[0].text : null
         });
         return text({ ...result, provisioning: redactForTransport(result.provisioning, conn.transport) });
       } catch (err) {
@@ -24409,9 +24940,9 @@ ${JSON.stringify(bundle, null, 2)}`);
     "scaffold_integration",
     {
       title: "Generate the host application integration code",
-      description: "Return the source a host application needs: the identity relay for its backend (the one security-critical piece, built on appilot-server), the widget boot call, and a client-action example. Returns file CONTENTS for you to write into the repository; this server never touches the filesystem. Pick the framework that matches the host.",
+      description: "Return the source a host application needs: the identity relay for its backend (the one security-critical piece, built on appilot-server), the widget boot call, and a client-action example. Returns file CONTENTS for you to write into the repository; this server never touches the filesystem. Pick the framework that matches the host, or `other` when the backend is not Node (Django, Rails, PHP), which returns the raw exchange as curl plus a Python and a Ruby handler. The notes carry what local development needs, and the answer differs between a hostname you registered and bare localhost.",
       inputSchema: {
-        framework: external_exports.enum(["next", "express", "fastify", "hono", "remix", "sveltekit"]),
+        framework: external_exports.enum(SCAFFOLD_FRAMEWORKS),
         widgetKey: external_exports.string().optional(),
         widgetScriptUrl: external_exports.string().optional(),
         idNamespace: external_exports.string().optional()
@@ -24499,16 +25030,18 @@ ${JSON.stringify(bundle, null, 2)}`);
     "scaffold_agent_first",
     {
       title: "Scaffold one capability so the agent can operate it",
-      description: "Return the four artifacts a capability needs to be agent-operable, agreeing with each other: the HTTP-proxy tool, the client action when the operation belongs in the page, the Action Plan that is the procedure, and the knowledge article that carries the meaning and not the steps. Also returns the order to create them in, which matters because a form cannot name controls that do not exist yet. `endpoint.path` is a path on the host origin, not an absolute URL. Use it when building a new agent-first app or making an existing feature reachable through the assistant.",
+      description: "Return the four artifacts a capability needs to be agent-operable, agreeing with each other: the HTTP-proxy tool, the client action when the operation belongs in the page, the Action Plan that is the procedure, and the knowledge article that carries the meaning and not the steps. Also returns the order to create them in, which matters because a form cannot name controls that do not exist yet. `endpoint.path` is a path on the host origin, not an absolute URL. Pass `shape`: `create` is the open, fill and submit plan, `navigate` is one step to a screen, and `read` gets NO plan at all, because a plan whose only step opens a screen does nothing. Pass `clientSide` when the operation belongs in the page, and no HTTP-proxy tool is emitted. Use it when building a new agent-first app or making an existing feature reachable through the assistant.",
       inputSchema: {
         capability: external_exports.string().min(1),
         slug: external_exports.string().min(1),
         appId: external_exports.number().int().optional(),
         endpoint: external_exports.object({ method: external_exports.string(), path: external_exports.string() }).optional(),
-        clientSide: external_exports.boolean().optional()
+        clientSide: external_exports.boolean().optional(),
+        shape: external_exports.enum(["create", "navigate", "read"]).optional(),
+        viewPath: external_exports.string().optional()
       }
     },
-    async ({ capability, slug, appId, endpoint, clientSide }) => {
+    async ({ capability, slug, appId, endpoint, clientSide, shape, viewPath }) => {
       try {
         return text(
           scaffoldAgentFirst({
@@ -24516,7 +25049,9 @@ ${JSON.stringify(bundle, null, 2)}`);
             slug,
             appId: appId ?? conn.defaultAppId ?? null,
             endpoint: endpoint ?? null,
-            clientSide
+            clientSide,
+            shape,
+            viewPath
           })
         );
       } catch (err) {
@@ -24588,7 +25123,7 @@ ${JSON.stringify(bundle, null, 2)}`);
   );
   return server;
 }
-var DEFAULT_WIDGET_SCRIPT_URL, SERVER_INSTRUCTIONS;
+var DEFAULT_WIDGET_SCRIPT_URL, SERVER_INSTRUCTIONS, HOW_TO_GRANT;
 var init_server3 = __esm({
   "src/server.ts"() {
     "use strict";
@@ -24607,7 +25142,9 @@ var init_server3 = __esm({
     DEFAULT_WIDGET_SCRIPT_URL = "https://cdn.appilot.space/widget/v1/appilot.esm.js";
     SERVER_INSTRUCTIONS = `Audit, extend and fix an Appilot app's content-model configuration, and build a new capability so the agent can operate it.
 
-Work in this order: capabilities (what this instance supports, and the closed vocabularies its entities accept; on-premise trails cloud), read_config, validate_config, then report the findings to the user in plain language, ranked critical to low, each with its concrete fix. Do not paste raw tool output at them.
+For a new app, work in this order: whoami, then create_app (on bare localhost pass isTest, which mints a wk_test_ key), then scaffold_integration for the host's framework, then verify_integration against the running page, then configure the content model.
+
+To audit an existing one, work in this order: capabilities (what this instance supports, and the closed vocabularies its entities accept; on-premise trails cloud), read_config, validate_config, then report the findings to the user in plain language, ranked critical to low, each with its concrete fix. Do not paste raw tool output at them.
 
 If read_config returns a gaps array, an entity could not be read. Say so and stop treating that entity as empty: every lint over it silently passed.
 
@@ -24622,6 +25159,12 @@ Three things to get right. A widget secret belongs in the server environment and
 If something is missing or broken in Appilot itself, report_feedback records it. Say plainly what it does: the report is read, and a reply is part of a support plan rather than something promised here. Never put configuration contents, knowledge bodies or secrets in a report, and show the user the exact text first.
 
 Writing needs a config:write service token, reading needs config:read, provisioning needs provision:write, reporting needs feedback:write. A scope refusal means the user should reconnect with a token carrying that scope, not that you should find another route.`;
+    HOW_TO_GRANT = {
+      "config:read": 'config:read is on every Service tokens preset in the Backoffice, "Inspect only" included.',
+      "config:write": 'config:write comes from the Backoffice Service tokens preset "Edit configuration".',
+      "provision:write": 'provision:write is granted by an organization administrator in the Backoffice, under Service tokens with the "Set up integrations" preset, or through the account approval screen. A configurator who is not an administrator cannot mint it and has to ask one.',
+      "feedback:write": "feedback:write is a Backoffice Service tokens option, and it is the only scope that sends anything out of the organization."
+    };
   }
 });
 
@@ -43475,7 +44018,7 @@ var require_view = __commonJS({
     var dirname = path.dirname;
     var basename = path.basename;
     var extname = path.extname;
-    var join = path.join;
+    var join2 = path.join;
     var resolve = path.resolve;
     module.exports = View;
     function View(name, options) {
@@ -43537,12 +44080,12 @@ var require_view = __commonJS({
     };
     View.prototype.resolve = function resolve2(dir, file) {
       var ext = this.ext;
-      var path2 = join(dir, file);
+      var path2 = join2(dir, file);
       var stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
       }
-      path2 = join(dir, basename(file, ext), "index" + ext);
+      path2 = join2(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
@@ -47350,7 +47893,7 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util2 = __require("util");
     var extname = path.extname;
-    var join = path.join;
+    var join2 = path.join;
     var normalize = path.normalize;
     var resolve = path.resolve;
     var sep = path.sep;
@@ -47522,7 +48065,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path2.split(sep);
-        path2 = normalize(join(root, path2));
+        path2 = normalize(join2(root, path2));
       } else {
         if (UP_PATH_REGEXP.test(path2)) {
           debug('malicious path "%s"', path2);
@@ -47655,7 +48198,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join(path2, self._index[i]);
+        var p = join2(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat) {
           if (err2) return next(err2);
@@ -53493,10 +54036,6 @@ function message(key, locale = "en", values = {}) {
   const template = ({ en, es, de }[locale] ?? en)[key];
   return template.replace(/\{(\w+)\}/g, (_, name) => values[name] ?? `{${name}}`);
 }
-function translateError(text, locale) {
-  const entry = Object.entries(en).find(([, value]) => value === text);
-  return entry ? message(entry[0], locale) : message("unavailableDetail", locale);
-}
 var en, es, de;
 var init_consentMessages = __esm({
   "src/remote/consentMessages.ts"() {
@@ -53556,7 +54095,12 @@ var init_consentMessages = __esm({
       failed: "Connection could not be completed",
       failedHelp: "The approval expired, was already used, or belongs to another browser. Start again from your assistant.",
       unavailableTitle: "Connection unavailable",
-      unavailableDetail: "Appilot could not complete the connection. Please try again."
+      unavailableDetail: "Appilot could not complete the connection. Please try again.",
+      // What a client is called when it did not register a name. One constant, so
+      // the same connection is not "your assistant" on one screen and "an MCP
+      // client" on the next.
+      clientFallback: "your assistant",
+      appNumber: "App #{id}"
     };
     es = {
       sessionUnavailable: "La aprobaci\xF3n desde tu cuenta no est\xE1 disponible temporalmente. Intenta conectar otra vez o usa un token de servicio abajo.",
@@ -53613,7 +54157,9 @@ var init_consentMessages = __esm({
       failed: "No se pudo completar la conexi\xF3n",
       failedHelp: "La aprobaci\xF3n venci\xF3, ya se utiliz\xF3 o pertenece a otro navegador. Vuelve a empezar desde tu asistente.",
       unavailableTitle: "Conexi\xF3n no disponible",
-      unavailableDetail: "Appilot no pudo completar la conexi\xF3n. Int\xE9ntalo de nuevo."
+      unavailableDetail: "Appilot no pudo completar la conexi\xF3n. Int\xE9ntalo de nuevo.",
+      clientFallback: "tu asistente",
+      appNumber: "Aplicaci\xF3n n.\xBA {id}"
     };
     de = {
       sessionUnavailable: "Die Freigabe \xFCber Ihr Konto ist vor\xFCbergehend nicht verf\xFCgbar. Starten Sie erneut oder verwenden Sie unten ein Service-Token.",
@@ -53670,7 +54216,9 @@ var init_consentMessages = __esm({
       failed: "Verbindung konnte nicht abgeschlossen werden",
       failedHelp: "Die Freigabe ist abgelaufen, wurde bereits verwendet oder geh\xF6rt zu einem anderen Browser. Starten Sie erneut in Ihrem Assistenten.",
       unavailableTitle: "Verbindung nicht verf\xFCgbar",
-      unavailableDetail: "Appilot konnte die Verbindung nicht abschlie\xDFen. Versuchen Sie es erneut."
+      unavailableDetail: "Appilot konnte die Verbindung nicht abschlie\xDFen. Versuchen Sie es erneut.",
+      clientFallback: "Ihr Assistent",
+      appNumber: "App Nr. {id}"
     };
   }
 });
@@ -53721,10 +54269,10 @@ function renderConfirmPage(opts) {
   const locale = opts.locale ?? "en";
   const m = (key, values) => escapeHtml(message(key, locale, values));
   const organization = opts.organizationName || (opts.organizationId != null ? `${message("organization", locale)} #${opts.organizationId}` : message("unknown", locale));
-  const app = opts.appName || (opts.appId != null ? `App #${opts.appId}` : message("allApps", locale));
+  const app = opts.appName || (opts.appId != null ? message("appNumber", locale, { id: String(opts.appId) }) : message("allApps", locale));
   return page(
     message("review", locale),
-    `${steps(2, locale)}<h1>${m("reviewFor", { client: opts.clientName || "AI assistant" })}</h1><p>${m("accepted")}</p>
+    `${steps(2, locale)}<h1>${m("reviewFor", { client: opts.clientName || message("clientFallback", locale) })}</h1><p>${m("accepted")}</p>
  <div class="panel"><dl><div><dt>${m("organization")}</dt><dd>${escapeHtml(organization)}</dd></div><div><dt>${m(opts.appScoped ? "limited" : "appAccess")}</dt><dd>${escapeHtml(app)}</dd></div></dl>${opts.appId != null && !opts.appScoped ? `<small>${m("defaultNote")}</small>` : ""}</div>
  <h2>${m("can")}</h2>${scopeItems(opts.scopes, locale)}
  ${opts.unavailableScopes?.length ? `<div class="panel help"><h2>${m("unavailable")}</h2><p class="small">${m("unavailableHelp", { scopes: opts.unavailableScopes.map((scope) => scopeTitle(scope, locale)).join(", ") })}</p></div>` : ""}
@@ -53735,11 +54283,11 @@ function renderConfirmPage(opts) {
     locale
   );
 }
-function renderErrorPage(title, detail, locale = "en") {
-  const translatedTitle = locale === "en" ? title : translateError(title, locale);
+function renderErrorPage(titleKey, detailKey, locale = "en") {
+  const title = message(titleKey, locale);
   return page(
-    translatedTitle,
-    `<h1>${escapeHtml(translatedTitle)}</h1><div class="error" role="alert">${escapeHtml(locale === "en" ? detail : translateError(detail, locale))}</div><p>${escapeHtml(message("restart", locale))}</p>`,
+    title,
+    `<h1>${escapeHtml(title)}</h1><div class="error" role="alert">${escapeHtml(message(detailKey, locale))}</div><p>${escapeHtml(message("restart", locale))}</p>`,
     void 0,
     locale
   );
@@ -56384,7 +56932,7 @@ var init_oauth = __esm({
         const sealedRequest = await this.sealAuthRequest({
           language,
           client_id: client.client_id,
-          client_name: client.client_name || "your assistant",
+          client_name: client.client_name || message("clientFallback", language),
           redirect_uri: params.redirectUri,
           code_challenge: params.codeChallenge,
           state: params.state,
@@ -56402,7 +56950,7 @@ var init_oauth = __esm({
               },
               sealedRequest,
               client.client_id,
-              client.client_name || "AI assistant",
+              client.client_name || message("clientFallback", language),
               requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
               language,
               res
@@ -56414,7 +56962,7 @@ var init_oauth = __esm({
                 locale: language,
                 request: sealedRequest,
                 action: this.consentPath,
-                clientName: client.client_name || "AI assistant",
+                clientName: client.client_name || message("clientFallback", language),
                 baseUrl: this.options.baseUrl,
                 backofficeUrl: this.options.backofficeUrl,
                 scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
@@ -56429,7 +56977,7 @@ var init_oauth = __esm({
             locale: language,
             request: sealedRequest,
             action: this.consentPath,
-            clientName: client.client_name || "an MCP client",
+            clientName: client.client_name || message("clientFallback", language),
             baseUrl: this.options.baseUrl,
             backofficeUrl: this.options.backofficeUrl,
             scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES]
@@ -56503,22 +57051,14 @@ var init_oauth = __esm({
         } catch {
           return {
             status: 400,
-            html: renderErrorPage(
-              "This sign-in link expired",
-              "Start the connection again from the client that sent you here. A consent link is valid for ten minutes.",
-              fallbackLocale
-            )
+            html: renderErrorPage("expired", "expiredHelp", fallbackLocale)
           };
         }
         const locale = request.language ?? fallbackLocale;
         if (request.stage !== "request" && request.stage !== "confirm") {
           return {
             status: 400,
-            html: renderErrorPage(
-              "Invalid request",
-              "That confirmation is incomplete. Start again.",
-              locale
-            )
+            html: renderErrorPage("invalid", "invalidHelp", locale)
           };
         }
         const redirect = new URL(request.redirect_uri);
@@ -56539,7 +57079,7 @@ var init_oauth = __esm({
                 locale,
                 request: await this.sealAuthRequest({ ...original, scopes }),
                 action: this.consentPath,
-                clientName: request.client_name || "your assistant",
+                clientName: request.client_name || message("clientFallback", locale),
                 baseUrl: this.options.baseUrl,
                 backofficeUrl: this.options.backofficeUrl,
                 scopes
@@ -56549,11 +57089,7 @@ var init_oauth = __esm({
           if (form.action !== "confirm" || !request.pat || !request.identity) {
             return {
               status: 400,
-              html: renderErrorPage(
-                "Invalid request",
-                "That confirmation is incomplete. Start again.",
-                locale
-              )
+              html: renderErrorPage("invalid", "invalidHelp", locale)
             };
           }
           return {
@@ -56572,7 +57108,7 @@ var init_oauth = __esm({
             locale,
             request: rawRequest,
             action: this.consentPath,
-            clientName: request.client_name || "your assistant",
+            clientName: request.client_name || message("clientFallback", locale),
             baseUrl: this.options.baseUrl,
             backofficeUrl: this.options.backofficeUrl,
             scopes: request.scopes,
@@ -56781,7 +57317,7 @@ function createRemoteApp(config2, options = {}) {
       const code = typeof req.query.code === "string" ? req.query.code : "";
       res.redirect(303, await provider.finishConnection(id, code, req.get("Cookie") ?? "", res));
     } catch {
-      res.status(400).type("html").send(renderErrorPage("Connection could not be completed", "The approval expired, was already used, or belongs to another browser. Start again from your assistant.", consentLocale(req.get("Accept-Language"))));
+      res.status(400).type("html").send(renderErrorPage("failed", "failedHelp", consentLocale(req.get("Accept-Language"))));
     }
   });
   app.post("/consent", import_express7.default.urlencoded({ extended: false, limit: "64kb" }), async (req, res) => {
@@ -56794,7 +57330,7 @@ function createRemoteApp(config2, options = {}) {
       res.status(outcome.status).set("Content-Type", "text/html; charset=utf-8").send(outcome.html);
     } catch {
       res.status(500).set("Content-Type", "text/html; charset=utf-8").send(
-        renderErrorPage("Connection unavailable", "Appilot could not complete the connection. Please try again.", consentLocale(req.get("Accept-Language")))
+        renderErrorPage("unavailableTitle", "unavailableDetail", consentLocale(req.get("Accept-Language")))
       );
     }
   });
@@ -57049,6 +57585,144 @@ function loadRemoteConfig(env = process.env) {
 
 // src/index.ts
 init_server3();
+
+// src/cli.ts
+init_version();
+import { cpSync, existsSync, readFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+init_client();
+init_manifest();
+var HELP = `appilot-mcp ${SERVER_VERSION}
+
+The Appilot MCP server: read, validate, fix and provision an Appilot app.
+
+USAGE
+  appilot-mcp                     Start the MCP server on stdio (what a client launches)
+  appilot-mcp --http              Start the remote HTTP service instead
+  appilot-mcp plan <file>         Preview an appilot.app-manifest. Writes nothing
+  appilot-mcp apply <file>        Plan, then apply the same manifest
+  appilot-mcp install-skill       Copy the app-configurator skill to an agent client
+  appilot-mcp --help | --version
+
+OPTIONS
+  apply           --mode merge|replace   How the config half is imported. Default merge
+                  --allow-unhealthy      Import a bundle the health gate would refuse
+  install-skill   --claude | --codex | --cursor | --gemini | --dir <path>
+
+ENVIRONMENT
+  APPILOT_BASE_URL   Your instance, e.g. https://api.appilot.space or http://localhost:6001
+  APPILOT_PAT        A scoped service token from the Backoffice, under Service tokens
+  APPILOT_APP_ID     Optional default app id
+
+Docs: https://docs.appilot.space/docs/developers/configure-with-ai/overview`;
+var SKILL_TARGETS = {
+  claude: join(".claude", "skills"),
+  codex: join(".codex", "skills"),
+  cursor: join(".cursor", "skills"),
+  gemini: join(".gemini", "config", "skills")
+};
+function bundledSkillDir(from = fileURLToPath(import.meta.url)) {
+  const candidates = [
+    join(from, "..", "..", "skills", "app-configurator"),
+    join(from, "..", "..", "..", "skills", "app-configurator")
+  ];
+  return candidates.find((candidate) => existsSync(join(candidate, "SKILL.md"))) ?? null;
+}
+function installSkill(args) {
+  const source = bundledSkillDir();
+  if (!source) {
+    process.stderr.write(
+      "[appilot-mcp] the bundled skill was not found next to this install. Reinstall the package (npm i -g appilot-mcp), or copy skills/app-configurator from the repository by hand.\n"
+    );
+    return 1;
+  }
+  const dirFlag = args.indexOf("--dir");
+  let destParent;
+  if (dirFlag !== -1) {
+    const explicit = args[dirFlag + 1];
+    if (!explicit) {
+      process.stderr.write("[appilot-mcp] --dir needs a path.\n");
+      return 2;
+    }
+    destParent = explicit;
+  } else {
+    const client = Object.keys(SKILL_TARGETS).find((name) => args.includes(`--${name}`));
+    if (!client) {
+      process.stderr.write(
+        `[appilot-mcp] name the client: ${Object.keys(SKILL_TARGETS).map((c) => `--${c}`).join(", ")}, or --dir <path>.
+`
+      );
+      return 2;
+    }
+    destParent = join(homedir(), SKILL_TARGETS[client]);
+  }
+  const dest = join(destParent, "app-configurator");
+  mkdirSync(destParent, { recursive: true });
+  cpSync(source, dest, { recursive: true });
+  process.stdout.write(`Installed the app-configurator skill to ${dest}
+Start a new session so the client loads it.
+`);
+  return 0;
+}
+function readManifestFile(path) {
+  if (!path) throw new Error("Name the manifest file: appilot-mcp plan app.appilot.json");
+  if (!existsSync(path)) throw new Error(`No such file: ${path}`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+async function runPlan(args) {
+  const conn = loadConnection();
+  const client = new AppilotClient(conn);
+  const manifest = parseManifest(readManifestFile(args[0]));
+  const plan = await planManifest(client, manifest, (id) => {
+    const resolved = id ?? conn.defaultAppId;
+    return resolved != null && Number.isFinite(resolved) ? resolved : null;
+  });
+  process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+  return 0;
+}
+async function runApply(args) {
+  const conn = loadConnection();
+  const client = new AppilotClient(conn);
+  const manifest = parseManifest(readManifestFile(args[0]));
+  const modeFlag = args.indexOf("--mode");
+  const mode = modeFlag !== -1 ? args[modeFlag + 1] : void 0;
+  if (mode !== void 0 && mode !== "merge" && mode !== "replace") {
+    throw new Error(`--mode is merge or replace, not ${mode}.`);
+  }
+  const plan = await planManifest(client, manifest, (id) => {
+    const resolved = id ?? conn.defaultAppId;
+    return resolved != null && Number.isFinite(resolved) ? resolved : null;
+  });
+  process.stderr.write(`[appilot-mcp] planned ${plan.planToken.slice(0, 12)}\u2026
+`);
+  const result = await applyManifest(client, manifest, {
+    planToken: plan.planToken,
+    mode,
+    expectedCurrentHash: plan.config?.expectedCurrentHash,
+    allowUnhealthy: args.includes("--allow-unhealthy")
+  });
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  return 0;
+}
+async function runCommand(argv) {
+  const [command, ...rest] = argv;
+  if (command === "--help" || command === "-h" || command === "help") {
+    process.stdout.write(HELP + "\n");
+    return 0;
+  }
+  if (command === "--version" || command === "-v" || command === "version") {
+    process.stdout.write(SERVER_VERSION + "\n");
+    return 0;
+  }
+  if (command === "install-skill") return installSkill(rest);
+  if (command === "plan") return runPlan(rest);
+  if (command === "apply") return runApply(rest);
+  return null;
+}
+
+// src/index.ts
 async function runStdio() {
   const conn = loadConnection();
   const server = createAppilotServer(conn);
@@ -57061,6 +57735,10 @@ async function runHttp() {
   await startRemote2(loadRemoteConfig());
 }
 async function main() {
+  const handled = await runCommand(process.argv.slice(2));
+  if (handled !== null) {
+    process.exit(handled);
+  }
   if (resolveTransport() === "http") {
     await runHttp();
     return;