diff --git a/docs/contract-requests/ai.md b/docs/contract-requests/ai.md
index c29e6af..7afe0a5 100644
--- a/docs/contract-requests/ai.md
+++ b/docs/contract-requests/ai.md
@@ -35,17 +35,30 @@ provider keeps each response's raw content blocks (thinking with signature, text
 and replays them unchanged. Proposal: `ChatMessage.toolCalls?: { id, name, input }[]` and an opaque
 `providerData?: unknown` the provider can round-trip.
 
+**Settled in v1.1 (`feat/v11-ai`):** `ChatMessage.toolCalls?: ToolCall[]` and `providerData?: unknown` are in
+`@stc/contracts`, and providers may yield `{ providerData }` once per turn. The assistant loop appends one assistant
+message per model turn. Anthropic returns `{ anthropic: <raw blocks> }` and replays it verbatim (no in-memory map);
+OpenAI maps `toolCalls` to `tool_calls`.
+
 ## 4. Per-course mentor toggle in `ai_settings`
 
 The frozen key is `(scope, owner_id)` with one `mentor_off` column, so a per-course toggle cannot be a row. The flag
 lives in the user row's `config_json.mentorOff[courseId]`; `mentor_off` stays 0 (reserved for "off everywhere").
 Proposal: add `course_id TEXT NOT NULL DEFAULT ''` to the key, or a small `ai_mentor_prefs(user_id, course_id, off)` table.
 
+**Settled in v1.1:** table `ai_mentor_prefs(user_id, course_id, off, updated_at)` from
+`packages/feature-ai/migrations/0002_ai_mentor_prefs.sql`. `upgradeAiData` (src/upgrade.ts) copies v1
+`config_json.mentorOff` toggles once (marker `ai_data_v11` in `schema_migrations`).
+
 ## 5. Citations on `ai_messages`
 
 `ai_messages` has no column for an assistant message's sources. They are stored as an extra row with role `sources`
 (JSON) right after the assistant row and folded back when reading. Proposal: `ai_messages.meta_json TEXT`.
 
+**Settled in v1.1:** column `ai_messages.citations_json` from `0001_ai_message_citations.sql`, which also folds v1
+`sources` rows into the assistant row before them. (MCP `env`/`headers` are now encrypted at rest too, masked in the
+admin API.)
+
 ## 6. Derived text cache layout (shared with WP-B)
 
 Retrieval reads the importer's layout: