@everfur/cli 0.1.0

package/dist/chunk-67H43MI6.js

@@ -0,0 +1,1822 @@
+#!/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 { 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}
+`;
+}
+function formatOutcome(outcome, options) {
+  if (options.json) {
+    return Object.freeze({
+      stdout: withNewline(JSON.stringify(outcome.json, null, 2)),
+      stderr: "",
+      exitCode: outcome.exitCode
+    });
+  }
+  const body = withNewline(outcome.text);
+  return Object.freeze({
+    stdout: outcome.stream === "stdout" ? body : "",
+    stderr: outcome.stream === "stderr" ? body : "",
+    exitCode: outcome.exitCode
+  });
+}
+
+// src/commands/plan/facts.ts
+function known(space, treeId, questionId) {
+  if (space === null) return null;
+  const choices = space.choices(treeId, questionId);
+  return choices.length === 0 ? null : choices;
+}
+function parseCapabilities(raw, space) {
+  if (raw === null) return { value: null, errors: [] };
+  const allowed = known(space, CAPABILITIES_TREE, CAPABILITY_QUESTION);
+  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(", ")}`
+      ]
+    };
+  }
+  const errors = [];
+  const selected = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    if (allowed === null || allowed.includes(token)) {
+      selected.add(token);
+      continue;
+    }
+    errors.push(`unknown capability "${token}"; supported: ${allowed.join(", ")}`);
+  }
+  if (errors.length > 0) return { value: null, errors };
+  return { value: Object.freeze([...selected].sort()), errors: [] };
+}
+function parseChoice(raw, space, treeId, questionId, flag) {
+  if (raw === null) return { value: null, errors: [] };
+  const token = raw.trim();
+  const allowed = known(space, treeId, questionId);
+  if (allowed === null || allowed.includes(token)) return { value: token, errors: [] };
+  return { value: null, errors: [`unknown ${flag} "${raw}"; supported: ${allowed.join(", ")}`] };
+}
+var IDENTITY_ALIASES = Object.freeze({ personalized: "partner-user-ref" });
+function parseIdentityMode(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) {
+  const capabilities = parseCapabilities(capabilitiesRaw, space);
+  const identity = parseIdentityMode(identityRaw, space);
+  const backend = parseSessionMintLanguage(backendRaw, space);
+  const errors = [...capabilities.errors, ...identity.errors, ...backend.errors];
+  return Object.freeze({
+    ok: errors.length === 0,
+    capabilities: capabilities.value,
+    identityMode: identity.value,
+    sessionMintLanguage: backend.value,
+    errors: Object.freeze(errors)
+  });
+}
+
+// src/commands/plan/render.ts
+function indent(lines, prefix) {
+  return lines.map((line) => `${prefix}${line}`);
+}
+function renderDetected(document) {
+  const { detected } = document;
+  const lines = ["Detected", `  root:            ${detected.root}`];
+  lines.push(`  project type:    ${detected.projectType}`);
+  lines.push(...indent(detected.projectTypeEvidence, "                   - "));
+  lines.push(`  package manager: ${detected.packageManager}`);
+  lines.push(...indent(detected.packageManagerEvidence, "                   - "));
+  if (detected.dependencies.length === 0) {
+    lines.push("  dependencies:    none of the relevant packages are declared");
+    return lines;
+  }
+  lines.push("  dependencies:");
+  for (const dependency of detected.dependencies) {
+    const declared = dependency.declared ?? "(none)";
+    const installed = dependency.installed === null ? "not installed" : `installed ${dependency.installed}`;
+    lines.push(`    ${dependency.name} ${declared} (${installed}, ${dependency.scope}, ${dependency.source})`);
+  }
+  return lines;
+}
+function renderContract(document) {
+  const { decisionSpace } = document;
+  if (decisionSpace === null) return [];
+  return [
+    "Decision space",
+    `  source: ${decisionSpace.source}`,
+    `  digest: ${decisionSpace.digest}`,
+    `  trees:  ${decisionSpace.trees.join(", ")}`
+  ];
+}
+function renderBlocked(document) {
+  const lines = [
+    `Blocked (${document.blocked.length})`,
+    "  These cannot be built today. No steps below cover them."
+  ];
+  for (const blocked of document.blocked) {
+    lines.push("");
+    lines.push(`  ${blocked.capability}`);
+    lines.push(`    why:     ${blocked.reason}`);
+    lines.push(`    ask:     ${blocked.unblockOwner}`);
+    lines.push(`    at:      ${blocked.requestPath}`);
+    if (blocked.capabilityKeys.length > 0) {
+      lines.push(`    covers:  ${blocked.capabilityKeys.join(", ")}`);
+    }
+  }
+  return lines;
+}
+function renderWarnings(document) {
+  const lines = ["Warnings"];
+  for (const warning of document.warnings) {
+    lines.push(`  [${warning.code}] ${warning.message}`);
+  }
+  return lines;
+}
+function renderPrinciples(document) {
+  const lines = ["Always true"];
+  for (const principle of document.principles) {
+    lines.push("");
+    lines.push(`  ${principle.title}`);
+    lines.push(`    ${principle.statement}`);
+    if (principle.docPath !== null) lines.push(`    see: ${principle.docPath}`);
+  }
+  return lines;
+}
+function renderRefusal(document) {
+  const lines = [
+    "everfur plan: refusing to guess.",
+    "",
+    `${document.missingFacts.length} required fact${document.missingFacts.length === 1 ? "" : "s"} missing:`
+  ];
+  for (const fact of document.missingFacts) {
+    lines.push("");
+    lines.push(`  ${fact.fact}`);
+    lines.push(`    why:    ${fact.reason}`);
+    lines.push(`    supply: ${fact.supplyWith}`);
+  }
+  lines.push("");
+  lines.push(...renderDetected(document));
+  if (document.blocked.length > 0) {
+    lines.push("");
+    lines.push(...renderBlocked(document));
+  }
+  if (document.warnings.length > 0) {
+    lines.push("");
+    lines.push(...renderWarnings(document));
+  }
+  lines.push("");
+  lines.push("No plan was produced. Supply the facts above and run again.");
+  return lines.join("\n");
+}
+function renderBlockedPlan(document) {
+  const lines = [
+    "everfur plan: nothing you asked for can be built today.",
+    "",
+    ...renderBlocked(document),
+    "",
+    ...renderDetected(document)
+  ];
+  if (document.warnings.length > 0) {
+    lines.push("");
+    lines.push(...renderWarnings(document));
+  }
+  const contract = renderContract(document);
+  if (contract.length > 0) {
+    lines.push("");
+    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.");
+  return lines.join("\n");
+}
+function renderReady(document) {
+  const capabilities = document.supplied.capabilities ?? [];
+  const lines = [
+    `everfur plan: ${document.steps.length} step${document.steps.length === 1 ? "" : "s"} for a ${document.detected.projectType} project.`,
+    "",
+    ...renderDetected(document),
+    "",
+    "Supplied",
+    `  capabilities:  ${capabilities.join(", ")}`,
+    `  identity mode: ${document.supplied.identityMode ?? "(none)"}`
+  ];
+  if (document.supplied.sessionMintLanguage !== null) {
+    lines.push(`  mint language: ${document.supplied.sessionMintLanguage}`);
+  }
+  lines.push("", "Plan");
+  document.steps.forEach((step, index) => {
+    lines.push("");
+    lines.push(`  ${index + 1}. [${step.phase}] ${step.title}`);
+    lines.push(`     ${step.detail}`);
+    for (const command of step.commands) lines.push(`     $ ${command}`);
+    for (const file of step.files) lines.push(`     file: ${file}`);
+  });
+  if (document.blocked.length > 0) {
+    lines.push("");
+    lines.push(...renderBlocked(document));
+  }
+  if (document.warnings.length > 0) {
+    lines.push("");
+    lines.push(...renderWarnings(document));
+  }
+  if (document.principles.length > 0) {
+    lines.push("");
+    lines.push(...renderPrinciples(document));
+  }
+  const contract = renderContract(document);
+  if (contract.length > 0) {
+    lines.push("");
+    lines.push(...contract);
+  }
+  return lines.join("\n");
+}
+function renderPlan(document) {
+  if (document.status === "underspecified") return renderRefusal(document);
+  if (document.status === "blocked") return renderBlockedPlan(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",
+  timeout: "remote_unreachable",
+  http: "remote_error",
+  malformed: "malformed_response"
+});
+function failureOutcome(failure, extraDetails = []) {
+  return errorOutcome(CODE_FOR_KIND[failure.kind], describeFailure(failure), [
+    ...failureDetails(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)";
+  return diagnosis.scope.levels.map((level) => `L${level.level} ${level.kind}${level.present ? "" : " (absent)"}`).join(", ");
+}
+function renderDiagnosis(input) {
+  const { diagnosis } = input;
+  const available = diagnosis.capabilities.filter((capability) => capability.available);
+  const unavailable = diagnosis.capabilities.filter((capability) => !capability.available);
+  const lines = [
+    `everfur diagnose: ${available.length} of ${diagnosis.capabilities.length} capabilities available.`,
+    "",
+    "Connection",
+    `  base url:     ${input.baseUrl}`,
+    `  request id:   ${diagnosis.requestId ?? "(the response carried none)"}`,
+    `  evaluated at: ${diagnosis.evaluatedAt}`,
+    "",
+    "Caller",
+    `  client:       ${diagnosis.clientSlug} (${diagnosis.clientId})`,
+    `  auth mode:    ${diagnosis.auth.mode}${diagnosis.auth.anonymous ? " (anonymous)" : ""}`,
+    `  user ref:     ${diagnosis.auth.userRefPrefix}... as ${diagnosis.auth.userRole} (${diagnosis.auth.roleSource})`,
+    `  session id:   ${diagnosis.auth.sessionId}`,
+    `  key scope:    ${diagnosis.auth.partnerKeyScopeResolved ? "resolved" : "not resolved"}`,
+    "",
+    "Scope",
+    `  provisioned:  ${diagnosis.scope.provisioned ? "yes" : "no"}`,
+    `  resolver:     ${diagnosis.scope.resolverStatus}`,
+    `  revision:     ${diagnosis.scope.revision}`,
+    `  region:       ${diagnosis.scope.region}`,
+    `  levels:       ${renderLevels(diagnosis)}`
+  ];
+  lines.push("", `Available (${available.length})`);
+  if (available.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const capability of available) lines.push(`  ${capability.key}`);
+  }
+  lines.push("", `Unavailable (${unavailable.length})`);
+  if (unavailable.length === 0) {
+    lines.push("  none");
+    return lines.join("\n");
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const capability of unavailable) {
+    const existing = groups.get(capability.reasonCode);
+    if (existing === void 0) groups.set(capability.reasonCode, [capability]);
+    else existing.push(capability);
+  }
+  for (const [code, members] of groups) {
+    const first = members[0];
+    if (first === void 0) continue;
+    lines.push("");
+    lines.push(`  [${code}] ${members.length} capabilit${members.length === 1 ? "y" : "ies"}`);
+    for (const member of members) {
+      const decided = member.decidedAtLevel === null ? "" : ` (decided at L${member.decidedAtLevel} ${member.decidedAtKind ?? "unknown"})`;
+      const surface = member.surface === null ? "" : ` (surface ${member.surface})`;
+      const masked = member.entitlementReasonCode === member.reasonCode ? "" : ` (entitlement says ${member.entitlementReasonCode})`;
+      lines.push(`    ${member.key}${decided}${surface}${masked}`);
+    }
+    if (first.reason.length > 0) lines.push(`    why:  ${first.reason}`);
+    lines.push(`    next: ${first.nextAction}`);
+  }
+  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 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."
+    );
+  }
+  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;
+  }
+  return previous[right.length] ?? Math.max(left.length, right.length);
+}
+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 });
+  }
+  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));
+}
+
+// src/commands/sandbox/create.ts
+function readString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function projectSandboxCreate(body) {
+  if (!isJsonObject(body)) return { ok: false, detail: "the body is not a JSON object" };
+  const keyId = readString(body, "key_id");
+  if (keyId === null) return { ok: false, detail: "the body carries no `key_id`" };
+  const claimUrl = readString(body, "claim_url");
+  return {
+    ok: true,
+    creation: Object.freeze({
+      status: claimUrl === null ? "claim_unavailable" : "claim_issued",
+      keyId,
+      clientId: readString(body, "client_id") ?? "",
+      label: readString(body, "label"),
+      createdAt: readString(body, "created_at"),
+      claimUrl,
+      claimExpiresAt: readString(body, "claim_expires_at"),
+      secretDiscarded: typeof body["secret_value"] === "string"
+    })
+  };
+}
+var SANDBOX_SCHEMA_VERSION = 1;
+var SANDBOX_DOCUMENT_KIND = "everfur.sandbox-create";
+function revokePathFor(creation) {
+  return `/admin/clients/${encodeURIComponent(creation.clientId)}/secret-keys/${encodeURIComponent(creation.keyId)}`;
+}
+function nextActionsFor(creation, revocation) {
+  if (creation.status === "claim_issued") {
+    return Object.freeze([
+      "Open the claim URL in a browser and copy the secret from there.",
+      "The claim URL is single use and expires; a lapsed claim needs a new key."
+    ]);
+  }
+  if (revocation === "revoke_failed") {
+    return Object.freeze([
+      "The server returned no claim URL, so the secret it minted was discarded unread and cannot be recovered.",
+      "This command tried to revoke the orphaned key and the revoke did not succeed, so a live credential nobody holds still exists.",
+      `Revoke it by hand: DELETE /api/v1${revokePathFor(creation)}`,
+      "Until the claim flow exists server side, issue partner secrets through the admin route directly."
+    ]);
+  }
+  return Object.freeze([
+    "The server returned no claim URL, so the secret it minted was discarded unread and cannot be recovered.",
+    "The key this command minted was revoked again immediately, so nothing live was left behind.",
+    "Until the claim flow exists server side, issue partner secrets through the admin route directly."
+  ]);
+}
+function buildSandboxDocument(input) {
+  const { creation, revocation } = input;
+  return {
+    schemaVersion: SANDBOX_SCHEMA_VERSION,
+    kind: SANDBOX_DOCUMENT_KIND,
+    generatedBy: { name: "@everfur/cli", version: input.cliVersion },
+    status: creation.status,
+    requestId: input.requestId,
+    clientId: creation.clientId,
+    keyId: creation.keyId,
+    label: creation.label,
+    createdAt: creation.createdAt,
+    claimUrl: creation.claimUrl,
+    claimExpiresAt: creation.claimExpiresAt,
+    /**
+     * A literal `false` pinned by the schema. A machine reading this document can assert the
+     * invariant rather than trusting the prose, and any change that ever made it true would
+     * fail the contract test before it shipped.
+     */
+    secretDisclosed: false,
+    secretDiscarded: creation.secretDiscarded,
+    /**
+     * What became of an unclaimable key. `revoke_failed` is the one value that means a live
+     * credential nobody holds still exists, so a wrapper can branch on it rather than parse
+     * the prose in `nextActions`.
+     */
+    orphanedKey: revocation,
+    nextActions: nextActionsFor(creation, revocation)
+  };
+}
+function renderSandboxCreate(creation, revocation, requestId) {
+  const lines = [
+    creation.status === "claim_issued" ? "everfur sandbox create: key provisioned, claim it in a browser." : "everfur sandbox create: key provisioned, but there is no way to claim its secret.",
+    "",
+    `  key id:      ${creation.keyId}`,
+    `  client id:   ${creation.clientId}`,
+    `  label:       ${creation.label ?? "(none)"}`,
+    `  created at:  ${creation.createdAt ?? "(not reported)"}`,
+    `  request id:  ${requestId ?? "(the response carried none)"}`
+  ];
+  if (creation.status === "claim_issued") {
+    lines.push(`  claim url:   ${creation.claimUrl ?? ""}`);
+    lines.push(`  claim until: ${creation.claimExpiresAt ?? "(not reported)"}`);
+  } else {
+    lines.push("  claim url:   none was offered");
+  }
+  lines.push("");
+  lines.push("The secret itself is never printed by this CLI, in either output mode.");
+  if (creation.secretDiscarded) {
+    lines.push("The response carried a raw secret. It was discarded unread and is unrecoverable.");
+  }
+  if (revocation === "revoked") {
+    lines.push("The unclaimable key was revoked again immediately, so nothing live was left behind.");
+  } else if (revocation === "revoke_failed") {
+    lines.push("The revoke of the unclaimable key FAILED. A live credential nobody holds still exists.");
+  }
+  lines.push("");
+  lines.push("Next");
+  for (const action of nextActionsFor(creation, revocation)) lines.push(`  - ${action}`);
+  return lines.join("\n");
+}
+var BASE_URL_FLAG = Object.freeze({
+  name: "base-url",
+  kind: "string",
+  summary: `API base URL. Defaults to ${BASE_URL_ENV_VAR}.`,
+  placeholder: "url"
+});
+var TIMEOUT_FLAG = Object.freeze({
+  name: "timeout",
+  kind: "string",
+  summary: `Per attempt timeout in milliseconds (${MIN_TIMEOUT_MS}-${MAX_TIMEOUT_MS}, default ${DEFAULT_TIMEOUT_MS}).`,
+  placeholder: "ms"
+});
+var REQUEST_ID_FLAG = Object.freeze({
+  name: "request-id",
+  kind: "string",
+  summary: "Correlation id to send. Must be a UUID or 32 hex characters, or the API replaces it.",
+  placeholder: "id"
+});
+var CONTRACT_FLAG = Object.freeze({
+  name: "contract",
+  kind: "string",
+  summary: "Path to a contract-public projection, used to explain any error code returned.",
+  placeholder: "file"
+});
+var CONTRACT_ENV_VAR = "EVERFUR_CONTRACT_PUBLIC";
+var DEFAULT_CONTRACT_PATHS = Object.freeze([
+  "contract-public/contract-public.json",
+  "contract-public.json"
+]);
+function resolveFromCwd(cwd, path) {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+function parseTimeout(raw) {
+  if (raw === null) return { value: DEFAULT_TIMEOUT_MS, errors: [] };
+  const parsed = Number(raw.trim());
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return { value: DEFAULT_TIMEOUT_MS, errors: [`--timeout must be a positive number of milliseconds, not "${raw}"`] };
+  }
+  if (parsed < MIN_TIMEOUT_MS || parsed > MAX_TIMEOUT_MS) {
+    return {
+      value: DEFAULT_TIMEOUT_MS,
+      errors: [`--timeout must be between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS} milliseconds`]
+    };
+  }
+  return { value: parsed, errors: [] };
+}
+function findContractPath(context, flagValue) {
+  if (flagValue !== null) return resolveFromCwd(context.cwd, flagValue);
+  const fromEnv = (context.env[CONTRACT_ENV_VAR] ?? "").trim();
+  if (fromEnv.length > 0) return resolveFromCwd(context.cwd, fromEnv);
+  for (const candidate of DEFAULT_CONTRACT_PATHS) {
+    const full = resolveFromCwd(context.cwd, candidate);
+    if (context.fs.readFile(full) !== null) return full;
+  }
+  return null;
+}
+function setUpWire(context, flags, options = {}) {
+  const errors = [];
+  const endpointResolution = resolveEndpoint(flags.string("base-url"), context.env);
+  if (!endpointResolution.ok) errors.push(...endpointResolution.errors);
+  const timeout = parseTimeout(flags.string("timeout"));
+  errors.push(...timeout.errors);
+  const requestId = flags.string("request-id");
+  if (requestId !== null && !isCorrelatableRequestId(requestId.trim())) {
+    errors.push(
+      "--request-id must be a UUID or 32 hex characters; the API ignores any other shape and stamps its own"
+    );
+  }
+  if (errors.length > 0 || !endpointResolution.ok) {
+    return { ok: false, outcome: errorOutcome("usage_error", "the connection could not be configured", errors) };
+  }
+  const contractFlag = flags.string("contract");
+  const contractPath = findContractPath(context, contractFlag);
+  let registry = EMPTY_REGISTRY;
+  let registrySource = null;
+  if (contractPath !== null) {
+    const load = loadErrorRegistry(context.fs, contractPath);
+    if (load.kind === "loaded") {
+      registry = load.registry;
+      registrySource = load.path;
+    } else if (contractFlag !== null) {
+      return { ok: false, outcome: contractRejection(contractPath, load.kind) };
+    }
+  }
+  return {
+    ok: true,
+    client: createApiClient({
+      transport: context.transport,
+      clock: context.clock,
+      endpoint: endpointResolution.endpoint,
+      registry,
+      timeoutMs: timeout.value,
+      requestId: requestId === null ? null : requestId.trim(),
+      ...options.maxAttempts === void 0 ? {} : { maxAttempts: options.maxAttempts },
+      ...options.retryDelayMs === void 0 ? {} : { retryDelayMs: options.retryDelayMs }
+    }),
+    endpoint: endpointResolution.endpoint,
+    registry,
+    registrySource
+  };
+}
+function contractRejection(path, kind) {
+  return errorOutcome("invalid_contract", `the contract at ${path} could not be used (${kind})`, [
+    "run `everfur contract validate --path <file>` for the specific failure"
+  ]);
+}
+
+// src/commands/verify/index.ts
+var DEFAULT_USER_REF = "everfur-cli-verify";
+var DEFAULT_ATTEMPTS = 3;
+var POLL_DELAY_MS = 500;
+var MAX_ATTEMPTS = 20;
+var VERIFICATION_SCHEMA_VERSION = 1;
+var VERIFICATION_DOCUMENT_KIND = "everfur.verification";
+var FLAGS = Object.freeze([
+  BASE_URL_FLAG,
+  {
+    name: "user-ref",
+    kind: "string",
+    summary: `End user reference to mint a session for. Defaults to ${DEFAULT_USER_REF}.`,
+    placeholder: "ref"
+  },
+  {
+    name: "attempts",
+    kind: "string",
+    summary: `How many times to read the verdict before calling it empty (default ${DEFAULT_ATTEMPTS}).`,
+    placeholder: "n"
+  },
+  CONTRACT_FLAG,
+  TIMEOUT_FLAG,
+  REQUEST_ID_FLAG
+]);
+function buildVerificationDocument(verification, baseUrl, cliVersion) {
+  const counts = { passed: 0, failed: 0, skipped: 0 };
+  for (const entry of verification.steps) {
+    if (entry.result === "PASS") counts.passed += 1;
+    else if (entry.result === "FAIL") counts.failed += 1;
+    else counts.skipped += 1;
+  }
+  return {
+    schemaVersion: VERIFICATION_SCHEMA_VERSION,
+    kind: VERIFICATION_DOCUMENT_KIND,
+    generatedBy: { name: "@everfur/cli", version: cliVersion },
+    status: verification.status,
+    baseUrl,
+    summary: counts,
+    steps: verification.steps.map((entry) => ({
+      id: entry.id,
+      title: entry.title,
+      result: entry.result,
+      reason: entry.reason,
+      requestId: entry.requestId,
+      details: [...entry.details]
+    }))
+  };
+}
+function renderVerification(verification, baseUrl) {
+  const lines = [
+    `everfur verify: ${verification.status}`,
+    "",
+    `  base url: ${baseUrl}`,
+    ""
+  ];
+  for (const entry of verification.steps) {
+    lines.push(`  ${entry.result.padEnd(4)} ${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}`);
+    lines.push("");
+  }
+  if (verification.status === "failed") {
+    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 {
+    lines.push("Every step passed. The session mint, the verdict read, and the verdict itself are all healthy.");
+  }
+  return lines.join("\n");
+}
+function parseAttempts(raw) {
+  if (raw === null) return { value: DEFAULT_ATTEMPTS, errors: [] };
+  const parsed = Number(raw.trim());
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_ATTEMPTS) {
+    return {
+      value: DEFAULT_ATTEMPTS,
+      errors: [`--attempts must be a whole number between 1 and ${MAX_ATTEMPTS}, not "${raw}"`]
+    };
+  }
+  return { value: parsed, errors: [] };
+}
+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]",
+  flags: FLAGS,
+  /** Exactly the pair `mintSession` resolves; without both, step one reports SKIP rather than FAIL. */
+  credentials: Object.freeze([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 wire = setUpWire(context, flags);
+    if (!wire.ok) 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({
+      client: wire.client,
+      clock: context.clock,
+      env: context.env,
+      userRef,
+      attempts: attempts.value,
+      pollDelayMs: POLL_DELAY_MS
+    });
+    const document = buildVerificationDocument(verification, wire.client.baseUrl, context.version);
+    const text = renderVerification(verification, wire.client.baseUrl);
+    switch (verification.status) {
+      case "passed":
+        return succeed(document, text);
+      case "failed":
+        return fail(ExitCode.VERIFICATION_FAILED, document, text);
+      case "incomplete":
+        return fail(ExitCode.UNDERSPECIFIED, document, text);
+    }
+  }
+};
+var FLAGS2 = Object.freeze([
+  {
+    name: "cwd",
+    kind: "string",
+    summary: "Project root to inspect. Defaults to the current working directory.",
+    placeholder: "path"
+  },
+  {
+    name: "capabilities",
+    kind: "string",
+    summary: "Comma separated capability ids. The valid ids come from the contract decision trees.",
+    placeholder: "list"
+  },
+  {
+    name: "identity",
+    kind: "string",
+    summary: "How end users are identified. The valid modes come from the contract decision trees.",
+    placeholder: "mode"
+  },
+  {
+    name: "backend",
+    kind: "string",
+    summary: "Language that mints sessions server side. Required only when the identity mode mints.",
+    placeholder: "language"
+  },
+  CONTRACT_FLAG
+]);
+function asJsonObject(document) {
+  return JSON.parse(JSON.stringify(document));
+}
+function contractOutcome(outcome) {
+  switch (outcome.kind) {
+    case "file_not_found":
+      return errorOutcome("file_not_found", `no readable file at ${outcome.path}`);
+    case "invalid_json":
+      return errorOutcome("invalid_json", `${outcome.path} is not valid JSON`, [outcome.detail]);
+    case "invalid_contract":
+      return errorOutcome(
+        "invalid_contract",
+        `${outcome.path} does not match the contract-public envelope schema`,
+        outcome.violations.map((violation) => `${violation.path}: ${violation.message}`)
+      );
+    case "digest_mismatch":
+      return errorOutcome("digest_mismatch", `${outcome.path} declares a digest that does not match its projection`, [
+        `declared:   ${outcome.digest.expected}`,
+        `recomputed: ${outcome.digest.actual}`,
+        "no plan was built: an edited projection is not a source of truth about what a partner can integrate"
+      ]);
+    /* c8 ignore next 2 -- `valid` never reaches here; the loader returns `loaded` for it. */
+    case "valid":
+      return errorOutcome("internal_error", "a valid contract was reported as rejected");
+  }
+}
+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]",
+  flags: FLAGS2,
+  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") {
+        space = load.space;
+      } else if (contractFlag !== null) {
+        return load.kind === "contract_rejected" ? contractOutcome(load.outcome) : errorOutcome("invalid_contract", `${load.path} carries no decision trees`, [
+          "the projection validated, but it has no `decision-trees.yaml` document with a `trees` list",
+          "this is a projection built before the planner decision trees were published, or a partial one"
+        ]);
+      }
+    }
+    if (space === null && contractPath === null) {
+      const bundled = loadBundledDecisionSpace();
+      if (bundled.kind === "loaded") {
+        space = bundled.space;
+        usedBundledContract = true;
+      }
+    }
+    const supplied = parseSuppliedFacts(
+      flags.string("capabilities"),
+      flags.string("identity"),
+      flags.string("backend"),
+      space
+    );
+    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 detection = detectProject(context.fs, root);
+    const document = planIntegration({
+      detection,
+      capabilities: supplied.capabilities,
+      identityMode: supplied.identityMode,
+      sessionMintLanguage: supplied.sessionMintLanguage,
+      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 === "blocked") return fail(ExitCode.BLOCKED, json, text);
+    return succeed(json, text);
+  }
+};
+
+// src/commands/contract/index.ts
+var FLAGS3 = Object.freeze([
+  {
+    name: "path",
+    kind: "string",
+    summary: "Path to the contract-public projection JSON file.",
+    placeholder: "file",
+    required: true
+  }
+]);
+var contractValidateCommand = {
+  path: ["contract", "validate"],
+  summary: "Validate a contract-public projection: envelope shape, then digest.",
+  usage: "contract validate --path <file> [--json]",
+  flags: FLAGS3,
+  async run(context, flags) {
+    const rawPath = flags.string("path");
+    if (rawPath === null) {
+      return errorOutcome("usage_error", "flag --path is required");
+    }
+    const path = resolveContractPath(context.cwd, rawPath);
+    const outcome = validateContractFile(context.fs, path);
+    switch (outcome.kind) {
+      case "file_not_found":
+        return errorOutcome("file_not_found", `no readable file at ${outcome.path}`);
+      case "invalid_json":
+        return errorOutcome("invalid_json", `${outcome.path} is not valid JSON`, [outcome.detail]);
+      case "invalid_contract":
+        return errorOutcome(
+          "invalid_contract",
+          `${outcome.path} does not match the contract-public envelope schema`,
+          outcome.violations.map((violation) => `${violation.path}: ${violation.message}`)
+        );
+      case "digest_mismatch":
+        return errorOutcome(
+          "digest_mismatch",
+          `${outcome.path} declares a digest that does not match its projection`,
+          [
+            `declared:   ${outcome.digest.expected}`,
+            `recomputed: ${outcome.digest.actual}`,
+            "The projection was edited after the digest was written, or the two came from different builds."
+          ]
+        );
+      case "valid": {
+        const json = {
+          schemaVersion: 1,
+          kind: "everfur.contract-validation",
+          status: "valid",
+          path: outcome.path,
+          generatedAt: outcome.generatedAt,
+          digest: { algorithm: "sha256", value: outcome.digest.actual },
+          projectionKeys: outcome.projectionKeys
+        };
+        const text = [
+          `contract validate: ok`,
+          `  file:            ${outcome.path}`,
+          `  generated at:    ${outcome.generatedAt}`,
+          `  digest (sha256): ${outcome.digest.actual}`,
+          `  projection keys: ${outcome.projectionKeys.join(", ")}`
+        ].join("\n");
+        return succeed(json, text);
+      }
+    }
+  }
+};
+
+// 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,
+  {
+    name: "user-ref",
+    kind: "string",
+    summary: "End user reference to diagnose as. Omit to diagnose the anonymous subject.",
+    placeholder: "ref"
+  },
+  CONTRACT_FLAG,
+  TIMEOUT_FLAG,
+  REQUEST_ID_FLAG
+]);
+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]",
+  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;
+    const auth = chooseWidgetAuth(context.env);
+    if (!auth.ok) return auth.outcome;
+    const userRef = flags.string("user-ref");
+    const headers = {};
+    if (userRef !== null && userRef.trim().length > 0) {
+      headers["x-everfur-user-ref"] = userRef.trim();
+    }
+    const result = await wire.client.request({
+      method: "GET",
+      path: DIAGNOSTICS_PATH,
+      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"
+      ]);
+    }
+    const parsed = parseDiagnostics(result.value, result.requestId);
+    if (!parsed.ok) {
+      return errorOutcome(
+        "malformed_response",
+        `${DIAGNOSTICS_PATH} answered ${result.status} with a body this CLI does not recognise`,
+        [
+          parsed.detail,
+          result.requestId === null ? "the response carried no request id" : `request id: ${result.requestId}`,
+          "check that --base-url points at the Everfur API and not at a proxy or login page"
+        ]
+      );
+    }
+    const document = buildDiagnosisDocument({
+      diagnosis: parsed.diagnosis,
+      baseUrl: wire.client.baseUrl,
+      path: DIAGNOSTICS_PATH,
+      cliVersion: context.version
+    });
+    return succeed(document, renderDiagnosis({ diagnosis: parsed.diagnosis, baseUrl: wire.client.baseUrl }));
+  }
+};
+
+// src/commands/explain-error/index.ts
+var FLAGS5 = Object.freeze([CONTRACT_FLAG]);
+var POSITIONALS = Object.freeze([
+  {
+    name: "code",
+    summary: "The wire error code, exactly as the response carried it. Case sensitive.",
+    required: true
+  }
+]);
+var explainErrorCommand = {
+  path: ["explain-error"],
+  summary: "Explain an API error code: cause, retryability, and next action.",
+  usage: "explain-error <code> [--contract <file>] [--json]",
+  flags: FLAGS5,
+  positionals: POSITIONALS,
+  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 contractFlag = flags.string("contract");
+    const contractPath = findContractPath(context, contractFlag);
+    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 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",
+        "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);
+      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`
+      ]);
+    }
+    const input = {
+      entry,
+      contractPath: load.path,
+      digest: load.digest,
+      cliVersion: context.version
+    };
+    return succeed(buildExplanationDocument(input), renderExplanation(input));
+  }
+};
+function contractOutcome2(outcome) {
+  switch (outcome.kind) {
+    case "file_not_found":
+      return errorOutcome("file_not_found", `no readable file at ${outcome.path}`);
+    case "invalid_json":
+      return errorOutcome("invalid_json", `${outcome.path} is not valid JSON`, [outcome.detail]);
+    case "invalid_contract":
+      return errorOutcome(
+        "invalid_contract",
+        `${outcome.path} does not match the contract-public envelope schema`,
+        outcome.violations.map((violation) => `${violation.path}: ${violation.message}`)
+      );
+    case "digest_mismatch":
+      return errorOutcome("digest_mismatch", `${outcome.path} declares a digest that does not match its projection`, [
+        `declared:   ${outcome.digest.expected}`,
+        `recomputed: ${outcome.digest.actual}`,
+        "the registry was not read: an edited projection is not a source of truth about error codes"
+      ]);
+    /* c8 ignore next 2 -- `valid` never reaches here; the loader returns `loaded` for it. */
+    case "valid":
+      return errorOutcome("internal_error", "a valid contract was reported as rejected");
+  }
+}
+
+// src/commands/sandbox/index.ts
+var FLAGS6 = Object.freeze([
+  {
+    name: "client",
+    kind: "string",
+    summary: "Client UUID to provision the key for.",
+    placeholder: "client-id",
+    required: true
+  },
+  {
+    name: "label",
+    kind: "string",
+    summary: 'Human readable label stored with the key, for example "sandbox laptop".',
+    placeholder: "text"
+  },
+  BASE_URL_FLAG,
+  CONTRACT_FLAG,
+  TIMEOUT_FLAG,
+  REQUEST_ID_FLAG
+]);
+var sandboxCreateCommand = {
+  path: ["sandbox", "create"],
+  summary: "Provision a partner secret key and return a claim URL. Never prints the secret.",
+  usage: "sandbox create --client <client-id> [--label <text>] [--base-url <url>] [--json]",
+  flags: FLAGS6,
+  /** The one credential this command resolves. It never reads a partner key of either kind. */
+  credentials: Object.freeze([ADMIN_TOKEN]),
+  async run(context, flags) {
+    const clientId = (flags.string("client") ?? "").trim();
+    if (clientId.length === 0) {
+      return errorOutcome("usage_error", "flag --client is required", [
+        "pass the client UUID the key should belong to"
+      ]);
+    }
+    const wire = setUpWire(context, flags);
+    if (!wire.ok) 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", [
+        admin.reason ?? `${ADMIN_TOKEN.envVar} is not set`,
+        `export ${ADMIN_TOKEN.envVar} with an admin bearer token`
+      ]);
+    }
+    const path = `/admin/clients/${encodeURIComponent(clientId)}/secret-keys`;
+    const label = flags.string("label");
+    const body = { label: label === null ? null : label.trim() };
+    const result = await wire.client.request({
+      method: "POST",
+      path,
+      credentials: { authorization: withPrefix(admin.credential, "Bearer ") },
+      body
+    });
+    if (!result.ok) {
+      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) {
+      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}`,
+        "a key MAY have been created; list the client's keys before retrying"
+      ]);
+    }
+    let revocation = "not_needed";
+    if (projected.creation.status === "claim_unavailable") {
+      const revoke = await wire.client.request({
+        method: "DELETE",
+        path: revokePathFor(projected.creation),
+        credentials: { authorization: withPrefix(admin.credential, "Bearer ") },
+        /** 404 means the key is already gone, which is the outcome this call wanted. */
+        acceptStatuses: [404]
+      });
+      revocation = revoke.ok ? "revoked" : "revoke_failed";
+    }
+    const document = buildSandboxDocument({
+      creation: projected.creation,
+      revocation,
+      requestId: result.requestId,
+      cliVersion: context.version
+    });
+    const text = renderSandboxCreate(projected.creation, revocation, result.requestId);
+    return projected.creation.status === "claim_issued" ? succeed(document, text) : fail(ExitCode.SECRET_UNCLAIMABLE, document, text);
+  }
+};
+
+// src/cli/registry.ts
+var COMMANDS = Object.freeze([
+  planCommand,
+  contractValidateCommand,
+  diagnoseCommand,
+  sandboxCreateCommand,
+  verifyCommand,
+  explainErrorCommand
+]);
+function matchCommand(path, commands = COMMANDS) {
+  const ordered = [...commands].sort((left, right) => right.path.length - left.path.length);
+  for (const command of ordered) {
+    if (command.path.length > path.length) continue;
+    const matches = command.path.every((token, index) => path[index] === token);
+    if (matches) return { command, consumed: command.path.length };
+  }
+  return null;
+}
+
+// src/cli/argv.ts
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "cwd",
+  "capabilities",
+  "identity",
+  "backend",
+  "path",
+  "base-url",
+  "contract",
+  "client",
+  "label",
+  "user-ref",
+  "timeout",
+  "attempts",
+  "request-id"
+]);
+var ALIASES = Object.freeze({
+  h: "help",
+  v: "version",
+  C: "cwd"
+});
+function isFlagToken(token) {
+  return token.startsWith("--") || token.startsWith("-") && token.length > 1 && !token.startsWith("--");
+}
+function normaliseName(raw) {
+  if (raw.startsWith("--")) return raw.slice(2);
+  const short = raw.slice(1);
+  return ALIASES[short] ?? short;
+}
+function parseArgv(argv) {
+  const path = [];
+  const flags = /* @__PURE__ */ new Map();
+  const errors = [];
+  let sawFlag = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === void 0) continue;
+    if (token === "--") break;
+    if (!isFlagToken(token)) {
+      if (sawFlag) {
+        errors.push(`unexpected argument "${token}" after flags began`);
+      } else {
+        path.push(token);
+      }
+      continue;
+    }
+    sawFlag = true;
+    const equalsAt = token.indexOf("=");
+    const rawName = equalsAt === -1 ? token : token.slice(0, equalsAt);
+    const inlineValue = equalsAt === -1 ? null : token.slice(equalsAt + 1);
+    const name = normaliseName(rawName);
+    if (name.length === 0) {
+      errors.push(`malformed flag "${token}"`);
+      continue;
+    }
+    const duplicate = flags.has(name);
+    if (duplicate) errors.push(`flag --${name} was given more than once`);
+    if (inlineValue !== null) {
+      if (!duplicate) flags.set(name, inlineValue);
+      continue;
+    }
+    if (!VALUE_FLAGS.has(name)) {
+      if (!duplicate) flags.set(name, true);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next === void 0 || isFlagToken(next)) {
+      if (!duplicate) errors.push(`flag --${name} requires a value`);
+      continue;
+    }
+    index += 1;
+    if (!duplicate) flags.set(name, next);
+  }
+  return Object.freeze({ path: Object.freeze(path), flags, errors: Object.freeze(errors) });
+}
+
+// src/cli/command.ts
+function commandName(command) {
+  return command.path.join(" ");
+}
+
+// src/cli/flags.ts
+var GLOBAL_FLAGS = Object.freeze([
+  { name: "json", kind: "boolean", summary: "Emit the machine document on stdout instead of human text." },
+  { name: "help", kind: "boolean", summary: "Show usage for this command." }
+]);
+var EMPTY_BOUND = Object.freeze({
+  string: () => null,
+  boolean: () => false
+});
+function bindFlags(specs, parsed) {
+  const all = [...specs, ...GLOBAL_FLAGS];
+  const byName = new Map(all.map((spec) => [spec.name, spec]));
+  const errors = [...parsed.errors];
+  const values = /* @__PURE__ */ new Map();
+  for (const [name, value] of parsed.flags) {
+    const spec = byName.get(name);
+    if (spec === void 0) {
+      errors.push(`unknown flag --${name}`);
+      continue;
+    }
+    if (spec.kind === "boolean" && typeof value === "string") {
+      errors.push(`flag --${name} does not take a value`);
+      continue;
+    }
+    if (spec.kind === "string" && value === true) {
+      errors.push(`flag --${name} requires a value`);
+      continue;
+    }
+    values.set(name, value);
+  }
+  for (const spec of all) {
+    if (spec.required === true && !values.has(spec.name)) {
+      errors.push(`flag --${spec.name} is required`);
+    }
+  }
+  if (errors.length > 0) {
+    return Object.freeze({ ok: false, flags: EMPTY_BOUND, errors: Object.freeze(errors) });
+  }
+  const flags = Object.freeze({
+    string: (name) => {
+      const value = values.get(name);
+      return typeof value === "string" ? value : null;
+    },
+    boolean: (name) => values.get(name) === true
+  });
+  return Object.freeze({ ok: true, flags, errors: Object.freeze([]) });
+}
+
+// src/cli/help.ts
+var NOT_IN_THIS_RELEASE = Object.freeze(["login", "test message"]);
+var FLAG_COLUMN = 34;
+function renderFlag(spec) {
+  const placeholder = spec.kind === "string" ? ` <${spec.placeholder ?? "value"}>` : "";
+  const required = spec.required === true ? " (required)" : "";
+  return `    --${spec.name}${placeholder}`.padEnd(FLAG_COLUMN) + `${spec.summary}${required}`;
+}
+function renderRootHelp(commands, version) {
+  const lines = [
+    `everfur ${version}`,
+    "Integration planner and contract validator for the Everfur partner platform.",
+    "",
+    "Usage",
+    "  everfur <command> [flags]",
+    "",
+    "Commands"
+  ];
+  for (const command of commands) {
+    lines.push(`  ${commandName(command).padEnd(20)}${command.summary}`);
+  }
+  lines.push("", "Global flags");
+  for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
+  lines.push("    --version".padEnd(FLAG_COLUMN) + "Print the CLI version.");
+  lines.push(...environmentBlock(CREDENTIAL_SPECS));
+  lines.push(
+    "",
+    "Not in this release",
+    `  ${NOT_IN_THIS_RELEASE.join(", ")}`,
+    "  These are unbuilt. See ROADMAP.md. They are absent rather than stubbed on purpose."
+  );
+  return lines.join("\n");
+}
+function environmentBlock(specs) {
+  const lines = ["", "Environment"];
+  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + "API base URL. Overridden by --base-url.");
+  for (const spec of specs) {
+    lines.push(`    ${spec.envVar}`.padEnd(FLAG_COLUMN) + spec.summary);
+  }
+  lines.push(
+    "    Credentials are read from these variables only. No .env file is read, and no value",
+    "    is ever printed, logged, or written into a --json document."
+  );
+  return lines;
+}
+function renderCommandHelp(command) {
+  const lines = [
+    commandName(command),
+    `  ${command.summary}`,
+    "",
+    "Usage",
+    `  everfur ${command.usage}`
+  ];
+  const positionals = command.positionals ?? [];
+  if (positionals.length > 0) {
+    lines.push("", "Arguments");
+    for (const spec of positionals) {
+      const required = spec.required ? "" : " (optional)";
+      lines.push(`    <${spec.name}>`.padEnd(FLAG_COLUMN) + `${spec.summary}${required}`);
+    }
+  }
+  if (command.flags.length > 0) {
+    lines.push("", "Flags");
+    for (const spec of command.flags) lines.push(renderFlag(spec));
+  }
+  lines.push("", "Global flags");
+  for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
+  const credentials = command.credentials ?? [];
+  if (credentials.length > 0) lines.push(...environmentBlock(credentials));
+  return lines.join("\n");
+}
+
+// src/cli/run.ts
+async function runCli(options) {
+  const commands = options.commands ?? COMMANDS;
+  const parsed = parseArgv(options.argv);
+  const wantsJson = parsed.flags.get("json") === true;
+  const format = { json: wantsJson };
+  if (parsed.path.length === 0) {
+    if (parsed.flags.get("version") === true) {
+      return formatOutcome(
+        succeed({ schemaVersion: 1, kind: "everfur.version", version: options.context.version }, options.context.version),
+        format
+      );
+    }
+    const help = renderRootHelp(commands, options.context.version);
+    if (parsed.flags.get("help") === true) {
+      return formatOutcome(succeed({ schemaVersion: 1, kind: "everfur.help", text: help }, help), format);
+    }
+    return formatOutcome(
+      errorOutcome("usage_error", "no command given", ["run `everfur --help` for the command list"]),
+      format
+    );
+  }
+  const match = matchCommand(parsed.path, commands);
+  if (match === null) {
+    return formatOutcome(
+      errorOutcome("unknown_command", `unknown command "${parsed.path.join(" ")}"`, [
+        `available: ${commands.map(commandName).join(", ")}`,
+        "run `everfur --help` for the full list, including what is deliberately not in this release"
+      ]),
+      format
+    );
+  }
+  const positionals = parsed.path.slice(match.consumed);
+  const specs = match.command.positionals ?? [];
+  if (positionals.length > specs.length) {
+    const surplus = positionals[specs.length] ?? "";
+    return formatOutcome(
+      errorOutcome("usage_error", `unexpected argument "${surplus}" after "${commandName(match.command)}"`, [
+        `usage: everfur ${match.command.usage}`
+      ]),
+      format
+    );
+  }
+  const missingPositionals = specs.filter((spec, index) => spec.required && (positionals[index] ?? "").length === 0).map((spec) => `<${spec.name}> is required`);
+  if (missingPositionals.length > 0 && parsed.flags.get("help") !== true) {
+    return formatOutcome(
+      errorOutcome("usage_error", `invalid invocation of "${commandName(match.command)}"`, [
+        ...missingPositionals,
+        `usage: everfur ${match.command.usage}`
+      ]),
+      format
+    );
+  }
+  if (parsed.flags.get("help") === true) {
+    const help = renderCommandHelp(match.command);
+    return formatOutcome(succeed({ schemaVersion: 1, kind: "everfur.help", text: help }, help), format);
+  }
+  const bound = bindFlags(match.command.flags, parsed);
+  if (!bound.ok) {
+    return formatOutcome(
+      errorOutcome("usage_error", `invalid invocation of "${commandName(match.command)}"`, [
+        ...bound.errors,
+        `usage: everfur ${match.command.usage}`
+      ]),
+      format
+    );
+  }
+  try {
+    const outcome = await match.command.run(options.context, bound.flags, positionals);
+    return formatOutcome(outcome, format);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return formatOutcome(
+      errorOutcome("internal_error", `"${commandName(match.command)}" failed unexpectedly`, [message]),
+      format
+    );
+  }
+}
+
+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 };