Changelog

Versioned releases. Pin a version with Archie-Version: YYYY-MM-DD in your requests to freeze the behaviour your code was built against. Breaking changes are flagged — they're rare, and come with migration notes.

2026-06-12alpha

Slack: citation cards on Archie's answers — for the first time, ever

•Citation reference cards on Archie's own Slack answers have never rendered — and couldn't: the delivery path asked Slack to unfurl the bot's own message after posting, but Slack only accepts an unfurl for a link it saw a human share (apps never receive `link_shared` for their own messages). Yesterday's activation note blamed the missing unfurl-domain registration; with the domain registered the call still failed, which exposed the deeper rule. Cards now travel inside the answer message itself as attachments, built before posting — same visual, a mechanism Slack actually permits. Proven live: a real ASC 606 answer carries five citation cards (capped at five per message). (PR #7032)
•Citation links a person pastes into Slack now also get cards: `/r/` reference links joined topic permalinks in the `link_shared` handler — previously the one mechanism Slack does allow for citation cards wasn't wired. Topic links and citation links mix in a single unfurl; only topic links carry Work Object entities. (PR #7032)
•Repo manifests now place `unfurl_domains` where Slack's manifest API accepts it (`features`, not `event_subscriptions`) — they previously worked only as human reading material and could never be applied programmatically. (PR #7028)

2026-06-12alpha

Three skill outputs gain the uniform disclosure surface

•`derive_period`, `enrich_tb_rows`, and `detect_tb_duplicates` outputs now carry the platform-standard `stub_fields` and `warnings` arrays like every other skill output — they had shipped without the disclosure mixin, so callers reading those fields uniformly would have hit missing keys. Additive on the wire (both fields default to empty lists); the OpenAPI spec, agents.md, and llms.txt are regenerated to match. (PR #7074)

2026-06-12alpha

For contributors: alpha PRs are test-gated again (they hadn't been since May 1)

•When the PR line moved from develop to alpha on 2026-05-01, no test workflow followed: the regression harness still filtered on develop, so no automated test gated any alpha merge for six weeks. Two gates now run on every alpha PR touching `apps/api`: the contract suite (1,400+ architectural guards, infra-free, ~1 minute) and the resurrected regression harness — real Postgres and Redis containers, migrations, seeded data, a booted API (running as a non-superuser role so row-level security stays enforced in CI), and L0/L1 smoke. The harness's green run on its own enabling PR was the first in its recorded history. (PRs #7051, #7077)
•The rot the gates surfaced is fixed alongside: stale guards repinned to deliberate changes, a test file whose fixtures never existed anywhere now runs (first time since #4090), and live-DB contract audits skip cleanly in CI via the new `ARCHIE_TEST_SENTINEL_KEYS` signal instead of failing on the sentinel DSN. (PRs #7051, #7069)

2026-06-11alpha

One identity per API key: REST, SDK, and CLI topics now work end-to-end

•The same sk_ key resolved to two different identities depending on transport: MCP acted as the key's creator, while REST (and therefore the Python SDK and CLI, which ride it) invented a synthetic per-key user that row-level security didn't recognise. The visible symptoms: `topic_list` always returned `{topics: [], total: 0}` over REST while the same key saw everything over MCP, `topic_get` 500'd, and every topic WRITE over REST failed with a 500 — including from the published PyPI 1.3.0 package. One shared resolver now derives the caller identity on every surface: act as the key's creator when the key has one, fall back to the per-key service actor otherwise. (PR #6917)
•What changes for you: topic reads and writes succeed over `POST /api/v1/skills/topic_*/invoke`, the typed SDK methods, generic `skills.invoke`, and `archie skills run topic-*` — verified live in both directions against MCP with the same key. Note the semantics: requests made with a key now run as the person who minted it (their topic visibility, their attribution), which is what MCP has always done.
•Also in this pass: every scope example in the Python SDK docstrings used a pre-consolidation vocabulary (`tax:read` etc.) that matches no skill since the 11-scope taxonomy — copied examples silently filtered the registry to zero skills. Examples now use live scopes, and a denylist test keeps retired vocabulary out of the packaged sources. (PR #6973)

2026-06-11alpha

Topics hardening: creator membership parity and the artifact-attach 500

•Topics created over MCP/REST now record the creator as a topic member, exactly like topics created in the web app — previously agent-created topics had no membership row, so anything that reads memberships (participant pips, share lists, the membership clause of the visibility gate) treated them differently. (PR #6955)
•`POST /api/v1/topics/{id}/artifacts` with a `metadata` object committed the row, bumped the topic's activity, then returned a 500 — and the natural retry hit `409 already linked`. Cause: the add path returned the database's raw JSON-as-string metadata into a response model that requires an object; the read path already normalised it. Both paths now return the same parsed shape; the call returns 201 with your metadata echoed back, queryable. (PR #6960)

2026-06-11alpha

Slack: /compliance answers again, and topic links become rich cards

•`/compliance` had returned an error block for every user on every tier since May — it was the one slash command still wired to a typed-input skill, which can never accept freeform slash text. It now routes to the conversational path like every other command, and a drift test pins the whole command surface (registered manifests ↔ code map ↔ App-Home help ↔ the {query} wire contract) so a command can no longer ship wired to a skill that rejects slash input. (PR #6946)
•Topic links pasted in Slack unfurl as rich cards: Archie answers `link_shared` events with Slack's new Work Object entities (with classic Block Kit fallback for clients without the feature). Cards show only what the Topics list already shows — name, type, id, last activity — and a permalink only resolves inside the Slack workspace's own organization. (PRs #6984, #6988)
•Activation note (dev tier): the card rendering switches on with the app-config update (Work Object Previews toggle, `link_shared` event, `links:read` scope, and registering the unfurl domain — the missing domain registration turned out to also be why citation reference cards were silently absent on the dev workspace).

2026-06-11alpha

Typed SDK methods and CLI commands, generated from the skills registry

•One generator now reads the canonical skills registry and emits the typed surface for all three clients: 65 typed Python methods (sync and async — `client.skills.list_clients(...)` with real keyword arguments instead of a payload dict), 65 typed TypeScript methods at `archie.skills.generated` (each with its own input interface, e.g. `topicAsk(input: TopicAskInput)`), and 65 `archie skills run <skill>` CLI commands. A new skill in the registry appears in all three on the next regenerate, and a CI parity check fails the build if any artifact drifts. (PRs #6874, #6878)
•CLI: every wire field becomes a flag — `archie skills run list-clients --json`, `archie skills run derive-period --kind bas_au_monthly --anchor-date 2026-04-30 --json`. Required fields are enforced (`--kind TEXT [required]` in `--help`), nested object/array inputs are passed as JSON strings, and the generated commands share the exact auth and `--json` plumbing of the generic `archie skills invoke`.
•What your install gets today: the typed surface ships in heyarchie 1.4.0, which is not yet on PyPI — `pip install heyarchie` currently serves 1.3.0, where the generic `client.skills.invoke(slug, payload)` is the only entry point. The TypeScript package (heyarchie 2.1.0) is not yet published to npm; until then build it from the repo's `apps/sdk-typescript`. The generic `invoke()` path is unchanged either way — typed methods delegate to it.
•TypeScript fixes in the same pass: `skills.list()` called `/v1/skills`, which 404s against the live API — now `/api/v1/skills` — and `SkillCatalog` gained the `skills` array the wire actually returns (`data` kept for older shapes). The client config key is `baseURL`.
•Generator hardening from the review round (#6878): `$ref`/`$defs` resolution so string-enums type as strings rather than objects, zero-parameter skills no longer emit invalid signatures, reserved-name collision guards abort generation rather than shadow hand-written methods, and docstrings escape backslashes and quotes from skill descriptions.

2026-06-11alpha

topic_messages: read a topic's thread from any surface

•A seventh topic skill completes the read direction of surface parity: `topic_messages` returns a topic conversation's messages chronologically, paginated — per message the content, role, `query_id` (the thinking-steps key), model, citations, and artifact refs from the persisted envelope. (PR #6898)
•It pairs with `topic_ask`: when an ask times out the response says the turn is still running server-side — `topic_messages` is how you poll for the answer. Turns made on the web are now readable over MCP/REST, and turns made over MCP/REST were already readable on the web, so a topic can be picked up from either side.
•The reader never writes: an empty topic returns an empty page instead of auto-creating a conversation, and a `conversation_id` from another topic is rejected. Requires the `topics:read` scope. Live on MCP, REST (`POST /api/v1/skills/topic_messages/invoke`), the Agent 365 manifest, and the typed SDK/CLI surface above.

2026-06-11alpha

Portal: sign-out actually signs you out, plus a design pass

•Sign-out on the dashboard was a no-op: it cleared the session cookie under a hard-coded fallback domain while the API sets the cookie under the tier's real cookie domain, and cookie deletion only matches an exact (name, domain, path). The portal now clears every candidate domain, calls the API's `POST /auth/logout` first so the token is revoked server-side, and `GET /api/v1/auth/me` now rejects revoked tokens — previously a revoked token still validated on the exact endpoint the portal uses to check sessions. (PR #6879)
•Design pass across the portal, driven by a 29-page desktop + mobile survey of the live site: the dashboard is now usable on a phone (the fixed sidebar rail hides on small screens, replaced by a sticky swipeable section strip), two pages with invisible navy-on-navy headings (Settings, Organizations) are legible again, and the stale light-theme modals (revoke / rotate key) plus four divergent empty states (Usage, Logs, Connections, Webhooks) moved onto the dark portal token system. Mobile nav and dark-theme consistency throughout. (PR #6892)

2026-06-10alphabreaking

Permission scopes consolidated: 16 → 11, catalog now registry-derived

2026-06-10alpha

Topics land on the Connect surface: six topic_* skills

•Topics — previously reachable only through the web app's session-authed REST — are now first-class Connect skills: `topic_list`, `topic_create`, `topic_get`, `topic_link_conversation`, `topic_post_message`, `topic_ask`. Each has typed input/output schemas and is live on MCP, REST (`POST /api/v1/skills/{slug}/invoke` with an API key), and the Agent 365 manifest. (PR #6804)
•`topic_ask` dispatches a real orchestrator turn inside the topic and waits for the answer; if it can't finish in time it returns `status="running"` and the turn keeps executing server-side — nothing is lost on a client timeout. `topic_post_message` persists the message and dispatches fire-and-return, reporting `submitted` or an inline `completed` with the answer.
•`topic_get` optionally resolves the topic's canvas descriptor (None when no domain run has produced one). `topic_link_conversation` is idempotent when re-linking within the same topic and errors loudly on a cross-topic conflict.
•Scopes: `topics:read` / `topics:write` for the CRUD skills, `ask:execute` for the two dispatch skills (named under the consolidated taxonomy — see the scopes entry above).

2026-06-04alpha

Outbound webhooks: Archie tells you when he's done

•Register an HTTPS endpoint and the events you care about, and Archie POSTs a signed payload when a matching event lands, so you can stop polling for the result of a long job. Today that covers `workstream.run.completed` and `workstream.run.failed` (with `playbook.run.*` kept as legacy aliases) plus `api_key.created` and `api_key.deleted`. Manage endpoints from the dashboard Webhooks page; each one gets a signing secret shown exactly once.
•Every delivery is signed. The `X-Webhook-Signature` header is `v1=HMAC-SHA256` over `{timestamp}.{body}`, alongside `X-Webhook-Timestamp`, `X-Webhook-Id`, and `X-Webhook-Event`. Verify it against the raw body and reject anything signed more than five minutes ago. Delivery is at least once with exponential backoff (1, 2, 4, 8, 16s) and a dead-letter after five attempts, so treat `X-Webhook-Id` as the idempotency key.
•Endpoints are restricted to public HTTPS hosts, re-checked on every delivery, so an endpoint cannot be pointed at an internal address. The new `/docs/webhooks` guide covers registration, the delivery shape, signature verification (copy-paste Python and Node), retries, and the events catalogue. The live event list is served at `GET /v1/webhooks/event-types`.

2026-06-04alpha

Idempotency on the skills API, plus a documentation accuracy sweep

•The skills API now honours the `Idempotency-Key` header on writes. A retried call carrying the same key within 60 seconds replays the original response (marked `X-Idempotent-Replayed: true`) instead of running again, so a network retry cannot post twice. It is opt-in and namespaced per user, so reads are unaffected. See the Retry Semantics section of `/docs/error-handling`.
•New `/docs/environments` page. There is one production API at `api.heyarchie.ai` and one environment. The `sandbox` or `live` label on a key is organisation metadata that gates nothing, which the page now states plainly.
•New `/docs/pagination` page documenting the real `limit` / `offset` / `has_more` pattern the list endpoints share. The WorkStreams page previously described a `next_cursor` the API does not return, and the error-handling page promised an `Idempotency-Key` that was not wired; both are now corrected (the idempotency one by wiring it, above).
•The API reference adds a Download OpenAPI control plus a note that the 3.1 spec imports straight into Postman or Insomnia, and its left nav collapsed the duplicated WorkStreams tags into one consistent family.

2026-06-03alpha

WorkStreams taxonomy: Blueprint renamed to Workplan

•The WorkStreams noun for a template bound to a client is now **Workplan**, not Blueprint. The taxonomy reads WorkStream → Workplan → Cycle → Task. The canonical REST surface is `/api/v1/workstreams/workplans/...` (list, create, get, update, archive, write-status, enable/disable-writes, triggers).
•Non-breaking. Every old `/api/v1/workstreams/blueprints/...` path still works. It is now a deprecated alias on the same handler, flagged `deprecated` in the OpenAPI spec, and will be removed in a future release. Update integrations to the `workplans` path when convenient.
•Response and request field names are unchanged: `blueprint_id` is retained as a deprecated alias field so existing payloads keep parsing. OpenAPI schema titles moved to Workplan / WorkplanCreate / WorkplanListResponse / WorkplanUpdate.
•Spec, llms.txt, agents.md, and the API reference regenerated from the live registry so the catalogue reads Workplan everywhere. No DB, FGA, or Temporal rename in this pass; only the developer-facing URL and display layer moved.

2026-05-18alpha

Per-key knobs land — workspace pin, rate-limit cap, description

•API keys now carry per-key metadata our mirror table holds independently of WorkOS: `workspace_id` (pin a key to a workspace in multi-workspace orgs), `rate_limit_per_minute` (override the 60/min default — wins over org override), `description` (free-text label), `environment` (sandbox|live). All four are editable in the portal Keys page (click a row to expand the detail panel — auto-saves 600ms after you stop typing) or via the SDK's new `client.keys.update(key_id, **fields)`.
•New SDK methods on `client.keys` (heyarchie 1.2.0): `get(key_id)` for single-key reads, `update(key_id, **fields)` for PATCH, `rotate(key_id, grace_period_hours=24)` for the mint-replacement-then-expire-parent flow. The rotated key inherits all of the parent's metadata; backend reaper job revokes the parent after the grace window expires. Existing `create()` now accepts all four mirror fields at create time.
•Backend now owns the entire keys lifecycle. `/api/v1/connect-keys/*` is the canonical customer-facing surface (list, get, create, patch, delete, rotate); WorkOS is a private secret-store implementation detail. Portal dashboard, SDK, CLI, and MCP all speak the same surface.
•Cache invalidation is automatic — PATCH writes the new rate-limit value directly into the in-process cache, DELETE flushes both the validator and the per-key cache, so any in-flight cached token gets 401 on the very next request (no 5-minute staleness window).
•Rate-limit error code is now `RATE_LIMIT.USER` (per-key/default) or `RATE_LIMIT.ORG` (org override). Branch on `code`, not `message`. The `X-RateLimit-Limit` header reflects the effective ceiling — your per-key override if set, else the org override, else 60/min.
•Backend reaper job (`apps/api/src/jobs/connect_keys_reaper.py`) runs every 15 minutes, walks `archie_connect.keys` for expired rows, revokes them at WorkOS, stamps `revoked_at` on the mirror, and flushes both caches. Replaces the portal's `app/api/cron/reap-ephemeral-keys` Next.js cron — that route now returns 410 with a pointer.
•Docs: new `/docs/managing-keys` walkthrough covers portal + SDK paths side-by-side. `/docs/auth` adds the per-key metadata table + correct scopes (18 slugs the create modal exposes). `/docs/rate-limits` rewritten with the override resolution order. `/docs/sdk/python` adds the Managing API keys section.

2026-05-13alpha

Reliability + observability sweep (internal, non-breaking)

•Accounting fine-tune promotion: v6.4-r20 is now the default `consult_accounting_expert` model on the dev tier. No API change — same skill names, same envelopes — but answer quality + citation discipline improved across the TAX / ASR / CMP / WLT clusters.
•Anthropic-overload resilience: the specialist now retries on `overloaded_error` and `rate_limit` with exponential backoff (PR #4710), and never persists an empty assistant message when a downstream specialist crashes (PR #4709). Partner-visible effect: fewer transient 5xx during Anthropic load spikes, fewer empty `messages` rows in chat history.
•Telemetry baggage Phase 3: conversation_id, file tags, and Haiku title-gen route now ride OpenTelemetry baggage end-to-end (PRs #4674 / #4676 / #4683). Doesn't change the public API; it does make Studio's Deep Inspector trace tree more reliable for any partner using the Connect API + the Studio trace surface.
•D-RAG corpus sync primitive (PR #4711) + alpha-deploy smoke check on Slack-install row presence (D7). Internal observability; doesn't change the skill catalogue.

2026-05-13alphabreaking

Playbooks surface retired — WorkStreams everywhere

•The `/api/v1/playbooks/*` REST surface is gone. The OpenAPI spec, llms.txt, agents.md, and MCP tool catalogue now publish the WorkStreams surface only: `POST /api/v1/workstreams/{templates,blueprints,cycles}` plus lifecycle (pause/resume/cancel/approve) and triggers. Replaces playbooks entirely; partner integrations should migrate to the new endpoints.
•Terminology: a WorkStream **template** binds to a client to become a **blueprint**; each execution of a blueprint is a **cycle**; a cycle contains **tasks**. NEVER "runs" — WorkStream executions are cycles. Skill-call docs and SDK examples updated to match.
•Developer portal: `/dashboard/playbooks/*` and `/docs/playbooks` removed. WorkStream UI lives in Archie WorkStream Studio (Tauri app), not the developers portal.
•Back-compat: the `playbook.creator` skill slug (`POST /v1/skills/playbook.creator`) is retained for SDKs in flight. Description reframed — it now produces WorkStream drafts. Prefer `workstream.draft` for new integrations.

2026-05-12alpha

Connect surface readiness + skill catalogue parity

•Skill catalogue is now 52 (51 public, 41 Teams-visible, 27 Slack-visible) and the developer portal hero stat + MCP catalogue (/api-reference, content/mcp-tools.json) match the live SKILLS registry. The 2026-04-08 sandbox playground (Try-it browser REPL) is fully removed — stale references in the status page and changelog were cleaned up.
•Connect surfaces re-audited end-to-end: MCP / Cowork / Slack / Connect REST / Agent 365 Path A + Path B / Teams / Copilot. Per-surface smoke runners ship at apps/api/scripts/smoke_connect_*.sh (5/5 pass on the dev tier).
•Capability check (the explain_capabilities tool) reads the V4 tool registry as fallback for chat surfaces — previously it told users zero tools were live on Slack/MCP/Web because state.tools_available was only populated by the Excel plugin path. WorkStream read tools (list / describe / status) now part of the catch-all skill (ask_archie) so 'what WorkStreams can you see?' resolves end-to-end.
•FGA shadow mode logging upgraded: both permission_shadow_allow (INFO) and permission_shadow_deny (WARNING) now emit, both tagged with surface=<canonical-label>. Closes the observability gap on shadow grants.
•Tool_allowlist contract enforced: 22 of 52 skills had pre-Phase-7 stale references (artifact_generation, generate_docx, generate_excel, workflow_advance, xero_get_payroll, plus 12 never-built names). All cleaned up; a sentinel test pins the contract to prevent future drift.

2026-04-27alpha

API reference redesign, playbooks in REST spec, auto-provisioning

•API reference redesigned: two-column layout (ops sidebar + content), no more cramped three-column grid. Adds authentication, error format, rate-limit headers, and versioning sections to the overview page.
•Playbooks added to the public OpenAPI spec: list, create, get, update, delete, invoke run, stream events. Playbooks were always a first-class REST resource — now they're in the spec and the API reference.
•Auto-provisioning on first MCP connector sign-in: users whose first contact with Archie is via Claude Desktop or Cursor are now provisioned a platform account automatically instead of hitting a 403.
•Connector base URL is now environment-driven. Alpha points at claude.alpha.heyarchie.com; production at claude.heyarchie.ai. Set NEXT_PUBLIC_CONNECTOR_URL per deploy to override.
•Docs sidebar nav unified into a single shared module. Previously the /docs and /api-reference layouts each maintained their own copy, which silently diverged on renames.

2026-04-25alpha

SDK streaming, playbooks docs, llms.txt playbooks

•Python SDK: invoke_stream() on both sync and async SkillsResource. Yields SkillStreamChunk(delta, event, data) objects as SSE events arrive — no polling, no buffering.
•Playbooks reference page at /docs/playbooks: create, invoke, stream events, run lifecycle states, debug breakpoints API, Python SDK examples, MCP tools, permission scopes.
•llms.txt updated with a Playbooks section so LLM consumers know the create/invoke/stream/poll endpoints and required permission scopes.

2026-04-25alpha

Agent-first developer experience

•agents.md and llms.txt published — LLM-readable skill catalogue and call examples baked into the OpenAPI regen template so they stay in sync.
•Quickstart code samples now inject the signed-in user's sandbox key prefix (curl + Python blocks).
•MCP docs page: quick-connect bar with one-click Cursor deeplink and anchor buttons for Claude Desktop, Claude Code, Windsurf.
•Docs landing: live platform status badge (operational/degraded/outage) with 60-second cache.
•Playbooks dashboard page (/dashboard/playbooks): list view + detail/invoke page with input form and run history.
•Scalar API reference: layout: modern, full Archie brand CSS variables.

2026-04-25alpha

Public beta opens

•Claude Connect (MCP) live at claude.heyarchie.ai with AuthKit MCP and dynamic client registration.
•REST gateway live at api.heyarchie.ai with bearer auth, rate limits, and audit logging.
•Registry-driven POST /api/v1/skills/{slug}/invoke so SDK callers stay in sync as skills evolve.
•Python SDK shipped to PyPI as heyarchie.
•Sandbox seed data: 3 test clients, 10 documents, 5 conversations, 1 WorkStream.

2026-04-24alpha

Skill registry rewrite (KSR)

•Skill catalogue grew from 19 to 36 canonical skills under a two-tier dispatch model: a general-intent classifier picks a primary cluster (TAX, ASR, CMP, WLT, BOP, XCT), then a specialist resolves the exact skill.
•Each skill now exposes x-skill-cluster in the OpenAPI spec so SDK callers can see which cluster a skill belongs to.
•Skill input/output schemas regenerated; LLM-readable summaries at /llms.txt and /agents.md updated to match.
•Skills reachable at POST /api/v1/skills/{slug}/invoke; for chat-style flows, the ask_archie skill is the first-class entry point that routes through the orchestrator and accepts free-form queries.

2026-04-08alpha

Portal preview

•Developer portal shell at developers.heyarchie.ai with API key management, usage charts, request logs, webhook config.
•OpenAPI 3.1 spec published at /openapi.json; rendered via Scalar viewer at /docs/api-reference.