Repository Public
1# API — SP Note Next, AI workstream (v3.0, branch `next-ai`)23Contract for the native teams (SPNotesCore, macOS, iOS/iPadOS) and the web UI. It covers SPEC §3.5, §4.9 (level 1), §4.10–§4.14 and the4smart database properties. Everything else is in `docs/next/API-NEXT.md` (foundation workstream).56Every example below is a **real response of the scratch instance** (`note_next_ai_dev`, 2026-11-19), shortened only where marked `…`.7Prices are USD per 1M tokens as stored in the catalogue; costs are the catalogue price × the tokens the provider reported.89## 0.0 Integration pass (2026-11-19, branch `next-int`) — what changed in the routes of this document1011The rules are written once in `API-NEXT.md` §0.2 (every error carries a `code`), §0.5 (DELETE is idempotent) and §0.6 (ISO dates,12JSON numbers, bare dates at 12:00 UTC, clamping). For the routes documented here:1314| Route | Before | After |15|---|---|---|16| any error without a specific code (`/api/inbox/…`, `/api/audio/…`, `/api/research/…`, `/api/databases/…/ai…`) | `{"error": …}` | `{"error": …, "code": "<default of the status>"}` — `bad_request`, `not_found`, `invalid_state` (409), `too_large`, `upstream_error` (502), `internal` (500) |17| `GET /api/ai/usage` | `byModel[].calls / errors / inputTokens / outputTokens`, `byDay[].calls`, `byTask[].calls` were strings (`"337"`) | JSON numbers (`337`); `costUsd` always a number |18| `GET /api/search/index-state` | `pages, attachments, chunks, embedded, indexed_sources, stale` strings; `last_indexed`, `health.pending[].updatedAt`, `health.failed[].at` raw PostgreSQL timestamps | JSON numbers; ISO-8601 UTC strings (`last_indexed` may be `null`) |19| `GET /api/search?mode=quick` (and no `mode`) | `updatedAt: "2026-11-19 13:45:47.060354-05"` when `q` is not empty | `updatedAt: "2026-11-19T18:45:47.060Z"` |20| `POST /api/research/references` with a known `id` | `201`, the stored row (also for a deleted reference) | `200` + `x-existing: 1`, the stored row; a **deleted** reference → `409 {"code":"reference_deleted","id","deletedAt"}` (restore: `POST /api/research/references/<id>?action=restore`) |21| `GET /api/research/references?ids=` | — | unchanged; `x-missing-ids` also lists the ids of deleted references (documented) |22| `POST / PATCH /api/research/tasks` `dueAt: "2026-12-05"` | stored `2026-12-05T00:00:00.000Z`; an unparsable date → 500 | stored `2026-12-05T12:00:00.000Z` (same rule as `/api/tasks`); unparsable → `400 bad_request` |23| `DELETE /api/research/tasks/<id>`, `/api/research/references/<id>`, `/api/research/experiments/<id>` | `200 {"ok":true}` for an unknown id | unchanged — this is now the documented rule for every DELETE |24| `GET /api/pages/<id>/zoom?level=1` | — | unchanged; the automated suites call it with `cachedOnly=1` only (no model call) |2526No AI route gained or lost a field. `GET /api/search?mode=hybrid` embeds the query (paid, text sent to the provider) unless27`semantic=0` — unchanged, now stated prominently in `API-NEXT.md` §4.15.2829## 0. Conventions (unchanged from 2.x)3031- **Auth**: session cookie. Mutations (`POST`/`PUT`/`PATCH`/`DELETE`) need `Origin` = the app origin (or `Sec-Fetch-Site: same-origin`),32 else `403 {"error":…,"code":"csrf"}`. No session → `401 {"code":"unauthenticated"}`.33- **Errors**: `{"error": "<human message>", "code": "<machine code>", …extra}` + `x-request-id`. Ids that are not UUIDs → `400` (`bad_id`34 on the routes of this document).35- **Idempotency**: optional `Idempotency-Key` on JSON mutations (stored answer replayed with `idempotent-replay: true`). SSE answers36 are never stored; the chat has its own `clientId` replay.37- **SSE format**: `content-type: text/event-stream`. Each event is one line `data: <JSON>` followed by a blank line; there are no38 `event:` names — the discriminator is the JSON field `type`. The stream always ends with `data: [DONE]`. If the server fails39 mid-stream: `{"type":"error","code":"server_error","retryable":true,"message":…}` then `[DONE]`.40- **AI marking (SPEC §0.10)**: every AI result carries `ai:true` and/or `model`; clients must show it as AI-generated and never apply it41 without an explicit user action. Nothing in this document writes to a page, a tag, a link or a row on its own, except the two42 explicit "apply" calls (§5.2, §7.3) and the configured auto-run of a database property (§7.4).43- **Model ids**: opaque strings ≤ 200 chars. Native-provider models keep their id (`claude-haiku-5-5`, `gpt-6-sol`); models of44 OpenAI-compatible providers are namespaced `<provider>:<remote id>` (`openrouter:anthropic/claude-fable-5`). Send back exactly the `id`45 you received.4647## 1. Models and providers — `GET /api/ai/models` (SPEC §3.5, §4.11)4849Query: `all=1` (also disabled, unlisted and embedding models) · `provider=<id>` · `creator=<id>` · `available=1` · `q=<text>` ·50`unavailable=1` (include the models of OpenAI-compatible providers that have no key — several hundred for OpenRouter; they are51otherwise only counted in `hiddenUnavailable`).5253```jsonc54{55 "models": [ /* see below */ ],56 "providers": [57 {"id":"openai","name":"OpenAI","enabled":true,"lastDiscoveryAt":null,"status":"unknown","statusDetail":null,"kind":"openai","baseUrl":null,"keyEnv":"OPENAI_API_KEY","label":"OpenAI API","configured":true,"available":true,"logo":"/model-logos/generic.svg"},58 {"id":"anthropic","name":"Anthropic","enabled":true,"lastDiscoveryAt":null,"status":"unknown","statusDetail":null,"kind":"anthropic","baseUrl":null,"keyEnv":"ANTHROPIC_API_KEY","label":"Anthropic API","configured":true,"available":true,"logo":"/model-logos/anthropic.svg"},59 {"id":"openrouter","name":"OpenRouter","enabled":true,"lastDiscoveryAt":"2026-11-19T18:02:34.001Z","status":"no_key","statusDetail":"479 models listed from the public catalogue; OPENROUTER_API_KEY is not set","kind":"openai_compatible","baseUrl":"https://openrouter.ai/api/v1","keyEnv":"OPENROUTER_API_KEY","label":"OpenRouter","configured":false,"available":false,"logo":"/model-logos/openrouter.svg"},60 {"id":"maclustr","name":"MacLustr LLM","enabled":true,"lastDiscoveryAt":"2026-11-19T18:02:34.001Z","status":"no_key","statusDetail":"MACLUSTR_LLM_API_KEY is not set","kind":"openai_compatible","baseUrl":"https://llm.spboucher.ai/v1","keyEnv":"MACLUSTR_LLM_API_KEY","label":"MacLustr","configured":false,"available":false,"logo":"/model-logos/generic.svg"}61 ],62 "creators": [ {"id":"anthropic","name":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN","generic":false}, {"id":"openai","name":"OpenAI","logo":"/model-logos/generic.svg","monogram":"OA","generic":true}, … ],63 "hiddenUnavailable": 479,64 "routes": { … }, "defaultRoutes": { … }, "taskLabels": { … }, "benchmark": { … } // unchanged from 2.x65}66```6768`keyEnv` is the **name** of the environment variable; the key itself is never returned. `configured` = the variable is set;69`available` = configured and enabled. A provider without key is listed and never routed to.7071A model (historical row fields kept, new fields after `updatedAt`):7273```json74{"id":"claude-haiku-5-5","provider":"anthropic","displayName":"Claude Haiku 5.5","category":"text","available":true,"enabled":true,75 "contextWindow":1000000,"maxOutput":128000,"inputPrice":0.1,"cachedPrice":0.01,"outputPrice":0.5,76 "pricingSource":"https://platform.claude.com/docs/en/about-claude/pricing","probes":{"text":{"ms":592,"status":"ok"},"…":{}},"benchmark":{"…":"summary.json aggregate, unchanged"},77 "capabilities":{"…provider-declared keys, unchanged…":{},"text":true,"streaming":true,"tools":true,"structuredOutput":true,"jsonMode":true,"vision":true,"reasoning":true,"source":"measured"},78 "notes":[],"discoveredAt":"2026-11-01T07:03:46.768Z","probedAt":"2026-11-01T07:03:46.768Z","benchmarkedAt":"2026-11-01T07:18:30.317Z","createdAt":"…","updatedAt":"…",79 "creator":"anthropic","creatorName":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN",80 "route":"anthropic","routeLabel":"Anthropic API","routeKind":"anthropic","routeLogo":"/model-logos/anthropic.svg","remoteId":"claude-haiku-5-5",81 "context":1000000,"priceIn":0.1,"priceOut":0.5,"priceCached":0.01,"priceUnit":"USD per 1M tokens",82 "listed":true,"unavailableReason":null,"benchmarked":true,"autoRoutable":true}83```8485The same creator through another route (returned with `unavailable=1`, `provider=openrouter` or `all=1` while OpenRouter has no key):8687```json88{"id":"openrouter:anthropic/claude-fable-5","provider":"openrouter","displayName":"Anthropic: Claude Fable 5","category":"text","available":false,"enabled":true,89 "contextWindow":1000000,"maxOutput":128000,"inputPrice":10,"cachedPrice":1,"outputPrice":50,"pricingSource":"https://openrouter.ai/api/v1/models","probes":{},"benchmark":{},90 "capabilities":{"tools":true,"vision":true,"reasoning":true,"text":true,"streaming":true,"structuredOutput":true,"jsonMode":true,"source":"declared"},91 "notes":["listed by the provider's /models; not probed or benchmarked — selectable manually, never routed automatically"],92 "creator":"anthropic","creatorName":"Anthropic","logo":"/model-logos/anthropic.svg","monogram":"AN",93 "route":"openrouter","routeLabel":"OpenRouter","routeKind":"openai_compatible","routeLogo":"/model-logos/openrouter.svg","remoteId":"anthropic/claude-fable-5",94 "context":1000000,"priceIn":10,"priceOut":50,"priceCached":1,"priceUnit":"USD per 1M tokens",95 "listed":true,"unavailableReason":"no_key","benchmarked":false,"autoRoutable":false}96```9798| field | meaning |99|---|---|100| `creator`, `creatorName`, `logo`, `monogram` | who made the model. `logo` = `/model-logos/<creator>.svg`, or `/model-logos/generic.svg` (then show `monogram`). Single-colour SVG: tint it (template image / CSS mask). Registry and licences: `docs/next/MODEL-LOGOS.md`, `/model-logos/registry.json`. |101| `route`, `routeLabel`, `routeKind`, `routeLogo`, `remoteId` | the API the call goes through (= provider id) — show it as a badge **distinct** from the creator. `routeKind`: `openai` \| `anthropic` \| `openai_compatible`. |102| `context` | context window in tokens (null = not published). Same value as the historical `contextWindow`. |103| `priceIn`, `priceOut`, `priceCached` | USD per 1M tokens (null = not published; `0` = free). Same values as `inputPrice` / `outputPrice` / `cachedPrice`. |104| `capabilities` | the stored provider object plus normalised booleans `text, streaming, tools, structuredOutput, jsonMode, vision, reasoning` (null = unknown) and `source`: `measured` (probed against the real API) \| `declared` (provider catalogue) \| `unknown`. |105| `available` | usable now. `unavailableReason`: `no_key` \| `provider_disabled` \| `not_listed` \| `disabled` \| null. `listed` = the provider still lists it. |106| `autoRoutable` / `benchmarked` | passed the measured probes → takes part in automatic routing. `false` = **manual selection only** (pass its `id` as `model`); automatic routing never picks it. |107108Rules a picker must follow: group by `creator`; show the route badge; a model with `available:false` cannot be selected; "Auto" =109send `model: null`.110111`POST /api/ai/models` (unchanged actions `toggle`, `routes`, `budget`; `discover` gains an optional provider):112`{"action":"discover","provider":"openrouter"}` → `{"openrouter":{"listed":479,"status":"no key"}}`. Discovery reads each provider's113`GET {base_url}/models`: context, prices and declared capabilities are stored as published. OpenRouter's catalogue is public and is read114even without a key (its models stay unavailable); another provider without key answers `{"listed":0,"status":"no key"}`.115Verified on 2026-11-19: `GET https://llm.spboucher.ai/health` → `200 {"status":"ok"}`; `GET https://llm.spboucher.ai/v1/models` without116key → `401` (so the MacLustr catalogue appears once `MACLUSTR_LLM_API_KEY` exists).117118## 2. Ask My Knowledge — `POST /api/ai/chat` (SSE, SPEC §4.10)119120Body (2.x fields unchanged; new fields marked ★):121122| field | type | notes |123|---|---|---|124| `message` | string 1–60 000 | required |125| `mode` | `notes` (default) \| `summarise` \| `actions` \| `contradictions` \| `draft` \| `general` | unchanged |126| `conversationId`, `clientId`, `pageId`, `model`, `task`, `useWorkspace`, `confirmExpensive`, `images`, `scopePageIds` | | unchanged (`model` ≤ 200 chars now) |127| ★ `scope` | `all` (default) \| `page` \| `project` \| `selection` | where the evidence may come from. Applies to modes `notes`, `draft`, `contradictions`; `selection` only to `notes`. |128| ★ `projectId` | uuid | with `scope:"project"`: that page and all its descendants. Without it the project is the **root ancestor of `pageId`** and all its descendants. |129| ★ `selection` | string ≤ 20 000 | with `scope:"selection"`: the only text the model may use (no search is run). |130| ★ `selectionBlockId` | string | block the selection was made in; echoed as the citation's `blockId` only if that block exists in `pageId`. |131132Events:133134- `meta` `{conversationId, clientId, mode, model, provider, reason, task, sources: SourceRef[], weak: SourceRef[], evidence, sent, budgetNote, replayed, ★scope, ★scopePages, ★staleDropped}` — `scopePages` = number of pages in the scope (null = unrestricted); `staleDropped` = retrieved passages discarded because their text is no longer in the page.135- `text` `{delta}` (repeated)136- `done` `{messageId, content, usage, costUsd, latencyMs, ttftMs, sources: SourceRef[] (only the cited ones), evidence, invalidCitations: number[], uncited, replayed}`137- `needs_confirmation` `{reason, plan}` — unchanged138- `error` `{message, code, retryable, conversationId?, alternative?}` — codes: `not_configured`, `page_required`, `not_found`, `no_model`, `refused`, `provider_error`, `server_error`, ★`bad_scope`, ★`selection_required`139140`SourceRef` = `{n, chunkId, pageId, title, icon, heading, blockId, excerpt, score, semantic, sourceType, ★blockIds, ★anchor, ★quote}`:141142- `blockId` — the block that **best supports** the citation: in `meta`, the block of the retrieved passage closest to the question; in143 `done`, the block closest to the sentence(s) of the answer carrying `[n]`. (2.x returned the first block of a ~350-token passage.)144- `blockIds` — every block of the passage; `quote` — the first 300 characters of the anchored block as it is in the page now.145- `anchor` — `block` (verified in the current page content) · `page` (verified text, block without id) · `file` (attachment text, no146 block) · `selection`.147- Open a citation with `/p/<pageId>#block-<blockId>` (web) or by scrolling to the block with that `id` attr (natives).148149Guarantees:1501511. A citation marker `[n]` that does not correspond to a retrieved source is removed from `content` and reported in `invalidCitations`.1522. A retrieved passage whose text is no longer in the page (page edited or block deleted since indexing) is dropped **before** the153 model is called — a cited `blockId` always exists in the page as it is now.1543. With no supporting source, **no answering provider is called**: `content` starts with `**No supporting note found.**`,155 `evidence:"none"`, `costUsd:0`.1564. An answer that cites none of its sources is **withheld**: `content` = `**No supporting note found.** The model wrote an answer157 without citing any of the retrieved passages, …`, `evidence:"insufficient"`, `uncited:true`, `sources:[]`.158159Request `{"message":"Quelle est la pénalité de remboursement anticipé ?","scope":"page","pageId":"2eea0ded-…","model":"claude-haiku-5-5","clientId":"live-ask-page-02"}`:160161```text162data: {"type":"meta","conversationId":"fe873d65-75c5-4827-89d2-37e1e48918f6","clientId":"live-ask-page-02","mode":"notes","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","task":"chat","sources":[{"n":1,"chunkId":"a8a64c4b-bafb-4afe-b4a6-2594f911b667","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"heading":"Conditions","blockId":"XycxLnbyuq","excerpt":"Le taux fixe cinq ans proposé est de 4,29 %, garanti 90 jours.\nLa pénalité de remboursement anticipé équivaut à trois mois d intérêts.\nL amortissement restant est de vingt-deux ans.","score":0.016666666666666666,"semantic":0.644,"sourceType":"page","blockIds":["RttMYFvegP","XycxLnbyuq","8As7edcAjg"],"anchor":"block","quote":"La pénalité de remboursement anticipé équivaut à trois mois d intérêts."}],"weak":[],"evidence":"ok","sent":{"pageChars":0,"excerpts":1,"references":0,"images":0,"history":0,"embeddedBy":"openai","rankedBy":null},"budgetNote":null,"replayed":false,"scope":"page","scopePages":1,"staleDropped":0}163164data: {"type":"text","delta":"La"}165166data: {"type":"text","delta":" pénalité de rembours"}167…168data: {"type":"done","messageId":"e52caff5-2aa9-4bea-aafe-46431bc80021","content":"La pénalité de remboursement anticipé équivaut à trois mois d'intérêts [1].","usage":{"inputTokens":553,"outputTokens":34,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.00007230000000000001,"latencyMs":1213,"ttftMs":953,"sources":[{"n":1,"chunkId":"a8a64c4b-…","pageId":"2eea0ded-…","title":"Offre de la banque","icon":null,"heading":"Conditions","blockId":"XycxLnbyuq","excerpt":"…","score":0.016666666666666666,"semantic":0.644,"sourceType":"page","blockIds":["RttMYFvegP","XycxLnbyuq","8As7edcAjg"],"anchor":"block","quote":"La pénalité de remboursement anticipé équivaut à trois mois d intérêts."}],"evidence":"ok","invalidCitations":[],"uncited":false,"replayed":false}169170data: [DONE]171```172173(The passage covers three paragraphs; the citation is anchored to the second one, `XycxLnbyuq`, which states the penalty.)174175`scope:"selection"` — `{"message":"Combien d années reste-t-il ?","scope":"selection","selection":"L amortissement restant est de vingt-deux ans.","pageId":"2eea0ded-…","model":"claude-haiku-5-5"}`:176177```text178data: {"type":"meta",…,"sources":[{"n":1,"chunkId":"selection","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"heading":null,"blockId":null,"excerpt":"L amortissement restant est de vingt-deux ans.","score":1,"semantic":1,"sourceType":"selection","blockIds":[],"anchor":"selection","quote":"L amortissement restant est de vingt-deux ans."}],"weak":[],"evidence":"ok","sent":{"pageChars":0,"excerpts":1,"references":0,"images":0,"history":0,"embeddedBy":null,"rankedBy":null},…,"scope":"selection","scopePages":null,"staleDropped":0}179180data: {"type":"done","messageId":"e2b5e9ee-…","content":"Il reste vingt-deux ans d'amortissement [1].","usage":{"inputTokens":476,"outputTokens":23,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.0000591,"latencyMs":726,"ttftMs":485,"sources":[{…same source…}],"evidence":"ok","invalidCitations":[],"uncited":false,"replayed":false}181```182183(`blockId` is null here because the request carried no `selectionBlockId`.)184185No support (`{"message":"Quel est le prix du baril de pétrole ?","scope":"project","pageId":"2eea0ded-…"}`):186187```text188data: {"type":"meta","conversationId":"27a49df1-…","clientId":"live-ask-none-02","mode":"notes","model":null,"provider":null,"reason":"no supporting source — no answering provider called","task":"chat","sources":[],"weak":[],"evidence":"none","sent":{"pageChars":0,"excerpts":0,"references":0,"images":0,"history":0,"embeddedBy":"openai","rankedBy":null},"budgetNote":null,"replayed":false,"scope":"project","scopePages":2,"staleDropped":0}189190data: {"type":"text","delta":"**No supporting note found.** I searched your workspace and found nothing relevant enough to support an answer. I am not answering from general knowledge as if it came from your notes."}191192data: {"type":"done","messageId":"228b8624-…","content":"**No supporting note found.** …","usage":null,"costUsd":0,"latencyMs":0,"ttftMs":null,"sources":[],"evidence":"none","invalidCitations":[],"uncited":false,"replayed":false}193```194195Scope error (`{"message":"x","scope":"page"}` without `pageId`) — nothing stored, nothing sent:196197```text198data: {"type":"error","code":"page_required","retryable":false,"message":"This scope works on an open page: open a page first."}199200data: [DONE]201```202203## 3. Inline actions — `POST /api/ai/action` (SSE, SPEC §4.10)204205Body: `{action, text ≤ 120 000, instruction? ≤ 4000, model? ≤ 200, language?, confirmExpensive?, ★pageId?}`.206`action` = one of the 21 historical ids (`rewrite, fix, translate, summarize, expand, explain, to_list, to_tasks, table, shorten, formal,207simplify, translate_fr, translate_en, explain_math, continue, outline, study_notes, action_items, contradictions, custom`) or ★208`coherence`, `questions`, `synthesis`, `structure`, `links`.209210Pre-stream errors (JSON, unchanged): `400 bad_language`, `400 no_instruction`, `503 no_model` / `not_configured`,211`409 confirm_expensive {plan}`; ★ `400 no_text` (`links` with empty text).212213`coherence` (logic, terminology, internal contradictions), `questions` (open questions the text raises), `synthesis`, `structure`214(a better outline + what to move/merge/cut) stream Markdown exactly like the historical actions; none is an expensive class:215216```text217data: {"type":"meta","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","budgetNote":null}218219data: {"type":"text","delta":"-"}220221data: {"type":"text","delta":" Le taux de"}222…223data: {"type":"done","usage":{"inputTokens":262,"outputTokens":1230,"cachedTokens":0,"reasoningTokens":…},"costUsd":0.000641,"latencyMs":…}224225data: [DONE]226```227228Failure inside the stream: `{"type":"error","code":"refused"|"provider_error","retryable":true,"message":…}`.229230★ `links` — suggested internal links, **as data; nothing is written**. The server retrieves candidate pages (never the page `pageId`231itself nor a page it already links to), the model picks among them through a strict JSON schema, each pick is validated (an unknown232index is dropped; an `anchorText` that is not literally in `text` becomes `null`). No `text` events:233234Request `{"action":"links","text":"Avant de signer, vérifier la pénalité de remboursement anticipé et le taux fixe proposé.","pageId":"1280ae37-…","model":"claude-haiku-5-5"}`:235236```text237data: {"type":"meta","model":"claude-haiku-5-5","provider":"anthropic","reason":"user selection","budgetNote":null}238239data: {"type":"result","data":{"ai":true,"model":"claude-haiku-5-5","links":[{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"blockId":"RttMYFvegP","excerpt":"Le taux fixe cinq ans proposé est de 4,29 %, garanti 90 jours. La pénalité de remboursement anticipé équivaut à trois mois d intérêts. L amortissement restant est de vingt-deux ans.","score":0.016666666666666666,"anchorText":"pénalité de remboursement anticipé","reason":"Donne les conditions chiffrées de la pénalité et du taux fixe évoqués dans la note."},{"pageId":"020cc747-b513-42f2-86b5-261f5ed48453","title":"Refinancement du triplex","icon":null,"blockId":"SLHKAchLmY","excerpt":"Dossier de refinancement du triplex de la rue Laurier, ouvert en novembre 2026.","score":0.015625,"anchorText":"taux fixe proposé","reason":"Dossier de refinancement qui contextualise l'offre de taux à vérifier avant signature."}],"candidates":4}}240241data: {"type":"done","usage":{"inputTokens":886,"outputTokens":134,"cachedTokens":0,"reasoningTokens":0},"costUsd":0.00015560000000000001,"latencyMs":2269}242243data: [DONE]244```245246When no candidate page exists no provider is called: `meta {model:null, reason:"no candidate page — no provider called"}`,247`result {data:{ai:true, links:[], candidates:0}}`, `done {usage:null, costUsd:0, latencyMs:0}`. Invalid model JSON →248`{"type":"error","code":"bad_output","retryable":true,…}`. The client turns an accepted suggestion into a link on `anchorText`249(or inserts a mention) through a normal page save.250251`GET /api/ai/chat/plan` is unchanged (it accepts the new action ids in `action=`).252253## 4. Semantic zoom, level 1 — `/api/pages/<id>/zoom/ai` (SPEC §4.9)254255The AI synopsis of a page, cached by content hash (title + Markdown). The foundation route `GET /api/pages/<id>/zoom?level=1` returns256the same object (it calls the same function); this route also lets a client read the cache without spending, and regenerate.257258- `GET /api/pages/<id>/zoom/ai` → synopsis; generated (one cheap model call, route `quick`) when missing or stale.259 `?cachedOnly=1` → never calls a provider. `?model=<id>` → manual model.260- `POST /api/pages/<id>/zoom/ai` `{model?}` → regenerate.261262```json263{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","level":1,"contentHash":"20156a7accd058b5857a3744a185c6de","ai":true,"status":"ready","synopsis":"La note décrit une offre de prêt bancaire : un taux fixe sur cinq ans de 4,29 %, garanti pendant 90 jours, avec une durée d'amortissement restante de vingt-deux ans. Elle précise qu'un remboursement anticipé coûte une pénalité équivalant à trois mois d'intérêts. Aucune question ouverte ni comparaison n'y figure.","model":"claude-haiku-5-5","provider":"anthropic","generatedAt":"2026-11-19T18:22:22.977Z","cached":false,"costUsd":0.0001022}264```265266Second call: identical, with `"cached":true` (no provider call). With `?cachedOnly=1` before any generation:267268```json269{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","level":1,"contentHash":"20156a7accd058b5857a3744a185c6de","ai":false,"status":"missing","synopsis":null,"model":null,"provider":null,"generatedAt":null,"cached":false,"costUsd":null}270```271272`status`: `ready` \| `missing` (cachedOnly, nothing valid cached) \| `empty` (page without text — no call, `ai:false`).273Errors: `400 bad_id`, `404` page, `503 no_model`, `502 provider_error` \| `refused` (nothing is cached on failure).274Any edit or rename changes `contentHash` and invalidates the synopsis.275276## 5. Smart Inbox (SPEC §4.12)277278### 5.0 `POST /api/capture` — kinds (3.0, branch `next-p-cv`)279280Body unchanged: `{kind, text?, url?, attachmentIds?}` → `201 {id, title, kind, inboxAt}` (`kind` = the stored `pages.capture_kind`).281282| kind | stored as | content |283|---|---|---|284| `note`, `tasks`, `link`, `photo`, `file` | same | unchanged from 2.x |285| `audio` | `audio` | each audio attachment becomes an **`audio` node** (`attachmentId`, `title`, `transcriptStatus:"none"`) instead of a file card, so the capture is a voice note that can be transcribed (§6); non-audio attachments keep their card |286| `screenshot` | `screenshot` | like `photo` (image nodes); default title `Screenshot · <date>` |287| `document` | `document` | a PDF attachment becomes a **`pdf` node** (`attachmentId`, `name`, `page:1`, `annotations:[]`), other files a file card |288| `selection` | `selection` | `text` (required) as a `blockquote`; `url` = its source, either `/p/<pageId>` / `/p/<pageId>#block-<blockId>` (kept relative: the capture then appears in that page's backlinks) or an http(s) address; any other value is ignored |289| `idea` | **`note`** | request-only alias: a note created with the icon 💡 (the stored kinds stay the ones of SPEC §4.12) |290291### 5.1 `GET /api/inbox/<id>/suggestions`292293AI suggestions for one capture: title, tags, destination, related pages, summary. **Suggestions only — this route changes nothing.**294Strict JSON schema; the model answers with indices into a candidate list built by the server, so a destination or a relation is always295an existing page; tags are normalised and flagged existing / new. Cached by content hash (title + text + tags of the capture) and296re-validated on every read. `?refresh=1` regenerates · `?cachedOnly=1` never calls a provider · `?model=<id>`.297298```json299{"pageId":"d420eb53-5bce-4ee5-a419-5c70cef55c7a","contentHash":"c0218f0950c5aad9b1170269bc6f4f2c","status":"ready","ai":true,"model":"claude-haiku-5-5","provider":"anthropic","generatedAt":"2026-11-19T18:24:12.565Z","cached":false,"costUsd":0.00010823,300 "suggestions":{301 "title":{"value":"Rappeler la banque triplex","current":"rappeler la banque triplex"},302 "tags":[{"name":"refinancement","existing":true},{"name":"triplex","existing":true},{"name":"banque","existing":true}],303 "destination":{"section":"projects","parentId":"020cc747-b513-42f2-86b5-261f5ed48453","parentTitle":"Refinancement du triplex"},304 "relations":[{"pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","title":"Offre de la banque","icon":null,"reason":"L'offre de la banque concerne probablement le même financement et la garantie de taux en question."}],305 "summary":"Rappeler la banque pour demander si la garantie de taux de 90 jours peut être prolongée dans le cadre du refinancement du triplex."}}306```307308Each key of `suggestions` may be null / empty: `title` is null when the model keeps the current title; `destination` is309`{section, parentId:null, parentTitle:null}` when only a section is proposed, or null. `status:"empty"` (`ai:false`, empty310suggestions) for a capture with no title and no text. Errors: `400 bad_id`, `404` page, `409 not_in_inbox`,311`404 not_generated` (cachedOnly), `503 no_model`, `502 provider_error` \| `refused` \| `bad_output`.312313### 5.2 `POST /api/inbox/<id>/apply`314315Applies **the subset the user chose**, with the values sent (the user may have edited them). Only the keys present are applied.316317Body (all optional, at least one): `{title?: string ≤300, tags?: string[] ≤10, destination?: {section?: notes|documents|projects|research, parentId?: uuid|null}, relations?: [{pageId, reason?}] ≤10, summary?: string ≤1000}`.318319- `title` → the page is renamed (a version "before AI suggestion" is kept).320- `tags` → added to the existing tags. `relations` → accepted relations to those pages (`knowledge_edges`, kind `ai_suggested`,321 status `accepted`).322- `summary` → inserted as the first block, as an `aiBlock` (`attrs.action = "summary"`) — it stays visibly AI.323- `destination` → the capture is filed (leaves the inbox). Without `destination` it **stays in the inbox**.324325```json326{"actionId":"68415a83-438b-46cf-b85e-25bfba7246be","summary":"4 suggestions applied","applied":["title","summary","tags","relations"],"filed":false,"created":{"summaryBlockId":"AW23RJ67ft","tagsAdded":["refinancement","triplex","banque"],"edgeIds":["bed79a14-d9c0-45ba-b641-383f4ae40f9d"]}}327```328329Errors (validated before any write): `400 nothing_to_apply` (`{"error":"Nothing chosen to apply","code":"nothing_to_apply"}`),330`400 bad_section` \| `bad_destination` \| `bad_relation`, `409 not_in_inbox`, `409 conflict` (page changed meanwhile).331332### 5.3 Undo — `POST /api/inbox/undo` `{actionId}` (existing route)333334Reverses the action journaled above exactly like a triage action: title, added tags, the inserted summary block, the created335relations and the filing. Later edits by the user (other tags, other text) are left alone. → `{"ok":true,"already":false}`336(`already:true` when repeated). The journal action name is `suggestions`.337338## 6. Voice (SPEC §4.13)339340### 6.1 `POST /api/audio/<attachmentId>/transcribe`341342Body `{summarize?: boolean, force?: boolean}`. Queues the pg-boss job `transcribe` (never retried automatically: it is a paid call).343344- `202` — a job was queued:345346```json347{"queued":true,"jobId":"1b60aa7a-da87-4306-b323-e37c5f233ca9","attachmentId":"82f70f18-d19f-4d58-ba81-8a4d72099e17","status":"pending","transcript":[],"text":"","engine":null,"model":null,"language":null,"duration":null,"segments":null,"summary":null,"error":null,"costUsd":null,"requestedAt":"2026-11-19T18:22:31.175Z","finishedAt":null}348```349350- `200` `{"queued":false, …current state…}` — a transcript already exists or is pending (no second call, no second charge).351 `force:true` transcribes again; `summarize:true` on a finished transcript without summary queues the summary only.352- Errors: `400 bad_id` · `404` unknown attachment (`{"error":"Attachment not found"}`) · `415 not_audio` · `413 too_large`353 (> 25 MB, the engine's limit) · `503 not_configured` (no OpenAI key) \| `queue_unavailable`.354355Accepted: `audio/*`, `video/webm`, `video/mp4` in a container the engine reads (webm, m4a/mp4, mp3, wav, ogg, flac).356357### 6.2 `GET /api/audio/<attachmentId>`358359Poll every 2–3 s while `status` is `pending`.360361```json362{"attachmentId":"82f70f18-d19f-4d58-ba81-8a4d72099e17","status":"done",363 "transcript":[{"t":0,"text":"Réunion du 19 novembre. Nous retenons le taux fixe de 5 ans."},{"t":4.4,"text":"Marie envoie les documents à la banque lundi matin."}],364 "text":"Réunion du 19 novembre. Nous retenons le taux fixe de 5 ans. Marie envoie les documents à la banque lundi matin.",365 "engine":"openai","model":"whisper-1","language":"french","duration":6.869999885559082,"segments":true,366 "summary":{"at":"2026-11-19T18:22:36.405Z","text":"Réunion du 19 novembre. Ils retiennent un taux fixe de 5 ans. Marie enverra les documents à la banque lundi matin.","model":"gpt-5.4-mini","tasks":["Marie envoie les documents à la banque lundi matin."],"decisions":["Ils retiennent le taux fixe de 5 ans."]},367 "error":null,"costUsd":null,"requestedAt":"2026-11-19T18:22:31.175Z","finishedAt":"2026-11-19T18:22:36.408Z"}368```369370(Real run: 6.8 s of French speech synthesized with macOS `say`, 32 KB m4a, transcribed in about 2 s. Transcripts stored after this371run round `duration` to 0.01 s.)372373| field | meaning |374|---|---|375| `status` | `none` (never requested) \| `pending` \| `done` \| `failed` |376| `transcript` | `[{t: seconds from the start, text}]` — exactly the `audio` node's `transcript` attr |377| `engine`, `model` | what actually produced the transcript (`audio.transcriptEngine` = `"<engine>:<model>"` is a reasonable client value) |378| `segments` | `true` when the model returns timestamps; `false` = text-only model, one segment at `t:0` |379| `summary` | `{text, decisions[], tasks[], model, at}` or null — the `audio` node's `summary` attr |380| `error` | reason when `failed`; when `done`, a non-null value means the summary could not be produced (`Summary not produced: …`) |381| `costUsd` | null unless the owner set `settings['ai.transcription_usd_per_minute']` (transcription prices are not in the catalogue) |382383Engine choice: the transcription models the OpenAI account exposes are discovered live. On 2026-11-19 the account exposes384`gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-03-20`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`,385`gpt-4o-transcribe-diarize`, `gpt-transcribe`, `whisper-1`; `whisper-1` is chosen because it returns segment timestamps386(`verbose_json`), then a diarising model, then text-only models. Override with `settings['ai.transcription_model']`.387388**Who writes the `audio` node**: the client. When `status` becomes `done`, the editor copies `transcript`, `transcriptStatus:"done"`,389`transcriptEngine`, `summary` into the node and saves the page normally (versioned). The server does not edit the page.390391## 7. Smart database properties392393The property type `ai` keeps working as in 2.x (`config.prompt`, manual "Generate" per cell). New: per-property configuration, a run394log, protection of hand-edited values, optional auto-run.395396### 7.1 Configuration — `/api/databases/<id>/ai/config`397398`GET` → `{"tasks":["custom","summarize","classify","extract","detect-date","categorize"],"properties":[…]}`:399400```json401{"tasks":["custom","summarize","classify","extract","detect-date","categorize"],"properties":[{"propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","name":"Priorité IA","ai":{"task":"classify","prompt":"","choices":["Urgent","Normal","Plus tard"],"model":"claude-haiku-5-5","autoRun":true,"managed":false},"problem":null,"runs":{"queued":0,"done":1,"failed":0,"skipped":1,"costUsd":0.0000626,"lastAt":"2026-11-19T18:22:41.699Z"}}]}402```403404`PUT` `{propertyId, ai: {task?, prompt? ≤4000, choices? string[] ≤40, model? | null, autoRun?, managed?}}` (partial, merged) →405406```json407{"propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","name":"Priorité IA","ai":{"task":"classify","prompt":"","choices":["Urgent","Normal","Plus tard"],"model":"claude-haiku-5-5","autoRun":true,"managed":false},"problem":null}408```409410| `ai` field | meaning |411|---|---|412| `task` | `custom` (free prompt, the 2.x behaviour) · `summarize` · `classify` (exactly one of `choices`) · `extract` (what `prompt` describes, copied faithfully) · `detect-date` (ISO `YYYY-MM-DD`) · `categorize` (zero or more of `choices`, or ≤ 3 free categories) |413| `prompt` | required for `custom` and `extract`; optional guidance otherwise. `{{Property name}}` placeholders. Mirrored in the historical `config.prompt`. |414| `choices` | allowed values for `classify` (≥ 2) / `categorize` |415| `model` | model override (an id of §1); null = measured route (`quick` / `extract`) |416| `autoRun` | recompute the cell when another value of the row changes (API row create / update) |417| `managed` | the property is AI-managed: the AI may overwrite a value typed by hand |418419`problem` is a string when the configuration cannot run (`"No prompt configured"`, `"Classification needs at least two choices"`, …).420Errors: `400 not_ai_property`, `404`. The stored shape is `database_properties.config.ai` — the generic property `PATCH` still works.421422An answer outside the task's contract (a class that is not a choice, an impossible date, invalid JSON) stores **null**, never a guess.423Cell values stay plain text (`"Urgent"`, `"2027-03-03"`, `"a, b"`), `{"pending":true,"at":…}` while queued, `{"error":…}` on failure.424425### 7.2 Run — `POST /api/databases/<id>/ai` (existing route)426427Body `{propertyId, rowId | rowIds[] ≤200, force?}`. Historical answer keys kept (`ok`, `queued`), plus `runs` and `skipped`.428429A cell whose value was typed by hand is **not** overwritten unless the property is `managed` or `force:true` is sent:430431```json432{"ok":true,"queued":0,"runs":[{"rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","runId":"d93a25ed-1f05-4353-ab79-f8f1e60082be","queued":false,"skipped":"user_edited"}],"skipped":[{"rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","reason":"user_edited","runId":"d93a25ed-1f05-4353-ab79-f8f1e60082be"}]}433```434435`skipped` reasons: `user_edited` · `bad_config` · `already_queued` (pending < 5 min) · `over_budget` (auto-run only) ·436`queue_unavailable`. A skipped cell is left exactly as it was. "Typed by hand" = a non-empty value that differs from the output of437the last successful run of that cell.438439### 7.3 Run log — `GET /api/databases/<id>/ai/runs?propertyId=&rowId=&status=&limit=`440441Newest first, ≤ 500:442443```json444[{"id":"303848ec-ce88-471b-9923-92e0c4ba7f60","databaseId":"03f4d928-e8ad-4dea-b6cc-f307e04303d4","propertyId":"3981f845-97b9-47f0-b153-96ef517c8e4c","rowId":"93e5f9e5-5f6e-4c40-ab8c-9ac28e28c524","status":"done","trigger":"auto","task":"classify","model":"claude-haiku-5-5","provider":"anthropic","inputTokens":561,"outputTokens":13,"costUsd":0.0000626,"error":null,"createdAt":"2026-11-19T18:22:37.475Z","startedAt":"2026-11-19T18:22:38.173Z","finishedAt":"2026-11-19T18:22:41.153Z"}]445```446447`status`: `queued` \| `running` \| `done` \| `failed` \| `skipped` · `trigger`: `manual` \| `auto`. (This run was triggered by creating448the row: the cell became `"Urgent"` 3.7 s later.)449450### 7.4 Auto-run451452After `POST` / `PATCH /api/databases/<id>/rows`, every AI property with `autoRun:true` is queued for the changed row — never when the453change only touched AI cells, never over a hand-edited value (unless `managed`), never when the daily AI budget is reached. The row454write never fails because of it. Clients poll the row (the existing 2.5 s polling while a value is `pending`) or the run log.455456## 8. Research (SPEC §4.14)457458### 8.1 `GET /api/research/export.tex?projectId=<page id>[&format=tex|json|zip][&inline=1]`459460LaTeX article skeleton of a project = the page `projectId` and all its live descendants in tree order (database rows and archived461pages left out). No AI is involved. Root page body first (its "Abstract" / "Résumé" heading becomes `\begin{abstract}`), then one462`\section` per child page, nested by depth; `hypothesis` callouts are also collected in a "Hypotheses" section; the project's463experiments become "Methods notes"; equations are kept verbatim (`inlineMath` → `$…$`, `blockMath` → `equation`); images become464`\includegraphics{figures/<attachment name>}` **placeholders**; `\cite{…}` typed in the text is preserved; `citation` nodes become465`\cite[locator]{key}` (a missing reference becomes a visible `[?]` + a comment, never an invented key).466467- `format=tex` (default) → `application/x-tex`; headers468 `x-export-report: {"pages":2,"sections":1,"citeKeys":0,"missingKeys":0,"missingRefs":0,"figures":0,"hypotheses":0,"experiments":0,"unknownNodes":[]}` and469 `x-bib-url: /api/research/references/export.bib?projectId=020cc747-…`; `inline=1` omits `content-disposition`.470471```latex472% Generated by SP Note — LaTeX skeleton of the project "Refinancement du triplex"473% 2 page(s), 0 cite key(s), 0 figure placeholder(s). Figures are expected in ./figures/ (see the ZIP export).474\documentclass[11pt]{article}475\usepackage[T1]{fontenc}476\usepackage[utf8]{inputenc}477\usepackage{amsmath,amssymb}478\usepackage{graphicx}479\usepackage[normalem]{ulem}480\usepackage{hyperref}481482\title{Refinancement du triplex}483\author{Simon-Pierre Boucher}484\date{\today}485486\begin{document}487\maketitle488489Dossier de refinancement du triplex de la rue Laurier, ouvert en novembre 2026.490491\section{Offre de la banque}492% page 2eea0ded-b5b8-4abe-b560-75345504be80493\subsection{Conditions}494495Le taux fixe cinq ans proposé est de 4,29 \%, garanti 90 jours.496…497\bibliographystyle{plain}498\bibliography{references}499\end{document}500```501502- `format=json` → `{"projectId", "title", "tex", "bib", "citeKeys":[], "missingKeys":[], "missingRefs":[], "figures":[{"attachmentId","name","file"}], "sections":1, "hypotheses":0, "experiments":0, "unknownNodes":[], "bibUrl"}`503 — `missingKeys` = cited but absent from the library; `figures[].file` = the name used in `\includegraphics{figures/<file>}`.504- `format=zip` → `application/zip` with `main.tex`, `references.bib`, `figures/<file>` (the real attachments present on disk, ≤ 150 MB)505 and `export-report.json` (`figuresIncluded`, `figuresMissing`, `missingKeyList`).506507Errors: `400 bad_id` (`{"error":"projectId is required (a page id)","code":"bad_id"}`), `400 bad_format`, `404 not_found`.508509### 8.2 `.bib` companion — `GET /api/research/references/export.bib?projectId=<page id>[&inline=1]`510511The existing BibTeX export, scoped to the project: references attached to any page of the project **plus** every library reference512cited by key or by a `citation` node in its text. (`?pageId=` and the whole-library form are unchanged.)513514```bibtex515@article{doe2021prepayment,516 author = {Doe, Jane and Roe, John},517 title = {Mortgage Prepayment and the Term Structure},518 journal = {Journal of Housing Finance},519 year = {2021}520}521```522523### 8.3 `GET /api/research/references`524525- `?pageId=` and no parameter — unchanged.526- ★ `?projectId=<page id>` → the same set as §8.2, as reference rows.527- ★ `?ids=<uuid,uuid,…>` (≤ 200) → exactly those references, for resolving `citation` nodes; each row gains `label` (author–year)528 and `citation` (formatted entry). Ids that do not exist — or belong to a deleted reference — are listed in the response header `x-missing-ids`.529530```json531[{"id":"54879947-9c63-455b-8e67-afa8cab80953","workspaceId":"…","pageId":"2eea0ded-b5b8-4abe-b560-75345504be80","citeKey":"doe2021prepayment","entryType":"article","title":"Mortgage Prepayment and the Term Structure","authors":["Jane Doe","John Roe"],"year":2021,"journal":"Journal of Housing Finance","doi":null,"url":null,"bibtex":"@article{doe2021prepayment,\n author = {Doe, Jane and Roe, John},\n …}","fields":{"year":"2021","title":"…","author":"Doe, Jane and Roe, John","journal":"Journal of Housing Finance"},"verified":"user","attachmentId":null,"createdAt":"2026-11-19T18:22:41.721Z","updatedAt":"2026-11-19T18:22:41.721Z","deletedAt":null,"label":"Doe & Roe (2021)","citation":"Doe, J., & Roe, J. (2021). Mortgage Prepayment and the Term Structure. Journal of Housing Finance."}]532```533534with `x-missing-ids: 00000000-0000-4000-8000-000000000000`. Errors: `400 bad_id`, `400 too_many_ids`.535536- ★ (slice next-p-ra) `?attachmentId=<attachment id>` → the references whose attached PDF is that file, each with `label`; used by the537 `pdf` block to save its annotations as extracts of that reference (extract id derived from attachment id + annotation id, see538 `src/lib/research/pdf-extracts.ts`; `POST …/extracts {id,…}` is idempotent on it). `400 bad_id` on a malformed id.539540### 8.4 `POST /api/research/papers` — `kind` (slice next-p-ra, additive)541542`{title?, status?, venue?, kind?: "paper" | "project"}`. Default `paper` = unchanged. `project` creates the root research page543(`properties.researchKind = "project"`) and five child pages (Hypotheses, Methods notes, Equations, Results, Figures;544`properties.researchRole`), and answers the root page plus `children: [{id, title, key}]` — the tree `export.tex` turns into sections.545546## 9. Error codes introduced by this workstream547548| code | status | where |549|---|---|---|550| `bad_scope`, `selection_required` | SSE `error` | chat |551| `no_text`, `bad_output` | 400 / SSE `error` | action `links` |552| `no_model` | 503 | zoom, inbox suggestions (no eligible model / no key) |553| `provider_error`, `refused`, `bad_output` | 502 | zoom, inbox suggestions |554| `not_generated` | 404 | inbox suggestions with `cachedOnly=1` |555| `not_in_inbox` | 409 | inbox suggestions / apply |556| `nothing_to_apply`, `bad_section`, `bad_destination`, `bad_relation` | 400 | inbox apply |557| `not_audio` (415), `too_large` (413), `not_configured`, `queue_unavailable` (503) | | transcription |558| `not_ai_property` | 400 | database AI config / run |559| `bad_format`, `too_many_ids`, `bad_id` | 400 | research, every route (malformed id) |560561## 10. Data added (migration `0004_next_ai`, additive; rollback `0004_next_ai.down.sql`)562563`ai_providers` + `kind`, `base_url`, `key_env`, `label` (rows `openrouter`, `maclustr` seeded) · `ai_models` + `creator`, `route` ·564tables `ai_synopses`, `inbox_suggestions`, `audio_transcripts`, `ai_property_runs`. New queue: `transcribe`. New settings keys:565`ai.transcription_model`, `ai.transcription_models` (cache of the discovered ids), `ai.transcription_usd_per_minute`.566`ai_usage.task` values added: `zoom`, `inbox_suggest`, `transcribe`, `transcribe_summary`, `action:links` (and `action:<new id>`).567568Deviations from SPEC v1, to keep in mind when coding against it:569570- §3.5 lists `context_window`, `price_in`, `price_out`, `capabilities` as new `ai_models` columns: they already existed571 (`context_window`, `input_price`, `output_price`, `capabilities`) and are **not duplicated** — the API exposes them as `context`,572 `priceIn`, `priceOut` (and keeps the historical names).573- §4.13 says the result is written into the `audio` node "through a normal versioned save": that save is done **by the client**574 (§6.2); the server only stores the transcript in `audio_transcripts`.575- §4.9: level 1 lives at `/api/pages/<id>/zoom/ai` in this branch; `…/zoom?level=1` is wired to it at merge.576- Events (`ai.applied`, …, SPEC §3.2) are not written by these routes yet: `knowledge_events` belongs to migration 0003 (wired at merge).577