appilot-mcp 0.1.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.1.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.1.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

@@ -29,7 +29,7 @@ not by preference.
 | Transport | Who launches it | Credential | Clients |
 |-----------|-----------------|------------|---------|
 | **stdio** (default) | The client, as a local child process | `APPILOT_PAT` in the process environment | Claude Code, Codex (CLI, IDE, app), Claude Desktop, Cursor, Antigravity |
-| **HTTP** (`--http`) | You, as a deployed service | The caller's own service token, collected once through OAuth | ChatGPT, claude.ai, and any remote MCP client |
+| **HTTP** (`--http`) | You, as a deployed service | Account approval or a manually supplied service token through OAuth | ChatGPT, claude.ai, and any remote MCP client |
 
 ChatGPT and claude.ai cannot start a process on your machine, and neither offers
 a field for pasting an API key: they connect to a URL and authenticate with
@@ -41,7 +41,7 @@ OAuth. That is what HTTP mode is for. See
 | Env | Required | Meaning |
 |-----|----------|---------|
 | `APPILOT_BASE_URL` | yes | Backend URL, e.g. `https://api.appilot.space` or `http://localhost:6001` |
-| `APPILOT_PAT` | for writes / server echo | A scoped service token (`appilot_pat_…`), minted in the Backoffice (admin → service tokens). `config:read` to read/validate, `config:write` to apply. |
+| `APPILOT_PAT` | for writes / server echo | A scoped service token (`appilot_pat_…`), minted in the Backoffice (Service tokens). `config:read` to read/validate, `config:write` to apply. |
 | `APPILOT_APP_ID` | optional | Default app id for tools that omit one |
 | `APPILOT_SOAK_STORAGE_STATE` | optional | Path to a Playwright `storageState` JSON for an authenticated site session (soak) |
 
@@ -55,17 +55,57 @@ 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) |
-| `update_action_plan` / `update_control` / `update_knowledge` | Guarded writes (server re-validates the trust boundary) |
+| `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 |
 | `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
 
@@ -78,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 |
 
@@ -108,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
 
