# Compatibility and versioning

## Stable surfaces

- MCP endpoint: `https://betterstood.com/api/mcp`.
- Scenario export format: `elicitra.scenario.v1`.
- Webhook event types end in `.v1`.
- The current machine contract lives under `/developers/v14/` and is byte-immutable after publication.
- The previous `/developers/v1/` through `/developers/v13/` trees remain available and byte-immutable; no sunset is currently scheduled.
- Webhook contracts are published as AsyncAPI 3.0.0 (document version `1.1.0`).

MCP protocol negotiation is separate from Betterstood contract versioning. The hosted server is stateless: it creates a fresh protocol server per POST and never returns `Mcp-Session-Id`.

Every published version tree is immutable. Consumers should ignore unknown JSON object properties when reading output, but must send inputs that match the current published closed schemas. Any contract-field addition or descriptive copy change is published under a parallel version before runtime starts returning it.

The unversioned MCP endpoint advertises and serves the `v14` MCP runtime contract. It updates the public descriptions to Betterstood and preserves the v13 account contract. It includes the `payg` plan in `elicitra_account_info`, with one member, Growth self-service features, 25 scenarios, 1,000 campaigns, and five PATs/webhooks. PAYG has no monthly credit grant or renewal; metered execution uses purchased credits, while Growth beta AI allowances are included. It retains `brand` in Campaign `theme.fontPreset` in draft-update inputs and campaign outputs, selecting the shared Betterstood typography. It keeps the same fourteen-tool allowlist and represents unlimited Scale scenario capacity as `null` in `elicitra_account_info.usage.scenarios.limit`, matching the campaign-limit convention. Clients must handle `null` before numeric comparisons or displaying remaining capacity. Growth retains its 25-scenario limit. It retains the v10 `poppins` Campaign font value. It retains the v9 true form-first `multi_select` Scenario fields with 2–20 stable option objects and ordered array values, the v8 `PUBLISH_VOICE_TIER_UNAVAILABLE` Campaign review result, and the v7 `RESOURCE_LOCKED` and optional `expectedRevision` error metadata. Both `initialize.serverInfo.version` and `elicitra_get_started.contractVersion` are `v14`. Versioned directories are pinned machine artifacts, not alternate MCP routes. Webhook event type suffixes (`.v1`), HMAC signature entries (`v1=`), and the `elicitra.scenario.v1` export format are independent protocols.

The assistant-name schema addition and fourth public event required the parallel v6 artifact tree because v5 is immutable. V6 kept the hosted v5 MCP runtime and the three lifecycle subscriptions unchanged until a later runtime migration while adding the non-subscribable `com.elicitra.automation.triggered.v1` conditional-destination event. The later v7 tree is the shared-resource MCP error-contract migration, v8 is the Campaign voice-plan readiness migration, v9 is the true multi-select Scenario field migration, v10 adds the Poppins Campaign font value, v11 makes the scenario capacity limit nullable for Scale, v12 adds the Brand Campaign font value, and v13 adds prepaid PAYG account access, and v14 updates the Betterstood display copy without adding tools or changing access; all preserve the webhook inventory.

Existing lifecycle deliveries remain pinned to their v5 `dataschema` URLs, so a consumer that validates the immutable URL continues to receive the same contract. Only `com.elicitra.automation.triggered.v1` uses the v6 `dataschema`; the v14 tree republishes all unchanged webhook schemas for discovery without changing emitted CloudEvent URLs.

Active MCP and documentation destinations use `https://betterstood.com`. CloudEvent `source` remains `https://elicitra.eigen.rest`, and `dataschema` retains its published `https://elicitra.eigen.rest/developers/v5/` or `/v6/` identity. These are immutable wire identifiers, independent of HTTP routing. Download pinned schemas from `https://betterstood.com/developers/v5/` or `/v6/` at the same schema path; preserve the downloaded bytes, original `$id` and event identity. Queued events retain their original bytes and signature inputs. This does not require the legacy host to remain online.

The versioned `manifest.json` publishes a deterministic `sha256:` digest for every MCP input/output and webhook data schema. Consumers can use those hashes to pin reviewed contracts and detect accidental artifact drift.

An incompatible change introduces a parallel version. Betterstood retains the previous public tool/event artifacts for at least 180 days. If a version is deprecated, its deprecation and sunset dates are published here and in the changelog before removal.

## Runtime brand identifiers

The rebrand does not rename published tool names, PATs, export formats,
webhook types or the `elicitra-signature` header. Keep using
`elicitra_get_started`, `elicitra_account_info` and `elicitra_knowledge_search`.
The server advertises `betterstood-developer-access`; existing client entries
named `elicitra` and environment references to `ELICITRA_MCP_TOKEN` remain valid.
New setup examples use `betterstood` and `BETTERSTOOD_MCP_TOKEN`.

HTTP request headers accept both `x-betterstood-*` and the corresponding
`x-elicitra-*` names for locale, test/poll/web tokens and call/session/device
identifiers. A supplied canonical value takes precedence, even if invalid.
Release/runtime identity responses include both names; health responses omit
both. Existing authentication and endpoint permissions are unchanged.

Legacy aliases have no automatic expiry. Retirement requires all dependencies
migrated or decommissioned and verified, plus separate approval in
[LINEAR-736](https://linear.app/eigensource/issue/LINEAR-736/rimuovere-alias-legacy-dopo-il-rebrand).
The published minimum artifact overlap above is a floor, not an alias sunset.
The application records legacy header/cookie family names without values;
MCP telemetry retains the requested stable tool name and outcome. Traffic
silence alone does not permit removal. No additional metered operation is added.

## Client support

Betterstood tests the current stable Codex CLI/IDE extension, Claude Code, and Cursor against staging before GA and after transport changes. A client is listed as supported only if it can:

1. send an environment-backed bearer token;
2. negotiate stateless Streamable HTTP without GET/session requirements;
3. list the correct scope-filtered tools;
4. complete the draft workflow without storing the PAT in the project.

If a client release cannot meet those invariants, the release is marked temporarily unsupported; Betterstood does not weaken tenant, auth, or stateless transport controls to accommodate it.