@everfur/cli 0.2.1 → 0.4.1

package/dist/{chunk-XMIERMOW.js → chunk-QCXZJW5C.js}

@@ -1,139 +1,226 @@
 #!/usr/bin/env node
-import { ENVIRONMENTS, SURFACES, VERIFY_IDENTITY_MODES, fetchContract, NO_CONTRACT_CACHE, systemClock, fetchTransport, describeFailure, loadDecisionSpaceFromContract, uuidFromKey, resolveEndpoint, createApiClient, createContractProvider, nodeContractCache, CLI_VERSION, withPrefix, ephemeralCredential, isJsonObject, error_explanation_v1_schema_default, verification_v1_schema_default, diagnosis_v1_schema_default, plan_v1_schema_default, IDENTITY_QUESTION, IDENTITY_TREE, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, nodeFileSystem, expandCapabilities, detectThemeFromText, planIntegration, parseOrigin, parseLoaderUrl, isEverfurLoaderHost, EVERFUR_LOADER_HOSTS, resolveCredential, PARTNER_KEY, runVerification, themePropFor, normalizeSurfaces, buildSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, resolveOffline, knownCodes, offlineSuggestions, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, buildExplanationDocument, nextActionFor, detectProject, BASE_URL_ENV_VAR, API_BASE_URL_BY_ENVIRONMENT, plannableCapabilities, blockedCapabilities, buildSdkExplanationDocument, buildContractTableExplanationDocument, SESSION_TOKEN, ALL_CAPABILITIES, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE } from './chunk-KQICUK54.js';
+import { ENVIRONMENTS, ENVELOPE_SHAPE, SURFACES, VERIFY_IDENTITY_MODES, refusal, API_BASE_URL_BY_ENVIRONMENT, fetchContract, NO_CONTRACT_CACHE, systemClock, fetchTransport, describeFailure, loadDecisionSpaceFromContract, uuidFromKey, resolveEndpoint, createApiClient, createContractProvider, nodeContractCache, CLI_VERSION, withPrefix, ephemeralCredential, isJsonObject, REFUSAL_POLICY, error_explanation_v1_schema_default, verification_v1_schema_default, diagnosis_v1_schema_default, plan_v1_schema_default, NEXT_ACTIONS, IDENTITY_QUESTION, IDENTITY_TREE, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, nodeFileSystem, expandCapabilities, detectThemeFromText, planIntegration, parseOrigin, parseLoaderUrl, isEverfurLoaderHost, EVERFUR_LOADER_HOSTS, resolveCredential, PARTNER_KEY, runVerification, themePropFromSource, normalizeSurfaces, failedResult, buildSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, toolCodeExplanation, resolveOffline, resolveWithoutRegistry, knownCodes, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, TOOL_CODES, registryAlsoIn, buildExplanationDocument, nextActionFor, digestOfProjection, detectProject, BASE_URL_ENV_VAR, checkTenantMode, isWorkspaceRootEvidence, plannableCapabilities, blockedCapabilities, offlineDocument, toolCodeMeaning, SESSION_TOKEN, SESSION_MINT_TREE, BACKEND_LANGUAGE_QUESTION, ALL_CAPABILITIES } from './chunk-EBVP6FAD.js';
 import { z } from 'zod';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { join } from 'path';
