appilot-mcp 0.2.1 → 0.4.0

package/.claude-plugin/plugin.json

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

@@ -1,11 +1,21 @@
 # appilot-mcp
 
-MCP server that lets an AI agent **read, validate, fix, and soak** an Appilot
-app's content-model configuration (Views, Controls, Forms, Action Plans,
-Knowledge, Zones, Tools) against the **config health contract**.
+Two MCP servers ship from this package, and they do opposite jobs.
 
-It is the tool surface behind the `app-configurator` skill. The skill is the
-instructions; this server is what actually touches your instance.
+**Appilot Studio** lets an AI agent **read, validate, fix, and soak** an Appilot
+app's content-model configuration (Views, Controls, Forms, Action Plans,
+Knowledge, Zones, Tools) against the **config health contract**. It is the tool
+surface behind the `app-configurator` skill: the skill is the instructions, and
+this server is what actually touches your instance. It is what a bare
+`appilot-mcp` starts.
+
+**Appilot**, the runtime connector, lets the person who USES a configured app
+operate it from the assistant they already pay for. It reads the page they are
+sharing, answers from the app's curated knowledge, and runs the app's own guided
+procedures in their browser under their own session. It writes no configuration.
+Start it with `appilot-mcp --runtime`, or connect to `/mcp/runtime` on the
+deployed service. See
+[the connector spec](../../../docs/architecture/appilot-runtime-connector.md).
 
 ## Why
 
@@ -21,10 +31,10 @@ Endpoint-agnostic by design. The same binary talks to a cloud tenant or an
 on-premise / sovereign instance purely by pointing `APPILOT_BASE_URL` at it. The
 static gate runs locally from `appilot-shared`, so it works with no network.
 
-## Two transports, one tool surface
+## Two transports
 
-The same tools serve two shapes, and which one you need is decided by the client,
-not by preference.
+Each server serves two shapes, and which one you need is decided by the client,
+not by preference. A tool is registered once per server and reachable over both.
 
 | Transport | Who launches it | Credential | Clients |
 |-----------|-----------------|------------|---------|
@@ -44,6 +54,8 @@ OAuth. That is what HTTP mode is for. See
 | `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) |
+| `APPILOT_SESSION_TOKEN` | for `--runtime` | An Appilot user session. The connector authenticates as the person, so this is the only credential it reads. |
+| `APPILOT_MCP_SERVER` | optional | `runtime` starts the Appilot connector instead of Studio. Same as `--runtime`. |
 
 HTTP mode reads a different profile. It holds no Appilot credential of its own,
 because each caller brings theirs.
@@ -55,23 +67,92 @@ 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
+## Studio 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 |
 
+## Appilot connector tools
+
+Eight, and deliberately no more: a model reads the whole list on every call.
+They are named in the vocabulary of the person using the app rather than in
+ours. `test/toolSurface.test.ts` holds this table to the registered surface.
+
+| Tool | Purpose |
+|------|---------|
+| `where_am_i` | Which app and view, whether the app is configured, whether a tab is shared, which plans apply here |
+| `read_page` | The shared page as an outline, as the visible text of a region, or as form state with its validation errors |
+| `find_on_page` | Elements by role and accessible name, with refs `highlight` can point at |
+| `highlight` | Point at one control, zone or element on the person's screen |
+| `search_knowledge` | The app's curated knowledge, with citations |
+| `list_plans` | The curated procedures that apply to this view, with the `plan_id` and fields `run_plan` takes |
+| `run_plan` | Run one curated plan in the page at a pace (`teach`, `walk`, `do`) |
+| `plan_status` | How a running plan is going, with a waiting mode that holds for the page to move |
+
+Every result says whether its work was visible in the page and what the answer
+is grounded in, and the tool descriptions oblige the assistant to act on both:
+confirm a plan in one sentence rather than re-listing steps the person is
+watching, and state the mode without inflating it.
+
+`read_page` and `find_on_page` answer with one `page_content` string: the DOM
+result serialized inside the backend's untrusted-content delimiters. The
+connector passes it through untouched, because the delimiters are the
+prompt-injection defence and they only work while they are still around the
+content. What the connector does decide is how much a read asks for, and over a
+hosted connection that is capped.
+
+The connector needs a live Appilot session, and over stdio that is
+`APPILOT_SESSION_TOKEN`. It never reads `APPILOT_PAT`: a service token names an
+organization, a session names a person, and the runtime routes exist so the
+connector can do no more than that person can.
+
+## 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 +164,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 +196,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 +245,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
 
@@ -184,8 +281,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.
@@ -201,8 +305,10 @@ What it serves:
 
 | Path | Purpose |
 |------|---------|
-| `POST /mcp` | The MCP endpoint, Streamable HTTP, bearer required |
-| `/.well-known/oauth-protected-resource/mcp` | Points a client at the authorization server |
+| `POST /mcp` | Appilot Studio over Streamable HTTP, bearer required, a configuration scope required |
+| `POST /mcp/runtime` | The Appilot connector, same transport, `runtime:use` required |
+| `/.well-known/oauth-protected-resource/mcp` | Points a Studio client at the authorization server |
+| `/.well-known/oauth-protected-resource/mcp/runtime` | The same for the connector |
 | `/.well-known/oauth-authorization-server` | Metadata, PKCE with S256, dynamic registration |
 | `/authorize`, `/token`, `/register` | The OAuth 2.1 flow |
 | `/consent` | Manual token verification and review |

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.4.0\n\nThe Appilot MCP server: read, validate, fix and provision an Appilot app.\n\nUSAGE\n  appilot-mcp                     Start Appilot Studio on stdio (what a client launches)\n  appilot-mcp --runtime           Start the Appilot connector instead: operate a configured app\n  appilot-mcp --http              Start the remote HTTP service, which serves both\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  APPILOT_SESSION_TOKEN  An Appilot user session, which is what --runtime authenticates with\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,173 @@
+/**
+ * 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 Appilot Studio on stdio (what a client launches)
+  appilot-mcp --runtime           Start the Appilot connector instead: operate a configured app
+  appilot-mcp --http              Start the remote HTTP service, which serves both
+  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
+  APPILOT_SESSION_TOKEN  An Appilot user session, which is what --runtime authenticates with
+
+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