appilot-mcp 0.2.1 → 0.4.0

package/dist/scaffold.js

@@ -10,7 +10,62 @@
  * integration a developer must write in their own backend, it is
  * security-critical, and getting it wrong is invisible until an auth edge case
  * shows up in production.
+ *
+ * Everything returned here has to COMPILE. Three of the six framework outputs
+ * did not typecheck under `strict` when the 2026-09-07 audit ran them through
+ * `tsc`, and the relay, the piece a developer is least able to review, was the
+ * file that failed. `test/scaffoldTypecheck.test.ts` now compiles every output
+ * against the workspace sources of `appilot` and `appilot-server`.
+ */
+import { IDENTIFIER_KINDS } from 'appilot-shared/validation';
+/**
+ * The frameworks with a first-class relay, plus `other`.
+ *
+ * `appilot-server` is a Node package, so a Django, Rails or PHP host cannot use
+ * it. That is not a reason to answer a raw Zod enum dump: the exchange is one
+ * authenticated HTTPS call, and `other` returns it as curl plus a Python and a
+ * Ruby handler.
  */
+export const SCAFFOLD_FRAMEWORKS = [
+    'next',
+    'express',
+    'fastify',
+    'hono',
+    'remix',
+    'sveltekit',
+    'other',
+];
+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',
+            };
+    }
+}
+/**
+ * The two ways a developer runs this against a machine they are sitting at.
+ * Both are true at once and the difference between them is what the turn can
+ * see, so the notes state both rather than picking one.
+ */
+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';
 
@@ -31,40 +86,68 @@ export const POST = createWidgetTokenHandler({
 });
 `;
 }
+/**
+ * Express and Fastify share the Node adapter and differ only in how the handler
+ * is mounted.
+ *
+ * Two things here are not decoration. The session lives on a property the host's
+ * own middleware added, which `IncomingMessage` does not declare, so the cast
+ * names the shape instead of leaving the read as an error. And Fastify owns the
+ * response until it is told otherwise: writing to `reply.raw` without
+ * `reply.hijack()` first is how a correct-looking relay produces "Reply was
+ * already sent" in production.
+ */
 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';",
-        '',
-        '// Call once, after your app knows the user is signed in. The widget',
-        '// requires an identified user; the relay below mints that identity.',
-        'export function startAppilot() {',
-        '  bootAppilotWidget({',
-        `    widgetScriptUrl: '${options.widgetScriptUrl}',`,
-    ];
-    if (options.widgetKey)
-        lines.push(`    widgetKey: '${options.widgetKey}',`);
+    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 mints that identity.', 'export function startAppilot() {', '  bootAppilotWidget({', `    widgetScriptUrl: '${options.widgetScriptUrl}',`, '    widgetKey,');
     if (options.apiUrl)
         lines.push(`    appilotApiUrl: '${options.apiUrl}',`);
     lines.push("    tokenEndpoint: '/api/widget/token',", '  });', '}');
@@ -96,8 +179,141 @@ export function registerBookingActions(navigate: (path: string) => void) {
   return () => handle.unregister();        // unregister on route change
 }
 `;
+/** The raw exchange, for a host `appilot-server` cannot serve. */
+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 ? `\n  data-api-key="${options.widgetKey}"` : '';
+    const apiAttr = options.apiUrl ? `\n  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>
+`,
+    };
+}
 export 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':
@@ -134,18 +350,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;
@@ -178,68 +397,135 @@ 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,
     };
 }
-export function scaffoldAgentFirst(options) {
-    const { capability, slug, appId } = options;
-    const method = options.endpoint?.method?.toUpperCase() ?? 'POST';
-    const pathTemplate = options.endpoint?.path ?? `/api/${slug}`;
-    const tool = {
-        app_id: appId,
-        tool_name: slug,
-        title: capability,
-        description: `Use when the user wants to ${capability.toLowerCase()}.`,
-        parameters: {
-            type: 'object',
-            properties: {},
-            required: [],
-        },
-        runtime_spec: {
-            kind: 'http_proxy',
-            method,
-            path_template: pathTemplate,
-            body_template: {},
+/** `open-booking` -> `open_booking`, and `Open booking!` -> `open_booking`. */
+function toolNameFrom(slug) {
+    return IDENTIFIER_KINDS.tool_name.normalize(slug) || 'do_the_thing';
+}
+/** `open_booking` -> `open-booking`, the shape control and plan ids take. */
+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}}}).`,
+            ],
         },
-        title_i18n: {},
-        description_i18n: {},
+    ];
+}
+export function scaffoldAgentFirst(options) {
+    const { capability, appId } = options;
+    const shape = options.shape ?? 'create';
+    const viewPath = options.viewPath ?? '/';
+    // Both identifier kinds, from the one slug. `tool_name` is snake_case because
+    // it reaches the model as a callable name; control, form and plan ids are
+    // semantic_ids. Normalising here is what stopped the scaffold from failing
+    // the server's own identifier contract on its first call.
+    const toolName = toolNameFrom(options.slug);
+    const slug = semanticSlugFrom(options.slug);
+    // `submit-x` rather than `btn-x-submit`: the contract's own identifier lint
+    // treats four segments over twenty-four characters as a slugified UI label,
+    // and a two-word capability made the scaffold trip that heuristic on an
+    // identifier it had just generated itself.
+    const ids = {
+        open: `btn-${slug}`,
+        form: `form-${slug}`,
+        submit: `submit-${slug}`,
     };
-    const actionPlan = {
+    const method = options.endpoint?.method?.toUpperCase() ?? (shape === 'read' ? 'GET' : 'POST');
+    const pathTemplate = options.endpoint?.path ?? `/api/${slug}`;
+    const trigger = `Use when the user wants to ${capability.toLowerCase()}.`;
+    // A client action and an HTTP-proxy tool are two answers to the same
+    // question, and emitting both taught the reader that a capability needs one
+    // of each. It needs whichever one matches where the work happens.
+    const tool = options.clientSide
+        ? null
+        : {
+            app_id: appId,
+            tool_name: toolName,
+            title: capability,
+            description: trigger,
+            parameters: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+            runtime_spec: {
+                kind: 'http_proxy',
+                method,
+                path_template: pathTemplate,
+                body_template: {},
+            },
+            title_i18n: {},
+            description_i18n: {},
+        };
+    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,
     };
@@ -261,6 +547,7 @@ export 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',
@@ -270,11 +557,11 @@ export 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.
@@ -288,24 +575,64 @@ 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 };
+}
+/**
+ * The script tag and the boot call for an app that is already provisioned.
+ *
+ * `create_app` returns these, and returning them was the only way to get them,
+ * so a developer who had lost the snippet re-ran a provisioning write to read
+ * one line of HTML. They are composed from the connection and the key, so this
+ * is pure: it calls nothing and needs no scope. The shape matches what the
+ * backend's own `buildIntegration` returns, deliberately, so a curl caller and
+ * an agent read the same thing.
+ */
+export function integrationSnippet(options) {
+    const idiom = publicKeyIdiom(options.framework ?? 'other');
+    const keyAttr = options.widgetKey ? `\n  data-api-key="${options.widgetKey}"` : '';
+    const apiAttr = options.apiUrl ? `\n  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\n  src="${options.widgetScriptUrl}"${keyAttr}${apiAttr}\n  async\n></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),
         ],
     };
 }