@everfur/cli 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -32,11 +32,12 @@ interface CredentialSpec {
     /**
      * Additional accepted prefixes, beyond `prefix`.
      *
-     * A publishable key is `pk_live_` on a production deployment and `pk_test_` on a sandbox one, and the
-     * CLI cannot tell which host it is pointed at before it makes a call. Hardcoding one of them would make
-     * the CLI reject exactly the sandbox credentials the platform now issues, which is the opposite of what
-     * a test-mode tool should do. The SERVER is the authority: it accepts one prefix per deployment and
-     * refuses the other on the fast-fail path, so accepting both here narrows nothing.
+     * The prefix a publishable key must carry is a property of the DEPLOYMENT, not of the tenant: production and
+     * staging both take `pk_live_` (a staging sandbox tenant is issued a `pk_live_` key and refuses `pk_test_`), and
+     * `pk_test_` is the prefix a deployment configured as a sandbox deployment would take instead; no deployed
+     * environment is configured that way today, so no deployed environment accepts it. The CLI cannot tell which
+     * deployment it is pointed at before it makes a call, so it accepts both shapes. The SERVER is the authority: each
+     * deployment refuses the prefix it does not take on the fast-fail path, so accepting both here narrows nothing.
      */
     readonly alsoAccepts?: readonly string[];
     /** Exact expected length when the prefix is known, or null. */
@@ -63,6 +64,12 @@ interface ResolvedCredential {
     readonly credential: Credential | null;
     /** Why the value was rejected. Names the variable and the expected shape, never the value. */
     readonly reason: string | null;
+    /**
+     * Which accepted prefix a `present` value starts with (`pk_live_` or `pk_test_`), or null for an
+     * opaque credential or one that is not present. A prefix is a public fact about the key, so a
+     * caller that needs it reads it here instead of reading the raw value out of the environment.
+     */
+    readonly matchedPrefix: string | null;
 }
 /**
  * Wrap a value that did NOT come from the environment, for example a session token the CLI just
@@ -87,6 +94,28 @@ declare function withPrefix(credential: Credential, prefix: string): Credential;
  */
 declare function resolveCredential(env: Readonly<Record<string, string | undefined>>, spec: CredentialSpec): ResolvedCredential;
 
+/**
+ * WHERE A FETCHED CONTRACT IS KEPT BETWEEN RUNS.
+ *
+ * The contract is served only to an authenticated partner (`GET /partners/contract`), so every
+ * command that needs it would otherwise make a network call per run. The route answers an ETag that
+ * IS the contract digest, so a cached copy costs one conditional request and an empty 304 while it is
+ * current, and is replaced the moment the platform publishes a new one.
+ *
+ * A PORT, NOT A MODULE-LEVEL FILESYSTEM, for the same reason `FileSystemPort` is one: commands stay pure
+ * functions over injected dependencies and a test never touches a real directory. Only the bin shims and
+ * the MCP server construct the node adapter.
+ *
+ * Writes never throw. A read-only home directory or a full disk degrades to fetching every time, which is
+ * slower and still correct; failing a plan because a cache could not be written would not be.
+ */
+interface ContractCachePort {
+    /** The entry's contents, or null when absent or unreadable. */
+    read(name: string): string | null;
+    /** Store an entry. Best effort: a failure is swallowed and the next run fetches again. */
+    write(name: string, contents: string): void;
+}
+
 /**
  * The filesystem seam. Detection and contract loading are pure functions over this interface,
  * which is the whole reason they can be tested against fixtures without a temp directory
@@ -105,6 +134,11 @@ interface FileSystemPort {
     exists(path: string): boolean;
     /** True when the path exists and is a directory. */
     isDirectory(path: string): boolean;
+    /**
+     * The names of a directory's direct entries, sorted, or null when the path is not a readable directory. Used only
+     * by the offline project checks of `verify`, which have to find a secret wherever it was written.
+     */
+    listDirectory(path: string): readonly string[] | null;
 }
 
 /**
@@ -116,7 +150,8 @@ interface FileSystemPort {
  * a `CommandOutcome`: it holds the credential headers, and an outcome is a thing the formatter
  * prints. Failures carry the method, the path, and the request id, never the request object.
  */
-type HttpMethod = 'GET' | 'POST' | 'DELETE';
+/** OPTIONS is sent only by the web checks' CORS preflight, directly through a transport, never retried. */
+type HttpMethod = 'GET' | 'POST' | 'DELETE' | 'OPTIONS';
 /** Methods that may be retried. A retry of anything else could mint a second credential. */
 declare const IDEMPOTENT_METHODS: readonly HttpMethod[];
 interface HttpRequest {
@@ -304,6 +339,11 @@ interface CommandContext {
     readonly transport: TransportPort;
     /** Waiting, injected so a poll loop in a test costs nothing. */
     readonly clock: ClockPort;
+    /**
+     * Where a contract fetched from `GET /partners/contract` is kept between runs. Absent means nothing is
+     * cached and every run that needs the contract fetches it. `src/bin` supplies the one real adapter.
+     */
+    readonly contractCache?: ContractCachePort;
 }
 /**
  * A positional argument. Declared as data beside the flags so `--help` documents it and the
@@ -334,7 +374,7 @@ interface Command {
      * The credentials this command can actually use, declared as data for the same reason the
      * flags are: `--help` renders what the command declares, so a credential a command reads is a
      * credential its own help names. Absent means the command touches none, which is the truth
-     * for `plan`, `contract validate`, and `explain-error`.
+     * for `contract validate`.
      *
      * This exists because per-command help used to render only the flags. A partner told to run
      * one command had no way to learn from the tool that they must export EVERFUR_PARTNER_KEY;
@@ -438,6 +478,10 @@ declare const fetchTransport: TransportPort;
  * `API_PREFIX` is appended by this module rather than being part of what the operator types,
  * because it is a deployment fact of the API and not a choice. A base URL that already ends in
  * the prefix is accepted as-is, so both spellings work and neither doubles up.
+ *
+ * HTTPS, EXCEPT ON THIS MACHINE. Every networked command sends a credential to this base (the partner
+ * key, the secret key, the docs key), so plain `http:` is accepted only for `localhost`, `127.0.0.1`
+ * and `[::1]`, where a local API runs. Anything else must be https.
  */
 declare const BASE_URL_ENV_VAR = "EVERFUR_API_BASE_URL";
 /** `app/main.py` mounts every router used here at `settings.api_prefix`. */
@@ -571,6 +615,26 @@ declare const SCHEMAS: Readonly<{
                             type?: never;
                         })[];
                     };
+                    embedding: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            $ref?: never;
+                        } | {
+                            $ref: string;
+                            type?: never;
+                        })[];
+                    };
+                    environment: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            enum?: never;
+                        } | {
+                            enum: string[];
+                            type?: never;
+                        })[];
+                    };
                 };
             };
             missingFacts: {
@@ -605,6 +669,16 @@ declare const SCHEMAS: Readonly<{
                     $ref: string;
                 };
             };
