appilot-mcp 0.2.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Set up, configure, audit, repair, back up, restore, and verify an Appilot app: provision the app, its domains and widget key, scaffold the host integration, and keep the content model correct. Uses the Appilot MCP server and the app-configurator skill.",
   "author": {
     "name": "Appilot",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Set up, configure, audit, repair, back up, restore, and verify an Appilot app: provision the app, its domains and widget key, scaffold the host integration, and keep the content model correct. Uses the Appilot MCP server and the app-configurator skill.",
   "author": {
     "name": "Appilot",

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 BetterKnow GmbH
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -55,23 +55,58 @@ because each caller brings theirs.
 | `APPILOT_MCP_OAUTH_SECRET` | yes | At least 32 characters (`openssl rand -base64 32`). Everything the authorization server issues is sealed with it, so rotating it disconnects every client. |
 | `PORT` | no | Defaults to 8080. Cloud Run supplies it. |
 | `APPILOT_MCP_ALLOWED_HOSTS` | no | Extra `Host` values to accept, comma separated, for a proxy or a platform-assigned hostname. The public origin is always accepted. |
+| `APPILOT_MCP_DOCS_URL` | no | Where the protected-resource metadata points a client for documentation. Defaults to the public docs site. |
+| `APPILOT_MCP_BACKOFFICE_URL` | no | The Backoffice origin consent screens link to, and the only origin account approval is accepted from. Must be HTTPS (localhost excepted). Defaults to `https://backoffice.appilot.space` when the instance is the Appilot cloud. |
+| `APPILOT_MCP_HANDOFF_SECRET` | no | Enables account approval instead of pasting a service token. At least 32 characters, and it must match the backend's. Separate from the OAuth secret, and it requires `APPILOT_MCP_BACKOFFICE_URL`. |
 
 ## Tools
 
+Twenty-five, in the order the server registers them. `test/toolSurface.test.ts`
+holds this table, `mcpb/manifest.json` and the registered tools to one list.
+
 | Tool | Purpose |
 |------|---------|
-| `capabilities` | Version + migration level + schema versions of the connected instance (negotiate before configuring) |
+| `capabilities` | Version, migration level and the closed vocabularies this instance accepts (negotiate before configuring) |
 | `read_config` | Normalized snapshot of an app's content model |
 | `validate_config` | Severity-ranked findings against the health contract (local + server echo) |
 | `entity_template` | A valid skeleton per entity kind, carrying the closed enums this instance accepts |
 | `create_entity` / `update_entity` / `delete_entity` | Authoring across all eight kinds (server re-validates the trust boundary) |
 | `validate_action_plan` | Check draft plan sections before writing them |
-| `inspect_page` | Read a page and rank locator candidates by whether they survive the next render |
-| `scaffold_agent_first` | The four artifacts one capability needs to be operable by the agent |
 | `export_config` / `import_config` | Whole-app ConfigBundle round trip, dry-run first, merge or replace |
+| `whoami` | Which organization, which app and which scopes the credential reaches |
+| `create_app` | Provision the app, its domains and a widget key, with the snippets to paste in |
+| `list_apps` | What this organization has provisioned, with each domain's verification status |
+| `list_widget_keys` | The keys already minted, by label and prefix. No raw key, no secret |
+| `verify_domain` | Where a domain's DNS verification stands, and the TXT record it needs |
+| `integration_snippet` | The script tag and boot call for an app that already exists. Pure, no scope |
+| `plan_manifest` / `apply_manifest` | A whole tenant from one versioned file, plan before apply |
+| `scaffold_integration` | The host application's source: identity relay, widget boot, a client action |
+| `verify_integration` | Load the running page and report what is actually true |
 | `soak_selectors` | Headless-browser check that each control selector resolves on the live page (needs Playwright) |
+| `inspect_page` | Read a page and rank locator candidates by whether they survive the next render |
+| `scaffold_agent_first` | The artifacts one capability needs to be operable by the agent |
 | `report_feedback` / `list_feedback` | Report a gap or a defect in Appilot, and see what this organization has already raised |
 
+## The command line
+
+The package is an MCP server first, and a small CLI for the things a pipeline
+needs without an MCP client in front of them.
+
+```bash
+npx appilot-mcp --help
+npx appilot-mcp --version
+npx appilot-mcp install-skill --claude     # or --codex, --cursor, --gemini
+npx appilot-mcp plan  app.appilot.json     # preview, writes nothing
+npx appilot-mcp apply app.appilot.json     # apply the plan it just printed
+```
+
+`plan` and `apply` read the same environment the stdio server does, and `apply`
+runs the plan itself and passes its own token, so the preview cannot be skipped.
+`install-skill` copies the bundled `app-configurator` skill into the client's
+skills directory, which is what makes the skill reachable from a bare `npx`
+install: inside the npm cache no client looks for it.
+
+
 ## Distribution artifacts
 
 One package carries a tool-neutral implementation plus thin discovery adapters:
@@ -83,6 +118,8 @@ One package carries a tool-neutral implementation plus thin discovery adapters:
 | `.codex-plugin/plugin.json` | Codex plugin |
 | `.claude-plugin/plugin.json` | Claude Code plugin |
 | `mcpb/manifest.json` | Claude Desktop bundle manifest, packed by `pnpm build:mcpb` |
+| `examples/app.appilot.json` | A complete app manifest to copy, held valid by `test/exampleManifest.test.ts` |
+| `.claude-plugin/public-marketplace/` | The public marketplace repository, prepared and not published |
 | `Dockerfile` | The remote HTTP service |
 | `dist/index.bundle.js` | Self-contained Node.js MCP server, both transports |
 
@@ -113,10 +150,20 @@ task after installation so the new tool surface is loaded.
 
 ### Claude Code
 
-Add the repository marketplace and install `app-configurator@appilot`. Claude's
-plugin settings prompt for the backend URL, service token, and optional app ID.
-The token is declared sensitive so Claude stores it in secure credential
-storage.
+```
+/plugin marketplace add /absolute/path/to/app-pilot
+/plugin install app-configurator@appilot
+```
+
+Claude's plugin settings then prompt for the backend URL, the service token and
+an optional app id. The token is declared sensitive, so Claude stores it in
+secure credential storage.
+
+There is no published marketplace repository yet: `appilot/appilot-plugins` does
+not exist on GitHub, so a `/plugin marketplace add appilot/appilot-plugins`
+anywhere is wrong until someone publishes it. The tree that repository would
+carry is prepared in `.claude-plugin/public-marketplace/`, along with the human
+steps, and `pnpm build:marketplace` assembles it.
 
 ### Claude Desktop
 
@@ -152,17 +199,21 @@ instance needs no public listener.
 
 ### Cursor
 
-Copy `skills/app-configurator` to `~/.cursor/skills/app-configurator`, then add
-the server to `~/.cursor/mcp.json`.
+```bash
+npx -y appilot-mcp install-skill --cursor
+```
+
+Then add the server to `~/.cursor/mcp.json`.
 
 ### Antigravity
 
-Copy `skills/app-configurator` to the applicable global skills directory:
-
-- Antigravity IDE: `~/.gemini/config/skills/app-configurator`
-- Antigravity CLI: `~/.gemini/antigravity-cli/skills/app-configurator`
+```bash
+npx -y appilot-mcp install-skill --gemini
+```
 
-Register the stdio server in `~/.gemini/config/mcp_config.json`.
+That writes `~/.gemini/config/skills/app-configurator`, which is where the IDE
+looks. The CLI reads `~/.gemini/antigravity-cli/skills/`, so pass `--dir` for
+that one. Register the stdio server in `~/.gemini/config/mcp_config.json`.
 
 ### Any stdio MCP client
 
@@ -184,8 +235,15 @@ Point the client at the built bundle:
 }
 ```
 
-For registry-backed distribution, replace `node` and the bundle path with
-`pnpm dlx appilot-mcp` after the package is published.
+From npm, with no checkout at all, replace `node` and the bundle path with
+`npx` and `-y appilot-mcp`, then install the skill the package ships:
+
+```bash
+npx -y appilot-mcp install-skill --claude   # or --codex, --cursor, --gemini
+```
+
+Without that step the skill stays in the npm cache, where no client looks, and
+the tools arrive with no procedure around them.
 
 Do not commit service tokens. Use the MCP client's secure secret storage or
 environment forwarding when available.

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The command line around the MCP server.
+ *
+ * `npx appilot-mcp` starts the stdio server, which is what an MCP client wants
+ * and what nothing else does. Everything here exists because a person or a
+ * pipeline typed something else and got a server waiting silently on stdin:
+ * `--help` and `--version` did that, and so did every attempt to apply a
+ * manifest from CI, which had to script an MCP client to reach a plan and an
+ * apply that are two ordinary function calls.
+ *
+ * `install-skill` is the other half of the same problem. The npm tarball
+ * carries `skills/app-configurator`, and it lands in the npm cache, where no
+ * client looks. Copying it to the client's own skills directory is the step
+ * that was documented only as a marketplace command pointing at a repository
+ * that does not exist.
+ */
+export declare const HELP = "appilot-mcp 0.3.0\n\nThe Appilot MCP server: read, validate, fix and provision an Appilot app.\n\nUSAGE\n  appilot-mcp                     Start the MCP server on stdio (what a client launches)\n  appilot-mcp --http              Start the remote HTTP service instead\n  appilot-mcp plan <file>         Preview an appilot.app-manifest. Writes nothing\n  appilot-mcp apply <file>        Plan, then apply the same manifest\n  appilot-mcp install-skill       Copy the app-configurator skill to an agent client\n  appilot-mcp --help | --version\n\nOPTIONS\n  apply           --mode merge|replace   How the config half is imported. Default merge\n                  --allow-unhealthy      Import a bundle the health gate would refuse\n  install-skill   --claude | --codex | --cursor | --gemini | --dir <path>\n\nENVIRONMENT\n  APPILOT_BASE_URL   Your instance, e.g. https://api.appilot.space or http://localhost:6001\n  APPILOT_PAT        A scoped service token from the Backoffice, under Service tokens\n  APPILOT_APP_ID     Optional default app id\n\nDocs: https://docs.appilot.space/docs/developers/configure-with-ai/overview";
+/** Where each client looks for a skill. One directory per client, all under $HOME. */
+export declare const SKILL_TARGETS: Record<string, string>;
+/**
+ * The bundled skill directory, resolved from the running file.
+ *
+ * `dist/index.bundle.js` and `skills/` are siblings under the package root in
+ * the tarball and in the workspace, so one hop up is the answer in both. The
+ * fallback covers a deeper build output rather than guessing silently.
+ */
+export declare function bundledSkillDir(from?: string): string | null;
+/**
+ * Handle everything that is not "start a server".
+ *
+ * Returns null when the argv asks for a server, so the entry point stays the
+ * transport switch it was.
+ */
+export declare function runCommand(argv: string[]): Promise<number | null>;

package/dist/cli.js

@@ -0,0 +1,171 @@
+/**
+ * The command line around the MCP server.
+ *
+ * `npx appilot-mcp` starts the stdio server, which is what an MCP client wants
+ * and what nothing else does. Everything here exists because a person or a
+ * pipeline typed something else and got a server waiting silently on stdin:
+ * `--help` and `--version` did that, and so did every attempt to apply a
+ * manifest from CI, which had to script an MCP client to reach a plan and an
+ * apply that are two ordinary function calls.
+ *
+ * `install-skill` is the other half of the same problem. The npm tarball
+ * carries `skills/app-configurator`, and it lands in the npm cache, where no
+ * client looks. Copying it to the client's own skills directory is the step
+ * that was documented only as a marketplace command pointing at a repository
+ * that does not exist.
+ */
+import { cpSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SERVER_VERSION } from './version.js';
+import { loadConnection } from './config.js';
+import { AppilotClient } from './client.js';
+import { applyManifest, parseManifest, planManifest } from './manifest.js';
+export const 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`;
+/** Where each client looks for a skill. One directory per client, all under $HOME. */
+export const SKILL_TARGETS = {
+    claude: join('.claude', 'skills'),
+    codex: join('.codex', 'skills'),
+    cursor: join('.cursor', 'skills'),
+    gemini: join('.gemini', 'config', 'skills'),
+};
+/**
+ * The bundled skill directory, resolved from the running file.
+ *
+ * `dist/index.bundle.js` and `skills/` are siblings under the package root in
+ * the tarball and in the workspace, so one hop up is the answer in both. The
+ * fallback covers a deeper build output rather than guessing silently.
+ */
+export 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>.\n`);
+            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}\nStart a new session so the client loads it.\n`);
+    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;
+}
+/**
+ * Apply runs its own plan and passes the token it produced.
+ *
+ * The token binds an apply to a preview of the same bytes, and a CLI that made
+ * the caller carry it between two commands would only teach them to store it.
+ * Planning here keeps the property (the manifest cannot change between the two)
+ * and prints the preview, so the run is still auditable in a CI log.
+ */
+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] : undefined;
+    if (mode !== undefined && 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)}…\n`);
+    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;
+}
+/**
+ * Handle everything that is not "start a server".
+ *
+ * Returns null when the argv asks for a server, so the entry point stays the
+ * transport switch it was.
+ */
+export 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;
+}

package/dist/client.d.ts

@@ -52,10 +52,19 @@ export interface ProvisionAppResponse {
     }>;
     widgetKey?: {
         id: number | null;
-        action: 'created' | 'reused' | 'updated';
+        /**
+         * `blocked` is a real outcome, not an error: a LIVE key needs a verified
+         * domain, and the app and its domains are still provisioned without it.
+         * The union has to carry it or every caller reads a blocked key as a
+         * successful one.
+         */
+        action: 'created' | 'reused' | 'updated' | 'blocked';
         keyPrefix?: string;
         rawKey?: string;
         rawSecret?: string;
+        allowedDomains?: string[];
+        /** Present on `blocked`: what is missing and what to do about it. */
+        reason?: string;
     };
     integration: {
         apiUrl: string | null;
@@ -91,6 +100,14 @@ export interface ProvisionedAppSummary {
         verification_status: string;
     }>;
 }
+/** A widget key as the org sees it back: no raw value, no secret, ever. */
+export interface ProvisionedWidgetKey {
+    id: number;
+    name: string;
+    keyPrefix: string;
+    allowedDomains: string[];
+    isActive: boolean;
+}
 export declare class AppilotApiError extends Error {
     readonly status: number;
     readonly body?: unknown;
@@ -169,6 +186,13 @@ export declare class AppilotClient {
         errors: string[];
     }>;
     listProvisioned(): Promise<ProvisionedAppSummary[]>;
+    /**
+     * 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.
+     */
+    listWidgetKeys(): Promise<ProvisionedWidgetKey[]>;
     provisionApp(body: ProvisionAppRequest): Promise<ProvisionAppResponse>;
     /**
      * Domain check: does this hostname resolve to a tenant? Public endpoint, so
@@ -180,6 +204,17 @@ export declare class AppilotClient {
      * the tenant on every single run.
      */
     checkDomain(domain: string): Promise<Record<string, unknown>>;
+    /**
+     * 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: number): Promise<Record<string, unknown>>;
+    /** Ask Appilot to look for the TXT record now. */
+    triggerDomainVerification(domainId: number): Promise<Record<string, unknown>>;
     /** Who this credential is: org, app narrowing, scopes. Never a secret. */
     whoami(): Promise<Record<string, unknown>>;
     exportConfig(appId: number): Promise<import('appilot-shared/config-bundle').ConfigBundle>;
@@ -205,6 +240,15 @@ export declare class AppilotClient {
      * languages it had never claimed to support.
      */
     buildSnapshot(appId: number, expectedLocales?: string[]): Promise<ConfigSnapshot>;
+    /**
+     * 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.
+     */
+    private credentialRefusal;
     /**
      * Which locales this app's configuration is expected to cover: the union of
      * its domains' configured languages. Falls back to the trilingual baseline

package/dist/client.js

@@ -116,7 +116,8 @@ export class AppilotClient {
         const text = await res.text();
         const body = text ? safeJson(text) : undefined;
         if (!res.ok) {
-            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}`, res.status, body);
+            const credential = res.status === 401 || res.status === 403 ? ` ${credentialAdvice(!!this.conn.token)}` : '';
+            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}${credential}`, res.status, body);
         }
         return body;
     }
@@ -217,6 +218,16 @@ export class AppilotClient {
     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) });
     }
@@ -233,6 +244,21 @@ export class AppilotClient {
         const url = /^https?:\/\//i.test(domain) ? domain : `https://${domain}`;
         return this.request(`/domain/check?url=${encodeURIComponent(url)}`);
     }
