@everfur/cli 0.1.0 → 0.2.1

package/README.md

@@ -3,33 +3,278 @@
 Plan, verify, and diagnose an [Everfur](https://everfur.com) pet-health integration from the terminal,
 and serve the same tools to your coding agent over MCP.
 
-Everfur lets partner apps embed veterinary chat, health records, and pet-state surfaces via
-`@everfur/sdk` (React Native). This CLI is the integration companion: it reads your project, plans the
+Everfur lets partner apps and pages embed veterinary chat, health records, and pet-state surfaces via
+`@everfur/sdk` (React Native and Expo; the web through `@everfur/sdk/web` and a hosted frame; Flutter
+through `everfur_sdk`). This CLI is the integration companion: it reads your project, plans the
 integration, exercises the live wire, and explains what it finds.
 
+**On the web the plan follows what the project is.** A React tree (react-dom in `package.json`) embeds the
+SDK's components in the page and installs the package; any other page (Vue, Svelte, a static page, a CMS
+template) includes a 2 KB loader and gets the chat in an iframe on Everfur's origin, installing nothing;
+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.
+
+**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}`
+(`theme.extend.colors`, `fontFamily`, `borderRadius`, with `hsl(var(--x))` resolved through your CSS), `:root`
+custom properties (`--primary`, `--brand`, `--background`, `--radius`, `--font-sans` and their common spellings,
+in a stylesheet or a static page's `<style>`), or a React Native theme or colours file (a react-navigation
+`Theme`, the Expo template's `constants/Colors.ts`). What maps unambiguously is written as the SDK's `theme` prop
+(`primaryColor`, `accentColor`, the dark variants, `brightness`, `surfaceStyle`, `radiusScale`, `fontFamily`, every
+colour as `#RRGGBB`), each field citing the file and line it came from, and the plan's `match-theme` step names
+the source. A React Native theme file's exact `fontFamily: '<Name>'` literals become the SDK's per-weight `fonts`
+map (`regular`, `medium`, `bold`: family names only, mapped by the weight word in each name, as in `Azeret-Regular`
+or `Inter_500Medium`; the one plain family a file names stands in for the regular face and is marked
+`REPLACE: verify`); the app registers the faces itself, the SDK bundles no font and synthesizes no weight on a named
+face, and a family the file does not name is never written. The frame's init never carries the map, since a family
+the page registered does not exist on Everfur's origin. A primary and a background read as literals from one source is high confidence; part of the picture
+is medium, and every field is then marked `REPLACE: verify`; anything less (nothing found, a computed value, a
+config that runs code when it loads) is low: no theme is written, and the step names the exact missing facts and
+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.
+
+**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
+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
+picker with `expo-image-picker` (`launchImageLibraryAsync({ mediaTypes: ['images'], quality: 0.85, selectionLimit:
+1 })`, `launchCameraAsync({ quality: 0.85 })` for the camera) and never calls `requestMediaLibraryPermissionsAsync`
+first, because a pre-request that is denied once disables the picker for good, and `copyText` is
+`expo-clipboard`'s `setStringAsync`, and `pickRecordsDocument` opens the system document UI with
+`expo-document-picker` for the records upload; the plan's `install-host-modules` step names the three modules as
+optional to the SDK, one sentence each. A bare React Native app passes **neither** prop and imports neither package: React
+Native ships no picker and no clipboard, so anything emitted as live code would be a stub, and a prop wired to a
+stub renders an attachment control that attaches nothing and a Copy control that copies nothing, while without the
+props the SDK renders neither control. The same helpers are emitted there as commented recipes naming
+`react-native-image-picker`, `@react-native-clipboard/clipboard` and `@react-native-documents/picker` (the current
+name: `react-native-document-picker` is deprecated), each between its own named markers, beside the commented
+`attachments`, `onCopy` and `onPickDocument` lines in the mounts; each recipe and its prop lines name each other, so
+both halves are uncommented together once the packages are installed. `tests/contract/plan-compiles.test.ts`
+compiles that uncommented result, so a recipe is held to the same standard as the code around it.
+
+**What the records upload accepts** is read from the SDK, not assumed: `application/pdf` compared exactly, at most
+25 MiB, and a handle with no `sizeBytes` is refused as oversize, so the generated picker asks the document UI for
+PDFs, passes the type the OS reported (falling back to the file extension, never claiming `application/pdf` merely
+because it asked for one) and always carries the size when the picker reports it. Photos are not an accepted
+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
+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
+`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
+`'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
+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
+document with no credential value in it.
+
 ## The fastest path: let your agent do it
 