+            platformBlock: {
+                description: string;
+                oneOf: ({
+                    type: string;
+                    $ref?: never;
+                } | {
+                    $ref: string;
+                    type?: never;
+                })[];
+            };
             decisionSpace: {
                 description: string;
                 oneOf: ({
@@ -746,6 +820,159 @@ declare const SCHEMAS: Readonly<{
                             $ref: string;
                         };
                     };
+                    webEmbedding: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            $ref?: never;
+                        } | {
+                            $ref: string;
+                            type?: never;
+                        })[];
+                    };
+                    webFramework: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            enum?: never;
+                        } | {
+                            enum: string[];
+                            type?: never;
+                        })[];
+                    };
+                    theme: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            $ref?: never;
+                        } | {
+                            $ref: string;
+                            type?: never;
+                        })[];
+                    };
+                };
+            };
+            ThemeToken: {
+                enum: string[];
+            };
+            ThemeDetection: {
+                type: string;
+                required: string[];
+                properties: {
+                    source: {
+                        enum: string[];
+                    };
+                    confidence: {
+                        enum: string[];
+                    };
+                    theme: {
+                        description: string;
+                        type: string;
+                        properties: {
+                            primaryColor: {
+                                type: string;
+                                pattern: string;
+                            };
+                            accentColor: {
+                                type: string;
+                                pattern: string;
+                            };
+                            primaryColorDark: {
+                                type: string;
+                                pattern: string;
+                            };
+                            accentColorDark: {
+                                type: string;
+                                pattern: string;
+                            };
+                            brightness: {
+                                enum: string[];
+                            };
+                            surfaceStyle: {
+                                enum: string[];
+                            };
+                            radiusScale: {
+                                enum: string[];
+                            };
+                            fontFamily: {
+                                type: string;
+                                minLength: number;
+                            };
+                            fontRegular: {
+                                type: string;
+                                minLength: number;
+                                description: string;
+                            };
+                            fontMedium: {
+                                type: string;
+                                minLength: number;
+                                description: string;
+                            };
+                            fontBold: {
+                                type: string;
+                                minLength: number;
+                                description: string;
+                            };
+                        };
+                        additionalProperties: boolean;
+                    };
+                    evidence: {
+                        type: string;
+                        items: {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                file: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                line: {
+                                    type: string;
+                                    minimum: number;
+                                };
+                                key: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                value: {
+                                    type: string;
+                                };
+                                token: {
+                                    oneOf: ({
+                                        type: string;
+                                        $ref?: never;
+                                    } | {
+                                        $ref: string;
+                                        type?: never;
+                                    })[];
+                                };
+                                reason: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                            };
+                        };
+                    };
+                    scanned: {
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    missing: {
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    inferred: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                    };
                 };
             };
             Dependency: {
@@ -802,6 +1029,28 @@ declare const SCHEMAS: Readonly<{
                             minLength: number;
                         };
                     };
+                    blockedBy: {
+                        description: string;
+                        enum: string[];
+                    };
+                };
+            };
+            PlatformBlock: {
+                type: string;
+                required: string[];
+                properties: {
+                    reason: {
+                        type: string;
+                        minLength: number;
+                    };
+                    unblockOwner: {
+                        type: string;
+                        minLength: number;
+                    };
+                    requestPath: {
+                        type: string;
+                        pattern: string;
+                    };
                 };
             };
             PlanPrinciple: {
@@ -1117,6 +1366,18 @@ declare const SCHEMAS: Readonly<{
                     $ref: string;
                 };
             };
+            switches: {
+                description: string;
+                oneOf: ({
+                    type: string;
+                    items?: never;
+                } | {
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                })[];
+            };
         };
         $defs: {
             GeneratedBy: {
@@ -1187,6 +1448,54 @@ declare const SCHEMAS: Readonly<{
                     };
                 };
             };