+    /**
+     * 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');
@@ -286,6 +312,17 @@ export class AppilotClient {
             read('knowledge', () => this.listKnowledge(appId), mapKnowledge),
             expectedLocales?.length ? Promise.resolve(expectedLocales) : this.resolveLocales(appId),
         ]);
+        // An empty knowledge list is the one read that can mean two things.
+        // `/knowledge/content` is an optional-auth route, so a missing or rejected
+        // bearer answers `200 []` instead of refusing, and from here that is
+        // indistinguishable from an app with no knowledge. Every knowledge lint
+        // then passes over a configuration nobody was allowed to look at, which is
+        // exactly the failure the `gaps` array exists to prevent.
+        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,
@@ -298,6 +335,29 @@ export class AppilotClient {
             ...(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
@@ -328,6 +388,19 @@ export class AppilotClient {
         return DEFAULT_EXPECTED_LOCALES;
     }
 }
+/**
+ * What to do about a 401 or a 403, in the same voice as the offline errors.
+ *
+ * "Access denied. Token required." is the first thing a new developer meets and
+ * it names nothing: not the variable to set, not the screen the token comes
+ * from, not the preset to choose. The `APPILOT_BASE_URL` message next door does
+ * name all three, and it is the standard this one had to reach.
+ */
+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);