-The Everfur MCP server ships with this package (and standalone as `@everfur/mcp`). Add it to your
-agent's MCP configuration:
+### 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:
+
+```
+https://mcp-staging.everfur.com/mcp
+```
+
+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.
+
+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"}}}`
+- **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)
+
+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
+registration, RFC 7591), and you are sent to the Everfur partner console to sign in and approve. From then
+on every tool runs as the tenant of that console session.
+
+The tools are the same five as below, plus eight that read your own tenant, with these differences that follow
+from where the server runs:
+
+1. It cannot read your disk. Describe the project with `project_details` (dependencies, package manager and
+   file-presence markers, never source files) and, to match your theme, pass `theme_source` (the text of your
+   Tailwind config or the CSS that declares your colours; read statically, never executed). `project_root` and
+   `contract_path` are not offered there (sent anyway, they are refused with `LOCAL_PATH_NOT_READABLE`), and
+   the offline project checks of `everfur_verify_integration` and `everfur_diagnose` are not available there.
+   An omitted `environment` plans for the deployment your tenant is on.
+2. `everfur_verify_integration` runs with a short-lived session the Everfur API mints for a synthetic test user
+   (`everfur-verify-...`) of your **sandbox** tenant on each call. Signed in as a live tenant, the session step
+   is reported `GATED` and the wire exercise does not run. `everfur_send_test_message` refuses a live tenant, as
+   it does everywhere.
+3. The hosted service holds no secret key, no docs key and no per-tenant key. On every request it verifies
+   your editor's sign-in with the Everfur API and resolves your tenant's publishable key from that answer;
+   the contract is served to the signed-in partner. The Everfur API re-checks on every such call that the
+   signed-in user is still an admin of an active partner tenant, and the service re-asks it at most every
+   60 seconds, so a removed admin or a deactivated tenant loses access within a minute.
+4. Eight read-only tools answer questions about your tenant, as the partner console does:
+   `everfur_get_tenant_status` (plan, features, mode, embed origins, entitlements, your publishable key's id
+   and prefix, Televet return keys and booking lead), `everfur_list_webhook_endpoints`,
+   `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).
+
+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.
+
+### Local MCP: the same block for every editor
+
+The Everfur MCP server ships with this package (and standalone as `@everfur/mcp`). Add this one block to
+your agent's MCP configuration. It is the same block for Claude Code, Cursor and VS Code; only the file it
+goes in differs:
+
+- **Claude Code:** `.mcp.json` at the project root (or `claude mcp add-json everfur '<the everfur entry>'`
+  for your user scope).
+- **Cursor:** `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project).
+- **VS Code:** `.vscode/mcp.json` in the workspace, which wraps the same `everfur` entry under a `servers`
+  key instead of `mcpServers`.
 
 ```json
 {
   "mcpServers": {
     "everfur": {
       "command": "npx",
-      "args": ["-y", "@everfur/mcp"],
+      "args": ["-y", "-p", "@everfur/mcp", "everfur-mcp"],
       "env": {
-        "EVERFUR_API_BASE_URL": "https://api.everfur.com/api/v1",
-        "EVERFUR_PARTNER_KEY": "pk_live_your_key"
+        "EVERFUR_API_BASE_URL": "https://api-staging.everfur.com/api/v1",
+        "EVERFUR_PARTNER_KEY": "pk_live_your_sandbox_tenant_key",
+        "EVERFUR_DOCS_KEY": "dk_partner_your_docs_key",
+        "EVERFUR_SESSION_TOKEN": "a_short_lived_session_your_backend_minted"
       }
     }
   }
 }
 ```
 