+import { isAbsolute, join, dirname, basename } from 'path';
 import { createHash } from 'crypto';
 import { InvalidTokenError, TooManyRequestsError, TemporarilyUnavailableError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
 
-var NEXT_ACTIONS = [
-  "ask_developer",
-  "fix_arguments",
-  "fix_environment",
-  "retry",
-  "wait_then_retry",
-  "call_explain_error",
-  "call_diagnose",
-  "use_sandbox_tenant",
-  "report_to_developer"
-];
-var REFUSAL_POLICY = Object.freeze({
-  // everfur_plan_integration
-  UNDERSPECIFIED_INTEGRATION: { retryable: false, nextAction: "ask_developer", docsPath: "everfur://guide" },
-  PROJECT_SOURCE_REQUIRED: { retryable: false, nextAction: "fix_arguments", docsPath: "everfur://guide" },
-  PROJECT_SOURCE_AMBIGUOUS: { retryable: false, nextAction: "fix_arguments", docsPath: "everfur://guide" },
-  PLATFORM_NOT_SUPPORTED: { retryable: false, nextAction: "report_to_developer", docsPath: "everfur://guide/platform" },
-  CAPABILITIES_BLOCKED: { retryable: false, nextAction: "report_to_developer", docsPath: "everfur://contract/capabilities" },
-  // hosted only: `environment` names a different API host than the connected tenant's
-  ENVIRONMENT_MISMATCH: { retryable: false, nextAction: "ask_developer", docsPath: null },
-  // shared wire configuration
-  WIRE_NOT_CONFIGURED: { retryable: false, nextAction: "fix_environment", docsPath: null },
-  // any tool given a server-side path (project_root, contract_path) on a server that does not run beside the
-  // developer's project: the Everfur-hosted MCP reads no path, its own disk included
-  LOCAL_PATH_NOT_READABLE: { retryable: false, nextAction: "fix_arguments", docsPath: "everfur://guide" },
-  WIDGET_CREDENTIAL_UNUSABLE: { retryable: false, nextAction: "fix_environment", docsPath: "everfur://contract/credentials" },
-  NO_PARTNER_KEY: { retryable: false, nextAction: "fix_environment", docsPath: "everfur://contract/credentials" },
-  PARTNER_KEY_MALFORMED: { retryable: false, nextAction: "fix_environment", docsPath: "everfur://contract/credentials" },
-  // everfur_verify_integration
-  INVALID_ORIGIN: { retryable: false, nextAction: "fix_arguments", docsPath: null },
-  INVALID_LOADER_URL: { retryable: false, nextAction: "fix_arguments", docsPath: null },
-  VERIFICATION_FAILED: { retryable: false, nextAction: "call_diagnose", docsPath: null },
-  // everfur_diagnose
-  DIAGNOSTICS_NOT_DEPLOYED: { retryable: false, nextAction: "report_to_developer", docsPath: null },
-  DIAGNOSTICS_FAILED: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  DIAGNOSTICS_MALFORMED: { retryable: false, nextAction: "fix_environment", docsPath: null },
-  // the contract, fetched from GET /partners/contract (everfur_plan_integration, everfur_explain_error)
-  CONTRACT_CREDENTIAL_MISSING: { retryable: false, nextAction: "fix_environment", docsPath: null },
-  CONTRACT_CREDENTIAL_UNUSABLE: { retryable: false, nextAction: "fix_environment", docsPath: null },
-  CONTRACT_UNAVAILABLE: { retryable: "from_failure", nextAction: "from_failure", docsPath: null },
-  UNKNOWN_OPTION: { retryable: false, nextAction: "fix_arguments", docsPath: "everfur://guide" },
-  // everfur_explain_error
-  CONTRACT_UNUSABLE: { retryable: false, nextAction: "fix_arguments", docsPath: null },
-  NO_ERROR_REGISTRY: { retryable: false, nextAction: "fix_arguments", docsPath: null },
-  UNKNOWN_ERROR_CODE: { retryable: false, nextAction: "fix_arguments", docsPath: "everfur://contract/errors" },
-  // everfur_send_test_message
-  ENTITLEMENTS_UNREADABLE: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  NOT_A_SANDBOX_TENANT: { retryable: false, nextAction: "use_sandbox_tenant", docsPath: null },
-  // from the mint call's own status: a 429 (VerifyMintRateLimited) or 503 (VerifyMintUnavailable) is transient
-  SESSION_NOT_MINTED: { retryable: "from_failure", nextAction: "from_failure", docsPath: null },
-  PET_NOT_REGISTERED: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  CHAT_NOT_GRANTED: { retryable: false, nextAction: "call_diagnose", docsPath: null },
-  CONVERSATIONS_UNREADABLE: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  PRIOR_TURN_UNANSWERED: { retryable: true, nextAction: "wait_then_retry", docsPath: null },
-  CONVERSATION_NOT_CREATED: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  SEND_FAILED: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  DEADLINE_EXCEEDED: { retryable: true, nextAction: "retry", docsPath: null },
-  STREAM_FAILED: { retryable: true, nextAction: "retry", docsPath: null },
-  EMPTY_STREAM: { retryable: true, nextAction: "retry", docsPath: null },
-  // the hosted tenant read tools (everfur_get_tenant_status and the rest), over GET /mcp/tenant/*
-  // (docs/HOSTED_TENANT_API.md): the read failed on the wire, answered a body outside the documented shape, or
-  // reached a surface that is not switched on for the connected tenant (a setting Everfur holds)
-  TENANT_READ_FAILED: { retryable: "from_failure", nextAction: "from_failure", docsPath: "everfur://contract/errors" },
-  TENANT_READ_MALFORMED: { retryable: false, nextAction: "report_to_developer", docsPath: null },
-  TENANT_SURFACE_NOT_ENABLED: { retryable: false, nextAction: "report_to_developer", docsPath: null },
-  // hosted only: the connected tenant has no publishable key, or one of a shape no deployment issues. Its keys are
-  // Everfur's to issue and nothing a developer exports reaches them, so the refusal is reported, never "fixed" locally
-  TENANT_PUBLISHABLE_KEY_UNUSABLE: { retryable: false, nextAction: "report_to_developer", docsPath: null },
-  // any tool: a body threw instead of returning a document
-  INTERNAL_ERROR: { retryable: false, nextAction: "report_to_developer", docsPath: null }
-});
-function fromFailure(details) {
-  const kind = details["kind"];
-  if (kind === "network" || kind === "timeout") return { retryable: true, nextAction: "retry" };
-  const status = details["status"];
-  if (typeof status === "number") {
-    if (status === 429) return { retryable: true, nextAction: "wait_then_retry" };
-    if (status >= 500) return { retryable: true, nextAction: "retry" };
-    if (status === 401 || status === 403) return { retryable: false, nextAction: "fix_environment" };
-  }
-  if (typeof details["code"] === "string") return { retryable: false, nextAction: "call_explain_error" };
-  return { retryable: false, nextAction: "report_to_developer" };
-}
-function errorBody(code, message, details = {}) {
-  const policy = REFUSAL_POLICY[code];
-  const derived = fromFailure(details);
-  const requestId = details["request_id"];
+var PLAN_STEPS_BUDGET_BYTES = 24 * 1024;
+var SUMMARY_MAX_CHARS = 120;
+var INTENT_MAX_CHARS = 72;
+var PLAN_SUMMARY_KIND = "everfur.plan.summary";
+var PLAN_SUMMARY_VERSION = 2;
+var PLAN_ID_PATTERN = /^[0-9a-f]{16}$/;
+var MAX_PAGES = 999;
+var PLAN_STEPS_INPUT_SHAPE = {
+  plan_id: z.string().regex(PLAN_ID_PATTERN).optional().describe("The plan_id of an earlier summary. When given, the call refuses with PLAN_CHANGED if the plan these arguments now produce has other steps, other arguments or another contract than the one summarised, so steps are never served from a plan other than the one summarised."),
+  page: z.number().int().min(1).max(MAX_PAGES).optional().describe("A page of an earlier summary, 1 to its pages, with the same arguments that produced it. The call then returns that page instead of the summary: its steps in full (detail, commands, files and the complete body of each file), and on page 1 the detection, the warnings and the checklist in full and the principles. Not with steps."),
+  steps: z.array(z.string().min(1).max(128)).min(1).max(64).optional().describe("Step ids from an earlier summary, with the same arguments that produced it. The call then returns those steps in full (detail, commands, files and the complete body of each file) instead of the summary, a page at a time: remaining_steps names the rest. Not with page.")
+};
+function byteLength(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+function planIdOf(plan) {
+  const identity = { steps: plan.steps, supplied: plan.supplied, contract: plan.decisionSpace?.digest ?? null };
+  return digestOfProjection(JSON.parse(JSON.stringify(identity))).slice(0, 16);
+}
+var SENTENCE_END = /[.!?](?=\s+[^a-z\s]|\s*$)/;
+var NAMES_A_SECRET = /SECRET_KEY/;
+function oneLine(text, max = SUMMARY_MAX_CHARS) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const end = flat.search(SENTENCE_END);
+  const sentence = end === -1 ? flat : flat.slice(0, end + 1);
+  if (sentence.length <= max || NAMES_A_SECRET.test(sentence)) return sentence;
+  const cut = sentence.slice(0, max - 1);
+  const space = cut.lastIndexOf(" ");
+  return `${(space > 0 ? cut.slice(0, space) : cut).replace(/[,;:(]$/, "")}\u2026`;
+}
+function principleByTitle(principle) {
+  return { treeId: principle.treeId, id: principle.id, title: principle.title, guide: `everfur://guide/${principle.treeId}` };
+}
+function preambleOf(plan) {
   return {
-    code,
-    message,
-    retryable: policy.retryable === "from_failure" ? derived.retryable : policy.retryable,
-    next_action: policy.nextAction === "from_failure" ? derived.nextAction : policy.nextAction,
-    request_id: typeof requestId === "string" ? requestId : null,
-    docs_path: policy.docsPath,
-    details
+    detected: plan.detected,
+    warnings: plan.warnings,
+    principles: plan.principles.map(principleByTitle),
+    ...plan.checklist === void 0 ? {} : { checklist: plan.checklist }
   };
 }
-function refusal(code, message, details = {}) {
-  const error = errorBody(code, message, details);
+var PAGE_ENVELOPE_BYTES = byteLength(JSON.stringify({
+  ok: true,
+  environment_source: "connected_tenant",
+  plan_id: "0".repeat(16),
+  page: MAX_PAGES,
+  pages: MAX_PAGES,
+  next_page: MAX_PAGES,
+  steps: []
+}));
+function pagesOf(plan) {
+  const pages = [];
+  let page = [];
+  let bytes = PAGE_ENVELOPE_BYTES + byteLength(JSON.stringify(preambleOf(plan)));
+  for (const step of plan.steps) {
+    const size = byteLength(JSON.stringify(step)) + 1;
+    const pageHasContent = page.length > 0 || pages.length === 0;
+    if (pageHasContent && bytes + size > PLAN_STEPS_BUDGET_BYTES) {
+      pages.push(page);
+      page = [];
+      bytes = PAGE_ENVELOPE_BYTES;
+    }
+    page.push(step);
+    bytes += size;
+  }
+  pages.push(page);
+  return pages;
+}
+function detectedFacts(detected) {
+  const { theme } = detected;
   return {
-    isError: true,
-    document: { ok: false, error, failed_precondition: error.code, message: error.message }
+    root: detected.root,
+    projectType: detected.projectType,
+    packageManager: detected.packageManager,
+    dependencies: Object.fromEntries(detected.dependencies.map((dependency) => [dependency.name, dependency.installed ?? dependency.declared])),
+    ...detected.webEmbedding === void 0 ? {} : { webEmbedding: detected.webEmbedding },
+    ...detected.webFramework === void 0 ? {} : { webFramework: detected.webFramework },
+    ...theme === void 0 ? {} : { theme: theme === null ? null : { source: theme.source, confidence: theme.confidence, theme: theme.theme } }
   };
 }
-function failedResult(result, code, message, details = {}) {
-  const error = errorBody(code, message, details);
+function goalOf(plan, pages) {
+  const capabilities = plan.supplied.capabilities ?? [];
+  const what = capabilities.length === 0 ? "Everfur" : `Everfur ${capabilities.join(", ")}`;
+  const where = `this ${plan.detected.projectType} project`;
+  const environment = plan.supplied.environment ? ` on ${plan.supplied.environment}` : "";
+  const identity = plan.supplied.identityMode ? `, identity ${plan.supplied.identityMode}` : "";
+  const steps = plan.steps.length === 1 ? "1 step" : `${plan.steps.length} steps`;
+  return `Add ${what} to ${where}${environment}${identity}: ${steps} on ${pages === 1 ? "1 page" : `${pages} pages`}.`;
+}
+function summarizePlan(plan) {
+  const { steps, checklist, warnings } = plan;
+  const pages = pagesOf(plan);
+  const pageOf = new Map(pages.flatMap((page, index) => page.map((step) => [step.id, index + 1])));
+  return {
+    schemaVersion: plan.schemaVersion,
+    kind: PLAN_SUMMARY_KIND,
+    generatedBy: plan.generatedBy,
+    status: plan.status,
+    detected: detectedFacts(plan.detected),
+    supplied: plan.supplied,
+    missingFacts: plan.missingFacts,
+    blocked: plan.blocked,
+    ...plan.platformBlock === void 0 ? {} : { platformBlock: plan.platformBlock },
+    decisionSpace: plan.decisionSpace,
+    summaryVersion: PLAN_SUMMARY_VERSION,
+    goal: goalOf(plan, pages.length),
+    // A warning is what an agent must not have to fetch, so each is here by its first sentence, which states it; page 1
+    // carries it whole.
+    warnings: warnings.map(({ code, message }) => ({ code, message: oneLine(message) })),
+    pages: pages.length,
+    steps: steps.map((step) => ({
+      id: step.id,
+      title: step.title,
+      intent: oneLine(step.detail, INTENT_MAX_CHARS),
+      page: pageOf.get(step.id) ?? 1
+    })),
+    // The definition of done by its requirements: what an agent is held to is never a thing to fetch later. Each
+    // item's check and the steps it covers are on page 1.
+    ...checklist === void 0 ? {} : { checklist: checklist.map(({ id, requirement }) => ({ id, requirement })) }
+  };
+}
+var FETCH_STEPS = Object.freeze({
+  tool: "everfur_plan_integration",
+  with: "the same arguments plus plan_id and page, for page 1 to pages",
+  returns: "the steps in full, file bodies included; page 1 also detection, warnings and checklist in full, and the principles",
+  when: "every page before any command runs or any file is written, since the plan's own steps change the project"
+});
+function isPlanDocument(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.steps);
+}
+function summarizeRefusal(result) {
+  const error = result.document["error"];
+  const plan = error?.details?.["plan"];
+  if (error === void 0 || !isPlanDocument(plan)) return result;
   return {
     isError: true,
-    document: { ...result, ok: false, error, failed_precondition: error.code, message: error.message }
+    document: { ...result.document, error: { ...error, details: { ...error.details, plan: summarizePlan(plan) } } }
+  };
+}
+function stepPage(plan, requested, envelope) {
+  const wanted = new Set(requested);
+  const selected = plan.steps.filter((step) => wanted.has(step.id));
+  const page = [];
+  let bytes = byteLength(JSON.stringify({ ...envelope, steps: [], remaining_steps: selected.map((step) => step.id) }));
+  for (const step of selected) {
+    const size = byteLength(JSON.stringify(step)) + 1;
+    if (page.length > 0 && bytes + size > PLAN_STEPS_BUDGET_BYTES) break;
+    page.push(step);
+    bytes += size;
+  }
+  return { page, remaining: selected.slice(page.length).map((step) => step.id) };
+}
+function numberedPage(plan, number, envelope) {
+  const pages = pagesOf(plan);
+  const steps = pages[number - 1];
+  if (steps === void 0) {
+    return refusal(
+      "UNKNOWN_PLAN_PAGE",
+      `This plan has ${pages.length === 1 ? "1 page" : `${pages.length} pages`}, so there is no page ${number}. Pages run from 1 to the summary's pages.`,
+      { page: number, pages: pages.length, plan_id: envelope["plan_id"] }
+    );
+  }
+  return {
+    isError: false,
+    document: {
+      ...envelope,
+      page: number,
+      pages: pages.length,
+      ...number < pages.length ? { next_page: number + 1 } : {},
+      ...number === 1 ? preambleOf(plan) : {},
+      steps
+    }
+  };
+}
+function planOnTheWire(result, request) {
+  if (result.isError) return summarizeRefusal(result);
+  const { plan, ...rest } = result.document;
+  if (!isPlanDocument(plan)) return result;
+  const planId = planIdOf(plan);
+  if (request.page !== void 0 && request.steps !== void 0) {
+    return refusal(
+      "UNKNOWN_PLAN_PAGE",
+      "page and steps were both given. Ask for a page of the summary with page, or for steps by id with steps, not both.",
+      { page: request.page, steps: request.steps, plan_id: planId }
+    );
+  }
+  if (request.plan_id !== void 0 && request.plan_id !== planId) {
+    return refusal(
+      "PLAN_CHANGED",
+      `These arguments now produce plan ${planId}, not plan ${request.plan_id}. A plan_id stands for the plan's steps, the arguments it was asked with and the contract it was built from, so one of three things changed since the call that returned it: the arguments differ from that call, the project the plan reads changed in a way that changes a step (as a command run or a file written from the plan can), or the contract changed. The same call without plan_id, page and steps returns the summary of the current plan.`,
+      { plan_id: request.plan_id, current_plan_id: planId }
+    );
+  }
+  const envelope = { ...rest, plan_id: planId };
+  if (request.page !== void 0) return numberedPage(plan, request.page, envelope);
+  if (request.steps === void 0) {
+    return { isError: false, document: { ...envelope, plan: summarizePlan(plan), fetch_steps: FETCH_STEPS } };
+  }
+  const known = new Set(plan.steps.map((step) => step.id));
+  const unknown = [...new Set(request.steps)].filter((id) => !known.has(id));
+  if (unknown.length > 0) {
+    return refusal(
+      "UNKNOWN_PLAN_STEP",
+      "One or more step ids are not steps of this plan. The ids it has are listed in details.steps.",
+      { unknown, plan_id: planId, steps: plan.steps.map((step) => step.id) }
+    );
+  }
+  const { page, remaining } = stepPage(plan, request.steps, envelope);
+  return {
+    isError: false,
+    document: { ...envelope, steps: page, ...remaining.length === 0 ? {} : { remaining_steps: remaining } }
   };
 }
-var ERROR_BODY_SCHEMA = z.object({
-  code: z.enum(Object.keys(REFUSAL_POLICY)).describe("Stable refusal code. The message beside it is prose for the developer and may change; the code does not."),
-  message: z.string().describe("What went wrong, for the developer."),
-  retryable: z.boolean().describe("Whether the same call, unchanged, can succeed later."),
-  next_action: z.enum(NEXT_ACTIONS).describe("What to do next, from a closed vocabulary."),
-  request_id: z.string().nullable().describe("The request id of the Everfur call that failed, when there was one."),
-  docs_path: z.string().nullable().describe("An MCP resource of this server that explains the refusal, or null."),
-  details: z.object({}).passthrough().describe("The facts specific to this refusal.")
-}).passthrough();
-var ENVELOPE_SHAPE = {
-  ok: z.boolean().describe("True when the tool did what was asked."),
-  error: ERROR_BODY_SCHEMA.optional().describe("Present exactly when the result is an error."),
-  failed_precondition: z.string().optional().describe("DEPRECATED: mirrors error.code for 0.3.x callers."),
-  message: z.string().optional().describe("DEPRECATED: mirrors error.message for 0.3.x callers.")
-};
 
 // src/mcp/tools.ts
 var DEFAULT_VERIFY_USER_REF = "everfur-mcp-verify";
@@ -230,7 +317,18 @@ function clientFor(context, ports = {}) {
     })
   };
 }