package/dist/contract/healthContract.js

@@ -31,6 +31,19 @@ const CREATE_INTENT = /\b(create|add|new|update|edit|erstell|anleg|neu|hinzu|cre
 function localizedValues(text) {
     return Object.values(text).filter((v) => typeof v === 'string');
 }
+/**
+ * `form_values` as a record, whatever arrived.
+ *
+ * The snapshot type says it is one, and a hand-authored or scaffolded plan can
+ * still carry null or a string. Reading it defensively keeps a malformed bundle
+ * a finding rather than an exception thrown out of the whole audit.
+ */
+function authoredFormValues(plan) {
+    const raw = plan.form_values;
+    return raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : {};
+}
 // ---------------------------------------------------------------------------
 // Lint 1 — marker trust boundary (reuse appilot-shared).
 // ---------------------------------------------------------------------------
@@ -52,7 +65,7 @@ function lintMarkers(snap) {
             });
         }
         // form_values fields must belong to their form.
-        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', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -60,8 +73,22 @@ function lintMarkers(snap) {
                 });
                 continue;
             }
+            // A malformed `form_values` entry is a FINDING, not a crash. The
+            // authored shape is `{ fields: [{ control_id, value }] }`, and a bundle
+            // carrying `{}` there used to take the whole contract down with
+            // "entry.fields is not iterable", so the one tool that could have named
+            // the defect answered with a stack trace instead.
+            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) ?? new Set();
-            for (const f of entry.fields) {
+            for (const f of authored.fields) {
                 if (!fields.has(f.control_id)) {
                     findings.push({
                         severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -84,7 +111,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);
@@ -123,7 +150,7 @@ function lintActionability(snap) {
             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;
+                || (authoredFormValues(plan)[form.semantic_id]?.fields?.length ?? 0) > 0;
             if (!fillsForm) {
                 findings.push({
                     severity: 'high', category: 'actionability', entity: `action_plan:${plan.semantic_id}`,