appilot-mcp 0.1.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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.0",
+  "version": "0.2.1",
   "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/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) |
 
@@ -63,9 +63,14 @@ because each caller brings theirs.
 | `capabilities` | Version + migration level + schema versions of the connected instance (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 |
+| `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 |
 | `soak_selectors` | Headless-browser check that each control selector resolves on the live page (needs Playwright) |
+| `report_feedback` / `list_feedback` | Report a gap or a defect in Appilot, and see what this organization has already raised |
 
 ## Distribution artifacts
 
@@ -134,7 +139,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
@@ -187,8 +192,8 @@ 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 +205,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 +239,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 +277,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/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 {
@@ -89,6 +96,40 @@ export declare class AppilotApiError extends Error {
     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,11 +144,25 @@ 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;
@@ -119,6 +174,10 @@ export declare class AppilotClient {
      * 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>>;
     /** Who this credential is: org, app narrowing, scopes. Never a secret. */
@@ -133,8 +192,24 @@ 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>;
+    /**
+     * 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;
 }

package/dist/client.js

@@ -9,6 +9,11 @@
  * defensively and never throw on a missing field. Field mapping is verified
  * against a live instance in the plan's Phase F.
  */
+/**
+ * Appilot's trilingual baseline, used only when the instance cannot say which
+ * languages an app actually claims to support.
+ */
+const DEFAULT_EXPECTED_LOCALES = ['de', 'en', 'es'];
 export class AppilotApiError extends Error {
     status;
     body;
@@ -19,8 +24,17 @@ export class AppilotApiError extends Error {
         this.name = 'AppilotApiError';
     }
 }
-/** Merge a base value + an `_i18n` override map into a single LocalizedText. */
-function fromBaseAndI18n(base, i18n) {
+/**
+ * Merge a base value + an `_i18n` override map into a single LocalizedText.
+ *
+ * The base column holds the text in the entity's SOURCE locale and `*_i18n`
+ * holds every other locale, so the source locale has to be indexed by name.
+ * Filing it under a synthetic 'base' key instead made the i18n lint report the
+ * source locale as missing on every entity that had any translation at all:
+ * a plan authored in `en` with `{ en: … }` and nothing else was told to
+ * "provide the name in en".
+ */
+function fromBaseAndI18n(base, i18n, sourceLocale) {
     const out = {};
     if (i18n && typeof i18n === 'object') {
         for (const [k, v] of Object.entries(i18n)) {
@@ -29,11 +43,17 @@ function fromBaseAndI18n(base, i18n) {
         }
     }
     if (typeof base === 'string' && base.length) {
-        // A base string has no locale of its own; expose it under a synthetic
-        // 'base' key AND leave declared locales as-is. The contract checks named
-        // locales, so we only surface base when nothing else exists.
-        if (Object.keys(out).length === 0)
+        const src = typeof sourceLocale === 'string' && sourceLocale ? sourceLocale : null;
+        // Never let the base overwrite an explicit per-locale value.
+        if (src) {
+            if (out[src] === undefined)
+                out[src] = base;
+        }
+        else if (Object.keys(out).length === 0) {
+            // An instance that does not record a source locale: the text is real
+            // but unattributable, so surface it without claiming a locale.
             out.base = base;
+        }
     }
     return out;
 }
@@ -55,8 +75,27 @@ function localized(entity, field) {
     const rows = entity.translations;
     if (Array.isArray(rows) && rows.length)
         return fromTranslationRows(rows, field);
-    return fromBaseAndI18n(entity[field], entity[`${field}_i18n`]);
+    return fromBaseAndI18n(entity[field], entity[`${field}_i18n`], entity.source_locale);
 }
+/**
+ * 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 const ENTITY_PATHS = {
+    view: '/views',
+    control: '/domain/controls',
+    form: '/domain/forms',
+    tool: '/domain/tools',
+    zone: '/domain/zones',
+    action_plan: '/domain/action-plans',
+    knowledge: '/knowledge/content',
+    session_template: '/domain/session-templates',
+};
+export const CONFIG_ENTITY_KINDS = Object.keys(ENTITY_PATHS);
 export class AppilotClient {
     conn;
     constructor(conn) {
@@ -77,8 +116,7 @@ export class AppilotClient {
         const text = await res.text();
         const body = text ? safeJson(text) : undefined;
         if (!res.ok) {
-            const message = body?.error ?? `${res.status} ${res.statusText}`;
-            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${message}`, res.status, body);
+            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}`, res.status, body);
         }
         return body;
     }
@@ -104,21 +142,66 @@ export class AppilotClient {
     listKnowledge(appId) {
         return this.request(`/knowledge/content?app_id=${appId}`);
     }
+    listTools(appId) {
+        return this.request(`/domain/tools?app_id=${appId}`);
+    }
+    listZones(appId) {
+        return this.request(`/domain/zones?app_id=${appId}`);
+    }
+    /**
+     * 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) {
+        return this.request(`/config/domains?appId=${appId}`);
+    }
     // -- writes -------------------------------------------------------------
+    //
+    // One create, one update and one delete per configurable entity, so a
+    // conversation can author configuration without round-tripping the whole
+    // app through a ConfigBundle. The routes below were already reachable by a
+    // service token holding `config:write`; what was missing was this surface.
+    //
+    // The path per entity is the only thing that varies, so the table drives it.
+    // A hand-written method per entity is twenty-four near-identical bodies and a
+    // place for a typo to hide.
+    entityPath(kind, id) {
+        const base = ENTITY_PATHS[kind];
+        return id == null ? base : `${base}/${encodeURIComponent(id)}`;
+    }
+    createEntity(kind, body) {
+        return this.request(this.entityPath(kind), { method: 'POST', body: JSON.stringify(body) });
+    }
+    updateEntity(kind, id, body) {
+        return this.request(this.entityPath(kind, id), { method: 'PUT', body: JSON.stringify(body) });
+    }
+    deleteEntity(kind, id) {
+        return this.request(this.entityPath(kind, id), { method: 'DELETE' });
+    }
     updateActionPlan(id, body) {
-        return this.request(`/domain/action-plans/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('action_plan', id, body);
     }
     updateControl(id, body) {
-        return this.request(`/domain/controls/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('control', id, body);
     }
     createControl(body) {
-        return this.request(`/domain/controls`, { method: 'POST', body: JSON.stringify(body) });
+        return this.createEntity('control', body);
     }
     updateForm(id, body) {
-        return this.request(`/domain/forms/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('form', id, body);
     }
     updateKnowledge(id, body) {
-        return this.request(`/knowledge/content/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('knowledge', id, body);
+    }
+    // -- developer feedback -------------------------------------------------
+    // The one surface here that sends data OUT of the tenant. See server.ts for
+    // the consent rule and redaction.ts for what may not travel.
+    createDeveloperReport(body) {
+        return this.request('/developer-reports', { method: 'POST', body: JSON.stringify(body) });
+    }
+    listDeveloperReports(query) {
+        return this.request(`/developer-reports${query ? `?${query}` : ''}`);
     }
     /** Server-side non-persisting plan validation (echoes the runtime trust boundary). */
     validatePlan(appId, sections, formValues) {
@@ -141,9 +224,14 @@ export class AppilotClient {
      * 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) {
-        return this.request(`/domain/check?domain=${encodeURIComponent(domain)}`);
+        const url = /^https?:\/\//i.test(domain) ? domain : `https://${domain}`;
+        return this.request(`/domain/check?url=${encodeURIComponent(url)}`);
     }
     /** Who this credential is: org, app narrowing, scopes. Never a secret. */
     whoami() {
@@ -164,27 +252,81 @@ export class AppilotClient {
     }
     /**
      * 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.
      */
-    async buildSnapshot(appId, expectedLocales = ['de', 'en', 'es']) {
-        const [plans, controls, forms, views, knowledge] = await Promise.all([
-            this.listActionPlans(appId).catch(() => []),
-            this.listControls(appId).catch(() => []),
-            this.listForms(appId).catch(() => []),
-            this.listViews(appId).catch(() => []),
-            this.listKnowledge(appId).catch(() => []),
+    async buildSnapshot(appId, expectedLocales) {
+        const gaps = [];
+        const read = async (entity, load, map) => {
+            try {
+                const rows = await load();
+                return Array.isArray(rows) ? rows.map(map) : [];
+            }
+            catch (err) {
+                gaps.push({ entity, reason: err instanceof Error ? err.message : String(err) });
+                return [];
+            }
+        };
+        const [plans, controls, forms, views, tools, zones, knowledge, locales] = await Promise.all([
+            read('actionPlans', () => this.listActionPlans(appId), mapActionPlan),
+            read('controls', () => this.listControls(appId), mapControl),
+            read('forms', () => this.listForms(appId), mapForm),
+            read('views', () => this.listViews(appId), mapView),
+            read('tools', () => this.listTools(appId), mapTool),
+            read('zones', () => this.listZones(appId), mapZone),
+            read('knowledge', () => this.listKnowledge(appId), mapKnowledge),
+            expectedLocales?.length ? Promise.resolve(expectedLocales) : this.resolveLocales(appId),
         ]);
         return {
-            expectedLocales,
-            views: views.map(mapView),
-            controls: controls.map(mapControl),
-            forms: forms.map(mapForm),
-            zones: [], // zones read per-domain; wired in Phase F once domain ids are resolved.
-            actionPlans: plans.map(mapActionPlan),
-            knowledge: knowledge.map(mapKnowledge),
+            expectedLocales: locales,
+            views,
+            controls,
+            forms,
+            tools,
+            zones,
+            actionPlans: plans,
+            knowledge,
+            ...(gaps.length ? { gaps } : {}),
         };
     }
+    /**
+     * 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.
+     */
+    async resolveLocales(appId) {
+        try {
+            const rows = await this.listAppDomains(appId);
+            const out = new Set();
+            for (const d of rows) {
+                const configured = d.configured_languages;
+                if (Array.isArray(configured)) {
+                    for (const l of configured)
+                        if (typeof l === 'string' && l)
+                            out.add(l);
+                }
+                const fallback = d.default_language;
+                if (typeof fallback === 'string' && fallback)
+                    out.add(fallback);
+            }
+            if (out.size)
+                return [...out].sort();
+        }
+        catch {
+            // Older instance, or a credential that cannot read domains.
+        }
+        return DEFAULT_EXPECTED_LOCALES;
+    }
 }
 function safeJson(text) {
     try {
@@ -194,11 +336,54 @@ function safeJson(text) {
         return text;
     }
 }
+/**
+ * Render a backend error the way a model can act on it.
+ *
+ * The backend answers with `{ error, code, details, requestId }` (see
+ * docs/setup/logging-conventions.md). Reporting only `error` throws away the
+ * half that says what to fix: "Bundle failed structural validation" names no
+ * field, while `details.errors` names every path. Keep the rendering compact,
+ * because this lands in a conversation, and keep `requestId` so a support
+ * request can be matched to a server log line.
+ */
+function describeError(body, res) {
+    const b = (body ?? {});
+    if (typeof body !== 'object' || body === null) {
+        return typeof body === 'string' && body.trim() ? body.trim() : `${res.status} ${res.statusText}`;
+    }
+    const parts = [b.error ?? `${res.status} ${res.statusText}`];
+    if (b.code)
+        parts.push(`[${b.code}]`);
+    // The per-field issues. The backend produces four shapes and every one of
+    // them is the difference between "Form validation failed" and a refusal the
+    // caller can act on: envelope errors and Zod issues under `details`, the
+    // forms router's top-level `violations`, and the delete routes' `dependents`
+    // on a 409, which names exactly what still points at the entity.
+    const issues = (b.details?.errors ?? b.details?.issues ?? b.violations);
+    if (Array.isArray(issues) && issues.length) {
+        const shown = issues.slice(0, 20).map(i => typeof i === 'string' ? `  ${i}` : `  ${i.path || '(root)'}: ${i.message ?? ''}`.trimEnd());
+        if (issues.length > 20)
+            shown.push(`  and ${issues.length - 20} more`);
+        parts.push('\n' + shown.join('\n'));
+    }
+    else if (Array.isArray(b.dependents) && b.dependents.length) {
+        parts.push('\n  still referenced by: ' + JSON.stringify(b.dependents));
+    }
+    else if (b.details && Object.keys(b.details).length) {
+        parts.push(`\n  ${JSON.stringify(b.details)}`);
+    }
+    if (b.requestId)
+        parts.push(`\n  requestId ${b.requestId}`);
+    return parts.join(' ').replace(/ \n/g, '\n');
+}
 function mapView(v) {
     return { slug: v.slug, path: String(v.path ?? v.view_path ?? ''), name: localized(v, 'name') };
 }
 function mapControl(c) {
     return {
+        // The row id is what `update_entity` takes. Without it here the agent had
+        // no way to name the control it wanted to patch.
+        id: c.id != null ? String(c.id) : undefined,
         semantic_id: String(c.semantic_id ?? c.name ?? ''),
         locator_type: String(c.locator_type ?? c.locator_strategy ?? ''),
         locator: String(c.locator ?? c.locator_value ?? ''),
@@ -218,6 +403,7 @@ function mapForm(f) {
 function mapActionPlan(p) {
     const sections = p.sections ?? [];
     return {
+        id: p.id != null ? String(p.id) : undefined,
         semantic_id: String(p.semantic_id ?? ''),
         sections,
         form_values: p.form_values ?? {},
@@ -227,6 +413,22 @@ function mapActionPlan(p) {
         is_active: p.is_active !== false,
     };
 }
+function mapTool(t) {
+    const runtime = (t.runtime_spec ?? t.runtimeSpec);
+    return {
+        id: t.id != null ? String(t.id) : undefined,
+        tool_name: String(t.tool_name ?? t.name ?? ''),
+        kind: String(runtime?.kind ?? t.kind ?? ''),
+        view_path: t.view_path ?? null,
+        is_active: t.is_active !== false,
+    };
+}
+function mapZone(z) {
+    return {
+        id: z.id != null ? String(z.id) : undefined,
+        semantic_id: String(z.semantic_id ?? ''),
+    };
+}
 function mapKnowledge(k) {
     // A knowledge article read may return either a single localized row or a group
     // of language rows. Normalize both into a bodies[] list.

package/dist/config.d.ts

@@ -26,6 +26,17 @@ export interface AppilotConnection {
      * Defaults to stdio, which is the operator's own machine.
      */
     transport?: 'stdio' | 'http';
+    /**
+     * Scopes the CALLER was granted, when a grant sits in front of the credential.
+     *
+     * Only the remote transport has one: the person approved a specific set on the
+     * consent screen, and the service token sealed behind it may carry more. The
+     * backend enforces the token's scopes, not the grant's, so without this the
+     * consent screen was describing a limit nothing applied. Undefined on stdio,
+     * where the operator's own credential is the only authority and there is no
+     * grant to narrow it.
+     */
+    grantedScopes?: string[];
 }
 export declare function loadConnection(env?: NodeJS.ProcessEnv): AppilotConnection;
 /** Which transport the process serves. Local stdio unless asked otherwise. */
@@ -41,6 +52,9 @@ export declare function resolveTransport(argv?: string[], env?: NodeJS.ProcessEn
  * needs three things and no database.
  */
 export interface RemoteConfig {
+    handoffSecret?: string;
+    /** Trusted Backoffice origin for the connection help and brand assets. */
+    backofficeUrl?: string;
     /** Port to listen on. Cloud Run supplies PORT. */
     port: number;
     /** Public origin the clients reach, e.g. https://mcp.appilot.space. */

package/dist/config.js

@@ -67,8 +67,27 @@ export function loadRemoteConfig(env = process.env) {
     catch {
         throw new RemoteConfigError(`APPILOT_MCP_DOCS_URL is not a valid URL: ${rawDocs}`);
     }
+    const rawBackoffice = env.APPILOT_MCP_BACKOFFICE_URL?.trim() ||
+        (trimTrailingSlash(baseUrl) === 'https://api.appilot.space' ? 'https://backoffice.appilot.space' : undefined);
+    let backofficeUrl;
+    if (rawBackoffice) {
+        try {
+            const parsed = new URL(rawBackoffice);
+            if ((parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(parsed.hostname))) || parsed.username || parsed.password)
+                throw new Error();
+            backofficeUrl = parsed.origin;
+        }
+        catch {
+            throw new RemoteConfigError('APPILOT_MCP_BACKOFFICE_URL must be an HTTPS origin (localhost excepted).');
+        }
+    }
+    const handoffSecret = env.APPILOT_MCP_HANDOFF_SECRET?.trim();
+    if (handoffSecret && (handoffSecret.length < 32 || !backofficeUrl))
+        throw new RemoteConfigError('Session approval requires a 32-character handoff secret and a Backoffice origin.');
     return {
+        handoffSecret,
         port,
+        backofficeUrl,
         publicUrl,
         secret,
         allowedHosts: [publicUrl.host, ...extraHosts],