-function supplyOverMcp(fact, space) {
+var IDENTITY_MODE_MEANING = Object.freeze({
+  anonymous: '"anonymous" (no backend, scoped to the device)',
+  "partner-user-ref": '"partner-user-ref" (your backend mints a session)',
+  "shopify-app-proxy": '"shopify-app-proxy" (a Shopify storefront; Shopify vouches for the signed-in customer and no partner backend mints)'
+});
+function identityModeList(options) {
+  const modes = options ?? ["anonymous", "partner-user-ref", "shopify-app-proxy"];
+  const described = modes.map((mode) => IDENTITY_MODE_MEANING[mode] ?? `"${mode}"`);
+  if (described.length === 1) return described[0];
+  return `${described.slice(0, -1).join(", ")}${described.length > 2 ? "," : ""} or ${described[described.length - 1]}`;
+}
+function supplyOverMcp(fact, space, options = null, detection = null) {
   switch (fact) {
     case "decisionTrees":
       return "pass `contract_path` (a contract-public projection), or set EVERFUR_CONTRACT_PUBLIC in the server environment, or unset both so the contract is fetched with EVERFUR_DOCS_KEY";
@@ -241,21 +339,55 @@ function supplyOverMcp(fact, space) {
       return `${choices}. Which surfaces to build is the developer's choice, and nothing in the project decides it. The plan holds no credential, so it cannot know which of these the tenant is entitled to: everfur_verify_integration is the fail-closed check of what the tenant actually has`;
     }
     case "identityMode":
-      return 'pass `identity_mode`: "anonymous" (no backend, scoped to the device), "partner-user-ref" (your backend mints a session), or "shopify-app-proxy" (a Shopify storefront; Shopify vouches for the signed-in customer and no partner backend mints). It is the developer\'s choice, and it changes the integration shape';
+      return "pass `identity_mode`: " + identityModeList(options) + ". " + (options === null ? "It is the developer's choice, and it changes the integration shape" : "These are the only modes this refusal accepts; the mode it refused cannot be built here");
     case "sessionMintLanguage":
       return "pass `session_mint_language`, the language of the backend that will mint sessions and receive Everfur's webhooks (node, python, go or other-language as the contract names them; node gets generated files)";
     case "embedding":
       return 'pass `embedding`: "in-page" (the SDK\'s React components in the page) or "frame" (the loader and the Everfur-hosted iframe). Detected from react-dom when omitted';
     case "environment":
-      return 'pass `environment`: "staging" (https://api-staging.everfur.com/api/v1, where your sandbox tenant takes a pk_live_ key and reports livemode false; "test" names the same deployment) or "production" (https://api.everfur.com/api/v1). No deployed environment accepts a pk_test_ key. It is the developer\'s choice; production is never assumed';
+      return 'pass `environment`: "test" (your sandbox tenant on https://api.everfur.com/api/v1, a pk_test_ key, livemode false), "staging" (your sandbox tenant on https://api-staging.everfur.com/api/v1, for early access) or "production" (your live tenant on https://api.everfur.com/api/v1, a pk_live_ key). It is the developer\'s choice; production is never assumed';
     case "projectType":
-    case "packageManager":
+      if (detection !== null && isWorkspaceRootEvidence(detection.projectTypeEvidence)) {
+        return "describe the workspace package that holds the app, not the workspace root: pass its `project_root` when this is a local MCP, or its own `project_details` (with `workspace_root` for the root's lockfile) when this is a remote MCP; this fact is detected, not asserted";
+      }
       return "pass `project_root` when this is a local MCP, or the manifest and file-marker-only `project_details` when this is a remote MCP; this fact is detected, not asserted";
+    case "packageManager":
+      return "pass `project_root` when this is a local MCP, or the manifest and file-marker-only `project_details` when this is a remote MCP (for a workspace package, with `workspace_root` naming the workspace root's lockfile or packageManager field); this fact is detected, not asserted";
     default:
       return "supply this fact as a tool argument of the same name";
   }
 }
-var REMOTE_PROJECT_MARKER = z.enum([
+var FIXED_QUESTIONS = Object.freeze({
+  capabilities: "Which Everfur surfaces should this integration build?",
+  identityMode: "How does your app identify the person using it?",
+  sessionMintLanguage: "What language is the backend that will mint Everfur sessions?",
+  environment: "Which Everfur environment should the generated code target?",
+  embedding: "Should the Everfur surface render inside your page, or in an Everfur-hosted frame?"
+});
+var QUESTION_ROUND_INSTRUCTION = "One question round: every question in missing_facts goes to the developer in one message, in the order given, worded as given and with its options; a question with required_when belongs in the same message and is used only for the answers it names. The answers are the developer's alone. The next everfur_plan_integration call carries the same arguments plus every answer.";
+function questionOptions(fact, space) {
+  switch (fact) {
+    case "capabilities":
+      return space === null ? null : [...plannableCapabilities(space), ALL_CAPABILITIES];
+    case "identityMode":
+      return space === null ? null : space.choices(IDENTITY_TREE, IDENTITY_QUESTION);
+    case "sessionMintLanguage":
+      return space === null ? null : space.choices(SESSION_MINT_TREE, BACKEND_LANGUAGE_QUESTION);
+    case "environment":
+      return [...ENVIRONMENTS];
+    case "embedding":
+      return space === null ? ["in-page", "frame"] : space.choices(PLATFORM_TREE, WEB_EMBEDDING_QUESTION);
+    default:
+      return null;
+  }
+}
+function fixedQuestion(fact, space, admitted = null) {
+  const question = FIXED_QUESTIONS[fact];
+  if (question === void 0) return null;
+  const options = admitted ?? questionOptions(fact, space);
+  return options === null || options.length === 0 ? { question } : { question, options: [...options] };
+}
+var REMOTE_PROJECT_MARKERS = [
   "app.json",
   "app.config.js",
   "app.config.ts",
@@ -270,13 +402,39 @@ var REMOTE_PROJECT_MARKER = z.enum([
   "src/app/",
   "pages/",
   "src/pages/",
+  // A server directory, and a tsconfig in it the plan must never write over (hosted MCP web integration test, 2026-10-04).
+  "server/",
+  "server/tsconfig.json",
+  // An env template the app already has, which the plan adds to and never replaces (hosted MCP mobile test, 2026-10-04).
+  ".env.example",
   "package-lock.json",
   "npm-shrinkwrap.json",
   "pnpm-lock.yaml",
   "yarn.lock",
   "bun.lockb",
   "bun.lock"
-]);
+];
+function normalizeRemoteMarker(value) {
+  if (typeof value !== "string") return value;
+  const bare = value.trim().replace(/\\/g, "/").replace(/\/{2,}/g, "/").replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+  const listed = REMOTE_PROJECT_MARKERS;
+  if (listed.includes(`${bare}/`)) return `${bare}/`;
+  if (listed.includes(bare)) return bare;
+  return value;
+}
+var REMOTE_PROJECT_MARKER = z.preprocess(normalizeRemoteMarker, z.enum(REMOTE_PROJECT_MARKERS));
+var REMOTE_WORKSPACE_LOCKFILES = [
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "bun.lock"
+];
+var REMOTE_WORKSPACE_ROOT = z.object({
+  package_manager: z.string().min(1).max(128).optional(),
+  files: z.array(z.preprocess(normalizeRemoteMarker, z.enum(REMOTE_WORKSPACE_LOCKFILES))).max(6).optional()
+}).strict();
 var REMOTE_DEPENDENCY_MAP = z.record(z.string().min(1).max(128), z.string().min(1).max(256));
 var REMOTE_PROJECT_DETAILS = z.object({
   /** A display label only. It is never treated as a path by the remote MCP. */
@@ -292,8 +450,14 @@ var REMOTE_PROJECT_DETAILS = z.object({
     flutter_sdk: z.string().min(1).max(128).optional(),
     dependencies: REMOTE_DEPENDENCY_MAP.optional()
   }).strict().optional(),
-  /** Presence-only markers, from the fixed allowlist above. File contents are neither accepted nor read. */
+  /**
+   * Presence-only markers, from the fixed allowlist above. File contents are neither accepted nor read. `ios/` and
+   * `android/` are listed only when checked in: on an Expo app, directories .gitignore lists are continuous native
+   * generation's output, and the app is managed.
+   */
   files: z.array(REMOTE_PROJECT_MARKER).max(24).optional(),
+  /** For a package inside a workspace: the workspace root's packageManager field and lockfiles, presence only. */
+  workspace_root: REMOTE_WORKSPACE_ROOT.optional(),
   /** Optional resolved versions for the small dependency report; never needed to select an integration path. */
   installed_versions: REMOTE_DEPENDENCY_MAP.optional()
 }).strict();
@@ -319,9 +483,18 @@ function detectRemoteProject(details) {
     }));
   }
   for (const marker of details.files ?? []) {
-    const path = join(REMOTE_ROOT, marker);
+    const path = join(REMOTE_ROOT, marker.replace(/\/+$/, ""));
     if (marker.endsWith("/")) directories.add(path);
     else files.set(path, "");
+    for (let parent = dirname(path); parent.startsWith(`${REMOTE_ROOT}/`); parent = dirname(parent)) directories.add(parent);
+  }
+  if (details.workspace_root !== void 0) {
+    const workspaceRoot = dirname(REMOTE_ROOT);
+    files.set(join(workspaceRoot, "package.json"), JSON.stringify({
+      workspaces: [basename(REMOTE_ROOT)],
+      packageManager: details.workspace_root.package_manager
+    }));
+    for (const lockfile of details.workspace_root.files ?? []) files.set(join(workspaceRoot, lockfile), "");
   }
   for (const [name, version] of Object.entries(details.installed_versions ?? {})) {
     files.set(join(REMOTE_ROOT, "node_modules", ...name.split("/"), "package.json"), JSON.stringify({ version }));
@@ -376,7 +549,20 @@ function planDetection(args) {
       )
     };
   }
