@everfur/cli 0.2.1 → 0.4.1

package/README.md

@@ -14,9 +14,14 @@ template) includes a 2 KB loader and gets the chat in an iframe on Everfur's ori
 a Shopify theme or app gets the Everfur app's `Everfur chat` block, with Shopify vouching for the
 signed-in customer so no backend mints. `--embedding in-page|frame` overrides the detected embedding.
 A capability the web cannot render (photo in the page, anything but chat in the frame) is reported as
-blocked by the platform, beside the steps for the rest. `everfur verify --origin https://your.page`
-adds the checks a web integration needs: the embed allowlist for that origin, the CORS exposure a
-browser depends on, the tenant's session policy, and the loader of the key's environment.
+blocked by the platform, beside the steps for the rest. For a page that includes the loader,
+`everfur verify --origin https://your.page --embedding frame` adds the checks a framed page needs: the embed
+allowlist for that origin, the CORS exposure a browser depends on, the tenant's session policy, and the loader
+of the key's environment. An in-page integration calls the API from its own origin, so it passes `--origin` too, with
+`--embedding in-page`: the preflight is of a widget request with the headers the SDK sends, the exposure and the
+session policy are checked, and the embed fence and the loader, which it never uses, are reported `N/A` rather than
+failed. Only a named `--embedding in-page` does that: with none named every check runs, and a project whose page
+includes the Everfur loader is checked as the frame it embeds.
 
 **The generated surface matches your own theme when the plan can read it, and says so when it cannot.** The
 plan reads, statically and never by executing anything, a Tailwind v4 `@theme` block, a `tailwind.config.{js,ts}`
@@ -37,14 +42,22 @@ config that runs code when it loads) is low: no theme is written, and the step n
 offers the manual `theme={{ ... }}` snippet. Over a remote MCP pass the config or CSS text as `theme_source`. The
 tenant's console branding is merged with the emitted theme per field (a locked field keeps the console's value;
 the console fills what the theme leaves unset); the plan holds no branding credential and never changes it.
+Branding v2 (SDK 0.9.0): a success, warning or info colour and a heading stack the theme declares by name
+(`--success`, `--color-warning`, `--font-heading`, `--font-display`, Tailwind v3 `colors.info` or
+`fontFamily.heading`) are written too, as `successColor`, `warningColor`, `infoColor` (with their dark twins) and
+`headingFontFamily`; a theme that declares none gets none. The logo and the chat's assistant avatar are uploaded in
+the partner console, the only images the SDK shows, so a logo read from the project is named as the image to upload
+rather than written. Custom fonts apply in-page only: the hosted frame keeps Everfur's fonts.
 
 **The chat and records mounts match the Everfur app, and the host seams are generated with them.** Chat has the
 header pet switcher (it appears by itself once two or more pets are registered), quick prompts, citations, thumbs
 feedback, the urgency banner and the history drawer built in. On an emergency or schedule-soon reply the banner's
 Find a vet pill opens the Everfur vet visit entry when Everfur has it on for your client, else calls `onFindVet`, else
-does not render: every in-page chat mount passes `onFindVet={findVet}`, which opens a maps search until you replace
-it with your own vet finder. A frame takes no `onFindVet`, so there the pill appears only while Everfur has its vet
-visit entry on for your client. The SDK bundles no picker and no
+does not render. No generated mount passes `onFindVet`, so the plan writes no vet finder of its own that sends the
+member to a page outside your app; the commented `onFindVet` line beside each in-page chat mount is for an app with
+its own in-app vet finder (on React Native, passing it also replaces the Everfur vet entry on the check-in card). A
+frame takes no `onFindVet`,
+so there the pill appears only while Everfur has its vet visit entry on for your client. The SDK bundles no picker and no
 clipboard module, so an EXPO plan mounts `<EverfurChat attachments={{ pick: pickChatPhoto }}
 onCopy={copyText} />` and writes both helpers into `everfur/EverfurRoot.tsx`, the module the app mounts from its
 own entry (`app/_layout.tsx` in an Expo Router app, `App.tsx` otherwise): in an Expo app `pickChatPhoto` opens the system
@@ -70,24 +83,52 @@ because it asked for one) and always carries the size when the picker reports it
 records upload, so no image picker is wired there. The system document UI is not the media library and needs no
 permission on either platform, so unlike the chat photo picker there is nothing to request before it opens. On the web the
 browser is the picker and the speech engine: photo attachments and voice dictation are on by default, and