-Then ask your agent to add Everfur to your app. The `everfur_plan_integration` tool reads your project,
-refuses to guess the facts only you can answer (which capabilities, which identity mode), and returns a
-plan whose steps include the complete integration file, ready to write.
+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_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. |
+
+The secret key (`sk_partner_...`) never appears in an MCP configuration: the server never reads it. Going
+live changes every value in the block: the production base URL, and the production tenant's own publishable
+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
+`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}`);
+the value is returned once. A docs key authenticates the contract route and no other route. Without it,
+`everfur_plan_integration`, `everfur_explain_error`, the `everfur://contract/*` and `everfur://guide*`
+resources, and the prompt completions refuse with `CONTRACT_CREDENTIAL_MISSING`. The partner secret key and
+the publishable key are not accepted for the contract; do not put the secret key in an MCP configuration.
+
+`EVERFUR_SESSION_TOKEN` is for `everfur_verify_integration`. It is a short-lived session your backend minted for a
+test user (the same mint your session route performs); the tool reads the entitlement verdict and the surfaces with
+it, and mints nothing itself. The server never reads `EVERFUR_PARTNER_SECRET_KEY`, even when it is set: the secret
+key stays on your backend. Sessions expire, so mint a fresh one before verifying; without one the session step is
+skipped and names the variable.
+
+Then ask your agent to add Everfur to your app. The `everfur_plan_integration` tool reads your project
+(the framework and package manager are detected, never asked) and refuses to guess the facts only you can
+answer, naming each one:
+
+1. **Which capabilities**, chosen from the contract's list (`chat`, `records`, `televet`, `events`, ...). The
+   refusal lists the ids the loaded contract can plan, and `all` names every one of them; a name the contract
+   does not list is refused with `UNKNOWN_OPTION`, never taken as free text. The plan holds no credential, so
+   `everfur verify` is the fail-closed check of what your tenant actually has.
+2. **How your users sign in**: `partner-user-ref` (your backend mints a session for your own user id),
+   `shopify-app-proxy` (a Shopify storefront vouches for the signed-in customer) or `anonymous`.
+3. **Which environment** the generated configuration targets (`staging` or `production`).
+4. **The language of the backend that mints sessions**, asked for `partner-user-ref`, because that is
+   the one mode where the plan generates a session route for you, and for `events`, because the webhook
+   receiver it generates (the server-side copy of every event about your members, for your own handling;
+   the members' push and email are sent by Everfur through the `notifications` lane) is written in it. A
+   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.
+
+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.
+
+### Run it on your own server
+
+For a partner-operated cloud/server deployment, run the guarded Streamable HTTP entry point behind TLS:
+
+```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.
+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.
+export EVERFUR_SESSION_TOKEN="..."
+export EVERFUR_MCP_HTTP_ACCESS_TOKEN="$(openssl rand -base64 48)"
+export EVERFUR_MCP_HTTP_HOST="0.0.0.0"
+export EVERFUR_MCP_HTTP_ALLOWED_HOSTS="mcp-staging.partner.example"
+npx -y -p @everfur/mcp everfur-mcp-http
+```
+
+It serves `POST /mcp` on port `3100` by default. Put a TLS reverse proxy in front of it and inject both
+the Everfur credentials and `EVERFUR_MCP_HTTP_ACCESS_TOKEN` from your server-side secret manager. Do not
+put either secret in an agent prompt, a browser, or a client bundle. The HTTP process is stateless and can
+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.
+
+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),
+`error.request_id`, `error.docs_path` and `error.details`. The server also serves resources (the fetched
+contract under `everfur://contract/*` and an integration guide rendered from its decision trees under
+`everfur://guide/*`, both requiring the partner docs key; the tool refusal codes and the JSON Schemas,
+served offline) and three prompts: `integrate-web`, `integrate-react-native` and `diagnose-integration`.
 
 ## Install the CLI
 