+            SwitchDiagnosis: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        description: string;
+                        type: string;
+                        minLength: number;
+                    };
+                    enabled: {
+                        description: string;
+                        oneOf: {
+                            type: string;
+                        }[];
+                    };
+                    kind: {
+                        description: string;
+                        enum: string[];
+                    };
+                    gates: {
+                        description: string;
+                        type: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    tenantTerm: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            minLength?: never;
+                        } | {
+                            type: string;
+                            minLength: number;
+                        })[];
+                    };
+                    reason: {
+                        description: string;
+                        type: string;
+                    };
+                    nextAction: {
+                        description: string;
+                        type: string;
+                        minLength: number;
+                    };
+                };
+            };
         };
     };
     sandboxCreate: {
@@ -1370,6 +1679,11 @@ declare const SCHEMAS: Readonly<{
                         type: string;
                         minimum: number;
                     };
+                    gated: {
+                        description: string;
+                        type: string;
+                        minimum: number;
+                    };
                 };
             };
             steps: {
@@ -1388,6 +1702,7 @@ declare const SCHEMAS: Readonly<{
                             minLength: number;
                         };
                         result: {
+                            description: string;
                             enum: string[];
                         };
                         reason: {
@@ -1616,7 +1931,14 @@ interface ErrorRegistryEntry {
     readonly note: string;
 }
 interface ErrorRegistry {
+    /**
+     * The row for a code. A code can ride both envelopes as two rows (`unavailable`: the 503 body and the SSE frame a
+     * partner chat turn ends with); this answers the HTTP row then, and `lookupAll` answers both.
+     */
     lookup(code: string): ErrorRegistryEntry | null;
+    /** Every row for a code, one per envelope it is registered on. Empty for an unknown code. */
+    lookupAll(code: string): readonly ErrorRegistryEntry[];
+    /** The distinct codes, sorted. */
     readonly codes: readonly string[];
 }
 /**
@@ -1660,6 +1982,8 @@ interface ApiSuccess<T> {
     /** The server's id, or null when the response carried none. */
     readonly requestId: string | null;
     readonly attempts: number;
+    /** The response headers, names lowercased by the adapter. A check on what a browser could read needs them. */
+    readonly headers: Readonly<Record<string, string>>;
 }
 type ApiFailure = {
     readonly ok: false;
@@ -1728,6 +2052,11 @@ interface ApiClientOptions {
     readonly maxAttempts?: number;
     /** Delay between attempts, in milliseconds. */
     readonly retryDelayMs?: number;
+    /**
+     * The `x-everfur-sdk-platform` every /widget/v1 call sends (`sdkClientHeaders`). Default `cli`; a caller that read
+     * the project passes `sdkPlatformForProjectType` of it. A header the request itself names always wins.
+     */
+    readonly sdkPlatform?: string;
 }
 interface RequestSpec {
     readonly method: HttpMethod;
@@ -1739,11 +2068,18 @@ interface RequestSpec {
     readonly body?: JsonValue;
     /** Statuses that are a successful outcome for this call, in addition to 2xx. */
     readonly acceptStatuses?: readonly number[];
+    /**
+     * `text` hands back the accepted body as the raw string instead of parsing it, for a route that
+     * answers `text/event-stream`. A failure body is still read for its wire code either way.
+     */
+    readonly responseType?: 'json' | 'text';
 }
 interface ApiClient {
     request(spec: RequestSpec): Promise<ApiResult<JsonValue>>;
     /** The resolved base URL, for reporting. Never a credential. */
     readonly baseUrl: string;
+    /** The absolute URL `request` would call for `path`, for a probe that goes straight to a transport. */
+    urlFor(path: string): string;
 }
 declare function clampTimeout(value: number): number;
 /** True when the value is a shape `RequestIDMiddleware` will reuse rather than replace. */
@@ -1783,6 +2119,38 @@ declare function failureDetails(failure: ApiFailure): readonly string[];
 
 declare function failureOutcome(failure: ApiFailure, extraDetails?: readonly string[]): CommandOutcome;
 
+/**
+ * WHY A CAPABILITY IS UNAVAILABLE, and what to do about it.
+ *
+ * The nine codes are the platform's own `DiagnosticsReasonCode`, which exists because an empty
+ * `capabilities:{}` verdict has five byte-identical causes and the render payload deliberately
+ * carries no "why". The server sends the code and its own safe copy; this table adds the part
+ * the server cannot know, which is what the PARTNER should do next.
+ *
+ * The distinction that makes this table worth having: three of these are somebody else's job
+ * (`scope_not_provisioned`, `not_in_grant`, `runtime_gate_off`), one is a commercial
+ * conversation (`outside_ceiling`), one is deliberate configuration (`capability_denied`), one
+ * is transient (`resolver_unavailable`), and one is a bug to report (`gate_unknown`). A single
+ * "the feature is unavailable" message collapses all seven into one wrong next step.
+ *
+ * An UNKNOWN code is not an error. The enum grows when the platform grows a new decision point,
+ * and a CLI that rejected the answer would be useless exactly when something new broke. It
+ * renders the code verbatim with an upgrade instruction.
+ */
+declare const REASON_CODES: readonly ["granted", "scope_not_provisioned", "capability_denied", "outside_ceiling", "not_in_grant", "runtime_gate_off", "gate_unknown", "platform_invariant", "resolver_unavailable"];
+type ReasonCode = (typeof REASON_CODES)[number];
+declare function isKnownReasonCode(value: string): value is ReasonCode;
+/** The next action for a code, including one this CLI has never heard of. */
+declare function nextActionFor$1(code: string): string;
+/**
+ * What a partner switch is. A ROUTE GATE opens or closes partner routes (off, they answer 404). A POSTURE changes how
+ * routes behave and is often off by design: `partner.min_version_gate_enabled` is inert off, and
+ * `partner.sessions_required` or `partner.transcript_consent_required` armed would refuse callers. UNKNOWN is an entry
+ * that neither says which it is nor names what it gates.
+ */
+declare const SWITCH_KINDS: readonly ["route_gate", "posture", "unknown"];
+type SwitchKind = (typeof SWITCH_KINDS)[number];
+
 /**
  * Narrow `GET /widget/v1/diagnostics` into the CLI's own shape.
  *
@@ -1814,6 +2182,35 @@ interface ScopeLevelDiagnosis {
     readonly kind: string;
     readonly present: boolean;
 }
+/**
+ * One partner switch that governs a partner-facing route, as the diagnostics block reports it.
+ *
+ * The capability list alone cannot say why a granted surface's routes 404: five switches have a capability gate
+ * (records, records clinic, Televet, records push, server pets), and the rest (notifications, webhooks, records depth,
+ * the Televet sub-features, follow-ups, branding and more) had none, so a partner whose switch was off was told
+ * everything was granted. The CLI renders EVERY switch the backend sends, keyed by its name, in the order sent:
+ * there is no list of known switches here to fall behind the platform.
+ */
+interface SwitchDiagnosis {
+    /** The switch's name as the backend sends it, e.g. `partner.notifications_enabled`. */
+    readonly name: string;
+    /** On, off, or null when the entry carried no state this CLI can read. */
+    readonly enabled: boolean | null;
+    /**
+     * A route gate (off, its routes 404), a posture (changes behaviour, often off by design), or unknown. The backend's
+     * `kind` when it sends one; otherwise a switch that names what it gates is a route gate, and one that names nothing
+     * is unknown. Only a route gate is ever told to ask Everfur to switch it on.
+     */
+    readonly kind: SwitchKind;
+    /** What it governs, as the backend names it: routes, capabilities or a description. */
+    readonly gates: readonly string[];
+    /** The tenant-level feature term the switch pairs with, when it has one. */
+    readonly tenantTerm: string | null;
+    /** The server's own copy for the switch, or ''. */
+    readonly reason: string;
+    /** CLI-authored. What the partner should do; see `reasons.ts`. */
+    readonly nextAction: string;
+}
 interface Diagnosis {
     readonly requestId: string | null;
     readonly evaluatedAt: string;
@@ -1836,6 +2233,11 @@ interface Diagnosis {
         readonly levels: readonly ScopeLevelDiagnosis[];
     };
     readonly capabilities: readonly CapabilityDiagnosis[];
+    /**
+     * The partner switches, or null when the response carried no switches block (a deployment older than it). An
+     * empty array is a deployment that reports switches and has none to report.
+     */
+    readonly switches: readonly SwitchDiagnosis[] | null;
 }
 type DiagnosisParse = {
     readonly ok: true;
@@ -1868,30 +2270,6 @@ interface DiagnosisRenderInput {
 }
 declare function renderDiagnosis(input: DiagnosisRenderInput): string;
 
-/**
- * WHY A CAPABILITY IS UNAVAILABLE, and what to do about it.
- *
- * The nine codes are the platform's own `DiagnosticsReasonCode`, which exists because an empty
- * `capabilities:{}` verdict has five byte-identical causes and the render payload deliberately
- * carries no "why". The server sends the code and its own safe copy; this table adds the part
- * the server cannot know, which is what the PARTNER should do next.
- *
- * The distinction that makes this table worth having: three of these are somebody else's job
- * (`scope_not_provisioned`, `not_in_grant`, `runtime_gate_off`), one is a commercial
- * conversation (`outside_ceiling`), one is deliberate configuration (`capability_denied`), one
- * is transient (`resolver_unavailable`), and one is a bug to report (`gate_unknown`). A single
- * "the feature is unavailable" message collapses all seven into one wrong next step.
- *
- * An UNKNOWN code is not an error. The enum grows when the platform grows a new decision point,
- * and a CLI that rejected the answer would be useless exactly when something new broke. It
- * renders the code verbatim with an upgrade instruction.
- */
-declare const REASON_CODES: readonly ["granted", "scope_not_provisioned", "capability_denied", "outside_ceiling", "not_in_grant", "runtime_gate_off", "gate_unknown", "platform_invariant", "resolver_unavailable"];
-type ReasonCode = (typeof REASON_CODES)[number];
-declare function isKnownReasonCode(value: string): value is ReasonCode;
-/** The next action for a code, including one this CLI has never heard of. */
-declare function nextActionFor$1(code: string): string;
-
 /**
  * THE SECRET FENCE. This module turns an admin mint response into the only shape this CLI is
  * allowed to hand back, and it is written so that a raw secret CANNOT travel through it.
@@ -1974,13 +2352,207 @@ declare function buildSandboxDocument(input: SandboxDocumentInput): JsonObject;
 /** The human projection. */
 declare function renderSandboxCreate(creation: SandboxCreation, revocation: SandboxRevocation, requestId: string | null): string;
 
+/**
+ * THEME DETECTION: what the partner's project already says about its own look, read statically, mapped to the
+ * SDK's `theme` prop only where the mapping is unambiguous, and graded so the planner knows whether to emit it.
+ *
+ * Owner decision, 18 September 2026: the MCP-built app must match the partner's existing theme automatically
+ * when it can, and refuse to guess when it cannot. Four sources are read, in confidence order:
+ *
+ *   (a) a Tailwind v4 `@theme` / `@theme inline` block in the project's CSS (what the everfur-frontend console
+ *       itself uses), with `var()` references resolved one level through `:root` and the dark block;
+ *   (b) a Tailwind v3 `tailwind.config.{js,ts,cjs,mjs}`: `theme.extend.colors`, `fontFamily`, `borderRadius`,
+ *       read by a tolerant static parser (theme-js.ts), `hsl(var(--x))` resolved through the project CSS;
+ *   (c) root CSS custom properties: `--primary`, `--brand`, `--color-primary`, `--background`, `--foreground`,
+ *       `--radius`, `--font-sans` and their common spellings, in a stylesheet or a static page's `<style>`;
+ *   (d) React Native: a react-navigation `Theme` object (`colors: { primary, background, card, text, border }`)
+ *       or a theme or colours file with obvious keys, identifiers resolved one level to `const` strings; and, from
+ *       the same theme files, the exact `fontFamily: '<Name>'` literals, mapped to the SDK's per-weight `fonts`
+ *       map by the weight word in each name (`Azeret-Regular`, `Inter_500Medium`, `Roboto Bold`), or the one
+ *       family the files name when none carries a weight. Never a family the files do not name.
+ *
+ * STATIC PARSING ONLY. Nothing here requires, evaluates or executes a partner's file; a value that is computed
+ * (an identifier, a call, a template literal, a `calc()`) is dropped with that reason, and a config that runs
+ * code at load time (a Node built-in module, `eval`) is refused whole. `tests/unit/theme-detect.test.ts` pins
+ * that at the source.
+ *
+ * THE MAPPING is to the SDK's `EverfurThemeInput` (everfur-sdk-rn src/client/theme/input.ts), and only where
+ * it is unambiguous: primary or brand to `primaryColor`; accent or secondary to `accentColor`, unless it reads
+ * as a surface tint (under 1.5:1 against the background, the shadcn `--accent` hover wash); the background to
+ * `brightness` (pinned when the project declares no dark variant) and, for a light ground close to one of the
+ * SDK's three compiled surfaces, `surfaceStyle`; a base radius to `radiusScale` by size; the first family of a
+ * font stack to `fontFamily` when it is a plain family name (the web, where the page loads the weights itself); a
+ * React Native theme file's `fontFamily` literals to the registered faces `fontRegular`, `fontMedium` and
+ * `fontBold` (written as the SDK's `fonts` map, names only: the app registers the faces, the SDK bundles no font
+ * and synthesizes no weight on a named face). The foreground is read as evidence only: the SDK
+ * computes its text colours from the ground (WCAG), and the prop has no text token outside slots. Every colour
+ * is written as `#RRGGBB`, the form the SDK parses; `hsl()` and `oklch()` are converted (theme-color.ts).
+ *
+ * THE CONFIDENCE GATE. `high` when a primary and a background both come from one source with literal values;
+ * `medium` when only some tokens were read; `low` otherwise. A computed colour the mapping wanted drops the
+ * grade one level; a config that runs code at load time, or builds a theme value with a template literal, is
+ * `low` whatever it declares. At `low` the theme is empty: nothing read from a source this tool could not fully
+ * trust is written into a partner's app.
+ */
+type ThemeSource = 'tailwind-v4' | 'tailwind-v3' | 'css-variables' | 'react-navigation' | 'rn-colors' | 'none';
+type ThemeConfidence = 'high' | 'medium' | 'low';
+/**
+ * The subset of the SDK's `EverfurThemeInput` a plan writes. Every value is a string, so the emitted literal
+ * type-checks against the prop on every SDK release that publishes it. Mirrors input.ts; extend both together.
+ */
+interface DetectedTheme {
+    /** `#RRGGBB`. */
+    readonly primaryColor?: string;
+    readonly accentColor?: string;
+    /** The fills on the dark palette, when the project declares a dark variant (or is dark only). */
+    readonly primaryColorDark?: string;
+    readonly accentColorDark?: string;
+    /** Pinned only when the project declares no dark variant: the surface then matches the page whatever the device says. */
+    readonly brightness?: 'light' | 'dark';
+    /** The compiled SDK surface nearest a light background, when one is within tolerance. */
+    readonly surfaceStyle?: 'white' | 'cream' | 'subtle';
+    readonly radiusScale?: 'sharp' | 'default' | 'round';
+    /** One plain family name, never a stack. */
+    readonly fontFamily?: string;
+    /**
+     * The registered face per weight (the SDK's `fonts` map, `regular`, `medium` and `bold`): one family NAME each,
+     * exactly as a React Native theme file declares it in a `fontFamily` literal. The app registers the faces itself.
+     */
+    readonly fontRegular?: string;
+    readonly fontMedium?: string;
+    readonly fontBold?: string;
+}
+type ThemeToken = keyof DetectedTheme;
+/** The order the tokens are written in generated code. */
+declare const THEME_TOKEN_ORDER: readonly ThemeToken[];
+interface ThemeEvidence {
+    /** The file, relative to the project root, or the label of a pasted source. */
+    readonly file: string;
+    /** 1-based line of the declaration the value was read from (the literal's line after a one-level resolution). */
+    readonly line: number;
+    /** The declaration read, with its resolution chain: `--color-primary -> --primary`, `Colors.light.tint -> tintColorLight`. */
+    readonly key: string;
+    /** The value as written. */
+    readonly value: string;
+    /** The theme field it became, or null when it was read and dropped (or read as evidence only). */
+    readonly token: ThemeToken | null;
+    /** How it mapped, or why it did not. */
+    readonly reason: string;
+}
+/** Where one logo URL was read from. */
+interface ThemeLogoEvidence {
+    readonly file: string;
+    /** 1-based line of the declaration in the file as written. */
+    readonly line: number;
+    /** The declaration read: a custom property name, or the img tag's attribute. */
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * THE LOGO (MCP-11). The SDK's theme takes `logoUrl` and `logoUrlDark` and the chat header shows them, and the
+ * planner's theme never carried either, so every generated integration rendered Everfur's header on a partner's own
+ * colours with no partner mark on it.
+ *
+ * https ONLY. The SDK drops a relative path (the frame and the app resolve it against the wrong origin) and plain
+ * http (a mixed-content load the browser blocks), so a value that is not an absolute https URL is not read at all
+ * rather than written and silently dropped at runtime.
+ */
+interface ThemeLogo {
+    readonly light: string;
+    readonly dark: string | null;
+    readonly evidence: readonly ThemeLogoEvidence[];
+}
+interface ThemeDetection {
+    readonly source: ThemeSource;
+    readonly confidence: ThemeConfidence;
+    /** Empty at `low`. */
+    readonly theme: DetectedTheme;
+    readonly evidence: readonly ThemeEvidence[];
+    /** The files read, relative to the root, so a refusal says where it looked. */
+    readonly scanned: readonly string[];
+    /** The facts a high-confidence match needs and this project did not give, in the refusal's words. Empty at `high`. */
+    readonly missing: readonly string[];
+    /** The fields whose value is a nearest match rather than a literal; generated code marks them `REPLACE: verify`. */
+    readonly inferred: readonly ThemeToken[];
+    /** The logo the project declares, https only; null when it declares none this detector can use. */
+    readonly logo?: ThemeLogo | null;
+}
+/**
+ * Detect the project's theme from disk, through the filesystem port. Every project gets every reader (a React
+ * Native app may carry a NativeWind config, a web project a colours module); `native` only puts the React
+ * Native readers first, so a tie in confidence goes to the source that fits the shape.
+ */
+declare function detectTheme(fs: FileSystemPort, root: string, options?: {
+    readonly native?: boolean;
+}): ThemeDetection;
+/**
+ * Detect a theme from pasted text (the MCP `theme_source` argument): a stylesheet, a Tailwind config, or a
+ * React Native theme file. The stylesheet readers and the Tailwind reader run over the text; the React Native
+ * readers run only when it is not a Tailwind config (a config's `theme.extend.colors` would read as a colours
+ * object otherwise). The best reading wins, and `label` names the text in the evidence.
+ */
+declare function detectThemeFromText(text: string, label: string): ThemeDetection;
+
+/**
+ * THE PARTNER'S `theme` PROP, as `everfur plan` writes it for a project: the `EVERFUR_THEME` constant a generated
+ * provider passes as `theme={EVERFUR_THEME}` (codegen.ts themeConstant), from the same theme detection the plan reads
+ * (the project on disk, or a pasted `theme_source`). The SDK merges it over the tenant's console branding per field,
+ * so `verify --surfaces theme` judges that merge rather than the console branding alone.
+ *
+ * The object holds exactly the fields the plan writes: every detected token by its own name (they are the SDK's
+ * `EverfurThemeInput` field names), with the three registered faces written as the `fonts` map. A detection the plan
+ * would not write a theme for (low confidence, or nothing read) yields null: the plan passes no prop then.
+ */
+interface ThemeProp {
+    /** The prop, in the SDK's `EverfurThemeInput` field names. */
+    readonly input: Readonly<Record<string, unknown>>;
+    /** Where it was read, for the report: the detection source and the file:line of each field. */
+    readonly source: string;
+}
+
+/**
+ * THE SURFACE CHECKS, run when `--surfaces` names them: each asks whether one Everfur surface works for THIS tenant
+ * with the session `verify` just minted, from the same wire a partner's app uses.
+ *
+ *   chat     the diagnostics reason for chat.message.create and chat.conversation.read, then GET
+ *            /widget/v1/conversations on the bearer.
+ *   records  the diagnostics reason for records.record.read, then GET /widget/v1/records/requests on the bearer.
+ *   televet  SANDBOX TENANTS ONLY (verdict livemode false): POST /widget/v1/televet/handoffs on the bearer. A live
+ *            tenant is never sent a write. The handoff token rides the URL fragment; it is stripped before anything
+ *            is kept, so only the origin, the path and the expiry reach the report.
+ *   theme    the branding the verdict's render_hints carry, rendered by the SDK's own resolver (theme-render.ts, over
+ *            the SDK code mirrored into src/registry/sdk): which fields are overridden and which the tenant locked,
+ *            whether the SDK drops the whole branding for a schema_version it does not read, whether it would drop a
+ *            logo or font URL, whether text on the brand fill it paints reaches WCAG 4.5:1 on each palette it shows
+ *            (light unless a brightness says otherwise, both for auto), and which configured slot colours its guard
+ *            repaints. The inks it pushes until they read (brand text, links) and the dark variants it derives are
+ *            reported, not failed. With a project (`--project-root`, `project_root`) or a pasted `theme_source`, the
+ *            branding is judged MERGED with the `theme` prop `everfur plan` writes from that theme, as the SDK merges
+ *            them: the prop wins per field unless the tenant locked it.
+ *
+ * Every step authenticates with the identity verify used: the minted session bearer, or, for
+ * `--identity anonymous`, the publishable key and the derived device session id (Records and Televet take a
+ * signed session only, so an anonymous run skips both and reads chat alone).
+ *
+ * A surface Everfur has not switched on for the tenant is GATED, not FAIL: a platform setting is not a broken
+ * integration, and reporting it as one would send a partner debugging code that is fine.
+ */
+declare const SURFACES: readonly ["chat", "records", "televet", "theme"];
+type Surface = (typeof SURFACES)[number];
+
 /**
  * THE WIRE EXERCISE. Three steps, run in order, each of which reports what happened rather than
  * what the process is about to exit with.
  *
- *   mint-session       POST /widget/v1/sessions with the sk + pk pair.
+ *   mint-session       the session to verify with: EVERFUR_SESSION_TOKEN when set (a short-lived session the
+ *                      partner backend minted, the only source the MCP tool reads), else, from the local CLI
+ *                      only, POST /widget/v1/sessions with the sk + pk pair. On the Everfur-hosted MCP the
+ *                      session was minted by the Everfur API for the signed-in sandbox tenant before this ran
+ *                      (`sessionSource: 'hosted'`), and a live tenant is GATED here rather than skipped.
  *   poll-entitlements  GET  /widget/v1/entitlements with the minted bearer.
- *   assert-verdict     the verdict carries at least one capability.
+ *   assert-verdict     the verdict carries at least one capability, and it is ENABLED. A listed capability
+ *                      whose surface is switched off is reported as unavailable with its reason code, never
+ *                      as granted: see `VerdictCapability`.
  *
  * Three properties this file exists to guarantee:
  *
@@ -1996,8 +2568,24 @@ declare function renderSandboxCreate(creation: SandboxCreation, revocation: Sand
  * The mint is a POST and gets exactly one attempt. The poll is a GET, so repeating it is safe,
  * and it repeats on purpose: an entitlement scope provisioned seconds ago propagates on a
  * revision bump, and a single read would report a stale empty verdict as a failure.
+ *
+ * `identityMode: 'anonymous'` verifies the path an anonymous integration actually uses, which has no
+ * backend to mint a session: the publishable key plus a device session id derived from the user ref
+ * (`x-everfur-session-id`), exactly what the SDK sends without a user. It runs the entitlement read and
+ * the assertion on that identity, then reads the tenant's session policy and lists the identity's conversations.
+ * `sessions_required` refuses only an UNSIGNED caller that claims an identity (a publishable key plus
+ * `x-everfur-user-ref`); signed callers and pure-anonymous callers stay exempt (EFBackend widget_dependencies.py,
+ * "Session enforcement"), so the policy is reported, never failed, on the anonymous path.
+ */
+/** The identities a verification can exercise, in the plan's own vocabulary. `partner-user-ref` is the default. */
+declare const VERIFY_IDENTITY_MODES: readonly ["partner-user-ref", "anonymous"];
+type VerifyIdentityMode = (typeof VERIFY_IDENTITY_MODES)[number];
+/**
+ * GATED is the fourth answer, added with the surface checks: the step ran and found a surface Everfur has switched
+ * off for the tenant. It is neither a failure of the integration (FAIL) nor something the operator can supply to make
+ * the step run (SKIP), so it moves the status in neither direction.
  */
-type StepResult = 'PASS' | 'FAIL' | 'SKIP';
+type StepResult = 'PASS' | 'FAIL' | 'SKIP' | 'GATED';
 interface VerifyStep {
     /** Stable within a schemaVersion. Callers may key on it. */
     readonly id: string;
@@ -2008,6 +2596,51 @@ interface VerifyStep {
     readonly requestId: string | null;
     readonly details: readonly string[];
 }
+/**
+ * What the Everfur-hosted MCP did about a session before `runVerification` ran.
+ *
+ * The hosted server holds no key of the partner's, so it asks the Everfur API to mint a verify session for
+ * the signed-in tenant (`POST /mcp/verify-sessions`, sandbox tenants only). The outcome is data here, not a
+ * credential: a minted session travels in the env map like a backend-minted one, and this record carries
+ * only what the step report may say about it.
+ */
+type HostedSessionOutcome = {
+    readonly kind: 'minted';
+    readonly userRef: string;
+    readonly expiresAt: string;
+    readonly capabilities: readonly string[];
+    readonly requestId: string | null;
+} | {
+    readonly kind: 'gated';
+    readonly reason: string;
+    readonly requestId: string | null;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+    readonly requestId: string | null;
+    readonly details: readonly string[];
+    /**
+     * The operator-owned facts of the failed mint call, when there was one: how it failed (`http`, `network`,
+     * `timeout`), the status and the wire code. Never the wire text. Lets a caller tell a transient failure (a 429
+     * VerifyMintRateLimited, a 503 VerifyMintUnavailable, a timeout) from a permanent one. Absent when no call was made.
+     */
+    readonly failure?: {
+        readonly kind: string;
+        readonly status: number | null;
+        readonly code: string | null;
+    };
+};
+/** What a hosted mint hands back: the outcome for the report, and the session itself when one was minted. */
+interface HostedMintResult {
+    readonly outcome: HostedSessionOutcome;
+    /** The minted widget session, wrapped as an ephemeral credential the moment it is read here. Null unless minted. */
+    readonly sessionToken: string | null;
+}
+/**
+ * The hosted server's mint, called by this step once verification has decided to run, so a call refused for
+ * its arguments never mints, and the session never travels through the env map.
+ */
+type HostedMint = () => Promise<HostedMintResult>;
 interface VerifyOptions {
     readonly client: ApiClient;
     readonly clock: ClockPort;
@@ -2016,6 +2649,47 @@ interface VerifyOptions {
     /** How many times to read the verdict before concluding it is empty. */
     readonly attempts: number;
     readonly pollDelayMs: number;
+    /**
+     * The page origin a web integration embeds from. When set, the web checks (`web.ts`) run after the wire
+     * exercise: the embed fence, the CORS exposure, the session policy, the loader. Null skips them.
+     */
+    readonly origin?: string | null;
+    /** The transport for the loader probe, which leaves the API host. Null skips that one check. */
+    readonly transport?: TransportPort | null;
+    readonly timeoutMs?: number;
+    /** The surfaces to exercise with the minted session (`surfaces.ts`). Empty or absent runs none. */
+    readonly surfaces?: readonly Surface[];
+    /** The project to run the offline checks over (`project-checks.ts`), with the port to read it. Null runs none. */
+    readonly project?: {
+        readonly fs: FileSystemPort;
+        readonly root: string;
+    } | null;
+    /**
+     * Whether the key pair may mint when EVERFUR_SESSION_TOKEN is absent. True for the local CLI (the fallback); false
+     * for the MCP tool, whose documented environment never holds the secret key, so it never reads one.
+     */
+    readonly mintWithSecretKey?: boolean;
+    /** The loader to probe for the web checks, overriding the one derived from the API host. Null derives it. */
+    readonly loaderUrl?: string | null;
+    /**
+     * Where the session comes from. `env` (the default): EVERFUR_SESSION_TOKEN, else the local key-pair mint when
+     * `mintWithSecretKey` allows it. `hosted`: this step asks the Everfur API for one on the signed-in tenant's
+     * behalf through `hostedMint`, and reports how that went. The hosted wording names no variable, because the
+     * partner exported none.
+     */
+    readonly sessionSource?: 'env' | 'hosted';
+    readonly hostedMint?: HostedMint | null;
+    /**
+     * Which identity to verify with. `partner-user-ref` (the default): a signed session, from `sessionSource` as
+     * above. `anonymous`: the publishable key and a derived device session id; nothing is minted, on either server.
+     */
+    readonly identityMode?: VerifyIdentityMode;
+    /**
+     * The `theme` prop the theme check merges over the tenant's branding, as the SDK does. Absent: the prop `everfur plan`
+     * writes from the project's own theme when `project` is given (none otherwise). Null: no prop. The MCP tool passes
+     * the prop read from a pasted `theme_source`, which wins over the project on disk, as it does for the plan.
+     */
+    readonly themeProp?: ThemeProp | null;
 }
 interface Verification {
     readonly steps: readonly VerifyStep[];
@@ -2072,7 +2746,26 @@ declare function createMemoryFileSystem(files: Readonly<Record<string, string>>)
  * disk. Anything it cannot establish lives in `src/commands/plan/facts.ts` as a supplied fact,
  * and the two sets are deliberately disjoint.
  */
-type ProjectType = 'expo-managed' | 'bare-react-native' | 'flutter' | 'web' | 'unknown';
+type ProjectType = 'expo-managed' | 'bare-react-native' | 'flutter' | 'web' | 'shopify-storefront' | 'unknown';
+/**
+ * How a web project embeds the Everfur surface, read from the project: `in-page` when package.json
+ * declares react-dom (the SDK's React components render in the host's own tree), `frame` otherwise (the
+ * loader puts the surface in an iframe on Everfur's origin, and nothing is installed). The platform tree
+ * asks this as its `web-embedding` question; `--embedding` overrides the detected answer. Null for every
+ * other project shape.
+ */
+type WebEmbedding = 'in-page' | 'frame';
+/**
+ * The web framework facet of a `web` project (see `web-framework.ts`). It spells the generated files; the
+ * contract's platform tree still branches on the project type, which this never replaces.
+ */
+type WebFramework = 'next-app-router' | 'next-pages-router' | 'vite-react' | 'remix' | 'static-html' | 'other-web';
+interface WebFrameworkDetection {
+    readonly framework: WebFramework;
+    /** `src/` when the framework's source root is `src/` (Next.js with src/app, a Vite app), else empty. */
+    readonly sourceDir: '' | 'src/';
+    readonly evidence: readonly string[];
+}
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'not-applicable' | 'undetermined';
 type DependencySource = 'package.json' | 'pubspec.yaml';
 type DependencyScope = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'sdk';
@@ -2097,6 +2790,47 @@ interface ProjectDetection {
     readonly packageManager: PackageManager;
     readonly packageManagerEvidence: readonly string[];
     readonly dependencies: readonly DetectedDependency[];
+    /** The detected embedding of a `web` project; null for every other shape. Its evidence is in `projectTypeEvidence`. */
+    readonly webEmbedding: WebEmbedding | null;
+    /**
+     * The detected framework of a `web` project; null (or absent, for a detection built by hand) for every
+     * other shape.
+     */
+    readonly webFramework?: WebFrameworkDetection | null;
+    /**
+     * What the project already says about its own look (theme-detect.ts), for the shapes the plan writes a provider
+     * for (web, Expo, bare React Native); null for every other shape, and absent for a detection built by hand.
+     */
+    readonly theme?: ThemeDetection | null;
+    /**
+     * Expo Router, for a React Native project that uses it (expo-router.ts); null when it does not, and absent for a
+     * detection built by hand. It decides where the plan tells the app to mount its Everfur module: Expo Router never
+     * renders App.tsx, and every file under its routes directory is a route.
+     */
+    readonly expoRouter?: ExpoRouterDetection | null;
+    /**
+     * The URL schemes a React Native project declares and the application ids beside them (app-schemes.ts), so the
+     * visit-return step can say whether one of them is a destination Everfur would register (MCP-14). Null for every
+     * other shape, and absent for a detection built by hand.
+     */
+    readonly appSchemes?: AppSchemeDetection | null;
+}
+/** What a React Native project declares about its own URL schemes. */
+interface AppSchemeDetection {
+    /** Every declared scheme, in the order app.json, iOS, Android. */
+    readonly schemes: readonly string[];
+    /** The application ids declared beside them (the iOS bundle identifier, the Android package). */
+    readonly appIds: readonly string[];
+    /** The first declared scheme in reverse-DNS form, which is the only form Everfur registers; null when there is none. */
+    readonly reverseDns: string | null;
+    /** The file and key each scheme was read from. */
+    readonly evidence: readonly string[];
+}
+/** An Expo Router project: its routes directory, and the files that said so. */
+interface ExpoRouterDetection {
+    /** `app`, or `src/app` when the routes live there (Expo Router reads `src/app` when `app` is absent). */
+    readonly appDir: 'app' | 'src/app';
+    readonly evidence: readonly string[];
 }
 
 declare function detectProject(fs: FileSystemPort, root: string): ProjectDetection;
@@ -2119,6 +2853,23 @@ interface TerminalOutcome {
     readonly capabilityRefs: readonly string[];
     /** The tree that must be answered next, or null when this answer stands alone. */
     readonly thenAskTreeId: string | null;
+    /**
+     * Present for a `human_ui` outcome (owner decision 2026-09-17): the plan may emit the UI a person taps, and no
+     * agent may perform what it does. Why, and where to ask. Absent (or null) for an ordinary terminal. A
+     * `partner_backend` outcome carries it too, for what no agent does with a delivery.
+     */
+    readonly agentBlocked?: AgentBlock | null;
+    /**
+     * True for a `partner_backend` outcome (DECISIONS.md entry 21): the plan writes code the partner's BACKEND runs to
+     * receive from Everfur (the webhook receiver), not a surface a device mounts. Absent for every other terminal.
+     */
+    readonly partnerBackend?: true;
+}
+/** The agent refusal a `human_ui` outcome carries beside its terminal facts. */
+interface AgentBlock {
+    readonly reason: string;
+    readonly unblockOwner: string;
+    readonly requestPath: string;
 }
 interface BlockedOutcome {
     readonly kind: 'blocked';
@@ -2233,7 +2984,7 @@ interface PlanCode {
     /** Suggested path, relative to the project root. */
     readonly path: string;
     /** For syntax highlighting and for an agent deciding how to write it. */
-    readonly language: 'tsx' | 'ts' | 'dart';
+    readonly language: 'tsx' | 'ts' | 'dart' | 'html' | 'liquid' | 'dotenv';
     readonly contents: string;
 }
 
@@ -2270,6 +3021,11 @@ declare const PLAN_DOCUMENT_KIND = "everfur.plan";
 type Capability = string;
 /** An identity mode id: one option of the identity-mode tree's entry question. */
 type IdentityMode = string;
+/**
+ * A web embedding id: one option of the platform tree's `web-embedding` question. Detected from the
+ * project (react-dom present means in-page, otherwise the frame) and overridable by `--embedding`.
+ */
+type Embedding = string;
 /** A backend language id: one option of the session-mint-language tree's entry question. */
 type SessionMintLanguage = string;
 type PlanStatus = 'ready' | 'underspecified' | 'blocked';
@@ -2282,7 +3038,7 @@ type PlanStatus = 'ready' | 'underspecified' | 'blocked';
  * reachable. It is a REFUSAL rather than a broken-artifact failure because nothing was loaded
  * and nothing on disk is wrong; the operator simply has not said where the contract is.
  */
-declare const MISSING_FACT_NAMES: readonly ["decisionTrees", "projectType", "packageManager", "capabilities", "identityMode", "sessionMintLanguage"];
+declare const MISSING_FACT_NAMES: readonly ["decisionTrees", "projectType", "packageManager", "embedding", "capabilities", "identityMode", "sessionMintLanguage", "environment"];
 type MissingFactName = (typeof MISSING_FACT_NAMES)[number];
 interface MissingFact {
     readonly fact: MissingFactName;
@@ -2331,8 +3087,18 @@ interface BlockedCapability {
     readonly unblockOwner: string;
     /** Site-relative path on the partner documentation site. Resolved at compile time. */
     readonly requestPath: string;
-    /** The capability pack keys the block derives from. */
+    /** The capability pack keys the block derives from. Empty when the block is the platform's. */
     readonly capabilityKeys: readonly string[];
+    /**
+     * What refused it. `capability` (the default when absent, for documents written before this field
+     * existed) is a BLOCKED terminal in the capabilities tree: the surface itself cannot be built.
+     * `platform` is the host project shape: the surface is buildable, but not for this project, because
+     * the SDK publishes no entry point for it or the contract blocks the shape outright. An agent that
+     * reads the two the same way tells a developer to ask support about chat when the answer is "not
+     * from this project shape". (Next.js, the App Router and the Pages Router alike, IS plannable: the
+     * framework is detected from the project and gets its own route convention.)
+     */
+    readonly blockedBy?: 'capability' | 'platform';
 }
 /**
  * Guidance that is true regardless of what was answered, carried in the document rather than
@@ -2364,6 +3130,22 @@ interface PlanDetection {
         readonly source: string;
         readonly scope: string;
     }[];
+    /**
+     * The detected embedding of a `web` project (`in-page` or `frame`), null for other shapes. Additive to
+     * schema v1: absent on documents written before the web shapes existed.
+     */
+    readonly webEmbedding?: string | null;
+    /**
+     * The detected framework of a `web` project (next-app-router, next-pages-router, vite-react, remix,
+     * static-html, other-web), null for other shapes. Additive to schema v1.
+     */
+    readonly webFramework?: string | null;
+    /**
+     * What the project says about its own look, read statically (detect/theme-detect.ts): the source, the confidence,
+     * the SDK theme fields it mapped, and the file:line evidence for each. Null for a shape the plan writes no
+     * provider for, or for a detection built by hand. Additive to schema v1.
+     */
+    readonly theme?: ThemeDetection | null;
 }
 interface PlanDocument {
     readonly schemaVersion: typeof PLAN_SCHEMA_VERSION;
@@ -2380,6 +3162,13 @@ interface PlanDocument {
         readonly capabilities: readonly Capability[] | null;
         readonly identityMode: IdentityMode | null;
         readonly sessionMintLanguage: SessionMintLanguage | null;
+        /** `--embedding`, when given; null means the detected embedding decided. Additive to schema v1. */
+        readonly embedding?: Embedding | null;
+        /**
+         * `--environment` (test, staging or production); null means it was not given. Required for a plan that writes
+         * configuration, and never defaulted. Additive to schema v1.
+         */
+        readonly environment?: string | null;
     };
     /** Empty when `status` is `ready`. Non-empty exactly when it is `underspecified`. */
     readonly missingFacts: readonly MissingFact[];
@@ -2387,12 +3176,31 @@ interface PlanDocument {
     readonly steps: readonly PlanStep[];
     /** Non-empty exactly when a selected capability cannot be built today. */
     readonly blocked: readonly BlockedCapability[];
+    /**
+     * Non-null when the host project SHAPE refuses every plan, whatever was asked for: the contract blocks
+     * the shape, or the SDK publishes no entry point for it. Carried at the top level, beside the
+     * per-capability blocks, because it is a fact about the project rather than about any capability, and
+     * a reader branching on `blocked[].blockedBy` alone would miss it on a document whose only asked-for
+     * capabilities were also blocked by the registry. Additive to schema v1 (optional; absent on documents
+     * written before it existed, which means "no platform block").
+     */
+    readonly platformBlock?: PlatformBlock | null;
     /** The principles of every tree this plan consulted. */
     readonly principles: readonly PlanPrinciple[];
     readonly warnings: readonly PlanWarning[];
     /** Null only on the refusal that says no decision space was found. */
     readonly decisionSpace: DecisionSpaceProvenance | null;
 }
+/** Why a whole project shape is refused, independent of which capabilities were asked for. */
+interface PlatformBlock {
+    readonly reason: string;
+    readonly unblockOwner: string;
+    /** Site-relative path on the partner documentation site. */
+    readonly requestPath: string;
+}
+
+declare const ENVIRONMENTS: readonly ["test", "staging", "production"];
+type Environment = (typeof ENVIRONMENTS)[number];
 
 /**
  * The planner. A pure function from (what was detected, what was supplied, what the contract
@@ -2427,9 +3235,27 @@ interface PlanInput {
     readonly capabilities: readonly Capability[] | null;
     readonly identityMode: IdentityMode | null;
     readonly sessionMintLanguage: SessionMintLanguage | null;
+    /** `--embedding`, overriding the detected web embedding; absent or null means detection decides. */
+    readonly embedding?: Embedding | null;
+    /**
+     * `--environment`: the Everfur deployment the generated configuration targets. Absent or null is a missing fact
+     * for a plan that writes configuration; it is never defaulted.
+     */
+    readonly environment?: Environment | null;
     /** The decision space from the contract projection, or null when none was found. */
     readonly space: DecisionSpace | null;
     readonly cliVersion: string;
+    /**
+     * True when `capabilities` came from the `all` sentinel (every capability the contract can plan). The plan then says
+     * so, and says that `verify` is the fail-closed check of what the tenant actually has: `plan` holds no credential.
+     */
+    readonly allCapabilities?: boolean;
+    /**
+     * A theme detection that replaces the one on `detection`: a remote MCP that cannot read the project received the
+     * partner's Tailwind config or CSS as `theme_source` and read it with `detectThemeFromText`. Absent means the
+     * detection's own (which is absent too for a detection built by hand, and then no theme step is planned).
+     */
+    readonly theme?: ThemeDetection | null;
 }
 /**
  * Compute the missing facts in a fixed order: the contract first, because everything else is
@@ -2474,17 +3300,25 @@ declare function renderPlan(document: PlanDocument): string;
 interface SuppliedFactsResult {
     readonly ok: boolean;
     readonly capabilities: readonly Capability[] | null;
+    /** True when `--capabilities all` expanded to every plannable capability, so the plan can say so. */
+    readonly allCapabilities: boolean;
     readonly identityMode: IdentityMode | null;
     readonly sessionMintLanguage: SessionMintLanguage | null;
+    readonly embedding: Embedding | null;
     readonly errors: readonly string[];
 }
 /**
  * Parse `--capabilities chat,records`. Order is normalised to sorted order and duplicates
  * collapse, so two equivalent invocations produce a byte-identical plan document.
+ *
+ * `all` is the one token the contract does not publish: it expands to every capability the loaded space can plan
+ * (a BLOCKED option is left out, since asking for it is asking for a refusal). `all` is reported so the plan can say
+ * what it meant, and that `verify` is the fail-closed check of what the tenant actually has.
  */
 declare function parseCapabilities(raw: string | null, space: DecisionSpace | null): {
     readonly value: readonly Capability[] | null;
     readonly errors: readonly string[];
+    readonly all: boolean;
 };
 declare function parseIdentityMode(raw: string | null, space: DecisionSpace | null): {
     readonly value: IdentityMode | null;
@@ -2496,7 +3330,7 @@ declare function parseSessionMintLanguage(raw: string | null, space: DecisionSpa
     readonly errors: readonly string[];
 };
 /** Parse every supplied fact, accumulating all errors rather than stopping at the first. */
-declare function parseSuppliedFacts(capabilitiesRaw: string | null, identityRaw: string | null, backendRaw: string | null, space: DecisionSpace | null): SuppliedFactsResult;
+declare function parseSuppliedFacts(capabilitiesRaw: string | null, identityRaw: string | null, backendRaw: string | null, space: DecisionSpace | null, embeddingRaw?: string | null): SuppliedFactsResult;
 
 /**
  * The CLI version, stamped into every emitted document under `generatedBy.version`.
@@ -2506,6 +3340,6 @@ declare function parseSuppliedFacts(capabilitiesRaw: string | null, identityRaw:
  * install, and a bundled artifact. `tests/unit/version.test.ts` asserts this constant equals
  * the package.json version, so the two cannot drift.
  */
-declare const CLI_VERSION = "0.1.0";
+declare const CLI_VERSION = "0.2.1";
 
-export { ADMIN_TOKEN, API_PREFIX, type ApiClient, type ApiFailure, type ApiResult, type ApiSuccess, BASE_URL_ENV_VAR, type BlockedCapability, type BlockedOutcome, CLI_VERSION, COMMANDS, CREDENTIAL_SPECS, type Capability, type CapabilityDiagnosis, type ClockPort, type Command, type CommandContext, type CommandOutcome, type ContractValidationOutcome, type Credential, type CredentialSpec, DEFAULT_TIMEOUT_MS, type DecisionSpace, type DecisionSpaceProvenance, type DecisionTree, type DetectedDependency, type Diagnosis, EMPTY_REGISTRY, ERRORS_DOCUMENT_KEY, type ErrorRegistry, type ErrorRegistryEntry, ExitCode, type FileSystemPort, type FormatOptions, type FormattedOutput, type HttpMethod, type HttpRequest, type HttpResponse, IDEMPOTENT_METHODS, type IdentityMode, MISSING_FACT_NAMES, type MissingFact, type MissingFactName, type Outcome, PARTNER_KEY, PARTNER_SECRET_KEY, PLAN_DOCUMENT_KIND, PLAN_SCHEMA_VERSION, type PackageManager, type PlanDocument, type PlanInput, type PlanPrinciple, type PlanStep, type PlanWarning, type PositionalSpec, type ProjectDetection, type ProjectType, REASON_CODES, REDACTED, type ReasonCode, type RegistryLoad, type RequestSpec, type ResolvedCredential, type ResolvedEndpoint, type RunOptions, SCHEMAS, SESSION_TOKEN, type SandboxCreateStatus, type SandboxCreation, type SchemaValidation, type SchemaViolation, type SessionMintLanguage, type StepResult, type TerminalOutcome, TransportError, type TransportPort, type TreeOption, type TreeQuestion, type Verification, type VerifyStep, type WalkResult, apiUrl, buildDecisionSpace, buildDiagnosisDocument, buildExplanationDocument, buildSandboxDocument, buildVerificationDocument, clampTimeout, createApiClient, createMemoryFileSystem, createRecordingClock, describeFailure, detectProject, digestOfProjection, digestsEqual, editDistance, entryFromRow, ephemeralCredential, errorCodeOf, failureDetails, failureOutcome, fetchTransport, formatOutcome, isCorrelatableRequestId, isIdempotent, isKnownReasonCode, loadDecisionSpace, loadErrorRegistry, matchCommand, missingFactsFor, nextActionFor as nextActionForErrorCode, nextActionFor$1 as nextActionForReason, nextActionsFor, nodeFileSystem, parseCapabilities, parseDiagnostics, parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, planIntegration, projectSandboxCreate, renderDiagnosis, renderExplanation, renderPlan, renderSandboxCreate, renderVerification, resolveContractPath, resolveCredential, resolveEndpoint, runCli, runVerification, suggestCodes, systemClock, validateContractFile, validateContractPublicEnvelope, validateDiagnosisDocument, validateErrorExplanationDocument, validatePlanDocument, validateSandboxCreateDocument, validateVerificationDocument, verifyDigest, walkSingle, walkTree, withPrefix };
+export { ADMIN_TOKEN, API_PREFIX, type ApiClient, type ApiFailure, type ApiResult, type ApiSuccess, BASE_URL_ENV_VAR, type BlockedCapability, type BlockedOutcome, CLI_VERSION, COMMANDS, CREDENTIAL_SPECS, type Capability, type CapabilityDiagnosis, type ClockPort, type Command, type CommandContext, type CommandOutcome, type ContractValidationOutcome, type Credential, type CredentialSpec, DEFAULT_TIMEOUT_MS, type DecisionSpace, type DecisionSpaceProvenance, type DecisionTree, type DetectedDependency, type DetectedTheme, type Diagnosis, EMPTY_REGISTRY, ERRORS_DOCUMENT_KEY, type ErrorRegistry, type ErrorRegistryEntry, ExitCode, type FileSystemPort, type FormatOptions, type FormattedOutput, type HttpMethod, type HttpRequest, type HttpResponse, IDEMPOTENT_METHODS, type IdentityMode, MISSING_FACT_NAMES, type MissingFact, type MissingFactName, type Outcome, PARTNER_KEY, PARTNER_SECRET_KEY, PLAN_DOCUMENT_KIND, PLAN_SCHEMA_VERSION, type PackageManager, type PlanDocument, type PlanInput, type PlanPrinciple, type PlanStep, type PlanWarning, type PositionalSpec, type ProjectDetection, type ProjectType, REASON_CODES, REDACTED, type ReasonCode, type RegistryLoad, type RequestSpec, type ResolvedCredential, type ResolvedEndpoint, type RunOptions, SCHEMAS, SESSION_TOKEN, type SandboxCreateStatus, type SandboxCreation, type SchemaValidation, type SchemaViolation, type SessionMintLanguage, type StepResult, THEME_TOKEN_ORDER, type TerminalOutcome, type ThemeConfidence, type ThemeDetection, type ThemeEvidence, type ThemeSource, type ThemeToken, TransportError, type TransportPort, type TreeOption, type TreeQuestion, type Verification, type VerifyStep, type WalkResult, apiUrl, buildDecisionSpace, buildDiagnosisDocument, buildExplanationDocument, buildSandboxDocument, buildVerificationDocument, clampTimeout, createApiClient, createMemoryFileSystem, createRecordingClock, describeFailure, detectProject, detectTheme, detectThemeFromText, digestOfProjection, digestsEqual, editDistance, entryFromRow, ephemeralCredential, errorCodeOf, failureDetails, failureOutcome, fetchTransport, formatOutcome, isCorrelatableRequestId, isIdempotent, isKnownReasonCode, loadDecisionSpace, loadErrorRegistry, matchCommand, missingFactsFor, nextActionFor as nextActionForErrorCode, nextActionFor$1 as nextActionForReason, nextActionsFor, nodeFileSystem, parseCapabilities, parseDiagnostics, parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, planIntegration, projectSandboxCreate, renderDiagnosis, renderExplanation, renderPlan, renderSandboxCreate, renderVerification, resolveContractPath, resolveCredential, resolveEndpoint, runCli, runVerification, suggestCodes, systemClock, validateContractFile, validateContractPublicEnvelope, validateDiagnosisDocument, validateErrorExplanationDocument, validatePlanDocument, validateSandboxCreateDocument, validateVerificationDocument, verifyDigest, walkSingle, walkTree, withPrefix };