appilot-mcp 0.2.1 → 0.3.0

package/dist/server.js

@@ -19,7 +19,7 @@ import { inspectPage } from './inspect.js';
 import { runHealthContract } from './contract/healthContract.js';
 import { soakSelectors } from './soak.js';
 import { applyManifest, parseManifest, planManifest } from './manifest.js';
-import { scaffoldIntegration, scaffoldAgentFirst } from './scaffold.js';
+import { SCAFFOLD_FRAMEWORKS, scaffoldIntegration, scaffoldAgentFirst, integrationSnippet } from './scaffold.js';
 import { verifyIntegration } from './verify.js';
 import { redactForTransport, refuseSecretOverRemote } from './redaction.js';
 /**
@@ -43,7 +43,9 @@ const DEFAULT_WIDGET_SCRIPT_URL = 'https://cdn.appilot.space/widget/v1/appilot.e
  */
 const 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.
 
@@ -58,6 +60,20 @@ 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.`;
+/**
+ * Where each scope comes from, appended to the refusal.
+ *
+ * A refusal that names the missing scope and stops leaves the reader one
+ * question short of acting: who can widen it. For provisioning the answer is
+ * not "you", which is exactly the case the configurator meets, so the refusal
+ * says who to ask and what the preset is called on the screen they will open.
+ */
+const 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.',
+};
 export function createAppilotServer(conn) {
     const client = new AppilotClient(conn);
     function text(value) {
@@ -85,7 +101,8 @@ export 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.'));
+            'Reconnect and approve that scope, using a service token that carries it. ' +
+            HOW_TO_GRANT[scope]));
     }
     function resolveAppId(appId) {
         const id = appId ?? conn.defaultAppId;
@@ -365,16 +382,17 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('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: z.string().min(1),
             description: z.string().optional(),
             domains: z.array(z.string()).optional(),
             widgetKeyName: z.string().optional(),
-            isTestKey: z.boolean().optional(),
+            isTest: z.boolean().optional(),
+            allowedDomains: z.array(z.string()).optional(),
             dryRun: z.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;
@@ -382,8 +400,8 @@ export function createAppilotServer(conn) {
             const result = await client.provisionApp({
                 app: { name, description },
                 domains: (domains ?? []).map(domain => ({ domain })),
-                widgetKey: widgetKeyName || isTestKey !== undefined
-                    ? { name: widgetKeyName, isTest: isTestKey }
+                widgetKey: widgetKeyName || isTest !== undefined || allowedDomains
+                    ? { name: widgetKeyName, isTest, allowedDomains }
                     : undefined,
                 dryRun: dryRun === true,
             });
@@ -393,9 +411,135 @@ export function createAppilotServer(conn) {
             return errorText(err);
         }
     });
+    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: z.string().min(1),
+            appId: z.number().int().optional(),
+            trigger: z.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,
+            };
+            // The TXT record lives on the apps router, which authenticates an
+            // organization session rather than a service token. When that is
+            // refused, the provisioning dry run answers the same question, so the
+            // tool degrades to a second source instead of to nothing.
+            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: z.number().int().optional(),
+            widgetKey: z.string().optional(),
+            widgetScriptUrl: z.string().optional(),
+            framework: z.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: z.union([z.record(z.any()), z.string()]) },
     }, async ({ manifest }) => {
         const refusal = scopeRefusal('config:read');
@@ -415,7 +559,7 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('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: z.union([z.record(z.any()), z.string()]),
             planToken: z.string(),
@@ -424,17 +568,26 @@ export function createAppilotServer(conn) {
             allowUnhealthy: z.boolean().optional(),
         },
     }, async ({ manifest, planToken, mode, expectedCurrentHash, allowUnhealthy }) => {
-        // A manifest apply provisions AND writes configuration, so it needs both.
-        const refusal = scopeRefusal('provision:write') ?? scopeRefusal('config:write');
-        if (refusal)
-            return refusal;
         try {
             const parsed = parseManifest(manifest);
+            // The config half always writes when the manifest carries one. The
+            // provisioning half is decided by the manifest rather than by the
+            // tool: applyManifest previews it and refuses only when it would
+            // actually change an app, a domain or a key. A CI token holding
+            // config:write alone keeps content in sync on an app a person
+            // already provisioned, which is the reason the scopes are separate.
+            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,
+                provisionRefusal: provisionRefusal ? provisionRefusal.content[0].text : null,
             });
             return text({ ...result, provisioning: redactForTransport(result.provisioning, conn.transport) });
         }
@@ -444,9 +597,9 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('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: z.enum(['next', 'express', 'fastify', 'hono', 'remix', 'sveltekit']),
+            framework: z.enum(SCAFFOLD_FRAMEWORKS),
             widgetKey: z.string().optional(),
             widgetScriptUrl: z.string().optional(),
             idNamespace: z.string().optional(),
@@ -522,15 +675,17 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('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: z.string().min(1),
             slug: z.string().min(1),
             appId: z.number().int().optional(),
             endpoint: z.object({ method: z.string(), path: z.string() }).optional(),
             clientSide: z.boolean().optional(),
+            shape: z.enum(['create', 'navigate', 'read']).optional(),
+            viewPath: z.string().optional(),
         },
-    }, async ({ capability, slug, appId, endpoint, clientSide }) => {
+    }, async ({ capability, slug, appId, endpoint, clientSide, shape, viewPath }) => {
         try {
             return text(scaffoldAgentFirst({
                 capability,
@@ -538,6 +693,8 @@ export function createAppilotServer(conn) {
                 appId: appId ?? conn.defaultAppId ?? null,
                 endpoint: endpoint ?? null,
                 clientSide,
+                shape,
+                viewPath,
             }));
         }
         catch (err) {

package/dist/version.d.ts

@@ -11,4 +11,4 @@
  * hand-synced numbers drift and the drift shows up as a client reporting a
  * version the server does not have.
  */
-export declare const SERVER_VERSION = "0.2.1";
+export declare const SERVER_VERSION = "0.3.0";

package/dist/version.js

@@ -11,4 +11,4 @@
  * hand-synced numbers drift and the drift shows up as a client reporting a
  * version the server does not have.
  */
-export const SERVER_VERSION = '0.2.1';
+export const SERVER_VERSION = '0.3.0';

package/examples/app.appilot.json

@@ -0,0 +1,212 @@
+{
+  "kind": "appilot.app-manifest",
+  "formatVersion": "1.0",
+  "app": {
+    "name": "Acme Booking",
+    "description": "The example manifest that ships with appilot-mcp. Copy it, change the names, keep the shape."
+  },
+  "domains": [
+    { "domain": "app.acme.com", "default_language": "en", "configured_languages": ["en", "de"] }
+  ],
+  "widgetKeys": [
+    { "name": "production", "allowedDomains": ["app.acme.com"] }
+  ],
+  "config": {
+    "kind": "appilot.config-bundle",
+    "formatVersion": "1.0",
+    "exportedAt": "2026-09-07T00:00:00.000Z",
+    "source": { "appId": 0, "appSlug": "acme-booking", "orgId": null },
+    "locales": ["en", "de"],
+    "entities": {
+      "views": [
+        {
+          "domain": "app.acme.com",
+          "path": "bookings",
+          "slug": "bookings",
+          "entry_path": "/bookings",
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": { "name": "Bookings", "description": "The list of bookings and the form that creates one." },
+            "de": { "name": "Buchungen", "description": "Die Liste der Buchungen und das Formular, das eine anlegt." }
+          },
+          "detection_rules": [
+            { "priority": 10, "type": "path_prefix", "config": { "value": "/bookings" }, "is_active": true }
+          ]
+        }
+      ],
+      "controls": [
+        {
+          "semantic_id": "btn-create-booking",
+          "locator": "[data-testid=\"new-booking\"]",
+          "locator_type": "class_text",
+          "llm_hint": "Opens the booking form.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": null,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "New booking", "description": "Opens the form that creates a booking." },
+            "de": { "label": "Neue Buchung", "description": "Öffnet das Formular, das eine Buchung anlegt." }
+          }
+        },
+        {
+          "semantic_id": "field-booking-date",
+          "locator": "booking-date",
+          "locator_type": "id",
+          "llm_hint": "The day the booking is for.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": { "form": "form-create-booking", "order": 1 },
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "Date", "description": "The day the booking is for." },
+            "de": { "label": "Datum", "description": "Der Tag, für den gebucht wird." }
+          }
+        },
+        {
+          "semantic_id": "submit-create-booking",
+          "locator": "[data-testid=\"save-booking\"]",
+          "locator_type": "class_text",
+          "llm_hint": "Saves the booking.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": null,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "Save", "description": "Saves the booking." },
+            "de": { "label": "Speichern", "description": "Speichert die Buchung." }
+          }
+        }
+      ],
+      "forms": [
+        {
+          "semantic_id": "form-create-booking",
+          "domain": "app.acme.com",
+          "llm_hint": "Creates one booking.",
+          "view_paths": ["bookings"],
+          "required_fields": ["field-booking-date"],
+          "submit_control": "submit-create-booking",
+          "entry_control": "btn-create-booking",
+          "visibility_rules": null,
+          "field_defaults": null,
+          "prerequisites": null,
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "New booking", "description": "Creates one booking." },
+            "de": { "label": "Neue Buchung", "description": "Legt eine Buchung an." }
+          }
+        }
+      ],
+      "tools": [
+        {
+          "tool_name": "create_booking",
+          "view": null,
+          "parameters": {
+            "type": "object",
+            "properties": { "date": { "type": "string", "description": "ISO date the booking is for." } },
+            "required": ["date"]
+          },
+          "runtime_spec": {
+            "kind": "http_proxy",
+            "method": "POST",
+            "path_template": "/api/bookings",
+            "body_template": { "date": "{{date}}" }
+          },
+          "auth_header_name": "Authorization",
+          "source_locale": "en",
+          "translations": {
+            "en": { "title": "Create a booking", "description": "Use when the user wants to create a booking." },
+            "de": { "title": "Buchung anlegen", "description": "Verwenden, wenn die Person eine Buchung anlegen möchte." }
+          },
+          "parameter_descriptions": {
+            "en": { "date": "ISO date the booking is for." },
+            "de": { "date": "ISO-Datum, für das gebucht wird." }
+          }
+        }
+      ],
+      "zones": [],
+      "action_plans": [
+        {
+          "semantic_id": "plan-create-booking",
+          "sections": [
+            {
+              "view_path": "bookings",
+              "steps": [
+                "Open the form with [New booking]({{click:btn-create-booking}}).",
+                "Fill in [the booking form]({{form:form-create-booking}}).",
+                "Submit it with [Save]({{click:submit-create-booking}})."
+              ]
+            }
+          ],
+          "form_values": { "form-create-booking": { "fields": [] } },
+          "provenance": "registry",
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": {
+              "name": "Create a booking",
+              "description": "Use when the user wants to create a booking.",
+              "step_narratives": null
+            },
+            "de": {
+              "name": "Buchung anlegen",
+              "description": "Verwenden, wenn die Person eine Buchung anlegen möchte.",
+              "step_narratives": [[
+                "Öffne das Formular mit [Neue Buchung]({{click:btn-create-booking}}).",
+                "Fülle [das Buchungsformular]({{form:form-create-booking}}) aus.",
+                "Sende es mit [Speichern]({{click:submit-create-booking}}) ab."
+              ]]
+            }
+          }
+        }
+      ],
+      "knowledge_content": [
+        {
+          "group": "booking-rules",
+          "scope": "app_global",
+          "url_pattern": null,
+          "domain": "app.acme.com",
+          "visibility": "internal",
+          "source": "manual",
+          "is_active": true,
+          "source_locale": "en",
+          "bodies": [
+            {
+              "language": "en",
+              "title": "What a booking is",
+              "description": "The rules and vocabulary behind a booking.",
+              "notes": null,
+              "general_info": "A booking reserves one resource for one day. Bookings are made by the account holder and cannot start in the past. A booking that has already started can be cancelled but not moved.\n\nThe procedure for creating one lives in the plan-create-booking action plan, not here."
+            },
+            {
+              "language": "de",
+              "title": "Was eine Buchung ist",
+              "description": "Die Regeln und Begriffe hinter einer Buchung.",
+              "notes": null,
+              "general_info": "Eine Buchung reserviert eine Ressource für einen Tag. Buchungen legt die Kontoinhaberin an, und sie können nicht in der Vergangenheit beginnen. Eine bereits begonnene Buchung lässt sich stornieren, aber nicht verschieben.\n\nDas Vorgehen zum Anlegen steht im Action Plan plan-create-booking, nicht hier."
+            }
+          ],
+          "views": [{ "domain": "app.acme.com", "path": "bookings", "priority": 10 }]
+        }
+      ],
+      "session_templates": []
+    },
+    "secretRefs": [
+      {
+        "entity": "tools",
+        "id": "create_booking",
+        "secret": "tool_auth:create_booking",
+        "status": "needs-reconnect",
+        "action": "Open the tool in the Backoffice and paste the credential. Secrets never travel in a bundle."
+      }
+    ]
+  }
+}