@@ -44,7 +289,8 @@ npx -y -p @everfur/cli everfur plan
 ```
 
 Plain `npx @everfur/cli` does not work, and the error it gives ("could not determine executable to
-run") does not explain why: this package ships two binaries, `everfur` and `everfur-mcp`, and npx only
+run") does not explain why: this package ships four binaries, `everfur`, `everfur-mcp`,
+`everfur-mcp-http` and `everfur-mcp-hosted` (the entry Everfur runs itself), and npx only
 picks a binary on its own when there is exactly one, or when one is named after the package. `-p` names
 the package and the word after it names the binary.
 
@@ -55,7 +301,7 @@ the package and the word after it names the binary.
 | `everfur plan` | Produce an integration plan for the project in the current directory. |
 | `everfur verify` | Exercise the wire: mint a session, read the verdict, assert it is not empty. |
 | `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. |
+| `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). |
 
@@ -76,7 +322,7 @@ CI is invited to branch on these. An existing code never changes meaning.
 | `6` | REMOTE_FAILURE | The API could not be reached, timed out, or answered with a typed error. |
 | `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 | Everything you asked for is blocked by the contract; nothing can be built today. |
+| `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. |
 
 ---
 
@@ -90,15 +336,39 @@ but a sandbox tenant.
 ## Credentials
 
 Configuration comes from environment variables only. No `.env` file is read.
-No command prints, logs, or writes a credential; two commands DO handle them in memory: `everfur sandbox create` mints a partner
-secret (and requires `EVERFUR_ADMIN_TOKEN`), and `everfur verify` reads your keys to exercise the wire.
+No command prints, logs, or writes a credential; four commands DO handle them in memory: `everfur sandbox create` mints a partner
+secret (and requires `EVERFUR_ADMIN_TOKEN`), `everfur verify` reads your keys to exercise the wire, and
+`everfur plan` and `everfur explain-error` present your partner docs key to fetch the contract.
+
+**The contract is fetched, not bundled.** `everfur plan`, `everfur explain-error`, `everfur diagnose --bundle`
+and the MCP server read the Everfur contract from `GET /partners/contract` on `EVERFUR_API_BASE_URL`, sending
+`EVERFUR_DOCS_KEY` in the `x-everfur-docs-key` header. They never send `EVERFUR_PARTNER_SECRET_KEY` there, and
+the route refuses it. The response is checked against the
+contract envelope schema and its digest before it is used. It is cached under `EVERFUR_CACHE_DIR`, else
+`$XDG_CACHE_HOME/everfur/contract`, else `~/.cache/everfur/contract`, keyed by the API base URL and the contract
+digest; later runs send `If-None-Match` and reuse the cached copy on a `304`. When the API cannot be reached, a
+cached copy is used and labelled as not revalidated; when the API rejects the key, the cache is not used. A
+projection file named with `--contract`, `contract_path` or `EVERFUR_CONTRACT_PUBLIC` is read from disk instead,
+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. |
-| `EVERFUR_PARTNER_SECRET_KEY` | Session minting, server side only. Never ship it in an app. |
+| `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_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`. |
+| `EVERFUR_CACHE_DIR` | Optional directory for the cached contract. |
+| `EVERFUR_CONTRACT_PUBLIC` | Optional path to a contract-public projection file, used instead of fetching the contract. |
 | `EVERFUR_ADMIN_TOKEN` | Everfur-internal administration. Partners do not need this. |
+| `EVERFUR_MCP_HTTP_ACCESS_TOKEN` | Required to run the self-hosted HTTP MCP; protect the endpoint from its clients. |
+| `EVERFUR_MCP_HTTP_HOST` / `PORT` / `PATH` | Optional HTTP listener configuration; defaults to `127.0.0.1:3100/mcp`. `EVERFUR_MCP_HTTP_PORT` is also the hosted service's port. |
+| `EVERFUR_MCP_HTTP_ALLOWED_HOSTS` | Required for any non-loopback bind; comma-separated public hostnames only. |
+| `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_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. |
 
 **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
@@ -106,8 +376,14 @@ up. The publishable key is designed to ship inside your app; the secret key is n
 
 ## Documentation
 
-The full integration guide, API reference, error catalog, and testing guide ship with the SDK:
-[`@everfur/sdk` docs](https://github.com/Everfur-Health/everfur-sdk-rn/tree/main/docs/partner-integration).
+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.
+
+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
+a doc you need is not on the site yet, ask [support@everfur.com](mailto:support@everfur.com) rather than
+looking for a repository you cannot open.
 
 ## License