-`attachments={false}` and `dictation={false}` turn them off. Records is the app's screen flow: `<EverfurRecords>`
-opens on the pet's dashboard and owns its own stack (the hardware back key pops it), every screen is exported by
-name for your own navigator, the mount passes `petName={selectedPet.name}` for headings such as
-`{petName}'s lab trends` (and `onCopy={copyText}` on React Native, for the share sheet), and
-`initialScreen={{ name: 'request', requestId }}` opens a request directly, which is what the generated
-notification router's `record_request` handler says to do. Lab markers, share links, the record PDF link, fact
+`attachments={false}` and `dictation={false}` turn them off. On React Native records is the app's screen flow:
+`<EverfurRecords>` opens on the pet's dashboard and owns its own stack (the hardware back key pops it), and
+`initialScreen={{ name: 'request', requestId }}` opens a request directly, which is what the generated notification
+router's `record_request` handler says to do. On the web records is a page, the shape of Everfur's own web records
+page: the generated `EverfurRecordsSurface` renders `EverfurRecordsPage` and opens what it links to (the full record,
+the timeline, an upload) in the records flow in the same place, with no route added to your app; the page holds no clinic
+request of its own, so `records-clinic` mounts beside it. Every screen is exported by name for your own navigator,
+and the plan's `mount-records-screens` step names them per platform. The mount passes `petName={selectedPet.name}` for
+headings such as `{petName}'s lab trends` (and `onCopy={copyText}` on React Native, for the share sheet). An Expo
+records mount also passes `onOpenUrl={openRecordUrl}`, which handles the share sheet the way the Everfur app does: a
+share link goes to the OS share sheet, and the record PDF is downloaded into the app's cache (`expo-file-system`),
+shared as a file (`expo-sharing`) and deleted, so neither opens a browser. A bare React Native mount passes none, and
+the SDK's default opens both in the system browser until you pass your own. Lab markers, share links, the record PDF link, fact
 edits and the signature gallery need the platform flag `partner.records_full_depth_enabled`; while it is off the
 SDK hides them.
 
