@everfur/cli 0.1.0 → 0.2.1

package/dist/{chunk-67H43MI6.js → chunk-4UB26D67.js}

@@ -1,61 +1,7 @@
 #!/usr/bin/env node
-import { failureDetails, describeFailure, isJsonObject, CAPABILITY_QUESTION, CAPABILITIES_TREE, loadDecisionSpace, loadBundledDecisionSpace, detectProject, planIntegration, resolveContractPath, validateContractFile, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, runVerification, PARTNER_SECRET_KEY, loadErrorRegistry, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-KQZ6ZXL7.js';
+import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, offlineSuggestions, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, knownCodes, buildExplanationDocument, renderExplanation, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, buildSdkExplanationDocument, renderSdkExplanation, buildContractTableExplanationDocument, renderContractTableExplanation, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-KQICUK54.js';
 import { isAbsolute, resolve } from 'path';
 
-// src/cli/exit-codes.ts
-var ExitCode = Object.freeze({
-  /** The command produced a complete answer. */
-  OK: 0,
-  /** An unexpected internal failure. A bug in the CLI, or an unreadable filesystem. */
-  INTERNAL_ERROR: 1,
-  /** The invocation was malformed: unknown command, unknown flag, missing flag value. */
-  USAGE_ERROR: 2,
-  /** The CLI refused to guess. Required facts were missing; see `missingFacts`. */
-  UNDERSPECIFIED: 3,
-  /**
-   * A NAMED ARTIFACT was missing, unparseable, or failed shape validation against its JSON
-   * Schema. All three mean the same thing to a caller: a file this command was pointed at
-   * cannot be used, and a human has to look at that file.
-   *
-   * The wording was tightened from "failed shape validation" because `file_not_found` and
-   * `invalid_json` have always mapped here too, and a code whose documented meaning is
-   * narrower than its behaviour is a code CI branches on wrongly. What does NOT belong here is
-   * a bad INVOCATION: `--cwd /nope` is a usage error (2), because nothing was loaded.
-   */
-  INVALID_CONTRACT: 4,
-  /** A loaded artifact was well shaped but its digest did not match its content. */
-  DIGEST_MISMATCH: 5,
-  /**
-   * The API could not be reached, did not answer in time, or answered with a typed error.
-   * The invocation was fine and no local artifact is wrong: the far side is the problem, so a
-   * CI wrapper branching on this retries or pages rather than sending someone to edit a file.
-   */
-  REMOTE_FAILURE: 6,
-  /**
-   * `verify` completed and at least one step FAILED. Distinct from 6 because the wire worked:
-   * the CLI got answers and one of them was wrong, which is a report to read rather than an
-   * outage to retry. A run with no failures but a skipped step settles at 3, not here, because
-   * a skip means the operator did not supply enough to exercise that step.
-   */
-  VERIFICATION_FAILED: 7,
-  /**
-   * `sandbox create` provisioned a key, and the server offered no claim URL for its secret.
-   * The CLI will not print a raw secret, so it discarded the one it was handed unread. The key
-   * exists and nobody can use it; the human projection prints the revoke command.
-   */
-  SECRET_UNCLAIMABLE: 8,
-  /**
-   * `plan` was told everything it needed and NOTHING the caller asked for can be built: every
-   * capability named resolved to a BLOCKED terminal in the contract.
-   *
-   * Distinct from 3 because supplying another flag will not help, and distinct from 0 because
-   * no plan was produced. A CI wrapper branching on 3 prompts for more input, which would loop
-   * forever here; one branching on 9 reads the reason and the request path out of the document
-   * and escalates to a human, which is the only thing that resolves it.
-   */
-  BLOCKED: 9
-});
-
 // src/cli/format.ts
 function withNewline(body) {
   return body.length === 0 ? "" : `${body}
@@ -84,28 +30,31 @@ function known(space, treeId, questionId) {
   return choices.length === 0 ? null : choices;
 }
 function parseCapabilities(raw, space) {
-  if (raw === null) return { value: null, errors: [] };
+  if (raw === null) return { value: null, errors: [], all: false };
   const allowed = known(space, CAPABILITIES_TREE, CAPABILITY_QUESTION);
+  const supported = allowed === null ? null : [...allowed, ALL_CAPABILITIES];
   const tokens = raw.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
   if (tokens.length === 0) {
     return {
       value: null,
       errors: [
-        allowed === null ? "--capabilities was empty; name at least one capability" : `--capabilities was empty; name at least one of: ${allowed.join(", ")}`
-      ]
+        supported === null ? "--capabilities was empty; name at least one capability" : `--capabilities was empty; name at least one of: ${supported.join(", ")}`
+      ],
+      all: false
     };
   }
   const errors = [];
   const selected = /* @__PURE__ */ new Set();
   for (const token of tokens) {
-    if (allowed === null || allowed.includes(token)) {
+    if (supported === null || supported.includes(token)) {
       selected.add(token);
       continue;
     }
-    errors.push(`unknown capability "${token}"; supported: ${allowed.join(", ")}`);
+    errors.push(`unknown capability "${token}"; supported: ${supported.join(", ")}`);
   }
-  if (errors.length > 0) return { value: null, errors };
-  return { value: Object.freeze([...selected].sort()), errors: [] };
+  if (errors.length > 0) return { value: null, errors, all: false };
+  const expanded = expandCapabilities([...selected].sort(), space);
+  return { value: Object.freeze([...expanded.capabilities]), errors: [], all: expanded.expanded };
 }
 function parseChoice(raw, space, treeId, questionId, flag) {
   if (raw === null) return { value: null, errors: [] };
@@ -115,23 +64,29 @@ function parseChoice(raw, space, treeId, questionId, flag) {
   return { value: null, errors: [`unknown ${flag} "${raw}"; supported: ${allowed.join(", ")}`] };
 }
 var IDENTITY_ALIASES = Object.freeze({ personalized: "partner-user-ref" });
-function parseIdentityMode(raw, space) {
+function parseIdentityMode2(raw, space) {
   const normalized = raw === null ? null : IDENTITY_ALIASES[raw.trim()] ?? raw;
   return parseChoice(normalized, space, IDENTITY_TREE, IDENTITY_QUESTION, "identity mode");
 }
 function parseSessionMintLanguage(raw, space) {
   return parseChoice(raw, space, SESSION_MINT_TREE, BACKEND_LANGUAGE_QUESTION, "backend language");
 }
-function parseSuppliedFacts(capabilitiesRaw, identityRaw, backendRaw, space) {
+function parseEmbedding(raw, space) {
+  return parseChoice(raw, space, PLATFORM_TREE, WEB_EMBEDDING_QUESTION, "embedding");
+}
+function parseSuppliedFacts(capabilitiesRaw, identityRaw, backendRaw, space, embeddingRaw = null) {
   const capabilities = parseCapabilities(capabilitiesRaw, space);
-  const identity = parseIdentityMode(identityRaw, space);
+  const identity = parseIdentityMode2(identityRaw, space);
   const backend = parseSessionMintLanguage(backendRaw, space);
-  const errors = [...capabilities.errors, ...identity.errors, ...backend.errors];
+  const embedding = parseEmbedding(embeddingRaw, space);
+  const errors = [...capabilities.errors, ...identity.errors, ...backend.errors, ...embedding.errors];
   return Object.freeze({
     ok: errors.length === 0,
     capabilities: capabilities.value,
+    allCapabilities: capabilities.all,
     identityMode: identity.value,
     sessionMintLanguage: backend.value,
+    embedding: embedding.value,
     errors: Object.freeze(errors)
   });
 }
@@ -147,6 +102,23 @@ function renderDetected(document) {
   lines.push(...indent(detected.projectTypeEvidence, "                   - "));
   lines.push(`  package manager: ${detected.packageManager}`);
   lines.push(...indent(detected.packageManagerEvidence, "                   - "));
+  const theme = detected.theme ?? null;
+  if (theme !== null) {
+    if (theme.confidence === "low") {
+      lines.push(`  theme:           not read (${theme.source === "none" ? "no theme source found" : `${theme.source}, low confidence`})`);
+      lines.push(...indent(theme.missing, "                   - "));
+    } else {
+      const fields = Object.entries(theme.theme).map(([key, value]) => `${key} ${String(value)}`);
+      lines.push(`  theme:           ${theme.source}, ${theme.confidence} confidence`);
+      lines.push(...indent(fields, "                   - "));
+      lines.push(
+        ...indent(
+          theme.evidence.filter((entry) => entry.token !== null).map((entry) => `${entry.file}:${entry.line} ${entry.key} -> ${entry.token}`),
+          "                   read: "
+        )
+      );
+    }
+  }
   if (detected.dependencies.length === 0) {
     lines.push("  dependencies:    none of the relevant packages are declared");
     return lines;
@@ -247,7 +219,9 @@ function renderBlockedPlan(document) {
     lines.push(...contract);
   }
   lines.push("");
-  lines.push("No steps were produced. An install plan for a surface that answers 404 is not a smaller plan, it is a wrong one.");
+  lines.push(
+    document.platformBlock ? "No steps were produced. An install plan for a project shape the SDK has no entry point for is not a smaller plan, it is a wrong one." : "No steps were produced. An install plan for a surface that answers 404 is not a smaller plan, it is a wrong one."
+  );
   return lines.join("\n");
 }
 function renderReady(document) {
@@ -297,53 +271,6 @@ function renderPlan(document) {
   return renderReady(document);
 }
 
-// src/cli/outcome.ts
-function succeed(json, text) {
-  return Object.freeze({ exitCode: 0, json, text, stream: "stdout" });
-}
-function fail(exitCode, json, text) {
-  return Object.freeze({ exitCode, json, text, stream: "stderr" });
-}
-
-// src/cli/errors.ts
-var EXIT_FOR_CODE = Object.freeze({
-  usage_error: ExitCode.USAGE_ERROR,
-  unknown_command: ExitCode.USAGE_ERROR,
-  /**
-   * A credential the command needs is not exported. That is a bad INVOCATION of the same shape
-   * as a missing required flag, so it settles at 2 and the message names the variable. It is
-   * deliberately NOT 6: nothing was sent, so the far side is not implicated.
-   */
-  credential_missing: ExitCode.USAGE_ERROR,
-  /** `explain-error` was given a code the loaded registry does not list. A bad argument. */
-  unknown_error_code: ExitCode.USAGE_ERROR,
-  file_not_found: ExitCode.INVALID_CONTRACT,
-  invalid_json: ExitCode.INVALID_CONTRACT,
-  invalid_contract: ExitCode.INVALID_CONTRACT,
-  digest_mismatch: ExitCode.DIGEST_MISMATCH,
-  /**
-   * The three remote failures share exit 6 and stay distinct in the document, for the same
-   * reason `file_not_found` and `invalid_json` share 4: one branch for a wrapper, one action
-   * for an operator, and full detail for anything reading `error.code`.
-   */
-  remote_unreachable: ExitCode.REMOTE_FAILURE,
-  remote_error: ExitCode.REMOTE_FAILURE,
-  malformed_response: ExitCode.REMOTE_FAILURE,
-  internal_error: ExitCode.INTERNAL_ERROR
-});
-function exitCodeFor(code) {
-  return EXIT_FOR_CODE[code];
-}
-function errorOutcome(code, message, details = []) {
-  const document = {
-    schemaVersion: 1,
-    kind: "everfur.error",
-    error: { code, message, details }
-  };
-  const lines = [`error: ${message}`, ...details.map((detail) => `  ${detail}`)];
-  return fail(exitCodeFor(code), document, lines.join("\n"));
-}
-
 // src/http/outcome.ts
 var CODE_FOR_KIND = Object.freeze({
   network: "remote_unreachable",
@@ -358,187 +285,6 @@ function failureOutcome(failure, extraDetails = []) {
   ]);
 }
 
-// src/commands/diagnose/document.ts
-var DIAGNOSIS_SCHEMA_VERSION = 1;
-var DIAGNOSIS_DOCUMENT_KIND = "everfur.diagnosis";
-function countByReasonCode(diagnosis) {
-  const counts = /* @__PURE__ */ new Map();
-  for (const capability of diagnosis.capabilities) {
-    counts.set(capability.reasonCode, (counts.get(capability.reasonCode) ?? 0) + 1);
-  }
-  const sorted = [...counts.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
-  return Object.fromEntries(sorted);
-}
-function buildDiagnosisDocument(input) {
-  const { diagnosis } = input;
-  const available = diagnosis.capabilities.filter((capability) => capability.available).length;
-  const capabilities = diagnosis.capabilities.map((capability) => ({
-    key: capability.key,
-    available: capability.available,
-    reasonCode: capability.reasonCode,
-    reason: capability.reason,
-    entitlementReasonCode: capability.entitlementReasonCode,
-    decidedAtLevel: capability.decidedAtLevel,
-    decidedAtKind: capability.decidedAtKind,
-    surface: capability.surface,
-    nextAction: capability.nextAction
-  }));
-  return {
-    schemaVersion: DIAGNOSIS_SCHEMA_VERSION,
-    kind: DIAGNOSIS_DOCUMENT_KIND,
-    generatedBy: { name: "@everfur/cli", version: input.cliVersion },
-    endpoint: { baseUrl: input.baseUrl, path: input.path },
-    requestId: diagnosis.requestId,
-    evaluatedAt: diagnosis.evaluatedAt,
-    client: { id: diagnosis.clientId, slug: diagnosis.clientSlug },
-    auth: {
-      mode: diagnosis.auth.mode,
-      anonymous: diagnosis.auth.anonymous,
-      userRefPrefix: diagnosis.auth.userRefPrefix,
-      userRole: diagnosis.auth.userRole,
-      roleSource: diagnosis.auth.roleSource,
-      sessionId: diagnosis.auth.sessionId,
-      partnerKeyScopeResolved: diagnosis.auth.partnerKeyScopeResolved
-    },
-    scope: {
-      provisioned: diagnosis.scope.provisioned,
-      resolverStatus: diagnosis.scope.resolverStatus,
-      revision: diagnosis.scope.revision,
-      region: diagnosis.scope.region,
-      levels: diagnosis.scope.levels.map((level) => ({
-        level: level.level,
-        kind: level.kind,
-        present: level.present
-      }))
-    },
-    summary: {
-      total: diagnosis.capabilities.length,
-      available,
-      unavailable: diagnosis.capabilities.length - available,
-      byReasonCode: countByReasonCode(diagnosis)
-    },
-    capabilities
-  };
-}
-
-// src/commands/diagnose/reasons.ts
-var REASON_CODES = Object.freeze([
-  "granted",
-  "scope_not_provisioned",
-  "capability_denied",
-  "outside_ceiling",
-  "not_in_grant",
-  "runtime_gate_off",
-  "gate_unknown",
-  "platform_invariant",
-  "resolver_unavailable"
-]);
-function isKnownReasonCode(value) {
-  return REASON_CODES.includes(value);
-}
-var NEXT_ACTION = Object.freeze({
-  granted: "Nothing to fix here. If a call against it still fails, run `everfur verify` and quote the request id.",
-  scope_not_provisioned: "Ask Everfur support to provision an entitlement scope for this tenant, quoting the client id and request id. Nothing on your side can make this resolve.",
-  capability_denied: "A deny was set deliberately at the level printed beside the key. Ask your Everfur contact to lift it; re-integrating will not change the answer.",
-  outside_ceiling: "This key is outside your tenant's agreed subset of the platform. That is a commercial change rather than a configuration one: raise it with your Everfur contact.",
-  not_in_grant: "Your scope is healthy and this key is simply not in the platform grant it resolves against. Ask Everfur support whether it is meant to be in your bundle.",
-  runtime_gate_off: "The lattice grants this and the surface is switched off, so its routes answer 404 whatever the verdict says. Ask Everfur to enable the named surface; entitlement changes will not help.",
-  gate_unknown: "Report this. A key was granted to you that the capability contract does not describe, so its runtime posture could not be read. Quote the key and the request id.",
-  platform_invariant: "Nothing to do. A platform invariant is never resolved through the entitlement lattice, so it is not a capability you can be granted.",
-  resolver_unavailable: "The state is UNKNOWN rather than denied. Retry in a few seconds; if it persists, quote the request id to Everfur support."
-});
-function nextActionFor(code) {
-  if (isKnownReasonCode(code)) return NEXT_ACTION[code];
-  return `This cause is newer than this CLI. Upgrade @everfur/cli, and quote the code "${code}" and the request id to Everfur support.`;
-}
-
-// src/commands/diagnose/parse.ts
-function str(record, key, fallback = "") {
-  const value = record[key];
-  return typeof value === "string" ? value : fallback;
-}
-function bool(record, key) {
-  return record[key] === true;
-}
-function num(record, key, fallback = 0) {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-function optionalNumber(record, key) {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-function optionalString(record, key) {
-  const value = record[key];
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function parseLevels(raw) {
-  if (!Array.isArray(raw)) return [];
-  const levels = [];
-  for (const item of raw) {
-    if (!isJsonObject(item)) continue;
-    levels.push(
-      Object.freeze({ level: num(item, "level"), kind: str(item, "kind", "unknown"), present: bool(item, "present") })
-    );
-  }
-  return Object.freeze(levels);
-}
-function parseCapability(raw) {
-  if (!isJsonObject(raw)) return null;
-  const key = str(raw, "key");
-  if (key.length === 0) return null;
-  const reasonCode = str(raw, "reason_code", "unknown");
-  return Object.freeze({
-    key,
-    available: bool(raw, "available"),
-    reasonCode,
-    reason: str(raw, "reason"),
-    entitlementReasonCode: str(raw, "entitlement_reason_code", reasonCode),
-    decidedAtLevel: optionalNumber(raw, "decided_at_level"),
-    decidedAtKind: optionalString(raw, "decided_at_kind"),
-    surface: optionalString(raw, "surface"),
-    nextAction: nextActionFor(reasonCode)
-  });
-}
-function parseDiagnostics(body, headerRequestId) {
-  if (!isJsonObject(body)) return { ok: false, detail: "the body is not a JSON object" };
-  const rawCapabilities = body["capabilities"];
-  if (!Array.isArray(rawCapabilities)) {
-    return { ok: false, detail: "the body carries no `capabilities` array" };
-  }
-  const rawScope = body["scope"];
-  if (!isJsonObject(rawScope)) return { ok: false, detail: "the body carries no `scope` object" };
-  const rawAuth = body["auth"];
-  if (!isJsonObject(rawAuth)) return { ok: false, detail: "the body carries no `auth` object" };
-  const capabilities = rawCapabilities.map(parseCapability).filter((entry) => entry !== null);
-  return {
-    ok: true,
-    diagnosis: Object.freeze({
-      requestId: optionalString(body, "request_id") ?? headerRequestId,
-      evaluatedAt: str(body, "evaluated_at"),
-      clientId: str(body, "client_id"),
-      clientSlug: str(body, "client_slug"),
-      auth: Object.freeze({
-        mode: str(rawAuth, "mode", "unknown"),
-        anonymous: bool(rawAuth, "anonymous"),
-        userRefPrefix: str(rawAuth, "user_ref_prefix"),
-        userRole: str(rawAuth, "user_role"),
-        roleSource: str(rawAuth, "role_source"),
-        sessionId: str(rawAuth, "session_id"),
-        partnerKeyScopeResolved: bool(rawAuth, "partner_key_scope_resolved")
-      }),
-      scope: Object.freeze({
-        provisioned: bool(rawScope, "provisioned"),
-        resolverStatus: str(rawScope, "resolver_status", "unknown"),
-        revision: num(rawScope, "revision"),
-        region: str(rawScope, "region", "unknown"),
-        levels: parseLevels(rawScope["levels"])
-      }),
-      capabilities: Object.freeze(capabilities)
-    })
-  };
-}
-
 // src/commands/diagnose/render.ts
 function renderLevels(diagnosis) {
   if (diagnosis.scope.levels.length === 0) return "(none reported)";
@@ -570,6 +316,7 @@ function renderDiagnosis(input) {
     `  region:       ${diagnosis.scope.region}`,
     `  levels:       ${renderLevels(diagnosis)}`
   ];
+  lines.push(...renderCauses(diagnosis));
   lines.push("", `Available (${available.length})`);
   if (available.length === 0) {
     lines.push("  none");
@@ -579,6 +326,7 @@ function renderDiagnosis(input) {
   lines.push("", `Unavailable (${unavailable.length})`);
   if (unavailable.length === 0) {
     lines.push("  none");
+    lines.push(...renderSwitches(diagnosis));
     return lines.join("\n");
   }
   const groups = /* @__PURE__ */ new Map();
@@ -601,136 +349,43 @@ function renderDiagnosis(input) {
     if (first.reason.length > 0) lines.push(`    why:  ${first.reason}`);
     lines.push(`    next: ${first.nextAction}`);
   }
+  lines.push(...renderSwitches(diagnosis));
   return lines.join("\n");
 }
-
-// src/commands/explain-error/explain.ts
-var EXPLANATION_SCHEMA_VERSION = 1;
-var EXPLANATION_DOCUMENT_KIND = "everfur.error-explanation";
-function nextActionFor2(entry) {
-  if (entry.retryable) {
-    if (entry.httpStatus === 429) {
-      return "Back off and retry. This is a rate limit, so retrying faster makes it worse; honour Retry-After if the response carried one.";
-    }
-    return "Retry with backoff. If it survives a few attempts, quote the request id from the failing response to Everfur support.";
-  }
-  switch (entry.httpStatus) {
-    case 400:
-    case 413:
-    case 415:
-    case 422:
-      return "Fix the request before sending it again. Branch on the HTTP status as well as the code: this code is the default for 400, 413, 415 and 422 alike, so a payload that is too large looks exactly like a bad field.";
-    case 401:
-      return "The credential was refused or the session expired. Mint a fresh session and retry once; every credential failure returns the same opaque 401, so do not read the message as a hint about which one.";
-    case 402:
-      return "The tenant needs a plan change. This is a commercial step, not a configuration one.";
-    case 403:
-      return "Authenticated but not permitted. Run `everfur diagnose` to see which fence blocked it and what the next action for that fence is.";
-    case 404:
-      return "Either the resource does not exist for this caller, or its surface is gated off and answers 404 by design. `everfur diagnose` tells the two apart.";
-    case 409:
-      return "A conflict, not a transient fault. Do not repeat the same request; build a new one.";
-    case 501:
-      return "The route exists and the behaviour does not. Nothing on the client side will change the answer.";
-    default:
-      return entry.httpStatus >= 500 ? "A server fault. Retry once, then quote the request id from the failing response to Everfur support." : "Quote the code and the request id from the failing response to Everfur support.";
+function renderSwitches(diagnosis) {
+  const lines = [""];
+  if (diagnosis.switches === null) {
+    lines.push("Switches", "  (the response carried none)");
+    return lines;
   }
-}
-function buildExplanationDocument(input) {
-  const { entry } = input;
-  return {
-    schemaVersion: EXPLANATION_SCHEMA_VERSION,
-    kind: EXPLANATION_DOCUMENT_KIND,
-    generatedBy: { name: "@everfur/cli", version: input.cliVersion },
-    code: entry.code,
-    source: { path: input.contractPath, digest: input.digest },
-    envelope: entry.envelope,
-    httpStatus: entry.httpStatus,
-    namingFamily: entry.namingFamily,
-    retryable: entry.retryable,
-    confirmedOnWire: entry.confirmedOnWire,
-    surfaces: [...entry.surfaces],
-    cause: entry.note,
-    display: entry.display,
-    docUrl: entry.docUrl,
-    nextAction: nextActionFor2(entry)
-  };
-}
-function renderExplanation(input) {
-  const { entry } = input;
-  const lines = [
-    `${entry.code}  (HTTP ${entry.httpStatus}, ${entry.envelope})`,
-    "",
-    "Cause",
-    `  ${entry.note.length > 0 ? entry.note : "(the registry carries no note for this code)"}`,
-    "",
-    "Retryable",
-    `  ${entry.retryable ? "yes" : "no"}`,
-    "",
-    "Next action",
-    `  ${nextActionFor2(entry)}`,
-    "",
-    "Detail",
-    `  naming family:     ${entry.namingFamily}`,
-    `  surfaces:          ${entry.surfaces.length === 0 ? "(none listed)" : entry.surfaces.join(", ")}`,
-    `  confirmed on wire: ${entry.confirmedOnWire ? "yes" : "no"}`,
-    `  docs:              ${entry.docUrl}`,
-    `  safe copy:         ${entry.display}`,
-    "",
-    "Source",
-    `  ${input.contractPath}`,
-    `  digest (sha256): ${input.digest}`
-  ];
-  if (!entry.confirmedOnWire) {
-    lines.push(
-      "",
-      "This code exists in source but the compiler could not trace a live route emitting it.",
-      "Treat it as documentation rather than as a contract to branch on."
-    );
+  const off = diagnosis.switches.filter(countsAsNotOn);
+  lines.push(`Switches (${diagnosis.switches.length}, ${off.length} not on)`);
+  if (diagnosis.switches.length === 0) {
+    lines.push("  none");
+    return lines;
   }
-  return lines.join("\n");
-}
-
-// src/commands/explain-error/suggest.ts
-var MAX_SUGGESTIONS = 5;
-var MAX_DISTANCE = 3;
-function editDistance(left, right) {
-  if (left === right) return 0;
-  if (left.length === 0) return right.length;
-  if (right.length === 0) return left.length;
-  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-  for (let row = 1; row <= left.length; row += 1) {
-    const current = [row];
-    for (let column = 1; column <= right.length; column += 1) {
-      const substitution = (previous[column - 1] ?? 0) + (left[row - 1] === right[column - 1] ? 0 : 1);
-      const deletion = (previous[column] ?? 0) + 1;
-      const insertion = (current[column - 1] ?? 0) + 1;
-      current[column] = Math.min(substitution, deletion, insertion);
-    }
-    previous = current;
+  for (const entry of diagnosis.switches) {
+    const state = entry.enabled === true ? "on" : entry.enabled === false ? "off" : "unknown";
+    lines.push(`  ${state.padEnd(7)} ${entry.name}${entry.kind === "posture" ? " (posture)" : ""}`);
+    if (entry.enabled === true && entry.kind !== "posture") continue;
+    if (entry.gates.length > 0) lines.push(`    gates: ${entry.gates.join(", ")}`);
+    if (entry.tenantTerm !== null) lines.push(`    tenant term: ${entry.tenantTerm}`);
+    if (entry.reason.length > 0) lines.push(`    why:  ${entry.reason}`);
+    lines.push(`    next: ${entry.nextAction}`);
   }
-  return previous[right.length] ?? Math.max(left.length, right.length);
+  return lines;
 }
-function suggestCodes(query, codes) {
-  const needle = query.toLowerCase();
-  const exact = [];
-  const contains = [];
-  const near = [];
-  for (const code of codes) {
-    const lower = code.toLowerCase();
-    if (lower === needle) {
-      exact.push(code);
-      continue;
-    }
-    if (lower.includes(needle) || needle.includes(lower)) {
-      contains.push(code);
-      continue;
-    }
-    const distance = editDistance(needle, lower);
-    if (distance <= MAX_DISTANCE) near.push({ code, distance });
+function renderCauses(diagnosis) {
+  const causes = diagnoseVerdict(diagnosis);
+  if (causes.length === 0) return [];
+  const lines = ["", `What is wrong (${causes.length})`];
+  for (const entry of causes) {
+    lines.push(`  [${entry.cause}] ${entry.summary}`);
+    if (entry.capabilities.length > 0) lines.push(`    capabilities: ${entry.capabilities.join(", ")}`);
+    if (entry.switches.length > 0) lines.push(`    switches:     ${entry.switches.join(", ")}`);
+    if (entry.switches.length > 0 || entry.reasonCodes.length !== 1) lines.push(`    next: ${entry.nextAction}`);
   }
-  near.sort((left, right) => left.distance - right.distance || (left.code < right.code ? -1 : 1));
-  return Object.freeze([...exact, ...contains.sort(), ...near.map((entry) => entry.code)].slice(0, MAX_SUGGESTIONS));
+  return lines;
 }
 
 // src/commands/sandbox/create.ts
@@ -903,7 +558,7 @@ function findContractPath(context, flagValue) {
 function setUpWire(context, flags, options = {}) {
   const errors = [];
   const endpointResolution = resolveEndpoint(flags.string("base-url"), context.env);
-  if (!endpointResolution.ok) errors.push(...endpointResolution.errors);
+  if (endpointResolution.ok === false) errors.push(...endpointResolution.errors);
   const timeout = parseTimeout(flags.string("timeout"));
   errors.push(...timeout.errors);
   const requestId = flags.string("request-id");
@@ -972,15 +627,48 @@ var FLAGS = Object.freeze([
     summary: `How many times to read the verdict before calling it empty (default ${DEFAULT_ATTEMPTS}).`,
     placeholder: "n"
   },
+  {
+    name: "origin",
+    kind: "string",
+    summary: "For a web integration: the page origin (https://shop.example.com) the surface is embedded on. Adds the embed fence, CORS exposure, session policy and loader checks.",
+    placeholder: "origin"
+  },
+  {
+    name: "loader-url",
+    kind: "string",
+    summary: "With --origin: the loader to probe instead of the one derived from the API host. Without it a local or unrecognised API reports the loader check as not checked.",
+    placeholder: "url"
+  },
+  {
+    // The same flag name `plan` takes for the same fact (the argv parser knows it as a value flag).
+    name: "identity",
+    kind: "string",
+    summary: `The identity mode to verify with: ${VERIFY_IDENTITY_MODES.join(" or ")}. partner-user-ref (the default) uses a signed session; anonymous uses the publishable key and a device session id, and reports whether the tenant requires signed sessions.`,
+    placeholder: "mode"
+  },
+  {
+    name: "surfaces",
+    kind: "string",
+    summary: `Comma separated surfaces to exercise with the minted session: ${SURFACES.join(", ")}. Televet mints a handoff only on a sandbox tenant. With --identity anonymous, records and televet are skipped: both take a signed session only.`,
+    placeholder: "list"
+  },
+  {
+    name: "project-root",
+    kind: "string",
+    summary: "The application root. Adds offline project checks: no secret key in source or client build output, no secret behind a public prefix, the secret read only by server code, 'use client' on App Router files, and the env files' API host. With --surfaces theme, the branding is judged merged with the theme prop everfur plan writes from the project's own theme.",
+    placeholder: "path"
+  },
   CONTRACT_FLAG,
   TIMEOUT_FLAG,
   REQUEST_ID_FLAG
 ]);
 function buildVerificationDocument(verification, baseUrl, cliVersion) {
   const counts = { passed: 0, failed: 0, skipped: 0 };
+  let gated = 0;
   for (const entry of verification.steps) {
     if (entry.result === "PASS") counts.passed += 1;
     else if (entry.result === "FAIL") counts.failed += 1;
+    else if (entry.result === "GATED") gated += 1;
     else counts.skipped += 1;
   }
   return {
@@ -989,7 +677,8 @@ function buildVerificationDocument(verification, baseUrl, cliVersion) {
     generatedBy: { name: "@everfur/cli", version: cliVersion },
     status: verification.status,
     baseUrl,
-    summary: counts,
+    // `gated` appears only when a step was GATED, so a document from a run with no surface checks is unchanged.
+    summary: gated === 0 ? counts : { ...counts, gated },
     steps: verification.steps.map((entry) => ({
       id: entry.id,
       title: entry.title,
@@ -1008,7 +697,7 @@ function renderVerification(verification, baseUrl) {
     ""
   ];
   for (const entry of verification.steps) {
-    lines.push(`  ${entry.result.padEnd(4)} ${entry.id}  ${entry.title}`);
+    lines.push(`  ${entry.result.padEnd(5)} ${entry.id}  ${entry.title}`);
     lines.push(`         ${entry.reason}`);
     lines.push(`         request id: ${entry.requestId ?? "(none; no call was made)"}`);
     for (const detail of entry.details) lines.push(`         - ${detail}`);
@@ -1018,8 +707,12 @@ function renderVerification(verification, baseUrl) {
     lines.push("At least one step failed. The reasons above are the report; the exit code only summarises them.");
   } else if (verification.status === "incomplete") {
     lines.push("Nothing failed, but a step was skipped, so the wire was not fully exercised.");
+  } else if (verification.steps.some((entry) => entry.result === "GATED")) {
+    lines.push("Nothing failed. A GATED step is a surface Everfur has not switched on for this tenant, not a fault in the integration.");
   } else {
-    lines.push("Every step passed. The session mint, the verdict read, and the verdict itself are all healthy.");
+    lines.push(
+      verification.steps.some((entry) => entry.id === "anonymous-identity") ? "Every step passed. The anonymous identity, the verdict read, and the verdict itself are all healthy." : "Every step passed. The session mint, the verdict read, and the verdict itself are all healthy."
+    );
   }
   return lines.join("\n");
 }
@@ -1037,17 +730,37 @@ function parseAttempts(raw) {
 var verifyCommand = {
   path: ["verify"],
   summary: "Exercise the wire: mint a session, read the verdict, assert it is not empty.",
-  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--json]",
+  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
   flags: FLAGS,
-  /** Exactly the pair `mintSession` resolves; without both, step one reports SKIP rather than FAIL. */
-  credentials: Object.freeze([PARTNER_KEY, PARTNER_SECRET_KEY]),
+  /**
+   * Exactly what `mintSession` resolves: the session token first, else the key pair it mints with locally. Without
+   * either source, step one reports SKIP rather than FAIL.
+   */
+  credentials: Object.freeze([SESSION_TOKEN, PARTNER_KEY, PARTNER_SECRET_KEY]),
   async run(context, flags) {
     const attempts = parseAttempts(flags.string("attempts"));
-    if (attempts.errors.length > 0) {
-      return errorOutcome("usage_error", "one or more flag values were not understood", attempts.errors);
+    const originFlag = flags.string("origin");
+    const origin = originFlag === null ? { origin: null, error: null } : parseOrigin(originFlag);
+    const loaderFlag = flags.string("loader-url");
+    const loader = loaderFlag === null ? { url: null, error: null } : parseLoaderUrl(loaderFlag);
+    const surfaces = parseSurfaces(flags.string("surfaces"));
+    const identityMode = parseIdentityMode(flags.string("identity"));
+    const projectRootFlag = flags.string("project-root");
+    const projectRoot = projectRootFlag === null ? null : resolveFromCwd(context.cwd, projectRootFlag.trim());
+    const projectErrors = projectRoot !== null && !context.fs.isDirectory(projectRoot) ? [`--project-root is not a directory: ${projectRoot}`] : [];
+    const flagErrors = [
+      ...attempts.errors,
+      ...origin.error === null ? [] : [origin.error],
+      ...loader.error === null ? [] : [loader.error],
+      ...surfaces.errors,
+      ...identityMode.errors,
+      ...projectErrors
+    ];
+    if (flagErrors.length > 0) {
+      return errorOutcome("usage_error", "one or more flag values were not understood", flagErrors);
     }
     const wire = setUpWire(context, flags);
-    if (!wire.ok) return wire.outcome;
+    if (wire.ok === false) return wire.outcome;
     const userRefFlag = flags.string("user-ref");
     const userRef = userRefFlag === null || userRefFlag.trim().length === 0 ? DEFAULT_USER_REF : userRefFlag.trim();
     const verification = await runVerification({
@@ -1056,7 +769,13 @@ var verifyCommand = {
       env: context.env,
       userRef,
       attempts: attempts.value,
-      pollDelayMs: POLL_DELAY_MS
+      pollDelayMs: POLL_DELAY_MS,
+      origin: origin.origin,
+      loaderUrl: loader.url,
+      transport: context.transport,
+      surfaces: surfaces.value ?? [],
+      project: projectRoot === null ? null : { fs: context.fs, root: projectRoot },
+      identityMode: identityMode.value
     });
     const document = buildVerificationDocument(verification, wire.client.baseUrl, context.version);
     const text = renderVerification(verification, wire.client.baseUrl);
@@ -1080,7 +799,7 @@ var FLAGS2 = Object.freeze([
   {
     name: "capabilities",
     kind: "string",
-    summary: "Comma separated capability ids. The valid ids come from the contract decision trees.",
+    summary: 'Comma separated capability ids, or "all" for every capability the contract can plan. The valid ids come from the contract decision trees; verify is the fail-closed check of what the tenant actually has.',
     placeholder: "list"
   },
   {
@@ -1095,6 +814,18 @@ var FLAGS2 = Object.freeze([
     summary: "Language that mints sessions server side. Required only when the identity mode mints.",
     placeholder: "language"
   },
+  {
+    name: "embedding",
+    kind: "string",
+    summary: "How a web project embeds the surface: in-page (the SDK's React components) or frame (the loader). Detected from react-dom; the flag overrides.",
+    placeholder: "mode"
+  },
+  {
+    name: "environment",
+    kind: "string",
+    summary: `The Everfur deployment the generated configuration targets: ${ENVIRONMENTS.join(", ")}. Required for a plan that writes configuration; never assumed.`,
+    placeholder: "name"
+  },
   CONTRACT_FLAG
 ]);
 function asJsonObject(document) {
@@ -1126,13 +857,13 @@ function contractOutcome(outcome) {
 var planCommand = {
   path: ["plan"],
   summary: "Produce an integration plan for the project in the current directory.",
-  usage: "plan [--cwd <path>] [--capabilities <list>] [--identity <mode>] [--backend <language>] [--contract <file>] [--json]",
+  usage: "plan [--cwd <path>] [--capabilities <list>] [--identity <mode>] [--backend <language>] [--embedding <mode>] [--environment <name>] [--contract <file>] [--json]",
   flags: FLAGS2,
+  credentials: Object.freeze([DOCS_KEY]),
   async run(context, flags) {
     const contractFlag = flags.string("contract");
     const contractPath = findContractPath(context, contractFlag);
     let space = null;
-    let usedBundledContract = false;
     if (contractPath !== null) {
       const load = loadDecisionSpace(context.fs, contractPath);
       if (load.kind === "loaded") {
@@ -1144,46 +875,58 @@ var planCommand = {
         ]);
       }
     }
+    const cwdFlag = flags.string("cwd");
+    const root = cwdFlag === null ? context.cwd : isAbsolute(cwdFlag) ? cwdFlag : resolve(context.cwd, cwdFlag);
+    if (!context.fs.isDirectory(root)) {
+      return errorOutcome("usage_error", `not a directory: ${root}`, [
+        "pass --cwd with a path to the application root"
+      ]);
+    }
     if (space === null && contractPath === null) {
-      const bundled = loadBundledDecisionSpace();
-      if (bundled.kind === "loaded") {
-        space = bundled.space;
-        usedBundledContract = true;
+      const fetched = await fetchContract({
+        env: context.env,
+        transport: context.transport,
+        clock: context.clock,
+        ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
+      });
+      if (fetched.kind === "unavailable") return contractUnavailableOutcome(fetched);
+      const load = loadDecisionSpaceFromContract(fetched.contract);
+      if (load.kind !== "loaded") {
+        return errorOutcome("invalid_contract", `${fetched.contract.source} carries no decision trees`, [
+          "the contract validated, but it has no `decision-trees.yaml` document with a `trees` list"
+        ]);
       }
+      space = load.space;
     }
     const supplied = parseSuppliedFacts(
       flags.string("capabilities"),
       flags.string("identity"),
       flags.string("backend"),
-      space
+      space,
+      flags.string("embedding")
     );
-    if (!supplied.ok) {
-      return errorOutcome("usage_error", "one or more flag values were not understood", supplied.errors);
-    }
-    const cwdFlag = flags.string("cwd");
-    const root = cwdFlag === null ? context.cwd : isAbsolute(cwdFlag) ? cwdFlag : resolve(context.cwd, cwdFlag);
-    if (!context.fs.isDirectory(root)) {
-      return errorOutcome("usage_error", `not a directory: ${root}`, [
-        "pass --cwd with a path to the application root"
+    const environment = parseEnvironment(flags.string("environment"));
+    if (!supplied.ok || environment.errors.length > 0) {
+      return errorOutcome("usage_error", "one or more flag values were not understood", [
+        ...supplied.errors,
+        ...environment.errors
       ]);
     }
     const detection = detectProject(context.fs, root);
     const document = planIntegration({
       detection,
       capabilities: supplied.capabilities,
+      allCapabilities: supplied.allCapabilities,
       identityMode: supplied.identityMode,
       sessionMintLanguage: supplied.sessionMintLanguage,
+      embedding: supplied.embedding,
+      environment: environment.value,
       space,
       cliVersion: context.version
     });
     const json = asJsonObject(document);
     const text = renderPlan(document);
-    if (document.status === "underspecified") {
-      const hint = contractPath === null && !usedBundledContract && document.missingFacts.some((fact) => fact.fact === "decisionTrees") ? `${text}
-
-Looked for a projection at: ${DEFAULT_CONTRACT_PATHS.join(", ")} under ${root}, and in ${CONTRACT_ENV_VAR}.` : text;
-      return fail(ExitCode.UNDERSPECIFIED, json, hint);
-    }
+    if (document.status === "underspecified") return fail(ExitCode.UNDERSPECIFIED, json, text);
     if (document.status === "blocked") return fail(ExitCode.BLOCKED, json, text);
     return succeed(json, text);
   }
@@ -1255,42 +998,7 @@ var contractValidateCommand = {
   }
 };
 
-// src/commands/shared/widget-auth.ts
-function chooseWidgetAuth(env) {
-  const session = resolveCredential(env, SESSION_TOKEN);
-  if (session.status === "present" && session.credential !== null) {
-    return {
-      ok: true,
-      auth: { mode: "session_token", headers: Object.freeze({ authorization: withPrefix(session.credential, "Bearer ") }) }
-    };
-  }
-  const partner = resolveCredential(env, PARTNER_KEY);
-  if (partner.status === "present" && partner.credential !== null) {
-    return {
-      ok: true,
-      auth: { mode: "partner_key", headers: Object.freeze({ "x-everfur-partner-key": partner.credential }) }
-    };
-  }
-  if (partner.status === "malformed") {
-    return {
-      ok: false,
-      outcome: errorOutcome("usage_error", "the partner key is not usable", [
-        partner.reason ?? "the value has the wrong shape",
-        "the value itself is never printed; check what you exported"
-      ])
-    };
-  }
-  return {
-    ok: false,
-    outcome: errorOutcome("credential_missing", "no widget credential is configured", [
-      `export ${PARTNER_KEY.envVar} with your publishable key (${PARTNER_KEY.prefix}...)`,
-      `or export ${SESSION_TOKEN.envVar} with an existing session bearer to diagnose the signed path`
-    ])
-  };
-}
-
 // src/commands/diagnose/index.ts
-var DIAGNOSTICS_PATH = "/widget/v1/diagnostics";
 var FLAGS4 = Object.freeze([
   BASE_URL_FLAG,
   {
@@ -1299,6 +1007,17 @@ var FLAGS4 = Object.freeze([
     summary: "End user reference to diagnose as. Omit to diagnose the anonymous subject.",
     placeholder: "ref"
   },
+  {
+    name: "bundle",
+    kind: "boolean",
+    summary: "Emit one support bundle instead: project, framework, SDK and CLI versions, contract digest, credential presence (never values), and the diagnosis with its request id. Produced whatever state the integration is in."
+  },
+  {
+    name: "project-root",
+    kind: "string",
+    summary: "With --bundle: the application root to describe. Defaults to the current working directory.",
+    placeholder: "path"
+  },
   CONTRACT_FLAG,
   TIMEOUT_FLAG,
   REQUEST_ID_FLAG
@@ -1306,15 +1025,41 @@ var FLAGS4 = Object.freeze([
 var diagnoseCommand = {
   path: ["diagnose"],
   summary: "Explain why each capability is or is not available to this caller.",
-  usage: "diagnose [--base-url <url>] [--user-ref <ref>] [--contract <file>] [--json]",
+  usage: "diagnose [--base-url <url>] [--user-ref <ref>] [--contract <file>] [--bundle [--project-root <path>]] [--json]",
   flags: FLAGS4,
   /** Exactly what `chooseWidgetAuth` resolves: the bearer wins, the publishable key is the fallback. */
   credentials: Object.freeze([PARTNER_KEY, SESSION_TOKEN]),
   async run(context, flags) {
     const wire = setUpWire(context, flags);
-    if (!wire.ok) return wire.outcome;
+    if (flags.boolean("bundle")) {
+      const projectRootFlag = flags.string("project-root");
+      const root = projectRootFlag === null ? context.cwd : resolveFromCwd(context.cwd, projectRootFlag.trim());
+      const wireErrors = wire.ok ? [] : [...wire.outcome.json.error?.details ?? []];
+      const bundle = await buildSupportBundle({
+        fs: context.fs,
+        root,
+        env: context.env,
+        cliVersion: context.version,
+        client: wire.ok ? wire.client : null,
+        wireErrors,
+        contractSource: wire.ok ? wire.registrySource : null,
+        contract: () => fetchContract({
+          env: context.env,
+          transport: context.transport,
+          clock: context.clock,
+          ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
+        })
+      });
+      return succeed(bundle, renderSupportBundle(bundle));
+    }
+    if (flags.string("project-root") !== null) {
+      return errorOutcome("usage_error", "--project-root describes the project in a support bundle, so it needs --bundle", [
+        "run `everfur diagnose --bundle --project-root <path>`"
+      ]);
+    }
+    if (wire.ok === false) return wire.outcome;
     const auth = chooseWidgetAuth(context.env);
-    if (!auth.ok) return auth.outcome;
+    if (auth.ok === false) return auth.outcome;
     const userRef = flags.string("user-ref");
     const headers = {};
     if (userRef !== null && userRef.trim().length > 0) {
@@ -1326,14 +1071,29 @@ var diagnoseCommand = {
       headers,
       credentials: auth.auth.headers
     });
-    if (!result.ok) {
-      return failureOutcome(result, [
-        `auth mode: ${auth.auth.mode}`,
-        "a 401 here means the credential was refused; every credential failure returns the same opaque 401"
+    if (result.ok === false) {
+      const diagnosed = diagnoseFailure(result, auth.auth);
+      const outcome = failureOutcome(result, [
+        `cause: ${diagnosed.summary}`,
+        ...diagnosed.evidence,
+        `next action: ${diagnosed.nextAction}`
       ]);
+      const document2 = outcome.json;
+      return {
+        ...outcome,
+        json: {
+          ...document2,
+          error: {
+            ...document2.error,
+            cause: diagnosed.cause,
+            evidence: [...diagnosed.evidence],
+            nextAction: diagnosed.nextAction
+          }
+        }
+      };
     }
     const parsed = parseDiagnostics(result.value, result.requestId);
-    if (!parsed.ok) {
+    if (parsed.ok === false) {
       return errorOutcome(
         "malformed_response",
         `${DIAGNOSTICS_PATH} answered ${result.status} with a body this CLI does not recognise`,
@@ -1369,34 +1129,50 @@ var explainErrorCommand = {
   usage: "explain-error <code> [--contract <file>] [--json]",
   flags: FLAGS5,
   positionals: POSITIONALS,
+  credentials: Object.freeze([DOCS_KEY]),
   async run(context, flags, positionals) {
     const code = (positionals[0] ?? "").trim();
     if (code.length === 0) {
       return errorOutcome("usage_error", "no error code was given", ["usage: everfur explain-error <code>"]);
     }
+    const offline = resolveOffline(code);
+    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version);
     const contractFlag = flags.string("contract");
     const contractPath = findContractPath(context, contractFlag);
+    let load;
     if (contractPath === null) {
-      return errorOutcome("file_not_found", "no contract-public projection was found", [
-        `pass --contract <file>, or export ${CONTRACT_ENV_VAR}`,
-        `looked for: ${DEFAULT_CONTRACT_PATHS.join(", ")} under ${context.cwd}`,
-        "the error registry is compiled by the platform; this CLI does not carry a copy"
-      ]);
+      const fetched = await fetchContract({
+        env: context.env,
+        transport: context.transport,
+        clock: context.clock,
+        ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
+      });
+      if (fetched.kind === "unavailable") {
+        if (offline !== null) return offlineOutcome(offline, context.version);
+        const suggestions = offlineSuggestions(code);
+        return contractUnavailableOutcome(fetched, [
+          ...suggestions.length > 0 ? [`did you mean: ${suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no code similar to "${code}" exists in the SDK taxonomy or the SDK contract table this CLI carries`]
+        ]);
+      }
+      load = loadErrorRegistryFromContract(fetched.contract);
+    } else {
+      load = loadErrorRegistry(context.fs, contractPath);
     }
-    const load = loadErrorRegistry(context.fs, contractPath);
     if (load.kind === "contract_rejected") return contractOutcome2(load.outcome);
     if (load.kind === "no_registry") {
       return errorOutcome("invalid_contract", `${load.path} carries no error registry`, [
-        "the projection validated, but it has no `errors.yaml` document with an `errors` list",
+        "no `errors.yaml` document with an `errors` list was found in the projection",
         "this is a projection built before the error registry was published, or a partial one"
       ]);
     }
     const entry = load.registry.lookup(code);
     if (entry === null) {
-      const suggestions = suggestCodes(code, load.registry.codes);
+      const fallback = resolveAfterRegistryMiss(code, load.registry);
+      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version);
       return errorOutcome("unknown_error_code", `"${code}" is not in the error registry`, [
-        ...suggestions.length > 0 ? [`did you mean: ${suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : ["no similar code exists in the registry"],
-        `the registry loaded from ${load.path} lists ${load.registry.codes.length} codes`
+        ...fallback.suggestions.length > 0 ? [`did you mean: ${fallback.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : ["no similar code exists in the registry"],
+        `the registry loaded from ${load.path} lists ${load.registry.codes.length} codes`,
+        `neither the SDK taxonomy nor the SDK contract table this CLI carries knows it either (${knownCodes(load.registry).length} codes searched in all)`
       ]);
     }
     const input = {
@@ -1408,6 +1184,9 @@ var explainErrorCommand = {
     return succeed(buildExplanationDocument(input), renderExplanation(input));
   }
 };
+function offlineOutcome(resolution, cliVersion) {
+  return resolution.kind === "sdk_member" ? succeed(buildSdkExplanationDocument(resolution.code, cliVersion), renderSdkExplanation(resolution.code)) : succeed(buildContractTableExplanationDocument(resolution.row, cliVersion), renderContractTableExplanation(resolution.row));
+}
 function contractOutcome2(outcome) {
   switch (outcome.kind) {
     case "file_not_found":
@@ -1467,7 +1246,7 @@ var sandboxCreateCommand = {
       ]);
     }
     const wire = setUpWire(context, flags);
-    if (!wire.ok) return wire.outcome;
+    if (wire.ok === false) return wire.outcome;
     const admin = resolveCredential(context.env, ADMIN_TOKEN);
     if (admin.status !== "present" || admin.credential === null) {
       return errorOutcome("credential_missing", "no admin credential is configured", [
@@ -1484,14 +1263,14 @@ var sandboxCreateCommand = {
       credentials: { authorization: withPrefix(admin.credential, "Bearer ") },
       body
     });
-    if (!result.ok) {
+    if (result.ok === false) {
       return failureOutcome(result, [
         "no key was provisioned, so there is nothing to revoke",
         "a 400 here means the client exists but is not an active partner tenant"
       ]);
     }
     const projected = projectSandboxCreate(result.value);
-    if (!projected.ok) {
+    if (projected.ok === false) {
       return errorOutcome("malformed_response", `${path} answered ${result.status} with an unreadable body`, [
         projected.detail,
         result.requestId === null ? "the response carried no request id" : `request id: ${result.requestId}`,
@@ -1545,6 +1324,9 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "capabilities",
   "identity",
   "backend",
+  "embedding",
+  "origin",
+  "loader-url",
   "path",
   "base-url",
   "contract",
@@ -1553,7 +1335,10 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "user-ref",
   "timeout",
   "attempts",
-  "request-id"
+  "request-id",
+  "environment",
+  "surfaces",
+  "project-root"
 ]);
 var ALIASES = Object.freeze({
   h: "help",
@@ -1798,7 +1583,7 @@ async function runCli(options) {
     return formatOutcome(succeed({ schemaVersion: 1, kind: "everfur.help", text: help }, help), format);
   }
   const bound = bindFlags(match.command.flags, parsed);
-  if (!bound.ok) {
+  if (bound.ok === false) {
     return formatOutcome(
       errorOutcome("usage_error", `invalid invocation of "${commandName(match.command)}"`, [
         ...bound.errors,
@@ -1819,4 +1604,4 @@ async function runCli(options) {
   }
 }
 
-export { COMMANDS, ExitCode, REASON_CODES, buildDiagnosisDocument, buildExplanationDocument, buildSandboxDocument, buildVerificationDocument, editDistance, failureOutcome, formatOutcome, isKnownReasonCode, matchCommand, nextActionFor, nextActionFor2, nextActionsFor, parseCapabilities, parseDiagnostics, parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, projectSandboxCreate, renderDiagnosis, renderExplanation, renderPlan, renderSandboxCreate, renderVerification, runCli, suggestCodes };
+export { COMMANDS, buildSandboxDocument, buildVerificationDocument, failureOutcome, formatOutcome, matchCommand, nextActionsFor, parseCapabilities, parseIdentityMode2 as parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, projectSandboxCreate, renderDiagnosis, renderPlan, renderSandboxCreate, renderVerification, runCli };