# Developer contract changelog

## Documentation

- The self-contained agent bootstrap is now [`/developers/agent-bootstrap.md`](/developers/agent-bootstrap.md). [`/developers/agent.md`](/developers/agent.md) remains a byte-identical compatibility alias so published contract `docsUrl` values keep working. The name change avoids colliding with the [AGENTS.md](https://agents.md) open format.

## Current hosted-runtime compatibility notice

- Public contract v14 still includes
  `operations[].set_intake.intake.quickAnswers.enabled` for schema
  compatibility. When the optional `quickAnswers` envelope is supplied,
  `enabled` remains required by the v14 schema but the hosted runtime ignores
  its value; the linked Scenario's form-first field plan determines whether
  every compatible Voice Campaign uses the hosted form-first journey. Omit the
  envelope unless changing its localized label. This compatibility behavior
  does not replace or disable the active Scenario's `required_disclaimer`,
  which the hosted runtime preserves and includes in the journey.
- `campaign_get` reports the derived `quickAnswers.enabled` state for v14
  clients. It is compatibility output, not a Campaign-level activation switch.

## v14 — Betterstood contract copy

- Updated MCP workflow, server instructions, product-reference descriptions, assistant identity descriptions and credit examples to use Betterstood. Updated the AsyncAPI title and description consistently.
- Advanced the hosted runtime and `elicitra_get_started.contractVersion` to v14 and published the parallel `/developers/v14/` tree. Every previously published `/developers/v1/` through `/developers/v13/` artifact remains byte-immutable and available with no scheduled sunset.
- Kept all fourteen tool names, PATs, scopes, entitlements, quotas, 0-credit MCP operations, export formats, webhook types, signature headers and emitted v5/v6 dataschema URLs unchanged. AsyncAPI remains specification `3.0.0`, document version `1.1.0`.
- Regenerated the current reference guides, agent bootstrap, its `agent.md` compatibility alias and LLM documents from the v14 contract sources.

## v13 — prepaid PAYG account access

- Added `payg` to `elicitra_account_info` and PAYG to Developer Access availability: one member, 25 scenarios, 1,000 campaigns, five active PATs and five webhook endpoints.
- PAYG includes Growth self-service capabilities and bounded beta AI allowances. Ordinary MCP configuration stays at 0 credits; metered respondent execution requires spendable prepaid credits. No subscription, automatic renewal, or monthly credit grant is created.
- Advanced the hosted contract to v13 and published `/developers/v13/`, preserving v1-v12 artifacts byte-for-byte. The fourteen tools, scopes, webhook payloads, emitted v5/v6 dataschema URLs, and AsyncAPI document version `1.1.0` are unchanged.

## v12 — Brand campaign font contract

- Added `brand` to the allowed Campaign `theme.fontPreset` values in draft-update inputs and campaign outputs, selecting the shared Betterstood typography.
- Advanced the hosted runtime and `elicitra_get_started.contractVersion` to v12 and published `/developers/v12/`, preserving all v1-v11 artifacts byte-for-byte with no scheduled sunset.
- The fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit draft authoring are unchanged. Webhook payloads and emitted v5/v6 `dataschema` URLs remain unchanged; AsyncAPI document version stays `1.1.0`.

## v11 — unlimited Scale scenarios

- Scale now includes unlimited stored scenarios in Studio and governed MCP draft creation. Growth retains its 25-scenario quota; deleted scenarios do not consume capacity.
- `elicitra_account_info.usage.scenarios.limit` is now nullable: `null` means unlimited on Scale, matching the existing campaign-limit convention. Clients must handle `null` before numeric comparisons or displaying a remaining count.
- Advanced the hosted runtime and `elicitra_get_started.contractVersion` to v11 and published `/developers/v11/`, preserving all v1-v10 artifacts byte-for-byte with no scheduled sunset.
- The fourteen-tool allowlist, scopes, AI Copilot allowances, and 0-credit draft authoring are unchanged. Webhook payloads and emitted v5/v6 `dataschema` URLs remain unchanged; AsyncAPI document version stays `1.1.0`.

## v10 — Poppins campaign font contract

- Added `poppins` to the allowed Campaign `theme.fontPreset` values in draft-update inputs and campaign outputs, exposing the font already supported by campaign customization.
- Advanced the unversioned hosted MCP runtime and `elicitra_get_started.contractVersion` to v10 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
- Published the parallel `/developers/v10/` artifact tree and preserved `/developers/v1/` through `/developers/v9/` byte-for-byte with no scheduled sunset.
- Kept all four webhook events and payloads unchanged, with lifecycle `dataschema` URLs pinned to v5 and conditional-automation `dataschema` URLs pinned to v6; v10 republishes those unchanged webhook schemas for discovery and keeps AsyncAPI document version `1.1.0`.

## v9 — true multi-select scenario fields

- Added `multi_select` to the governed Scenario field contract used by create, update, get, review, and export operations. It is form-first-only, requires 2–20 stable `{ value, label }` options, and preserves simultaneous selections as ordered arrays.
- Advanced the unversioned hosted MCP runtime and `elicitra_get_started.contractVersion` to v9 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
- Published the parallel `/developers/v9/` artifact tree and preserved `/developers/v1/` through `/developers/v8/` byte-for-byte with no scheduled sunset.
- Kept lifecycle webhook `dataschema` URLs pinned to v5 and conditional-automation `dataschema` URLs pinned to v6; v9 republishes those unchanged webhook schemas for discovery.

## v8 — voice-plan publish readiness

- Added `PUBLISH_VOICE_TIER_UNAVAILABLE` to Campaign draft review results so an integration can distinguish a plan upgrade requirement from caller-number remediation before a human publishes a voice campaign.
- Advanced the unversioned hosted MCP runtime and `elicitra_get_started.contractVersion` to v8 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
- Published the parallel `/developers/v8/` artifact tree and preserved `/developers/v1/` through `/developers/v7/` byte-for-byte with no scheduled sunset.
- Kept lifecycle webhook `dataschema` URLs pinned to v5 and conditional-automation `dataschema` URLs pinned to v6; v8 republishes those unchanged webhook schemas for discovery.

## v7 — shared-resource edit contention

- Added `RESOURCE_LOCKED` for Scenario and Campaign mutations that contend with an active editor lease. Clients must wait for release or expiry and then read the latest revision before retrying; there is no automatic takeover.
- Added optional `expectedRevision` to the common public error object so revision conflicts can report both the attempted and current revisions.
- Advanced the unversioned hosted MCP runtime and `elicitra_get_started.contractVersion` to v7 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
- Published the parallel `/developers/v7/` artifact tree and preserved `/developers/v1/` through `/developers/v6/` byte-for-byte with no scheduled sunset.
- Kept lifecycle webhook `dataschema` URLs pinned to v5 and conditional-automation `dataschema` URLs pinned to v6; v7 republishes those unchanged webhook schemas for discovery.

## v6 — conditional automation destination

- Added optional `definition.assistantName` plus
  `set_metadata.assistantName`; `null` clears the identity-label override while
  Betterstood keeps AI identity and recording/transcription wording server-owned.
- Added `com.elicitra.automation.triggered.v1` with a fixed, data-minimized analysis and `activation` payload.
- Added `deliveryMode` metadata to distinguish the three unchanged `lifecycle_subscription` events from the new `conditional_destination` event. Automation is not subscribable and omits `lifecycleSequence`.
- Published the assistant-name schema addition in the parallel v6 tree while the hosted public MCP runtime remained pinned to v5 until a later runtime migration. The fourteen-tool allowlist and three-event lifecycle subscription inventory stayed unchanged.
- Published AsyncAPI 3.0.0 document version `1.1.0` and the parallel `/developers/v6/` artifact tree.
- Preserved `/developers/v1/` through `/developers/v5/` byte-for-byte with no scheduled sunset.

## v5 — bilingual Betterstood product knowledge

- Added the read-only `elicitra_knowledge_search` tool for customer-safe product concepts, campaigns, credits, pricing tiers, and use cases in `en-US` or `it-IT`.
- Kept the existing `scenario:read` scope, Growth/Scale entitlement, shared rate limits, and 0-credit weight; read PATs now expose 10 tools and full PATs expose 14.
- Kept product-reference search separate from organization scenario Knowledge Base administration and respondent data.
- Published `/developers/v5/` while preserving `/developers/v1/` through `/developers/v4/` byte-for-byte. The three webhook events and payload contracts are unchanged.

## v4 — account context and campaign DRAFT authoring

- Expanded the public catalog from seven to thirteen tools with allowlisted account context and campaign list/get/create/update/review operations.
- Added `campaign:read` and `campaign:write`. Legacy read and write PAT profiles gain the matching effective campaign scopes without rotation.
- Added atomic, idempotent DRAFT campaign updates for scenario, channel, intake, and constrained theme configuration, plus deterministic review and operator handoff.
- Added `CAMPAIGN_LOCKED`; kept publishing, access configuration, provider operations, live testing, and respondent data outside public MCP.
- Published `/developers/v4/`, preserved `/developers/v1/` through `/developers/v3/` byte-for-byte, and kept all three webhook events and payloads unchanged.

## v3 — Live Fit policy

- Added optional `definition.liveFit` to scenario drafts and exports, with at
  most ten ordered typed gates.
- Added the closed `set_live_fit` operation to create/update drafts, including
  explicit acknowledgement for gate removals.
- Kept the public catalog at exactly seven tools and left webhook event types,
  payloads, signature syntax, and the Scenario export envelope unchanged.
- Published `/developers/v3/` as the current contract and preserved
  `/developers/v1/` and `/developers/v2/` byte-for-byte.

## v2 — form-first scenario fields

- Added stable machine `value` plus respondent-facing `label` objects to public select options while continuing to accept legacy string options.
- Published a parallel `/developers/v2/` contract and made `v2` the contract advertised by the hosted MCP endpoint.
- Kept webhook event types, webhook payload shapes, HMAC signature syntax, and the Scenario export format unchanged.
- Preserved `/developers/v1/` byte-for-byte as the previous immutable contract. It is not currently scheduled for sunset.

## v1 — initial public contract

- Added hosted, stateless Streamable HTTP MCP with seven semantic scenario tools.
- Added personal bearer PATs with `scenario:read` and `scenario:write` scopes.
- Added signed `interaction.ended`, `analysis.completed`, and `analysis.failed` lifecycle webhooks.
- Added CloudEvents envelopes, HMAC-SHA256 signatures, replay, JSON Schema, and AsyncAPI artifacts.
- Developer Access is included in Growth and Scale at 0 incremental credits.

No public REST API is part of v1.