-**Every plan that writes code names its environment.** `--environment staging|production` (or
+**The vet visit runs inside your app.** A plan that mounts `televet` installs `@everfur/sdk@^0.9.0`, a release
+whose `VetVisitButton`, `useVetVisit().open()` and `openVisit()`, and every vet entry inside chat open the visit in
+the app by default, and writes the two things that default needs: `registerEverfurDaily(...)` once at load, from
+`@everfur/sdk/televet/call` over `@daily-co/react-native-daily-js` (React Native) or from
+`@everfur/sdk/web/televet/call` over `import('@daily-co/daily-js')` (the web), and one `<EverfurTelevetHost />`
+inside the provider, where every visit opens: a full-screen modal on React Native, a dialog in the SDK's own DOM
+subtree on the web. The button passes no `returnTo` and no `prefer`, the file registers no presenter and reads no
+return URL, and the chat mount gets the member's state as `vetUsState`. On React Native the plan installs the Daily
+modules the consumer app runs and the native setup (the Expo config plugin and a clean prebuild, or the bare
+manifest and Info.plist edits), and the notifications file opens a tapped visit in the app through the same hook.
+The booking lists vets only for the member's US state and the SDK never reads a device location, so the file's
+`YOUR_USER_US_STATE` reaches the button, the chat and the notifications bridge, and `everfur verify --project-root`
+fails while it is still `null` as shipped. The hosted visit in the system browser or a new tab is the SDK's explicit
+`prefer="redirect"`, which no generated file passes. A plan without `televet` installs the same `@everfur/sdk@^0.9.0`
+and none of the call.
+
+<!-- Owner-approved 2026-10-01 (production sandbox plan, PC-1/PC-2): what `test` and the key prefixes mean. -->
+**Every plan that writes code names its environment.** `--environment test|staging|production` (or
 `environment` over MCP) is required and never assumed; generated files read the publishable key and base
 URL from the framework's own variables (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`) and the plan writes the
-names into `.env.example`. Test mode is not a third deployment: it is your **sandbox tenant on the staging
-API** (`https://api-staging.everfur.com/api/v1`), issued an ordinary `pk_live_` key, whose entitlements
-report `livemode: false`. No deployed environment accepts a `pk_test_` key. `--environment test` is
-accepted and resolves to that same staging deployment. The web framework is detected from the project: the Next.js App Router gets a
+names into `.env.example`. `test` is your **sandbox tenant on the production API**
+(`https://api.everfur.com/api/v1`), issued a `pk_test_` key, whose entitlements report `livemode: false`;
+`staging` is your sandbox tenant on the staging API (`https://api-staging.everfur.com/api/v1`), for early
+access; `production` is your live tenant and its `pk_live_` key. The key prefix names the tenant mode: a
+sandbox created before `pk_test_` keys were issued may still carry `pk_live_`. The web framework is detected from the project: the Next.js App Router gets a
 `'use client'` surface and a Route Handler, the Pages Router a component and an API route, Vite with React
-reads `import.meta.env`. `everfur verify --surfaces chat,records,televet,theme` exercises each surface
+reads `import.meta.env` and gets `server/dev-server.ts`, a development server for its session route (a Vite build has
+no server, so the plan also says where the route goes in production). A signed-in React Native app gets the same server
+on its own route, with the URL that reaches it from the iOS simulator, the Android emulator and a device, and its
+server-only names in `server/.env.example`, never in the app's env file. `everfur verify --surfaces chat,records,televet,theme` exercises each surface
 with the minted session (Televet mints a handoff only on a sandbox tenant, and a surface Everfur has not
 switched on is reported `GATED`, not failed); `--project-root <path>` adds offline checks for a secret key
 in source or client build output and for `'use client'`. `everfur diagnose --bundle` prints one support
@@ -97,28 +138,33 @@ document with no credential value in it.
 
 ### Hosted MCP: nothing to install
 
-Everfur runs the MCP server for you, so there is no key, token, variable or file to set. Today it is
-reachable at one endpoint:
+Everfur runs the MCP server for you, so there is no key, token, variable or file to set. It is reachable at
+two endpoints, one per deployment:
 
 ```
-https://mcp-staging.everfur.com/mcp
+https://mcp.everfur.com/mcp           production: your sandbox (test) tenant and your live tenant
+https://mcp-staging.everfur.com/mcp   staging: an early-access sandbox tenant on the staging API
 ```
 
-That is the staging deployment, and it is where your sandbox tenant lives while you build. **The production
-endpoint `https://mcp.everfur.com/mcp` is not available yet:** the hostname does not resolve, so a client
-pointed at it fails to connect rather than falling back to anything. Use the staging URL until Everfur tells
-you production is live.
+Use the one for the deployment your tenant is on. A client pointed at the other one signs in to a different
+deployment and does not fall back to anything.
 
 Add the URL to your editor as a remote (Streamable HTTP) MCP server. You paste the URL yourself; there is
 nothing to search for in a connector directory. Adding it is the whole configuration step:
 
-- **Claude Code:** `claude mcp add --transport http everfur https://mcp-staging.everfur.com/mcp`
-- **Cursor:** `.cursor/mcp.json` with `{"mcpServers":{"everfur":{"url":"https://mcp-staging.everfur.com/mcp"}}}`
-- **VS Code:** `.vscode/mcp.json` with `{"servers":{"everfur":{"type":"http","url":"https://mcp-staging.everfur.com/mcp"}}}`
+- **Claude Code:** `claude mcp add --transport http everfur https://mcp.everfur.com/mcp`
+- **Cursor:** `.cursor/mcp.json` with `{"mcpServers":{"everfur":{"url":"https://mcp.everfur.com/mcp"}}}`
+- **VS Code:** `.vscode/mcp.json` with `{"servers":{"everfur":{"type":"http","url":"https://mcp.everfur.com/mcp"}}}`
 - **Codex:** a streamable HTTP server entry with that URL in `~/.codex/config.toml` (`[mcp_servers.everfur]`, `url`)
-- **claude.ai:** add it as a **custom connector** and paste the URL into the dialog. Click by click,
-  including what the sign-in asks and how to tell it worked:
-  [docs/ADD_THE_EVERFUR_CONNECTOR_IN_CLAUDE.md](docs/ADD_THE_EVERFUR_CONNECTOR_IN_CLAUDE.md)
+- **claude.ai:** add it as a **custom connector** at <https://claude.ai/customize/connectors> (**+**, then
+  **Add custom connector**): name it `Everfur` and paste the URL exactly, all lowercase, `https://`, `/mcp` on
+  the end, no trailing slash. Leave **Request headers** empty: Everfur never wants a key there. Click
+  **Connect** and sign in to the partner console. The approval page names Claude as the application asking
+  and shows the address Claude will be sent back to, `https://claude.ai/api/mcp/auth_callback` or
+  `https://claude.com/api/mcp/auth_callback`; anything else is not Everfur's consent page. Connecting does not
+  switch it on for every conversation: in a chat, **+**, then **Connectors**, then toggle **Everfur**. To check
+  it worked, ask Claude to explain the Everfur error code `authExpired`: an answer through
+  `everfur_explain_error` means the connection itself is good.
 
 There is no key to type because the server authenticates you instead. On first connect it answers with a
 `401` naming its OAuth resource metadata, your client registers itself automatically (dynamic client
@@ -149,8 +195,7 @@ from where the server runs:
    `everfur_list_webhook_deliveries`, `everfur_get_webhook_delivery`, `everfur_list_events`,
    `everfur_get_usage_summary`, `everfur_get_records_status_summary` and `everfur_search_docs` (the error
    registry, capabilities and guide of your contract). None returns a signing secret, a key value or a
-   member's content. The routes behind them are specified in
-   [docs/HOSTED_TENANT_API.md](docs/HOSTED_TENANT_API.md).
+   member's content.
 
 Everything below is for running the server yourself, which is what you want when the agent runs beside the
 project (so `project_root` works) or when your organisation keeps its own MCP process.
@@ -188,8 +233,8 @@ The four values, and where they come from:
 
 | Variable | What it is |
 |---|---|
-| `EVERFUR_API_BASE_URL` | The staging API while you build. Your test tenant is a **sandbox tenant on staging**; there is no separate test deployment. Going live changes this to `https://api.everfur.com/api/v1`. |
-| `EVERFUR_PARTNER_KEY` | The sandbox tenant's publishable key. It is a `pk_live_` key (no deployed environment accepts `pk_test_`); what makes the tenant a sandbox is the tenant, and its entitlements report `livemode: false`. |
+| `EVERFUR_API_BASE_URL` | The API of your sandbox tenant while you build: `https://api.everfur.com/api/v1` for a test (production sandbox) tenant, the staging API for an early-access one. Going live uses `https://api.everfur.com/api/v1`. |
+| `EVERFUR_PARTNER_KEY` | The sandbox tenant's publishable key, `pk_test_...` (a sandbox created before `pk_test_` keys may still carry `pk_live_`); its entitlements report `livemode: false`. |
 | `EVERFUR_DOCS_KEY` | A read-only docs key (`dk_partner_...`) that opens `GET /partners/contract` and nothing else. |
 | `EVERFUR_SESSION_TOKEN` | A short-lived session your backend minted for a test user. Only `everfur_verify_integration` reads it. |
 
@@ -198,8 +243,10 @@ live changes every value in the block: the production base URL, and the producti
 key and docs key (its secret key changes on your backend at the same time). Production keys are issued only
 after `everfur_verify_integration` passes on the sandbox tenant.
 
-`EVERFUR_DOCS_KEY` is required. The Everfur contract (the error registry, capability packs, credential
-shapes and the decision trees the planner walks) is not included in this package: the tools fetch it from
+`EVERFUR_DOCS_KEY` is required here, for the server you run yourself. The Everfur-hosted connector above
+needs no docs key: it signs in with OAuth and is served the contract as your tenant. The Everfur contract
+(the error registry, capability packs, credential shapes and the decision trees the planner walks) is not
+included in this package: the tools fetch it from
 `GET /partners/contract` on `EVERFUR_API_BASE_URL`, presenting a partner docs key (`dk_partner_...`), and
 cache it on disk (see [Credentials](#credentials)). A partner admin mints a docs key with
 `POST /api/v1/partners/docs-keys` (list with `GET`, revoke with `DELETE /api/v1/partners/docs-keys/{key_id}`);
@@ -232,7 +279,12 @@ answer, naming each one:
    Node backend gets the files; any other backend gets the recipe.
 
 That is three questions for an anonymous integration and four for `partner-user-ref`. Once answered, the
-plan's steps include the complete integration file, ready to write.
+plan's steps include the complete integration file, ready to write. Over MCP the tool first returns a small
+summary with a `plan_id` and a number of `pages` (the goal, the detected facts, each step's id, title, one-line
+intent and page, and the checklist); the same call with `plan_id` and `page` returns that page's steps in full,
+commands and file bodies included, and page 1 also the detection, warnings and checklist in full. `steps`
+(step ids) in place of `page` still returns those steps, a page at a time. `everfur plan` prints the whole plan at
+once.
 
 The explicit `everfur-mcp` command is intentional: `@everfur/mcp` also ships `everfur-mcp-http` for a
 server deployment, so bare `npx @everfur/mcp` can no longer safely guess which executable you mean.
@@ -243,7 +295,7 @@ For a partner-operated cloud/server deployment, run the guarded Streamable HTTP
 
 ```bash
 export EVERFUR_API_BASE_URL="https://api-staging.everfur.com/api/v1"
-# No deployed environment accepts pk_test_: use the pk_live_ key of a tenant created as a sandbox.
+# The publishable key of a tenant created as a sandbox (pk_test_..., or pk_live_... on an older staging sandbox).
 export EVERFUR_PARTNER_KEY="pk_live_..."
 export EVERFUR_DOCS_KEY="dk_partner_..."
 # For verification only: a short-lived session your backend minted. The server never reads the secret key.
@@ -260,14 +312,14 @@ put either secret in an agent prompt, a browser, or a client bundle. The HTTP pr
 scale behind a load balancer. It does **not** replace a platform OAuth service: use this mode when one
 partner owns the deployment and its credentials.
 
-For release gates, reverse-proxy requirements, negative tests, and the staged production rollout, use the
-[remote MCP staging and production runbook](docs/REMOTE_MCP_STAGING_PRODUCTION_RUNBOOK.md).
-
 Five tools are served: `everfur_plan_integration`, `everfur_verify_integration`, `everfur_diagnose`,
 `everfur_explain_error`, and `everfur_send_test_message`. Each is a body of the CLI, so the two surfaces
 answer the same question the same way. `everfur_explain_error` is the one to reach for when a response
-carries an error code: it needs no project, reads the registry from the fetched contract, and refuses a code
-it does not recognise instead of explaining it from the shape of the string.
+carries an error code: it needs no project, reads the registry from the fetched contract, answers offline the SDK's
+own codes (`EverfurError` and its closed sub-enums such as `AttachmentErrorCode` and `VetVisitErrorReason`), the
+diagnostics reason codes, the CLI's own error codes and the `error.code` these tools return (`VERIFICATION_FAILED`,
+`PLAN_CHANGED` and the rest), and refuses a code it does not recognise instead of explaining it from the shape of the
+string. `everfur explain-error` gives the same answers.
 
 Every tool declares an `outputSchema` and returns `structuredContent`. A failed call carries one envelope
 whatever the tool: `error.code`, `error.retryable`, `error.next_action` (a closed vocabulary),
@@ -303,7 +355,7 @@ the package and the word after it names the binary.
 | `everfur diagnose` | Explain why each capability is or is not available to this caller. |
 | `everfur explain-error` | Explain an API error code: cause, retryability, and next action. Reads the registry from `--contract <file>` when given, otherwise from the contract fetched with `EVERFUR_DOCS_KEY`. |
 | `everfur contract validate` | Validate a contract-public projection: envelope shape, then digest. |
-| `everfur sandbox create` | Provision a partner secret key (Everfur-internal; requires an admin token). |
+| `everfur sandbox create` | Everfur-internal (requires an admin token): mints a partner secret key and, because no claim flow exists to hand it over safely, revokes it again and exits `8`. |
 
 `--json` on any command emits a machine-readable document on stdout, which is what you want in CI.
 
@@ -315,7 +367,7 @@ CI is invited to branch on these. An existing code never changes meaning.
 |---|---|---|
 | `0` | OK | The command produced a complete answer. |
 | `1` | INTERNAL_ERROR | A bug in the CLI, or an unreadable filesystem. |
-| `2` | USAGE_ERROR | Malformed invocation: unknown command or flag, missing flag value. |
+| `2` | USAGE_ERROR | Malformed invocation: unknown command or flag, missing flag value, or an argument value the command does not recognise (for example `explain-error <unknown code>`). |
 | `3` | UNDERSPECIFIED | The CLI refused to guess. Required facts were missing; supply them and retry. |
 | `4` | INVALID_CONTRACT | A named artifact was missing, unparseable, or failed schema validation. |
 | `5` | DIGEST_MISMATCH | A loaded artifact was well shaped but its digest did not match its content. |
@@ -323,6 +375,7 @@ CI is invited to branch on these. An existing code never changes meaning.
 | `7` | VERIFICATION_FAILED | `verify` ran and at least one hard assertion failed. |
 | `8` | SECRET_UNCLAIMABLE | `sandbox create` minted a key but no claim flow exists to hand it over safely. |
 | `9` | BLOCKED | Nothing you asked for can be built today: the contract blocks every capability you named, or the SDK ships no entry point for this project shape. |
+| `10` | CONTRACT_CREDENTIAL_MISSING | The command needs the Everfur contract and has none: no `--contract` file, no `EVERFUR_CONTRACT_PUBLIC`, and no `EVERFUR_DOCS_KEY` to fetch it with. The error says where a docs key comes from, and that the Everfur-hosted MCP connector (OAuth) needs none. |
 
 ---
 
@@ -354,7 +407,7 @@ with no network call and no credential.
 | Variable | Used for |
 |---|---|
 | `EVERFUR_API_BASE_URL` | Everything that touches the network. No default host. |
-| `EVERFUR_PARTNER_KEY` | Your publishable key (`pk_live_...`). Identifies your tenant. A sandbox tenant is issued the same `pk_live_` form; no deployed environment accepts `pk_test_`. |
+| `EVERFUR_PARTNER_KEY` | Your publishable key (`pk_test_...` or `pk_live_...`). Identifies your tenant. The prefix names the tenant mode: `pk_test_` for a sandbox tenant, `pk_live_` for a live one; a sandbox created before `pk_test_` keys may still carry `pk_live_`. |
 | `EVERFUR_PARTNER_SECRET_KEY` | Session minting, server side only. Never ship it in an app, and never put it in an MCP server's environment. `everfur verify` mints with it locally only when `EVERFUR_SESSION_TOKEN` is not set. |
 | `EVERFUR_SESSION_TOKEN` | A short-lived session your backend minted. `everfur verify` and `everfur_verify_integration` use it instead of minting (the MCP tool verifies only this way); `everfur diagnose` uses it for the signed path. |
 | `EVERFUR_DOCS_KEY` | Your partner docs key (`dk_partner_...`). Fetches the contract; accepted by no other route. Minted with `POST /api/v1/partners/docs-keys`. |
@@ -367,8 +420,9 @@ with no network call and no credential.
 | `EVERFUR_MCP_HTTP_ALLOWED_ORIGINS` | Optional browser-origin allowlist. Origins are rejected unless explicitly listed. |
 | `MCP_PUBLIC_URL` | Everfur-internal: the FULL endpoint URL of the hosted service (`everfur-mcp-hosted`), path included (`https://mcp-staging.everfur.com/mcp` on the staging deployment), exactly as a partner pastes it into Claude. It is the OAuth resource every token names and the base of every 401's metadata pointer; a bare origin is refused at start. With `EVERFUR_API_BASE_URL`, `EVERFUR_MCP_HTTP_PORT` and `MCP_TRUSTED_PROXY_HOPS` it is the hosted task's whole environment. Partners do not set this. |
 | `MCP_ALLOWED_HOSTS` | Everfur-internal, optional: extra `Host` values the hosted service accepts beside its own. `MCP_PORT` is read only when `EVERFUR_MCP_HTTP_PORT` is unset. Partners do not set these. |
-| `MCP_ALLOWED_ORIGINS` | Everfur-internal, optional: extra `Origin` values the hosted service's MCP endpoint accepts beside `https://claude.ai` and `https://claude.com`; any other `Origin` is refused with `403`. A browser page at an accepted origin gets its CORS preflight answered and can read the `401` challenge. Partners do not set this. |
+| `MCP_ALLOWED_ORIGINS` | Everfur-internal, optional: extra `Origin` values the hosted service's MCP endpoint accepts beside `https://claude.ai`, `https://claude.com` and `https://chatgpt.com`; any other `Origin` is refused with `403`. A browser page at an accepted origin gets its CORS preflight answered and can read the `401` challenge. Partners do not set this. |
 | `MCP_TRUSTED_PROXY_HOPS` | Everfur-internal, optional: how many proxies appended to `X-Forwarded-For` (`1` behind the load balancer). Keys the hosted service's per-client budget of unauthenticated failures; `0` (default) uses the socket address. Partners do not set this. |
+| `OPENAI_APPS_CHALLENGE_TOKEN` | Everfur-internal, optional: the domain verification token OpenAI's plugin portal generates. Set, the hosted service serves it as the whole plain-text body of `/.well-known/openai-apps-challenge` on its own host; unset or blank, that path is a `404`. Never logged. Partners do not set this. |
 
 **Getting keys:** Everfur keys are currently provisioned by the Everfur team during partner onboarding;
 there is no self-serve signup yet. Contact [support@everfur.com](mailto:support@everfur.com) to get set
@@ -377,8 +431,8 @@ up. The publishable key is designed to ship inside your app; the secret key is n
 ## Documentation
 
 The integration guide, API reference, error catalog and testing guide are at
-[everfur.com/docs](https://everfur.com/docs): adoption paths, the HTTP contract, API keys, the launch
-checklist and troubleshooting.
+[sdk.everfur.com/v1/docs](https://sdk.everfur.com/v1/docs/index.html): adoption paths, the HTTP contract, API
+keys, the launch checklist and troubleshooting.
 
 This page used to link to `github.com/Everfur-Health/everfur-sdk-rn`, which is a PRIVATE repository: the
 link returned 404 for every partner who clicked it, since a partner is outside Everfur by definition. If

package/dist/{chunk-4UB26D67.js → chunk-2MTX6YWO.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, offlineSuggestions, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, knownCodes, buildExplanationDocument, renderExplanation, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, buildSdkExplanationDocument, renderSdkExplanation, buildContractTableExplanationDocument, renderContractTableExplanation, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-KQICUK54.js';
+import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, checkTenantMode, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, resolveWithoutRegistry, knownCodes, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, registryAlsoIn, buildExplanationDocument, renderExplanation, alsoInLines, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, offlineDocument, renderOffline, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-EBVP6FAD.js';
 import { isAbsolute, resolve } from 'path';
 
 // src/cli/format.ts
@@ -186,6 +186,9 @@ function renderRefusal(document) {
     lines.push(`  ${fact.fact}`);
     lines.push(`    why:    ${fact.reason}`);
     lines.push(`    supply: ${fact.supplyWith}`);
+    if (fact.requiredWhen !== void 0) {
+      lines.push(`    only when: ${fact.requiredWhen.fact} is ${fact.requiredWhen.oneOf.join(" or ")}; answer it with that fact`);
+    }
   }
   lines.push("");
   lines.push(...renderDetected(document));
@@ -523,6 +526,14 @@ var CONTRACT_FLAG = Object.freeze({
   summary: "Path to a contract-public projection, used to explain any error code returned.",
   placeholder: "file"
 });
+var PLAN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection to plan from (its decision trees), read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
+var EXPLAIN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection whose error registry answers the code, read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
 var CONTRACT_ENV_VAR = "EVERFUR_CONTRACT_PUBLIC";
 var DEFAULT_CONTRACT_PATHS = Object.freeze([
   "contract-public/contract-public.json",
@@ -613,6 +624,7 @@ var POLL_DELAY_MS = 500;
 var MAX_ATTEMPTS = 20;
 var VERIFICATION_SCHEMA_VERSION = 1;
 var VERIFICATION_DOCUMENT_KIND = "everfur.verification";
+var WEB_EMBEDDINGS = Object.freeze(["in-page", "frame"]);
 var FLAGS = Object.freeze([
   BASE_URL_FLAG,
   {
@@ -630,9 +642,16 @@ var FLAGS = Object.freeze([
   {
     name: "origin",
     kind: "string",
-    summary: "For a web integration: the page origin (https://shop.example.com) the surface is embedded on. Adds the embed fence, CORS exposure, session policy and loader checks.",
+    summary: "For a framed web page (the loader and an iframe): the page origin (https://shop.example.com) the frame renders on. Adds the CORS preflight, embed fence, CORS exposure, session policy and loader checks. An in-page integration needs no --origin.",
     placeholder: "origin"
   },
+  {
+    // The same flag name `plan` takes for the same fact (the argv parser knows it as a value flag).
+    name: "embedding",
+    kind: "string",
+    summary: `With --origin: how the page embeds the surface, ${WEB_EMBEDDINGS.join(" or ")}. frame (the default without --project-root) runs every check; in-page (the SDK's React components in the page) reports the embed fence and the loader N/A, since only the frame uses them. Read from --project-root when not given.`,
+    placeholder: "mode"
+  },
   {
     name: "loader-url",
     kind: "string",
@@ -665,10 +684,12 @@ var FLAGS = Object.freeze([
 function buildVerificationDocument(verification, baseUrl, cliVersion) {
   const counts = { passed: 0, failed: 0, skipped: 0 };
   let gated = 0;
+  let notApplicable = 0;
   for (const entry of verification.steps) {
     if (entry.result === "PASS") counts.passed += 1;
     else if (entry.result === "FAIL") counts.failed += 1;
     else if (entry.result === "GATED") gated += 1;
+    else if (entry.result === "N/A") notApplicable += 1;
     else counts.skipped += 1;
   }
   return {
@@ -677,8 +698,9 @@ function buildVerificationDocument(verification, baseUrl, cliVersion) {
     generatedBy: { name: "@everfur/cli", version: cliVersion },
     status: verification.status,
     baseUrl,
-    // `gated` appears only when a step was GATED, so a document from a run with no surface checks is unchanged.
-    summary: gated === 0 ? counts : { ...counts, gated },
+    // `gated` appears only when a step was GATED, and `notApplicable` only when one was N/A, so a document from a run
+    // with neither is unchanged.
+    summary: { ...counts, ...gated === 0 ? {} : { gated }, ...notApplicable === 0 ? {} : { notApplicable } },
     steps: verification.steps.map((entry) => ({
       id: entry.id,
       title: entry.title,
@@ -709,6 +731,8 @@ function renderVerification(verification, baseUrl) {
     lines.push("Nothing failed, but a step was skipped, so the wire was not fully exercised.");
   } else if (verification.steps.some((entry) => entry.result === "GATED")) {
     lines.push("Nothing failed. A GATED step is a surface Everfur has not switched on for this tenant, not a fault in the integration.");
+  } else if (verification.steps.some((entry) => entry.result === "N/A")) {
+    lines.push("Nothing failed. An N/A step is a check that does not apply to this integration, and it was not run.");
   } else {
     lines.push(
       verification.steps.some((entry) => entry.id === "anonymous-identity") ? "Every step passed. The anonymous identity, the verdict read, and the verdict itself are all healthy." : "Every step passed. The session mint, the verdict read, and the verdict itself are all healthy."
@@ -716,6 +740,12 @@ function renderVerification(verification, baseUrl) {
   }
   return lines.join("\n");
 }
+function parseEmbedding2(raw) {
+  if (raw === null) return { value: null, errors: [] };
+  const value = raw.trim();
+  const known2 = WEB_EMBEDDINGS.find((embedding) => embedding === value);
+  return known2 === void 0 ? { value: null, errors: [`--embedding must be ${WEB_EMBEDDINGS.join(" or ")}, not "${raw}"`] } : { value: known2, errors: [] };
+}
 function parseAttempts(raw) {
   if (raw === null) return { value: DEFAULT_ATTEMPTS, errors: [] };
   const parsed = Number(raw.trim());
@@ -730,7 +760,7 @@ function parseAttempts(raw) {
 var verifyCommand = {
   path: ["verify"],
   summary: "Exercise the wire: mint a session, read the verdict, assert it is not empty.",
-  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
+  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--embedding <mode>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
   flags: FLAGS,
   /**
    * Exactly what `mintSession` resolves: the session token first, else the key pair it mints with locally. Without
@@ -741,6 +771,7 @@ var verifyCommand = {
     const attempts = parseAttempts(flags.string("attempts"));
     const originFlag = flags.string("origin");
     const origin = originFlag === null ? { origin: null, error: null } : parseOrigin(originFlag);
+    const embedding = parseEmbedding2(flags.string("embedding"));
     const loaderFlag = flags.string("loader-url");
     const loader = loaderFlag === null ? { url: null, error: null } : parseLoaderUrl(loaderFlag);
     const surfaces = parseSurfaces(flags.string("surfaces"));
@@ -751,6 +782,7 @@ var verifyCommand = {
     const flagErrors = [
       ...attempts.errors,
       ...origin.error === null ? [] : [origin.error],
+      ...embedding.errors,
       ...loader.error === null ? [] : [loader.error],
       ...surfaces.errors,
       ...identityMode.errors,
@@ -771,6 +803,7 @@ var verifyCommand = {
       attempts: attempts.value,
       pollDelayMs: POLL_DELAY_MS,
       origin: origin.origin,
+      embedding: embedding.value,
       loaderUrl: loader.url,
       transport: context.transport,
       surfaces: surfaces.value ?? [],
@@ -826,7 +859,7 @@ var FLAGS2 = Object.freeze([
     summary: `The Everfur deployment the generated configuration targets: ${ENVIRONMENTS.join(", ")}. Required for a plan that writes configuration; never assumed.`,
     placeholder: "name"
   },
-  CONTRACT_FLAG
+  PLAN_CONTRACT_FLAG
 ]);
 function asJsonObject(document) {
   return JSON.parse(JSON.stringify(document));
@@ -912,8 +945,10 @@ var planCommand = {
         ...environment.errors
       ]);
     }
+    const mode = await checkTenantMode({ env: context.env, environment: environment.value, transport: context.transport, clock: context.clock });
+    if (mode.kind === "mismatch") return errorOutcome("usage_error", mode.message, mode.details);
     const detection = detectProject(context.fs, root);
-    const document = planIntegration({
+    const planned = planIntegration({
       detection,
       capabilities: supplied.capabilities,
       allCapabilities: supplied.allCapabilities,
@@ -924,6 +959,7 @@ var planCommand = {
       space,
       cliVersion: context.version
     });
+    const document = mode.kind === "not_checked" && planned.status === "ready" ? Object.freeze({ ...planned, warnings: Object.freeze([...planned.warnings, mode.warning]) }) : planned;
     const json = asJsonObject(document);
     const text = renderPlan(document);
     if (document.status === "underspecified") return fail(ExitCode.UNDERSPECIFIED, json, text);
@@ -1115,7 +1151,7 @@ var diagnoseCommand = {
 };
 
 // src/commands/explain-error/index.ts
-var FLAGS5 = Object.freeze([CONTRACT_FLAG]);
+var FLAGS5 = Object.freeze([EXPLAIN_CONTRACT_FLAG]);
 var POSITIONALS = Object.freeze([
   {
     name: "code",
@@ -1136,7 +1172,7 @@ var explainErrorCommand = {
       return errorOutcome("usage_error", "no error code was given", ["usage: everfur explain-error <code>"]);
     }
     const offline = resolveOffline(code);
-    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version);
+    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version, "no_registry");
     const contractFlag = flags.string("contract");
     const contractPath = findContractPath(context, contractFlag);
     let load;
@@ -1148,10 +1184,13 @@ var explainErrorCommand = {
         ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
       });
       if (fetched.kind === "unavailable") {
-        if (offline !== null) return offlineOutcome(offline, context.version);
-        const suggestions = offlineSuggestions(code);
-        return contractUnavailableOutcome(fetched, [
-          ...suggestions.length > 0 ? [`did you mean: ${suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no code similar to "${code}" exists in the SDK taxonomy or the SDK contract table this CLI carries`]
+        const resolved = resolveWithoutRegistry(code);
+        if (resolved.kind !== "unknown") return offlineOutcome(resolved, context.version, "no_registry");
+        return errorOutcome("unknown_error_code", `"${code}" is not a code this CLI knows`, [
+          ...resolved.suggestions.length > 0 ? [`did you mean: ${resolved.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no similar code exists in the ${knownCodes(null).length} codes this CLI carries`],
+          "searched: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums",
+          `the live error registry was not read (${fetched.message}); it can list a code these tables predate:`,
+          ...fetched.details.filter((detail) => detail.startsWith("export "))
         ]);
       }
       load = loadErrorRegistryFromContract(fetched.contract);
@@ -1168,11 +1207,11 @@ var explainErrorCommand = {
     const entry = load.registry.lookup(code);
     if (entry === null) {
       const fallback = resolveAfterRegistryMiss(code, load.registry);
-      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version);
+      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version, "registry_miss");
       return errorOutcome("unknown_error_code", `"${code}" is not in the error registry`, [
         ...fallback.suggestions.length > 0 ? [`did you mean: ${fallback.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : ["no similar code exists in the registry"],
         `the registry loaded from ${load.path} lists ${load.registry.codes.length} codes`,
-        `neither the SDK taxonomy nor the SDK contract table this CLI carries knows it either (${knownCodes(load.registry).length} codes searched in all)`
+        `no other table this CLI carries knows it either: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums (${knownCodes(load.registry).length} codes searched in all)`
       ]);
     }
     const input = {
@@ -1181,11 +1220,13 @@ var explainErrorCommand = {
       digest: load.digest,
       cliVersion: context.version
     };
-    return succeed(buildExplanationDocument(input), renderExplanation(input));
+    const document = { ...buildExplanationDocument(input), ...registryAlsoIn(code) };
+    return succeed(document, [renderExplanation(input), ...alsoInLines(document)].join("\n"));
   }
 };
-function offlineOutcome(resolution, cliVersion) {
-  return resolution.kind === "sdk_member" ? succeed(buildSdkExplanationDocument(resolution.code, cliVersion), renderSdkExplanation(resolution.code)) : succeed(buildContractTableExplanationDocument(resolution.row, cliVersion), renderContractTableExplanation(resolution.row));
+function offlineOutcome(resolution, cliVersion, context) {
+  const document = offlineDocument(resolution, cliVersion, context);
+  return succeed(document, renderOffline(resolution, document, context));
 }
 function contractOutcome2(outcome) {
   switch (outcome.kind) {
@@ -1233,7 +1274,11 @@ var FLAGS6 = Object.freeze([
 ]);
 var sandboxCreateCommand = {
   path: ["sandbox", "create"],
-  summary: "Provision a partner secret key and return a claim URL. Never prints the secret.",
+  /**
+   * What the command does TODAY (ROADMAP.md), not the designed claim flow: the live route returns the secret inline and
+   * no claim URL, so the key is revoked unread and the command exits 8 (SECRET_UNCLAIMABLE).
+   */
+  summary: "Everfur-internal. Mints a partner secret key and, because no claim flow exists to hand it over safely, revokes it again and exits 8. 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. */
@@ -1357,20 +1402,14 @@ 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);
-      }
+      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);
@@ -1477,7 +1516,7 @@ function renderRootHelp(commands, version) {
   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(...environmentBlock(CREDENTIAL_SPECS, "all"));
   lines.push(
     "",
     "Not in this release",
@@ -1486,9 +1525,10 @@ function renderRootHelp(commands, version) {
   );
   return lines.join("\n");
 }
-function environmentBlock(specs) {
+function environmentBlock(specs, baseUrlFlag) {
   const lines = ["", "Environment"];
-  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + "API base URL. Overridden by --base-url.");
+  const override = baseUrlFlag === "all" ? " Overridden by --base-url on the commands that take it." : baseUrlFlag ? " Overridden by --base-url." : "";
+  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + `API base URL.${override}`);
   for (const spec of specs) {
     lines.push(`    ${spec.envVar}`.padEnd(FLAG_COLUMN) + spec.summary);
   }
@@ -1521,7 +1561,9 @@ function renderCommandHelp(command) {
   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));
+  if (credentials.length > 0) {
+    lines.push(...environmentBlock(credentials, command.flags.some((spec) => spec.name === "base-url")));
+  }
   return lines.join("\n");
 }
 
@@ -1561,8 +1603,10 @@ async function runCli(options) {
   const specs = match.command.positionals ?? [];
   if (positionals.length > specs.length) {
     const surplus = positionals[specs.length] ?? "";
+    const flagErrors = bindFlags(match.command.flags, parsed);
     return formatOutcome(
       errorOutcome("usage_error", `unexpected argument "${surplus}" after "${commandName(match.command)}"`, [
+        ...flagErrors.ok ? [] : flagErrors.errors,
         `usage: everfur ${match.command.usage}`
       ]),
       format

package/dist/{chunk-FC23PLWG.js → chunk-A2QEBO5U.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { buildServer } from './chunk-XMIERMOW.js';
+import { buildServer } from './chunk-QCXZJW5C.js';
 import { createServer } from 'http';
 import { timingSafeEqual } from 'crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';