-  return args.project_details === void 0 ? { ok: true, detection: detectProject(nodeFileSystem, args.project_root) } : { ok: true, detection: detectRemoteProject(args.project_details) };
+  if (args.project_details !== void 0) return { ok: true, detection: detectRemoteProject(args.project_details) };
+  const root = args.project_root;
+  const problem = !isAbsolute(root) ? "it is not an absolute path" : !nodeFileSystem.isDirectory(root) ? "no readable directory exists at it" : null;
+  if (problem !== null) {
+    return {
+      ok: false,
+      result: refusal(
+        "LOCAL_PATH_NOT_READABLE",
+        `project_root cannot be read: ${problem}. Pass the absolute path of the application root on the machine this server runs on, or describe the project with \`project_details\` instead.`,
+        { arguments: ["project_root"], project_root: root, next_action: "fix_arguments" }
+      )
+    };
+  }
+  return { ok: true, detection: detectProject(nodeFileSystem, root) };
 }
 var THEME_SOURCE_MAX_BYTES = 256 * 1024;
 var PLAN_INPUT_SHAPE = {
@@ -386,13 +572,14 @@ var PLAN_INPUT_SHAPE = {
     "For a remote MCP: the text of the project's tailwind.config.{js,ts}, the CSS that declares its theme (a Tailwind v4 @theme block or :root custom properties), or a React Native theme or colours file, so the plan can match the generated surface to the project's own theme. Read statically and never executed. With project_root the project is read from disk instead; this argument, when given, wins. The plan refuses to guess a theme it cannot read and names the missing facts in its match-theme step."
   ),
   capabilities: z.array(CAPABILITY).optional().describe(
-    'Which Everfur capabilities this integration uses, as the contract names them. The ids the contract can plan today are "chat", "entitlements", "events", "notifications", "photo", "records", "records-clinic" and "televet"; "animations", "records-push", "records-transfer", "server-pets" and "video" are blocked today and a plan refuses them with the reason. Pass ["all"] for every plannable capability. The loaded contract is the authority: an UNKNOWN_OPTION refusal lists its exact ids. The plan holds no credential, so everfur_verify_integration (not this tool) is the fail-closed check of what the tenant actually has. Omit if unknown; the tool will refuse and list the ids.'
+    'Which Everfur capabilities this integration uses, as the contract names them. The ids the contract can plan today are "chat", "entitlements", "events", "notifications", "photo", "records", "records-clinic" and "televet"; "animations", "records-push", "records-transfer", "server-pets" and "video" are blocked today and a plan refuses them with the reason. Pass ["all"] for every plannable capability. The loaded contract is the authority: an UNKNOWN_OPTION refusal lists its exact ids. The plan holds no credential, so everfur_verify_integration (not this tool) is the fail-closed check of what the tenant actually has. The native setup an in-app vet call needs (the Daily modules, an Expo config plugin, a clean prebuild, camera and microphone declarations, and a warning naming the missing-native-module error Expo Go produces) is planned only when the generated React Native file mounts that call; a plan whose file mounts only the vet visit button installs none of it. Omit if unknown; the tool will refuse and list the ids.'
   ),
   identity_mode: IDENTITY_MODE.optional().describe('anonymous = no backend, scoped to the device. partner-user-ref = your backend mints a session against your own user id. shopify-app-proxy = a Shopify storefront, where Shopify vouches for the signed-in customer and no partner backend mints. "personalized" is accepted as an alias for partner-user-ref.'),
   session_mint_language: MINT_LANGUAGE.optional().describe("Backend language that will mint sessions. Only meaningful when identity_mode is partner-user-ref."),
   embedding: EMBEDDING.optional().describe(`For a web project only: "in-page" mounts the SDK's React components in the page (detected when package.json declares react-dom), "frame" includes the loader and renders the surface in an iframe on Everfur's origin (detected otherwise). Omit to accept what the project says; pass it to override.`),
-  environment: z.enum(ENVIRONMENTS).optional().describe(`The Everfur deployment the generated configuration targets: staging (your sandbox tenant, a pk_live_ key, livemode false; "test" names the same deployment) or production. Required for a plan that writes code; never assumed. Ask the developer. On the Everfur-hosted server an omitted environment is the connected tenant's, and one naming a different host is refused (ENVIRONMENT_MISMATCH).`),
-  contract_path: z.string().optional().describe("Path to a contract-public projection. Defaults to EVERFUR_CONTRACT_PUBLIC, then to the contract fetched from the Everfur API with EVERFUR_DOCS_KEY.")
+  environment: z.enum(ENVIRONMENTS).optional().describe("The Everfur deployment the generated configuration targets: test (your sandbox tenant on the production API, a pk_test_ key, livemode false), staging (your sandbox tenant on the staging API, for early access) or production (your live tenant, a pk_live_ key). Required for a plan that writes code; never assumed. Ask the developer. On the Everfur-hosted server an omitted environment is the connected tenant's, one naming a different host is refused (ENVIRONMENT_MISMATCH), and one naming a tenant mode the connected tenant does not have is refused (ENVIRONMENT_MODE_MISMATCH)."),
+  contract_path: z.string().optional().describe("Path to a contract-public projection. Defaults to EVERFUR_CONTRACT_PUBLIC, then to the contract fetched from the Everfur API with EVERFUR_DOCS_KEY."),
+  ...PLAN_STEPS_INPUT_SHAPE
 };
 var HOSTED_PLAN_INPUT_SHAPE = {
   project_details: REMOTE_PROJECT_DETAILS.optional().describe("A safe projection of the project: package dependencies, package manager, and fixed file-presence markers. Never source files, env files, or credentials; this server reads no path."),
@@ -403,9 +590,11 @@ var HOSTED_PLAN_INPUT_SHAPE = {
   identity_mode: PLAN_INPUT_SHAPE.identity_mode,
   session_mint_language: PLAN_INPUT_SHAPE.session_mint_language,
   embedding: PLAN_INPUT_SHAPE.embedding,
+  // Owner-approved 2026-10-01 (production sandbox plan section 10: the CLI environment text).
   environment: PLAN_INPUT_SHAPE.environment.describe(
-    `The Everfur deployment the generated configuration targets: staging (the sandbox tenant, a pk_live_ key, livemode false; "test" names the same deployment) or production. Omitted, the plan targets the connected tenant's deployment; one naming a different host than the connected tenant's is refused (ENVIRONMENT_MISMATCH).`
-  )
+    "The Everfur deployment the generated configuration targets: test (the sandbox tenant on the production API, a pk_test_ key, livemode false; for a live tenant, its paired sandbox), staging (the sandbox tenant on the staging API, for early access) or production (the live tenant, a pk_live_ key). Omitted, the plan targets the connected tenant's deployment and mode; one naming a different host than the connected tenant's is refused (ENVIRONMENT_MISMATCH), and one naming a mode it does not have is refused (ENVIRONMENT_MODE_MISMATCH)."
+  ),
+  ...PLAN_STEPS_INPUT_SHAPE
 };
 function apiHostOf(apiBaseUrl) {
   try {
@@ -425,28 +614,81 @@ function environmentOfApi(apiBaseUrl) {
 function hostedEnvironment(requested, context) {
   if (context.credentialSource !== "hosted") return { ok: true, environment: requested, fromTenant: false };
   const connectedApi = context.env[BASE_URL_ENV_VAR];
-  const connected = environmentOfApi(connectedApi);
-  if (connected === null) return { ok: true, environment: requested, fromTenant: false };
+  const deployment = environmentOfApi(connectedApi);
+  if (deployment === null) return { ok: true, environment: requested, fromTenant: false };
+  const mode = context.tenantMode ?? null;
+  const connected = deployment === "production" && mode !== null && !mode.livemode ? "test" : deployment;
   if (requested === null) return { ok: true, environment: connected, fromTenant: true };
   const requestedApi = API_BASE_URL_BY_ENVIRONMENT[requested];
-  if (apiHostOf(requestedApi) === apiHostOf(API_BASE_URL_BY_ENVIRONMENT[connected])) {
-    return { ok: true, environment: requested, fromTenant: false };
-  }
   const requestedHost = apiHostOf(requestedApi) ?? requestedApi;
   const connectedHost = apiHostOf(connectedApi ?? "") ?? String(connectedApi);
+  if (apiHostOf(requestedApi) !== apiHostOf(API_BASE_URL_BY_ENVIRONMENT[deployment])) {
+    return {
+      ok: false,
+      result: refusal(
+        "ENVIRONMENT_MISMATCH",
+        `This server is connected to a tenant on ${connectedHost} (${connected}), but environment "${requested}" targets ${requestedHost}. A plan for ${requestedHost} would carry a key that host does not know, and every request would answer 401. Which of the two was meant is the developer's to say.`,
+        {
+          environment: requested,
+          requested_host: requestedHost,
+          connected_host: connectedHost,
+          connected_environment: connected,
+          how_to_fix: [
+            `omit environment to plan for the connected tenant on ${connectedHost}`,
+            `or connect the editor to the Everfur MCP server of the ${requested} environment and plan there`
+          ]
+        }
+      )
+    };
+  }
+  const modeMismatch = mode !== null && (requested === "production" && !mode.livemode || requested === "test" && deployment === "production" && mode.livemode && !mode.paired);
+  if (!modeMismatch) return { ok: true, environment: requested, fromTenant: false };
+  const needs = requested === "production" ? "a live tenant, and the connected tenant is a sandbox" : "a sandbox tenant, or a live tenant with a paired sandbox, and the connected tenant is live with no paired sandbox";
   return {
     ok: false,
     result: refusal(
-      "ENVIRONMENT_MISMATCH",
-      `This server is connected to a tenant on ${connectedHost} (${connected}), but environment "${requested}" targets ${requestedHost}. A plan for ${requestedHost} would carry a key that host does not know, and every request would answer 401. Which of the two was meant is the developer's to say.`,
+      "ENVIRONMENT_MODE_MISMATCH",
+      `Environment "${requested}" needs ${needs}. Test and production share ${connectedHost}, so the tenant's mode, not the host, decides which one a plan is for. Which was meant is the developer's to say.`,
       {
         environment: requested,
-        requested_host: requestedHost,
         connected_host: connectedHost,
         connected_environment: connected,
+        tenant_livemode: mode.livemode,
+        test_mode_paired: mode.paired,
+        how_to_fix: [
+          `omit environment to plan for the connected tenant (${connected})`,
+          requested === "production" ? "or connect the editor with the live tenant and plan there" : "or connect the editor with the sandbox tenant, or pair this live tenant with one, and plan there"
+        ]
+      }
+    )
+  };
+}
+async function localTenantMode(environment, context, ports) {
+  if (context.credentialSource === "hosted") return { ok: true, warning: null };
+  const check = await checkTenantMode({
+    env: context.env,
+    environment,
+    transport: ports.transport ?? fetchTransport,
+    clock: ports.clock ?? systemClock
+  });
+  if (check.kind === "not_checked") return { ok: true, warning: check.warning };
+  if (check.kind !== "mismatch" || environment === null) return { ok: true, warning: null };
+  const host = apiHostOf(API_BASE_URL_BY_ENVIRONMENT[environment]) ?? API_BASE_URL_BY_ENVIRONMENT[environment];
+  const needs = environment === "production" ? "a live tenant" : "a sandbox tenant";
+  const has = check.livemode ? "a live tenant (livemode true)" : "a sandbox tenant (livemode false)";
+  const other = check.livemode ? "production" : "test";
+  return {
+    ok: false,
+    result: refusal(
+      "ENVIRONMENT_MODE_MISMATCH",
+      `Environment "${environment}" needs ${needs}, and the ${PARTNER_KEY.envVar} in this server's environment belongs to ${has}. Test and production share ${host}, so the tenant's mode, not the host, decides which one a plan is for. Which was meant is the developer's to say.`,
+      {
+        environment,
+        connected_host: host,
+        tenant_livemode: check.livemode,
         how_to_fix: [
-          `omit environment to plan for the connected tenant on ${connectedHost}`,
-          `or connect the editor to the Everfur MCP server of the ${requested} environment and plan there`
+          `pass environment "${other}" to plan for the tenant of this server's ${PARTNER_KEY.envVar}`,
+          `or set ${PARTNER_KEY.envVar} in this server's environment to the publishable key of the tenant you meant`
         ]
       }
     )
@@ -457,6 +699,8 @@ async function planIntegrationTool(args, context, ports = {}) {
   if (detected.ok === false) return detected.result;
   const environment = hostedEnvironment(args.environment ?? null, context);
   if (environment.ok === false) return environment.result;
+  const mode = await localTenantMode(environment.environment, context, ports);
+  if (mode.ok === false) return mode.result;
   const contractPath = args.contract_path ?? context.env["EVERFUR_CONTRACT_PUBLIC"] ?? null;
   let load;
   if (contractPath === null) {
@@ -489,7 +733,9 @@ async function planIntegrationTool(args, context, ports = {}) {
     environment: environment.environment,
     space,
     cliVersion: CLI_VERSION,
-    ...theme === void 0 ? {} : { theme }
+    ...theme === void 0 ? {} : { theme },
+    // The hosted server knows whether a live tenant has a paired sandbox, which decides how a live plan is verified.
+    ...context.credentialSource === "hosted" && context.tenantMode?.livemode === true ? { tenantPairedSandbox: context.tenantMode.paired } : {}
   };
   const plan = planIntegration(input);
   if (plan.platformBlock) {
@@ -514,13 +760,18 @@ async function planIntegrationTool(args, context, ports = {}) {
       "UNDERSPECIFIED_INTEGRATION",
       "This plan cannot be produced without the facts below. Each one is the developer's to answer, and none is guessed here.",
       {
+        ask: QUESTION_ROUND_INSTRUCTION,
         missing_facts: plan.missingFacts.map((fact) => ({
           fact: fact.fact,
+          ...fixedQuestion(fact.fact, space, fact.options ?? null) ?? {},
           why: fact.reason,
-          how_to_supply: supplyOverMcp(fact.fact, space),
+          how_to_supply: supplyOverMcp(fact.fact, space, fact.options ?? null, detected.detection),
           // The CLI's own phrasing, kept so the two surfaces are visibly the same refusal and a partner
           // moving between them recognises it.
-          how_to_supply_via_cli: fact.supplyWith
+          how_to_supply_via_cli: fact.supplyWith,
+          // A fact needed only for some answers to another missing fact, asked in the same round (one question round,
+          // timed integration run 2026-09-26): ask it beside that fact, and it is unused for any other answer.
+          ...fact.requiredWhen === void 0 ? {} : { required_when: { fact: fact.requiredWhen.fact, one_of: [...fact.requiredWhen.oneOf] } }
         })),
         // Everything detection already knows, so the agent does not learn it only after the round trip.
         warnings: plan.warnings,
@@ -538,21 +789,35 @@ async function planIntegrationTool(args, context, ports = {}) {
       { blocked: plan.blocked, warnings: plan.warnings, plan, next_call: null }
     );
   }
+  const ready = mode.warning === null ? plan : { ...plan, warnings: [...plan.warnings, mode.warning] };
   return {
     isError: false,
-    document: { ok: true, plan, ...environment.fromTenant ? { environment_source: "connected_tenant" } : {} }
+    document: { ok: true, plan: ready, ...environment.fromTenant ? { environment_source: "connected_tenant" } : {} }
   };
 }
 var PLAN_OUTPUT_SHAPE = {
   ...ENVELOPE_SHAPE,
-  plan: z.object({}).passthrough().optional().describe("The integration plan, shaped by everfur://schema/plan.v1. Present when ok is true."),
+  plan_id: z.string().optional().describe("A digest of the plan's steps, the arguments it was asked with and the contract it was built from. Present when ok is true."),
+  plan: z.object({}).passthrough().optional().describe("The plan summary (kind everfur.plan.summary, summaryVersion 2): the goal, detection, what was supplied, each warning by its first sentence, every step by its id, title, one-line intent and page, the number of pages, and the checklist's requirements. Present when ok is true and neither page nor steps was given."),
+  fetch_steps: z.object({}).passthrough().optional().describe("With the summary: the call that returns its pages."),
+  page: z.number().int().optional().describe("With page: the page this response carries."),
+  pages: z.number().int().optional().describe("With page: how many pages the plan has."),
+  next_page: z.number().int().optional().describe("With page: the page to ask for next, absent on the last page."),
+  detected: z.object({}).passthrough().optional().describe("On page 1: what was detected in the project, in full, with the evidence for each fact."),
+  warnings: z.array(z.object({}).passthrough()).optional().describe("On page 1: every warning of the plan, in full."),
+  principles: z.array(z.object({}).passthrough()).optional().describe("On page 1: the principles of every decision tree the plan consulted, each by its title and the everfur://guide section that states it in full."),
+  checklist: z.array(z.object({}).passthrough()).optional().describe("On page 1: the definition of done in full, each requirement with the check that proves it and the steps it covers."),
+  steps: z.array(z.object({}).passthrough()).optional().describe("With page or steps: those steps in full, as everfur://schema/plan.v1 describes a step, each with the complete body of every file it writes."),
+  remaining_steps: z.array(z.string()).optional().describe("With steps: requested steps left out to keep this response small. The same call with steps set to these returns them."),
   environment_source: z.literal("connected_tenant").optional().describe("Present when environment was omitted on the Everfur-hosted server and the plan targets the connected tenant's deployment.")
 };
+var VERIFY_EMBEDDING = z.enum(["in-page", "frame"]);
 var VERIFY_INPUT_SHAPE = {
   user_ref: z.string().optional().describe("End-user id to mint the test session for. Defaults to a CLI-owned value."),
   identity_mode: z.enum(VERIFY_IDENTITY_MODES).optional().describe(`The identity to verify with. "partner-user-ref" (the default): a signed session. "anonymous": the publishable key and a device session id derived from user_ref, exactly what an anonymous integration sends; nothing is minted, the verdict and the conversation list are read on that identity, and the tenant's sessions_required policy is reported (it refuses only a publishable-key caller that asserts x-everfur-user-ref; pure anonymous chat keeps working).`),
   attempts: z.number().int().min(1).max(20).optional().describe("How many times to read the verdict before concluding it is empty."),
-  origin: z.string().optional().describe("For a web integration: the page origin the surface is embedded on, e.g. https://shop.example.com. Adds the web checks: the CORS preflight, the embed fence for that origin, CORS exposure of X-Request-ID and Retry-After, whether the tenant requires signed sessions, and that the loader pairing with the configured API is reachable."),
+  origin: z.string().optional().describe("The web page origin, e.g. https://shop.example.com: the origin an in-page page calls the API from, or the one the frame renders on. Pass embedding beside it. Adds the web checks: the CORS preflight (of a widget request with the headers the SDK sends for in-page, of the fence request for a frame), CORS exposure of X-Request-ID and Retry-After, whether the tenant requires signed sessions, and, for a frame, the embed fence for that origin and the loader pairing with the configured API."),
+  embedding: VERIFY_EMBEDDING.optional().describe('With origin: how the page embeds the surface, the embedding the plan was built on (its supplied.embedding, else its detected.webEmbedding). "frame" runs every web check; "in-page" reports the embed fence and the loader N/A, since only the frame uses them, and still checks CORS and the session policy. Not named, every web check runs: only a page named in-page has the fence and the loader N/A, and a project read locally whose page includes the Everfur loader is checked as the frame it embeds.'),
   loader_url: z.string().optional().describe("With origin: the loader to probe instead of the one derived from EVERFUR_API_BASE_URL (https, or http on localhost). Without it a local or unrecognised API reports the loader check as not checked."),
   surfaces: z.array(z.enum(SURFACES)).optional().describe("Surfaces to exercise with the minted session. chat and records: the diagnostics reason, then a read on the session. televet: mints a real vet visit handoff, on a SANDBOX tenant only (never a live one); the one-time token is never returned. theme: the branding the verdict carries, judged with the SDK's own rules, merged with the theme prop everfur_plan_integration writes when project_root or theme_source is given. A surface Everfur has not switched on is reported GATED, not FAIL. With identity_mode anonymous, chat is read on the anonymous identity and records and televet are skipped: both take a signed session only."),
   project_root: z.string().optional().describe("Absolute path to the application root. Adds offline project checks: no partner secret key in source or client build output, no secret behind a NEXT_PUBLIC_/VITE_/EXPO_PUBLIC_ prefix, the secret read only by server code, 'use client' on Next.js App Router files importing the SDK, and that the env files name the same API host this verify ran against. File contents are never returned."),
@@ -565,6 +830,7 @@ var HOSTED_VERIFY_INPUT_SHAPE = {
   identity_mode: VERIFY_INPUT_SHAPE.identity_mode,
   attempts: VERIFY_INPUT_SHAPE.attempts,
   origin: VERIFY_INPUT_SHAPE.origin,
+  embedding: VERIFY_INPUT_SHAPE.embedding,
   loader_url: VERIFY_INPUT_SHAPE.loader_url.describe(
     "With origin: the loader to probe instead of the one that pairs with the connected tenant's API. On this server it is accepted only on an Everfur SDK host."
   ),
@@ -607,6 +873,8 @@ async function verifyIntegrationTool(args, context, ports = {}) {
     attempts: args.attempts ?? 3,
     pollDelayMs: 500,
     origin: origin.origin,
+    // Named, or read from project_root when one is given; otherwise the frame, which is what origin has always checked.
+    embedding: args.embedding ?? null,
     loaderUrl: loader.url,
     // The MCP server's documented environment holds no secret key, so it verifies only with a session the partner
     // backend minted (EVERFUR_SESSION_TOKEN) and never reads EVERFUR_PARTNER_SECRET_KEY, even when one is set.
@@ -624,7 +892,11 @@ async function verifyIntegrationTool(args, context, ports = {}) {
     // Anonymous verifies the path an anonymous integration uses: the publishable key and a derived session id.
     identityMode: args.identity_mode ?? "partner-user-ref",
     // A pasted theme wins over the project on disk, as it does for the plan; absent, the project's own (if any) is read.
-    ...args.theme_source === void 0 ? {} : { themeProp: themePropFor(detectThemeFromText(args.theme_source, "theme_source")) }
+    // A theme prop literal is read as the prop; a theme_source nothing could be read from fails the theme check.
+    ...args.theme_source === void 0 ? {} : (() => {
+      const read = themePropFromSource(args.theme_source, "theme_source");
+      return { themeProp: read.prop, themeSourceUnread: read.unread };
+    })()
   });
   const result = {
     ok: verification.status === "passed",
@@ -644,12 +916,12 @@ async function verifyIntegrationTool(args, context, ports = {}) {
 }
 var VERIFY_OUTPUT_SHAPE = {
   ...ENVELOPE_SHAPE,
-  status: z.enum(["passed", "failed", "incomplete"]).optional().describe("passed: every step PASS. incomplete: a step was skipped for a missing credential. failed: a step FAILED."),
+  status: z.enum(["passed", "failed", "incomplete"]).optional().describe("passed: every step PASS, GATED or N/A. incomplete: a step was skipped for a missing credential. failed: a step FAILED."),
   base_url: z.string().optional().describe("The API base URL the checks ran against."),
   steps: z.array(z.object({
     id: z.string(),
     title: z.string(),
-    result: z.enum(["PASS", "FAIL", "SKIP", "GATED"]),
+    result: z.enum(["PASS", "FAIL", "SKIP", "GATED", "N/A"]),
     reason: z.string(),
     requestId: z.string().nullable(),
     details: z.array(z.string())
@@ -768,19 +1040,34 @@ var HOSTED_EXPLAIN_ERROR_INPUT_SHAPE = {
 };
 async function explainErrorTool(args, context, ports = {}) {
   const code = args.code.trim();
+  const toolCode = toolCodeExplanation(code, CLI_VERSION);
+  if (toolCode !== null) {
+    const wire = await wireExplanationOf(code, args, context, ports);
+    if (wire === null) return { isError: false, document: { ok: true, explanation: toolCode } };
+    return { isError: false, document: { ok: true, explanation: withToolCodeBeside(code, wire) } };
+  }
   const offline = resolveOffline(code);
-  if (offline?.kind === "sdk_member") return offlineExplanation(offline);
+  if (offline?.kind === "sdk_member") return offlineExplanation(offline, "no_registry");
   const contractPath = args.contract_path ?? context.env["EVERFUR_CONTRACT_PUBLIC"] ?? null;
   let load;
   if (contractPath === null) {
     const fetched = await contractProviderFor(context, ports)();
     if (fetched.kind === "unavailable") {
-      if (offline !== null) return offlineExplanation(offline);
-      return contractRefusal(fetched, {
-        did_you_mean: offlineSuggestions(code),
-        case_sensitive: true,
-        searched: { source: "the SDK taxonomy and the SDK contract table this CLI carries", codes: knownCodes(null).length }
-      });
+      const resolved = resolveWithoutRegistry(code);
+      if (resolved.kind !== "unknown") return offlineExplanation(resolved, "no_registry");
+      return refusal(
+        "UNKNOWN_ERROR_CODE",
+        `"${code}" is not a code this server knows, so its cause and whether a retry can help are unknown here. The shape of the string does not say, and the code the response carried may differ from this one. The live error registry was not read, and it can list a code the tables inside this server predate.`,
+        {
+          did_you_mean: resolved.suggestions,
+          case_sensitive: true,
+          searched: {
+            source: "the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, the CLI's error codes and the SDK's sub-enums this server carries",
+            codes: knownCodes(null).length
+          },
+          registry: { read: false, reason: fetched.message }
+        }
+      );
     }
     load = loadErrorRegistryFromContract(fetched.contract);
   } else {
@@ -805,7 +1092,7 @@ async function explainErrorTool(args, context, ports = {}) {
   const entry = load.registry.lookup(code);
   if (entry === null) {
     const fallback = resolveAfterRegistryMiss(code, load.registry);
-    if (fallback.kind !== "unknown") return offlineExplanation(fallback);
+    if (fallback.kind !== "unknown") return offlineExplanation(fallback, "registry_miss");
     return refusal(
       "UNKNOWN_ERROR_CODE",
       `"${code}" is not in the error registry, so its cause and whether a retry can help are unknown here. The shape of the string does not say, and the code the response carried may differ from this one.`,
@@ -818,7 +1105,9 @@ async function explainErrorTool(args, context, ports = {}) {
           codes: load.registry.codes.length,
           // The SDK taxonomy and the SDK contract table were searched too, so a reader knows the refusal is not
           // just "this one file does not have it".
-          with_sdk_tables: knownCodes(load.registry).length
+          with_sdk_tables: knownCodes(load.registry).length,
+          // Of them, the codes the tools on this server return (tool-codes.ts).
+          mcp_tool_codes: TOOL_CODES.length
         }
       }
     );
@@ -827,31 +1116,61 @@ async function explainErrorTool(args, context, ports = {}) {
     isError: false,
     document: {
       ok: true,
-      explanation: buildExplanationDocument({
-        entry,
-        contractPath: load.path,
-        digest: load.digest,
-        cliVersion: CLI_VERSION
-      })
+      explanation: {
+        ...buildExplanationDocument({
+          entry,
+          contractPath: load.path,
+          digest: load.digest,
+          cliVersion: CLI_VERSION
+        }),
+        ...registryAlsoIn(code)
+      }
     }
   };
 }
-function offlineExplanation(resolution) {
+async function wireExplanationOf(code, args, context, ports) {
+  const offline = resolveOffline(code);
+  if (offline !== null) return offlineDocument(offline, CLI_VERSION, "no_registry");
+  const contractPath = args.contract_path ?? context.env["EVERFUR_CONTRACT_PUBLIC"] ?? null;
+  let load;
+  if (contractPath === null) {
+    const fetched = await contractProviderFor(context, ports)();
+    if (fetched.kind === "unavailable") return null;
+    load = loadErrorRegistryFromContract(fetched.contract);
+  } else {
+    load = loadErrorRegistry(nodeFileSystem, contractPath);
+  }
+  if (load.kind !== "loaded") return null;
+  const entry = load.registry.lookup(code);
+  if (entry === null) return null;
+  return buildExplanationDocument({ entry, contractPath: load.path, digest: load.digest, cliVersion: CLI_VERSION });
+}
+function withToolCodeBeside(code, wire) {
+  const tool = toolCodeMeaning(code);
+  if (tool === null) return wire;
   return {
-    isError: false,
-    document: {
-      ok: true,
-      explanation: resolution.kind === "sdk_member" ? buildSdkExplanationDocument(resolution.code, CLI_VERSION) : buildContractTableExplanationDocument(resolution.row, CLI_VERSION)
+    ...wire,
+    collision: `"${code}" is both a code in the error registry and a code an Everfur MCP tool returns (${tool.tools.join(", ")}). This document explains the registry's code, the one a response from the Everfur API carries; the error.code of an everfur_* tool result is the tool code in mcpToolCode.`,
+    mcpToolCode: {
+      tools: [...tool.tools],
+      meaning: tool.meaning,
+      nextAction: tool.nextAction,
+      retryable: tool.retryable,
+      policyNextAction: tool.policyNextAction,
+      docsPath: tool.docsPath
     }
   };
 }
+function offlineExplanation(resolution, context) {
+  return { isError: false, document: { ok: true, explanation: offlineDocument(resolution, CLI_VERSION, context) } };
+}
 var EXPLAIN_ERROR_OUTPUT_SHAPE = {
   ...ENVELOPE_SHAPE,
   explanation: z.object({}).passthrough().optional().describe("The registry's explanation, shaped by everfur://schema/error-explanation.v1. Present when ok is true.")
 };
 var ACCESS_TOKEN_SHAPE = /^mcp_at_[0-9a-f]{64}$/;
 var CONTEXT_PATH = "/mcp/context";
-var CONTEXT_CACHE_TTL_MS = 6e4;
+var CONTEXT_CACHE_TTL_MS = 15e3;
 var REFUSAL_CACHE_TTL_MS = 3e4;
 var MAX_CACHE_ENTRIES = 1e4;
 function isAccessTokenShaped(raw) {
@@ -866,7 +1185,17 @@ function tokenBucketOf(presented) {
 }
 var MCP_SCOPE = "mcp:tools";
 var REVOKED_AUTHORIZATION_REMEDY = "the authorization was revoked or expired since it was verified; reconnect the editor to sign in again";
-var ACCEPT_CONTEXT_WITHOUT_RESOURCE = true;
+var ACCEPT_CONTEXT_WITHOUT_RESOURCE = false;
+var CONTEXT_WIRE_FIELDS = Object.freeze([
+  "tenant",
+  "user_id",
+  "publishable_key",
+  "api_base_url",
+  "scopes",
+  "expires_at",
+  "resource"
+]);
+Object.freeze([...CONTEXT_WIRE_FIELDS, "test"]);
 function canonicalResource(value) {
   let parsed;
   try {
@@ -878,6 +1207,23 @@ function canonicalResource(value) {
   while (path.endsWith("/")) path = path.slice(0, -1);
   return `${parsed.origin}${path}${parsed.search}${parsed.hash}`;
 }
+function parseTestMode(value) {
+  if (value === void 0 || value === null) return { ok: true, test: null };
+  if (!isJsonObject(value)) return { ok: false };
+  const slug = value["slug"];
+  const publishableKey = value["publishable_key"];
+  if (typeof slug !== "string" || slug.length === 0) return { ok: false };
+  if (publishableKey !== null && typeof publishableKey !== "string") return { ok: false };
+  if (value["livemode"] !== false) return { ok: false };
+  return {
+    ok: true,
+    test: Object.freeze({
+      slug,
+      publishableKey: publishableKey === null || publishableKey.length === 0 ? null : publishableKey,
+      livemode: false
+    })
+  };
+}
 function parseTenantContext(body) {
   if (!isJsonObject(body)) return null;
   const tenant = body["tenant"];
@@ -900,6 +1246,8 @@ function parseTenantContext(body) {
   if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string")) return null;
   if (typeof expiresAt !== "string" || Number.isNaN(Date.parse(expiresAt))) return null;
   if (resource !== void 0 && resource !== null && typeof resource !== "string") return null;
+  const test = parseTestMode(body["test"]);
+  if (!test.ok) return null;
   return Object.freeze({
     tenant: Object.freeze({ clientId, slug, livemode }),
     userId,
@@ -907,7 +1255,8 @@ function parseTenantContext(body) {
     apiBaseUrl,
     scopes: Object.freeze([...scopes]),
     expiresAt,
-    resource: typeof resource === "string" ? resource : null
+    resource: typeof resource === "string" ? resource : null,
+    test: test.test
   });
 }
 function createTtlCache(ttlMs, now, live) {
@@ -1345,6 +1694,13 @@ function registerResources(server, provider) {
 var TIMESTAMP = z.string();
 var COUNT = z.number().int().min(0);
 var TENANT = z.object({ client_id: z.string(), slug: z.string(), livemode: z.boolean() });
+var CONNECTED_TENANT = z.object({
+  slug: z.string(),
+  livemode: z.boolean(),
+  paired_sandbox_slug: z.string().nullable(),
+  environment: z.string(),
+  publishable_key_prefix: z.string().nullable()
+});
 var TENANT_STATUS = z.object({
   tenant: TENANT,
   mode: z.object({
@@ -1494,10 +1850,35 @@ var TENANT_STATUS_TOOL = {
   name: "everfur_get_tenant_status",
   description: "Read the connected tenant's status: its plan and limits, which features are on and which it may switch, live or test mode and its paired tenant, its embed origins, the capabilities its account holds, its publishable key's id and prefix (never the key), and its Televet return destination keys and booking lead. Read-only.",
   input: {},
-  output: { ...ENVELOPE_SHAPE, tenant_status: TENANT_STATUS.optional().describe("The status, as GET /mcp/tenant/status serves it.") },
+  output: {
+    ...ENVELOPE_SHAPE,
+    tenant_status: TENANT_STATUS.optional().describe("The status, as GET /mcp/tenant/status serves it."),
+    connected_tenant: CONNECTED_TENANT.optional().describe(
+      "When the status read is switched off for the tenant: which tenant is connected, from the sign-in itself."
+    ),
+    tenant_status_unavailable: z.object({ code: z.string(), message: z.string(), request_id: z.string().nullable() }).optional().describe("Why the status itself was not read, beside connected_tenant.")
+  },
   async run(_args, context) {
     const read = await readTenant(context, "status", "status", TENANT_STATUS);
-    return read.ok ? ok({ tenant_status: read.value }) : read.result;
+    if (read.ok) return ok({ tenant_status: read.value });
+    const error = read.result.document["error"];
+    const connected = context.connectedTenant ?? null;
+    if (connected === null || error?.code !== "TENANT_SURFACE_NOT_ENABLED") return read.result;
+    const deployment = environmentOfApi(connected.apiBaseUrl);
+    return ok({
+      connected_tenant: {
+        slug: connected.slug,
+        livemode: connected.livemode,
+        paired_sandbox_slug: connected.pairedSandboxSlug,
+        environment: deployment === "production" && !connected.livemode ? "test" : deployment ?? "unknown",
+        publishable_key_prefix: connected.publishableKeyPrefix
+      },
+      tenant_status_unavailable: {
+        code: "TENANT_SURFACE_NOT_ENABLED",
+        message: typeof error.message === "string" ? error.message : "",
+        request_id: typeof error.details?.request_id === "string" ? error.details.request_id : null
+      }
+    });
   }
 };
 var WEBHOOK_ENDPOINTS_TOOL = {
@@ -1746,9 +2127,9 @@ function sharedRules(options) {
   const hosted = options.sessionSource === "hosted";
   const project = hosted ? `- Describe the project with project_details (dependencies, package manager, file-presence markers; never source
   files or credentials). This server runs on Everfur's hosts and cannot read a path on my machine. To match the
-  surface to my site's theme, pass theme_source: the text of my tailwind config or the CSS that declares my colours.` : `- Describe the project with project_root when the MCP server runs beside the project, or with project_details
+  surface to my site's theme, pass theme_source: the text of my tailwind config or the CSS that declares my colors.` : `- Describe the project with project_root when the MCP server runs beside the project, or with project_details
   (dependencies, package manager, file-presence markers; never source files or credentials) for a remote MCP, plus
-  theme_source (the text of my tailwind config or the CSS that declares my colours) so the plan matches my theme.`;
+  theme_source (the text of my tailwind config or the CSS that declares my colors) so the plan matches my theme.`;
   const session = hosted ? `- Verification runs with a session this server obtains from the Everfur API for my sandbox tenant; on a live
   tenant the session step is GATED. Never ask me for a session, a key or a variable to set.` : "- Verification reads EVERFUR_SESSION_TOKEN, a short-lived session my backend minted; never ask for the secret key.";
   const keys = hosted ? "- Never put a key in a tool argument, a file you write, or a message. This server holds none of mine." : "- Never put a key in a tool argument, a file you write, or a message. Keys come from the environment.";
@@ -1761,39 +2142,73 @@ ${session}
   says the code is unknown, say so; do not explain it yourself.
 ${keys}`;
 }
+var PROMPT_DESCRIPTIONS = Object.freeze({
+  integrateWeb: "Plan, write, build and verify an Everfur integration in a web project.",
+  integrateReactNative: "Plan, write, typecheck and verify an Everfur integration in a React Native or Expo app.",
+  diagnoseIntegration: "Explain an error code, read diagnostics and verify the wire, before changing any code."
+});
+function verifyCall(embedding, origin) {
+  const given = origin === void 0 || origin.trim() === "" ? null : origin.trim();
+  const pageOrigin = (where) => given === null ? `\`origin\` set to ${where} (ask me for it)` : `\`origin\` set to ${JSON.stringify(given)}`;
+  switch (embedding?.trim()) {
+    case "in-page":
+      return `Call everfur_verify_integration with \`embedding\` "in-page" and ${pageOrigin("the page origin the SDK runs on")}: the page calls the API from that origin, so the CORS preflight, the exposure and the session policy apply, and the frame's own checks (its embed fence and its loader) are reported N/A.`;
+    case "frame":
+      return `Call everfur_verify_integration with \`embedding\` "frame" and ${pageOrigin("the page origin the frame renders on")}.`;
+    default:
+      return `Call everfur_verify_integration with \`embedding\` set to the embedding the plan was built on (its \`supplied.embedding\`, else its \`detected.webEmbedding\`: "in-page" or "frame") and ${pageOrigin("the page origin")}. With "in-page" the frame's own checks (the embed fence and the loader) are reported N/A; the CORS checks apply to both.`;
+  }
+}
 function integrateWebPrompt(args, options = {}) {
   const { origin, ...planArgs } = args;
-  const verifyWith = origin === void 0 || origin.trim() === "" ? "with `origin` set to the page origin the surface is embedded on (ask me for it)" : `with \`origin\` set to ${JSON.stringify(origin.trim())}`;
   return {
-    description: "Add Everfur to a web project: plan, write, build, verify.",
+    description: PROMPT_DESCRIPTIONS.integrateWeb,
     text: `Integrate Everfur into this web project. Follow these steps in order.
 ${knownArguments(planArgs)}
 1. Read everfur://guide/platform and everfur://guide/identity-mode.
-2. Call everfur_plan_integration. If it refuses with UNDERSPECIFIED_INTEGRATION, ask me each fact in
-   error.details.missing_facts, then call it again with my answers. Do not guess them.
+2. Call everfur_plan_integration. If it refuses with UNDERSPECIFIED_INTEGRATION, ask me the question of every fact in
+   error.details.missing_facts in one message, worded as given and with its options (a fact with required_when is
+   needed only for the answers it names: ask it beside them), then call it again with my answers. Do not guess them.
+   If the plan's match-theme step says the theme could not be read, do what it says: find this app's brand colors
+   in its own code (a Tailwind config, the CSS that declares its theme, or a React Native theme file) and call again
+   with that file's text as theme_source. Never pick a color.
 3. If it refuses with PLATFORM_NOT_SUPPORTED or CAPABILITIES_BLOCKED, tell me the reason and the owner from
    error.details and stop. Do not build around a blocked surface.
-4. Write exactly the files the plan's steps name and run the commands it gives, in order.
+4. Call everfur_plan_integration again with the same arguments plus plan_id and page, for page 1 to the summary's
+   pages, for every step's full detail, commands and file bodies (with steps instead of page, call again with steps
+   set to remaining_steps until none remain). Then write exactly the files the plan's steps name and
+   run the commands it gives, in order.
 5. Build the project and fix any build error before going on.
-6. Call everfur_verify_integration ${verifyWith}. Report each step's result with its request id.
+6. ${verifyCall(args.embedding, origin)} Report each step's result with its request id.
 7. If the capability verdict is empty, call everfur_diagnose and report the reason it gives per capability.
+8. Report every item of the plan's checklist with the result of its verify. The integration is done only when every
+   item holds.
 ${sharedRules(options)}`
   };
 }
 function integrateReactNativePrompt(args, options = {}) {
   return {
-    description: "Add Everfur to a React Native or Expo app: plan, write, typecheck, verify.",
+    description: PROMPT_DESCRIPTIONS.integrateReactNative,
     text: `Integrate Everfur into this React Native app. Follow these steps in order.
 ${knownArguments(args)}
 1. Read everfur://guide/platform and everfur://guide/identity-mode.
-2. Call everfur_plan_integration. If it refuses with UNDERSPECIFIED_INTEGRATION, ask me each fact in
-   error.details.missing_facts, then call it again with my answers. Do not guess them.
+2. Call everfur_plan_integration. If it refuses with UNDERSPECIFIED_INTEGRATION, ask me the question of every fact in
+   error.details.missing_facts in one message, worded as given and with its options (a fact with required_when is
+   needed only for the answers it names: ask it beside them), then call it again with my answers. Do not guess them.
+   If the plan's match-theme step says the theme could not be read, do what it says: find this app's brand colors
+   in its own code (a Tailwind config, the CSS that declares its theme, or a React Native theme file) and call again
+   with that file's text as theme_source. Never pick a color.
 3. If it refuses with PLATFORM_NOT_SUPPORTED or CAPABILITIES_BLOCKED, tell me the reason and the owner from
    error.details and stop. Do not build around a blocked surface.
-4. Write exactly the files the plan's steps name and run the install commands it gives, in order.
+4. Call everfur_plan_integration again with the same arguments plus plan_id and page, for page 1 to the summary's
+   pages, for every step's full detail, commands and file bodies (with steps instead of page, call again with steps
+   set to remaining_steps until none remain). Then write exactly the files the plan's steps name and
+   run the install commands it gives, in order.
 5. Typecheck the app and fix any error before going on.
 6. Call everfur_verify_integration. Report each step's result with its request id.
 7. If the capability verdict is empty, call everfur_diagnose and report the reason it gives per capability.
+8. Report every item of the plan's checklist with the result of its verify. The integration is done only when every
+   item holds.
 ${sharedRules(options)}`
   };
 }
@@ -1804,7 +2219,7 @@ What I see: ${args.symptom.trim()}
   const code = args.error_code?.trim() ? `call everfur_explain_error with the code ${JSON.stringify(args.error_code.trim())}` : "if a response carried an error code, call everfur_explain_error with that exact code";
   const requestId = args.request_id?.trim() ? ` The failing request id was ${JSON.stringify(args.request_id.trim())}; quote it in your report.` : "";
   return {
-    description: "Find out why an Everfur integration is not working, before changing any code.",
+    description: PROMPT_DESCRIPTIONS.diagnoseIntegration,
     text: `Diagnose my Everfur integration. Do not change any code until the cause is named.
 ${symptom}
 1. First, ${code}, and follow its retryable flag and next action.
@@ -1821,9 +2236,11 @@ function registerPrompts(server, provider, options = {}) {
   const capabilities = contractChoices(provider, CAPABILITIES_TREE, CAPABILITY_QUESTION);
   const identityModes = contractChoices(provider, IDENTITY_TREE, IDENTITY_QUESTION);
   const embeddings = contractChoices(provider, PLATFORM_TREE, WEB_EMBEDDING_QUESTION);
-  const projectRoot = z.string().optional().describe(
-    options.sessionSource === "hosted" ? "Not read by this hosted server, which cannot see the developer's disk; pass project_details to everfur_plan_integration instead." : "Absolute path to the project, for a local MCP. A remote MCP cannot read it; pass project_details to everfur_plan_integration instead."
-  );
+  const projectRoot = options.sessionSource === "hosted" ? {} : {
+    project_root: z.string().optional().describe(
+      "Absolute path to the project, for a local MCP. A remote MCP cannot read it; pass project_details to everfur_plan_integration instead."
+    )
+  };
   const capabilityList = () => completable(
     z.string().optional().describe("Comma-separated capabilities, as the contract names them."),
     completeList(capabilities)
@@ -1840,9 +2257,9 @@ function registerPrompts(server, provider, options = {}) {
     "integrate-web",
     {
       title: "Integrate Everfur into a web project",
-      description: "Plan, write, build and verify an Everfur integration in a web project.",
+      description: PROMPT_DESCRIPTIONS.integrateWeb,
       argsSchema: {
-        project_root: projectRoot,
+        ...projectRoot,
         capabilities: capabilityList(),
         identity_mode: identityMode(),
         embedding: completable(
@@ -1850,7 +2267,9 @@ function registerPrompts(server, provider, options = {}) {
           startingWith(embeddings)
         ),
         environment: environment(),
-        origin: z.string().optional().describe("The page origin the surface is embedded on, for verification.")
+        origin: z.string().optional().describe(
+          "The page origin, e.g. https://shop.example.com: where the SDK runs (embedding in-page) or where the frame renders (embedding frame). Verification passes it with the embedding and runs the CORS checks against it; with in-page the frame's own checks (the embed fence and the loader) are reported N/A."
+        )
       }
     },
     (args) => userMessage(integrateWebPrompt(args, options))
@@ -1859,9 +2278,9 @@ function registerPrompts(server, provider, options = {}) {
     "integrate-react-native",
     {
       title: "Integrate Everfur into a React Native app",
-      description: "Plan, write, typecheck and verify an Everfur integration in a React Native or Expo app.",
+      description: PROMPT_DESCRIPTIONS.integrateReactNative,
       argsSchema: {
-        project_root: projectRoot,
+        ...projectRoot,
         capabilities: capabilityList(),
         identity_mode: identityMode(),
         environment: environment()
@@ -1873,7 +2292,7 @@ function registerPrompts(server, provider, options = {}) {
     "diagnose-integration",
     {
       title: "Diagnose an Everfur integration",
-      description: "Explain an error code, read diagnostics and verify the wire, before changing any code.",
+      description: PROMPT_DESCRIPTIONS.diagnoseIntegration,
       argsSchema: {
         error_code: completable(
           z.string().optional().describe("The error code a response carried, exactly as it appeared."),
@@ -1919,6 +2338,7 @@ function frameOf(block) {
     if (typeof obj["status"] === "string") return { kind: `status:${obj["status"]}` };
     if (obj["error"] !== void 0 || typeof obj["code"] === "string") return { kind: "error" };
     if (obj["done"] === true) return { kind: "done" };
+    if (obj["metadata"] === true) return { kind: "metadata" };
     return { kind: "unknown" };
   } catch {
     return { kind: "malformed" };
@@ -2140,9 +2560,12 @@ async function sendTestMessage(args, env, ports = {}, identitySources = {}) {
       "This tool sends a REAL message and only runs against a sandbox tenant. This key resolves to a tenant reporting livemode true, or to a deployment that does not report livemode at all. Refusing: a test message landing in a tenant that holds real veterinary records is not recoverable by deleting it afterwards.",
       {
         livemode: body.livemode ?? null,
-        // A sandbox is a TENANT, not a key prefix or a deployment switch: every deployed environment issues a sandbox
-        // tenant an ordinary pk_live_ key, and its verdict reports livemode false (commands/plan/environment.ts).
-        how_to_fix: "Use the publishable key of a sandbox tenant (one created as a sandbox, for example with `everfur sandbox create`): it is issued a pk_live_ key like any tenant, and its entitlements report livemode false."
+        // A sandbox is a TENANT, and the verdict is the authority: a sandbox tenant is issued a pk_test_ key (EFBackend
+        // #1630), an older one may still carry pk_live_, and either way its verdict reports livemode false
+        // (commands/plan/environment.ts).
+        // `everfur sandbox create` is Everfur-internal (it needs an admin token), so it is no partner's remedy; the
+        // documented path is the partner docs' testing page (tester run, 2026-10-01).
+        how_to_fix: 'Use the publishable key of a sandbox tenant: its key starts pk_test_ (a sandbox created before pk_test_ keys may still carry pk_live_), and its entitlements report livemode false. How a sandbox is created, and how a live tenant reaches its paired sandbox, is in docs/partner/10-TESTING.md ("Your sandbox and your live tenant").'
       }
     );
   }
@@ -2300,10 +2723,21 @@ machine as the project, or with project_details (package dependencies, package m
 never source files or credentials) when this is a remote MCP that cannot read the project. The plan matches the
 generated surface to the project's own theme (a Tailwind v4 @theme block, tailwind.config, :root custom properties,
 a React Native theme file), read statically and never executed; a remote MCP passes that text as theme_source.
-When the theme cannot be read the plan says so in its match-theme step and never guesses one. It refuses
+When the theme cannot be read the plan says so in its match-theme step and never guesses one. A plan comes back as
+a summary with a plan_id and a number of pages (the goal, the detected facts, each step's id, title, one-line intent
+and page, and the checklist); call it again with the same arguments plus plan_id and page, for page 1 to pages, for
+the steps in full, with their commands and the complete body of each file, before writing them. Page 1 also carries
+the detection, the warnings and the checklist in full, and the principles. (The same arguments plus plan_id and steps,
+step ids, return those steps instead, a page at a time, and remaining_steps names the rest.) Fetch every page
+before any command runs or any file is written: each call recomputes the plan from the project, and the plan's own
+commands and files change it. everfur_plan_integration refuses
 underspecified input by naming exactly which facts are missing. When it refuses, ask the developer those specific questions and call it again. Do not guess the
 answers and do not proceed without them: an integration built on a guessed identity mode is wrong in a way
-that only shows up in production.
+that only shows up in production. Each missing fact carries a fixed question and its options: ask them all in one
+message, worded as given. When the plan's match-theme step says the theme could not be read, find the host app's
+brand colours in its own code as that step lists, pass the file's text as theme_source and plan again; never pick a
+colour. The tenant's console branding (partner console) is the other side of the theme. A ready plan carries a
+checklist: the integration is finished only when every item holds, each proved by its verify.
 
 Then everfur_verify_integration to exercise the real wire, and everfur_diagnose when a working integration
 stops returning capabilities. Verification uses EVERFUR_SESSION_TOKEN, a short-lived session the partner's backend
@@ -2313,7 +2747,7 @@ integration is verified with identity_mode anonymous instead: the publishable ke
 nothing minted.
 
 Whenever an Everfur response carries an error code, call everfur_explain_error with that code rather than
-explaining it yourself. Three naming families are live at once and
+explaining it yourself; that includes the error.code these tools return. Three naming families are live at once and
 one code is the default for four different HTTP statuses, so a code explained from the shape of its string
 produces a confident, wrong retry policy. If the tool says the code is unknown, say so; do not fill it in.
 
@@ -2330,7 +2764,7 @@ The documented environment is EVERFUR_DOCS_KEY, EVERFUR_API_BASE_URL, EVERFUR_PA
 EVERFUR_SESSION_TOKEN.`;
 function toContent(result) {
   return {
-    content: [{ type: "text", text: JSON.stringify(result.document, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(result.document) }],
     structuredContent: result.document,
     isError: result.isError
   };
@@ -2355,36 +2789,36 @@ var TOOL_DESCRIPTIONS = Object.freeze({
   })
 });
 var HOSTED_TOOL_DESCRIPTIONS = Object.freeze({
-  verify: "Exercise the real wire as the connected tenant: a short-lived session the Everfur API mints for a synthetic test user of a sandbox tenant, the entitlement verdict read with it, and the assertion that the verdict is not empty; optionally the chat, records, televet and theme surfaces and, with origin, the web checks. On a live tenant the signed session step is reported GATED. With identity_mode anonymous it verifies the anonymous path instead (the tenant's publishable key and a device session id derived for a synthetic test user), which is the read-only check a live tenant takes: GET requests only, with nothing minted and nothing written. Returns PASS/SKIP/FAIL/GATED per step with the request id of the call that produced it. Mints a session, and on a sandbox tenant only a real Televet handoff, so it is not read-only.",
+  verify: "Exercise the real wire as the connected tenant: a short-lived session the Everfur API mints for a synthetic test user of a sandbox tenant, the entitlement verdict read with it, and the assertion that the verdict is not empty; optionally the chat, records, televet and theme surfaces and, with origin and embedding, the web checks of the page (the frame's embed fence and loader are N/A for embedding in-page). On a live tenant with a paired sandbox the session is minted on that sandbox and the call uses its publishable key; on a live tenant with no pair the signed session step is reported GATED. With identity_mode anonymous it verifies the anonymous path instead (the tenant's publishable key and a device session id derived for a synthetic test user), which is the read-only check a live tenant takes: GET requests only, with nothing minted and nothing written. Returns PASS/SKIP/FAIL/GATED/N/A per step with the request id of the call that produced it. Mints a session, and on a sandbox tenant only a real Televet handoff, so it is not read-only.",
   diagnose: "Separate the four byte-identical causes of an empty entitlement verdict for the connected tenant, with its publishable key. Read-only. Reports honestly when the deployment does not serve the diagnostics route rather than relaying a bare 404. With bundle: true, returns one support bundle (SDK and CLI versions, contract digest, credential presence without values, and the diagnosis request id) whatever state the integration is in.",
-  sendTestMessage: "Send a REAL message and stream a real veterinary answer as a synthetic test user of the connected tenant, a SANDBOX tenant only: the session is one the Everfur API mints for everfur-verify- and a stable id derived from idempotency_key, and a live tenant is refused before anything is sent. Returns the answer plus a frame histogram, so a stream that died mid-answer is distinguishable from a short one. With pet_profile it registers a sandbox pet first so the answer is pet-aware. Calling again with the same idempotency_key reuses that conversation and returns the existing answer instead of sending a second message."
+  sendTestMessage: "Send a REAL message and stream a real veterinary answer as a synthetic test user of the connected tenant, a SANDBOX tenant only: the session is one the Everfur API mints for everfur-verify- and a stable id derived from idempotency_key, and a live tenant with no paired sandbox is refused before anything is sent (a paired one runs on its sandbox). Returns the answer plus a frame histogram, so a stream that died mid-answer is distinguishable from a short one. With pet_profile it registers a sandbox pet first so the answer is pet-aware. Calling again with the same idempotency_key reuses that conversation and returns the existing answer instead of sending a second message."
 });
 var EFFECT_HINTS = Object.freeze({
   reads: Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: true }),
-  writes_sandbox: Object.freeze({ readOnlyHint: false, destructiveHint: false, idempotentHint: false }),
-  writes_live: Object.freeze({ readOnlyHint: false, destructiveHint: false, idempotentHint: false }),
+  writes_sandbox: Object.freeze({ readOnlyHint: false, destructiveHint: true, idempotentHint: false }),
+  writes_live: Object.freeze({ readOnlyHint: false, destructiveHint: true, idempotentHint: false }),
   destroys_live: Object.freeze({ readOnlyHint: false, destructiveHint: true, idempotentHint: false })
 });
 var TOOL_DECLARATIONS = Object.freeze({
-  everfur_plan_integration: { title: "Plan an Everfur integration", effect: "reads" },
-  everfur_verify_integration: { title: "Verify the wire end to end", effect: "writes_sandbox" },
-  everfur_diagnose: { title: "Explain why a capability is unavailable", effect: "reads" },
-  everfur_explain_error: { title: "Explain an Everfur API error code", effect: "reads" },
-  everfur_send_test_message: { title: "Send a real message against a sandbox tenant", effect: "writes_sandbox" },
-  everfur_get_tenant_status: { title: "Read the tenant status", effect: "reads" },
-  everfur_list_webhook_endpoints: { title: "List webhook endpoints", effect: "reads" },
-  everfur_list_webhook_deliveries: { title: "List webhook deliveries", effect: "reads" },
-  everfur_get_webhook_delivery: { title: "Read one webhook delivery", effect: "reads" },
-  everfur_list_events: { title: "List emitted events", effect: "reads" },
-  everfur_get_usage_summary: { title: "Read the usage summary", effect: "reads" },
-  everfur_get_records_status_summary: { title: "Count records requests by status", effect: "reads" },
-  everfur_search_docs: { title: "Search the Everfur docs", effect: "reads" }
+  everfur_plan_integration: { title: "Plan an Everfur integration", effect: "reads", openWorld: false },
+  everfur_verify_integration: { title: "Verify the wire end to end", effect: "writes_sandbox", openWorld: true },
+  everfur_diagnose: { title: "Explain why a capability is unavailable", effect: "reads", openWorld: false },
+  everfur_explain_error: { title: "Explain an Everfur API error code", effect: "reads", openWorld: false },
+  everfur_send_test_message: { title: "Send a real message against a sandbox tenant", effect: "writes_sandbox", openWorld: false },
+  everfur_get_tenant_status: { title: "Read the tenant status", effect: "reads", openWorld: false },
+  everfur_list_webhook_endpoints: { title: "List webhook endpoints", effect: "reads", openWorld: false },
+  everfur_list_webhook_deliveries: { title: "List webhook deliveries", effect: "reads", openWorld: false },
+  everfur_get_webhook_delivery: { title: "Read one webhook delivery", effect: "reads", openWorld: false },
+  everfur_list_events: { title: "List emitted events", effect: "reads", openWorld: false },
+  everfur_get_usage_summary: { title: "Read the usage summary", effect: "reads", openWorld: false },
+  everfur_get_records_status_summary: { title: "Count records requests by status", effect: "reads", openWorld: false },
+  everfur_search_docs: { title: "Search the Everfur docs", effect: "reads", openWorld: false }
 });
 var TOOL_ANNOTATIONS = Object.freeze(
   Object.fromEntries(
     Object.entries(TOOL_DECLARATIONS).map(([name, declared]) => [
       name,
-      Object.freeze({ title: declared.title, ...EFFECT_HINTS[declared.effect], openWorldHint: true })
+      Object.freeze({ title: declared.title, ...EFFECT_HINTS[declared.effect], openWorldHint: declared.openWorld })
     ])
   )
 );
@@ -2431,18 +2865,20 @@ function buildServer(context, ports = {}, options = {}) {
     "everfur_plan_integration",
     {
       title: TOOL_ANNOTATIONS.everfur_plan_integration.title,
-      description: `Produce an integration plan for a project. REFUSES underspecified input by naming the missing facts rather than guessing them, and REFUSES a project shape the SDK ships no entry point for (PLATFORM_NOT_SUPPORTED) or a capability set the contract blocks outright (CAPABILITIES_BLOCKED). Read-only. ${describe.planContract}`,
+      description: `Produce an integration plan for a project. REFUSES underspecified input by naming the missing facts rather than guessing them, and REFUSES a project shape the SDK ships no entry point for (PLATFORM_NOT_SUPPORTED) or a capability set the contract blocks outright (CAPABILITIES_BLOCKED). Returns a small summary with a plan_id and a number of pages: the goal, the detected facts, each step's id, title, one-line intent and page, and the checklist. The same arguments plus plan_id and page (1 to pages) return that page: its steps in full, with their commands and the complete body of each file they write, and on page 1 the detection, warnings and checklist in full. With steps (step ids) instead of page, those steps come a page at a time and remaining_steps names the rest. Each call recomputes the plan from the project, which the plan's own commands and files change, so every page is fetched before any command runs or any file is written. Read-only. ${describe.planContract}`,
       inputSchema: argumentsSchema(PLAN_INPUT_SHAPE, HOSTED_PLAN_INPUT_SHAPE, readsLocalFiles),
       outputSchema: PLAN_OUTPUT_SHAPE,
       annotations: { ...TOOL_ANNOTATIONS.everfur_plan_integration }
     },
-    (args, extra) => run("everfur_plan_integration", args, extra.authInfo, (resolved) => planIntegrationTool(args, resolved, shared))
+    // The planner computes the full plan, as the CLI prints it; what the wire carries is its summary or the steps asked
+    // for (plan-wire.ts).
+    (args, extra) => run("everfur_plan_integration", args, extra.authInfo, async (resolved) => planOnTheWire(await planIntegrationTool(args, resolved, shared), args))
   );
   server.registerTool(
     "everfur_verify_integration",
     {
       title: TOOL_ANNOTATIONS.everfur_verify_integration.title,
-      description: hosted ? HOSTED_TOOL_DESCRIPTIONS.verify : "Mint a session, poll entitlements, and hard-assert the verdict is not empty; optionally exercise the chat, records, televet and theme surfaces and check the project on disk. With identity_mode anonymous it verifies the anonymous path instead (the publishable key and a derived session id, the conversation list, and whether the tenant requires signed sessions). Returns PASS/SKIP/FAIL/GATED per step with the request id of the call that produced it. Mints a real session, and on a sandbox tenant only a real Televet handoff, so it is not read-only; it sends no write to a live tenant.",
+      description: hosted ? HOSTED_TOOL_DESCRIPTIONS.verify : "Mint a session, poll entitlements, and hard-assert the verdict is not empty; optionally exercise the chat, records, televet and theme surfaces and check the project on disk. With identity_mode anonymous it verifies the anonymous path instead (the publishable key and a derived session id, the conversation list, and whether the tenant requires signed sessions). Returns PASS/SKIP/FAIL/GATED/N/A per step with the request id of the call that produced it. Mints a real session, and on a sandbox tenant only a real Televet handoff, so it is not read-only; it sends no write to a live tenant.",
       inputSchema: argumentsSchema(VERIFY_INPUT_SHAPE, HOSTED_VERIFY_INPUT_SHAPE, readsLocalFiles),
       outputSchema: VERIFY_OUTPUT_SHAPE,
       annotations: { ...TOOL_ANNOTATIONS.everfur_verify_integration }
@@ -2464,7 +2900,7 @@ function buildServer(context, ports = {}, options = {}) {
     "everfur_explain_error",
     {
       title: TOOL_ANNOTATIONS.everfur_explain_error.title,
-      description: `Explain a wire error code: cause, whether it is retryable, and the next action. Reads the registry from the contract. ${describe.explainContract} Needs no project. REFUSES a code the registry does not list, with near misses, rather than inventing an explanation from the shape of the string.`,
+      description: `Explain an error code: cause, whether it is retryable, and the next action. A wire code is read from the registry in the contract. ${describe.explainContract} The SDK's own codes (EverfurError and its closed sub-enums such as AttachmentErrorCode and VetVisitErrorReason), the diagnostics reason codes, the CLI's error codes and the error.code these tools return (VERIFICATION_FAILED, PLAN_CHANGED and the rest) are answered offline. Needs no project. REFUSES a code the registry does not list, with near misses, rather than inventing an explanation from the shape of the string.`,
       inputSchema: argumentsSchema(EXPLAIN_ERROR_INPUT_SHAPE, HOSTED_EXPLAIN_ERROR_INPUT_SHAPE, readsLocalFiles),
       outputSchema: EXPLAIN_ERROR_OUTPUT_SHAPE,
       annotations: { ...TOOL_ANNOTATIONS.everfur_explain_error }