@@ -134,7 +186,7 @@ Once one is running (see [Remote deployment](#remote-deployment)):
 
 - **ChatGPT**: Settings, Apps, Advanced settings, turn on Developer mode, then
   add a connector pointing at `https://<your-host>/mcp` with OAuth. The
-  authorization step asks for a service token, once.
+  authorization step opens Appilot account approval, or manual token consent on older deployments.
 - **claude.ai**: Settings, Connectors, Add custom connector, same URL.
 - **Codex** can use the remote endpoint too, if you prefer one shared deployment
   over a local process: add the URL to `~/.codex/config.toml` and run
@@ -147,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
+```
 
-### Antigravity
+Then add the server to `~/.cursor/mcp.json`.
 
-Copy `skills/app-configurator` to the applicable global skills directory:
+### Antigravity
 
-- 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
 
@@ -179,16 +235,23 @@ 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.
 
 ## Remote deployment
 
-HTTP mode is a small stateless web service. It stores nothing: no user table, no
-client registry, no token store. The OAuth authorization server seals its own
+HTTP mode delegates identity and approval storage to the backend. It has no
+local user table, client registry or raw token store. The OAuth authorization server seals its own
 state into the artifacts it issues (see `src/remote/tokens.ts`), so a second
 instance behaves exactly like the first and a cold start loses nothing.
 
@@ -200,7 +263,8 @@ What it serves:
 | `/.well-known/oauth-protected-resource/mcp` | Points a client at the authorization server |
 | `/.well-known/oauth-authorization-server` | Metadata, PKCE with S256, dynamic registration |
 | `/authorize`, `/token`, `/register` | The OAuth 2.1 flow |
-| `/consent` | The one page a person sees, where they paste a service token |
+| `/consent` | Manual token verification and review |
+| `/connect/callback` | Redeems account approval bound to the initiating browser |
 | `/health` (also `/healthz` off Cloud Run) | Liveness |
 
 Run it:
@@ -233,9 +297,9 @@ has to read before it can authenticate at all. The upload carries the
 
 ### How access works
 
-The service never sees an Appilot password and never mints a credential. A
-person creates a scoped service token in the Backoffice, pastes it once on the
-consent screen, and the service checks it against the instance
+The service never sees an Appilot password. Account approval asks the backend
+to create a scoped credential after the administrator reviews access. In the
+manual flow, a person pastes a previously created token and MCP checks it against the instance
 (`GET /config/whoami`) before granting anything. The granted scopes are the
 intersection of what the client asked for and what that token actually carries,
 so a `config:read` token cannot be talked into write access. The token is then
@@ -271,3 +335,17 @@ Live DOM soak needs Playwright: add it with pnpm and install Chromium.
 
 See `docs/architecture/appilot-mcp.md` (server) and
 `docs/content-model/config-health-contract.md` (the contract it enforces).
+
+### Account-based remote approval
+
+Remote deployments can reuse the Backoffice session for approval without asking
+users to create or paste a token. Configure APPILOT_MCP_HANDOFF_SECRET on backend
+and MCP, a trusted APPILOT_MCP_BACKOFFICE_URL on MCP, and the fixed
+APPILOT_MCP_PUBLIC_URL on backend. Deploy migration system/025 and the Backoffice
+approval page first. The cloud activation script is
+`scripts/enable-session-approval.sh`. Keep this secret separate from the OAuth key.
+
+Manual service-token consent remains available when session approval is not
+configured, or with `manual=1` on the authorization request. Consent and errors
+support English, Spanish and German. Administrators can filter connections,
+renew expiry and revoke access in Backoffice Service tokens.

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

@@ -26,6 +26,13 @@ export interface Capabilities {
         bundleFormatVersion: string;
         maxImportBytes: number;
     };
+    /**
+     * The closed enums the write paths reject on, sourced from the instance so
+     * the published list and the validator are one list. Absent on instances
+     * that predate it, which is why every reader treats it as optional: an agent
+     * with no vocabulary guesses, and `css` is the guess it makes.
+     */
+    entityVocabularies?: Record<string, unknown>;
 }
 /** Mirrors the backend's ProvisioningService result. Secrets appear once. */
 export interface ProvisionAppResponse {
@@ -45,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;
@@ -84,11 +100,53 @@ 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;
     constructor(message: string, status: number, body?: unknown);
 }
+/**
+ * The eight configurable entities, and where each one is written.
+ *
+ * Session templates and zones are here for the same reason as the rest: an app
+ * whose activities are conversations, or whose pages need landmark regions, was
+ * not authorable from a conversation at all, because the only writer that
+ * reached them was a whole-bundle import.
+ */
+export declare const ENTITY_PATHS: {
+    readonly view: "/views";
+    readonly control: "/domain/controls";
+    readonly form: "/domain/forms";
+    readonly tool: "/domain/tools";
+    readonly zone: "/domain/zones";
+    readonly action_plan: "/domain/action-plans";
+    readonly knowledge: "/knowledge/content";
+    readonly session_template: "/domain/session-templates";
+};
+export type ConfigEntityKind = keyof typeof ENTITY_PATHS;
+export declare const CONFIG_ENTITY_KINDS: ConfigEntityKind[];
+/** What `POST /developer-reports` answers. The posture is the point of it. */
+export interface DeveloperReportResponse {
+    report: {
+        id: string;
+        status: string;
+        occurrences: number;
+        kind: string;
+        title: string;
+    };
+    supportPosture: {
+        eligible: boolean;
+        message: string;
+    };
+}
 export declare class AppilotClient {
     private readonly conn;
     constructor(conn: AppilotConnection);
@@ -103,24 +161,60 @@ export declare class AppilotClient {
     listForms(appId: number): Promise<Record<string, unknown>[]>;
     listViews(appId: number): Promise<Record<string, unknown>[]>;
     listKnowledge(appId: number): Promise<Record<string, unknown>[]>;
+    listTools(appId: number): Promise<Record<string, unknown>[]>;
+    listZones(appId: number): Promise<Record<string, unknown>[]>;
+    /**
+     * The app's domains: which hostnames it serves, the languages each declares,
+     * and whether the hostname is verified. On the config surface, so a read-only
+     * credential can resolve the locales the configuration is expected to cover.
+     */
+    listAppDomains(appId: number): Promise<Record<string, unknown>[]>;
+    private entityPath;
+    createEntity(kind: ConfigEntityKind, body: unknown): Promise<unknown>;
+    updateEntity(kind: ConfigEntityKind, id: string, body: unknown): Promise<unknown>;
+    deleteEntity(kind: ConfigEntityKind, id: string): Promise<unknown>;
     updateActionPlan(id: string, body: unknown): Promise<unknown>;
     updateControl(id: string, body: unknown): Promise<unknown>;
     createControl(body: unknown): Promise<unknown>;
     updateForm(id: string, body: unknown): Promise<unknown>;
     updateKnowledge(id: string, body: unknown): Promise<unknown>;
+    createDeveloperReport(body: unknown): Promise<DeveloperReportResponse>;
+    listDeveloperReports(query: string): Promise<unknown>;
     /** Server-side non-persisting plan validation (echoes the runtime trust boundary). */
     validatePlan(appId: number, sections: unknown, formValues: unknown): Promise<{
         ok: boolean;
         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
      * it answers even for a read-only caller, which is what makes it usable as
      * the first probe of `verify_integration`.
+     *
+     * The endpoint takes a URL and derives the hostname itself; passing the bare
+     * hostname made the probe answer "URL is required" and report a warning about
+     * 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>;
@@ -133,8 +227,33 @@ export declare class AppilotClient {
     }): Promise<import('appilot-shared/config-bundle').ImportDiff>;
     /**
      * Read the app's content-model config and normalize it into a ConfigSnapshot.
-     * `expectedLocales` defaults to de/en/es (Appilot's trilingual baseline) but
-     * can be overridden per call once the domain's configured_languages are known.
+     *
+     * Two properties matter here and were both missing before.
+     *
+     * A failed read is a GAP, never an empty list. Swallowing the error made a
+     * refused knowledge read indistinguishable from an app with no knowledge, and
+     * every knowledge lint then passed on a configuration nobody had looked at.
+     *
+     * `expectedLocales` comes from the app's own domains when the caller does not
+     * say. The trilingual default is Appilot's baseline, not every customer's: a
+     * single-language app used to collect two medium i18n findings per entity for
+     * 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
+     * when the instance cannot answer, which is the behaviour every caller had
+     * before and is still better than checking nothing.
+     */
+    private resolveLocales;
 }