From e72cf0acef40abacce15969ada5d9fe2794b39bf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 10:21:35 +0000
Subject: [PATCH 1/2] M4/M5 part 1: AI providers, usage and Settings

The assistant's foundations, copied from GAM's M6 (which came from
Notes): per-user AI providers with encrypted keys, the SSRF guard, the
retrying upstream call, usage events and list-price pricing (Claude
table brought up to date), and a Settings page with the provider panel
and spend.

New over GAM: the clients are multi-turn and call tools. Each keeps its
history in the provider's own wire format and only appends to it, so an
Anthropic turn's content (thinking blocks included) is replayed exactly.
Ollama is served over its OpenAI-compatible /v1 endpoint, tools and all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fiRJAt34ag62iPiuMkNhm
---
 ..._add_ai_provider_and_usage_event_tables.py |  87 +++
 backend/app/main.py                           |   4 +
 backend/app/models/__init__.py                |   4 +-
 backend/app/models/provider.py                |  74 +++
 backend/app/models/usage.py                   |  62 ++
 backend/app/providers/__init__.py             | 119 ++++
 backend/app/providers/_upstream.py            | 172 ++++++
 backend/app/providers/anthropic.py            | 170 +++++
 backend/app/providers/base.py                 | 100 +++
 backend/app/providers/endpoints.py            |  89 +++
 backend/app/providers/openai.py               | 152 +++++
 backend/app/providers/params.py               |  45 ++
 backend/app/routers/providers.py              | 360 +++++++++++
 backend/app/routers/usage.py                  |  62 ++
 backend/app/safe_url.py                       |  81 +++
 backend/app/schemas_providers.py              | 105 ++++
 backend/app/usage/__init__.py                 |   1 +
 backend/app/usage/events.py                   |  86 +++
 backend/app/usage/pricing.py                  | 100 +++
 backend/tests/test_build_provider.py          | 141 +++++
 backend/tests/test_provider_conversations.py  | 197 ++++++
 backend/tests/test_provider_upstream.py       | 219 +++++++
 backend/tests/test_providers_api.py           | 537 ++++++++++++++++
 backend/tests/test_safe_url.py                | 143 +++++
 backend/tests/test_usage.py                   |  58 ++
 frontend/src/App.tsx                          |   2 +
 frontend/src/api/providers.ts                 | 108 ++++
 frontend/src/api/usage.ts                     |  58 ++
 frontend/src/components/AppShell.tsx          |  10 +-
 .../src/components/ProviderPanel.test.tsx     | 242 ++++++++
 frontend/src/components/ProviderPanel.tsx     | 579 ++++++++++++++++++
 frontend/src/components/UsagePanel.test.tsx   |  36 ++
 frontend/src/components/UsagePanel.tsx        |  78 +++
 frontend/src/utils/useSavedFlash.ts           |  19 +
 frontend/src/views/SettingsView.tsx           |  13 +
 35 files changed, 4311 insertions(+), 2 deletions(-)
 create mode 100644 backend/alembic/versions/20261016_1016_add_ai_provider_and_usage_event_tables.py
 create mode 100644 backend/app/models/provider.py
 create mode 100644 backend/app/models/usage.py
 create mode 100644 backend/app/providers/__init__.py
 create mode 100644 backend/app/providers/_upstream.py
 create mode 100644 backend/app/providers/anthropic.py
 create mode 100644 backend/app/providers/base.py
 create mode 100644 backend/app/providers/endpoints.py
 create mode 100644 backend/app/providers/openai.py
 create mode 100644 backend/app/providers/params.py
 create mode 100644 backend/app/routers/providers.py
 create mode 100644 backend/app/routers/usage.py
 create mode 100644 backend/app/safe_url.py
 create mode 100644 backend/app/schemas_providers.py
 create mode 100644 backend/app/usage/__init__.py
 create mode 100644 backend/app/usage/events.py
 create mode 100644 backend/app/usage/pricing.py
 create mode 100644 backend/tests/test_build_provider.py
 create mode 100644 backend/tests/test_provider_conversations.py
 create mode 100644 backend/tests/test_provider_upstream.py
 create mode 100644 backend/tests/test_providers_api.py
 create mode 100644 backend/tests/test_safe_url.py
 create mode 100644 backend/tests/test_usage.py
 create mode 100644 frontend/src/api/providers.ts
 create mode 100644 frontend/src/api/usage.ts
 create mode 100644 frontend/src/components/ProviderPanel.test.tsx
 create mode 100644 frontend/src/components/ProviderPanel.tsx
 create mode 100644 frontend/src/components/UsagePanel.test.tsx
 create mode 100644 frontend/src/components/UsagePanel.tsx
 create mode 100644 frontend/src/utils/useSavedFlash.ts
 create mode 100644 frontend/src/views/SettingsView.tsx

diff --git a/backend/alembic/versions/20261016_1016_add_ai_provider_and_usage_event_tables.py b/backend/alembic/versions/20261016_1016_add_ai_provider_and_usage_event_tables.py
new file mode 100644
index 0000000..e57170c
--- /dev/null
+++ b/backend/alembic/versions/20261016_1016_add_ai_provider_and_usage_event_tables.py
@@ -0,0 +1,87 @@
+"""Add the aiprovider and usageevent tables (M4/M5, the assistant's first half).
+
+Both are copied from GAM's, which came from gecko-notes. `usageevent.project_id` and
+`turn_id` are plain indexed columns, not foreign keys: deleting a project must not
+delete the record of what was spent on it.
+
+Revision ID: 4a8c2f6e9d13
+Revises: 7e2d5a91b3c6
+Create Date: 2026-10-16 10:16:48.213291+00:00
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+revision: str = '4a8c2f6e9d13'
+down_revision: Union[str, None] = '7e2d5a91b3c6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table('aiprovider',
+    sa.Column('id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('user_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('provider_type', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('api_key', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('base_url', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('model', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('max_tokens', sa.Integer(), nullable=False),
+    sa.Column('supports_images', sa.Boolean(), nullable=False),
+    sa.Column('use_anthropic_api', sa.Boolean(), nullable=False),
+    sa.Column('extra_params', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('enabled', sa.Boolean(), nullable=False),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('aiprovider', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_aiprovider_user_id'), ['user_id'], unique=False)
+
+    op.create_table('usageevent',
+    sa.Column('id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('user_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('project_id', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('kind', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('provider', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('model', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('units', sa.Integer(), nullable=False),
+    sa.Column('unit_type', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('cost', sa.Float(), nullable=True),
+    sa.Column('currency', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('cost_estimated', sa.Boolean(), nullable=True),
+    sa.Column('turn_id', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('usageevent', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_usageevent_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_usageevent_kind'), ['kind'], unique=False)
+        batch_op.create_index(batch_op.f('ix_usageevent_project_id'), ['project_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_usageevent_provider'), ['provider'], unique=False)
+        batch_op.create_index(batch_op.f('ix_usageevent_turn_id'), ['turn_id'], unique=False)
+        batch_op.create_index('ix_usageevent_user_created', ['user_id', 'created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_usageevent_user_id'), ['user_id'], unique=False)
+
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('usageevent', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_usageevent_user_id'))
+        batch_op.drop_index('ix_usageevent_user_created')
+        batch_op.drop_index(batch_op.f('ix_usageevent_turn_id'))
+        batch_op.drop_index(batch_op.f('ix_usageevent_provider'))
+        batch_op.drop_index(batch_op.f('ix_usageevent_project_id'))
+        batch_op.drop_index(batch_op.f('ix_usageevent_kind'))
+        batch_op.drop_index(batch_op.f('ix_usageevent_created_at'))
+
+    op.drop_table('usageevent')
+    with op.batch_alter_table('aiprovider', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_aiprovider_user_id'))
+
+    op.drop_table('aiprovider')
diff --git a/backend/app/main.py b/backend/app/main.py
index 6d957b4..0d0e76f 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -22,8 +22,10 @@
 from app.gam.client import GamError
 from app.routers import gam as gam_router
 from app.routers import projects as projects_router
+from app.routers import providers as providers_router
 from app.routers import renders as renders_router
 from app.routers import spec as spec_router
+from app.routers import usage as usage_router
 from app.schemas import ClientConfig, DataResponse, HealthResponse
 
 logging.basicConfig(level=logging.INFO)
@@ -145,5 +147,7 @@ def me(user: CurrentUser, session: Session = Depends(get_session)) -> DataRespon
 app.include_router(spec_router.router, prefix="/api/spec", tags=["spec"])
 app.include_router(gam_router.router, prefix="/api/gam", tags=["gam"])
 app.include_router(renders_router.router, prefix="/api", tags=["renders"])
+app.include_router(providers_router.router, prefix="/api/providers", tags=["providers"])
+app.include_router(usage_router.router, prefix="/api/usage", tags=["usage"])
 # Not under /api: these URLs go straight into <video src>, authorised by signature.
 app.include_router(renders_router.media_router, prefix="/media/renders", tags=["media"])
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 7438325..01a3944 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -6,7 +6,9 @@
 """
 
 from app.models.project import Project, ProjectVersion
+from app.models.provider import AIProvider
 from app.models.render import RenderJob
+from app.models.usage import UsageEvent
 from app.models.user import User
 
-__all__ = ["Project", "ProjectVersion", "RenderJob", "User"]
+__all__ = ["AIProvider", "Project", "ProjectVersion", "RenderJob", "UsageEvent", "User"]
diff --git a/backend/app/models/provider.py b/backend/app/models/provider.py
new file mode 100644
index 0000000..f88b3dd
--- /dev/null
+++ b/backend/app/models/provider.py
@@ -0,0 +1,74 @@
+"""A configured generative LLM, per user.
+
+Separate from the embedding provider in `app.settings_store`, and deliberately so:
+embeddings and generation are different capabilities with genuinely different provider
+sets. Anthropic publishes no embeddings API at all, and DeepSeek's chat models are
+text-only while its Anthropic-compatible endpoint is the one that can search the web.
+`docs/m6-ai-enrichment.md` works through why one dial cannot serve both.
+
+A row per provider rather than a key-value blob in `UserSetting`: a user keeps several
+configured at once — a local Ollama for cheap work, Claude for anything needing vision —
+and switches between them, which is what `is_active` is for.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Optional
+
+from sqlmodel import Field, SQLModel
+
+from app.clock import utcnow
+
+
+def new_provider_id() -> str:
+    return str(uuid.uuid4())
+
+
+class AIProvider(SQLModel, table=True):
+    id: str = Field(default_factory=new_provider_id, primary_key=True)
+    # Not Optional, unlike gecko-notes' column: there is no such thing as an
+    # unowned provider here, and a nullable owner is a row every user can see.
+    user_id: str = Field(index=True)
+
+    name: str
+    provider_type: str  # one of app.providers.PROVIDER_TYPES
+    # Fernet-encrypted at rest (app.auth.encrypt_api_key), empty when the provider
+    # needs no credential — Ollama is local and takes none.
+    api_key: str = Field(default="")
+    base_url: Optional[str] = None
+    # Free text, not a closed list. Models appear faster than this app can be
+    # redeployed, and a dropdown is the thing that dates first.
+    model: str
+    max_tokens: int = Field(default=16384)  # cap on the model's response (output) length
+
+    # Whether this provider/model accepts image (and PDF) content blocks. Text-only
+    # backends (DeepSeek chat, most local models) reject them with a deserialization
+    # error from upstream, which is an unreadable way to learn the model cannot see.
+    # This flag is what will gate the `describe` job in step 5 of the milestone.
+    supports_images: bool = Field(default=False)
+
+    # Speak the Anthropic Messages protocol to this provider instead of its default
+    # (OpenAI-compatible) one. DeepSeek publishes an Anthropic-compatible endpoint at
+    # api.deepseek.com/anthropic which runs the same server-side web_search tool Claude
+    # does — so a DeepSeek provider with this set searches the web itself, natively,
+    # with no third-party search key. Also usable for a `custom` Anthropic-compatible
+    # gateway (with its own base_url). Ignored for `anthropic` (already native) and
+    # `ollama` (its own protocol) — see app.providers.ANTHROPIC_CAPABLE_TYPES.
+    use_anthropic_api: bool = Field(default=False)
+
+    # Arbitrary extra request parameters, JSON-as-TEXT — e.g. {"temperature": 0}, top_p,
+    # or provider-specific knobs. Merged into the outgoing request once the clients land
+    # in step 2; structural keys (model, messages, max_tokens, …) are stripped first.
+    # None sends nothing optional. Decoded to a dict on read.
+    extra_params: Optional[str] = None
+
+    enabled: bool = Field(default=True)
+    # At most one active row per user. Enforced by the router rather than by a partial
+    # unique index: SQLite supports one, Alembic's autogenerate does not emit it, and a
+    # constraint the migration silently drops is worse than none.
+    is_active: bool = Field(default=False)
+
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
diff --git a/backend/app/models/usage.py b/backend/app/models/usage.py
new file mode 100644
index 0000000..637a165
--- /dev/null
+++ b/backend/app/models/usage.py
@@ -0,0 +1,62 @@
+"""What each call to a paid service cost, so GVC can answer "how much".
+
+Copied from GAM (`app/models/usage.py`), which ported it from gecko-notes, with
+`project_id` in place of GAM's `asset_id`: spend is attributed to the video it was spent
+on. A plain indexed column and not a foreign key, on purpose: deleting a project must
+not delete the record of what was spent on it.
+
+The field that matters most is `cost_estimated`. A figure from `usage/pricing.py` is a
+published list price, not a bill, and nothing may show a cost without saying so.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import Index
+from sqlmodel import Field, SQLModel
+
+from app.clock import utcnow
+
+# Only the assistant spends in GVC so far. Narration is read through Notes and billed
+# there, so it is never counted here twice.
+KIND_AI = "ai"
+
+UNIT_TOKENS = "tokens"
+
+
+def new_usage_id() -> str:
+    return str(uuid.uuid4())
+
+
+class UsageEvent(SQLModel, table=True):
+    __table_args__ = (Index("ix_usageevent_user_created", "user_id", "created_at"),)
+
+    id: str = Field(default_factory=new_usage_id, primary_key=True)
+    user_id: str = Field(index=True)
+    # Nullable: a draft from the project list has no project until it is applied. No
+    # foreign key, on purpose: see the module docstring.
+    project_id: Optional[str] = Field(default=None, index=True)
+
+    kind: str = Field(index=True)
+    # The provider's own type, not the protocol it spoke. A DeepSeek provider addressed
+    # over the Anthropic endpoint is DeepSeek spend, and costing it as Anthropic would be
+    # wrong by an order of magnitude.
+    provider: Optional[str] = Field(default=None, index=True)
+    model: str = Field(default="")
+
+    units: int = Field(default=0)
+    unit_type: str = Field(default="")
+
+    # None when no estimate is possible — a `custom` endpoint, or a model family the
+    # table does not know. Storing a zero there would read as "this was free".
+    cost: Optional[float] = None
+    currency: Optional[str] = None
+    # True for a list-price estimate, which is all GVC records.
+    cost_estimated: Optional[bool] = None
+    # The assistant turn the call belonged to, so a turn's cost is one sum.
+    turn_id: Optional[str] = Field(default=None, index=True)
+
+    created_at: datetime = Field(default_factory=utcnow, index=True)
diff --git a/backend/app/providers/__init__.py b/backend/app/providers/__init__.py
new file mode 100644
index 0000000..9700ba7
--- /dev/null
+++ b/backend/app/providers/__init__.py
@@ -0,0 +1,119 @@
+"""Chat LLM providers for the assistant. Copied from GAM's `app/providers/` (which came
+from gecko-notes), with the clients rewritten for multi-turn tool use: see `base.py`.
+
+Constants and endpoint resolution live here, alongside `build_provider` — the one
+function a caller needs. The clients themselves are imported lazily inside it, so the
+settings router still pays nothing for an HTTP stack it never uses, and `endpoints.py`
+can import these constants without a cycle.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sqlmodel import Session
+
+    from app.models.provider import AIProvider
+    from app.providers.base import ChatProvider
+
+logger = logging.getLogger(__name__)
+
+PROVIDER_ANTHROPIC = "anthropic"
+PROVIDER_OPENAI = "openai"
+PROVIDER_DEEPSEEK = "deepseek"
+PROVIDER_OLLAMA = "ollama"
+PROVIDER_CUSTOM = "custom"
+
+# The allowlist the router validates against. A
+# stored value outside it is not a 500 later — it is a 400 now.
+PROVIDER_TYPES = (
+    PROVIDER_ANTHROPIC,
+    PROVIDER_OPENAI,
+    PROVIDER_DEEPSEEK,
+    PROVIDER_OLLAMA,
+    PROVIDER_CUSTOM,
+)
+
+# Types that may be pointed at an Anthropic-compatible endpoint instead of their own.
+# `anthropic` is absent because it is always on that path already. `ollama` is absent
+# deliberately: it speaks only its own protocol, and its base_url is the one address in
+# this app allowed to be private, so honouring the flag there would aim the Messages
+# request at an internal host.
+ANTHROPIC_CAPABLE_TYPES = (PROVIDER_DEEPSEEK, PROVIDER_CUSTOM)
+
+# Types whose base_url is user-supplied and therefore SSRF-checked before it is stored.
+# `anthropic` and `deepseek` resolve to fixed managed endpoints (see endpoints.py) and
+# `ollama` is the deliberate private-address exception.
+CHECKED_BASE_URL_TYPES = (PROVIDER_OPENAI, PROVIDER_CUSTOM)
+
+def active_provider(session: "Session", user_id: str) -> Optional["AIProvider"]:
+    """This user's chosen provider row, if they have one that can run.
+
+    `enabled` is the user saying "not this one for now" without deleting it, so a
+    disabled row is not a candidate even when it is the active one.
+    """
+    from sqlmodel import col, select
+
+    from app.models.provider import AIProvider
+
+    # `col(...).is_(True)` rather than `== True`: this has to render as SQL, and the
+    # plain comparison is the one flake8 flags and readers misread as a Python bug.
+    return session.exec(
+        select(AIProvider).where(
+            AIProvider.user_id == user_id,
+            col(AIProvider.is_active).is_(True),
+            col(AIProvider.enabled).is_(True),
+        )
+    ).first()
+
+
+def build_provider(session: "Session", user_id: str) -> Optional["ChatProvider"]:
+    """This user's configured LLM client, or None if they have not set one up.
+
+    None rather than an exception: a project with no
+    provider is not broken, it simply has no assistant yet, and everything else about
+    it still works. Only an attempt to *use* one is an error worth raising.
+
+    Which client is chosen keys off the protocol the provider speaks, never off the
+    vendor name — a DeepSeek row with `use_anthropic_api` is addressed over Messages,
+    and `speaks_anthropic` is the single place that decision lives.
+    """
+    from app.auth import decrypt_api_key
+    from app.providers.endpoints import speaks_anthropic
+
+    row = active_provider(session, user_id)
+    if row is None:
+        return None
+
+    api_key = decrypt_api_key(row.api_key) if row.api_key else ""
+    if not api_key and row.provider_type != PROVIDER_OLLAMA:
+        # A row whose key failed to decrypt — JWT_SECRET_KEY rotated under it — reads as
+        # unconfigured rather than as a provider that will 401 on every turn. The settings screen already reports the key as missing.
+        logger.warning("Provider %s for %s has no usable API key", row.id, user_id)
+        return None
+
+    if speaks_anthropic(row):
+        from app.providers.anthropic import AnthropicProvider
+
+        return AnthropicProvider(row, api_key)
+
+    # Ollama too: its /v1 endpoint speaks the OpenAI protocol, tools included.
+    from app.providers.openai import OpenAIProvider
+
+    return OpenAIProvider(row, api_key)
+
+
+__all__ = [
+    "ANTHROPIC_CAPABLE_TYPES",
+    "CHECKED_BASE_URL_TYPES",
+    "PROVIDER_ANTHROPIC",
+    "PROVIDER_CUSTOM",
+    "PROVIDER_DEEPSEEK",
+    "PROVIDER_OLLAMA",
+    "PROVIDER_OPENAI",
+    "PROVIDER_TYPES",
+    "active_provider",
+    "build_provider",
+]
diff --git a/backend/app/providers/_upstream.py b/backend/app/providers/_upstream.py
new file mode 100644
index 0000000..f892f2e
--- /dev/null
+++ b/backend/app/providers/_upstream.py
@@ -0,0 +1,172 @@
+"""One POST to a provider, with the retries and the timeout split.
+
+Copied from GAM, which ported it from gecko-notes' `_post_upstream`, made synchronous:
+every provider call here runs on the assistant's job worker thread, so blocking one is
+the intended behaviour.
+
+Two decisions carried over from there, both worth keeping:
+
+- **Only 429 and 503 are retried.** They mean "ask again", and nothing was produced or
+  billed on the attempt that returned them, so a fresh request is safe. A 400 or a 401
+  will fail identically forever and retrying it just delays the error.
+- **The timeout is split.** A blocking completion returns no bytes until the whole
+  answer is generated, so the read window has to cover generation — but connect, write
+  and pool stay short, so a genuinely dead endpoint fails in seconds instead of hanging
+  for the entire read budget.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from app.providers.base import ProviderError
+
+logger = logging.getLogger(__name__)
+
+RETRY_STATUS_CODES = frozenset({429, 503})
+MAX_ATTEMPTS = 3
+RETRY_BASE_DELAY = 0.5
+
+# A provider that asks for a longer wait than this is telling us to come back later, not
+# to hold a worker thread open. Past the cap the run fails and the user can start it
+# again — one job stuck for an hour would block everything queued behind it.
+MAX_RETRY_AFTER = 30.0
+
+
+def _retry_after(response: httpx.Response, fallback: float) -> float:
+    """Honour a `Retry-After` header when the provider sends one.
+
+    gecko-notes backs off blindly. A provider that has told us exactly how long to wait
+    is better information than an exponential guess — but it is also attacker-adjacent
+    input for a `custom` endpoint, so it is clamped rather than trusted.
+    """
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return fallback
+    try:
+        seconds = float(raw.strip())
+    except ValueError:
+        # The header may also be an HTTP date. Parsing one to shave a fraction off a
+        # backoff is not worth the timezone handling it needs to be correct.
+        return fallback
+    if seconds <= 0:
+        return fallback
+    return min(seconds, MAX_RETRY_AFTER)
+
+
+def post_json(
+    url: str,
+    *,
+    headers: Optional[Mapping[str, str]] = None,
+    json_body: Mapping[str, Any],
+    timeout: float,
+    label: str,
+    sleep=time.sleep,
+) -> httpx.Response:
+    """POST and return the response, retrying only what is worth retrying.
+
+    Connection-level failures become ProviderError with a sentence naming the provider;
+    an HTTP error status is returned as-is, because only the caller knows how to read
+    its body. `sleep` is injected so tests do not spend the backoff.
+    """
+    try:
+        with httpx.Client(timeout=_split_timeout(timeout)) as client:
+            for attempt in range(MAX_ATTEMPTS):
+                response = client.post(url, headers=dict(headers or {}), json=dict(json_body))
+                if response.status_code not in RETRY_STATUS_CODES:
+                    return response
+                if attempt == MAX_ATTEMPTS - 1:
+                    return response
+
+                delay = _retry_after(response, RETRY_BASE_DELAY * (2**attempt))
+                logger.info(
+                    "%s returned %d; retrying in %.1fs (attempt %d of %d)",
+                    label,
+                    response.status_code,
+                    delay,
+                    attempt + 1,
+                    MAX_ATTEMPTS,
+                )
+                sleep(delay)
+            return response
+    except httpx.TimeoutException as exc:
+        raise ProviderError(f"{label} did not respond in time") from exc
+    except httpx.RequestError as exc:
+        # The exception type, not its text: a RequestError's message can carry the full
+        # URL, and a `custom` provider's URL is user-supplied.
+        raise ProviderError(f"Could not reach {label} ({type(exc).__name__})") from exc
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    headers: Optional[Mapping[str, str]] = None,
+    params: Optional[Mapping[str, str]] = None,
+    timeout: float,
+    label: str,
+) -> httpx.Response:
+    """One call with headers and no retry, for anything that is not a POST of JSON.
+
+    fal's queue (M8) is the reason: its status, result and cancel calls are a GET and a
+    PUT that carry the key in a header, which `get_json` cannot send. Not retried —
+    a status poll is retried by being polled again, and a cancel is best-effort — but
+    connection failures read the same way `post_json`'s do.
+    """
+    try:
+        with httpx.Client(timeout=_split_timeout(timeout)) as client:
+            return client.request(
+                method, url, headers=dict(headers or {}), params=dict(params or {})
+            )
+    except httpx.TimeoutException as exc:
+        raise ProviderError(f"{label} did not respond in time") from exc
+    except httpx.RequestError as exc:
+        raise ProviderError(f"Could not reach {label} ({type(exc).__name__})") from exc
+
+
+def _split_timeout(timeout: float) -> httpx.Timeout:
+    return httpx.Timeout(
+        timeout,
+        connect=min(timeout, 10.0),
+        write=min(timeout, 30.0),
+        pool=min(timeout, 10.0),
+    )
+
+
+def get_json(url: str, *, timeout: float, label: str) -> httpx.Response:
+    """The read-only counterpart, for probing whether a local daemon is up."""
+    try:
+        return httpx.get(url, timeout=httpx.Timeout(timeout, connect=min(timeout, 10.0)))
+    except httpx.TimeoutException as exc:
+        raise ProviderError(f"{label} did not respond in time") from exc
+    except httpx.RequestError as exc:
+        raise ProviderError(f"Could not reach {label} ({type(exc).__name__})") from exc
+
+
+def error_detail(response: httpx.Response) -> str:
+    """A sentence from an error response, whatever shape it arrived in.
+
+    Every provider nests its message somewhere different and some send HTML, so this
+    tries the known shapes and falls back to the status code rather than pasting a page
+    of markup into a job's error field.
+    """
+    try:
+        body = response.json()
+    except ValueError:
+        return f"HTTP {response.status_code}"
+
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, dict) and isinstance(error.get("message"), str):
+            return error["message"]
+        if isinstance(error, str):
+            return error
+        for key in ("message", "detail", "err_msg"):
+            if isinstance(body.get(key), str):
+                return body[key]
+
+    return f"HTTP {response.status_code}"
diff --git a/backend/app/providers/anthropic.py b/backend/app/providers/anthropic.py
new file mode 100644
index 0000000..7736395
--- /dev/null
+++ b/backend/app/providers/anthropic.py
@@ -0,0 +1,170 @@
+"""The Anthropic Messages protocol, with tools.
+
+Serves `anthropic`, and `deepseek` or a `custom` gateway with `use_anthropic_api` set
+(see `endpoints.py`). Raw httpx like the rest of the suite's provider code, because one
+layer has to speak four vendors' protocols and the others have no Anthropic SDK to hand.
+
+Two rules from the current API shape this:
+- The assistant's content goes back exactly as it arrived, thinking blocks included,
+  for every later request in the turn (`base.py` says why).
+- Nothing forces a tool or switches thinking off: on current models a forced
+  `tool_choice` and a disabled-thinking setting are both rejected, so the defaults
+  (`auto`, adaptive thinking) are left alone and the prompt does the steering.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Sequence, Tuple
+
+from app.providers import PROVIDER_ANTHROPIC, _upstream
+from app.providers.base import ProviderError, Reply, ToolCall, ToolResult, ToolSpec, Usage
+from app.providers.endpoints import anthropic_base, anthropic_headers
+from app.providers.params import parse_extra_params
+
+logger = logging.getLogger(__name__)
+
+# A whole first draft can be several thousand tokens of tool input, generated before a
+# byte comes back. Connect and write stay short in `_upstream`, so a dead endpoint still
+# fails fast.
+REQUEST_TIMEOUT = 300.0
+
+_STOPS = {"end_turn": "end", "tool_use": "tool_use", "max_tokens": "max_tokens",
+          "refusal": "refusal", "stop_sequence": "end"}
+
+
+class AnthropicProvider:
+    def __init__(self, provider, api_key: str):
+        self._provider = provider
+        self._api_key = api_key
+
+    @property
+    def model(self) -> str:
+        return self._provider.model
+
+    @property
+    def provider_type(self) -> str:
+        return self._provider.provider_type
+
+    def conversation(self, *, system: Sequence[str], tools: Sequence[ToolSpec],
+                     history: Sequence[Tuple[str, str]], prompt: str) -> "AnthropicConversation":
+        return AnthropicConversation(self._provider, self._api_key, system, tools, history, prompt)
+
+
+class AnthropicConversation:
+    def __init__(self, provider, api_key: str, system: Sequence[str], tools: Sequence[ToolSpec],
+                 history: Sequence[Tuple[str, str]], prompt: str):
+        self._provider = provider
+        self._api_key = api_key
+        # Each system block is a cache breakpoint: the reference first (never changes),
+        # then the project context (fixed for the whole turn). Anthropic allows four.
+        self._system = [{"type": "text", "text": text, "cache_control": {"type": "ephemeral"}}
+                        for text in system[:3] if text]
+        self._tools = [{"name": t.name, "description": t.description, "input_schema": t.parameters}
+                       for t in tools]
+        self.messages: List[Dict[str, Any]] = []
+        for role, text in history:
+            self._push(role, text)
+        self._push("user", prompt)
+
+    def _push(self, role: str, text: str) -> None:
+        # The API wants turns to alternate; two of the same role in a row (a turn that
+        # failed before answering) are merged rather than sent as a 400.
+        if self.messages and self.messages[-1]["role"] == role and isinstance(
+                self.messages[-1]["content"], str):
+            self.messages[-1]["content"] += "\n\n" + text
+        else:
+            self.messages.append({"role": role, "content": text})
+
+    def _body(self) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "model": self._provider.model,
+            "max_tokens": self._provider.max_tokens,
+            "messages": self.messages,
+        }
+        if self._system:
+            body["system"] = self._system
+        if self._tools:
+            body["tools"] = self._tools
+        if self._provider.provider_type == PROVIDER_ANTHROPIC:
+            # Top-level caching moves its breakpoint to the end of the conversation each
+            # round, so a long tool loop re-reads its history at the cached rate. Only
+            # for Anthropic itself: a compatible gateway may not know the field.
+            body["cache_control"] = {"type": "ephemeral"}
+        body.update(parse_extra_params(self._provider.extra_params))
+        return body
+
+    def ask(self) -> Reply:
+        response = _upstream.post_json(
+            f"{anthropic_base(self._provider)}/v1/messages",
+            headers=anthropic_headers(self._api_key, self._provider.provider_type),
+            json_body=self._body(), timeout=REQUEST_TIMEOUT, label=self._provider.name,
+        )
+        if response.status_code >= 400:
+            raise ProviderError(f"{self._provider.name}: {_upstream.error_detail(response)}")
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ProviderError(f"{self._provider.name} returned a response that was not JSON") from exc
+        reply = parse_response(payload, model=self._provider.model,
+                               provider_type=self._provider.provider_type)
+        content = payload.get("content") if isinstance(payload, dict) else None
+        # Verbatim, thinking blocks and all.
+        self.messages.append({"role": "assistant", "content": content or []})
+        return reply
+
+    def answer(self, results: Sequence[ToolResult]) -> None:
+        # Every result in one user message: splitting them teaches the model to stop
+        # calling tools in parallel.
+        self.messages.append({"role": "user", "content": [
+            {"type": "tool_result", "tool_use_id": r.call_id, "content": r.content,
+             **({"is_error": True} if r.is_error else {})}
+            for r in results
+        ]})
+
+
+def parse_response(payload: Any, *, model: str, provider_type: str) -> Reply:
+    if not isinstance(payload, dict) or not isinstance(payload.get("content"), list):
+        raise ProviderError("The provider returned a message with no content")
+    text_parts: List[str] = []
+    calls: List[ToolCall] = []
+    for block in payload["content"]:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") == "text":
+            text_parts.append(block.get("text", ""))
+        elif block.get("type") == "tool_use":
+            arguments = block.get("input")
+            calls.append(ToolCall(
+                id=str(block.get("id", "")), name=str(block.get("name", "")),
+                arguments=arguments if isinstance(arguments, dict) else {},
+                parse_error=None if isinstance(arguments, dict) else "arguments were not an object",
+            ))
+    stop = _STOPS.get(payload.get("stop_reason"), "other")
+    if stop == "refusal":
+        details = payload.get("stop_details") or {}
+        raise ProviderError("The model declined this request"
+                            + (f" ({details.get('category')})" if details.get("category") else ""))
+
+    usage = payload.get("usage") if isinstance(payload.get("usage"), dict) else {}
+
+    def count(key: str) -> int:
+        try:
+            return int(usage.get(key, 0) or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    # Cache reads and writes are billed input; dropping them would make a cached turn
+    # look nearly free.
+    return Reply(
+        text="".join(text_parts).strip(), tool_calls=calls, stop=stop,
+        usage=Usage(input_tokens=count("input_tokens") + count("cache_read_input_tokens")
+                    + count("cache_creation_input_tokens"),
+                    output_tokens=count("output_tokens")),
+        model=model, provider_type=provider_type,
+    )
+
+
+def dumps(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False)
diff --git a/backend/app/providers/base.py b/backend/app/providers/base.py
new file mode 100644
index 0000000..49239ce
--- /dev/null
+++ b/backend/app/providers/base.py
@@ -0,0 +1,100 @@
+"""What a chat provider has to do for the assistant: a conversation that can call tools.
+
+GAM's provider layer (which this package is copied from) is one prompt in, one answer
+out, because its callers each ask one question. The assistant is an agent: it searches
+the library, edits the spec, reads the issues its edit produced and fixes them, all in
+one turn. So the unit here is a `Conversation`, which owns its message history in the
+provider's own wire format and grows it append-only.
+
+Append-only is load-bearing, not tidiness. Anthropic's current models return thinking
+blocks that must be replayed exactly as they came for the rest of the turn; a history
+rebuilt from a neutral format each round would drop or alter them. So each adapter keeps
+what the provider sent and only ever appends to it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, Sequence, Tuple
+
+
+class ProviderError(Exception):
+    """The provider refused, failed, or returned something unusable."""
+
+
+class ProviderUnavailable(ProviderError):
+    """No usable provider is configured for this user: the fix is Settings, not a retry."""
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    # JSON Schema of the arguments.
+    parameters: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+    # Set when the model's arguments were not a JSON object; handed back as an error
+    # result so it can try again, never executed.
+    parse_error: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    call_id: str
+    content: str
+    is_error: bool = False
+
+
+@dataclass
+class Reply:
+    text: str
+    tool_calls: List[ToolCall] = field(default_factory=list)
+    usage: Usage = field(default_factory=Usage)
+    # end | tool_use | max_tokens | refusal | other
+    stop: str = "end"
+    model: str = ""
+    # The provider's own type, not the protocol it spoke: DeepSeek over the Anthropic
+    # endpoint is DeepSeek spend.
+    provider_type: str = ""
+
+
+class Conversation(Protocol):
+    def ask(self) -> Reply:
+        """Send the history so far and return what the model said next."""
+        ...
+
+    def answer(self, results: Sequence[ToolResult]) -> None:
+        """Append the results of the tool calls in the last reply, all in one message."""
+        ...
+
+
+class ChatProvider(Protocol):
+    @property
+    def model(self) -> str: ...
+
+    @property
+    def provider_type(self) -> str: ...
+
+    def conversation(
+        self, *, system: Sequence[str], tools: Sequence[ToolSpec],
+        history: Sequence[Tuple[str, str]], prompt: str,
+    ) -> Conversation:
+        """A new conversation.
+
+        `system` is a list of blocks, most stable first: a provider that caches prompts
+        breaks after each. `history` is earlier (role, text) turns, roles "user" and
+        "assistant"; `prompt` is the user's new message.
+        """
+        ...
diff --git a/backend/app/providers/endpoints.py b/backend/app/providers/endpoints.py
new file mode 100644
index 0000000..025e9b3
--- /dev/null
+++ b/backend/app/providers/endpoints.py
@@ -0,0 +1,89 @@
+"""Which URL a provider is actually addressed at, and over which protocol.
+
+Ported from gecko-notes (`backend/app/routers/settings.py:843-886`), whose reasoning is
+the part worth carrying: three of the decisions here look arbitrary and are not.
+
+The Messages protocol is no longer only Anthropic's. DeepSeek publishes an
+Anthropic-compatible endpoint at api.deepseek.com/anthropic, and — this is the point of
+it — that endpoint runs the same SERVER-SIDE web_search tool Claude does. So a DeepSeek
+provider pointed at it searches the web natively, exactly the way a Claude one does: no
+third-party search key, no per-search fee, nothing for this app to run. Its
+OpenAI-compatible endpoint has no such tool.
+
+A provider opts in per row with `use_anthropic_api`; `anthropic` itself is always on this
+path. Everything downstream keys off `speaks_anthropic()`, not off the vendor name.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from app.models.provider import AIProvider
+from app.providers import (
+    ANTHROPIC_CAPABLE_TYPES,
+    PROVIDER_ANTHROPIC,
+    PROVIDER_DEEPSEEK,
+)
+
+ANTHROPIC_BASE = "https://api.anthropic.com"
+DEEPSEEK_ANTHROPIC_BASE = "https://api.deepseek.com/anthropic"
+OPENAI_BASE = "https://api.openai.com"
+DEEPSEEK_BASE = "https://api.deepseek.com"
+OLLAMA_BASE = "http://localhost:11434"
+
+
+def speaks_anthropic(provider: AIProvider) -> bool:
+    """Whether this provider is addressed over the Anthropic Messages protocol."""
+    if provider.provider_type == PROVIDER_ANTHROPIC:
+        return True
+    return bool(provider.use_anthropic_api) and provider.provider_type in ANTHROPIC_CAPABLE_TYPES
+
+
+def anthropic_base(provider: AIProvider) -> str:
+    """Base URL for a provider's Messages endpoint.
+
+    Anthropic's own is fixed, and so is DeepSeek's — its stored `base_url` describes the
+    OpenAI-compatible endpoint, so it is deliberately ignored here (the same reasoning as
+    `openai_compat_base`: a fixed managed endpoint spares the user a field and stops a
+    crafted base_url redirecting the request). Any other provider opting in supplies its
+    own gateway URL, SSRF-checked when it was saved.
+    """
+    if provider.provider_type == PROVIDER_ANTHROPIC:
+        return ANTHROPIC_BASE
+    if provider.provider_type == PROVIDER_DEEPSEEK:
+        return DEEPSEEK_ANTHROPIC_BASE
+    return (provider.base_url or ANTHROPIC_BASE).rstrip("/")
+
+
+def openai_compat_base(provider_type: Optional[str], base_url: Optional[str]) -> str:
+    """Resolve the upstream base URL for an OpenAI-compatible provider.
+
+    DeepSeek is a fixed managed endpoint, like OpenAI's own, so it ignores any stored
+    base_url: that both spares the user a URL field and stops a crafted base_url from
+    redirecting the request. `openai` and `custom` supply their own, already SSRF-checked
+    on save.
+    """
+    if provider_type == PROVIDER_DEEPSEEK:
+        return DEEPSEEK_BASE
+    return (base_url or OPENAI_BASE).rstrip("/")
+
+
+def anthropic_headers(api_key: str, provider_type: str) -> dict[str, str]:
+    """Auth and protocol headers for one Messages request.
+
+    Beta flags go only to Anthropic: they name Anthropic-internal features, and a gateway
+    that does not recognise one could reject the whole request over a feature it was
+    never asked for. Compatible gateways get BOTH auth headers because they disagree
+    about which to read — DeepSeek documents `x-api-key`, while Claude Code's own
+    ANTHROPIC_AUTH_TOKEN path sends a bearer token — and an unread header is ignored.
+    """
+    headers = {
+        "x-api-key": api_key,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+    }
+    if provider_type == PROVIDER_ANTHROPIC:
+        headers["anthropic-beta"] = "pdfs-2024-09-25"
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
diff --git a/backend/app/providers/openai.py b/backend/app/providers/openai.py
new file mode 100644
index 0000000..f0272d7
--- /dev/null
+++ b/backend/app/providers/openai.py
@@ -0,0 +1,152 @@
+"""The OpenAI chat-completions protocol, with tools.
+
+Serves `openai`, `custom`, `deepseek` (unless pointed at its Anthropic endpoint) and
+`ollama`, whose `/v1` endpoint speaks the same protocol, tools included. One client for
+all four, named for the protocol rather than a vendor.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Sequence, Tuple
+
+from app.providers import PROVIDER_OLLAMA, _upstream
+from app.providers.base import ProviderError, Reply, ToolCall, ToolResult, ToolSpec, Usage
+from app.providers.endpoints import OLLAMA_BASE, openai_compat_base
+from app.providers.params import parse_extra_params
+
+logger = logging.getLogger(__name__)
+
+REQUEST_TIMEOUT = 300.0
+# A local model on modest hardware takes minutes per answer, not seconds.
+OLLAMA_TIMEOUT = 900.0
+
+_STOPS = {"stop": "end", "tool_calls": "tool_use", "length": "max_tokens",
+          "content_filter": "refusal", "function_call": "tool_use"}
+
+
+class OpenAIProvider:
+    def __init__(self, provider, api_key: str):
+        self._provider = provider
+        self._api_key = api_key
+
+    @property
+    def model(self) -> str:
+        return self._provider.model
+
+    @property
+    def provider_type(self) -> str:
+        return self._provider.provider_type
+
+    def conversation(self, *, system: Sequence[str], tools: Sequence[ToolSpec],
+                     history: Sequence[Tuple[str, str]], prompt: str) -> "OpenAIConversation":
+        return OpenAIConversation(self._provider, self._api_key, system, tools, history, prompt)
+
+
+class OpenAIConversation:
+    def __init__(self, provider, api_key: str, system: Sequence[str], tools: Sequence[ToolSpec],
+                 history: Sequence[Tuple[str, str]], prompt: str):
+        self._provider = provider
+        self._api_key = api_key
+        self._tools = [{"type": "function", "function": {
+            "name": t.name, "description": t.description, "parameters": t.parameters}}
+            for t in tools]
+        # One system message: this protocol has no blocks, and its providers cache the
+        # longest stable prefix on their own.
+        self.messages: List[Dict[str, Any]] = []
+        joined = "\n\n".join(text for text in system if text)
+        if joined:
+            self.messages.append({"role": "system", "content": joined})
+        for role, text in history:
+            self.messages.append({"role": role, "content": text})
+        self.messages.append({"role": "user", "content": prompt})
+
+    def _url_and_timeout(self) -> Tuple[str, float]:
+        if self._provider.provider_type == PROVIDER_OLLAMA:
+            base = (self._provider.base_url or OLLAMA_BASE).rstrip("/")
+            return f"{base}/v1/chat/completions", OLLAMA_TIMEOUT
+        base = openai_compat_base(self._provider.provider_type, self._provider.base_url)
+        return f"{base}/v1/chat/completions", REQUEST_TIMEOUT
+
+    def ask(self) -> Reply:
+        body: Dict[str, Any] = {
+            "model": self._provider.model,
+            "max_tokens": self._provider.max_tokens,
+            "messages": self.messages,
+        }
+        if self._tools:
+            body["tools"] = self._tools
+        body.update(parse_extra_params(self._provider.extra_params))
+        url, timeout = self._url_and_timeout()
+        headers = {"content-type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        response = _upstream.post_json(url, headers=headers, json_body=body, timeout=timeout,
+                                       label=self._provider.name)
+        if response.status_code >= 400:
+            raise ProviderError(f"{self._provider.name}: {_upstream.error_detail(response)}")
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ProviderError(f"{self._provider.name} returned a response that was not JSON") from exc
+        reply, message = parse_response(payload, model=self._provider.model,
+                                        provider_type=self._provider.provider_type)
+        self.messages.append(message)
+        return reply
+
+    def answer(self, results: Sequence[ToolResult]) -> None:
+        for r in results:
+            # No error flag in this protocol: an error is said in the content.
+            self.messages.append({"role": "tool", "tool_call_id": r.call_id,
+                                  "content": ("ERROR: " + r.content) if r.is_error else r.content})
+
+
+def parse_response(payload: Any, *, model: str, provider_type: str) -> Tuple[Reply, Dict[str, Any]]:
+    """The reply, and the assistant message to append to the history as it came."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("choices"), list) \
+            or not payload["choices"]:
+        raise ProviderError("The provider returned no choices")
+    first = payload["choices"][0] if isinstance(payload["choices"][0], dict) else {}
+    message = first.get("message") if isinstance(first.get("message"), dict) else {}
+    calls: List[ToolCall] = []
+    for raw in message.get("tool_calls") or []:
+        function = raw.get("function") or {}
+        try:
+            arguments = json.loads(function.get("arguments") or "{}")
+            error = None if isinstance(arguments, dict) else "arguments were not an object"
+        except ValueError as exc:
+            arguments, error = {}, f"arguments were not valid JSON ({exc})"
+        calls.append(ToolCall(id=str(raw.get("id", "")), name=str(function.get("name", "")),
+                              arguments=arguments if isinstance(arguments, dict) else {},
+                              parse_error=error))
+    stop = _STOPS.get(first.get("finish_reason"), "other")
+    if calls and stop == "end":
+        # Some compatible servers say "stop" even when they called a tool.
+        stop = "tool_use"
+    if stop == "refusal":
+        raise ProviderError("The provider's content filter declined this request")
+    text = message.get("content")
+    text = text.strip() if isinstance(text, str) else ""
+
+    usage = payload.get("usage") if isinstance(payload.get("usage"), dict) else {}
+
+    def count(key: str) -> int:
+        try:
+            return int(usage.get(key, 0) or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    input_tokens, output_tokens = count("prompt_tokens"), count("completion_tokens")
+    if not (input_tokens or output_tokens):
+        # Some servers report only a total; counted as input, the cheaper side, so the
+        # estimate errs low rather than inventing spend.
+        input_tokens = count("total_tokens")
+    # What goes back into the history: role, content and tool calls, nothing else a
+    # server might reject on the way back in.
+    echoed: Dict[str, Any] = {"role": "assistant", "content": message.get("content")}
+    if message.get("tool_calls"):
+        echoed["tool_calls"] = message["tool_calls"]
+    return Reply(text=text, tool_calls=calls, stop=stop,
+                 usage=Usage(input_tokens=input_tokens, output_tokens=output_tokens),
+                 model=model, provider_type=provider_type), echoed
diff --git a/backend/app/providers/params.py b/backend/app/providers/params.py
new file mode 100644
index 0000000..72a3219
--- /dev/null
+++ b/backend/app/providers/params.py
@@ -0,0 +1,45 @@
+"""A provider's stored `extra_params`, decoded into something safe to merge.
+
+The blob is the user's escape hatch for whatever their model wants — `temperature`,
+`top_p`, a vendor-specific knob this app has never heard of — which is the whole point
+of it being free-form JSON. What it must never do is reach the keys the client builds
+itself: a blob that sets `messages` or `model` does not tune a request, it replaces one.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+# Request-body keys the clients construct. Stripped before the merge, so the blob can
+# only ever add optional parameters. `stream` is here because every client in this
+# package is deliberately non-streaming and a blob that turned streaming on would get a
+# response body none of them can parse.
+PROTECTED_KEYS = frozenset(
+    {
+        "model",
+        "max_tokens",
+        "messages",
+        "system",
+        "tools",
+        "stream",
+        "stream_options",
+    }
+)
+
+
+def parse_extra_params(raw: Optional[str]) -> dict[str, Any]:
+    """Decode the stored JSON text. Anything unusable reads as "none set".
+
+    Not an error: a blob written by an older version, or by hand, should cost the user a
+    tuning parameter rather than the whole turn.
+    """
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except (TypeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if k not in PROTECTED_KEYS}
diff --git a/backend/app/routers/providers.py b/backend/app/routers/providers.py
new file mode 100644
index 0000000..47ff2d6
--- /dev/null
+++ b/backend/app/routers/providers.py
@@ -0,0 +1,360 @@
+"""CRUD over the chat LLM providers a user has configured for the assistant.
+
+Copied from GAM's `app/routers/providers.py`: per user, at most one active, the key going
+out only as `api_key_configured`, and `POST /test` so a key and a model can be checked
+before a turn exists to fail on them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from sqlmodel import Session, select
+
+from app.auth import CurrentUser, decrypt_api_key, encrypt_api_key
+from app.database import get_session
+from app.models.provider import AIProvider
+from app.providers import (
+    CHECKED_BASE_URL_TYPES,
+    PROVIDER_ANTHROPIC,
+    PROVIDER_OLLAMA,
+    PROVIDER_TYPES,
+)
+from app.providers.endpoints import (
+    OLLAMA_BASE,
+    anthropic_base,
+    anthropic_headers,
+    openai_compat_base,
+)
+from app.safe_url import require_safe_external_url
+from app.schemas import DataResponse, ListResponse
+from app.schemas_providers import (
+    AIProviderCreate,
+    AIProviderRead,
+    AIProviderTest,
+    AIProviderUpdate,
+    ProviderTestResult,
+)
+from app.clock import utcnow
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Short on purpose. This is a reachability check a user is watching a spinner for, not a
+# real completion — a provider that cannot answer in ten seconds has failed the question
+# being asked.
+PROBE_TIMEOUT = httpx.Timeout(10.0)
+
+# The smallest exchange that still proves the credentials, the route and the model name.
+PROBE_BODY = {"max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}
+
+
+def _serialise(provider: AIProvider) -> AIProviderRead:
+    """The row as the browser sees it: everything except the credential."""
+    data = AIProviderRead.model_validate(provider)
+    data.api_key_configured = bool(provider.api_key)
+    return data
+
+
+def _require_known_type(provider_type: str) -> None:
+    if provider_type not in PROVIDER_TYPES:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={
+                "code": "bad_request",
+                "message": f"Unknown provider type: {provider_type}",
+            },
+        )
+
+
+def _check_base_url(provider_type: str, base_url: Optional[str]) -> None:
+    """SSRF-check a base URL, for the types whose base URL is actually fetched.
+
+    `anthropic` and `deepseek` resolve to fixed managed endpoints and never read the
+    stored value, and `ollama` is deliberately allowed to be a private address.
+    """
+    if base_url and provider_type in CHECKED_BASE_URL_TYPES:
+        require_safe_external_url(base_url)
+
+
+def _owned(session: Session, provider_id: str, user_id: str) -> AIProvider:
+    provider = session.get(AIProvider, provider_id)
+    if not provider or provider.user_id != user_id:
+        # 404 rather than 403 for someone else's row: whether a provider id exists is
+        # not a question this API answers for people who do not own it.
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"code": "not_found", "message": "No such provider"},
+        )
+    return provider
+
+
+def _deactivate_others(session: Session, user_id: str, keep: Optional[str]) -> None:
+    """At most one active provider per user."""
+    others = session.exec(select(AIProvider).where(AIProvider.user_id == user_id)).all()
+    for other in others:
+        if other.id != keep and other.is_active:
+            other.is_active = False
+            other.updated_at = utcnow()
+            session.add(other)
+
+
+@router.get("", response_model=ListResponse[AIProviderRead])
+def list_providers(
+    user: CurrentUser, session: Session = Depends(get_session)
+) -> ListResponse[AIProviderRead]:
+    providers = session.exec(
+        select(AIProvider)
+        .where(AIProvider.user_id == user.id)
+        .order_by(AIProvider.created_at)
+    ).all()
+    return ListResponse(
+        data=[_serialise(p) for p in providers],
+        total=len(providers),
+        limit=len(providers),
+        offset=0,
+    )
+
+
+@router.post("", response_model=DataResponse[AIProviderRead], status_code=201)
+def create_provider(
+    payload: AIProviderCreate,
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+) -> DataResponse[AIProviderRead]:
+    _require_known_type(payload.provider_type)
+    _check_base_url(payload.provider_type, payload.base_url)
+
+    provider = AIProvider(
+        user_id=user.id,
+        name=payload.name,
+        provider_type=payload.provider_type,
+        api_key=encrypt_api_key(payload.api_key) if payload.api_key else "",
+        base_url=payload.base_url or None,
+        model=payload.model,
+        max_tokens=payload.max_tokens,
+        supports_images=payload.supports_images,
+        use_anthropic_api=payload.use_anthropic_api,
+        extra_params=json.dumps(payload.extra_params) if payload.extra_params else None,
+        enabled=payload.enabled,
+        is_active=payload.is_active,
+    )
+
+    if payload.is_active:
+        _deactivate_others(session, user.id, keep=None)
+
+    session.add(provider)
+    session.commit()
+    session.refresh(provider)
+    return DataResponse(data=_serialise(provider))
+
+
+@router.put("/{provider_id}", response_model=DataResponse[AIProviderRead])
+def update_provider(
+    provider_id: str,
+    payload: AIProviderUpdate,
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+) -> DataResponse[AIProviderRead]:
+    provider = _owned(session, provider_id, user.id)
+
+    if payload.provider_type is not None:
+        _require_known_type(payload.provider_type)
+
+    # Validated before anything is stored, and against the type this request results in
+    # rather than the one already on the row — otherwise changing only the URL, or
+    # changing the type and the URL together, skips the check that the stored URL is
+    # what a later request will be sent to.
+    effective_type = payload.provider_type or provider.provider_type
+    _check_base_url(effective_type, payload.base_url)
+
+    for field in (
+        "name",
+        "provider_type",
+        "base_url",
+        "model",
+        "max_tokens",
+        "supports_images",
+        "use_anthropic_api",
+        "enabled",
+        "is_active",
+    ):
+        value = getattr(payload, field)
+        if value is not None:
+            setattr(provider, field, value)
+
+    # A dict on the wire, JSON text in the column; {} clears it.
+    if payload.extra_params is not None:
+        provider.extra_params = (
+            json.dumps(payload.extra_params) if payload.extra_params else None
+        )
+
+    # None leaves the stored key alone — the browser never had it to send back. "" is
+    # the only way to remove one, so it has to be distinguishable from "unchanged".
+    if payload.api_key is not None:
+        provider.api_key = encrypt_api_key(payload.api_key) if payload.api_key else ""
+
+    if payload.is_active:
+        _deactivate_others(session, user.id, keep=provider.id)
+
+    provider.updated_at = utcnow()
+    session.add(provider)
+    session.commit()
+    session.refresh(provider)
+    return DataResponse(data=_serialise(provider))
+
+
+# response_model=None alongside the `-> None` annotation: FastAPI infers a response
+# model from the return type, and NoneType is a type like any other, so it would try to
+# give a 204 a body and refuse at import time. Same as app/routers/tags.py.
+@router.delete(
+    "/{provider_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    response_model=None,
+    response_class=Response,
+)
+def delete_provider(
+    provider_id: str,
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+) -> None:
+    provider = _owned(session, provider_id, user.id)
+    session.delete(provider)
+    session.commit()
+
+
+@router.post("/{provider_id}/activate", response_model=DataResponse[AIProviderRead])
+def activate_provider(
+    provider_id: str,
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+) -> DataResponse[AIProviderRead]:
+    provider = _owned(session, provider_id, user.id)
+
+    _deactivate_others(session, user.id, keep=provider.id)
+    provider.is_active = True
+    provider.updated_at = utcnow()
+    session.add(provider)
+    session.commit()
+    session.refresh(provider)
+    return DataResponse(data=_serialise(provider))
+
+
+def _probe_result(status_code: int) -> ProviderTestResult:
+    """Read an HTTP status as an answer about reachability, not about the probe body.
+
+    400 counts as success: the endpoint answered, which means the URL and the credential
+    were both accepted — it is the ten-token message it did not like, and that is not the
+    question. 401/403/404 are the ones that mean the configuration is wrong.
+    """
+    if status_code in (200, 400):
+        return ProviderTestResult(success=True, message="Connected")
+    if status_code in (401, 403):
+        return ProviderTestResult(success=False, message="The API key was rejected")
+    if status_code == 404:
+        return ProviderTestResult(
+            success=False, message="No such model, or the wrong address"
+        )
+    if status_code == 429:
+        return ProviderTestResult(
+            success=False, message="Rate limited or out of quota"
+        )
+    return ProviderTestResult(success=False, message=f"The provider returned HTTP {status_code}")
+
+
+@router.post("/test", response_model=DataResponse[ProviderTestResult])
+def test_provider(
+    payload: AIProviderTest,
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+) -> DataResponse[ProviderTestResult]:
+    """Ask the provider a ten-token question and report whether it answered.
+
+    Synchronous `httpx`: FastAPI runs a sync endpoint in a threadpool, so this blocks a
+    worker thread and not the event loop.
+    """
+    _require_known_type(payload.provider_type)
+
+    api_key = payload.api_key
+    base_url = payload.base_url
+    if payload.provider_id:
+        saved = _owned(session, payload.provider_id, user.id)
+        # Re-testing a saved provider must not require the key again: the browser was
+        # never given it, so it has nothing to send.
+        api_key = decrypt_api_key(saved.api_key)
+        base_url = base_url or saved.base_url
+
+    # A provider that speaks the Anthropic protocol is tested against THAT endpoint
+    # whatever its type — otherwise a DeepSeek provider on api.deepseek.com/anthropic
+    # would be tested against the OpenAI-compatible endpoint it no longer uses, and
+    # report a result for the wrong URL entirely.
+    speaks_anthropic = (
+        payload.provider_type == PROVIDER_ANTHROPIC or payload.use_anthropic_api
+    )
+
+    probe = AIProvider(
+        user_id=user.id,
+        name="probe",
+        provider_type=payload.provider_type,
+        base_url=base_url,
+        model=payload.model,
+        use_anthropic_api=payload.use_anthropic_api,
+    )
+
+    try:
+        if speaks_anthropic:
+            target = anthropic_base(probe)
+            # gecko-notes checks the OpenAI-compatible branch and not this one, which
+            # leaves a `custom` provider's payload-supplied base_url going straight into
+            # an outbound POST. Check whatever is about to be fetched, on both paths.
+            _check_base_url(payload.provider_type, base_url)
+            response = httpx.post(
+                f"{target}/v1/messages",
+                headers=anthropic_headers(api_key, payload.provider_type),
+                json={"model": payload.model, **PROBE_BODY},
+                timeout=PROBE_TIMEOUT,
+            )
+        elif payload.provider_type == PROVIDER_OLLAMA:
+            # The one base URL allowed to be private, and the one provider with no
+            # credential to check, so "is it running" is the whole question. (Whether
+            # the model can call tools is only learnt on the first turn.)
+            target = (base_url or OLLAMA_BASE).rstrip("/")
+            response = httpx.get(f"{target}/api/tags", timeout=PROBE_TIMEOUT)
+            return DataResponse(
+                data=ProviderTestResult(success=True, message="Ollama is reachable")
+                if response.status_code == 200
+                else ProviderTestResult(
+                    success=False, message=f"Ollama returned HTTP {response.status_code}"
+                )
+            )
+        else:
+            target = openai_compat_base(payload.provider_type, base_url)
+            _check_base_url(payload.provider_type, base_url)
+            response = httpx.post(
+                f"{target}/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "content-type": "application/json",
+                },
+                json={"model": payload.model, **PROBE_BODY},
+                timeout=PROBE_TIMEOUT,
+            )
+    except HTTPException:
+        raise
+    except httpx.TimeoutException:
+        return DataResponse(
+            data=ProviderTestResult(success=False, message="The provider did not respond in time")
+        )
+    except httpx.HTTPError as exc:
+        # The URL and the exception text can both carry the key; log neither.
+        logger.warning("Provider probe failed: %s", type(exc).__name__)
+        return DataResponse(
+            data=ProviderTestResult(success=False, message="Could not reach that address")
+        )
+
+    return DataResponse(data=_probe_result(response.status_code))
diff --git a/backend/app/routers/usage.py b/backend/app/routers/usage.py
new file mode 100644
index 0000000..e9517cd
--- /dev/null
+++ b/backend/app/routers/usage.py
@@ -0,0 +1,62 @@
+"""What the assistant has spent, overall and per project.
+
+Every figure is a list-price estimate (`usage/pricing.py`), and the response says so in
+`estimated`, which the frontend is required to show.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlmodel import Session
+
+from app.auth import CurrentUser
+from app.database import get_session
+from app.schemas import DataResponse
+from app.services import projects as project_service
+from app.usage import events as usage_events
+
+router = APIRouter()
+
+
+class ProviderTotal(BaseModel):
+    provider: str
+    model: str
+    events: int
+    units: int
+    cost: Optional[float] = None
+
+
+class UsageTotals(BaseModel):
+    total_events: int
+    # Fewer than `total_events` means some calls could not be priced, so `cost` is a
+    # floor rather than the whole story.
+    priced_events: int
+    cost: float
+    currency: str
+    estimated: bool
+    tokens: int
+
+
+class UsageSummary(BaseModel):
+    totals: UsageTotals
+    by_provider: list[ProviderTotal]
+
+
+@router.get("", response_model=DataResponse[UsageSummary])
+def read_usage(user: CurrentUser, session: Session = Depends(get_session)) -> DataResponse[UsageSummary]:
+    return DataResponse(data=UsageSummary(
+        totals=UsageTotals(**usage_events.totals_for(session, user.id)),
+        by_provider=[ProviderTotal(**row) for row in usage_events.by_provider(session, user.id)],
+    ))
+
+
+@router.get("/projects/{project_id}", response_model=DataResponse[UsageTotals])
+def read_project_usage(project_id: str, user: CurrentUser,
+                       session: Session = Depends(get_session)) -> DataResponse[UsageTotals]:
+    # Checked rather than trusted: a project id that is not yours should not be a way
+    # to learn that it exists.
+    project_service.get_owned(session, user, project_id)
+    return DataResponse(data=UsageTotals(**usage_events.totals_for(session, user.id, project_id)))
diff --git a/backend/app/safe_url.py b/backend/app/safe_url.py
new file mode 100644
index 0000000..053104d
--- /dev/null
+++ b/backend/app/safe_url.py
@@ -0,0 +1,81 @@
+"""Refuse a user-supplied URL that points back inside the network.
+
+Anywhere this app is handed a URL and later fetches it, the user chooses the
+destination — so "the internet" is not the only place it can reach. A base URL of
+`https://169.254.169.254/` or `https://10.0.0.5:8080/` turns an outbound request into a
+read of whatever the container can see that the browser cannot.
+
+Copied from GAM, which ported it from gecko-notes' `_require_safe_external_url` and
+added the DNS check. Kept at the app root rather than inside `app/providers/`: it is not
+about providers.
+
+Two exceptions are deliberate and live at the call sites, not here:
+- Ollama's base URL is allowed to be private. It is a local daemon; that is the point.
+- `anthropic` and `deepseek` resolve to fixed managed endpoints, so their stored
+  base_url is never fetched at all (see app.providers.endpoints).
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+import urllib.parse
+
+from fastapi import HTTPException, status
+
+
+def _reject(code: str, message: str) -> None:
+    raise HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail={"code": code, "message": message},
+    )
+
+
+def _is_safe_address(host: str) -> bool:
+    """Whether a literal IP is routable on the public internet.
+
+    `is_global` is False for loopback, link-local, private and reserved ranges, which is
+    exactly the set worth refusing, and it stays correct for IPv6 without a second list.
+    """
+    return ipaddress.ip_address(host).is_global
+
+
+def require_safe_external_url(url: str) -> None:
+    """Raise unless `url` is https and resolves somewhere public."""
+    parsed = urllib.parse.urlparse(url)
+
+    if parsed.scheme != "https":
+        _reject("invalid_url", "The address must start with https://")
+
+    hostname = (parsed.hostname or "").lower()
+    if not hostname:
+        _reject("invalid_url", "That address has no hostname")
+
+    try:
+        if not _is_safe_address(hostname):
+            _reject("ssrf_blocked", "The address must point to a public host")
+        return
+    except ValueError:
+        pass  # a name, not a literal address — resolve it below
+
+    if hostname == "localhost" or hostname.endswith(".localhost"):
+        _reject("ssrf_blocked", "The address must point to a public host")
+
+    # gecko-notes stops at the literal-IP check, which leaves the interesting case open:
+    # a name the attacker controls that resolves to 127.0.0.1 passes it untouched. So
+    # resolve and check every address the name answers with.
+    try:
+        resolved = socket.getaddrinfo(hostname, None)
+    except (socket.gaierror, UnicodeError):
+        # Deliberately not a rejection. A name that cannot be resolved here may resolve
+        # perfectly well later (split-horizon DNS, a temporarily unreachable resolver),
+        # and refusing to *save* a setting because of a transient lookup failure is a
+        # worse failure than letting the eventual request fail on its own merits. This
+        # is defence in depth, not the only line of it.
+        return
+
+    for family, _type, _proto, _canonname, sockaddr in resolved:
+        if family not in (socket.AF_INET, socket.AF_INET6):
+            continue
+        if not _is_safe_address(sockaddr[0]):
+            _reject("ssrf_blocked", "The address must point to a public host")
diff --git a/backend/app/schemas_providers.py b/backend/app/schemas_providers.py
new file mode 100644
index 0000000..b20d2d1
--- /dev/null
+++ b/backend/app/schemas_providers.py
@@ -0,0 +1,105 @@
+"""Wire shapes for the AI provider CRUD, copied from GAM.
+
+The rule this file exists to enforce: a stored key goes out of here as a boolean
+(`api_key_configured`) and never as a string. Redacting it to `""` instead, as
+gecko-notes does, is indistinguishable from "no key set".
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AIProviderRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True, protected_namespaces=())
+
+    id: str
+    name: str
+    provider_type: str
+    base_url: Optional[str] = None
+    model: str
+    max_tokens: int
+    supports_images: bool
+    use_anthropic_api: bool
+    extra_params: Optional[dict[str, Any]] = None
+    enabled: bool
+    is_active: bool
+    # Derived in the router from the stored column, which is never serialised.
+    api_key_configured: bool = False
+
+    @field_validator("extra_params", mode="before")
+    @classmethod
+    def _decode_extra_params(cls, value: Any) -> Any:
+        """JSON-as-TEXT in the column, a dict on the wire.
+
+        Unreadable text reads as "nothing configured" rather than raising: a row written
+        by an older version should not make the whole settings screen 500.
+        """
+        if isinstance(value, str):
+            try:
+                decoded = json.loads(value)
+            except ValueError:
+                return None
+            return decoded if isinstance(decoded, dict) else None
+        return value
+
+
+class AIProviderCreate(BaseModel):
+    model_config = ConfigDict(protected_namespaces=())
+
+    name: str = Field(min_length=1, max_length=200)
+    provider_type: str
+    api_key: str = ""
+    base_url: Optional[str] = None
+    model: str = Field(min_length=1, max_length=200)
+    max_tokens: int = Field(default=16384, ge=1, le=200000)
+    supports_images: bool = False
+    use_anthropic_api: bool = False
+    extra_params: Optional[dict[str, Any]] = None
+    enabled: bool = True
+    is_active: bool = False
+
+
+class AIProviderUpdate(BaseModel):
+    model_config = ConfigDict(protected_namespaces=())
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200)
+    provider_type: Optional[str] = None
+    # Three-state, the same contract as every other credential in this app: None leaves
+    # the stored key alone, "" removes it, anything else replaces it. gecko-notes writes
+    # only on a truthy value, which is why a key can never be cleared there.
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    model: Optional[str] = Field(default=None, min_length=1, max_length=200)
+    max_tokens: Optional[int] = Field(default=None, ge=1, le=200000)
+    supports_images: Optional[bool] = None
+    use_anthropic_api: Optional[bool] = None
+    extra_params: Optional[dict[str, Any]] = None
+    enabled: Optional[bool] = None
+    is_active: Optional[bool] = None
+
+
+class AIProviderTest(BaseModel):
+    """A connection probe, for a saved provider or for an unsaved form.
+
+    `provider_id` names a saved row whose stored key should be used — so the screen can
+    re-test a provider without asking the user to paste the key again, which it could not
+    do anyway since it never received it.
+    """
+
+    model_config = ConfigDict(protected_namespaces=())
+
+    provider_id: Optional[str] = None
+    provider_type: str
+    api_key: str = ""
+    base_url: Optional[str] = None
+    model: str = Field(min_length=1, max_length=200)
+    use_anthropic_api: bool = False
+
+
+class ProviderTestResult(BaseModel):
+    success: bool
+    message: str
diff --git a/backend/app/usage/__init__.py b/backend/app/usage/__init__.py
new file mode 100644
index 0000000..1e7cf91
--- /dev/null
+++ b/backend/app/usage/__init__.py
@@ -0,0 +1 @@
+"""Cost visibility: what was spent, and how confident the figure is."""
diff --git a/backend/app/usage/events.py b/backend/app/usage/events.py
new file mode 100644
index 0000000..6c33930
--- /dev/null
+++ b/backend/app/usage/events.py
@@ -0,0 +1,86 @@
+"""Recording what a call consumed, and reading it back as totals.
+
+Copied from GAM's `app/usage/events.py`, attributed to projects and assistant turns
+instead of assets. Best-effort by design: a failure to write a usage row must never fail
+the work that produced it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from sqlmodel import Session, func, select
+
+from app.models.usage import KIND_AI, UNIT_TOKENS, UsageEvent
+from app.usage import pricing
+
+logger = logging.getLogger(__name__)
+
+
+def record_reply(session: Session, *, user_id: str, project_id: Optional[str],
+                 turn_id: Optional[str], reply) -> Optional[float]:
+    """Record one LLM call from the `Reply` its provider returned. Never raises.
+
+    Returns the estimated cost (None when it cannot be priced), so the turn can keep a
+    running total without reading the rows back.
+    """
+    try:
+        tokens_in, tokens_out = reply.usage.input_tokens, reply.usage.output_tokens
+        if tokens_in + tokens_out <= 0:
+            # A provider that reported nothing. A zero-token row would suggest a free
+            # call rather than an unmeasured one.
+            return None
+        estimate = pricing.cost_for(reply.provider_type, reply.model, tokens_in, tokens_out)
+        session.add(UsageEvent(
+            user_id=user_id, project_id=project_id, turn_id=turn_id, kind=KIND_AI,
+            provider=reply.provider_type, model=reply.model or "",
+            units=tokens_in + tokens_out, unit_type=UNIT_TOKENS,
+            cost=estimate[0] if estimate else None, currency=estimate[1] if estimate else None,
+            cost_estimated=True if estimate else None,
+        ))
+        session.commit()
+        return estimate[0] if estimate else None
+    except Exception:  # noqa: BLE001 - accounting must not break the work it measures
+        logger.warning("Could not record usage for %s", user_id, exc_info=True)
+        session.rollback()
+        return None
+
+
+def totals_for(session: Session, user_id: str, project_id: Optional[str] = None) -> dict:
+    """What has been spent, overall or on one project.
+
+    `priced_events` and `total_events` are reported apart on purpose: when they differ,
+    some calls could not be priced, and a total that silently left them out would read
+    as complete.
+    """
+    where = [UsageEvent.user_id == user_id]
+    if project_id is not None:
+        where.append(UsageEvent.project_id == project_id)
+    rows = session.exec(select(UsageEvent).where(*where)).all()
+    priced = [r for r in rows if r.cost is not None]
+    return {
+        "total_events": len(rows),
+        "priced_events": len(priced),
+        "cost": round(sum(r.cost or 0.0 for r in priced), 6) if priced else 0.0,
+        "currency": next((r.currency for r in priced if r.currency), "USD"),
+        "estimated": True,
+        "tokens": sum(r.units for r in rows if r.unit_type == UNIT_TOKENS),
+    }
+
+
+def by_provider(session: Session, user_id: str) -> list[dict]:
+    """Spend grouped by provider and model, biggest first."""
+    rows = session.exec(
+        select(UsageEvent.provider, UsageEvent.model, func.count(UsageEvent.id),
+               func.sum(UsageEvent.units), func.sum(UsageEvent.cost))
+        .where(UsageEvent.user_id == user_id)
+        .group_by(UsageEvent.provider, UsageEvent.model)
+    ).all()
+    grouped = [
+        {"provider": provider or "unknown", "model": model or "", "events": int(events or 0),
+         "units": int(units or 0), "cost": round(float(cost), 6) if cost is not None else None}
+        for provider, model, events, units, cost in rows
+    ]
+    grouped.sort(key=lambda g: (g["cost"] or 0.0), reverse=True)
+    return grouped
diff --git a/backend/app/usage/pricing.py b/backend/app/usage/pricing.py
new file mode 100644
index 0000000..38546d9
--- /dev/null
+++ b/backend/app/usage/pricing.py
@@ -0,0 +1,100 @@
+"""List-price estimates for LLM token costs, in USD per 1,000,000 tokens.
+
+These are published list prices, used only to *estimate* what an assistant turn cost.
+They are **not** billing figures: providers change prices and offer cache and volume
+discounts this table does not model. Every cost derived here is stored with
+`cost_estimated=True`, and nothing in the app may show a figure without saying so.
+
+Copied from GAM (ported from gecko-notes' `backend/app/pricing.py`), with the Claude
+table brought up to date. Ollama is free and `custom` unpriced, for the reasons given there.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+# provider_type -> [(model-id substring, input $/1M, output $/1M), ...].
+#
+# Checked in order and the first substring *contained in* the model id wins, so the more
+# specific ids come before their shorter prefixes — "claude-3-5-haiku" has to be tested
+# before "claude-haiku" or it would never match. Each family ends in a catch-all, so a
+# model released after this table was written still gets a figure of the right order of
+# magnitude rather than none at all.
+_PRICES: dict[str, List[Tuple[str, float, float]]] = {
+    "anthropic": [
+        ("claude-fable-5", 10.0, 50.0),
+        ("claude-mythos-5", 10.0, 50.0),
+        ("claude-opus-5-5", 4.0, 20.0),
+        ("claude-opus-5", 5.0, 25.0),
+        ("claude-opus-4-8", 5.0, 25.0),
+        ("claude-opus-4-7", 5.0, 25.0),
+        ("claude-opus-4-6", 5.0, 25.0),
+        ("claude-opus-4-5", 5.0, 25.0),
+        ("claude-opus-4-1", 15.0, 75.0),
+        ("claude-opus-4-0", 15.0, 75.0),
+        ("claude-opus", 5.0, 25.0),
+        ("claude-sonnet-5", 2.0, 10.0),
+        ("claude-sonnet", 3.0, 15.0),
+        ("claude-3-7-sonnet", 3.0, 15.0),
+        ("claude-3-5-sonnet", 3.0, 15.0),
+        ("claude-haiku-5", 0.10, 0.50),
+        ("claude-haiku-4", 1.0, 5.0),
+        ("claude-3-5-haiku", 0.80, 4.0),
+        ("claude-3-haiku", 0.25, 1.25),
+        ("claude-haiku", 1.0, 5.0),
+        ("claude", 4.0, 20.0),  # unknown Claude model: assume the current Opus tier
+    ],
+    "openai": [
+        ("gpt-4o-mini", 0.15, 0.60),
+        ("gpt-4o", 2.50, 10.0),
+        ("gpt-4.1-nano", 0.10, 0.40),
+        ("gpt-4.1-mini", 0.40, 1.60),
+        ("gpt-4.1", 2.0, 8.0),
+        ("gpt-4-turbo", 10.0, 30.0),
+        ("gpt-4", 30.0, 60.0),
+        ("gpt-3.5", 0.50, 1.50),
+        ("o4-mini", 1.10, 4.40),
+        ("o3-mini", 1.10, 4.40),
+        ("o3", 2.0, 8.0),
+        ("o1-mini", 1.10, 4.40),
+        ("o1", 15.0, 60.0),
+        ("gpt", 2.50, 10.0),  # unknown GPT model — assume 4o-tier
+    ],
+    # DeepSeek's standard (cache-miss) list prices. Its cache-hit discount is real and
+    # substantial and is not modelled here, which is one more reason these are estimates.
+    "deepseek": [
+        ("deepseek-reasoner", 0.55, 2.19),
+        ("deepseek-chat", 0.27, 1.10),
+        ("deepseek", 0.27, 1.10),  # unknown DeepSeek model — assume chat-tier
+    ],
+}
+
+
+def cost_for(
+    provider_type: Optional[str],
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+) -> Optional[Tuple[float, str]]:
+    """Estimate (cost, currency) for one LLM call, or None when no estimate is possible.
+
+    None rather than zero for an unknown family or a `custom` endpoint: a stored 0.0
+    reads as "this was free", which is a different and wrong claim. Ollama genuinely is
+    free — it runs on the user's own machine — so it returns an honest zero.
+    """
+    kind = (provider_type or "").lower()
+    if kind == "ollama":
+        return (0.0, "USD")
+
+    table = _PRICES.get(kind)
+    if not table:
+        return None
+
+    needle_in = (model or "").lower()
+    for needle, input_price, output_price in table:
+        if needle in needle_in:
+            cost = (input_tokens / 1_000_000.0) * input_price + (
+                output_tokens / 1_000_000.0
+            ) * output_price
+            return (round(cost, 6), "USD")
+    return None
diff --git a/backend/tests/test_build_provider.py b/backend/tests/test_build_provider.py
new file mode 100644
index 0000000..f0537a9
--- /dev/null
+++ b/backend/tests/test_build_provider.py
@@ -0,0 +1,141 @@
+"""Choosing which client speaks to which row.
+
+The decision keys off the protocol, never the vendor name — which is the whole reason
+`speaks_anthropic` exists in one place — so these are the cases that would otherwise be
+re-derived wrongly in each job.
+"""
+
+from app.auth import encrypt_api_key
+from app.models.provider import AIProvider
+from app.providers import build_provider
+from app.providers.anthropic import AnthropicProvider
+from app.providers.openai import OpenAIProvider
+
+USER = "user-under-test"
+
+
+def add(session, **overrides) -> AIProvider:
+    fields = {
+        "user_id": USER,
+        "name": "Configured",
+        "provider_type": "anthropic",
+        "model": "claude-sonnet-4-20250514",
+        "api_key": encrypt_api_key("sk-secret"),
+        "is_active": True,
+        "enabled": True,
+    }
+    fields.update(overrides)
+    provider = AIProvider(**fields)
+    session.add(provider)
+    session.commit()
+    return provider
+
+
+def test_no_provider_reads_as_none_not_an_error(session):
+    """A library with no provider is not broken — it simply cannot be enriched yet, and
+    everything else about it still works. Same contract as build_embedder."""
+    assert build_provider(session, USER) is None
+
+
+def test_a_row_that_is_not_active_is_not_used(session):
+    add(session, is_active=False)
+
+    assert build_provider(session, USER) is None
+
+
+def test_a_disabled_row_is_not_used_even_when_active(session):
+    """`enabled` is the user saying "not this one for now" without deleting it."""
+    add(session, enabled=False)
+
+    assert build_provider(session, USER) is None
+
+
+def test_another_users_provider_is_not_borrowed(session):
+    add(session, user_id="somebody-else")
+
+    assert build_provider(session, USER) is None
+
+
+def test_an_anthropic_row_speaks_messages(session):
+    add(session)
+
+    client = build_provider(session, USER)
+
+    assert isinstance(client, AnthropicProvider)
+    assert client.model == "claude-sonnet-4-20250514"
+    assert client.provider_type == "anthropic"
+
+
+def test_a_deepseek_row_with_the_flag_speaks_messages(session):
+    add(session, provider_type="deepseek", model="deepseek-chat", use_anthropic_api=True)
+
+    assert isinstance(build_provider(session, USER), AnthropicProvider)
+
+
+def test_the_same_row_without_the_flag_speaks_openai(session):
+    add(session, provider_type="deepseek", model="deepseek-chat")
+
+    assert isinstance(build_provider(session, USER), OpenAIProvider)
+
+
+def test_ollama_never_takes_the_messages_path(session):
+    """Its address is the one this app allows to be private, so honouring the flag
+    would aim a Messages request at an internal host."""
+    add(session, provider_type="ollama", model="llama3.2", api_key="", use_anthropic_api=True)
+
+    # Ollama is served by the OpenAI-protocol client, over its /v1 endpoint.
+    assert isinstance(build_provider(session, USER), OpenAIProvider)
+
+
+def test_ollama_needs_no_key(session):
+    add(session, provider_type="ollama", model="llama3.2", api_key="")
+
+    assert build_provider(session, USER) is not None
+
+
+def test_every_other_type_needs_one(session):
+    """A keyless hosted provider would 401 on every turn."""
+    add(session, provider_type="openai", model="gpt-4o", api_key="")
+
+    assert build_provider(session, USER) is None
+
+
+def test_a_key_that_no_longer_decrypts_reads_as_unconfigured(session):
+    """JWT_SECRET_KEY rotated under the row. The settings screen already reports the
+    key as missing; this makes the assistant agree with it."""
+    add(session, api_key="enc:this-is-not-a-valid-fernet-token")
+
+    assert build_provider(session, USER) is None
+
+
+def test_the_active_row_wins_over_the_others(session):
+    add(session, name="Old", provider_type="openai", model="gpt-4o", is_active=False)
+    add(session, name="Current", provider_type="ollama", model="llama3.2", api_key="", is_active=True)
+
+    client = build_provider(session, USER)
+
+    assert isinstance(client, OpenAIProvider)
+    assert client.model == "llama3.2"
+
+
+def test_the_client_carries_the_stored_key(session, monkeypatch):
+    """Decrypted once here rather than in each job."""
+    import httpx
+
+    from app.providers import _upstream
+
+    seen = {}
+
+    def fake_post_json(url, *, headers=None, json_body, timeout, label, **kwargs):
+        seen.update(headers or {})
+        return httpx.Response(
+            200,
+            json={"content": [{"type": "text", "text": "ok"}], "usage": {}},
+        )
+
+    monkeypatch.setattr(_upstream, "post_json", fake_post_json)
+    add(session)
+
+    build_provider(session, USER).conversation(system=[], tools=[], history=[], prompt="Hi").ask()
+
+    assert seen["x-api-key"] == "sk-secret"
diff --git a/backend/tests/test_provider_conversations.py b/backend/tests/test_provider_conversations.py
new file mode 100644
index 0000000..050c9a7
--- /dev/null
+++ b/backend/tests/test_provider_conversations.py
@@ -0,0 +1,197 @@
+"""The tool-calling conversation each protocol client keeps, with the network faked.
+
+`_upstream.post_json` is replaced, as in GAM's provider tests: what matters is the body
+each client sends and how it reads what comes back, round after round.
+"""
+
+import json
+
+import httpx
+import pytest
+
+from app.models.provider import AIProvider
+from app.providers import _upstream
+from app.providers.anthropic import AnthropicProvider
+from app.providers.base import ProviderError, ToolResult, ToolSpec
+from app.providers.openai import OpenAIProvider
+
+SEARCH = ToolSpec(name="search_assets", description="Search GAM",
+                  parameters={"type": "object", "properties": {"query": {"type": "string"}},
+                              "required": ["query"]})
+
+
+@pytest.fixture
+def wire(monkeypatch):
+    """Queue replies; record every request."""
+    sent, queue = [], []
+
+    def fake(url, *, headers=None, json_body, timeout, label, **kwargs):
+        # A deep copy: the client appends to its history after the call, and the test
+        # wants what was on the wire at the time.
+        sent.append({"url": url, "headers": dict(headers or {}),
+                     "body": json.loads(json.dumps(json_body))})
+        return httpx.Response(200, json=queue.pop(0))
+
+    monkeypatch.setattr(_upstream, "post_json", fake)
+    return sent, queue
+
+
+def row(**overrides):
+    data = dict(user_id="u", name="Test", provider_type="anthropic", model="claude-opus-5-5",
+                max_tokens=16000)
+    data.update(overrides)
+    return AIProvider(**data)
+
+
+# ── Anthropic ────────────────────────────────────────────────────────────────
+
+THINKING = {"type": "thinking", "thinking": "", "signature": "sig-abc"}
+
+
+def test_an_anthropic_tool_loop_replays_the_assistant_turn_verbatim(wire):
+    sent, queue = wire
+    queue.append({
+        "content": [THINKING, {"type": "text", "text": "Searching."},
+                    {"type": "tool_use", "id": "t1", "name": "search_assets",
+                     "input": {"query": "water"}}],
+        "stop_reason": "tool_use",
+        "usage": {"input_tokens": 100, "output_tokens": 20, "cache_read_input_tokens": 900},
+    })
+    queue.append({"content": [{"type": "text", "text": "Found two clips."}],
+                  "stop_reason": "end_turn", "usage": {"input_tokens": 50, "output_tokens": 10}})
+
+    chat = AnthropicProvider(row(), "sk").conversation(
+        system=["REFERENCE", "PROJECT"], tools=[SEARCH],
+        history=[("user", "Hi"), ("assistant", "Hello")], prompt="Find water")
+    first = chat.ask()
+    assert first.stop == "tool_use"
+    assert [(c.id, c.name, c.arguments) for c in first.tool_calls] == [
+        ("t1", "search_assets", {"query": "water"})]
+    # Cache reads are billed input.
+    assert (first.usage.input_tokens, first.usage.output_tokens) == (1000, 20)
+
+    chat.answer([ToolResult("t1", '{"hits": 2}')])
+    second = chat.ask()
+    assert second.text == "Found two clips." and second.stop == "end"
+
+    body = sent[1]["body"]
+    assert sent[0]["url"] == "https://api.anthropic.com/v1/messages"
+    assert body["model"] == "claude-opus-5-5"
+    # Each system block a cache breakpoint; the conversation's end cached automatically.
+    assert [b["text"] for b in body["system"]] == ["REFERENCE", "PROJECT"]
+    assert all(b["cache_control"] == {"type": "ephemeral"} for b in body["system"])
+    assert body["cache_control"] == {"type": "ephemeral"}
+    assert body["tools"] == [{"name": "search_assets", "description": "Search GAM",
+                              "input_schema": SEARCH.parameters}]
+    # Nothing that current models reject.
+    assert "tool_choice" not in body and "thinking" not in body
+    roles = [m["role"] for m in body["messages"]]
+    assert roles == ["user", "assistant", "user", "assistant", "user"]
+    # The assistant's content exactly as it came, thinking block and signature included.
+    assert body["messages"][3]["content"][0] == THINKING
+    assert body["messages"][4]["content"] == [
+        {"type": "tool_result", "tool_use_id": "t1", "content": '{"hits": 2}'}]
+
+
+def test_every_result_goes_back_in_one_message_with_errors_flagged(wire):
+    sent, queue = wire
+    queue.append({"content": [{"type": "text", "text": "ok"}], "stop_reason": "end_turn",
+                  "usage": {}})
+    chat = AnthropicProvider(row(), "sk").conversation(system=[], tools=[SEARCH], history=[],
+                                                      prompt="x")
+    chat.answer([ToolResult("a", "fine"), ToolResult("b", "no such scene", is_error=True)])
+    chat.ask()
+    last = sent[0]["body"]["messages"][-1]
+    assert last["role"] == "user"
+    assert last["content"][1] == {"type": "tool_result", "tool_use_id": "b",
+                                  "content": "no such scene", "is_error": True}
+
+
+def test_a_compatible_gateway_gets_no_top_level_cache_field(wire):
+    sent, queue = wire
+    queue.append({"content": [{"type": "text", "text": "ok"}], "stop_reason": "end_turn"})
+    chat = AnthropicProvider(row(provider_type="deepseek", use_anthropic_api=True,
+                                 model="deepseek-chat"), "sk").conversation(
+        system=["R"], tools=[], history=[], prompt="x")
+    chat.ask()
+    assert sent[0]["url"] == "https://api.deepseek.com/anthropic/v1/messages"
+    assert "cache_control" not in sent[0]["body"]
+
+
+def test_back_to_back_user_turns_are_merged_rather_than_refused(wire):
+    sent, queue = wire
+    queue.append({"content": [{"type": "text", "text": "ok"}], "stop_reason": "end_turn"})
+    # A turn that failed before answering leaves two user messages in a row.
+    AnthropicProvider(row(), "sk").conversation(
+        system=[], tools=[], history=[("user", "first")], prompt="second").ask()
+    assert sent[0]["body"]["messages"] == [{"role": "user", "content": "first\n\nsecond"}]
+
+
+def test_a_refusal_is_an_error_naming_its_category(wire):
+    _, queue = wire
+    queue.append({"content": [], "stop_reason": "refusal", "stop_details": {"category": "cyber"}})
+    with pytest.raises(ProviderError, match="declined.*cyber"):
+        AnthropicProvider(row(), "sk").conversation(system=[], tools=[], history=[],
+                                                    prompt="x").ask()
+
+
+# ── OpenAI-compatible ────────────────────────────────────────────────────────
+
+def test_an_openai_tool_loop(wire):
+    sent, queue = wire
+    queue.append({"choices": [{"finish_reason": "tool_calls", "message": {
+        "role": "assistant", "content": None, "tool_calls": [
+            {"id": "c1", "type": "function",
+             "function": {"name": "search_assets", "arguments": '{"query": "water"}'}},
+            {"id": "c2", "type": "function",
+             "function": {"name": "search_assets", "arguments": "{not json"}}]}}],
+        "usage": {"prompt_tokens": 70, "completion_tokens": 9}})
+    queue.append({"choices": [{"finish_reason": "stop",
+                               "message": {"role": "assistant", "content": "Done."}}]})
+
+    chat = OpenAIProvider(row(provider_type="openai", model="gpt-4.1"), "sk").conversation(
+        system=["REFERENCE", "PROJECT"], tools=[SEARCH], history=[], prompt="Find water")
+    first = chat.ask()
+    assert first.stop == "tool_use"
+    assert first.tool_calls[0].arguments == {"query": "water"}
+    # Unparseable arguments are kept as an error to hand back, never executed.
+    assert first.tool_calls[1].parse_error and first.tool_calls[1].arguments == {}
+    chat.answer([ToolResult("c1", "2 hits"), ToolResult("c2", "bad arguments", is_error=True)])
+    assert chat.ask().text == "Done."
+
+    body = sent[1]["body"]
+    assert sent[0]["url"] == "https://api.openai.com/v1/chat/completions"
+    assert sent[0]["headers"]["Authorization"] == "Bearer sk"
+    assert body["messages"][0] == {"role": "system", "content": "REFERENCE\n\nPROJECT"}
+    assert body["tools"][0] == {"type": "function", "function": {
+        "name": "search_assets", "description": "Search GAM", "parameters": SEARCH.parameters}}
+    assert body["messages"][2]["tool_calls"][0]["id"] == "c1"
+    assert body["messages"][3:] == [
+        {"role": "tool", "tool_call_id": "c1", "content": "2 hits"},
+        {"role": "tool", "tool_call_id": "c2", "content": "ERROR: bad arguments"}]
+
+
+def test_ollama_is_spoken_to_over_its_v1_endpoint_with_no_key(wire):
+    sent, queue = wire
+    queue.append({"choices": [{"finish_reason": "stop", "message": {"content": "hi"}}]})
+    OpenAIProvider(row(provider_type="ollama", model="qwen3", base_url="http://10.0.0.5:11434"),
+                   "").conversation(system=[], tools=[], history=[], prompt="x").ask()
+    assert sent[0]["url"] == "http://10.0.0.5:11434/v1/chat/completions"
+    assert "Authorization" not in sent[0]["headers"]
+
+
+def test_a_server_that_says_stop_while_calling_a_tool_is_read_as_a_tool_call(wire):
+    _, queue = wire
+    queue.append({"choices": [{"finish_reason": "stop", "message": {"content": "", "tool_calls": [
+        {"id": "c1", "function": {"name": "search_assets", "arguments": "{}"}}]}}]})
+    reply = OpenAIProvider(row(provider_type="custom"), "sk").conversation(
+        system=[], tools=[SEARCH], history=[], prompt="x").ask()
+    assert reply.stop == "tool_use"
+
+
+def test_a_provider_error_names_the_provider(monkeypatch):
+    monkeypatch.setattr(_upstream, "post_json", lambda *a, **k: httpx.Response(
+        401, json={"error": {"message": "bad key"}}))
+    with pytest.raises(ProviderError, match="Test"):
+        OpenAIProvider(row(provider_type="openai"), "sk").conversation(
+            system=[], tools=[], history=[], prompt="x").ask()
diff --git a/backend/tests/test_provider_upstream.py b/backend/tests/test_provider_upstream.py
new file mode 100644
index 0000000..19d5d86
--- /dev/null
+++ b/backend/tests/test_provider_upstream.py
@@ -0,0 +1,219 @@
+"""The retry, backoff and timeout translation.
+
+GAM had none of this anywhere before: `enrichment/deepgram.py` and both embedders call
+a bare `httpx.post`, so the first 429 of a backfill is a hard failure. These are the
+cases that behaviour turns on.
+"""
+
+import httpx
+import pytest
+
+from app.providers import _upstream
+from app.providers.base import ProviderError
+from app.providers.params import PROTECTED_KEYS, parse_extra_params
+
+
+class FakeClient:
+    """Stands in for httpx.Client, handing back a scripted sequence of responses."""
+
+    def __init__(self, responses, recorder):
+        self._responses = list(responses)
+        self._recorder = recorder
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def post(self, url, headers=None, json=None):
+        self._recorder.append({"url": url, "headers": headers, "json": json})
+        result = self._responses.pop(0)
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+
+@pytest.fixture(name="transport")
+def transport_fixture(monkeypatch):
+    """Script the responses, record the requests, and never actually sleep."""
+    state = {"requests": [], "slept": []}
+
+    def install(*responses):
+        monkeypatch.setattr(
+            httpx, "Client", lambda **kwargs: FakeClient(responses, state["requests"])
+        )
+        return state
+
+    state["install"] = install
+    return state
+
+
+def _post(state, **overrides):
+    kwargs = {
+        "headers": {"x-api-key": "secret"},
+        "json_body": {"model": "m"},
+        "timeout": 30.0,
+        "label": "Test provider",
+        "sleep": state["slept"].append,
+    }
+    kwargs.update(overrides)
+    return _upstream.post_json("https://api.example.com/v1/messages", **kwargs)
+
+
+# ─── what is retried ─────────────────────────────────────────────────────────
+
+
+def test_a_rate_limit_is_retried_and_can_succeed(transport):
+    state = transport["install"](
+        httpx.Response(429, json={}), httpx.Response(200, json={"ok": True})
+    )
+
+    response = _post(state)
+
+    assert response.status_code == 200
+    assert len(state["requests"]) == 2
+    assert state["slept"] == [0.5]
+
+
+def test_backoff_doubles(transport):
+    state = transport["install"](
+        httpx.Response(503, json={}),
+        httpx.Response(503, json={}),
+        httpx.Response(200, json={}),
+    )
+
+    _post(state)
+
+    assert state["slept"] == [0.5, 1.0]
+
+
+def test_it_gives_up_after_three_attempts_and_hands_back_the_failure(transport):
+    state = transport["install"](*[httpx.Response(429, json={}) for _ in range(3)])
+
+    response = _post(state)
+
+    assert response.status_code == 429
+    assert len(state["requests"]) == 3
+
+
+@pytest.mark.parametrize("status", [400, 401, 403, 404, 422, 500])
+def test_everything_else_is_returned_immediately(transport, status):
+    """A 400 will fail identically forever; retrying it only delays the error."""
+    state = transport["install"](httpx.Response(status, json={}))
+
+    response = _post(state)
+
+    assert response.status_code == status
+    assert len(state["requests"]) == 1
+    assert state["slept"] == []
+
+
+# ─── Retry-After ─────────────────────────────────────────────────────────────
+
+
+def test_a_retry_after_header_is_honoured(transport):
+    """Better information than an exponential guess — the provider said how long."""
+    state = transport["install"](
+        httpx.Response(429, headers={"retry-after": "4"}), httpx.Response(200, json={})
+    )
+
+    _post(state)
+
+    assert state["slept"] == [4.0]
+
+
+def test_an_absurd_retry_after_is_clamped(transport):
+    """It is attacker-adjacent input for a custom endpoint, and a worker thread held
+    open for an hour blocks everything queued behind it."""
+    state = transport["install"](
+        httpx.Response(429, headers={"retry-after": "86400"}), httpx.Response(200, json={})
+    )
+
+    _post(state)
+
+    assert state["slept"] == [_upstream.MAX_RETRY_AFTER]
+
+
+@pytest.mark.parametrize("value", ["", "soon", "-1", "0", "Wed, 21 Oct 2026 07:28:00 GMT"])
+def test_an_unusable_retry_after_falls_back_to_the_backoff(transport, value):
+    state = transport["install"](
+        httpx.Response(429, headers={"retry-after": value}), httpx.Response(200, json={})
+    )
+
+    _post(state)
+
+    assert state["slept"] == [0.5]
+
+
+# ─── connection failures ─────────────────────────────────────────────────────
+
+
+def test_a_timeout_becomes_a_readable_error(transport):
+    state = transport["install"](httpx.ReadTimeout("too slow"))
+
+    with pytest.raises(ProviderError) as exc_info:
+        _post(state)
+    assert "Test provider" in str(exc_info.value)
+    assert "time" in str(exc_info.value)
+
+
+def test_an_unreachable_host_does_not_leak_the_url(transport):
+    """A RequestError's own text carries the full URL, and a custom provider's URL is
+    user-supplied — so the type is reported and the message is not."""
+    state = transport["install"](
+        httpx.ConnectError("failed to connect to https://internal.example.com/secret")
+    )
+
+    with pytest.raises(ProviderError) as exc_info:
+        _post(state)
+    message = str(exc_info.value)
+    assert "ConnectError" in message
+    assert "internal.example.com" not in message
+
+
+# ─── reading an error body ───────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "payload,expected",
+    [
+        ({"error": {"message": "Invalid API key"}}, "Invalid API key"),
+        ({"error": "model not found"}, "model not found"),
+        ({"message": "quota exceeded"}, "quota exceeded"),
+        ({"detail": "nope"}, "nope"),
+    ],
+)
+def test_the_message_is_found_wherever_the_provider_put_it(payload, expected):
+    assert _upstream.error_detail(httpx.Response(400, json=payload)) == expected
+
+
+def test_a_page_of_html_becomes_the_status_code():
+    """Otherwise a gateway's error page ends up pasted into a job's error field."""
+    response = httpx.Response(502, text="<html><body>Bad Gateway</body></html>")
+
+    assert _upstream.error_detail(response) == "HTTP 502"
+
+
+# ─── extra_params ────────────────────────────────────────────────────────────
+
+
+def test_extra_params_pass_tuning_through():
+    assert parse_extra_params('{"temperature": 0, "top_p": 0.9}') == {
+        "temperature": 0,
+        "top_p": 0.9,
+    }
+
+
+@pytest.mark.parametrize("key", sorted(PROTECTED_KEYS))
+def test_a_structural_key_is_stripped(key):
+    """A blob that sets `messages` does not tune a request, it replaces one."""
+    assert parse_extra_params('{"%s": "hijacked", "temperature": 1}' % key) == {
+        "temperature": 1
+    }
+
+
+@pytest.mark.parametrize("raw", [None, "", "not json", "[1, 2]", '"a string"', "null"])
+def test_anything_unusable_reads_as_none_set(raw):
+    """Costing the user a tuning parameter beats failing the whole enrichment run."""
+    assert parse_extra_params(raw) == {}
diff --git a/backend/tests/test_providers_api.py b/backend/tests/test_providers_api.py
new file mode 100644
index 0000000..038817b
--- /dev/null
+++ b/backend/tests/test_providers_api.py
@@ -0,0 +1,537 @@
+"""The AI provider CRUD over HTTP.
+
+Nothing consumes these rows yet — the clients that speak to the endpoints are the next
+step of the milestone — so this file is where the configuration is proved to work at all.
+The cases that matter most are the ones about the credential: it must be encrypted going
+in, unreadable coming out, and removable, which is one more than gecko-notes manages.
+"""
+
+import json
+import socket
+
+import httpx
+import pytest
+from sqlmodel import select
+
+from app.auth import decrypt_api_key
+from app.models.provider import AIProvider
+from app.providers import (
+    PROVIDER_ANTHROPIC,
+    PROVIDER_CUSTOM,
+    PROVIDER_DEEPSEEK,
+    PROVIDER_OLLAMA,
+    PROVIDER_OPENAI,
+)
+
+
+def _payload(**overrides) -> dict:
+    body = {
+        "name": "Claude",
+        "provider_type": PROVIDER_ANTHROPIC,
+        "api_key": "sk-ant-secret",
+        "model": "claude-sonnet-4-20250514",
+        "supports_images": True,
+    }
+    body.update(overrides)
+    return body
+
+
+def _create(auth_client, **overrides) -> dict:
+    response = auth_client.post("/api/providers", json=_payload(**overrides))
+    assert response.status_code == 201, response.text
+    return response.json()["data"]
+
+
+# ─── the credential ──────────────────────────────────────────────────────────
+
+
+def test_the_key_is_encrypted_at_rest(auth_client, session):
+    created = _create(auth_client)
+
+    row = session.get(AIProvider, created["id"])
+    assert "sk-ant-secret" not in row.api_key
+    assert row.api_key.startswith("enc:")
+    assert decrypt_api_key(row.api_key) == "sk-ant-secret"
+
+
+def test_the_key_is_never_returned(auth_client):
+    created = _create(auth_client)
+    assert "sk-ant-secret" not in json.dumps(created)
+    assert "api_key" not in created
+
+    listed = auth_client.get("/api/providers").json()
+    assert "sk-ant-secret" not in json.dumps(listed)
+
+
+def test_the_response_says_whether_a_key_is_configured(auth_client):
+    """gecko-notes redacts the key to "", which reads identically to having none — so
+    its own settings screen cannot tell a configured provider from an unconfigured one."""
+    with_key = _create(auth_client)
+    assert with_key["api_key_configured"] is True
+
+    without = _create(auth_client, name="Local", provider_type=PROVIDER_OLLAMA, api_key="")
+    assert without["api_key_configured"] is False
+
+
+def test_omitting_the_key_on_update_leaves_it_alone(auth_client, session):
+    """The browser never received the key, so it has nothing to send back. An update
+    that does not mention it must not wipe it."""
+    created = _create(auth_client)
+
+    auth_client.put(f"/api/providers/{created['id']}", json={"name": "Renamed"})
+
+    session.expire_all()
+    row = session.get(AIProvider, created["id"])
+    assert decrypt_api_key(row.api_key) == "sk-ant-secret"
+    assert row.name == "Renamed"
+
+
+def test_an_empty_key_on_update_removes_it(auth_client, session):
+    """gecko-notes writes only `if payload.api_key:`, so a stored key can never be
+    cleared there. Same three-state contract as every other credential in this app."""
+    created = _create(auth_client)
+
+    body = auth_client.put(f"/api/providers/{created['id']}", json={"api_key": ""})
+    assert body.json()["data"]["api_key_configured"] is False
+
+    session.expire_all()
+    assert session.get(AIProvider, created["id"]).api_key == ""
+
+
+def test_a_new_key_replaces_the_old_one(auth_client, session):
+    created = _create(auth_client)
+
+    auth_client.put(f"/api/providers/{created['id']}", json={"api_key": "sk-ant-second"})
+
+    session.expire_all()
+    assert decrypt_api_key(session.get(AIProvider, created["id"]).api_key) == "sk-ant-second"
+
+
+# ─── ownership ───────────────────────────────────────────────────────────────
+
+
+def test_the_list_starts_empty(auth_client):
+    body = auth_client.get("/api/providers").json()
+    assert body["data"] == []
+    assert body["total"] == 0
+
+
+def test_another_users_provider_is_invisible(auth_client, session):
+    """404 rather than 403: whether a provider id exists is not a question this API
+    answers for people who do not own it."""
+    session.add(
+        AIProvider(
+            id="someone-elses",
+            user_id="a-different-user",
+            name="Theirs",
+            provider_type=PROVIDER_OPENAI,
+            model="gpt-4o",
+        )
+    )
+    session.commit()
+
+    assert auth_client.get("/api/providers").json()["data"] == []
+    assert auth_client.put("/api/providers/someone-elses", json={"name": "x"}).status_code == 404
+    assert auth_client.delete("/api/providers/someone-elses").status_code == 404
+    assert auth_client.post("/api/providers/someone-elses/activate").status_code == 404
+
+
+def test_authentication_is_required(client):
+    assert client.get("/api/providers").status_code == 401
+    assert client.post("/api/providers", json=_payload()).status_code == 401
+
+
+# ─── validation ──────────────────────────────────────────────────────────────
+
+
+def test_an_unknown_provider_type_is_refused(auth_client):
+    response = auth_client.post("/api/providers", json=_payload(provider_type="skynet"))
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "bad_request"
+
+
+def test_an_unknown_provider_type_is_refused_on_update(auth_client):
+    created = _create(auth_client)
+    response = auth_client.put(
+        f"/api/providers/{created['id']}", json={"provider_type": "skynet"}
+    )
+    assert response.status_code == 400
+
+
+def test_a_model_is_free_text(auth_client):
+    """No closed dropdown. Models ship faster than this app is redeployed."""
+    created = _create(auth_client, model="claude-something-not-released-yet")
+    assert created["model"] == "claude-something-not-released-yet"
+
+
+# ─── base URL and SSRF ───────────────────────────────────────────────────────
+
+
+def test_a_custom_base_url_must_be_https(auth_client):
+    response = auth_client.post(
+        "/api/providers",
+        json=_payload(provider_type=PROVIDER_CUSTOM, base_url="http://gateway.example.com"),
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_url"
+
+
+def test_a_private_base_url_is_refused(auth_client):
+    response = auth_client.post(
+        "/api/providers",
+        json=_payload(provider_type=PROVIDER_CUSTOM, base_url="https://127.0.0.1:8080"),
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "ssrf_blocked"
+
+
+def test_a_name_resolving_inside_the_network_is_refused(auth_client, monkeypatch):
+    def fake_getaddrinfo(host, port, *args, **kwargs):
+        return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("10.0.0.7", 443))]
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    response = auth_client.post(
+        "/api/providers",
+        json=_payload(provider_type=PROVIDER_CUSTOM, base_url="https://gateway.example.com"),
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "ssrf_blocked"
+
+
+def test_changing_only_the_base_url_is_still_checked(auth_client):
+    """The bug gecko-notes had and fixed: the check rode inside the `if payload.api_key`
+    block, so an update that touched only the URL skipped it — and the stored URL is
+    exactly what a later request gets sent to."""
+    created = _create(auth_client, provider_type=PROVIDER_CUSTOM, base_url="https://8.8.8.8")
+
+    response = auth_client.put(
+        f"/api/providers/{created['id']}", json={"base_url": "https://192.168.0.1"}
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "ssrf_blocked"
+
+
+def test_changing_type_and_url_together_is_checked_against_the_new_type(auth_client):
+    """An ollama row moving to `custom` brings its private URL with it unless the check
+    uses the type this request results in rather than the one already stored."""
+    created = _create(
+        auth_client,
+        provider_type=PROVIDER_OLLAMA,
+        api_key="",
+        base_url="http://localhost:11434",
+        model="llama3.2",
+    )
+
+    response = auth_client.put(
+        f"/api/providers/{created['id']}",
+        json={"provider_type": PROVIDER_CUSTOM, "base_url": "http://localhost:11434"},
+    )
+    assert response.status_code == 400
+
+
+def test_ollama_may_point_at_a_private_address(auth_client):
+    """The one deliberate exception. It is a local daemon; that is the point of it."""
+    created = _create(
+        auth_client,
+        name="Local",
+        provider_type=PROVIDER_OLLAMA,
+        api_key="",
+        base_url="http://localhost:11434",
+        model="llama3.2",
+    )
+    assert created["base_url"] == "http://localhost:11434"
+
+
+def test_a_deepseek_base_url_is_not_checked_because_it_is_never_used(auth_client):
+    """DeepSeek resolves to a fixed managed endpoint, so the stored value is inert."""
+    created = _create(
+        auth_client,
+        provider_type=PROVIDER_DEEPSEEK,
+        base_url="http://whatever.invalid",
+        model="deepseek-chat",
+    )
+    assert created["id"]
+
+
+# ─── activation ──────────────────────────────────────────────────────────────
+
+
+def test_activating_one_provider_deactivates_the_rest(auth_client):
+    first = _create(auth_client, name="Claude", is_active=True)
+    second = _create(auth_client, name="DeepSeek", provider_type=PROVIDER_DEEPSEEK, model="deepseek-chat")
+
+    auth_client.post(f"/api/providers/{second['id']}/activate")
+
+    listed = {p["id"]: p for p in auth_client.get("/api/providers").json()["data"]}
+    assert listed[first["id"]]["is_active"] is False
+    assert listed[second["id"]]["is_active"] is True
+
+
+def test_creating_an_active_provider_deactivates_the_previous_one(auth_client):
+    first = _create(auth_client, name="Claude", is_active=True)
+    _create(auth_client, name="OpenAI", provider_type=PROVIDER_OPENAI, model="gpt-4o", is_active=True)
+
+    listed = {p["id"]: p for p in auth_client.get("/api/providers").json()["data"]}
+    assert listed[first["id"]]["is_active"] is False
+    assert sum(p["is_active"] for p in listed.values()) == 1
+
+
+def test_updating_a_provider_to_active_deactivates_the_others(auth_client):
+    first = _create(auth_client, name="Claude", is_active=True)
+    second = _create(auth_client, name="DeepSeek", provider_type=PROVIDER_DEEPSEEK, model="deepseek-chat")
+
+    auth_client.put(f"/api/providers/{second['id']}", json={"is_active": True})
+
+    listed = {p["id"]: p for p in auth_client.get("/api/providers").json()["data"]}
+    assert listed[first["id"]]["is_active"] is False
+    assert listed[second["id"]]["is_active"] is True
+
+
+# ─── extra params ────────────────────────────────────────────────────────────
+
+
+def test_extra_params_round_trip_as_a_dict(auth_client, session):
+    created = _create(auth_client, extra_params={"temperature": 0, "top_p": 0.9})
+    assert created["extra_params"] == {"temperature": 0, "top_p": 0.9}
+
+    # JSON-as-TEXT in the column, per the house convention.
+    assert isinstance(session.get(AIProvider, created["id"]).extra_params, str)
+
+
+def test_empty_extra_params_clears_them(auth_client):
+    created = _create(auth_client, extra_params={"temperature": 0})
+
+    body = auth_client.put(f"/api/providers/{created['id']}", json={"extra_params": {}})
+    assert body.json()["data"]["extra_params"] is None
+
+
+def test_unreadable_extra_params_read_as_nothing_rather_than_500(auth_client, session):
+    """A row written by an older version should not take the settings screen down."""
+    created = _create(auth_client)
+    session.get(AIProvider, created["id"]).extra_params = "not json"
+    session.commit()
+
+    body = auth_client.get("/api/providers").json()["data"][0]
+    assert body["extra_params"] is None
+
+
+# ─── deletion ────────────────────────────────────────────────────────────────
+
+
+def test_delete_removes_the_row(auth_client, session):
+    created = _create(auth_client)
+
+    assert auth_client.delete(f"/api/providers/{created['id']}").status_code == 204
+
+    session.expire_all()
+    assert session.exec(select(AIProvider)).all() == []
+
+
+# ─── the connection probe ────────────────────────────────────────────────────
+
+
+@pytest.fixture(name="captured")
+def captured_fixture(monkeypatch):
+    """Record the outbound probe instead of making it.
+
+    Same shape as tests/test_deepgram.py: patch `httpx.post`, keep everything else real,
+    and assert on the URL and headers the app chose.
+    """
+    calls: list[dict] = []
+
+    def fake_post(url, **kwargs):
+        calls.append({"url": url, **kwargs})
+        return httpx.Response(200, json={})
+
+    def fake_get(url, **kwargs):
+        calls.append({"url": url, **kwargs})
+        return httpx.Response(200, json={"models": []})
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+    monkeypatch.setattr(httpx, "get", fake_get)
+    return calls
+
+
+def test_an_anthropic_probe_goes_to_anthropic(auth_client, captured):
+    body = auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_type": PROVIDER_ANTHROPIC,
+            "api_key": "sk-ant-x",
+            "model": "claude-sonnet-4-20250514",
+        },
+    ).json()["data"]
+
+    assert body["success"] is True
+    assert captured[0]["url"] == "https://api.anthropic.com/v1/messages"
+    assert captured[0]["headers"]["x-api-key"] == "sk-ant-x"
+    assert captured[0]["headers"]["anthropic-version"] == "2023-06-01"
+
+
+def test_a_deepseek_probe_with_the_flag_goes_to_the_anthropic_compatible_endpoint(
+    auth_client, captured
+):
+    """The whole reason `use_anthropic_api` exists. Testing it against the
+    OpenAI-compatible endpoint would report a result for a URL it no longer uses."""
+    body = auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_type": PROVIDER_DEEPSEEK,
+            "api_key": "sk-ds-x",
+            "model": "deepseek-chat",
+            "use_anthropic_api": True,
+        },
+    ).json()["data"]
+
+    assert body["success"] is True
+    assert captured[0]["url"] == "https://api.deepseek.com/anthropic/v1/messages"
+    # Both auth headers, because compatible gateways disagree about which to read.
+    assert captured[0]["headers"]["x-api-key"] == "sk-ds-x"
+    assert captured[0]["headers"]["Authorization"] == "Bearer sk-ds-x"
+    # Beta flags are Anthropic-internal; a gateway could reject the whole request over
+    # a feature it was never asked for.
+    assert "anthropic-beta" not in captured[0]["headers"]
+
+
+def test_a_deepseek_probe_without_the_flag_goes_to_the_openai_compatible_endpoint(
+    auth_client, captured
+):
+    auth_client.post(
+        "/api/providers/test",
+        json={"provider_type": PROVIDER_DEEPSEEK, "api_key": "k", "model": "deepseek-chat"},
+    )
+    assert captured[0]["url"] == "https://api.deepseek.com/v1/chat/completions"
+
+
+def test_a_deepseek_probe_ignores_a_stored_base_url(auth_client, captured):
+    """A fixed managed endpoint, so a crafted base_url cannot redirect the request."""
+    auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_type": PROVIDER_DEEPSEEK,
+            "api_key": "k",
+            "model": "deepseek-chat",
+            "base_url": "https://8.8.8.8",
+        },
+    )
+    assert captured[0]["url"].startswith("https://api.deepseek.com")
+
+
+def test_an_ollama_probe_asks_for_its_model_list(auth_client, captured):
+    body = auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_type": PROVIDER_OLLAMA,
+            "model": "llama3.2",
+            "base_url": "http://localhost:11434",
+        },
+    ).json()["data"]
+
+    assert body["success"] is True
+    assert captured[0]["url"] == "http://localhost:11434/api/tags"
+
+
+def test_a_saved_provider_is_probed_with_its_stored_key(auth_client, captured):
+    """The screen can re-test a provider without asking for the key again, which it
+    could not do anyway — it was never given it."""
+    created = _create(auth_client)
+
+    auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_id": created["id"],
+            "provider_type": PROVIDER_ANTHROPIC,
+            "model": "claude-sonnet-4-20250514",
+        },
+    )
+    assert captured[0]["headers"]["x-api-key"] == "sk-ant-secret"
+
+
+def test_probing_someone_elses_provider_is_a_404(auth_client, session, captured):
+    session.add(
+        AIProvider(
+            id="theirs",
+            user_id="a-different-user",
+            name="Theirs",
+            provider_type=PROVIDER_ANTHROPIC,
+            model="claude-sonnet-4-20250514",
+        )
+    )
+    session.commit()
+
+    response = auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_id": "theirs",
+            "provider_type": PROVIDER_ANTHROPIC,
+            "model": "claude-sonnet-4-20250514",
+        },
+    )
+    assert response.status_code == 404
+    assert captured == []
+
+
+def test_the_anthropic_probe_is_ssrf_checked(auth_client, captured):
+    """gecko-notes checks the OpenAI-compatible branch and not this one, so a `custom`
+    provider's payload-supplied base_url goes straight into an outbound POST."""
+    response = auth_client.post(
+        "/api/providers/test",
+        json={
+            "provider_type": PROVIDER_CUSTOM,
+            "api_key": "k",
+            "model": "m",
+            "base_url": "https://169.254.169.254",
+            "use_anthropic_api": True,
+        },
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "ssrf_blocked"
+    assert captured == []
+
+
+@pytest.mark.parametrize(
+    "status_code,success",
+    [(200, True), (400, True), (401, False), (403, False), (404, False), (429, False), (500, False)],
+)
+def test_how_a_status_code_is_read(auth_client, monkeypatch, status_code, success):
+    """400 counts as success: the endpoint answered, so the address and the credential
+    were both accepted — it is the ten-token probe body it did not like, and that is not
+    the question being asked."""
+    monkeypatch.setattr(
+        httpx, "post", lambda url, **kwargs: httpx.Response(status_code, json={})
+    )
+
+    body = auth_client.post(
+        "/api/providers/test",
+        json={"provider_type": PROVIDER_ANTHROPIC, "api_key": "k", "model": "m"},
+    ).json()["data"]
+    assert body["success"] is success
+
+
+def test_an_unreachable_provider_reports_a_sentence_not_a_traceback(auth_client, monkeypatch):
+    def explode(url, **kwargs):
+        raise httpx.ConnectError("nope")
+
+    monkeypatch.setattr(httpx, "post", explode)
+
+    body = auth_client.post(
+        "/api/providers/test",
+        json={"provider_type": PROVIDER_ANTHROPIC, "api_key": "k", "model": "m"},
+    ).json()["data"]
+    assert body["success"] is False
+    assert body["message"]
+
+
+def test_a_timeout_says_so(auth_client, monkeypatch):
+    def slow(url, **kwargs):
+        raise httpx.ReadTimeout("too slow")
+
+    monkeypatch.setattr(httpx, "post", slow)
+
+    body = auth_client.post(
+        "/api/providers/test",
+        json={"provider_type": PROVIDER_ANTHROPIC, "api_key": "k", "model": "m"},
+    ).json()["data"]
+    assert body["success"] is False
+    assert "time" in body["message"].lower()
diff --git a/backend/tests/test_safe_url.py b/backend/tests/test_safe_url.py
new file mode 100644
index 0000000..a759e4d
--- /dev/null
+++ b/backend/tests/test_safe_url.py
@@ -0,0 +1,143 @@
+"""The SSRF guard.
+
+Every check here is about a URL a *user* chose. The threat is not a malformed address —
+it is a well-formed one that resolves somewhere the browser could never reach but the
+container can: a metadata endpoint, an internal admin port, a neighbouring service.
+"""
+
+import socket
+
+import pytest
+from fastapi import HTTPException
+
+from app.safe_url import require_safe_external_url
+
+
+def _code(exc_info) -> str:
+    return exc_info.value.detail["code"]
+
+
+# ─── scheme ──────────────────────────────────────────────────────────────────
+
+
+def test_https_is_required():
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("http://api.example.com")
+    assert exc_info.value.status_code == 400
+    assert _code(exc_info) == "invalid_url"
+
+
+def test_a_non_http_scheme_is_refused():
+    """file:// and gopher:// are the classic ways to turn a fetch into a local read."""
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("file:///etc/passwd")
+    assert _code(exc_info) == "invalid_url"
+
+
+def test_something_that_is_not_a_url_at_all():
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("https://")
+    assert _code(exc_info) == "invalid_url"
+
+
+# ─── literal addresses ───────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://127.0.0.1/v1",
+        "https://10.0.0.5:8080",
+        "https://192.168.1.10",
+        "https://172.16.4.4",
+        # The cloud metadata endpoint, which is the single most valuable target here.
+        "https://169.254.169.254/latest/meta-data/",
+        "https://[::1]/v1",
+        "https://[fd00::1]/v1",
+    ],
+)
+def test_private_and_loopback_literals_are_refused(url):
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url(url)
+    assert _code(exc_info) == "ssrf_blocked"
+
+
+def test_a_public_literal_is_allowed():
+    require_safe_external_url("https://8.8.8.8/v1")
+
+
+@pytest.mark.parametrize("host", ["localhost", "LOCALHOST", "api.localhost"])
+def test_localhost_by_name_is_refused(host):
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url(f"https://{host}/v1")
+    assert _code(exc_info) == "ssrf_blocked"
+
+
+# ─── resolution ──────────────────────────────────────────────────────────────
+
+
+def _resolving_to(address: str, family=socket.AF_INET):
+    def fake_getaddrinfo(host, port, *args, **kwargs):
+        return [(family, socket.SOCK_STREAM, 6, "", (address, 443))]
+
+    return fake_getaddrinfo
+
+
+def test_a_public_name_pointing_at_loopback_is_refused(monkeypatch):
+    """The case gecko-notes' version misses.
+
+    It checks literal addresses only, so a name the attacker controls — pointed at
+    127.0.0.1 by their own DNS — walks straight through it. That is the whole attack,
+    not an edge case.
+    """
+    monkeypatch.setattr(socket, "getaddrinfo", _resolving_to("127.0.0.1"))
+
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("https://totally-fine.example.com/v1")
+    assert _code(exc_info) == "ssrf_blocked"
+
+
+def test_a_name_pointing_at_a_private_range_is_refused(monkeypatch):
+    monkeypatch.setattr(socket, "getaddrinfo", _resolving_to("10.1.2.3"))
+
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("https://gateway.example.com")
+    assert _code(exc_info) == "ssrf_blocked"
+
+
+def test_a_name_resolving_to_a_public_address_is_allowed(monkeypatch):
+    monkeypatch.setattr(socket, "getaddrinfo", _resolving_to("93.184.216.34"))
+
+    require_safe_external_url("https://api.example.com/v1")
+
+
+def test_every_resolved_address_is_checked_not_just_the_first(monkeypatch):
+    """A name can answer with several addresses, and one private answer is enough."""
+
+    def fake_getaddrinfo(host, port, *args, **kwargs):
+        return [
+            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 443)),
+            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 443)),
+        ]
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    with pytest.raises(HTTPException) as exc_info:
+        require_safe_external_url("https://split.example.com")
+    assert _code(exc_info) == "ssrf_blocked"
+
+
+def test_a_resolution_failure_does_not_block(monkeypatch):
+    """Deliberate, and the reason this guard is defence in depth rather than the only line.
+
+    Refusing to *save* a setting because a lookup failed is a worse failure than letting
+    the eventual request fail on its own merits — the resolver may be temporarily
+    unreachable, or the name may only resolve from where the request is finally made.
+    """
+
+    def fake_getaddrinfo(host, port, *args, **kwargs):
+        raise socket.gaierror("Name or service not known")
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    require_safe_external_url("https://not-yet-registered.example.com")
diff --git a/backend/tests/test_usage.py b/backend/tests/test_usage.py
new file mode 100644
index 0000000..5fc23f1
--- /dev/null
+++ b/backend/tests/test_usage.py
@@ -0,0 +1,58 @@
+"""Spend: priced per call, attributed to projects and turns, read back as totals."""
+
+from app.models.usage import UsageEvent
+from app.providers.base import Reply, Usage
+from app.usage import events as usage_events
+from app.usage import pricing
+
+
+def test_current_claude_models_are_priced_from_the_most_specific_entry():
+    assert pricing.cost_for("anthropic", "claude-opus-5-5", 1_000_000, 1_000_000) == (24.0, "USD")
+    assert pricing.cost_for("anthropic", "claude-opus-5", 1_000_000, 0) == (5.0, "USD")
+    assert pricing.cost_for("anthropic", "claude-sonnet-5-5", 0, 1_000_000) == (10.0, "USD")
+    assert pricing.cost_for("anthropic", "claude-haiku-5-5", 1_000_000, 0) == (0.1, "USD")
+    assert pricing.cost_for("anthropic", "claude-fable-5-1", 1_000_000, 0) == (10.0, "USD")
+    assert pricing.cost_for("ollama", "qwen3", 10**6, 10**6) == (0.0, "USD")
+    assert pricing.cost_for("custom", "anything", 10**6, 10**6) is None
+
+
+def reply(provider="anthropic", model="claude-opus-5-5", tokens_in=1000, tokens_out=500):
+    return Reply(text="", usage=Usage(tokens_in, tokens_out), model=model, provider_type=provider)
+
+
+def test_a_reply_is_recorded_against_its_project_and_turn(session):
+    cost = usage_events.record_reply(session, user_id="u", project_id="p", turn_id="t",
+                                     reply=reply())
+    assert cost == round(1000 / 1e6 * 4 + 500 / 1e6 * 20, 6)
+    [row] = session.query(UsageEvent).all()
+    assert (row.project_id, row.turn_id, row.units, row.cost_estimated) == ("p", "t", 1500, True)
+
+
+def test_an_unmeasured_call_records_nothing_and_an_unpriced_one_no_cost(session):
+    assert usage_events.record_reply(session, user_id="u", project_id=None, turn_id=None,
+                                     reply=reply(tokens_in=0, tokens_out=0)) is None
+    assert session.query(UsageEvent).count() == 0
+    assert usage_events.record_reply(session, user_id="u", project_id=None, turn_id=None,
+                                     reply=reply(provider="custom")) is None
+    assert session.query(UsageEvent).one().cost is None
+
+
+def test_totals_overall_per_project_and_by_model_over_http(auth_client, session):
+    project = auth_client.post("/api/projects", json={"spec": {"title": "T", "segments": []}}).json()["data"]
+    from tests.conftest import TEST_USER_ID
+    usage_events.record_reply(session, user_id=TEST_USER_ID, project_id=project["id"],
+                              turn_id="t1", reply=reply())
+    usage_events.record_reply(session, user_id=TEST_USER_ID, project_id=None, turn_id="t2",
+                              reply=reply(provider="custom", model="x"))
+
+    overall = auth_client.get("/api/usage").json()["data"]
+    assert overall["totals"]["total_events"] == 2
+    # One call could not be priced, so the total says it is a floor.
+    assert overall["totals"]["priced_events"] == 1
+    assert overall["totals"]["estimated"] is True
+    assert {(r["provider"], r["model"]) for r in overall["by_provider"]} == {
+        ("anthropic", "claude-opus-5-5"), ("custom", "x")}
+
+    mine = auth_client.get(f"/api/usage/projects/{project['id']}").json()["data"]
+    assert mine["total_events"] == 1 and mine["tokens"] == 1500
+    assert auth_client.get("/api/usage/projects/nope").status_code == 404
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 5b22b75..1959c2a 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -4,6 +4,7 @@ import AppShell from '@/components/AppShell'
 import RequireAuth from '@/components/RequireAuth'
 import ProjectListView from '@/views/ProjectListView'
 import ProjectView from '@/views/ProjectView'
+import SettingsView from '@/views/SettingsView'
 import { loadConfig } from '@/api/config'
 import { setUnauthorizedHandler } from '@/api/client'
 import { useAuthStore } from '@/stores/auth'
@@ -44,6 +45,7 @@ export default function App() {
       <Route path="/" element={<Navigate to="/projects" replace />} />
       <Route path="/projects" element={page(<ProjectListView />)} />
       <Route path="/p/:id" element={page(<ProjectView />)} />
+      <Route path="/settings" element={page(<SettingsView />)} />
       <Route path="*" element={<Navigate to="/projects" replace />} />
     </Routes>
   )
diff --git a/frontend/src/api/providers.ts b/frontend/src/api/providers.ts
new file mode 100644
index 0000000..1337dc5
--- /dev/null
+++ b/frontend/src/api/providers.ts
@@ -0,0 +1,108 @@
+import client from '@/api/client'
+
+/**
+ * The generative LLM providers a user has configured.
+ *
+ * Separate from the embedding provider in `api/settings.ts`, and deliberately so:
+ * embeddings and generation are different capabilities with different provider sets.
+ * Anthropic publishes no embeddings API at all; DeepSeek's chat models are text-only
+ * while its Anthropic-compatible endpoint is the one that can search the web.
+ *
+ * As everywhere else, a key is written and never read back — the server reports whether
+ * one is configured, not what it is.
+ */
+
+interface DataResponse<T> {
+  data: T
+}
+
+interface ListResponse<T> {
+  data: T[]
+  total: number
+}
+
+export type ProviderType = 'anthropic' | 'openai' | 'deepseek' | 'ollama' | 'custom'
+
+export interface AIProvider {
+  id: string
+  name: string
+  provider_type: ProviderType
+  base_url: string | null
+  model: string
+  max_tokens: number
+  /** Whether this model accepts images. Gates the describe job, once it exists. */
+  supports_images: boolean
+  /**
+   * Speak the Anthropic Messages protocol to this provider instead of its own. Only
+   * meaningful for `deepseek` and `custom` — see `canUseAnthropicApi`.
+   */
+  use_anthropic_api: boolean
+  extra_params: Record<string, unknown> | null
+  enabled: boolean
+  is_active: boolean
+  api_key_configured: boolean
+}
+
+export interface ProviderInput {
+  name: string
+  provider_type: ProviderType
+  /** '' clears the stored key on update; omit the field to leave it alone. */
+  api_key?: string
+  base_url?: string | null
+  model: string
+  max_tokens?: number
+  supports_images?: boolean
+  use_anthropic_api?: boolean
+  extra_params?: Record<string, unknown>
+  enabled?: boolean
+  is_active?: boolean
+}
+
+export interface ProviderTestResult {
+  success: boolean
+  message: string
+}
+
+export interface ProviderTestInput {
+  /** A saved provider, so its stored key is used — the browser never received it. */
+  provider_id?: string
+  provider_type: ProviderType
+  api_key?: string
+  base_url?: string | null
+  model: string
+  use_anthropic_api?: boolean
+}
+
+export const providersApi = {
+  list(): Promise<AIProvider[]> {
+    return client.get<ListResponse<AIProvider>>('/providers').then((r) => r.data.data)
+  },
+
+  create(input: ProviderInput): Promise<AIProvider> {
+    return client
+      .post<DataResponse<AIProvider>>('/providers', input)
+      .then((r) => r.data.data)
+  },
+
+  update(id: string, changes: Partial<ProviderInput>): Promise<AIProvider> {
+    return client
+      .put<DataResponse<AIProvider>>(`/providers/${id}`, changes)
+      .then((r) => r.data.data)
+  },
+
+  remove(id: string): Promise<void> {
+    return client.delete(`/providers/${id}`).then(() => undefined)
+  },
+
+  activate(id: string): Promise<AIProvider> {
+    return client
+      .post<DataResponse<AIProvider>>(`/providers/${id}/activate`)
+      .then((r) => r.data.data)
+  },
+
+  test(input: ProviderTestInput): Promise<ProviderTestResult> {
+    return client
+      .post<DataResponse<ProviderTestResult>>('/providers/test', input)
+      .then((r) => r.data.data)
+  },
+}
diff --git a/frontend/src/api/usage.ts b/frontend/src/api/usage.ts
new file mode 100644
index 0000000..78c6474
--- /dev/null
+++ b/frontend/src/api/usage.ts
@@ -0,0 +1,58 @@
+import client from '@/api/client'
+
+/**
+ * What the assistant has spent. Every figure is a list-price estimate, and the UI says
+ * so: a cost from the pricing table is a published rate, not a bill.
+ */
+
+interface DataResponse<T> {
+  data: T
+}
+
+export interface UsageTotals {
+  total_events: number
+  /** Fewer than `total_events` means some calls could not be priced, so `cost` is a
+   *  floor rather than the whole story. */
+  priced_events: number
+  cost: number
+  currency: string
+  estimated: boolean
+  tokens: number
+}
+
+export interface ProviderTotal {
+  provider: string
+  model: string
+  events: number
+  units: number
+  /** null when nothing in this group could be priced. */
+  cost: number | null
+}
+
+export interface UsageSummary {
+  totals: UsageTotals
+  by_provider: ProviderTotal[]
+}
+
+export const usageApi = {
+  summary(): Promise<UsageSummary> {
+    return client.get<DataResponse<UsageSummary>>('/usage').then((r) => r.data.data)
+  },
+
+  forProject(projectId: string): Promise<UsageTotals> {
+    return client
+      .get<DataResponse<UsageTotals>>(`/usage/projects/${projectId}`)
+      .then((r) => r.data.data)
+  },
+}
+
+/**
+ * A cost at a precision that does not pretend. A turn costs fractions of a cent to a
+ * few cents, and rounding to two decimals would show "$0.00" for work that was not free.
+ */
+export function formatCost(cost: number, currency = 'USD'): string {
+  const symbol = currency === 'USD' ? '$' : `${currency} `
+  if (cost === 0) return `${symbol}0.00`
+  if (cost < 0.01) return `${symbol}${cost.toFixed(4)}`
+  return `${symbol}${cost.toFixed(2)}`
+}
diff --git a/frontend/src/components/AppShell.tsx b/frontend/src/components/AppShell.tsx
index aabe43f..7e7d96f 100644
--- a/frontend/src/components/AppShell.tsx
+++ b/frontend/src/components/AppShell.tsx
@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react'
-import { LogOut, Moon, Sun } from 'lucide-react'
+import { LogOut, Moon, Settings, Sun } from 'lucide-react'
 import { Link } from 'react-router-dom'
 import { useAuthStore } from '@/stores/auth'
 import { useThemeStore } from '@/stores/theme'
@@ -29,6 +29,14 @@ export default function AppShell({ children }: Props) {
           </Link>
 
           <div className="ml-auto flex items-center gap-3">
+            <Link
+              to="/settings"
+              className="btn btn-ghost p-2"
+              aria-label="Settings"
+              title="Settings"
+            >
+              <Settings className="h-4 w-4" />
+            </Link>
             <button
               type="button"
               onClick={toggleTheme}
diff --git a/frontend/src/components/ProviderPanel.test.tsx b/frontend/src/components/ProviderPanel.test.tsx
new file mode 100644
index 0000000..5cb7d63
--- /dev/null
+++ b/frontend/src/components/ProviderPanel.test.tsx
@@ -0,0 +1,242 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import ProviderPanel from '@/components/ProviderPanel'
+import { providersApi, type AIProvider } from '@/api/providers'
+
+function provider(overrides: Partial<AIProvider> = {}): AIProvider {
+  return {
+    id: 'p1',
+    name: 'Claude',
+    provider_type: 'anthropic',
+    base_url: null,
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 64000,
+    supports_images: true,
+    use_anthropic_api: false,
+    extra_params: null,
+    enabled: true,
+    is_active: true,
+    api_key_configured: true,
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  vi.spyOn(providersApi, 'list').mockResolvedValue([])
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('ProviderPanel', () => {
+  it('says plainly when nothing is configured', async () => {
+    render(<ProviderPanel />)
+
+    expect(await screen.findByText(/no provider configured yet/i)).toBeInTheDocument()
+  })
+
+  it('lists what is configured, and which one is in use', async () => {
+    vi.spyOn(providersApi, 'list').mockResolvedValue([
+      provider(),
+      provider({
+        id: 'p2',
+        name: 'DeepSeek',
+        provider_type: 'deepseek',
+        model: 'deepseek-chat',
+        supports_images: false,
+        is_active: false,
+      }),
+    ])
+    render(<ProviderPanel />)
+
+    expect(await screen.findByText('Claude')).toBeInTheDocument()
+    expect(screen.getByText('DeepSeek')).toBeInTheDocument()
+    expect(screen.getByText(/^active$/i)).toBeInTheDocument()
+    // Only the inactive one offers to be switched to.
+    expect(screen.getAllByRole('button', { name: /use this one/i })).toHaveLength(1)
+  })
+
+  it('keeps the form closed until asked', async () => {
+    // Load-bearing beyond tidiness: SettingsView already renders two panels with an
+    // "API key" field, and a third always-present one makes every label query in
+    // SettingsView.test.tsx ambiguous.
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+
+    expect(screen.queryByLabelText(/provider api key/i)).toBeNull()
+
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+    expect(await screen.findByLabelText(/provider api key/i)).toBeInTheDocument()
+  })
+
+  it('creates a provider from the form', async () => {
+    const create = vi.spyOn(providersApi, 'create').mockResolvedValue(provider())
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+    await userEvent.type(screen.getByLabelText(/^name$/i), 'Claude')
+    await userEvent.type(
+      screen.getByLabelText(/^model name$/i),
+      'claude-sonnet-4-20250514'
+    )
+    await userEvent.type(screen.getByLabelText(/provider api key/i), 'sk-ant-secret')
+    await userEvent.click(screen.getByRole('button', { name: /save provider/i }))
+
+    await waitFor(() => expect(create).toHaveBeenCalled())
+    expect(create.mock.calls[0][0]).toMatchObject({
+      name: 'Claude',
+      provider_type: 'anthropic',
+      model: 'claude-sonnet-4-20250514',
+      api_key: 'sk-ant-secret',
+    })
+  })
+
+  it('never seeds the key field from the server', async () => {
+    // It was never sent one. An empty box on edit means "leave the stored key alone",
+    // which is also what the request means by omitting it.
+    vi.spyOn(providersApi, 'list').mockResolvedValue([provider()])
+    render(<ProviderPanel />)
+
+    await userEvent.click(await screen.findByRole('button', { name: /edit claude/i }))
+
+    expect(screen.getByLabelText(/provider api key/i)).toHaveValue('')
+    expect(screen.getByLabelText(/provider api key/i)).toHaveAttribute(
+      'placeholder',
+      expect.stringMatching(/keep the stored key/i)
+    )
+  })
+
+  it('omits the key on edit unless one was typed', async () => {
+    vi.spyOn(providersApi, 'list').mockResolvedValue([provider()])
+    const update = vi.spyOn(providersApi, 'update').mockResolvedValue(provider())
+    render(<ProviderPanel />)
+
+    await userEvent.click(await screen.findByRole('button', { name: /edit claude/i }))
+    await userEvent.clear(screen.getByLabelText(/^name$/i))
+    await userEvent.type(screen.getByLabelText(/^name$/i), 'Claude Opus')
+    await userEvent.click(screen.getByRole('button', { name: /save provider/i }))
+
+    await waitFor(() => expect(update).toHaveBeenCalled())
+    expect(update.mock.calls[0][1]).not.toHaveProperty('api_key')
+    expect(update.mock.calls[0][1]).toMatchObject({ name: 'Claude Opus' })
+  })
+
+  it('offers the Anthropic-compatible endpoint only where it exists', async () => {
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+
+    const anthropicOption = /use the anthropic-compatible endpoint/i
+    // Anthropic is already on that protocol, so there is nothing to opt into.
+    expect(screen.queryByLabelText(anthropicOption)).toBeNull()
+
+    await userEvent.selectOptions(screen.getByLabelText(/^provider type$/i), 'deepseek')
+    expect(screen.getByText(anthropicOption)).toBeInTheDocument()
+
+    // Ollama speaks only its own protocol, and its address may be private — pointing a
+    // Messages request at it would mean pointing it inside the network.
+    await userEvent.selectOptions(screen.getByLabelText(/^provider type$/i), 'ollama')
+    expect(screen.queryByText(anthropicOption)).toBeNull()
+  })
+
+  it('pre-ticks whether the model can see, by type', async () => {
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+
+    const seesImages = () => screen.getByLabelText(/this model can look at images/i)
+    expect(seesImages()).toBeChecked()
+
+    await userEvent.selectOptions(screen.getByLabelText(/^provider type$/i), 'deepseek')
+    expect(seesImages()).not.toBeChecked()
+  })
+
+  it('asks for a key everywhere except Ollama', async () => {
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+
+    expect(screen.getByLabelText(/provider api key/i)).toBeInTheDocument()
+
+    await userEvent.selectOptions(screen.getByLabelText(/^provider type$/i), 'ollama')
+    expect(screen.queryByLabelText(/provider api key/i)).toBeNull()
+    expect(screen.getByLabelText(/base url/i)).toBeInTheDocument()
+  })
+
+  it('refuses extra parameters that are not a JSON object', async () => {
+    const create = vi.spyOn(providersApi, 'create').mockResolvedValue(provider())
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+    await userEvent.type(screen.getByLabelText(/^name$/i), 'Claude')
+    await userEvent.type(
+      screen.getByLabelText(/^model name$/i),
+      'claude-sonnet-4-20250514'
+    )
+    // Valid JSON, wrong shape — the case a bare `JSON.parse` check would let through.
+    await userEvent.type(screen.getByLabelText(/extra parameters/i), '"temperature"')
+    await userEvent.click(screen.getByRole('button', { name: /save provider/i }))
+
+    expect(await screen.findByText(/must be a json object/i)).toBeInTheDocument()
+    expect(create).not.toHaveBeenCalled()
+  })
+
+  it('reports what a connection test found', async () => {
+    vi.spyOn(providersApi, 'test').mockResolvedValue({
+      success: false,
+      message: 'The API key was rejected',
+    })
+    render(<ProviderPanel />)
+    await screen.findByText(/no provider configured yet/i)
+
+    await userEvent.click(screen.getByRole('button', { name: /add a provider/i }))
+    await userEvent.type(
+      screen.getByLabelText(/^model name$/i),
+      'claude-sonnet-4-20250514'
+    )
+    await userEvent.click(screen.getByRole('button', { name: /test connection/i }))
+
+    expect(await screen.findByText(/the api key was rejected/i)).toBeInTheDocument()
+  })
+
+  it('tests a saved provider by id, so the stored key is used', async () => {
+    vi.spyOn(providersApi, 'list').mockResolvedValue([provider()])
+    const test = vi
+      .spyOn(providersApi, 'test')
+      .mockResolvedValue({ success: true, message: 'Connected' })
+    render(<ProviderPanel />)
+
+    await userEvent.click(await screen.findByRole('button', { name: /edit claude/i }))
+    await userEvent.click(screen.getByRole('button', { name: /test connection/i }))
+
+    await waitFor(() => expect(test).toHaveBeenCalled())
+    expect(test.mock.calls[0][0]).toMatchObject({ provider_id: 'p1' })
+  })
+
+  it('switches the active provider', async () => {
+    vi.spyOn(providersApi, 'list').mockResolvedValue([
+      provider({ id: 'p2', name: 'DeepSeek', is_active: false }),
+    ])
+    const activate = vi.spyOn(providersApi, 'activate').mockResolvedValue(provider())
+    render(<ProviderPanel />)
+
+    await userEvent.click(await screen.findByRole('button', { name: /use this one/i }))
+
+    await waitFor(() => expect(activate).toHaveBeenCalledWith('p2'))
+  })
+
+  it('shows no price, because this panel is configuration', async () => {
+    // Not because GAM refuses to show costs — it has a pricing table now and its own
+    // panel for spend. This one is about which model to use, and a figure here would be
+    // answering a question nobody asked while configuring a provider.
+    vi.spyOn(providersApi, 'list').mockResolvedValue([provider()])
+    render(<ProviderPanel />)
+
+    await screen.findByText('Claude')
+    expect(screen.queryByText(/\$/)).toBeNull()
+  })
+})
diff --git a/frontend/src/components/ProviderPanel.tsx b/frontend/src/components/ProviderPanel.tsx
new file mode 100644
index 0000000..c287392
--- /dev/null
+++ b/frontend/src/components/ProviderPanel.tsx
@@ -0,0 +1,579 @@
+import { useEffect, useState } from 'react'
+import { Check, Pencil, Plus, Sparkles, Trash2 } from 'lucide-react'
+import {
+  providersApi,
+  type AIProvider,
+  type ProviderTestResult,
+  type ProviderType,
+} from '@/api/providers'
+import { apiErrorMessage } from '@/api/client'
+import { useSavedFlash } from '@/utils/useSavedFlash'
+
+/**
+ * Configuring the model behind the assistant. Copied from GAM's provider panel.
+ *
+ * "Test connection" is here so a key and a model name can be checked before a turn
+ * exists to fail on them.
+ */
+
+const TYPES: ProviderType[] = ['anthropic', 'openai', 'deepseek', 'ollama', 'custom']
+
+const TYPE_LABELS: Record<ProviderType, string> = {
+  anthropic: 'Anthropic (Claude)',
+  openai: 'OpenAI',
+  deepseek: 'DeepSeek',
+  ollama: 'Ollama (runs locally)',
+  custom: 'Custom (OpenAI-compatible)',
+}
+
+// Per-type output-token defaults. The assistant's requests are not streamed, so a cap
+// much past 16000 risks a reply that outlasts the request timeout; a whole first draft
+// fits well inside it.
+const DEFAULT_MAX_TOKENS: Record<ProviderType, number> = {
+  anthropic: 16000,
+  openai: 16384,
+  deepseek: 8192,
+  ollama: 16384,
+  custom: 16384,
+}
+
+// Whether a type's typical model can look at a picture — used to pre-tick the box when
+// the user picks a type, not to decide for them. Anthropic and OpenAI are vision-capable
+// across their current models; DeepSeek chat is text-only, and local or self-hosted
+// models mostly are too, so those start off and the user ticks one on for llava or a
+// multimodal gateway.
+const DEFAULT_SUPPORTS_IMAGES: Record<ProviderType, boolean> = {
+  anthropic: true,
+  openai: true,
+  deepseek: false,
+  ollama: false,
+  custom: false,
+}
+
+const MODEL_PLACEHOLDERS: Record<ProviderType, string> = {
+  anthropic: 'claude-opus-5-5',
+  openai: 'gpt-4.1',
+  deepseek: 'deepseek-chat',
+  ollama: 'qwen3',
+  custom: 'model-name',
+}
+
+/**
+ * Which types can be pointed at an Anthropic-compatible endpoint instead of their own.
+ * DeepSeek publishes one that runs its own server-side web search; a custom gateway may
+ * speak Messages too. Anthropic is already there, and Ollama speaks only its own
+ * protocol — and its address is allowed to be private, so aiming a Messages request at
+ * it would mean aiming it inside the network.
+ */
+const canUseAnthropicApi = (type: ProviderType) =>
+  type === 'deepseek' || type === 'custom'
+
+/** Only these have a base URL worth showing: the others resolve to fixed endpoints. */
+const hasBaseUrl = (type: ProviderType) =>
+  type === 'openai' || type === 'custom' || type === 'ollama'
+
+interface Form {
+  name: string
+  provider_type: ProviderType
+  api_key: string
+  base_url: string
+  model: string
+  max_tokens: number
+  supports_images: boolean
+  use_anthropic_api: boolean
+  extra_params: string
+}
+
+const emptyForm = (): Form => ({
+  name: '',
+  provider_type: 'anthropic',
+  api_key: '',
+  base_url: '',
+  model: '',
+  max_tokens: DEFAULT_MAX_TOKENS.anthropic,
+  supports_images: DEFAULT_SUPPORTS_IMAGES.anthropic,
+  use_anthropic_api: false,
+  extra_params: '',
+})
+
+export default function ProviderPanel() {
+  const [providers, setProviders] = useState<AIProvider[]>([])
+  const [showForm, setShowForm] = useState(false)
+  const [editingId, setEditingId] = useState<string | null>(null)
+  const [form, setForm] = useState<Form>(emptyForm())
+  const [saving, setSaving] = useState(false)
+  const [testing, setTesting] = useState(false)
+  const [testResult, setTestResult] = useState<ProviderTestResult | null>(null)
+  const [saved, flashSaved] = useSavedFlash()
+  const [error, setError] = useState<string | null>(null)
+
+  const load = () =>
+    providersApi
+      .list()
+      .then(setProviders)
+      .catch((err) => setError(apiErrorMessage(err, 'Could not load providers')))
+
+  useEffect(() => {
+    void load()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  function startAdd() {
+    setEditingId(null)
+    setForm(emptyForm())
+    setTestResult(null)
+    setError(null)
+    setShowForm(true)
+  }
+
+  function startEdit(provider: AIProvider) {
+    setEditingId(provider.id)
+    setForm({
+      name: provider.name,
+      provider_type: provider.provider_type,
+      // Never seeded from the server: it was never sent one. Empty means "leave the
+      // stored key alone", which is the same contract the request carries.
+      api_key: '',
+      base_url: provider.base_url ?? '',
+      model: provider.model,
+      max_tokens: provider.max_tokens,
+      supports_images: provider.supports_images,
+      use_anthropic_api: provider.use_anthropic_api,
+      extra_params: provider.extra_params
+        ? JSON.stringify(provider.extra_params, null, 2)
+        : '',
+    })
+    setTestResult(null)
+    setError(null)
+    setShowForm(true)
+  }
+
+  function changeType(provider_type: ProviderType) {
+    setForm((f) => ({
+      ...f,
+      provider_type,
+      max_tokens: DEFAULT_MAX_TOKENS[provider_type],
+      supports_images: DEFAULT_SUPPORTS_IMAGES[provider_type],
+      use_anthropic_api: canUseAnthropicApi(provider_type) ? f.use_anthropic_api : false,
+    }))
+    setTestResult(null)
+  }
+
+  /** null means the text was not a JSON object, which is not something to send. */
+  function parseExtraParams(): Record<string, unknown> | null {
+    const raw = form.extra_params.trim()
+    if (!raw) return {}
+    try {
+      const parsed = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null
+      return parsed as Record<string, unknown>
+    } catch {
+      return null
+    }
+  }
+
+  const save = async () => {
+    const extra_params = parseExtraParams()
+    if (extra_params === null) {
+      setError('Extra parameters must be a JSON object, like {"temperature": 0}')
+      return
+    }
+
+    setSaving(true)
+    setError(null)
+    try {
+      const payload = {
+        name: form.name.trim(),
+        provider_type: form.provider_type,
+        base_url: hasBaseUrl(form.provider_type) ? form.base_url.trim() || null : null,
+        model: form.model.trim(),
+        max_tokens: form.max_tokens,
+        supports_images: form.supports_images,
+        use_anthropic_api:
+          canUseAnthropicApi(form.provider_type) && form.use_anthropic_api,
+        extra_params,
+      }
+      if (editingId) {
+        // Omitted on edit unless the user typed one, so an unrelated change cannot wipe
+        // a stored key. Typing a space and deleting it is how you clear one.
+        await providersApi.update(editingId, {
+          ...payload,
+          ...(form.api_key ? { api_key: form.api_key } : {}),
+        })
+      } else {
+        await providersApi.create({ ...payload, api_key: form.api_key })
+      }
+      await load()
+      setShowForm(false)
+      setEditingId(null)
+      flashSaved()
+    } catch (err) {
+      setError(apiErrorMessage(err, 'Could not save the provider'))
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const test = async () => {
+    setTesting(true)
+    setTestResult(null)
+    try {
+      setTestResult(
+        await providersApi.test({
+          ...(editingId ? { provider_id: editingId } : {}),
+          provider_type: form.provider_type,
+          api_key: form.api_key,
+          base_url: hasBaseUrl(form.provider_type) ? form.base_url.trim() || null : null,
+          model: form.model.trim(),
+          use_anthropic_api:
+            canUseAnthropicApi(form.provider_type) && form.use_anthropic_api,
+        })
+      )
+    } catch (err) {
+      setTestResult({
+        success: false,
+        message: apiErrorMessage(err, 'Could not connect'),
+      })
+    } finally {
+      setTesting(false)
+    }
+  }
+
+  const activate = async (id: string) => {
+    setError(null)
+    try {
+      await providersApi.activate(id)
+      await load()
+    } catch (err) {
+      setError(apiErrorMessage(err, 'Could not activate the provider'))
+    }
+  }
+
+  const remove = async (provider: AIProvider) => {
+    if (!confirm(`Delete ${provider.name}?`)) return
+    setError(null)
+    try {
+      await providersApi.remove(provider.id)
+      await load()
+    } catch (err) {
+      setError(apiErrorMessage(err, 'Could not delete the provider'))
+    }
+  }
+
+  const canSave = form.name.trim() !== '' && form.model.trim() !== '' && !saving
+
+  return (
+    <section className="card space-y-4 p-5">
+      <header className="flex items-center gap-2">
+        <Sparkles className="h-4 w-4 text-gray-500" />
+        <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100">
+          AI provider
+        </h2>
+      </header>
+
+      <p className="text-xs text-gray-600 dark:text-gray-400">
+        The model behind the assistant, which drafts and edits videos. It has to be able
+        to call tools: any current Claude, GPT or DeepSeek model can, and so can most
+        recent Ollama models. Keep several and switch between them. Keys are encrypted
+        before they are stored and are never sent back to the browser.
+      </p>
+
+      {error && (
+        <p className="rounded-md border border-red-300 bg-red-50 px-3 py-2 text-xs text-red-800 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300">
+          {error}
+        </p>
+      )}
+
+      {providers.length === 0 && !showForm && (
+        <p className="text-xs text-amber-700 dark:text-amber-400">
+          No provider configured yet. The assistant needs one before it can draft or edit
+          a video.
+        </p>
+      )}
+
+      {providers.length > 0 && (
+        <ul className="space-y-2">
+          {providers.map((provider) => (
+            <li
+              key={provider.id}
+              className="flex items-center gap-3 rounded-md border border-gray-200 px-3 py-2 dark:border-gray-800"
+            >
+              <div className="min-w-0 flex-1">
+                <p className="flex items-center gap-2 text-sm font-medium text-gray-900 dark:text-gray-100">
+                  <span className="truncate">{provider.name}</span>
+                  {provider.is_active && (
+                    <span className="shrink-0 rounded bg-green-100 px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-green-700 dark:bg-green-900/30 dark:text-green-400">
+                      Active
+                    </span>
+                  )}
+                </p>
+                <p className="truncate text-xs text-gray-500 dark:text-gray-400">
+                  {TYPE_LABELS[provider.provider_type]} · {provider.model}
+                  {provider.supports_images && ' · can see images'}
+                  {provider.use_anthropic_api && ' · Messages protocol'}
+                </p>
+              </div>
+
+              {!provider.is_active && (
+                <button
+                  type="button"
+                  className="btn btn-ghost text-xs"
+                  onClick={() => void activate(provider.id)}
+                >
+                  Use this one
+                </button>
+              )}
+              <button
+                type="button"
+                className="btn btn-ghost p-1.5"
+                aria-label={`Edit ${provider.name}`}
+                onClick={() => startEdit(provider)}
+              >
+                <Pencil className="h-3.5 w-3.5" />
+              </button>
+              <button
+                type="button"
+                className="btn btn-ghost p-1.5 text-red-600 dark:text-red-400"
+                aria-label={`Delete ${provider.name}`}
+                onClick={() => void remove(provider)}
+              >
+                <Trash2 className="h-3.5 w-3.5" />
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {!showForm && (
+        <button type="button" className="btn btn-secondary" onClick={startAdd}>
+          <Plus className="mr-1.5 h-3.5 w-3.5" />
+          Add a provider
+        </button>
+      )}
+
+      {showForm && (
+        <div className="space-y-3 border-t border-gray-100 pt-4 dark:border-gray-800">
+          <div>
+            <label className="label" htmlFor="provider-name">
+              Name
+            </label>
+            <input
+              id="provider-name"
+              className="input"
+              placeholder="Claude"
+              value={form.name}
+              onChange={(e) => setForm({ ...form, name: e.target.value })}
+            />
+          </div>
+
+          <div>
+            {/* "Provider type", not "Provider": the embedding panel on the same page
+                already has a field labelled that, and two identical labels are
+                ambiguous to anyone navigating the page by label. */}
+            <label className="label" htmlFor="provider-type">
+              Provider type
+            </label>
+            <select
+              id="provider-type"
+              className="input"
+              value={form.provider_type}
+              onChange={(e) => changeType(e.target.value as ProviderType)}
+            >
+              {TYPES.map((type) => (
+                <option key={type} value={type}>
+                  {TYPE_LABELS[type]}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div>
+            {/* "Model name", not "Model": the settings page shows a transcription model
+                and an embedding model too, and three fields labelled the same thing is
+                ambiguous to anyone reading the page through a screen reader. */}
+            <label className="label" htmlFor="provider-model">
+              Model name
+            </label>
+            <input
+              id="provider-model"
+              className="input"
+              placeholder={MODEL_PLACEHOLDERS[form.provider_type]}
+              value={form.model}
+              onChange={(e) => setForm({ ...form, model: e.target.value })}
+            />
+            <p className="mt-1.5 text-xs text-gray-500 dark:text-gray-400">
+              Typed, not picked from a list — models ship faster than this app is
+              redeployed.
+            </p>
+          </div>
+
+          {form.provider_type !== 'ollama' && (
+            <div>
+              <label className="label" htmlFor="provider-key">
+                Provider API key
+              </label>
+              <input
+                id="provider-key"
+                type="password"
+                className="input"
+                autoComplete="off"
+                placeholder={
+                  editingId ? 'Leave blank to keep the stored key' : 'Paste your key'
+                }
+                value={form.api_key}
+                onChange={(e) => setForm({ ...form, api_key: e.target.value })}
+              />
+            </div>
+          )}
+
+          {hasBaseUrl(form.provider_type) && (
+            <div>
+              <label className="label" htmlFor="provider-base-url">
+                Base URL
+              </label>
+              <input
+                id="provider-base-url"
+                type="url"
+                className="input"
+                placeholder={
+                  form.provider_type === 'ollama'
+                    ? 'http://localhost:11434'
+                    : 'https://api.openai.com'
+                }
+                value={form.base_url}
+                onChange={(e) => setForm({ ...form, base_url: e.target.value })}
+              />
+              <p className="mt-1.5 text-xs text-gray-500 dark:text-gray-400">
+                {form.provider_type === 'ollama'
+                  ? 'Where Ollama is listening. A local address is expected here.'
+                  : 'Optional. Leave blank for the provider’s own endpoint.'}
+              </p>
+            </div>
+          )}
+
+          <div>
+            <label className="label" htmlFor="provider-max-tokens">
+              Maximum response length
+            </label>
+            <input
+              id="provider-max-tokens"
+              type="number"
+              className="input"
+              min={1}
+              max={200000}
+              value={form.max_tokens}
+              onChange={(e) =>
+                setForm({ ...form, max_tokens: Number(e.target.value) || 1 })
+              }
+            />
+          </div>
+
+          <label className="flex items-start gap-2 text-xs text-gray-700 dark:text-gray-300">
+            <input
+              type="checkbox"
+              className="mt-0.5"
+              checked={form.supports_images}
+              onChange={(e) => setForm({ ...form, supports_images: e.target.checked })}
+            />
+            <span>
+              This model can look at images
+              <span className="block text-gray-500 dark:text-gray-400">
+                Text-only models reject a picture with an unreadable error from upstream,
+                so the assistant only shows pictures to providers marked here.
+              </span>
+            </span>
+          </label>
+
+          {canUseAnthropicApi(form.provider_type) && (
+            <label className="flex items-start gap-2 text-xs text-gray-700 dark:text-gray-300">
+              <input
+                type="checkbox"
+                className="mt-0.5"
+                checked={form.use_anthropic_api}
+                onChange={(e) =>
+                  setForm({ ...form, use_anthropic_api: e.target.checked })
+                }
+              />
+              <span>
+                Use the Anthropic-compatible endpoint
+                <span className="block text-gray-500 dark:text-gray-400">
+                  DeepSeek publishes one that runs the same server-side web search Claude
+                  does — no separate search key, no per-search fee. Its ordinary endpoint
+                  has no such tool.
+                </span>
+              </span>
+            </label>
+          )}
+
+          <div>
+            <label className="label" htmlFor="provider-extra-params">
+              Extra parameters
+            </label>
+            <textarea
+              id="provider-extra-params"
+              className="input font-mono text-xs"
+              rows={3}
+              placeholder='{"temperature": 0}'
+              value={form.extra_params}
+              onChange={(e) => setForm({ ...form, extra_params: e.target.value })}
+            />
+            <p className="mt-1.5 text-xs text-gray-500 dark:text-gray-400">
+              A JSON object merged into each request. Leave blank for none.
+            </p>
+          </div>
+
+          {testResult && (
+            <p
+              className={
+                testResult.success
+                  ? 'flex items-center gap-1.5 text-xs text-green-700 dark:text-green-400'
+                  : 'text-xs text-red-700 dark:text-red-400'
+              }
+            >
+              {testResult.success && <Check className="h-3.5 w-3.5" />}
+              {testResult.message}
+            </p>
+          )}
+
+          <div className="flex gap-2">
+            <button
+              type="button"
+              className="btn btn-primary"
+              disabled={!canSave}
+              onClick={() => void save()}
+            >
+              {saving ? 'Saving…' : 'Save provider'}
+            </button>
+            <button
+              type="button"
+              className="btn btn-secondary"
+              disabled={!form.model.trim() || testing}
+              onClick={() => void test()}
+            >
+              {testing ? 'Testing…' : 'Test connection'}
+            </button>
+            <button
+              type="button"
+              className="btn btn-ghost"
+              onClick={() => {
+                setShowForm(false)
+                setEditingId(null)
+                setError(null)
+              }}
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      )}
+
+      {saved && (
+        <p className="flex items-center gap-1.5 text-xs text-green-700 dark:text-green-400">
+          <Check className="h-3.5 w-3.5" />
+          Saved
+        </p>
+      )}
+    </section>
+  )
+}
diff --git a/frontend/src/components/UsagePanel.test.tsx b/frontend/src/components/UsagePanel.test.tsx
new file mode 100644
index 0000000..409c997
--- /dev/null
+++ b/frontend/src/components/UsagePanel.test.tsx
@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { usageApi } from '@/api/usage'
+import UsagePanel from '@/components/UsagePanel'
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('UsagePanel', () => {
+  it('says the total is an estimate, and a floor when some calls were not priced', async () => {
+    vi.spyOn(usageApi, 'summary').mockResolvedValue({
+      totals: {
+        total_events: 3,
+        priced_events: 2,
+        cost: 0.0042,
+        currency: 'USD',
+        estimated: true,
+        tokens: 12000,
+      },
+      by_provider: [
+        {
+          provider: 'anthropic',
+          model: 'claude-opus-5-5',
+          events: 2,
+          units: 11000,
+          cost: 0.0042,
+        },
+        { provider: 'custom', model: 'x', events: 1, units: 1000, cost: null },
+      ],
+    })
+    render(<UsagePanel />)
+    expect(await screen.findAllByText('$0.0042')).toHaveLength(2)
+    expect(screen.getByText(/not a bill/)).toBeInTheDocument()
+    expect(screen.getByText('1 call, not priced')).toBeInTheDocument()
+    expect(screen.getByText(/total\s+is a floor/)).toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/UsagePanel.tsx b/frontend/src/components/UsagePanel.tsx
new file mode 100644
index 0000000..3872e77
--- /dev/null
+++ b/frontend/src/components/UsagePanel.tsx
@@ -0,0 +1,78 @@
+import { useEffect, useState } from 'react'
+import { Receipt } from 'lucide-react'
+import { apiErrorMessage } from '@/api/client'
+import { formatCost, usageApi, type UsageSummary } from '@/api/usage'
+
+/** What the assistant has cost so far, always said to be an estimate. */
+export default function UsagePanel() {
+  const [summary, setSummary] = useState<UsageSummary | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let live = true
+    usageApi
+      .summary()
+      .then((s) => live && setSummary(s))
+      .catch((err) => live && setError(apiErrorMessage(err)))
+    return () => {
+      live = false
+    }
+  }, [])
+
+  const totals = summary?.totals
+  const unpriced = totals ? totals.total_events - totals.priced_events : 0
+
+  return (
+    <section className="card space-y-3 p-5" aria-label="Spend">
+      <header className="flex items-center gap-2">
+        <Receipt className="h-4 w-4 text-gray-500" />
+        <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100">
+          What the assistant has cost
+        </h2>
+      </header>
+      {error && <p className="text-xs text-red-700 dark:text-red-400">{error}</p>}
+      {totals && totals.total_events === 0 && (
+        <p className="text-xs text-gray-600 dark:text-gray-400">Nothing yet.</p>
+      )}
+      {totals && totals.total_events > 0 && (
+        <>
+          <div>
+            <p className="text-2xl font-semibold text-gray-900 dark:text-gray-100">
+              {formatCost(totals.cost, totals.currency)}
+            </p>
+            <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+              An estimate from published list prices, not a bill. Check your
+              provider&apos;s dashboard for what you were charged.
+            </p>
+          </div>
+          <dl className="space-y-1 border-t border-gray-100 pt-3 text-xs dark:border-gray-800">
+            <div className="flex justify-between">
+              <dt className="text-gray-500 dark:text-gray-400">Tokens</dt>
+              <dd className="text-gray-900 dark:text-gray-100">
+                {totals.tokens.toLocaleString()}
+              </dd>
+            </div>
+            {summary.by_provider.map((row) => (
+              <div key={`${row.provider}/${row.model}`} className="flex justify-between">
+                <dt className="text-gray-500 dark:text-gray-400">
+                  {row.model || row.provider}
+                </dt>
+                <dd className="text-gray-900 dark:text-gray-100">
+                  {row.cost === null
+                    ? `${row.events} call${row.events === 1 ? '' : 's'}, not priced`
+                    : formatCost(row.cost, totals.currency)}
+                </dd>
+              </div>
+            ))}
+          </dl>
+          {unpriced > 0 && (
+            <p className="text-xs text-amber-700 dark:text-amber-400">
+              {unpriced} call{unpriced === 1 ? '' : 's'} could not be priced, so the total
+              is a floor.
+            </p>
+          )}
+        </>
+      )}
+    </section>
+  )
+}
diff --git a/frontend/src/utils/useSavedFlash.ts b/frontend/src/utils/useSavedFlash.ts
new file mode 100644
index 0000000..b63b70c
--- /dev/null
+++ b/frontend/src/utils/useSavedFlash.ts
@@ -0,0 +1,19 @@
+import { useState } from 'react'
+
+/**
+ * A saved-tick that clears itself.
+ *
+ * Lives here rather than in SettingsView because every settings panel wants it, and the
+ * provider panel is in its own file — importing it back out of the view that renders it
+ * would be a cycle.
+ */
+export function useSavedFlash(): [boolean, () => void] {
+  const [saved, setSaved] = useState(false)
+  return [
+    saved,
+    () => {
+      setSaved(true)
+      setTimeout(() => setSaved(false), 2000)
+    },
+  ]
+}
diff --git a/frontend/src/views/SettingsView.tsx b/frontend/src/views/SettingsView.tsx
new file mode 100644
index 0000000..949c5c7
--- /dev/null
+++ b/frontend/src/views/SettingsView.tsx
@@ -0,0 +1,13 @@
+import ProviderPanel from '@/components/ProviderPanel'
+import UsagePanel from '@/components/UsagePanel'
+
+/** GVC's own settings: the assistant's AI provider, and what it has spent. */
+export default function SettingsView() {
+  return (
+    <div className="mx-auto max-w-3xl space-y-6 p-6">
+      <h2 className="text-lg font-semibold text-gray-900 dark:text-gray-100">Settings</h2>
+      <ProviderPanel />
+      <UsagePanel />
+    </div>
+  )
+}

From f3408786df9a7dfe364cc94018600285635cb468 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 10:40:10 +0000
Subject: [PATCH 2/2] M4/M5 part 2: the video assistant

An assistant beside every page, collapsible as in Notes, that knows the
whole VideoSpec: it drafts a video from a prompt and the GAM library,
or makes any edit to the one open.

- Tools: the Notes spec doc's 8.2 operations, addressed by id, over a
  working copy of the spec. Every edit is validated as it is made and
  the issues go back to the model; a valid spec is never broken, a
  draft with mistakes is repaired step by step.
- A turn is a background job: prompt, starting draft, steps, reply and
  proposal live on its row, so it finishes with the page closed and
  waits for Apply. The caller's token stays in memory only; a restart
  ends a turn and says so.
- The proposal applies into the editor's draft (or, from the project
  list, becomes a new project with source brief and author ai), with a
  warning when the project was saved in between.
- A header marker shows a turn running or waiting anywhere in the app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fiRJAt34ag62iPiuMkNhm
---
 README.md                                     |  11 +-
 ...7_add_assistant_session_and_turn_tables.py |  84 +++
 backend/app/assistant/__init__.py             |   1 +
 backend/app/assistant/loop.py                 |  87 +++
 backend/app/assistant/prompt.py               | 155 +++++
 backend/app/assistant/tools.py                | 635 ++++++++++++++++++
 backend/app/assistant/worker.py               | 194 ++++++
 backend/app/config.py                         |   9 +
 backend/app/main.py                           |   6 +
 backend/app/models/__init__.py                |   3 +-
 backend/app/models/assistant.py               |  66 ++
 backend/app/providers/anthropic.py            |   4 +
 backend/app/providers/base.py                 |   4 +
 backend/app/providers/openai.py               |   4 +
 backend/app/routers/assistant.py              | 270 ++++++++
 backend/app/schemas_assistant.py              |  73 ++
 backend/app/services/projects.py              |  11 +-
 backend/tests/conftest.py                     |   5 +
 backend/tests/fake_provider.py                |  62 ++
 backend/tests/test_assistant_tools.py         | 181 +++++
 backend/tests/test_assistant_turns.py         | 296 ++++++++
 docs/plan-of-attack.md                        |  12 +-
 frontend/src/api/assistant.ts                 | 135 ++++
 frontend/src/components/AppShell.tsx          |   9 +-
 frontend/src/components/AssistantMarker.tsx   |  46 ++
 .../src/components/AssistantPanel.test.tsx    | 197 ++++++
 frontend/src/components/AssistantPanel.tsx    | 513 ++++++++++++++
 frontend/src/components/ProviderPanel.tsx     |   3 -
 frontend/src/components/SceneList.tsx         |   5 +
 frontend/src/stores/assistant.ts              | 288 ++++++++
 frontend/src/stores/auth.ts                   |   2 +
 frontend/tsconfig.node.tsbuildinfo            |   1 +
 frontend/tsconfig.tsbuildinfo                 |   1 +
 frontend/vite.config.d.ts                     |   2 +
 frontend/vite.config.js                       |  36 +
 35 files changed, 3400 insertions(+), 11 deletions(-)
 create mode 100644 backend/alembic/versions/20261016_1027_add_assistant_session_and_turn_tables.py
 create mode 100644 backend/app/assistant/__init__.py
 create mode 100644 backend/app/assistant/loop.py
 create mode 100644 backend/app/assistant/prompt.py
 create mode 100644 backend/app/assistant/tools.py
 create mode 100644 backend/app/assistant/worker.py
 create mode 100644 backend/app/models/assistant.py
 create mode 100644 backend/app/routers/assistant.py
 create mode 100644 backend/app/schemas_assistant.py
 create mode 100644 backend/tests/fake_provider.py
 create mode 100644 backend/tests/test_assistant_tools.py
 create mode 100644 backend/tests/test_assistant_turns.py
 create mode 100644 frontend/src/api/assistant.ts
 create mode 100644 frontend/src/components/AssistantMarker.tsx
 create mode 100644 frontend/src/components/AssistantPanel.test.tsx
 create mode 100644 frontend/src/components/AssistantPanel.tsx
 create mode 100644 frontend/src/stores/assistant.ts
 create mode 100644 frontend/tsconfig.node.tsbuildinfo
 create mode 100644 frontend/tsconfig.tsbuildinfo
 create mode 100644 frontend/vite.config.d.ts
 create mode 100644 frontend/vite.config.js

diff --git a/README.md b/README.md
index 3b47b38..a3d7e67 100644
--- a/README.md
+++ b/README.md
@@ -28,8 +28,15 @@ GAM by what is said in it. Then preview and render it:
 - text, lower thirds and pictures on screen, timed to the scenes and lines they belong to;
 - end credits from the library's attribution, and a description with chapters and credits.
 
-A finished render can be saved back into GAM. AI drafting and the full storyboard
-editor are next (M3, M4).
+A finished render can be saved back into GAM.
+
+**The assistant (M4/M5).** A panel beside every page that knows the whole video format.
+Describe a video and it drafts one from your GAM library, or ask for any change to the
+one open. What it would change is listed for you to apply or discard. It runs in the
+background, so a request finishes with the page closed. Set up its AI provider
+(Anthropic, OpenAI, DeepSeek, Ollama or a custom endpoint) under Settings.
+
+The full storyboard editor is next (M3).
 
 ## Read first
 
diff --git a/backend/alembic/versions/20261016_1027_add_assistant_session_and_turn_tables.py b/backend/alembic/versions/20261016_1027_add_assistant_session_and_turn_tables.py
new file mode 100644
index 0000000..e2997f7
--- /dev/null
+++ b/backend/alembic/versions/20261016_1027_add_assistant_session_and_turn_tables.py
@@ -0,0 +1,84 @@
+"""Add the assistant_session and assistant_turn tables (M4/M5).
+
+A turn is a job, so it carries the job fields the runner reads (status, stage,
+progress, detail, error_message, updated_at) next to everything the turn is: its
+prompt, the draft it started from, its steps, its reply and its proposal.
+
+Revision ID: 9b3e7d215f60
+Revises: 4a8c2f6e9d13
+Create Date: 2026-10-16 10:27:22.137896+00:00
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+revision: str = '9b3e7d215f60'
+down_revision: Union[str, None] = '4a8c2f6e9d13'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table('assistant_session',
+    sa.Column('id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('user_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('project_id', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('title', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('messages', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('assistant_session', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_assistant_session_project_id'), ['project_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_assistant_session_user_id'), ['user_id'], unique=False)
+
+    op.create_table('assistant_turn',
+    sa.Column('id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('session_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('user_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('project_id', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('stage', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('progress', sa.Integer(), nullable=False),
+    sa.Column('detail', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('error_message', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('prompt', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('base_spec', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('base_version', sa.Integer(), nullable=True),
+    sa.Column('focus', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('steps', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('reply', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('proposed_spec', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('changes', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('outcome', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('cost', sa.Float(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['session_id'], ['assistant_session.id'], ),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('assistant_turn', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_assistant_turn_project_id'), ['project_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_assistant_turn_session_id'), ['session_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_assistant_turn_user_id'), ['user_id'], unique=False)
+
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('assistant_turn', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_assistant_turn_user_id'))
+        batch_op.drop_index(batch_op.f('ix_assistant_turn_session_id'))
+        batch_op.drop_index(batch_op.f('ix_assistant_turn_project_id'))
+
+    op.drop_table('assistant_turn')
+    with op.batch_alter_table('assistant_session', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_assistant_session_user_id'))
+        batch_op.drop_index(batch_op.f('ix_assistant_session_project_id'))
+
+    op.drop_table('assistant_session')
diff --git a/backend/app/assistant/__init__.py b/backend/app/assistant/__init__.py
new file mode 100644
index 0000000..3ddaa85
--- /dev/null
+++ b/backend/app/assistant/__init__.py
@@ -0,0 +1 @@
+"""The video assistant: tools over a working copy of the spec, a loop, a job (M4/M5)."""
diff --git a/backend/app/assistant/loop.py b/backend/app/assistant/loop.py
new file mode 100644
index 0000000..9b8917a
--- /dev/null
+++ b/backend/app/assistant/loop.py
@@ -0,0 +1,87 @@
+"""One turn: the model and the tools, round after round, until the model is done.
+
+Pure of the database and the job queue (`worker.py` owns those), so a whole turn can be
+run in a test against a scripted provider.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Sequence, Tuple
+
+from app.assistant import tools as T
+from app.assistant.tools import Working, _issues_text
+from app.providers.base import ChatProvider, Reply
+
+logger = logging.getLogger(__name__)
+
+# Times the loop tells a model that stopped with the video still invalid to fix it.
+# Past that it would only be spending the user's money to repeat itself.
+MAX_REPAIR_NUDGES = 2
+
+Step = Callable[[str, str], None]
+
+
+class Stopped(Exception):
+    """The user pressed Stop."""
+
+
+@dataclass
+class Outcome:
+    reply: str
+    # Set when the turn ran out of rounds or output before finishing on its own.
+    cut_short: Optional[str] = None
+    replies: List[Reply] = field(default_factory=list)
+
+
+def _first_line(text: str) -> str:
+    return text.split("\n", 1)[0].strip()
+
+
+def run(provider: ChatProvider, working: Working, *, system: Sequence[str],
+        history: Sequence[Tuple[str, str]], prompt: str, on_step: Step,
+        on_reply: Callable[[Reply], None], cancelled: Callable[[], bool],
+        max_rounds: int) -> Outcome:
+    conversation = provider.conversation(system=system, tools=T.SPECS, history=history,
+                                         prompt=prompt)
+    outcome = Outcome(reply="")
+    nudges = 0
+    for _ in range(max_rounds):
+        if cancelled():
+            raise Stopped()
+        reply = conversation.ask()
+        outcome.replies.append(reply)
+        on_reply(reply)
+        if reply.text:
+            outcome.reply = reply.text
+        if not reply.tool_calls:
+            if reply.stop == "max_tokens":
+                outcome.cut_short = ("The reply hit the provider's output limit. Raise the "
+                                     "maximum response length in Settings, or ask for less "
+                                     "at once.")
+                return outcome
+            if working.issues and working.changes and nudges < MAX_REPAIR_NUDGES:
+                nudges += 1
+                on_step("issue", f"{len(working.issues)} issue(s) left to fix")
+                conversation.tell("The video still has issues, so it can't be proposed yet. "
+                                  "Fix these, then finish:\n" + _issues_text(working.issues))
+                continue
+            return outcome
+        if reply.text:
+            on_step("think", reply.text)
+        results = []
+        for call in reply.tool_calls:
+            if cancelled():
+                raise Stopped()
+            if call.name == "search_assets":
+                on_step("search", f"Searching the library: {call.arguments.get('query', '')!r}")
+            result = T.execute(working, call)
+            results.append(result)
+            if call.name in T.READS:
+                continue
+            on_step("issue" if result.is_error else "edit", _first_line(result.content))
+        conversation.answer(results)
+    outcome.cut_short = (f"Stopped after {max_rounds} rounds without finishing. What it had "
+                         "done so far is below; ask again to carry on.")
+    return outcome
diff --git a/backend/app/assistant/prompt.py b/backend/app/assistant/prompt.py
new file mode 100644
index 0000000..beedf5a
--- /dev/null
+++ b/backend/app/assistant/prompt.py
@@ -0,0 +1,155 @@
+"""What the assistant is told, in two blocks.
+
+1. `REFERENCE`: who it is and how a VideoSpec works. Fixed text, so a provider that caches
+   prompts reads it at the cached rate on every turn of every session.
+2. `context(...)`: this project as it stands. Fixed for one turn, so the rounds of a turn
+   share its cache too.
+
+The reference is written for a capable model: it says what the format means and what
+good work looks like, not a checklist of commands. The schema itself is the authority,
+and every edit is validated against it, so the reference doesn't try to restate every
+field and range.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+REFERENCE = """\
+You are the editor inside Gecko Video Creator (GVC), working with the user on one narrated \
+video. You can build a video from nothing, from a brief, or from material in their asset \
+library (GAM), and you can make any change to an existing one. You work by calling tools \
+that edit a working copy of the video. Nothing you do reaches the project until the user \
+presses Apply on what you propose, so make the edits the request needs, then say what you \
+changed.
+
+## How a video is described (VideoSpec 0.2)
+A video is one JSON document:
+- `title`, and project-wide `output` (aspect 16:9 / 9:16 / 1:1, resolution, subtitles, \
+chapters), `voice` (speed, pauses; leave `voice.voice` unset to use the account's voice), \
+`style`, `chrome`, `credits`.
+- `assets`: a registry of named keys. Library files are `{"from":"gam","id":<gam_id>,\
+"type":"image"|"video"|"audio","label":...}`. Placeholders are `{"from":"search","query":...}` \
+(footage still to find) or `{"from":"generate","type":"image",...,"prompt":...}`. Segments \
+and tracks refer to assets by key, never by gam_id directly.
+- `segments`, in order. Each has a stable `id`, a `label`, and a `kind`:
+  - `scene`: a `visual` (a still or muted b-roll video) with `narration.beats` read over it. \
+Each beat is one line or paragraph of script: `{"id":"b1","text":"..."}`. A scene lasts as \
+long as its narration, at least `style.min_segment_seconds`.
+  - `card`: a title or chapter screen: `{"card":{"variant":"title"|"chapter","title":...,\
+"subtitle":...}}`. May have narration too.
+  - `clip`: a video played with its own sound and no narration: `visual` with `trim` and \
+`"audio":"play"`.
+  - Optional: `chapter` (a chapter mark at its start), `transition_in`, `duration` \
+(`min` or `fixed` seconds), `overlays`, `role` (title / intro / outro).
+- `audio_tracks`: music, sound effects or extra voice, each from a `start` anchor to an \
+`end` anchor (omit `end` to play once to its natural end), with `volume` (0-1; music \
+usually 0.12-0.2 under narration), `fade_in` / `fade_out` seconds, `duck_under_narration`, \
+`loop`.
+
+## Time is anchored to structure, not seconds
+An anchor is `"video_start"`, `"video_end"`, or `{"segment":id,"beat":id?,"edge":"start"|\
+"end","offset":seconds}`. Inside a segment's overlay, a missing `segment` means that segment. \
+Anchoring to structure is what keeps music and overlays on the right cut when scenes are \
+reworded or moved, so always anchor; never compute seconds yourself.
+- Change the music partway through: end track 1 at a segment's start and start track 2 \
+there. For a crossfade, start track 2 a few seconds early (negative offset) with a matching \
+`fade_in`, and give track 1 the same `fade_out` with its end a few seconds late.
+
+## Transitions
+`style.transition` is the default join `{style, duration}`; a segment's `transition_in` \
+overrides it field by field. Styles: `none` (a cut), dips that pass through a colour \
+(`fade` to black, `fadewhite`), and blends that overlap the two shots (`dissolve`, \
+`slideleft`/`slideright`, `wipeleft`/`wiperight`, `circleopen`, `smoothleft`). A blend can \
+take at most half of the shorter shot. Use cuts within a sequence, dissolves for a change of \
+place or time, and a fade to black for a change of chapter or mood.
+
+## Pictures and movement
+`visual`: `{"asset":key,"fit":"blur"|"pad"|"crop","motion":...,"trim":{"in":s,"out":s},\
+"loop":true}`. On a still, `motion` is a Ken Burns move: presets `zoom_in`, `zoom_out`, \
+`pan_left`, `pan_right`, `pan_up`, `pan_down` with `amount` (0.02-0.5), or a two-frame path \
+`{"effect":"path","from":{"x":0,"y":0,"w":1},"to":{"x":0.55,"y":0.3,"w":0.35},\
+"ease":"in_out"}` that drifts from one crop of the picture to another (fractions of the \
+picture; the height follows the output's aspect). Use a path to move the eye to the part of \
+a picture the narration is about. `style.motion` `alternate` cycles the presets for stills \
+with no motion of their own.
+
+## On screen
+`overlays` on a segment, each with an `id`, an optional `show {from, to}` (default: the whole \
+segment; `to` may reach into a later segment to hold something across a transition), and \
+`fade` seconds:
+- `{"type":"lower_third","title":"Name","subtitle":"Role"}`: for whoever is speaking in a clip.
+- `{"type":"text","text":...,"position":"top-left"|...|"center","size_pct":6}`.
+- `{"type":"image","asset":key,"position":...,"scale_pct":25,"opacity":1}`.
+- `{"type":"quote","text":...,"attribution":...}` and `{"type":"code",...}`: full-screen \
+panels. Anchored to a beat, they cut the scene so the quote gets its own shot.
+
+## Credits
+`credits {"auto":true,"card":true,"description":true,"extra":[...]}` adds an end card and a \
+description crediting each library asset (from its attribution in GAM) plus `extra` lines. \
+Suggest it when the video uses others' material.
+
+## The library
+Use `search_assets` before choosing any picture, footage or music. It searches names, \
+descriptions and what is said in videos: a hit with `said_at` is the moment someone says it, \
+and `set_visual` with that hit's gam_id cuts to that moment for you. Search in a few \
+different phrasings when the first finds little. Prefer real assets; when nothing fits, \
+`add_placeholder` with a clear description of what to find or generate. Never invent a \
+gam_id or an asset key that isn't in the registry.
+
+## Pacing
+Narration reads at about 15 characters a second. A 3-minute video is about 2,500 characters \
+of narration over 10-20 segments. Keep beats to one or two sentences each so pictures can \
+change with the script. Open with a title card; use chapter cards for long videos.
+
+## Working
+- For a new video or a full rewrite, search the library first, then write the whole draft \
+with `replace_spec` in one call, then fix any issues it reports. For anything smaller, use \
+the targeted tools; don't rewrite what you weren't asked to change.
+- Keep existing ids. Give new segments ids like `s_market`, beats `b1`, `b2`…, overlays \
+`o_name`, tracks `m_theme`.
+- Every edit is checked as you make it. When a result lists issues, fix them before you \
+finish; a video with issues can't be proposed.
+- "This scene" means the focused segment, when one is given below.
+- If the request is a question rather than a change, answer it without editing.
+- Finish with a short reply in plain prose: what you made or changed and anything the user \
+should check (placeholders to fill, pictures to look at). Don't list every tool call; the \
+user sees the changes separately.
+"""
+
+
+def _registry_lines(data: Dict[str, Any]) -> str:
+    lines = []
+    for key, ref in (data.get("assets") or {}).items():
+        source = ref.get("from")
+        if source == "gam":
+            lines.append(f"- {key}: library {ref.get('type') or 'asset'} "
+                         f"{ref.get('label') or ''} (gam_id {ref.get('id')})".rstrip())
+        elif source == "search":
+            lines.append(f"- {key}: placeholder, footage to find: {ref.get('query')!r}")
+        elif source == "generate":
+            lines.append(f"- {key}: placeholder, to generate: {ref.get('prompt')!r}")
+        elif source == "notes":
+            lines.append(f"- {key}: a file still in Gecko Notes ({ref.get('label') or ref.get('url')})")
+    return "\n".join(lines) or "(empty)"
+
+
+def context(data: Dict[str, Any], *, focus: Optional[str], from_scratch: bool,
+            attached: Optional[str] = None) -> str:
+    """This project, for this turn."""
+    parts = []
+    if from_scratch:
+        parts.append("This is a new video: the working copy is a blank starter. Build it "
+                     "from the user's request.")
+    if focus:
+        label = next((s.get("label") for s in data.get("segments", [])
+                      if s.get("id") == focus), None)
+        parts.append(f"Focused segment (\"this scene\"): {focus}"
+                     + (f" ({label})" if label else ""))
+    if attached:
+        parts.append("The user attached these library assets to start from:\n" + attached)
+    parts.append("Asset registry:\n" + _registry_lines(data))
+    parts.append("The video now (VideoSpec JSON):\n"
+                 + json.dumps(data, ensure_ascii=False, separators=(",", ":")))
+    return "\n\n".join(parts)
diff --git a/backend/app/assistant/tools.py b/backend/app/assistant/tools.py
new file mode 100644
index 0000000..690e3c9
--- /dev/null
+++ b/backend/app/assistant/tools.py
@@ -0,0 +1,635 @@
+"""The assistant's operations on a video: the Notes spec doc's §8.2, addressed by id.
+
+Every edit works on a `Working` copy of the spec, never on the project. Nothing reaches
+the project until a person applies the proposal the turn ends with.
+
+Each edit is checked with `parse_spec` the moment it is made, and the issues go straight
+back to the model as the tool's result, so a mistake is fixed in the same turn by the
+same model that made it. That is the plan of attack's "one repair round" (D2),
+generalised to every edit rather than only a first draft.
+
+Two rules decide what an edit that produces issues does:
+- **A valid spec stays valid.** An edit that would break it is refused, and the spec is
+  left as it was, so a slip can't wreck a working video.
+- **An invalid spec can be repaired step by step.** After `replace_spec` with mistakes
+  in it, each edit is accepted while issues remain, and the result says which are left.
+
+Items are addressed by their ids, never by list position. JSON Patch indexes (the Notes
+spec doc, open decision 14) point at the wrong item as soon as something is reordered.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from app.gam.client import GamClient, GamError
+from app.providers.base import ToolCall, ToolResult, ToolSpec
+from app.render.estimate import estimate
+from app.spec.validation import SpecIssue, parse_spec
+
+# A found moment is padded so a cut doesn't clip a word: the editor's `momentTrim`.
+MOMENT_PAD = 0.5
+DEFAULT_MOMENT_SECONDS = 5.0
+MAX_SEARCH_HITS = 12
+
+
+class ToolFailed(Exception):
+    """The call can't be done as asked; the message goes back to the model."""
+
+
+def _issues_text(issues: List[SpecIssue], limit: int = 20) -> str:
+    lines = [f"- {'.'.join(str(p) for p in i.path) or '(spec)'}: {i.message}"
+             for i in issues[:limit]]
+    if len(issues) > limit:
+        lines.append(f"- … and {len(issues) - limit} more")
+    return "\n".join(lines)
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", (text or "").lower()).strip("_")[:32]
+
+
+def merge(base: Any, changes: Any) -> Any:
+    """A JSON merge patch (RFC 7386): objects merge, a null removes, anything else
+    replaces. Lists are replaced whole, which is what "these are the beats" means."""
+    if not isinstance(changes, dict) or not isinstance(base, dict):
+        return copy.deepcopy(changes)
+    out = copy.deepcopy(base)
+    for key, value in changes.items():
+        if value is None:
+            out.pop(key, None)
+        else:
+            out[key] = merge(out.get(key), value)
+    return out
+
+
+@dataclass
+class Hit:
+    """What a search found, kept so `set_visual` can take its moment as the trim."""
+
+    gam_id: str
+    name: str
+    asset_type: str
+    duration: Optional[float]
+    start: Optional[float]
+    end: Optional[float]
+
+
+@dataclass
+class Working:
+    data: Dict[str, Any]
+    gam: Optional[GamClient] = None
+    changes: List[str] = field(default_factory=list)
+    hits: Dict[str, Hit] = field(default_factory=dict)
+    issues: List[SpecIssue] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.data = copy.deepcopy(self.data)
+        _, self.issues = parse_spec(self.data)
+
+    @property
+    def valid(self) -> bool:
+        return not self.issues
+
+    # ── lookups ──────────────────────────────────────────────────────────────
+
+    def segments(self) -> List[Dict[str, Any]]:
+        return self.data.setdefault("segments", [])
+
+    def segment(self, segment_id: str) -> Dict[str, Any]:
+        for segment in self.segments():
+            if segment.get("id") == segment_id:
+                return segment
+        known = ", ".join(s.get("id", "?") for s in self.segments()) or "none"
+        raise ToolFailed(f"No segment {segment_id!r}. The segments are: {known}.")
+
+    def index_of(self, segment_id: str) -> int:
+        return self.segments().index(self.segment(segment_id))
+
+    def name_of(self, segment: Dict[str, Any]) -> str:
+        return segment.get("label") or segment.get("id", "?")
+
+    def tracks(self) -> List[Dict[str, Any]]:
+        return self.data.setdefault("audio_tracks", [])
+
+    def track(self, track_id: str) -> Dict[str, Any]:
+        for track in self.tracks():
+            if track.get("id") == track_id:
+                return track
+        raise ToolFailed(f"No audio track {track_id!r}.")
+
+    def new_id(self, prefix: str, taken: List[str]) -> str:
+        n = len(taken) + 1
+        while f"{prefix}{n}" in taken:
+            n += 1
+        return f"{prefix}{n}"
+
+    def all_overlay_ids(self) -> List[str]:
+        return [o.get("id") for s in self.segments() for o in s.get("overlays", [])]
+
+    def register_gam(self, data: Dict[str, Any], gam_id: str, *,
+                     asset_type: Optional[str] = None, label: Optional[str] = None) -> str:
+        """The asset key for a GAM asset in `data`, added to its registry if new.
+
+        `data` rather than `self.data`: edits build a candidate and commit it whole, so
+        a refused edit leaves no stray registry entry behind.
+        """
+        assets = data.setdefault("assets", {})
+        for key, ref in assets.items():
+            if ref.get("from") == "gam" and ref.get("id") == gam_id:
+                return key
+        hit = self.hits.get(gam_id)
+        label = label or (hit.name if hit else None)
+        asset_type = asset_type or (hit.asset_type if hit else None)
+        base = f"a_{_slug(label or '') or 'gam'}"
+        key, n = base, 2
+        while key in assets:
+            key, n = f"{base}_{n}", n + 1
+        ref: Dict[str, Any] = {"from": "gam", "id": gam_id}
+        if asset_type in ("image", "video", "audio"):
+            ref["type"] = asset_type
+        if label:
+            ref["label"] = label
+        assets[key] = ref
+        return key
+
+    # ── committing ───────────────────────────────────────────────────────────
+
+    def commit(self, candidate: Dict[str, Any], summary: str) -> str:
+        """Take `candidate` as the new spec if the rules above allow it."""
+        _, issues = parse_spec(candidate)
+        if issues and self.valid:
+            raise ToolFailed("That edit would make the video invalid, so it was not made:\n"
+                             + _issues_text(issues))
+        self.data, self.issues = candidate, issues
+        self.changes.append(summary)
+        if issues:
+            return (f"Done: {summary}. The video still has issues to fix:\n"
+                    + _issues_text(issues))
+        return f"Done: {summary}."
+
+
+# ── the tools ─────────────────────────────────────────────────────────────────
+
+def _compact(data: Dict[str, Any]) -> str:
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+
+
+def get_spec(w: Working, segment_id: Optional[str] = None) -> str:
+    if segment_id:
+        return _compact(w.segment(segment_id))
+    return _compact(w.data)
+
+
+def search_assets(w: Working, query: str, type: Optional[str] = None,
+                  limit: int = 8) -> str:
+    if w.gam is None:
+        raise ToolFailed("The asset library isn't reachable in this turn.")
+    try:
+        found = w.gam.search(query, asset_type=type, limit=max(1, min(MAX_SEARCH_HITS, limit)))
+    except GamError as exc:
+        raise ToolFailed(f"The asset library search failed: {exc.message}")
+    rows = []
+    for hit in found.data:
+        asset = hit.asset
+        w.hits[asset.id] = Hit(asset.id, asset.name, asset.asset_type, asset.duration_seconds,
+                               hit.start_time, hit.end_time)
+        row: Dict[str, Any] = {"gam_id": asset.id, "name": asset.name, "type": asset.asset_type}
+        if asset.duration_seconds:
+            row["duration"] = round(asset.duration_seconds, 1)
+        if hit.start_time is not None:
+            # Where in the video it was said: what `set_visual` will cut to.
+            row["said_at"] = [round(hit.start_time, 1),
+                              round(hit.end_time, 1) if hit.end_time is not None else None]
+        if hit.snippet:
+            row["snippet"] = hit.snippet.replace("«", "").replace("»", "")[:240]
+        if asset.credit:
+            row["credit"] = asset.credit
+        if asset.width and asset.height:
+            row["size"] = f"{asset.width}x{asset.height}"
+        rows.append(row)
+    if not rows:
+        return (f"Nothing in the library matches {query!r}. Try other words, or leave a "
+                "placeholder with add_placeholder.")
+    return _compact({"query": query, "semantic": found.semantic, "hits": rows})
+
+
+def get_asset(w: Working, gam_id: str) -> str:
+    if w.gam is None:
+        raise ToolFailed("The asset library isn't reachable in this turn.")
+    try:
+        asset = w.gam.get_asset(gam_id)
+    except GamError as exc:
+        raise ToolFailed(f"The asset library failed: {exc.message}")
+    if asset is None:
+        raise ToolFailed(f"No asset {gam_id!r} in the library.")
+    return _compact({"gam_id": asset.id, "name": asset.name, "type": asset.asset_type,
+                     "duration": asset.duration_seconds, "width": asset.width,
+                     "height": asset.height, "credit": asset.credit,
+                     "clip_of": asset.parent_asset_id})
+
+
+def replace_spec(w: Working, spec: Dict[str, Any]) -> str:
+    if not isinstance(spec, dict):
+        raise ToolFailed("spec must be a VideoSpec object.")
+    candidate = copy.deepcopy(spec)
+    # The project owns its id; a draft never changes it.
+    if "id" in w.data:
+        candidate["id"] = w.data["id"]
+    # Accepted even with issues: a whole draft is the one edit too big to throw away
+    # over a typo. The issues come back to be fixed with the other tools.
+    _, issues = parse_spec(candidate)
+    w.data, w.issues = candidate, issues
+    w.changes.append(f"Drafted the video: {len(candidate.get('segments', []))} segments")
+    if issues:
+        return (f"The draft is in place, with {len(issues)} issue"
+                f"{'s' if len(issues) != 1 else ''} to fix:\n" + _issues_text(issues))
+    return "Done: the draft is in place and valid."
+
+
+def _insert_at(w: Working, after: Optional[str]) -> int:
+    if after in (None, ""):
+        return len(w.segments())
+    if after == "start":
+        return 0
+    return w.index_of(after) + 1
+
+
+def add_segment(w: Working, segment: Dict[str, Any], after: Optional[str] = None) -> str:
+    if not isinstance(segment, dict):
+        raise ToolFailed("segment must be an object.")
+    candidate = copy.deepcopy(w.data)
+    taken = [s.get("id") for s in candidate.get("segments", [])]
+    segment = copy.deepcopy(segment)
+    if not segment.get("id") or segment["id"] in taken:
+        segment["id"] = w.new_id("s_", taken)
+    position = _insert_at(w, after)
+    candidate.setdefault("segments", []).insert(position, segment)
+    return w.commit(candidate, f"Added {segment.get('kind', 'segment')} "
+                               f"{segment.get('label') or segment['id']} (id {segment['id']})")
+
+
+def update_segment(w: Working, segment_id: str, changes: Dict[str, Any]) -> str:
+    if not isinstance(changes, dict):
+        raise ToolFailed("changes must be an object.")
+    if "id" in changes:
+        raise ToolFailed("A segment's id can't be changed; anchors point at it.")
+    candidate = copy.deepcopy(w.data)
+    index = w.index_of(segment_id)
+    candidate["segments"][index] = merge(candidate["segments"][index], changes)
+    fields = ", ".join(sorted(changes)) or "nothing"
+    return w.commit(candidate, f"Changed {w.name_of(candidate['segments'][index])}: {fields}")
+
+
+def move_segment(w: Working, segment_id: str, after: str) -> str:
+    candidate = copy.deepcopy(w.data)
+    index = w.index_of(segment_id)
+    moving = candidate["segments"].pop(index)
+    if after == segment_id:
+        raise ToolFailed("A segment can't be moved after itself.")
+    if after == "start":
+        position = 0
+    else:
+        ids = [s.get("id") for s in candidate["segments"]]
+        if after not in ids:
+            raise ToolFailed(f"No segment {after!r} to move it after.")
+        position = ids.index(after) + 1
+    candidate["segments"].insert(position, moving)
+    where = "to the start" if after == "start" else f"after {after}"
+    return w.commit(candidate, f"Moved {w.name_of(moving)} {where}")
+
+
+def _anchors_naming(data: Dict[str, Any], segment_id: str) -> List[str]:
+    """What points at a segment, so removing it can say what will be orphaned."""
+    named = []
+
+    def hits(anchor: Any) -> bool:
+        return isinstance(anchor, dict) and anchor.get("segment") == segment_id
+
+    for track in data.get("audio_tracks", []):
+        if hits(track.get("start")) or hits(track.get("end")):
+            named.append(f"audio track {track.get('id')}")
+    for segment in data.get("segments", []):
+        for overlay in segment.get("overlays", []):
+            show = overlay.get("show") or {}
+            if hits(show.get("from")) or hits(show.get("to")):
+                named.append(f"overlay {overlay.get('id')} on {segment.get('id')}")
+    return named
+
+
+def remove_segment(w: Working, segment_id: str) -> str:
+    candidate = copy.deepcopy(w.data)
+    index = w.index_of(segment_id)
+    removed = candidate["segments"].pop(index)
+    result = w.commit(candidate, f"Removed {w.name_of(removed)}")
+    orphans = _anchors_naming(candidate, segment_id)
+    if orphans:
+        # Allowed, as in the editor: the renderer drops what can't be placed with a
+        # warning. Said so the model can re-anchor them.
+        result += (" These are still anchored to it and will be left out of the render "
+                   "unless re-anchored: " + ", ".join(orphans) + ".")
+    return result
+
+
+def _moment_trim(hit: Hit) -> Optional[Dict[str, float]]:
+    if hit.start is None:
+        return None
+    end = hit.end if hit.end is not None else hit.start + DEFAULT_MOMENT_SECONDS
+    a = max(0.0, hit.start - MOMENT_PAD)
+    b = end + MOMENT_PAD
+    if hit.duration:
+        b = min(b, hit.duration)
+    return {"in": round(a, 1), "out": round(b, 1)} if b > a else None
+
+
+def set_visual(w: Working, segment_id: str, gam_id: Optional[str] = None,
+               asset: Optional[str] = None, trim: Optional[Dict[str, Any]] = None,
+               motion: Optional[Dict[str, Any]] = None, fit: Optional[str] = None,
+               audio: Optional[str] = None, loop: Optional[bool] = None) -> str:
+    if not gam_id and not asset:
+        raise ToolFailed("Give gam_id (from search_assets) or asset (a key in the registry).")
+    candidate = copy.deepcopy(w.data)
+    if gam_id:
+        key = w.register_gam(candidate, gam_id)
+    else:
+        if asset not in w.data.get("assets", {}):
+            raise ToolFailed(f"No asset {asset!r} in the registry.")
+        key = asset
+    index = w.index_of(segment_id)
+    segment = candidate["segments"][index]
+    visual: Dict[str, Any] = {"asset": key}
+    previous = segment.get("visual") or {}
+    if previous.get("asset") == key:
+        visual = copy.deepcopy(previous)
+    hit = w.hits.get(gam_id) if gam_id else None
+    if trim is not None:
+        visual["trim"] = trim
+    elif hit and hit.asset_type == "video" and _moment_trim(hit):
+        # The moment that was said becomes the cut, as picking a hit does in the editor.
+        visual["trim"] = _moment_trim(hit)
+    if motion is not None:
+        visual["motion"] = motion
+    if fit is not None:
+        visual["fit"] = fit
+    if audio is not None:
+        visual["audio"] = audio
+    if loop is not None:
+        visual["loop"] = loop
+    segment["visual"] = visual
+    label = hit.name if hit else key
+    trimmed = f", {visual['trim'].get('in')}–{visual['trim'].get('out')} s" if visual.get("trim") else ""
+    return w.commit(candidate, f"{w.name_of(segment)} shows {label}{trimmed}")
+
+
+def add_placeholder(w: Working, segment_id: str, kind: str, text: str,
+                    media_type: str = "video", moment_min: Optional[float] = None,
+                    moment_max: Optional[float] = None, use_as: str = "visual") -> str:
+    """Footage still to find, or a picture still to generate: drawn as a slate in a
+    preview, filled in by a person later."""
+    candidate = copy.deepcopy(w.data)
+    assets = candidate.setdefault("assets", {})
+    base = f"a_{_slug(text) or kind}"
+    key, n = base, 2
+    while key in assets:
+        key, n = f"{base}_{n}", n + 1
+    if kind == "search":
+        ref: Dict[str, Any] = {"from": "search", "query": text, "type": media_type}
+        if media_type == "video" and (moment_min or moment_max):
+            ref["moment"] = {k: v for k, v in (("min", moment_min), ("max", moment_max)) if v}
+    elif kind == "generate":
+        if media_type not in ("image", "video", "music", "sfx"):
+            media_type = "image"
+        ref = {"from": "generate", "type": media_type, "prompt": text}
+    else:
+        raise ToolFailed('kind must be "search" or "generate".')
+    assets[key] = ref
+    index = w.index_of(segment_id)
+    segment = candidate["segments"][index]
+    if use_as == "visual":
+        segment["visual"] = {"asset": key}
+    return w.commit(candidate, f"{w.name_of(segment)}: placeholder to "
+                               f"{'find' if kind == 'search' else 'generate'}: {text!r}")
+
+
+def add_overlay(w: Working, segment_id: str, overlay: Dict[str, Any],
+                gam_id: Optional[str] = None) -> str:
+    if not isinstance(overlay, dict):
+        raise ToolFailed("overlay must be an object.")
+    candidate = copy.deepcopy(w.data)
+    overlay = copy.deepcopy(overlay)
+    if gam_id:
+        overlay["asset"] = w.register_gam(candidate, gam_id, asset_type="image")
+    taken = w.all_overlay_ids()
+    if not overlay.get("id") or overlay["id"] in taken:
+        overlay["id"] = w.new_id("o_", taken)
+    index = w.index_of(segment_id)
+    segment = candidate["segments"][index]
+    segment.setdefault("overlays", []).append(overlay)
+    what = overlay.get("title") or overlay.get("text") or overlay.get("type")
+    return w.commit(candidate, f"On {w.name_of(segment)}: added "
+                                      f"{overlay.get('type', 'overlay')} {what!r} (id {overlay['id']})")
+
+
+def _overlay_index(segment: Dict[str, Any], overlay_id: str) -> int:
+    for i, overlay in enumerate(segment.get("overlays", [])):
+        if overlay.get("id") == overlay_id:
+            return i
+    raise ToolFailed(f"No overlay {overlay_id!r} on {segment.get('id')}.")
+
+
+def update_overlay(w: Working, segment_id: str, overlay_id: str, changes: Dict[str, Any]) -> str:
+    candidate = copy.deepcopy(w.data)
+    segment = candidate["segments"][w.index_of(segment_id)]
+    i = _overlay_index(segment, overlay_id)
+    segment["overlays"][i] = merge(segment["overlays"][i], changes)
+    return w.commit(candidate, f"On {w.name_of(segment)}: changed overlay {overlay_id} "
+                               f"({', '.join(sorted(changes))})")
+
+
+def remove_overlay(w: Working, segment_id: str, overlay_id: str) -> str:
+    candidate = copy.deepcopy(w.data)
+    segment = candidate["segments"][w.index_of(segment_id)]
+    segment["overlays"].pop(_overlay_index(segment, overlay_id))
+    return w.commit(candidate, f"On {w.name_of(segment)}: removed overlay {overlay_id}")
+
+
+def add_audio_track(w: Working, track: Dict[str, Any], gam_id: Optional[str] = None) -> str:
+    if not isinstance(track, dict):
+        raise ToolFailed("track must be an object.")
+    candidate = copy.deepcopy(w.data)
+    track = copy.deepcopy(track)
+    if gam_id:
+        track["asset"] = w.register_gam(candidate, gam_id, asset_type="audio")
+    taken = [t.get("id") for t in candidate.get("audio_tracks", [])]
+    if not track.get("id") or track["id"] in taken:
+        track["id"] = w.new_id("m_" if track.get("kind", "music") == "music" else "x_", taken)
+    candidate.setdefault("audio_tracks", []).append(track)
+    hit = w.hits.get(gam_id) if gam_id else None
+    return w.commit(candidate, f"Added {track.get('kind', 'music')} track "
+                                      f"{(hit.name if hit else track.get('asset'))!r} (id {track['id']})")
+
+
+def update_audio_track(w: Working, track_id: str, changes: Dict[str, Any]) -> str:
+    candidate = copy.deepcopy(w.data)
+    tracks = candidate.get("audio_tracks", [])
+    for i, track in enumerate(tracks):
+        if track.get("id") == track_id:
+            tracks[i] = merge(track, changes)
+            return w.commit(candidate, f"Changed audio track {track_id} "
+                                       f"({', '.join(sorted(changes))})")
+    raise ToolFailed(f"No audio track {track_id!r}.")
+
+
+def remove_audio_track(w: Working, track_id: str) -> str:
+    w.track(track_id)
+    candidate = copy.deepcopy(w.data)
+    candidate["audio_tracks"] = [t for t in candidate["audio_tracks"] if t.get("id") != track_id]
+    return w.commit(candidate, f"Removed audio track {track_id}")
+
+
+_PROJECT_KEYS = ("title", "style", "output", "voice", "chrome", "credits")
+
+
+def set_project(w: Working, changes: Dict[str, Any]) -> str:
+    if not isinstance(changes, dict) or not changes:
+        raise ToolFailed("changes must be an object.")
+    unknown = sorted(set(changes) - set(_PROJECT_KEYS))
+    if unknown:
+        raise ToolFailed(f"set_project changes only {', '.join(_PROJECT_KEYS)}; "
+                         f"not {', '.join(unknown)}. Segments and tracks have their own tools.")
+    candidate = merge(w.data, changes)
+    return w.commit(candidate, f"Changed the project's {', '.join(sorted(changes))}")
+
+
+def run_estimate(w: Working) -> str:
+    spec, issues = parse_spec(w.data)
+    if spec is None:
+        return "Can't estimate yet; the video has issues:\n" + _issues_text(issues)
+    result = estimate(spec)
+    return _compact({"seconds": result.seconds, "seconds_is_floor": result.seconds_is_floor,
+                     "narration_chars": result.narration_chars,
+                     "blocks_full_render": result.blocks_render})
+
+
+# ── schemas ───────────────────────────────────────────────────────────────────
+
+_OBJ = {"type": "object"}
+_STR = {"type": "string"}
+_NUM = {"type": "number"}
+
+TOOLS: List[Tuple[ToolSpec, Callable[..., str]]] = [
+    (ToolSpec("get_spec", "The video as it stands now (after this turn's edits), or one "
+              "segment of it.",
+              {"type": "object", "properties": {"segment_id": _STR}}), get_spec),
+    (ToolSpec("search_assets",
+              "Search the user's asset library (GAM) by name, description and what is SAID in "
+              "videos. A hit on speech carries said_at [start, end] seconds: the moment to cut "
+              "to. Use type to restrict to video, image or audio.",
+              {"type": "object", "properties": {
+                  "query": _STR, "type": {"type": "string", "enum": ["video", "image", "audio"]},
+                  "limit": {"type": "integer", "minimum": 1, "maximum": MAX_SEARCH_HITS}},
+               "required": ["query"]}), search_assets),
+    (ToolSpec("get_asset", "Details of one library asset by gam_id.",
+              {"type": "object", "properties": {"gam_id": _STR}, "required": ["gam_id"]}),
+     get_asset),
+    (ToolSpec("replace_spec",
+              "Replace the whole video with a complete VideoSpec. For a first draft or a full "
+              "rewrite only; use the targeted tools for anything smaller. Library assets go in "
+              "`assets` as {\"from\":\"gam\",\"id\":<gam_id>,\"type\":...}.",
+              {"type": "object", "properties": {"spec": _OBJ}, "required": ["spec"]}),
+     replace_spec),
+    (ToolSpec("add_segment",
+              "Insert a segment (scene, card or clip) after the segment `after` (\"start\" for "
+              "first, omit for last). A missing or taken id is replaced with a fresh one.",
+              {"type": "object", "properties": {"segment": _OBJ, "after": _STR},
+               "required": ["segment"]}), add_segment),
+    (ToolSpec("update_segment",
+              "Change fields of one segment by merge patch: objects merge, null removes a "
+              "field, lists (beats, overlays) are replaced whole.",
+              {"type": "object", "properties": {"segment_id": _STR, "changes": _OBJ},
+               "required": ["segment_id", "changes"]}), update_segment),
+    (ToolSpec("move_segment", "Move a segment to after another (\"start\" for first).",
+              {"type": "object", "properties": {"segment_id": _STR, "after": _STR},
+               "required": ["segment_id", "after"]}), move_segment),
+    (ToolSpec("remove_segment", "Remove a segment. Says what was anchored to it.",
+              {"type": "object", "properties": {"segment_id": _STR},
+               "required": ["segment_id"]}), remove_segment),
+    (ToolSpec("set_visual",
+              "Set a segment's picture or footage: gam_id (from search_assets, registered for "
+              "you) or asset (an existing registry key). A video hit's said_at becomes the trim "
+              "unless trim is given. motion and fit as in the spec.",
+              {"type": "object", "properties": {
+                  "segment_id": _STR, "gam_id": _STR, "asset": _STR, "trim": _OBJ,
+                  "motion": _OBJ, "fit": {"type": "string", "enum": ["blur", "pad", "crop"]},
+                  "audio": {"type": "string", "enum": ["mute", "play"]},
+                  "loop": {"type": "boolean"}},
+               "required": ["segment_id"]}), set_visual),
+    (ToolSpec("add_placeholder",
+              "When the library has nothing fitting: a placeholder for footage still to find "
+              "(kind search, text = what to look for) or a picture to generate (kind generate, "
+              "text = the prompt), set as the segment's visual. Never invent a gam_id.",
+              {"type": "object", "properties": {
+                  "segment_id": _STR, "kind": {"type": "string", "enum": ["search", "generate"]},
+                  "text": _STR, "media_type": {"type": "string",
+                                               "enum": ["video", "image", "audio", "music", "sfx"]},
+                  "moment_min": _NUM, "moment_max": _NUM},
+               "required": ["segment_id", "kind", "text"]}), add_placeholder),
+    (ToolSpec("add_overlay",
+              "Add an overlay to a segment: text, lower_third, image (pass gam_id for the "
+              "picture), quote or code. show {from, to} anchors default to the segment.",
+              {"type": "object", "properties": {"segment_id": _STR, "overlay": _OBJ,
+                                                "gam_id": _STR},
+               "required": ["segment_id", "overlay"]}), add_overlay),
+    (ToolSpec("update_overlay", "Change an overlay by merge patch.",
+              {"type": "object", "properties": {"segment_id": _STR, "overlay_id": _STR,
+                                                "changes": _OBJ},
+               "required": ["segment_id", "overlay_id", "changes"]}), update_overlay),
+    (ToolSpec("remove_overlay", "Remove an overlay.",
+              {"type": "object", "properties": {"segment_id": _STR, "overlay_id": _STR},
+               "required": ["segment_id", "overlay_id"]}), remove_overlay),
+    (ToolSpec("add_audio_track",
+              "Add music, a sound effect or voice from the library (gam_id from search_assets "
+              "with type audio), with start/end anchors, volume and fades.",
+              {"type": "object", "properties": {"track": _OBJ, "gam_id": _STR},
+               "required": ["track"]}), add_audio_track),
+    (ToolSpec("update_audio_track", "Change an audio track by merge patch.",
+              {"type": "object", "properties": {"track_id": _STR, "changes": _OBJ},
+               "required": ["track_id", "changes"]}), update_audio_track),
+    (ToolSpec("remove_audio_track", "Remove an audio track.",
+              {"type": "object", "properties": {"track_id": _STR}, "required": ["track_id"]}),
+     remove_audio_track),
+    (ToolSpec("set_project",
+              "Change project-wide settings by merge patch: title, style (default transition, "
+              "motion, background, cards…), output, voice, chrome, credits.",
+              {"type": "object", "properties": {"changes": _OBJ}, "required": ["changes"]}),
+     set_project),
+    (ToolSpec("estimate", "How long the video runs, its narration length, and what would "
+              "stop a full render.", {"type": "object", "properties": {}}), run_estimate),
+]
+
+SPECS = [spec for spec, _ in TOOLS]
+_HANDLERS = {spec.name: handler for spec, handler in TOOLS}
+
+# Read-only tools, which neither change the video nor count as an edit in the steps.
+READS = {"get_spec", "search_assets", "get_asset", "estimate"}
+
+
+def execute(w: Working, call: ToolCall) -> ToolResult:
+    """Run one call. Never raises: a failure is a result the model reads and acts on."""
+    if call.parse_error:
+        return ToolResult(call.id, f"Your arguments couldn't be read: {call.parse_error}.",
+                          is_error=True)
+    handler = _HANDLERS.get(call.name)
+    if handler is None:
+        return ToolResult(call.id, f"There is no tool {call.name!r}.", is_error=True)
+    try:
+        return ToolResult(call.id, handler(w, **call.arguments))
+    except ToolFailed as exc:
+        return ToolResult(call.id, str(exc), is_error=True)
+    except TypeError as exc:
+        # Arguments the handler doesn't take: said in the schema's terms.
+        return ToolResult(call.id, f"Wrong arguments for {call.name}: {exc}", is_error=True)
diff --git a/backend/app/assistant/worker.py b/backend/app/assistant/worker.py
new file mode 100644
index 0000000..6d610f5
--- /dev/null
+++ b/backend/app/assistant/worker.py
@@ -0,0 +1,194 @@
+"""Running assistant turns in the background, as the user who asked.
+
+A turn searches GAM with the requester's own token, so it can never see what they could
+not. The token is held here, in memory, for the turn's life only, never in the database,
+which is why a server restart ends a running turn ("ask again") rather than resuming it:
+the render queue's rule, for the same reason.
+
+Everything else lives on the `AssistantTurn` row as it happens, so a turn finishes and
+waits for Apply with nobody watching.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from typing import Dict, List, Optional, Tuple
+
+from sqlmodel import Session
+
+from app.assistant import loop
+from app.assistant.prompt import REFERENCE, context
+from app.assistant.tools import Working
+from app.clock import utcnow
+from app.config import settings
+from app.gam.client import GamClient
+from app.jobs.runner import JobQueue, readable_error, set_fields
+from app.models.assistant import AssistantSession, AssistantTurn
+from app.providers import build_provider
+from app.providers.base import ProviderError, Reply
+from app.spec.model import dump_spec
+from app.spec.validation import parse_spec
+from app.usage import events as usage_events
+
+logger = logging.getLogger(__name__)
+
+_tokens: Dict[str, Optional[str]] = {}
+
+MAX_STEPS_KEPT = 200
+
+
+def append_message(row: AssistantSession, role: str, text: str,
+                   turn_id: Optional[str] = None) -> None:
+    messages = json.loads(row.messages or "[]")
+    messages.append({"role": role, "text": text, "turn_id": turn_id,
+                     "at": utcnow().isoformat(timespec="seconds")})
+    row.messages = json.dumps(messages, ensure_ascii=False)
+    row.updated_at = utcnow()
+
+
+def history_for(row: AssistantSession, turn_id: str) -> List[Tuple[str, str]]:
+    """Earlier messages, newest kept, with this turn's own prompt left out (it is sent
+    as the new message)."""
+    messages = [m for m in json.loads(row.messages or "[]")
+                if m.get("turn_id") != turn_id and m.get("text")
+                and m.get("role") in ("user", "assistant")]
+    return [(m["role"], m["text"]) for m in messages[-settings.assistant_history_messages:]]
+
+
+def _canonical(data: dict) -> Optional[dict]:
+    spec, issues = parse_spec(data)
+    return dump_spec(spec) if spec is not None else None
+
+
+def _run(turn_id: str) -> None:
+    with queue.session() as session:
+        turn = session.get(AssistantTurn, turn_id)
+        if turn is None or turn.status != "queued":
+            return
+        chat = session.get(AssistantSession, turn.session_id)
+        if turn_id not in _tokens:
+            set_fields(session, turn, status="error", stage="",
+                       error_message="Interrupted by a restart of the server. Ask again.")
+            if chat:
+                append_message(chat, "assistant", "_Interrupted by a restart. Ask again._", turn_id)
+                session.add(chat)
+                session.commit()
+            return
+        set_fields(session, turn, status="processing", stage="Thinking", progress=0)
+        user_id, project_id = turn.user_id, turn.project_id
+        prompt, focus = turn.prompt, turn.focus
+        base = json.loads(turn.base_spec or "{}")
+        history = history_for(chat, turn_id) if chat else []
+
+    token = _tokens.get(turn_id)
+    gam = GamClient(token)
+    steps: List[dict] = []
+    cost: List[float] = []
+
+    def write(**fields) -> None:
+        with queue.session() as session:
+            row = session.get(AssistantTurn, turn_id)
+            if row is not None:
+                set_fields(session, row, **fields)
+
+    def on_step(kind: str, text: str) -> None:
+        steps.append({"kind": kind, "text": text[:600]})
+        detail = {"search": "searching the library", "edit": "editing",
+                  "issue": "fixing", "think": "thinking"}.get(kind, "")
+        write(steps=json.dumps(steps[-MAX_STEPS_KEPT:], ensure_ascii=False),
+              stage="Working", detail=detail)
+
+    def on_reply(reply: Reply) -> None:
+        with queue.session() as session:
+            spent = usage_events.record_reply(session, user_id=user_id, project_id=project_id,
+                                              turn_id=turn_id, reply=reply)
+        if spent is not None:
+            cost.append(spent)
+            write(cost=round(sum(cost), 6))
+
+    try:
+        with queue.session() as session:
+            provider = build_provider(session, user_id)
+        if provider is None:
+            raise ProviderError("No AI provider is set up. Add one in Settings first.")
+        working = Working(base, gam=gam)
+        system = [REFERENCE, context(base, focus=focus, from_scratch=project_id is None)]
+        outcome = loop.run(provider, working, system=system, history=history, prompt=prompt,
+                           on_step=on_step, on_reply=on_reply,
+                           cancelled=lambda: queue.is_cancelled(turn_id),
+                           max_rounds=settings.assistant_max_rounds)
+    except loop.Stopped:
+        _finish(turn_id, status="cancelled", stage="", message="_Stopped._", steps=steps)
+        return
+    except ProviderError as exc:
+        _finish(turn_id, status="error", stage="", error_message=str(exc),
+                message=f"_{exc}_", steps=steps)
+        return
+    except Exception as exc:  # noqa: BLE001 - a failed turn is a job error, not a crash
+        logger.exception("Assistant turn %s failed", turn_id)
+        _finish(turn_id, status="error", stage="", error_message=readable_error(exc),
+                message="_Something went wrong; ask again._", steps=steps)
+        return
+    finally:
+        gam.close()
+        _tokens.pop(turn_id, None)
+
+    reply = outcome.reply or ("Done." if working.changes else "")
+    proposed = None
+    if working.changes:
+        canonical = _canonical(working.data)
+        if canonical is None:
+            reply += ("\n\nI couldn't get the video into a valid state, so there's nothing to "
+                      "apply. Ask me to try again, or say what to change.")
+        elif canonical != _canonical(base):
+            proposed = canonical
+    if outcome.cut_short:
+        reply = (reply + "\n\n" if reply else "") + f"_{outcome.cut_short}_"
+    _finish(turn_id, status="done", stage="", progress=100, detail="", message=reply,
+            steps=steps, reply=reply,
+            proposed_spec=json.dumps(proposed, ensure_ascii=False) if proposed else None,
+            changes=json.dumps(working.changes if proposed else [], ensure_ascii=False),
+            outcome="pending" if proposed else "")
+
+
+def _finish(turn_id: str, *, message: str, steps: List[dict], **fields) -> None:
+    with queue.session() as session:
+        turn = session.get(AssistantTurn, turn_id)
+        if turn is None:
+            return
+        set_fields(session, turn, steps=json.dumps(steps[-MAX_STEPS_KEPT:], ensure_ascii=False),
+                   **fields)
+        chat = session.get(AssistantSession, turn.session_id)
+        if chat is not None and message:
+            append_message(chat, "assistant", message, turn_id)
+            session.add(chat)
+            session.commit()
+
+
+queue = JobQueue(AssistantTurn, _run, name="assistant",
+                 concurrency=settings.assistant_concurrency, requeue_on_restart=False)
+
+
+def submit(session: Session, chat: AssistantSession, *, user_id: str, token: Optional[str],
+           prompt: str, base_spec: dict, base_version: Optional[int],
+           focus: Optional[str]) -> AssistantTurn:
+    turn = AssistantTurn(id=str(uuid.uuid4()), session_id=chat.id, user_id=user_id,
+                         project_id=chat.project_id, prompt=prompt,
+                         base_spec=json.dumps(base_spec, ensure_ascii=False),
+                         base_version=base_version, focus=focus)
+    append_message(chat, "user", prompt, turn.id)
+    if not chat.title:
+        chat.title = prompt.strip().splitlines()[0][:80]
+    session.add(turn)
+    session.add(chat)
+    session.commit()
+    session.refresh(turn)
+    _tokens[turn.id] = token
+    queue.enqueue(turn.id)
+    return turn
+
+
+def start() -> None:
+    queue.start()
diff --git a/backend/app/config.py b/backend/app/config.py
index 4bf4398..6ad5c64 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -86,6 +86,15 @@ class Settings(BaseSettings):
     render_cache_max_gb: float = 20
     # The largest single file a render will fetch from GAM.
     render_max_file_mb: int = 8192
+    # The assistant (M4/M5). A turn is a job: it keeps running with the browser closed.
+    # Rounds are model calls in one turn; a from-scratch draft takes a handful, the
+    # rest of the budget is for searching and fixing. Two workers: a turn is
+    # mostly waiting on the provider, so two run side by side without contention.
+    assistant_concurrency: int = 2
+    assistant_max_rounds: int = 24
+    # Earlier messages a turn is given, newest kept. Older ones are still in the
+    # session; the spec itself, not the chat, is the record of what was decided.
+    assistant_history_messages: int = 20
     job_heartbeat_seconds: int = 30
     job_stale_minutes: int = 40
 
diff --git a/backend/app/main.py b/backend/app/main.py
index 0d0e76f..b0001b3 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -20,6 +20,7 @@
 from app.config import settings
 from app.database import engine, get_session
 from app.gam.client import GamError
+from app.routers import assistant as assistant_router
 from app.routers import gam as gam_router
 from app.routers import projects as projects_router
 from app.routers import providers as providers_router
@@ -50,9 +51,13 @@ async def lifespan(_app: FastAPI):
 
     # Picks up nothing a restart interrupted (a render runs as its requester, whose
     # token is gone), and starts the render workers.
+    from app.assistant import worker as assistant_worker
     from app.render import worker
 
     worker.start()
+    # The same rule for the assistant: a turn interrupted by a restart is ended and
+    # said so, never rerun without the token it needs.
+    assistant_worker.start()
     yield
 
 
@@ -148,6 +153,7 @@ def me(user: CurrentUser, session: Session = Depends(get_session)) -> DataRespon
 app.include_router(gam_router.router, prefix="/api/gam", tags=["gam"])
 app.include_router(renders_router.router, prefix="/api", tags=["renders"])
 app.include_router(providers_router.router, prefix="/api/providers", tags=["providers"])
+app.include_router(assistant_router.router, prefix="/api/assistant", tags=["assistant"])
 app.include_router(usage_router.router, prefix="/api/usage", tags=["usage"])
 # Not under /api: these URLs go straight into <video src>, authorised by signature.
 app.include_router(renders_router.media_router, prefix="/media/renders", tags=["media"])
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 01a3944..91ba32e 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -5,10 +5,11 @@
 empty migration and a silent schema drift.
 """
 
+from app.models.assistant import AssistantSession, AssistantTurn
 from app.models.project import Project, ProjectVersion
 from app.models.provider import AIProvider
 from app.models.render import RenderJob
 from app.models.usage import UsageEvent
 from app.models.user import User
 
-__all__ = ["AIProvider", "Project", "ProjectVersion", "RenderJob", "UsageEvent", "User"]
+__all__ = ["AIProvider", "AssistantSession", "AssistantTurn", "Project", "ProjectVersion", "RenderJob", "UsageEvent", "User"]
diff --git a/backend/app/models/assistant.py b/backend/app/models/assistant.py
new file mode 100644
index 0000000..73f0933
--- /dev/null
+++ b/backend/app/models/assistant.py
@@ -0,0 +1,66 @@
+"""The assistant's conversations and turns.
+
+A turn is a job (the render queue's pattern), so it keeps running after the project, the
+tab or the browser is closed, and everything it is and does lives on its row: the prompt,
+the draft it started from, each step as it happens, the reply and the proposed spec. A
+person coming back finds it running, or finished and waiting for Apply or Discard.
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlmodel import Field, SQLModel
+
+from app.clock import utcnow
+
+
+class AssistantSession(SQLModel, table=True):
+    __tablename__ = "assistant_session"
+
+    id: str = Field(primary_key=True)
+    user_id: str = Field(foreign_key="user.id", index=True)
+    # None: a conversation about a video that doesn't exist yet (from the project list).
+    # No foreign key: deleting a project deletes its sessions explicitly, and a draft
+    # applied as a new project fills this in afterwards.
+    project_id: Optional[str] = Field(default=None, index=True)
+    title: str = ""
+    # JSON: [{"role": "user"|"assistant", "text", "turn_id", "at"}]
+    messages: str = "[]"
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
+
+
+class AssistantTurn(SQLModel, table=True):
+    __tablename__ = "assistant_turn"
+
+    id: str = Field(primary_key=True)
+    session_id: str = Field(foreign_key="assistant_session.id", index=True)
+    user_id: str = Field(foreign_key="user.id", index=True)
+    project_id: Optional[str] = Field(default=None, index=True)
+    # queued | processing | done | error | cancelled (jobs/runner.py)
+    status: str = "queued"
+    stage: str = ""
+    progress: int = 0
+    detail: str = ""
+    error_message: Optional[str] = None
+    prompt: str = ""
+    # The editor's draft when the turn was asked, unsaved edits included (JSON), and the
+    # project version it was a draft of. The proposal is built on the draft, so applying
+    # it later carries those edits too; the version is what "based on an older version"
+    # is judged against.
+    base_spec: str = "{}"
+    base_version: Optional[int] = None
+    # The scene open in the editor, if any: "this scene" in a request means it.
+    focus: Optional[str] = None
+    # JSON: [{"kind": "think"|"search"|"edit"|"issue"|"note", "text"}]
+    steps: str = "[]"
+    reply: str = ""
+    # JSON of the proposed spec; None when the turn changed nothing.
+    proposed_spec: Optional[str] = None
+    # JSON list of one-line change summaries.
+    changes: str = "[]"
+    # pending | applied | discarded, once there is a proposal; "" otherwise.
+    outcome: str = ""
+    cost: Optional[float] = None
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
diff --git a/backend/app/providers/anthropic.py b/backend/app/providers/anthropic.py
index 7736395..4074b1f 100644
--- a/backend/app/providers/anthropic.py
+++ b/backend/app/providers/anthropic.py
@@ -114,6 +114,10 @@ def ask(self) -> Reply:
         self.messages.append({"role": "assistant", "content": content or []})
         return reply
 
+    def tell(self, text: str) -> None:
+        """A user message mid-turn: what the loop says when the model stops too soon."""
+        self.messages.append({"role": "user", "content": text})
+
     def answer(self, results: Sequence[ToolResult]) -> None:
         # Every result in one user message: splitting them teaches the model to stop
         # calling tools in parallel.
diff --git a/backend/app/providers/base.py b/backend/app/providers/base.py
index 49239ce..33c032a 100644
--- a/backend/app/providers/base.py
+++ b/backend/app/providers/base.py
@@ -79,6 +79,10 @@ def answer(self, results: Sequence[ToolResult]) -> None:
         """Append the results of the tool calls in the last reply, all in one message."""
         ...
 
+    def tell(self, text: str) -> None:
+        """Append a user message after a reply that called no tools."""
+        ...
+
 
 class ChatProvider(Protocol):
     @property
diff --git a/backend/app/providers/openai.py b/backend/app/providers/openai.py
index f0272d7..6839364 100644
--- a/backend/app/providers/openai.py
+++ b/backend/app/providers/openai.py
@@ -95,6 +95,10 @@ def ask(self) -> Reply:
         self.messages.append(message)
         return reply
 
+    def tell(self, text: str) -> None:
+        """A user message mid-turn: what the loop says when the model stops too soon."""
+        self.messages.append({"role": "user", "content": text})
+
     def answer(self, results: Sequence[ToolResult]) -> None:
         for r in results:
             # No error flag in this protocol: an error is said in the content.
diff --git a/backend/app/routers/assistant.py b/backend/app/routers/assistant.py
new file mode 100644
index 0000000..a716382
--- /dev/null
+++ b/backend/app/routers/assistant.py
@@ -0,0 +1,270 @@
+"""The assistant: start a turn, follow it, stop it, and act on what it proposes.
+
+A turn is a background job, so none of this needs the page that started it to stay
+open. `GET /turns?attention=1` is what the header asks to say "something is running, or
+waiting for you", on any page.
+"""
+
+import json
+import uuid
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlmodel import Session, col, select
+
+from app.assistant import worker
+from app.auth import CallerToken, CurrentUser
+from app.clock import utcnow
+from app.database import get_session
+from app.jobs.runner import ACTIVE_STATUSES
+from app.models.assistant import AssistantSession, AssistantTurn
+from app.providers import active_provider
+from app.schemas import DataResponse, ListResponse
+from app.schemas_assistant import (
+    Message, NewProjectRead, SessionRead, SessionSummary, Step, TurnCreate, TurnRead,
+)
+from app.services import projects as project_service
+from app.services.users import ensure_user
+from app.spec.model import BriefSource, dump_spec
+from app.spec.starter import starter_spec
+from app.spec.validation import parse_spec
+
+router = APIRouter()
+
+
+def _turn_read(turn: AssistantTurn) -> TurnRead:
+    proposal = json.loads(turn.proposed_spec) if turn.proposed_spec and \
+        turn.outcome == "pending" else None
+    return TurnRead(
+        id=turn.id, session_id=turn.session_id, project_id=turn.project_id, status=turn.status,
+        stage=turn.stage, detail=turn.detail, error=turn.error_message, prompt=turn.prompt,
+        steps=[Step(**s) for s in json.loads(turn.steps or "[]")], reply=turn.reply,
+        proposed_spec=proposal, changes=json.loads(turn.changes or "[]"), outcome=turn.outcome,
+        base_version=turn.base_version, cost=turn.cost,
+        created_at=turn.created_at, updated_at=turn.updated_at,
+    )
+
+
+def _summary(row: AssistantSession) -> SessionSummary:
+    return SessionSummary(id=row.id, project_id=row.project_id, title=row.title or "New chat",
+                          created_at=row.created_at, updated_at=row.updated_at)
+
+
+def _not_found(what: str) -> HTTPException:
+    return HTTPException(status_code=status.HTTP_404_NOT_FOUND,
+                         detail={"code": "not_found", "message": f"{what} not found"})
+
+
+def _owned_session(session: Session, user, session_id: str) -> AssistantSession:
+    row = session.get(AssistantSession, session_id)
+    if row is None or row.user_id != user.id:
+        raise _not_found("Conversation")
+    return row
+
+
+def _owned_turn(session: Session, user, turn_id: str) -> AssistantTurn:
+    row = session.get(AssistantTurn, turn_id)
+    if row is None or row.user_id != user.id:
+        raise _not_found("Turn")
+    return row
+
+
+# ── sessions ──────────────────────────────────────────────────────────────────
+
+@router.get("/sessions", response_model=ListResponse[SessionSummary])
+def list_sessions(user: CurrentUser, project_id: Optional[str] = None,
+                  limit: int = Query(default=20, ge=1, le=100),
+                  session: Session = Depends(get_session)) -> ListResponse[SessionSummary]:
+    """A project's conversations, newest first; without a project, the ones about new
+    videos not yet made."""
+    if project_id:
+        project_service.get_owned(session, user, project_id)
+    where = AssistantSession.project_id == project_id if project_id else \
+        col(AssistantSession.project_id).is_(None)
+    rows = session.exec(select(AssistantSession).where(
+        AssistantSession.user_id == user.id, where)
+        .order_by(AssistantSession.updated_at.desc()).limit(limit)).all()
+    return ListResponse(data=[_summary(r) for r in rows], total=len(rows), limit=limit, offset=0)
+
+
+@router.get("/sessions/{session_id}", response_model=DataResponse[SessionRead])
+def get_chat(session_id: str, user: CurrentUser,
+             session: Session = Depends(get_session)) -> DataResponse[SessionRead]:
+    row = _owned_session(session, user, session_id)
+    turns = session.exec(select(AssistantTurn).where(AssistantTurn.session_id == row.id)
+                         .order_by(AssistantTurn.created_at)).all()
+    return DataResponse(data=SessionRead(
+        **_summary(row).model_dump(),
+        messages=[Message(**m) for m in json.loads(row.messages or "[]")],
+        turns=[_turn_read(t) for t in turns],
+        cost=round(sum(t.cost or 0.0 for t in turns), 6),
+    ))
+
+
+@router.delete("/sessions/{session_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_chat(session_id: str, user: CurrentUser,
+                session: Session = Depends(get_session)) -> Response:
+    row = _owned_session(session, user, session_id)
+    turns = session.exec(select(AssistantTurn).where(AssistantTurn.session_id == row.id)).all()
+    if any(t.status in ACTIVE_STATUSES for t in turns):
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "turn_running", "message": "Stop the running turn first"})
+    for turn in turns:
+        session.delete(turn)
+    session.flush()
+    session.delete(row)
+    session.commit()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ── turns ─────────────────────────────────────────────────────────────────────
+
+@router.post("/turns", response_model=DataResponse[TurnRead], status_code=status.HTTP_202_ACCEPTED)
+def start_turn(body: TurnCreate, user: CurrentUser, token: CallerToken,
+               session: Session = Depends(get_session)) -> DataResponse[TurnRead]:
+    """Ask the assistant something. It runs in the background from here."""
+    if active_provider(session, user.id) is None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "no_provider",
+                                    "message": "Set up an AI provider in Settings first."})
+    project = project_service.get_owned(session, user, body.project_id) if body.project_id \
+        else None
+    if body.session_id:
+        chat = _owned_session(session, user, body.session_id)
+        if chat.project_id != (project.id if project else None):
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
+                                detail={"code": "wrong_session",
+                                        "message": "That conversation is about another video"})
+        running = session.exec(select(AssistantTurn).where(
+            AssistantTurn.session_id == chat.id,
+            col(AssistantTurn.status).in_(ACTIVE_STATUSES))).first()
+        if running is not None:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                                detail={"code": "turn_running",
+                                        "message": "The assistant is still working on the last request"})
+    else:
+        ensure_user(session, user)
+        chat = AssistantSession(id=str(uuid.uuid4()), user_id=user.id,
+                                project_id=project.id if project else None)
+        session.add(chat)
+        session.commit()
+        session.refresh(chat)
+
+    if body.draft_spec is not None:
+        base = body.draft_spec
+    elif project is not None:
+        base = project_service.decode(project.spec)
+    else:
+        base = dump_spec(starter_spec("Untitled video"))
+    turn = worker.submit(session, chat, user_id=user.id, token=token, prompt=body.prompt.strip(),
+                         base_spec=base,
+                         base_version=body.base_version if body.base_version is not None
+                         else (project.head_seq if project else None),
+                         focus=body.focus)
+    return DataResponse(data=_turn_read(turn))
+
+
+@router.get("/turns", response_model=ListResponse[TurnRead])
+def list_turns(user: CurrentUser, attention: bool = False,
+               limit: int = Query(default=20, ge=1, le=100),
+               session: Session = Depends(get_session)) -> ListResponse[TurnRead]:
+    """With `attention`: what is running, or finished with a proposal not yet acted on."""
+    query = select(AssistantTurn).where(AssistantTurn.user_id == user.id)
+    if attention:
+        query = query.where((col(AssistantTurn.status).in_(ACTIVE_STATUSES))
+                            | (AssistantTurn.outcome == "pending"))
+    rows = session.exec(query.order_by(AssistantTurn.created_at.desc()).limit(limit)).all()
+    return ListResponse(data=[_turn_read(t) for t in rows], total=len(rows), limit=limit, offset=0)
+
+
+@router.get("/turns/{turn_id}", response_model=DataResponse[TurnRead])
+def get_turn(turn_id: str, user: CurrentUser,
+             session: Session = Depends(get_session)) -> DataResponse[TurnRead]:
+    return DataResponse(data=_turn_read(_owned_turn(session, user, turn_id)))
+
+
+@router.delete("/turns/{turn_id}", response_model=DataResponse[TurnRead])
+def stop_turn(turn_id: str, user: CurrentUser,
+              session: Session = Depends(get_session)) -> DataResponse[TurnRead]:
+    turn = _owned_turn(session, user, turn_id)
+    if turn.status in ACTIVE_STATUSES:
+        worker.queue.cancel(turn.id)
+        if turn.status == "queued":
+            # Never picked up, so nothing will unwind it: say so now.
+            turn.status, turn.stage, turn.updated_at = "cancelled", "", utcnow()
+            chat = session.get(AssistantSession, turn.session_id)
+            if chat:
+                worker.append_message(chat, "assistant", "_Stopped._", turn.id)
+                session.add(chat)
+            session.add(turn)
+            session.commit()
+            session.refresh(turn)
+    return DataResponse(data=_turn_read(turn))
+
+
+def _decide(session: Session, user, turn_id: str, outcome: str) -> AssistantTurn:
+    turn = _owned_turn(session, user, turn_id)
+    if turn.outcome != "pending":
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "nothing_pending",
+                                    "message": "That proposal was already applied or discarded"})
+    turn.outcome, turn.updated_at = outcome, utcnow()
+    session.add(turn)
+    session.commit()
+    session.refresh(turn)
+    return turn
+
+
+@router.post("/turns/{turn_id}/applied", response_model=DataResponse[TurnRead])
+def mark_applied(turn_id: str, user: CurrentUser,
+                 session: Session = Depends(get_session)) -> DataResponse[TurnRead]:
+    """The editor loaded the proposal into its draft (saving it is the editor's)."""
+    return DataResponse(data=_turn_read(_decide(session, user, turn_id, "applied")))
+
+
+@router.post("/turns/{turn_id}/discarded", response_model=DataResponse[TurnRead])
+def mark_discarded(turn_id: str, user: CurrentUser,
+                   session: Session = Depends(get_session)) -> DataResponse[TurnRead]:
+    return DataResponse(data=_turn_read(_decide(session, user, turn_id, "discarded")))
+
+
+@router.post("/turns/{turn_id}/new-project", response_model=DataResponse[NewProjectRead],
+             status_code=status.HTTP_201_CREATED)
+def apply_as_new_project(turn_id: str, user: CurrentUser,
+                         session: Session = Depends(get_session)) -> DataResponse[NewProjectRead]:
+    """Apply a draft made from the project list: it becomes a project of its own, and the
+    conversation moves with it."""
+    turn = _owned_turn(session, user, turn_id)
+    if turn.outcome != "pending" or not turn.proposed_spec:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "nothing_pending",
+                                    "message": "That draft was already applied or discarded"})
+    if turn.project_id is not None:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
+                            detail={"code": "has_project",
+                                    "message": "This proposal is for an existing project"})
+    spec, issues = parse_spec(json.loads(turn.proposed_spec))
+    if spec is None:
+        raise project_service.invalid_spec(issues)
+    if spec.source is None:
+        # Where it came from (S2), so a draft can be traced and redone.
+        provider = active_provider(session, user.id)
+        spec.source = BriefSource(kind="brief", prompt=turn.prompt,
+                                  drafted_at=turn.created_at.isoformat(timespec="seconds") + "Z",
+                                  provider=provider.provider_type if provider else None,
+                                  model=provider.model if provider else None)
+    project = project_service.create(session, user, spec, origin="brief",
+                                     message="Drafted by the assistant", author="ai")
+    turn.outcome, turn.project_id, turn.updated_at = "applied", project.id, utcnow()
+    chat = session.get(AssistantSession, turn.session_id)
+    if chat is not None:
+        chat.project_id = project.id
+        session.add(chat)
+        # The conversation's other turns move with it, so the project shows them.
+        for other in session.exec(select(AssistantTurn).where(
+                AssistantTurn.session_id == chat.id)).all():
+            other.project_id = project.id
+            session.add(other)
+    session.add(turn)
+    session.commit()
+    return DataResponse(data=NewProjectRead(project_id=project.id))
diff --git a/backend/app/schemas_assistant.py b/backend/app/schemas_assistant.py
new file mode 100644
index 0000000..524f789
--- /dev/null
+++ b/backend/app/schemas_assistant.py
@@ -0,0 +1,73 @@
+"""Request and response bodies for the assistant."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TurnCreate(BaseModel):
+    # None: continue in a new session (for this project, or for a new video).
+    session_id: Optional[str] = None
+    project_id: Optional[str] = None
+    prompt: str = Field(min_length=1, max_length=20_000)
+    # The editor's draft, unsaved edits included. Absent: the saved version (or, with
+    # no project, a blank starter).
+    draft_spec: Optional[Dict[str, Any]] = None
+    # The project version the draft was opened from.
+    base_version: Optional[int] = None
+    # The segment open in the editor, if any.
+    focus: Optional[str] = None
+
+
+class Step(BaseModel):
+    kind: str
+    text: str
+
+
+class TurnRead(BaseModel):
+    id: str
+    session_id: str
+    project_id: Optional[str] = None
+    status: str
+    stage: str
+    detail: str
+    error: Optional[str] = None
+    prompt: str
+    steps: List[Step] = []
+    reply: str = ""
+    # Present while there is a proposal: the whole spec to load into the editor.
+    proposed_spec: Optional[Dict[str, Any]] = None
+    changes: List[str] = []
+    outcome: str = ""
+    base_version: Optional[int] = None
+    cost: Optional[float] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class Message(BaseModel):
+    role: str
+    text: str
+    turn_id: Optional[str] = None
+    at: Optional[str] = None
+
+
+class SessionSummary(BaseModel):
+    id: str
+    project_id: Optional[str] = None
+    title: str
+    created_at: datetime
+    updated_at: datetime
+
+
+class SessionRead(SessionSummary):
+    messages: List[Message] = []
+    # Every turn of the session, newest last, so the panel can show each one's steps,
+    # change card and cost beside its message.
+    turns: List[TurnRead] = []
+    cost: float = 0.0
+
+
+class NewProjectRead(BaseModel):
+    project_id: str
diff --git a/backend/app/services/projects.py b/backend/app/services/projects.py
index 024df2f..7acd0b4 100644
--- a/backend/app/services/projects.py
+++ b/backend/app/services/projects.py
@@ -102,7 +102,8 @@ def _commit_spec(
 
 
 def create(
-    session: Session, user: UserCtx, spec: VideoSpec, *, origin: str, message: str
+    session: Session, user: UserCtx, spec: VideoSpec, *, origin: str, message: str,
+    author: str = "user",
 ) -> Project:
     # The project row has a foreign key to the shadow user, which `/api/me` normally
     # writes first. A Notes push may well be the first request this user ever makes.
@@ -110,7 +111,7 @@ def create(
     now = utcnow()
     project = Project(id=str(uuid.uuid4()), user_id=user.id, origin=origin,
                       created_at=now, updated_at=now)
-    _commit_spec(session, project, spec, author="user", message=message)
+    _commit_spec(session, project, spec, author=author, message=message)
     return project
 
 
@@ -178,6 +179,12 @@ def delete(session: Session, project: Project) -> None:
     for job in session.exec(select(RenderJob).where(RenderJob.project_id == project.id)).all():
         shutil.rmtree(renders_dir() / job.id, ignore_errors=True)
     session.exec(sa_delete(RenderJob).where(RenderJob.project_id == project.id))
+    # The assistant's conversations about it go too (their spend stays in UsageEvent).
+    # Turns before sessions, for the same foreign-key reason as versions.
+    from app.models.assistant import AssistantSession, AssistantTurn
+
+    session.exec(sa_delete(AssistantTurn).where(AssistantTurn.project_id == project.id))
+    session.exec(sa_delete(AssistantSession).where(AssistantSession.project_id == project.id))
     session.exec(sa_delete(ProjectVersion).where(ProjectVersion.project_id == project.id))
     session.delete(project)
     session.commit()
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index c65b49a..021534a 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -119,6 +119,11 @@ def no_render_workers(monkeypatch, tmp_path):
     monkeypatch.setattr(worker.queue, "start", lambda: None)
     monkeypatch.setattr(worker.queue, "enqueue", lambda job_id: None)
     monkeypatch.setattr(settings, "data_dir", str(tmp_path / "data"))
+    # The assistant's queue, the same way: a test runs a turn with `worker._run`.
+    from app.assistant import worker as assistant_worker
+
+    monkeypatch.setattr(assistant_worker.queue, "start", lambda: None)
+    monkeypatch.setattr(assistant_worker.queue, "enqueue", lambda job_id: None)
 
 
 # ── media a render can really encode ─────────────────────────────────────────
diff --git a/backend/tests/fake_provider.py b/backend/tests/fake_provider.py
new file mode 100644
index 0000000..87a783f
--- /dev/null
+++ b/backend/tests/fake_provider.py
@@ -0,0 +1,62 @@
+"""A chat provider that plays back a script, for running whole assistant turns offline.
+
+Each scripted reply is a `Reply`; the fake records what it was told (tool results and
+mid-turn messages) so a test can assert on the conversation as well as the outcome.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from app.providers.base import Reply, ToolCall, ToolResult, ToolSpec, Usage
+
+
+def call(name: str, **arguments: Any) -> ToolCall:
+    call.counter += 1
+    return ToolCall(id=f"c{call.counter}", name=name, arguments=arguments)
+
+
+call.counter = 0
+
+
+def says(text: str = "", *calls: ToolCall, stop: Optional[str] = None,
+         tokens: Tuple[int, int] = (1000, 200)) -> Reply:
+    return Reply(text=text, tool_calls=list(calls),
+                 stop=stop or ("tool_use" if calls else "end"),
+                 usage=Usage(*tokens), model="claude-opus-5-5", provider_type="anthropic")
+
+
+@dataclass
+class ScriptedConversation:
+    script: List[Reply]
+    log: List[Tuple[str, Any]]
+
+    def ask(self) -> Reply:
+        if not self.script:
+            raise AssertionError("the model was asked more often than the script allows")
+        reply = self.script.pop(0)
+        self.log.append(("reply", reply))
+        return reply
+
+    def answer(self, results: Sequence[ToolResult]) -> None:
+        self.log.append(("results", list(results)))
+
+    def tell(self, text: str) -> None:
+        self.log.append(("told", text))
+
+
+@dataclass
+class ScriptedProvider:
+    script: List[Reply]
+    log: List[Tuple[str, Any]] = field(default_factory=list)
+    started: Dict[str, Any] = field(default_factory=dict)
+    model: str = "claude-opus-5-5"
+    provider_type: str = "anthropic"
+
+    def conversation(self, *, system: Sequence[str], tools: Sequence[ToolSpec],
+                     history: Sequence[Tuple[str, str]], prompt: str) -> ScriptedConversation:
+        self.started = {"system": list(system), "tools": [t.name for t in tools],
+                        "history": list(history), "prompt": prompt}
+        return ScriptedConversation(self.script, self.log)
+
+    def results(self) -> List[ToolResult]:
+        return [r for kind, batch in self.log if kind == "results" for r in batch]
diff --git a/backend/tests/test_assistant_tools.py b/backend/tests/test_assistant_tools.py
new file mode 100644
index 0000000..2df8423
--- /dev/null
+++ b/backend/tests/test_assistant_tools.py
@@ -0,0 +1,181 @@
+"""The assistant's operations on a working copy of a spec: pure, with GAM faked."""
+
+import pytest
+
+from app.assistant import tools as T
+from app.assistant.tools import Working
+from app.gam.client import GamClient
+from app.providers.base import ToolCall
+from tests.fake_siblings import gam_asset, hit
+
+
+def spec():
+    return {
+        "title": "Water Wars",
+        "assets": {"a_map": {"from": "gam", "id": "p", "type": "image", "label": "Map"}},
+        "segments": [
+            {"id": "s_title", "kind": "card", "label": "Title",
+             "card": {"variant": "title", "title": "Water Wars"}},
+            {"id": "s_valley", "kind": "scene", "label": "The valley",
+             "visual": {"asset": "a_map"},
+             "narration": {"beats": [{"id": "b1", "text": "The valley used to run clear."}]}},
+        ],
+        "audio_tracks": [
+            {"id": "m_theme", "asset": "a_map", "start": {"segment": "s_valley", "edge": "start"}},
+        ],
+    }
+
+
+def run(w, name, **arguments):
+    return T.execute(w, ToolCall(id="x", name=name, arguments=arguments))
+
+
+def test_a_valid_spec_stays_valid_and_a_breaking_edit_is_refused_untouched():
+    w = Working(spec())
+    before = w.data
+    result = run(w, "update_segment", segment_id="s_valley",
+                 changes={"transition_in": {"style": "sideways"}})
+    assert result.is_error and "transition_in" in result.content
+    assert w.data == before and w.changes == []
+
+    result = run(w, "update_segment", segment_id="s_valley",
+                 changes={"transition_in": {"style": "dissolve"}, "chapter": "The valley"})
+    assert not result.is_error
+    assert w.data["segments"][1]["transition_in"] == {"style": "dissolve"}
+    assert w.changes == ["Changed The valley: chapter, transition_in"]
+
+
+def test_segments_are_addressed_by_id_and_unknown_ids_say_what_exists():
+    w = Working(spec())
+    result = run(w, "update_segment", segment_id="s_nope", changes={"label": "x"})
+    assert result.is_error and "s_title, s_valley" in result.content
+
+    run(w, "add_segment", after="s_title",
+        segment={"id": "s_title", "kind": "scene", "label": "Dam",
+                 "narration": {"beats": [{"id": "b1", "text": "Then came the dam."}]}})
+    # A taken id is replaced, never duplicated.
+    assert [s["id"] for s in w.data["segments"]] == ["s_title", "s_3", "s_valley"]
+    run(w, "move_segment", segment_id="s_3", after="s_valley")
+    assert [s["id"] for s in w.data["segments"]] == ["s_title", "s_valley", "s_3"]
+
+
+def test_a_merge_patch_removes_with_null_and_replaces_lists_whole():
+    w = Working(spec())
+    run(w, "update_segment", segment_id="s_valley", changes={
+        "visual": {"motion": {"effect": "zoom_in"}},
+        "narration": {"beats": [{"id": "b1", "text": "One."}, {"id": "b2", "text": "Two."}]}})
+    segment = w.data["segments"][1]
+    assert segment["visual"] == {"asset": "a_map", "motion": {"effect": "zoom_in"}}
+    assert [b["id"] for b in segment["narration"]["beats"]] == ["b1", "b2"]
+    run(w, "update_segment", segment_id="s_valley", changes={"visual": {"motion": None}})
+    assert "motion" not in w.data["segments"][1]["visual"]
+
+
+def test_removing_a_segment_says_what_was_anchored_to_it():
+    w = Working(spec())
+    result = run(w, "remove_segment", segment_id="s_valley")
+    assert not result.is_error
+    assert "audio track m_theme" in result.content
+
+
+def test_a_draft_with_mistakes_is_kept_and_repaired_edit_by_edit():
+    w = Working(spec())
+    draft = spec()
+    draft["segments"][1]["transition_in"] = {"style": "sideways"}
+    result = run(w, "replace_spec", spec=draft)
+    assert not result.is_error and "1 issue to fix" in result.content and not w.valid
+    # While issues remain, an edit is accepted and says what is left.
+    result = run(w, "update_segment", segment_id="s_valley", changes={"label": "Valley"})
+    assert "still has issues" in result.content
+    result = run(w, "update_segment", segment_id="s_valley",
+                 changes={"transition_in": {"style": "dissolve"}})
+    assert w.valid and result.content.startswith("Done")
+
+
+def test_the_project_id_survives_a_replaced_draft():
+    data = spec()
+    data["id"] = "proj-1"
+    w = Working(data)
+    run(w, "replace_spec", spec={**spec(), "id": "someone-else"})
+    assert w.data["id"] == "proj-1"
+
+
+@pytest.fixture
+def gam(siblings):
+    reel = gam_asset("r", "River interview", "video", duration_seconds=600.0,
+                     credit="Footage: River Archive")
+    siblings.assets["r"] = reel
+    siblings.hits = [hit(reel, start=42.0, end=47.5, snippet="the «water» is gone")]
+    client = GamClient("user-token")
+    yield client
+    client.close()
+
+
+def test_a_search_hit_becomes_the_visual_with_its_moment_as_the_trim(gam, siblings):
+    w = Working(spec(), gam=gam)
+    found = run(w, "search_assets", query="people talking about water", type="video")
+    assert '"said_at":[42.0,47.5]' in found.content and "River Archive" in found.content
+    assert siblings.gam_requests()[0].headers["authorization"] == "Bearer user-token"
+
+    result = run(w, "set_visual", segment_id="s_valley", gam_id="r")
+    assert not result.is_error
+    visual = w.data["segments"][1]["visual"]
+    assert visual == {"asset": "a_river_interview", "trim": {"in": 41.5, "out": 48.0}}
+    assert w.data["assets"]["a_river_interview"] == {
+        "from": "gam", "id": "r", "type": "video", "label": "River interview"}
+
+
+def test_an_empty_search_says_to_try_again_or_leave_a_placeholder(gam, siblings):
+    siblings.hits = []
+    w = Working(spec(), gam=gam)
+    assert "add_placeholder" in run(w, "search_assets", query="glaciers").content
+    result = run(w, "add_placeholder", segment_id="s_valley", kind="search",
+                 text="a melting glacier", moment_min=4)
+    assert not result.is_error
+    key = w.data["segments"][1]["visual"]["asset"]
+    assert w.data["assets"][key] == {"from": "search", "query": "a melting glacier",
+                                     "type": "video", "moment": {"min": 4}}
+
+
+def test_overlays_and_tracks_by_id(gam):
+    w = Working(spec(), gam=gam)
+    run(w, "search_assets", query="river")
+    run(w, "add_overlay", segment_id="s_valley",
+        overlay={"type": "lower_third", "title": "Ada", "subtitle": "Hydrologist"})
+    [overlay] = w.data["segments"][1]["overlays"]
+    run(w, "update_overlay", segment_id="s_valley", overlay_id=overlay["id"],
+        changes={"show": {"from": {"edge": "start", "offset": 0.5}, "to": {"edge": "end"}}})
+    assert w.data["segments"][1]["overlays"][0]["show"]["from"]["offset"] == 0.5
+    run(w, "add_audio_track", gam_id="r", track={
+        "kind": "sfx", "start": {"segment": "s_valley", "beat": "b1", "edge": "start"}})
+    track = w.data["audio_tracks"][-1]
+    assert track["id"].startswith("x_") and w.data["assets"][track["asset"]]["id"] == "r"
+    run(w, "update_audio_track", track_id=track["id"], changes={"volume": 0.5})
+    run(w, "remove_audio_track", track_id="m_theme")
+    assert [t["id"] for t in w.data["audio_tracks"]] == [track["id"]]
+    assert w.valid
+
+
+def test_project_settings_only_through_set_project():
+    w = Working(spec())
+    result = run(w, "set_project", changes={"segments": []})
+    assert result.is_error and "Segments and tracks" in result.content
+    run(w, "set_project", changes={"style": {"transition": {"style": "dissolve"}},
+                                   "credits": {"extra": ["Narrated by Rex"]}})
+    assert w.data["style"]["transition"] == {"style": "dissolve"}
+    assert w.valid
+
+
+def test_bad_calls_come_back_as_errors_never_exceptions():
+    w = Working(spec())
+    assert run(w, "no_such_tool").is_error
+    assert run(w, "update_segment", segment_id="s_valley").is_error   # missing argument
+    unreadable = T.execute(w, ToolCall(id="x", name="get_spec", arguments={},
+                                       parse_error="not JSON"))
+    assert unreadable.is_error and "not JSON" in unreadable.content
+
+
+def test_estimate_reads_the_working_copy():
+    w = Working(spec())
+    result = run(w, "estimate")
+    assert '"narration_chars":' in result.content and not result.is_error
diff --git a/backend/tests/test_assistant_turns.py b/backend/tests/test_assistant_turns.py
new file mode 100644
index 0000000..ab07473
--- /dev/null
+++ b/backend/tests/test_assistant_turns.py
@@ -0,0 +1,296 @@
+"""Whole assistant turns, over HTTP and through the worker, with a scripted provider.
+
+A turn is a background job: these start one with the API, run it with `worker._run` (the
+queue is stubbed in conftest, so nothing runs on its own), then read what it left on its
+row, which is what a person coming back to the page would see.
+"""
+
+import json
+
+import pytest
+
+from app.assistant import worker
+from app.models.provider import AIProvider
+from app.models.usage import UsageEvent
+from tests.conftest import TEST_USER_ID
+from tests.fake_provider import ScriptedProvider, call, says
+from tests.fake_siblings import gam_asset, hit
+
+
+@pytest.fixture
+def engine_for_worker(engine, monkeypatch):
+    monkeypatch.setattr(worker.queue, "engine", engine)
+    return engine
+
+
+@pytest.fixture
+def provider(session, monkeypatch):
+    """An active provider row (the API checks one exists) and a script to play back."""
+    from app.services.users import ensure_user
+    from app.auth import UserCtx
+
+    ensure_user(session, UserCtx(id=TEST_USER_ID, username=TEST_USER_ID))
+    session.add(AIProvider(user_id=TEST_USER_ID, name="Claude", provider_type="anthropic",
+                           model="claude-opus-5-5", api_key="sk", is_active=True))
+    session.commit()
+    scripted = ScriptedProvider(script=[])
+    monkeypatch.setattr(worker, "build_provider", lambda session, user_id: scripted)
+    return scripted
+
+
+@pytest.fixture
+def library(siblings):
+    reel = gam_asset("r", "River interview", "video", duration_seconds=600.0)
+    picture = gam_asset("p", "Valley map", "image", width=1600, height=900)
+    siblings.assets.update({"r": reel, "p": picture})
+    siblings.hits = [hit(reel, start=42.0, end=47.5, snippet="the «water» is gone"),
+                     hit(picture)]
+    return siblings
+
+
+DRAFT = {
+    "title": "Water Wars",
+    "style": {"transition": {"style": "fade", "duration": 0.6}},
+    "assets": {"a_map": {"from": "gam", "id": "p", "type": "image"}},
+    "segments": [
+        {"id": "s_title", "kind": "card", "label": "Title",
+         "card": {"variant": "title", "title": "Water Wars"}},
+        {"id": "s_valley", "kind": "scene", "label": "The valley",
+         "visual": {"asset": "a_map", "motion": {"effect": "zoom_in"}},
+         # The mistake the model then fixes from the issues it is handed.
+         "transition_in": {"style": "sideways"},
+         "narration": {"beats": [{"id": "b1", "text": "The valley used to run clear."}]}},
+    ],
+}
+
+
+def start(client, **body):
+    res = client.post("/api/assistant/turns", json={"prompt": "Make it", **body})
+    assert res.status_code == 202, res.text
+    return res.json()["data"]
+
+
+def test_a_video_from_a_prompt_searches_drafts_repairs_and_becomes_a_project(
+        auth_client, session, provider, library, engine_for_worker):
+    provider.script += [
+        says("Looking in your library.", call("search_assets", query="water", type="video")),
+        says("", call("replace_spec", spec=DRAFT)),
+        says("", call("update_segment", segment_id="s_valley",
+                      changes={"transition_in": {"style": "dissolve"}})),
+        says("", call("set_visual", segment_id="s_valley", gam_id="r")),
+        says("A two-scene draft: a title, then the valley over the river interview."),
+    ]
+    turn = start(auth_client, prompt="A short video about the water wars")
+    assert turn["status"] == "queued" and turn["project_id"] is None
+
+    worker._run(turn["id"])
+    done = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    assert done["status"] == "done", done
+    assert done["reply"] == "A two-scene draft: a title, then the valley over the river interview."
+    assert done["outcome"] == "pending"
+    # The proposal is the repaired draft, the found moment cut in.
+    valley = done["proposed_spec"]["segments"][1]
+    assert valley["transition_in"] == {"style": "dissolve"}
+    assert valley["visual"]["trim"] == {"in": 41.5, "out": 48.0}
+    assert done["changes"][0].startswith("Drafted the video")
+    kinds = [s["kind"] for s in done["steps"]]
+    assert kinds[:2] == ["think", "search"] and "edit" in kinds
+    # The model was told the issues, and fixed them in the next call.
+    replace_result = provider.results()[1]
+    assert "transition_in" in replace_result.content and "to fix" in replace_result.content
+    # Told it is a new video, given the reference and the tools.
+    assert "new video" in provider.started["system"][1]
+    assert "set_visual" in provider.started["tools"]
+
+    # Spend: one row per call, the turn's total on the turn.
+    rows = session.query(UsageEvent).all()
+    assert len(rows) == 5 and all(r.turn_id == turn["id"] for r in rows)
+    assert done["cost"] == pytest.approx(sum(r.cost for r in rows))
+
+    # Applying it from the project list makes the project, with the chat moved over.
+    made = auth_client.post(f"/api/assistant/turns/{turn['id']}/new-project")
+    assert made.status_code == 201, made.text
+    project_id = made.json()["data"]["project_id"]
+    project = auth_client.get(f"/api/projects/{project_id}").json()["data"]
+    assert project["origin"] == "brief" and project["title"] == "Water Wars"
+    assert project["spec"]["source"]["kind"] == "brief"
+    assert project["spec"]["source"]["prompt"] == "A short video about the water wars"
+    versions = auth_client.get(f"/api/projects/{project_id}/versions").json()["data"]
+    assert versions[0]["author"] == "ai"
+    chats = auth_client.get("/api/assistant/sessions", params={"project_id": project_id}).json()
+    assert [c["id"] for c in chats["data"]] == [turn["session_id"]]
+    again = auth_client.post(f"/api/assistant/turns/{turn['id']}/new-project")
+    assert again.status_code == 409
+
+
+def project_with(client, spec):
+    res = client.post("/api/projects", json={"spec": spec})
+    assert res.status_code == 201, res.text
+    return res.json()["data"]
+
+
+VALID = json.loads(json.dumps(DRAFT))
+VALID["segments"][1]["transition_in"] = {"style": "fade"}
+
+
+def test_an_edit_is_proposed_on_the_draft_and_waits_to_be_applied(
+        auth_client, provider, library, engine_for_worker):
+    project = project_with(auth_client, VALID)
+    # The editor's draft carries an unsaved edit; the proposal must keep it.
+    draft = json.loads(json.dumps(project["spec"]))
+    draft["segments"][1]["label"] = "Valley (unsaved)"
+    provider.script += [
+        says("", call("update_segment", segment_id="s_valley",
+                      changes={"transition_in": {"style": "dissolve"}})),
+        says("Dissolve into the valley now."),
+    ]
+    turn = start(auth_client, project_id=project["id"], prompt="dissolve into this scene",
+                 draft_spec=draft, base_version=project["version"], focus="s_valley")
+    worker._run(turn["id"])
+
+    done = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    valley = done["proposed_spec"]["segments"][1]
+    assert valley["transition_in"] == {"style": "dissolve"}
+    assert valley["label"] == "Valley (unsaved)"
+    assert done["base_version"] == project["version"]
+    assert "Focused segment" in provider.started["system"][1]
+    # Nothing reached the project.
+    saved = auth_client.get(f"/api/projects/{project['id']}").json()["data"]
+    assert saved["version"] == project["version"]
+
+    # Still waiting when the person comes back, on any page.
+    waiting = auth_client.get("/api/assistant/turns", params={"attention": True}).json()["data"]
+    assert [t["id"] for t in waiting] == [turn["id"]]
+    assert auth_client.post(f"/api/assistant/turns/{turn['id']}/applied").status_code == 200
+    assert auth_client.get("/api/assistant/turns", params={"attention": True}).json()["data"] == []
+    assert auth_client.post(f"/api/assistant/turns/{turn['id']}/discarded").status_code == 409
+
+
+def test_a_question_changes_nothing_and_proposes_nothing(
+        auth_client, provider, engine_for_worker):
+    project = project_with(auth_client, VALID)
+    provider.script += [says("", call("estimate")), says("About 7 seconds.")]
+    turn = start(auth_client, project_id=project["id"], prompt="how long is it?")
+    worker._run(turn["id"])
+    done = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    assert done["reply"] == "About 7 seconds." and done["proposed_spec"] is None
+    assert done["outcome"] == "" and done["changes"] == []
+
+
+def test_a_model_that_stops_with_issues_is_told_to_fix_them_then_nothing_is_proposed(
+        auth_client, provider, engine_for_worker):
+    provider.script += [
+        says("", call("replace_spec", spec=DRAFT)),
+        says("Here it is."), says("Done, I think."), says("Really done."),
+    ]
+    turn = start(auth_client, prompt="draft")
+    worker._run(turn["id"])
+    done = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    told = [entry for kind, entry in provider.log if kind == "told"]
+    assert len(told) == 2 and "transition_in" in told[0]
+    assert done["proposed_spec"] is None and "nothing to apply" in done["reply"]
+
+
+def test_the_conversation_carries_on_with_its_history(auth_client, provider, engine_for_worker):
+    project = project_with(auth_client, VALID)
+    provider.script += [says("First answer.")]
+    first = start(auth_client, project_id=project["id"], prompt="first question")
+    worker._run(first["id"])
+    provider.script += [says("Second answer.")]
+    second = start(auth_client, project_id=project["id"], session_id=first["session_id"],
+                   prompt="second question")
+    worker._run(second["id"])
+    assert provider.started["history"] == [("user", "first question"),
+                                           ("assistant", "First answer.")]
+    assert provider.started["prompt"] == "second question"
+    chat = auth_client.get(f"/api/assistant/sessions/{first['session_id']}").json()["data"]
+    assert [m["text"] for m in chat["messages"]] == [
+        "first question", "First answer.", "second question", "Second answer."]
+    assert [t["id"] for t in chat["turns"]] == [first["id"], second["id"]]
+    assert chat["title"] == "first question"
+
+
+def test_one_turn_at_a_time_per_conversation(auth_client, provider):
+    first = start(auth_client)
+    again = auth_client.post("/api/assistant/turns",
+                             json={"prompt": "more", "session_id": first["session_id"]})
+    assert again.status_code == 409 and again.json()["detail"]["code"] == "turn_running"
+
+
+def test_no_provider_says_where_to_set_one_up(auth_client):
+    res = auth_client.post("/api/assistant/turns", json={"prompt": "hi"})
+    assert res.status_code == 409 and res.json()["detail"]["code"] == "no_provider"
+
+
+def test_stop_ends_a_queued_turn_and_a_running_one_at_its_next_round(
+        auth_client, provider, engine_for_worker, monkeypatch):
+    queued = start(auth_client)
+    stopped = auth_client.delete(f"/api/assistant/turns/{queued['id']}").json()["data"]
+    assert stopped["status"] == "cancelled"
+    worker._run(queued["id"])   # reaching it later, the worker leaves it alone
+    assert auth_client.get(f"/api/assistant/turns/{queued['id']}").json()["data"]["status"] == "cancelled"
+
+    running = start(auth_client, prompt="again")
+    provider.script += [says("", call("estimate"))]
+    calls = iter([False, True, True])
+    monkeypatch.setattr(worker.queue, "is_cancelled", lambda job_id: next(calls))
+    worker._run(running["id"])
+    done = auth_client.get(f"/api/assistant/turns/{running['id']}").json()["data"]
+    assert done["status"] == "cancelled"
+
+
+def test_a_restart_ends_a_turn_and_says_so(auth_client, provider, engine_for_worker):
+    turn = start(auth_client)
+    worker._tokens.clear()      # what a restart does to the in-memory tokens
+    worker._run(turn["id"])
+    ended = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    assert ended["status"] == "error" and "restart" in ended["error"]
+    chat = auth_client.get(f"/api/assistant/sessions/{turn['session_id']}").json()["data"]
+    assert "restart" in chat["messages"][-1]["text"]
+
+
+def test_a_provider_failure_is_the_turns_error_in_its_own_words(
+        auth_client, provider, engine_for_worker, monkeypatch):
+    from app.providers.base import ProviderError
+
+    def broken():
+        raise ProviderError("Claude: the API key was rejected")
+
+    turn = start(auth_client)
+    provider.script.clear()
+    monkeypatch.setattr(provider, "conversation", lambda **kw: type(
+        "C", (), {"ask": staticmethod(broken)})())
+    worker._run(turn["id"])
+    failed = auth_client.get(f"/api/assistant/turns/{turn['id']}").json()["data"]
+    assert failed["status"] == "error" and "key was rejected" in failed["error"]
+
+
+def test_the_token_is_never_stored(auth_client, session, provider, engine_for_worker):
+    from app.models.assistant import AssistantTurn
+
+    turn = start(auth_client)
+    row = session.get(AssistantTurn, turn["id"])
+    assert "token" not in json.dumps(row.model_dump(mode="json")).lower()
+
+
+def test_someone_elses_conversation_and_turns_do_not_exist_for_you(
+        auth_client, provider, switch_user):
+    turn = start(auth_client)
+    switch_user("someone-else")
+    for method, url in (("get", f"/api/assistant/turns/{turn['id']}"),
+                        ("delete", f"/api/assistant/turns/{turn['id']}"),
+                        ("post", f"/api/assistant/turns/{turn['id']}/applied"),
+                        ("post", f"/api/assistant/turns/{turn['id']}/new-project"),
+                        ("get", f"/api/assistant/sessions/{turn['session_id']}"),
+                        ("delete", f"/api/assistant/sessions/{turn['session_id']}")):
+        assert getattr(auth_client, method)(url).status_code == 404, (method, url)
+
+
+def test_deleting_a_project_deletes_its_conversations(auth_client, session, provider):
+    from app.models.assistant import AssistantSession, AssistantTurn
+
+    project = project_with(auth_client, VALID)
+    start(auth_client, project_id=project["id"])
+    assert auth_client.delete(f"/api/projects/{project['id']}").status_code == 204
+    assert session.query(AssistantTurn).count() == 0
+    assert session.query(AssistantSession).count() == 0
diff --git a/docs/plan-of-attack.md b/docs/plan-of-attack.md
index c91fae7..d93cf2b 100644
--- a/docs/plan-of-attack.md
+++ b/docs/plan-of-attack.md
@@ -122,6 +122,14 @@ as a `search` or `generate` placeholder rather than inventing an asset id. A pre
 renders placeholders as labelled slates, so a draft is watchable before every shot
 exists.
 
+**As built (M4/M5 together).** One assistant does both, with one tool set: the draft is
+a `replace_spec` tool call rather than structured output, and every tool, `replace_spec`
+included, validates the working copy as it goes and returns the issues to the model. So
+the "one repair round" became a repair at every step, by the model that made the
+mistake. A turn ends with one proposal (the whole spec, plus a line per change) applied
+or discarded as a whole, rather than suggestions accepted one by one: the user chose
+that, and the editor's draft, Save and History already give per-change undo.
+
 ### D3. GVC stands by itself: three ways in, one project
 
 GVC is a complete tool on its own. There are three ways to start a video, and all of
@@ -289,8 +297,8 @@ Each milestone ends with something you can use, not just with code merged.
 | **M1** | **GAM as the library** | GAM-1 applied (gam#36). GVC's server calls GAM as the signed-in user by forwarding their own Notes token, so GAM's ownership checks hold and no service account exists. Search GAM from a scene: results with transcript snippets and the moment's time; picking a hit places it as muted b-roll or as a clip with its own sound, trimmed to what was said (padded, and sized by a placeholder's `moment`). `search` placeholders resolved the same way. Thumbnails and names looked up per page load, since GAM's signed URLs expire, and loaded straight from GAM (CSP `img-src`/`media-src`). A pushed note's media copied into GAM (D3). The byte cache keyed on asset id and checksum moved to M2: nothing reads media bytes until the renderer does. | A scene's footage is found by what is said in it ("where people talk about *X*") and lands in the spec as a trimmed GAM clip |
 | **M2** | **Native renderer** | **Built (M2a).** Engine copied from Notes (`app/render/`: ffmpeg, compose, narration, pause markup, shot cache, with Notes' 359 tests). `compile.py` is the §5.8 compile step, done natively: scenes cut at quote/code beats, defaults cascading field by field, per-join transitions (blends overlap, dips draw in-shot, cuts cut), anchors resolved to seconds. Ken Burns paths between two frames (S1), trimmed and held clips, N audio tracks with fades, crossfades and ducking. Media fetched from GAM into a cache keyed on GAM id and size; placeholders drawn as slates in a preview, refusing a full render. Narration read per beat through Notes (GN-V4), so beat anchors are exact. Render jobs on GAM's runner; the requester's token held in memory only, so a restart ends a render rather than storing a credential. Finished files at signed, ranged URLs. Editor: per-scene transition and Ken Burns (with a frame editor), a Soundtrack tab, a Render tab with estimate, progress and the result. **M2b:** timed text, lower thirds and pictures, drawn over the stitched video in one extra pass (`enable=` windows with alpha fades) so they can be held across a join, anchored to a scene's edges or lines; end credits from each GAM asset's credit plus extra lines, as cards and in a description (chapters + credits) to paste where the video is published; Save to GAM (GAM-3) for full renders, once per render. | A spec with two music tracks crossfading at a scene cut, a dissolve into one scene, and a Ken Burns path over a chosen part of a picture renders correctly |
 | **M3** | **Editor** | The M0 scene list grows into the storyboard: a card per segment (thumbnail, label, first line), lanes for audio tracks and overlays against the segments, a per-scene panel (visual, trim, transition, motion with a drag-a-box framing tool, voice), a project defaults panel. Sliders take their ranges from the schema (the Notes spec doc, open decision 12). Undo/redo over `ProjectVersion`. | You can build and fix a whole video by hand without opening the JSON tab |
-| **M4** | **AI drafting** | Providers copied from GAM's M6. "New video from a prompt": brief → spec (D2) with GAM search as a tool, and placeholders for gaps, with one repair round. Also from selected GAM assets. Cost estimate before running, usage recorded. | "Make a 3-minute video about *X* using clips where people talk about it" produces a spec that previews immediately |
-| **M5** | **AI editing** | The Notes spec doc §8.2 operations, addressed by id. Chat beside the storyboard. Suggestions staged and accepted one by one. Generate placeholders sent to GAM's M8. | "Change the music after the second chapter to something calmer, and dissolve into the last scene" becomes reviewed, applied edits |
+| **M4** | **AI drafting** | **Built, with M5, as one assistant.** Providers, usage and pricing copied from GAM's M6, with the clients made multi-turn and tool-calling (Anthropic and OpenAI-compatible, Ollama over `/v1`). A panel beside every page, collapsible as in Notes. From the project list, "describe a video" drafts one: GAM search as a tool, moments said in videos cut in as trims, placeholders for gaps, the draft repaired from its validation issues, applied as a new project with `source: brief` and `author: ai`. Each turn's estimated cost is shown, and usage recorded per project and turn. Turns are background jobs: they finish with the page closed, and wait for Apply. | "Make a 3-minute video about *X* using clips where people talk about it" produces a spec that previews immediately |
+| **M5** | **AI editing** | **Built, with M4.** The §8.2 operations as tools, addressed by id: segments, visuals, placeholders, overlays, tracks and project settings by merge patch. The turn starts from the editor's draft (unsaved edits included) and the focused scene; it ends with one proposal applied into the draft, warned about if the project was saved in between. Not yet: generate placeholders sent to GAM's M8, and `split`/`merge` of segments as their own tools (`update_segment` and `add_segment` cover them). | "Change the music after the second chapter to something calmer, and dissolve into the last scene" becomes reviewed, applied edits |
 | **M6** | **Notes hands over** | GN-V1 to GN-V3: "Make video" in Notes pushes to GVC, and Notes' render pipeline is retired (the Notes spec doc §10, Phase 4). | No render code left in Notes |
 
 **M1 before M2** is the user's call: real media from GAM from the first render, with
diff --git a/frontend/src/api/assistant.ts b/frontend/src/api/assistant.ts
new file mode 100644
index 0000000..4bc846f
--- /dev/null
+++ b/frontend/src/api/assistant.ts
@@ -0,0 +1,135 @@
+import client from '@/api/client'
+import type { VideoSpec } from '@/api/projects'
+
+/**
+ * The assistant. A turn is a background job on the server, so nothing here needs the
+ * page to stay open: a turn started and left keeps running, and is found again by
+ * `sessions` and `attention` on the way back.
+ */
+
+export type TurnStatus = 'queued' | 'processing' | 'done' | 'error' | 'cancelled'
+
+export interface TurnStep {
+  kind: 'think' | 'search' | 'edit' | 'issue' | 'note'
+  text: string
+}
+
+export interface Turn {
+  id: string
+  session_id: string
+  project_id: string | null
+  status: TurnStatus
+  stage: string
+  detail: string
+  error: string | null
+  prompt: string
+  steps: TurnStep[]
+  reply: string
+  /** The whole proposed spec, while the proposal waits for Apply or Discard. */
+  proposed_spec: VideoSpec | null
+  changes: string[]
+  outcome: '' | 'pending' | 'applied' | 'discarded'
+  /** The project version the turn was asked about. */
+  base_version: number | null
+  cost: number | null
+  created_at: string
+  updated_at: string
+}
+
+export interface ChatMessage {
+  role: 'user' | 'assistant'
+  text: string
+  turn_id: string | null
+  at: string | null
+}
+
+export interface ChatSummary {
+  id: string
+  project_id: string | null
+  title: string
+  created_at: string
+  updated_at: string
+}
+
+export interface Chat extends ChatSummary {
+  messages: ChatMessage[]
+  turns: Turn[]
+  cost: number
+}
+
+export interface TurnRequest {
+  prompt: string
+  session_id?: string | null
+  project_id?: string | null
+  draft_spec?: VideoSpec | null
+  base_version?: number | null
+  focus?: string | null
+}
+
+export const ACTIVE_TURN: TurnStatus[] = ['queued', 'processing']
+
+interface DataResponse<T> {
+  data: T
+}
+
+interface ListResponse<T> {
+  data: T[]
+  total: number
+}
+
+export const assistantApi = {
+  sessions(projectId: string | null): Promise<ChatSummary[]> {
+    return client
+      .get<ListResponse<ChatSummary>>('/assistant/sessions', {
+        params: projectId ? { project_id: projectId } : {},
+      })
+      .then((r) => r.data.data)
+  },
+
+  session(id: string): Promise<Chat> {
+    return client
+      .get<DataResponse<Chat>>(`/assistant/sessions/${id}`)
+      .then((r) => r.data.data)
+  },
+
+  removeSession(id: string): Promise<void> {
+    return client.delete(`/assistant/sessions/${id}`).then(() => undefined)
+  },
+
+  start(body: TurnRequest): Promise<Turn> {
+    return client
+      .post<DataResponse<Turn>>('/assistant/turns', body)
+      .then((r) => r.data.data)
+  },
+
+  stop(id: string): Promise<Turn> {
+    return client
+      .delete<DataResponse<Turn>>(`/assistant/turns/${id}`)
+      .then((r) => r.data.data)
+  },
+
+  applied(id: string): Promise<Turn> {
+    return client
+      .post<DataResponse<Turn>>(`/assistant/turns/${id}/applied`)
+      .then((r) => r.data.data)
+  },
+
+  discarded(id: string): Promise<Turn> {
+    return client
+      .post<DataResponse<Turn>>(`/assistant/turns/${id}/discarded`)
+      .then((r) => r.data.data)
+  },
+
+  newProject(id: string): Promise<string> {
+    return client
+      .post<DataResponse<{ project_id: string }>>(`/assistant/turns/${id}/new-project`)
+      .then((r) => r.data.data.project_id)
+  },
+
+  /** What is running, or finished with a proposal nobody has acted on yet. */
+  attention(): Promise<Turn[]> {
+    return client
+      .get<ListResponse<Turn>>('/assistant/turns', { params: { attention: true } })
+      .then((r) => r.data.data)
+  },
+}
diff --git a/frontend/src/components/AppShell.tsx b/frontend/src/components/AppShell.tsx
index 7e7d96f..002c3f6 100644
--- a/frontend/src/components/AppShell.tsx
+++ b/frontend/src/components/AppShell.tsx
@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react'
 import { LogOut, Moon, Settings, Sun } from 'lucide-react'
 import { Link } from 'react-router-dom'
+import AssistantMarker from '@/components/AssistantMarker'
+import AssistantPanel from '@/components/AssistantPanel'
 import { useAuthStore } from '@/stores/auth'
 import { useThemeStore } from '@/stores/theme'
 
@@ -29,6 +31,7 @@ export default function AppShell({ children }: Props) {
           </Link>
 
           <div className="ml-auto flex items-center gap-3">
+            {user && <AssistantMarker />}
             <Link
               to="/settings"
               className="btn btn-ghost p-2"
@@ -71,7 +74,11 @@ export default function AppShell({ children }: Props) {
         </div>
       </header>
 
-      <main className="flex-1 overflow-auto">{children}</main>
+      {/* The assistant sits beside every page, so it can follow you around the app. */}
+      <div className="flex min-h-0 flex-1">
+        <main className="min-w-0 flex-1 overflow-auto">{children}</main>
+        {user && <AssistantPanel />}
+      </div>
     </div>
   )
 }
diff --git a/frontend/src/components/AssistantMarker.tsx b/frontend/src/components/AssistantMarker.tsx
new file mode 100644
index 0000000..5c7a3d6
--- /dev/null
+++ b/frontend/src/components/AssistantMarker.tsx
@@ -0,0 +1,46 @@
+import { useEffect } from 'react'
+import { Loader2, Sparkles } from 'lucide-react'
+import { Link } from 'react-router-dom'
+import { ACTIVE_TURN } from '@/api/assistant'
+import { useAssistantStore } from '@/stores/assistant'
+
+const REFRESH_MS = 20_000
+
+/**
+ * In the header: the assistant is working, or has something waiting for you, on some
+ * video, with a link to it. Requests run on the server, so this is how one asked and
+ * left is found again from anywhere in the app.
+ */
+export default function AssistantMarker() {
+  const attention = useAssistantStore((s) => s.attention)
+  const refresh = useAssistantStore((s) => s.refreshAttention)
+
+  useEffect(() => {
+    void refresh()
+    const id = setInterval(() => void refresh(), REFRESH_MS)
+    return () => clearInterval(id)
+  }, [refresh])
+
+  if (attention.length === 0) return null
+  const working = attention.filter((t) => ACTIVE_TURN.includes(t.status))
+  const first = working[0] ?? attention[0]
+  const to = first.project_id ? `/p/${first.project_id}` : '/projects'
+  const label = working.length
+    ? `The assistant is working${working.length > 1 ? ` (${working.length})` : ''}`
+    : `${attention.length} change${attention.length > 1 ? 's' : ''} to review`
+
+  return (
+    <Link
+      to={to}
+      className="flex items-center gap-1 rounded-full bg-primary-50 px-2 py-1 text-xs text-primary-700 hover:bg-primary-100 dark:bg-primary-900/40 dark:text-primary-200"
+      title={first.prompt}
+    >
+      {working.length ? (
+        <Loader2 className="h-3 w-3 animate-spin" />
+      ) : (
+        <Sparkles className="h-3 w-3" />
+      )}
+      {label}
+    </Link>
+  )
+}
diff --git a/frontend/src/components/AssistantPanel.test.tsx b/frontend/src/components/AssistantPanel.test.tsx
new file mode 100644
index 0000000..526dd90
--- /dev/null
+++ b/frontend/src/components/AssistantPanel.test.tsx
@@ -0,0 +1,197 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MemoryRouter, Route, Routes } from 'react-router-dom'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { assistantApi, type Chat, type Turn } from '@/api/assistant'
+import type { Project, VideoSpec } from '@/api/projects'
+import AssistantPanel from '@/components/AssistantPanel'
+import { useAssistantStore } from '@/stores/assistant'
+import { useProjectStore } from '@/stores/projects'
+
+const spec: VideoSpec = {
+  title: 'Water Wars',
+  segments: [{ id: 's_valley', kind: 'scene', label: 'The valley' }],
+}
+
+const project = {
+  id: 'p1',
+  title: 'Water Wars',
+  origin: 'blank',
+  version: 3,
+  created_at: '',
+  updated_at: '',
+  spec,
+} as unknown as Project
+
+function turn(overrides: Partial<Turn> = {}): Turn {
+  return {
+    id: 't1',
+    session_id: 'c1',
+    project_id: 'p1',
+    status: 'done',
+    stage: '',
+    detail: '',
+    error: null,
+    prompt: 'dissolve into the valley',
+    steps: [{ kind: 'edit', text: 'Done: Changed The valley: transition_in.' }],
+    reply: 'Dissolve into the valley now.',
+    proposed_spec: {
+      ...spec,
+      segments: [{ ...spec.segments[0], transition_in: { style: 'dissolve' } }],
+    },
+    changes: ['Changed The valley: transition_in'],
+    outcome: 'pending',
+    base_version: 3,
+    cost: 0.0123,
+    created_at: '',
+    updated_at: '',
+    ...overrides,
+  }
+}
+
+function chat(t: Turn): Chat {
+  return {
+    id: 'c1',
+    project_id: t.project_id,
+    title: 'dissolve into the valley',
+    created_at: '',
+    updated_at: '',
+    cost: t.cost ?? 0,
+    turns: [t],
+    messages: [
+      { role: 'user', text: t.prompt, turn_id: t.id, at: null },
+      ...(t.status === 'done'
+        ? [{ role: 'assistant' as const, text: t.reply, turn_id: t.id, at: null }]
+        : []),
+    ],
+  }
+}
+
+function at(path: string) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route path="/p/:id" element={<AssistantPanel />} />
+        <Route path="/projects" element={<AssistantPanel />} />
+      </Routes>
+    </MemoryRouter>
+  )
+}
+
+beforeEach(() => {
+  localStorage.clear()
+  useAssistantStore.getState().reset()
+  useAssistantStore.setState({ open: true })
+  useProjectStore.setState({ project, draft: spec, dirty: false })
+  vi.spyOn(assistantApi, 'attention').mockResolvedValue([])
+})
+afterEach(() => vi.restoreAllMocks())
+
+describe('AssistantPanel', () => {
+  it('finds a finished proposal on the way back and applies it into the draft', async () => {
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([chat(turn())])
+    vi.spyOn(assistantApi, 'session')
+      .mockResolvedValueOnce(chat(turn()))
+      .mockResolvedValue(chat(turn({ outcome: 'applied', proposed_spec: null })))
+    const applied = vi.spyOn(assistantApi, 'applied').mockResolvedValue(turn())
+    at('/p/p1')
+
+    expect(await screen.findByText('Dissolve into the valley now.')).toBeInTheDocument()
+    expect(screen.getByText('Changed The valley: transition_in')).toBeInTheDocument()
+    // The turn and the conversation each say their cost.
+    expect(screen.getAllByText(/about \$0\.01 \(estimate\)/)).toHaveLength(2)
+
+    await userEvent.click(screen.getByRole('button', { name: 'Apply' }))
+    expect(useProjectStore.getState().draft?.segments[0].transition_in).toEqual({
+      style: 'dissolve',
+    })
+    expect(useProjectStore.getState().dirty).toBe(true)
+    expect(applied).toHaveBeenCalledWith('t1')
+    expect(await screen.findByText(/Applied/)).toBeInTheDocument()
+  })
+
+  it('warns when the project was saved after the request was made', async () => {
+    useProjectStore.setState({ project: { ...project, version: 5 } })
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([chat(turn())])
+    vi.spyOn(assistantApi, 'session').mockResolvedValue(chat(turn()))
+    at('/p/p1')
+    expect(await screen.findByText(/Based on version 3/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Apply anyway' })).toBeInTheDocument()
+  })
+
+  it('sends the draft, its version and the focused scene, and shows the live steps', async () => {
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([])
+    const running = turn({
+      status: 'processing',
+      stage: 'Working',
+      detail: 'searching the library',
+      steps: [{ kind: 'search', text: "Searching the library: 'water'" }],
+      outcome: '',
+      proposed_spec: null,
+    })
+    const start = vi.spyOn(assistantApi, 'start').mockResolvedValue(running)
+    vi.spyOn(assistantApi, 'session').mockResolvedValue(chat(running))
+    const stop = vi.spyOn(assistantApi, 'stop').mockResolvedValue(running)
+    useAssistantStore.setState({ focus: 's_valley' })
+    at('/p/p1')
+    await waitFor(() => expect(assistantApi.sessions).toHaveBeenCalledWith('p1'))
+    useAssistantStore.setState({ focus: 's_valley' })
+
+    expect(await screen.findByText(/means The valley/)).toBeInTheDocument()
+    await userEvent.type(
+      screen.getByLabelText('Ask the assistant'),
+      'dissolve into this{Enter}'
+    )
+    expect(start).toHaveBeenCalledWith({
+      prompt: 'dissolve into this',
+      draft_spec: spec,
+      base_version: 3,
+      focus: 's_valley',
+      session_id: null,
+      project_id: 'p1',
+    })
+    expect(await screen.findByText(/Working: searching the library/)).toBeInTheDocument()
+    expect(screen.getByText("Searching the library: 'water'")).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: /Stop/ }))
+    expect(stop).toHaveBeenCalledWith('t1')
+  })
+
+  it('on the project list, a draft becomes a new video', async () => {
+    const draft = turn({ project_id: null })
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([chat(draft)])
+    vi.spyOn(assistantApi, 'session').mockResolvedValue(chat(draft))
+    const made = vi.spyOn(assistantApi, 'newProject').mockResolvedValue('p9')
+    at('/projects')
+    await userEvent.click(
+      await screen.findByRole('button', { name: 'Create this video' })
+    )
+    expect(made).toHaveBeenCalledWith('t1')
+  })
+
+  it('collapses to a strip and remembers it', async () => {
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([])
+    at('/projects')
+    await userEvent.click(screen.getByRole('button', { name: 'Close the assistant' }))
+    expect(screen.getByRole('button', { name: 'Open the assistant' })).toBeInTheDocument()
+    expect(localStorage.getItem('gvc-assistant-open')).toBe('0')
+  })
+
+  it('points at Settings when no provider is set up', async () => {
+    vi.spyOn(assistantApi, 'sessions').mockResolvedValue([])
+    vi.spyOn(assistantApi, 'start').mockRejectedValue({
+      isAxiosError: true,
+      response: {
+        status: 409,
+        data: {
+          detail: {
+            code: 'no_provider',
+            message: 'Set up an AI provider in Settings first.',
+          },
+        },
+      },
+    })
+    at('/projects')
+    await userEvent.type(screen.getByLabelText('Ask the assistant'), 'a video{Enter}')
+    expect(await screen.findByRole('link', { name: 'Open Settings' })).toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/AssistantPanel.tsx b/frontend/src/components/AssistantPanel.tsx
new file mode 100644
index 0000000..527438a
--- /dev/null
+++ b/frontend/src/components/AssistantPanel.tsx
@@ -0,0 +1,513 @@
+import { Fragment, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  History,
+  Loader2,
+  MessageSquarePlus,
+  PanelRightClose,
+  PanelRightOpen,
+  Search,
+  Send,
+  Sparkles,
+  Square,
+  Trash2,
+  TriangleAlert,
+  Wrench,
+} from 'lucide-react'
+import { Link, useMatch, useNavigate } from 'react-router-dom'
+import { ACTIVE_TURN, type Turn, type TurnStep } from '@/api/assistant'
+import { formatCost } from '@/api/usage'
+import { MAX_WIDTH, MIN_WIDTH, useAssistantStore } from '@/stores/assistant'
+import { useProjectStore } from '@/stores/projects'
+
+/**
+ * The assistant, always to hand at the side of every page, as in Gecko Notes.
+ *
+ * On a project it talks about that project, starting from the editor's draft with any
+ * unsaved edits; on the project list, about a new video. What it changes comes back as
+ * a proposal to apply or discard, so it can never alter a video behind your back. A
+ * request keeps running on the server with this page closed, and is found here again
+ * on the way back, still running or still waiting.
+ */
+
+/** Paragraphs, lists, **bold**, _italic_ and `code`: what a reply uses, no more. */
+function inline(text: string): ReactNode[] {
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`|_[^_]+_)/).map((part, i) => {
+    if (part.startsWith('**') && part.endsWith('**') && part.length > 4)
+      return <strong key={i}>{part.slice(2, -2)}</strong>
+    if (part.startsWith('`') && part.endsWith('`') && part.length > 2)
+      return (
+        <code key={i} className="rounded bg-gray-100 px-1 text-[0.85em] dark:bg-gray-700">
+          {part.slice(1, -1)}
+        </code>
+      )
+    if (part.startsWith('_') && part.endsWith('_') && part.length > 2)
+      return <em key={i}>{part.slice(1, -1)}</em>
+    return <Fragment key={i}>{part}</Fragment>
+  })
+}
+
+function Prose({ text }: { text: string }) {
+  const blocks = text.split(/\n{2,}/)
+  return (
+    <div className="space-y-2">
+      {blocks.map((block, i) => {
+        const lines = block.split('\n')
+        if (lines.every((l) => /^\s*[-*] /.test(l)))
+          return (
+            <ul key={i} className="list-disc space-y-0.5 pl-4">
+              {lines.map((l, j) => (
+                <li key={j}>{inline(l.replace(/^\s*[-*] /, ''))}</li>
+              ))}
+            </ul>
+          )
+        return (
+          <p key={i} className="whitespace-pre-wrap">
+            {inline(block)}
+          </p>
+        )
+      })}
+    </div>
+  )
+}
+
+const STEP_ICON: Record<TurnStep['kind'], ReactNode> = {
+  search: <Search className="h-3 w-3" />,
+  edit: <Wrench className="h-3 w-3" />,
+  issue: <TriangleAlert className="h-3 w-3 text-amber-600" />,
+  think: <Sparkles className="h-3 w-3" />,
+  note: <Sparkles className="h-3 w-3" />,
+}
+
+function Steps({ turn, live }: { turn: Turn; live: boolean }) {
+  const [open, setOpen] = useState(live)
+  useEffect(() => setOpen(live), [live])
+  if (turn.steps.length === 0) return null
+  return (
+    <div className="text-xs text-gray-500 dark:text-gray-400">
+      <button
+        type="button"
+        className="flex items-center gap-1 hover:text-gray-700 dark:hover:text-gray-200"
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+      >
+        {open ? (
+          <ChevronDown className="h-3 w-3" />
+        ) : (
+          <ChevronRight className="h-3 w-3" />
+        )}
+        {turn.steps.length} step{turn.steps.length === 1 ? '' : 's'}
+      </button>
+      {open && (
+        <ol className="mt-1 space-y-0.5 border-l border-gray-200 pl-2 dark:border-gray-700">
+          {turn.steps.map((step, i) => (
+            <li key={i} className="flex items-start gap-1.5">
+              <span className="mt-0.5 shrink-0">{STEP_ICON[step.kind] ?? null}</span>
+              <span className="line-clamp-3">{step.text}</span>
+            </li>
+          ))}
+        </ol>
+      )}
+    </div>
+  )
+}
+
+interface ProposalProps {
+  turn: Turn
+  /** null on the project list: applying makes a new project. */
+  projectVersion: number | null
+}
+
+/** What a turn would change, and Apply / Discard. */
+function Proposal({ turn, projectVersion }: ProposalProps) {
+  const markApplied = useAssistantStore((s) => s.markApplied)
+  const discard = useAssistantStore((s) => s.discard)
+  const newProject = useAssistantStore((s) => s.newProject)
+  const edit = useProjectStore((s) => s.edit)
+  const navigate = useNavigate()
+  const [busy, setBusy] = useState(false)
+
+  if (turn.outcome === 'applied')
+    return (
+      <p className="flex items-center gap-1 text-xs text-green-700 dark:text-green-400">
+        <Check className="h-3 w-3" />
+        Applied{turn.project_id && projectVersion === null ? ' as a new video' : ''}
+      </p>
+    )
+  if (turn.outcome === 'discarded')
+    return <p className="text-xs text-gray-500">Discarded</p>
+  if (turn.outcome !== 'pending' || !turn.proposed_spec) return null
+
+  const stale =
+    projectVersion !== null &&
+    turn.base_version !== null &&
+    turn.base_version !== projectVersion
+
+  async function apply() {
+    setBusy(true)
+    if (projectVersion === null) {
+      const id = await newProject(turn.id)
+      setBusy(false)
+      if (id) navigate(`/p/${id}`)
+      return
+    }
+    // Into the editor's draft, as an unsaved edit: Save, Discard and History then work
+    // on it exactly as they do on a change made by hand.
+    edit(turn.proposed_spec!)
+    await markApplied(turn.id)
+    setBusy(false)
+  }
+
+  return (
+    <div
+      className="space-y-2 rounded border border-primary-200 bg-primary-50/50 p-2 text-xs dark:border-primary-800 dark:bg-primary-900/20"
+      aria-label="Proposed changes"
+    >
+      <ul className="list-disc space-y-0.5 pl-4 text-gray-700 dark:text-gray-300">
+        {turn.changes.map((c, i) => (
+          <li key={i}>{c}</li>
+        ))}
+      </ul>
+      {stale && (
+        <p className="text-amber-700 dark:text-amber-300">
+          Based on version {turn.base_version}; the project has been saved since (now
+          version {projectVersion}). Applying replaces the draft with this proposal.
+        </p>
+      )}
+      <div className="flex gap-2">
+        <button
+          type="button"
+          className="btn btn-primary px-2 py-1 text-xs"
+          disabled={busy}
+          onClick={() => void apply()}
+        >
+          {projectVersion === null
+            ? 'Create this video'
+            : stale
+              ? 'Apply anyway'
+              : 'Apply'}
+        </button>
+        <button
+          type="button"
+          className="btn btn-ghost px-2 py-1 text-xs"
+          disabled={busy}
+          onClick={() => void discard(turn.id)}
+        >
+          Discard
+        </button>
+      </div>
+    </div>
+  )
+}
+
+/** The chats about this video, to go back to an earlier one. */
+function ChatList({ onPicked }: { onPicked: () => void }) {
+  const sessions = useAssistantStore((s) => s.sessions)
+  const chat = useAssistantStore((s) => s.chat)
+  const openChat = useAssistantStore((s) => s.openChat)
+  const removeChat = useAssistantStore((s) => s.removeChat)
+  if (sessions.length === 0)
+    return <p className="p-3 text-xs text-gray-500">No earlier conversations.</p>
+  return (
+    <ul
+      className="divide-y divide-gray-100 dark:divide-gray-800"
+      aria-label="Conversations"
+    >
+      {sessions.map((s) => (
+        <li key={s.id} className="flex items-center gap-1 px-3 py-2 text-xs">
+          <button
+            type="button"
+            className={`min-w-0 flex-1 truncate text-left ${
+              chat?.id === s.id ? 'font-semibold' : ''
+            }`}
+            onClick={() => {
+              void openChat(s.id)
+              onPicked()
+            }}
+          >
+            {s.title}
+          </button>
+          <button
+            type="button"
+            className="btn btn-ghost p-1"
+            aria-label={`Delete conversation ${s.title}`}
+            onClick={() => void removeChat(s.id)}
+          >
+            <Trash2 className="h-3 w-3" />
+          </button>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+export default function AssistantPanel() {
+  const match = useMatch('/p/:id')
+  const scope = match?.params.id ?? null
+  const open = useAssistantStore((s) => s.open)
+  const width = useAssistantStore((s) => s.width)
+  const setOpen = useAssistantStore((s) => s.setOpen)
+  const setWidth = useAssistantStore((s) => s.setWidth)
+  const enter = useAssistantStore((s) => s.enter)
+  const chat = useAssistantStore((s) => s.chat)
+  const sending = useAssistantStore((s) => s.sending)
+  const error = useAssistantStore((s) => s.error)
+  const send = useAssistantStore((s) => s.send)
+  const stop = useAssistantStore((s) => s.stop)
+  const newChat = useAssistantStore((s) => s.newChat)
+  const focus = useAssistantStore((s) => s.focus)
+  const project = useProjectStore((s) => s.project)
+  const draft = useProjectStore((s) => s.draft)
+  const [prompt, setPrompt] = useState('')
+  const [showList, setShowList] = useState(false)
+  const bottom = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    void enter(scope)
+    setShowList(false)
+  }, [scope, enter])
+
+  const turns = useMemo(
+    () => Object.fromEntries((chat?.turns ?? []).map((t) => [t.id, t])),
+    [chat]
+  )
+  const running = chat?.turns.find((t) => ACTIVE_TURN.includes(t.status))
+  const steps = running?.steps.length ?? 0
+  const messageCount = chat?.messages.length ?? 0
+
+  useEffect(() => {
+    bottom.current?.scrollIntoView?.({ block: 'end' })
+  }, [messageCount, steps])
+
+  // The editor's project, once it has loaded the one this page is about.
+  const here = scope && project?.id === scope ? project : null
+  const focusLabel =
+    here && focus ? draft?.segments.find((s) => s.id === focus)?.label || focus : null
+
+  async function submit() {
+    const text = prompt.trim()
+    if (!text || sending || running) return
+    const ok = await send({
+      prompt: text,
+      draft_spec: here ? draft : null,
+      base_version: here ? here.version : null,
+      focus: here ? focus : null,
+    })
+    if (ok) setPrompt('')
+  }
+
+  function startResize(e: React.MouseEvent) {
+    e.preventDefault()
+    const startX = e.clientX
+    const startWidth = width
+    const move = (ev: MouseEvent) => setWidth(startWidth + (startX - ev.clientX))
+    const up = () => {
+      window.removeEventListener('mousemove', move)
+      window.removeEventListener('mouseup', up)
+    }
+    window.addEventListener('mousemove', move)
+    window.addEventListener('mouseup', up)
+  }
+
+  if (!open) {
+    return (
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="flex w-9 shrink-0 flex-col items-center gap-2 border-l border-gray-200 bg-white py-3 text-xs text-gray-600 hover:bg-gray-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300"
+        aria-label="Open the assistant"
+        title="Open the assistant"
+      >
+        <PanelRightOpen className="h-4 w-4" />
+        <span style={{ writingMode: 'vertical-rl' }}>Assistant</span>
+        {running && <Loader2 className="h-3 w-3 animate-spin" />}
+      </button>
+    )
+  }
+
+  return (
+    <aside
+      className="relative flex shrink-0 flex-col border-l border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-800"
+      style={{ width }}
+      aria-label="Assistant"
+    >
+      <div
+        role="separator"
+        aria-orientation="vertical"
+        aria-valuemin={MIN_WIDTH}
+        aria-valuemax={MAX_WIDTH}
+        aria-valuenow={width}
+        className="absolute inset-y-0 -left-1 w-2 cursor-col-resize"
+        onMouseDown={startResize}
+      />
+      <header className="flex items-center gap-1 border-b border-gray-200 px-3 py-2 dark:border-gray-700">
+        <Sparkles className="h-4 w-4 text-primary-600" />
+        <h2 className="min-w-0 flex-1 truncate text-sm font-semibold text-gray-900 dark:text-gray-100">
+          {chat?.title || (scope ? 'Assistant' : 'New video from a prompt')}
+        </h2>
+        <button
+          type="button"
+          className="btn btn-ghost p-1"
+          aria-label="Earlier conversations"
+          title="Earlier conversations"
+          onClick={() => setShowList(!showList)}
+        >
+          <History className="h-4 w-4" />
+        </button>
+        <button
+          type="button"
+          className="btn btn-ghost p-1"
+          aria-label="New conversation"
+          title="New conversation"
+          onClick={() => {
+            newChat()
+            setShowList(false)
+          }}
+        >
+          <MessageSquarePlus className="h-4 w-4" />
+        </button>
+        <button
+          type="button"
+          className="btn btn-ghost p-1"
+          aria-label="Close the assistant"
+          onClick={() => setOpen(false)}
+        >
+          <PanelRightClose className="h-4 w-4" />
+        </button>
+      </header>
+
+      {showList ? (
+        <div className="flex-1 overflow-auto">
+          <ChatList onPicked={() => setShowList(false)} />
+        </div>
+      ) : (
+        <div className="flex-1 space-y-3 overflow-auto p-3 text-sm text-gray-800 dark:text-gray-200">
+          {!chat && (
+            <div className="space-y-2 text-xs text-gray-600 dark:text-gray-400">
+              {scope ? (
+                <p>
+                  Ask for any change to this video: &ldquo;dissolve into the last
+                  scene&rdquo;, &ldquo;find footage of people talking about water for
+                  scene 3&rdquo;, &ldquo;change the music after chapter 2 to something
+                  calmer&rdquo;. You see what it would change before anything does.
+                </p>
+              ) : (
+                <p>
+                  Describe a video and the assistant drafts it from your library: &ldquo;A
+                  3-minute video about the Colorado River water wars, using clips where
+                  people talk about it.&rdquo; You review the draft before it becomes a
+                  project.
+                </p>
+              )}
+              <p>It keeps working if you close this page.</p>
+            </div>
+          )}
+          {chat?.messages.map((m, i) => {
+            const turn = m.turn_id ? turns[m.turn_id] : undefined
+            if (m.role === 'user') {
+              const live = turn && ACTIVE_TURN.includes(turn.status)
+              return (
+                <div key={i} className="space-y-1">
+                  <div className="ml-6 rounded-lg bg-primary-600 px-3 py-2 text-white">
+                    <p className="whitespace-pre-wrap">{m.text}</p>
+                  </div>
+                  {live && turn && (
+                    <div className="space-y-1 rounded border border-gray-200 p-2 dark:border-gray-700">
+                      <p className="flex items-center gap-2 text-xs text-gray-600 dark:text-gray-300">
+                        <Loader2 className="h-3 w-3 animate-spin" />
+                        <span className="flex-1">
+                          {turn.status === 'queued'
+                            ? 'Waiting to start…'
+                            : `${turn.stage || 'Working'}${turn.detail ? `: ${turn.detail}` : ''}`}
+                        </span>
+                        <button
+                          type="button"
+                          className="btn btn-ghost px-1 py-0.5 text-xs"
+                          onClick={() => void stop(turn.id)}
+                        >
+                          <Square className="mr-1 inline h-3 w-3" />
+                          Stop
+                        </button>
+                      </p>
+                      <Steps turn={turn} live />
+                    </div>
+                  )}
+                </div>
+              )
+            }
+            return (
+              <div key={i} className="space-y-1.5">
+                <Prose text={m.text} />
+                {turn && <Steps turn={turn} live={false} />}
+                {turn && (
+                  <Proposal
+                    turn={turn}
+                    projectVersion={scope ? (here?.version ?? null) : null}
+                  />
+                )}
+                {turn?.cost != null && turn.cost > 0 && (
+                  <p className="text-[11px] text-gray-400">
+                    about {formatCost(turn.cost)} (estimate)
+                  </p>
+                )}
+              </div>
+            )
+          })}
+          {error && (
+            <p role="alert" className="text-xs text-red-600 dark:text-red-400">
+              {error}
+              {/Settings/.test(error) && (
+                <>
+                  {' '}
+                  <Link to="/settings" className="underline">
+                    Open Settings
+                  </Link>
+                </>
+              )}
+            </p>
+          )}
+          <div ref={bottom} />
+        </div>
+      )}
+
+      <footer className="space-y-1 border-t border-gray-200 p-2 dark:border-gray-700">
+        {focusLabel && (
+          <p className="truncate text-[11px] text-gray-500">
+            &ldquo;This scene&rdquo; means {focusLabel}
+          </p>
+        )}
+        <div className="flex items-end gap-2">
+          <textarea
+            className="input max-h-40 min-h-[2.5rem] flex-1 resize-y text-sm"
+            aria-label="Ask the assistant"
+            placeholder={scope ? 'Ask for a change…' : 'Describe a video…'}
+            value={prompt}
+            onChange={(e) => setPrompt(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' && !e.shiftKey) {
+                e.preventDefault()
+                void submit()
+              }
+            }}
+          />
+          <button
+            type="button"
+            className="btn btn-primary p-2"
+            aria-label="Send"
+            disabled={!prompt.trim() || sending || !!running || (!!scope && !here)}
+            onClick={() => void submit()}
+          >
+            <Send className="h-4 w-4" />
+          </button>
+        </div>
+        {chat && chat.cost > 0 && (
+          <p className="text-[11px] text-gray-400">
+            This conversation: about {formatCost(chat.cost)} (estimate)
+          </p>
+        )}
+      </footer>
+    </aside>
+  )
+}
diff --git a/frontend/src/components/ProviderPanel.tsx b/frontend/src/components/ProviderPanel.tsx
index c287392..63d4087 100644
--- a/frontend/src/components/ProviderPanel.tsx
+++ b/frontend/src/components/ProviderPanel.tsx
@@ -368,9 +368,6 @@ export default function ProviderPanel() {
           </div>
 
           <div>
-            {/* "Provider type", not "Provider": the embedding panel on the same page
-                already has a field labelled that, and two identical labels are
-                ambiguous to anyone navigating the page by label. */}
             <label className="label" htmlFor="provider-type">
               Provider type
             </label>
diff --git a/frontend/src/components/SceneList.tsx b/frontend/src/components/SceneList.tsx
index 6c3a55c..070c73b 100644
--- a/frontend/src/components/SceneList.tsx
+++ b/frontend/src/components/SceneList.tsx
@@ -12,6 +12,7 @@ import {
   updateSegment,
   withNarrationText,
 } from '@/spec/edits'
+import { useAssistantStore } from '@/stores/assistant'
 
 interface Props {
   spec: VideoSpec
@@ -43,6 +44,7 @@ export default function SceneList({
   onFindFootage,
 }: Props) {
   const segments = spec.segments
+  const setFocus = useAssistantStore((s) => s.setFocus)
   const edit = (index: number, change: (s: Segment) => Segment) =>
     onChange(updateSegment(spec, index, change))
 
@@ -51,8 +53,11 @@ export default function SceneList({
       {segments.map((segment, index) => (
         <section
           key={segment.id}
+          id={`scene-${segment.id}`}
           aria-label={segment.label || segment.id}
           className="card space-y-2 p-3"
+          // The scene being worked on is what "this scene" means to the assistant.
+          onFocusCapture={() => setFocus(segment.id)}
         >
           <div className="flex items-center gap-2">
             <span className="w-6 text-right text-xs text-gray-400">{index + 1}</span>
diff --git a/frontend/src/stores/assistant.ts b/frontend/src/stores/assistant.ts
new file mode 100644
index 0000000..7f0777d
--- /dev/null
+++ b/frontend/src/stores/assistant.ts
@@ -0,0 +1,288 @@
+import { create } from 'zustand'
+import { apiErrorMessage } from '@/api/client'
+import {
+  ACTIVE_TURN,
+  assistantApi,
+  type Chat,
+  type ChatSummary,
+  type Turn,
+  type TurnRequest,
+} from '@/api/assistant'
+
+/**
+ * The assistant panel's state: which video it is about (`scope`), its conversations,
+ * and the one open.
+ *
+ * A turn runs on the server, so this only follows it. While the open conversation has
+ * a turn running, the conversation is re-read every second and a half; the poll is one
+ * timer re-armed after each answer, and every answer is checked against a token so a
+ * conversation left mid-turn can't have its steps land on the next one.
+ */
+
+const POLL_MS = 1500
+const OPEN_KEY = 'gvc-assistant-open'
+const WIDTH_KEY = 'gvc-assistant-width'
+export const MIN_WIDTH = 280
+export const MAX_WIDTH = 640
+
+function stored<T>(key: string, fallback: T, parse: (raw: string) => T): T {
+  try {
+    const raw = localStorage.getItem(key)
+    return raw === null ? fallback : parse(raw)
+  } catch {
+    return fallback
+  }
+}
+
+function keep(key: string, value: string) {
+  try {
+    localStorage.setItem(key, value)
+  } catch {
+    /* a private window: the panel just forgets */
+  }
+}
+
+interface AssistantState {
+  open: boolean
+  width: number
+  /** The project the panel is about; null on the project list (a new video). */
+  scope: string | null
+  sessions: ChatSummary[]
+  chat: Chat | null
+  sending: boolean
+  error: string | null
+  /** Turns running, or waiting for Apply, anywhere: the header's marker. */
+  attention: Turn[]
+  /** The scene last worked on in the editor: "this scene". */
+  focus: string | null
+
+  setOpen: (open: boolean) => void
+  setWidth: (width: number) => void
+  setFocus: (segmentId: string | null) => void
+  enter: (scope: string | null) => Promise<void>
+  openChat: (id: string) => Promise<void>
+  newChat: () => void
+  send: (request: Omit<TurnRequest, 'session_id' | 'project_id'>) => Promise<boolean>
+  stop: (turnId: string) => Promise<void>
+  markApplied: (turnId: string) => Promise<void>
+  discard: (turnId: string) => Promise<void>
+  newProject: (turnId: string) => Promise<string | null>
+  refreshAttention: () => Promise<void>
+  removeChat: (id: string) => Promise<void>
+  reset: () => void
+}
+
+let token = 0
+let timer: ReturnType<typeof setTimeout> | null = null
+
+function stopPolling() {
+  if (timer) clearTimeout(timer)
+  timer = null
+}
+
+export const useAssistantStore = create<AssistantState>((set, get) => {
+  function running(chat: Chat | null): Turn | undefined {
+    return chat?.turns.find((t) => ACTIVE_TURN.includes(t.status))
+  }
+
+  function poll(mine: number) {
+    stopPolling()
+    const chat = get().chat
+    if (!chat || !running(chat)) return
+    timer = setTimeout(async () => {
+      try {
+        const fresh = await assistantApi.session(chat.id)
+        if (mine !== token) return
+        set({ chat: fresh })
+        if (!running(fresh)) {
+          void get().refreshAttention()
+          return
+        }
+      } catch (error) {
+        if (mine !== token) return
+        set({ error: apiErrorMessage(error) })
+      }
+      poll(mine)
+    }, POLL_MS)
+  }
+
+  async function reload(mine: number, id: string) {
+    const fresh = await assistantApi.session(id)
+    if (mine !== token) return
+    set({ chat: fresh })
+    poll(mine)
+  }
+
+  return {
+    open: stored(OPEN_KEY, true, (raw) => raw === '1'),
+    width: stored(WIDTH_KEY, 360, (raw) =>
+      Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Number(raw) || 360))
+    ),
+    scope: null,
+    sessions: [],
+    chat: null,
+    sending: false,
+    error: null,
+    attention: [],
+    focus: null,
+
+    setOpen(open) {
+      keep(OPEN_KEY, open ? '1' : '0')
+      set({ open })
+    },
+
+    setWidth(width) {
+      const clamped = Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.round(width)))
+      keep(WIDTH_KEY, String(clamped))
+      set({ width: clamped })
+    },
+
+    setFocus(focus) {
+      set({ focus })
+    },
+
+    async enter(scope) {
+      const mine = ++token
+      stopPolling()
+      set({ scope, sessions: [], chat: null, error: null, focus: null })
+      try {
+        const sessions = await assistantApi.sessions(scope)
+        if (mine !== token) return
+        set({ sessions })
+        // The latest conversation, so coming back to a video finds where it was left,
+        // a turn still running or a proposal still waiting.
+        if (sessions[0]) await reload(mine, sessions[0].id)
+      } catch (error) {
+        if (mine !== token) return
+        set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async openChat(id) {
+      const mine = ++token
+      stopPolling()
+      set({ error: null })
+      try {
+        await reload(mine, id)
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    newChat() {
+      token += 1
+      stopPolling()
+      set({ chat: null, error: null })
+    },
+
+    async send(request) {
+      const mine = token
+      const { chat, scope } = get()
+      set({ sending: true, error: null })
+      try {
+        const turn = await assistantApi.start({
+          ...request,
+          session_id: chat?.id ?? null,
+          project_id: scope,
+        })
+        if (mine !== token) return false
+        await reload(mine, turn.session_id)
+        if (mine !== token) return false
+        const sessions = await assistantApi.sessions(scope)
+        if (mine !== token) return false
+        set({ sessions, sending: false })
+        void get().refreshAttention()
+        return true
+      } catch (error) {
+        if (mine !== token) return false
+        set({ sending: false, error: apiErrorMessage(error) })
+        return false
+      }
+    },
+
+    async stop(turnId) {
+      const mine = token
+      try {
+        await assistantApi.stop(turnId)
+        const chat = get().chat
+        if (mine === token && chat) await reload(mine, chat.id)
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async markApplied(turnId) {
+      const mine = token
+      try {
+        await assistantApi.applied(turnId)
+        const chat = get().chat
+        if (mine === token && chat) await reload(mine, chat.id)
+        void get().refreshAttention()
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async discard(turnId) {
+      const mine = token
+      try {
+        await assistantApi.discarded(turnId)
+        const chat = get().chat
+        if (mine === token && chat) await reload(mine, chat.id)
+        void get().refreshAttention()
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async newProject(turnId) {
+      const mine = token
+      try {
+        const projectId = await assistantApi.newProject(turnId)
+        void get().refreshAttention()
+        return mine === token ? projectId : null
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+        return null
+      }
+    },
+
+    async refreshAttention() {
+      try {
+        set({ attention: await assistantApi.attention() })
+      } catch {
+        /* the marker is a nicety; the panel says what is wrong */
+      }
+    },
+
+    async removeChat(id) {
+      const mine = token
+      try {
+        await assistantApi.removeSession(id)
+        if (mine !== token) return
+        const wasOpen = get().chat?.id === id
+        set({
+          sessions: get().sessions.filter((s) => s.id !== id),
+          ...(wasOpen ? { chat: null } : {}),
+        })
+        if (wasOpen) stopPolling()
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    reset() {
+      token += 1
+      stopPolling()
+      set({
+        scope: null,
+        sessions: [],
+        chat: null,
+        sending: false,
+        error: null,
+        attention: [],
+        focus: null,
+      })
+    },
+  }
+})
diff --git a/frontend/src/stores/auth.ts b/frontend/src/stores/auth.ts
index b28ad6d..15e2c99 100644
--- a/frontend/src/stores/auth.ts
+++ b/frontend/src/stores/auth.ts
@@ -3,6 +3,7 @@ import { authApi, redirectToLogin, type User } from '@/api/auth'
 import { apiErrorCode, apiErrorMessage, clearToken } from '@/api/client'
 import { useProjectStore } from '@/stores/projects'
 import { useRenderStore } from '@/stores/renders'
+import { useAssistantStore } from '@/stores/assistant'
 
 /**
  * Who is signed in.
@@ -70,6 +71,7 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     useProjectStore.getState().reset()
     // Also stops the poll, which would otherwise keep asking as the old user.
     useRenderStore.getState().reset()
+    useAssistantStore.getState().reset()
     void redirectToLogin()
   },
 
diff --git a/frontend/tsconfig.node.tsbuildinfo b/frontend/tsconfig.node.tsbuildinfo
new file mode 100644
index 0000000..ef5ec4f
--- /dev/null
+++ b/frontend/tsconfig.node.tsbuildinfo
@@ -0,0 +1 @@
+{"fileNames":["./node_modules/typescript/lib/lib.d.ts","./node_modules/typescript/lib/lib.es5.d.ts","./node_modules/typescript/lib/lib.dom.d.ts","./node_modules/typescript/lib/lib.webworker.importscripts.d.ts","./node_modules/typescript/lib/lib.scripthost.d.ts","./node_modules/typescript/lib/lib.decorators.d.ts","./node_modules/typescript/lib/lib.decorators.legacy.d.ts","./node_modules/@vitest/pretty-format/dist/index.d.ts","./node_modules/@vitest/utils/dist/types.d.ts","./node_modules/@vitest/utils/dist/helpers.d.ts","./node_modules/tinyrainbow/dist/index-c1cfc5e9.d.ts","./node_modules/tinyrainbow/dist/node.d.ts","./node_modules/@vitest/utils/dist/index.d.ts","./node_modules/@vitest/runner/dist/tasks-3ZnPj1LR.d.ts","./node_modules/@vitest/utils/dist/types-Bxe-2Udy.d.ts","./node_modules/@vitest/utils/dist/diff.d.ts","./node_modules/@vitest/runner/dist/types.d.ts","./node_modules/@vitest/utils/dist/error.d.ts","./node_modules/@vitest/runner/dist/index.d.ts","./node_modules/vitest/dist/chunks/environment.LoooBwUu.d.ts","./node_modules/@types/estree/index.d.ts","./node_modules/rollup/dist/rollup.d.ts","./node_modules/rollup/dist/parseAst.d.ts","./node_modules/vitest/node_modules/vite/types/hmrPayload.d.ts","./node_modules/vitest/node_modules/vite/types/customEvent.d.ts","./node_modules/vitest/node_modules/vite/types/hot.d.ts","./node_modules/vitest/node_modules/vite/dist/node/types.d-aGj9QkWt.d.ts","./node_modules/vitest/node_modules/esbuild/lib/main.d.ts","./node_modules/source-map-js/source-map.d.ts","./node_modules/postcss/lib/previous-map.d.ts","./node_modules/postcss/lib/input.d.ts","./node_modules/postcss/lib/css-syntax-error.d.ts","./node_modules/postcss/lib/declaration.d.ts","./node_modules/postcss/lib/root.d.ts","./node_modules/postcss/lib/warning.d.ts","./node_modules/postcss/lib/lazy-result.d.ts","./node_modules/postcss/lib/no-work-result.d.ts","./node_modules/postcss/lib/processor.d.ts","./node_modules/postcss/lib/result.d.ts","./node_modules/postcss/lib/document.d.ts","./node_modules/postcss/lib/rule.d.ts","./node_modules/postcss/lib/node.d.ts","./node_modules/postcss/lib/comment.d.ts","./node_modules/postcss/lib/container.d.ts","./node_modules/postcss/lib/at-rule.d.ts","./node_modules/postcss/lib/list.d.ts","./node_modules/postcss/lib/postcss.d.ts","./node_modules/postcss/lib/postcss.d.mts","./node_modules/vitest/node_modules/vite/dist/node/runtime.d.ts","./node_modules/vitest/node_modules/vite/types/importGlob.d.ts","./node_modules/vitest/node_modules/vite/types/metadata.d.ts","./node_modules/vitest/node_modules/vite/dist/node/index.d.ts","./node_modules/@vitest/snapshot/dist/environment-Ddx0EDtY.d.ts","./node_modules/@vitest/snapshot/dist/rawSnapshot-CPNkto81.d.ts","./node_modules/@vitest/snapshot/dist/index.d.ts","./node_modules/@vitest/snapshot/dist/environment.d.ts","./node_modules/vitest/dist/chunks/config.Cy0C388Z.d.ts","./node_modules/vite-node/dist/trace-mapping.d-DLVdEqOp.d.ts","./node_modules/vite-node/dist/index-z0R8hVRu.d.ts","./node_modules/vite-node/dist/index.d.ts","./node_modules/@vitest/utils/dist/source-map.d.ts","./node_modules/vite-node/dist/client.d.ts","./node_modules/vite-node/node_modules/vite/dist/node/index.d.ts","./node_modules/vite-node/dist/server.d.ts","./node_modules/@vitest/runner/dist/utils.d.ts","./node_modules/tinybench/dist/index.d.ts","./node_modules/vitest/dist/chunks/benchmark.geERunq4.d.ts","./node_modules/@vitest/snapshot/dist/manager.d.ts","./node_modules/vitest/dist/chunks/reporters.nr4dxCkA.d.ts","./node_modules/vitest/dist/chunks/worker.tN5KGIih.d.ts","./node_modules/vitest/dist/chunks/worker.B9FxPCaC.d.ts","./node_modules/vitest/dist/chunks/vite.CzKp4x9w.d.ts","./node_modules/@vitest/expect/dist/chai.d.cts","./node_modules/@vitest/expect/dist/index.d.ts","./node_modules/@vitest/expect/index.d.ts","./node_modules/@vitest/spy/dist/index.d.ts","./node_modules/vitest/node_modules/@vitest/mocker/dist/types-DZOqTgiN.d.ts","./node_modules/vitest/node_modules/@vitest/mocker/dist/index.d.ts","./node_modules/vitest/dist/chunks/mocker.cRtM890J.d.ts","./node_modules/vitest/dist/chunks/suite.B2jumIFP.d.ts","./node_modules/expect-type/dist/utils.d.ts","./node_modules/expect-type/dist/overloads.d.ts","./node_modules/expect-type/dist/branding.d.ts","./node_modules/expect-type/dist/messages.d.ts","./node_modules/expect-type/dist/index.d.ts","./node_modules/vitest/dist/index.d.ts","./node_modules/vite/types/hmrPayload.d.ts","./node_modules/vite/types/customEvent.d.ts","./node_modules/vite/types/hot.d.ts","./node_modules/vite/dist/node/moduleRunnerTransport.d-DJ_mE5sf.d.ts","./node_modules/vite/dist/node/module-runner.d.ts","./node_modules/esbuild/lib/main.d.ts","./node_modules/vite/types/internal/lightningcssOptions.d.ts","./node_modules/vite/types/internal/cssPreprocessorOptions.d.ts","./node_modules/vite/types/importGlob.d.ts","./node_modules/vite/types/metadata.d.ts","./node_modules/vite/dist/node/index.d.ts","./node_modules/@babel/types/lib/index.d.ts","./node_modules/@types/babel__generator/index.d.ts","./node_modules/@babel/parser/typings/babel-parser.d.ts","./node_modules/@types/babel__template/index.d.ts","./node_modules/@types/babel__traverse/index.d.ts","./node_modules/@types/babel__core/index.d.ts","./node_modules/@vitejs/plugin-react/dist/index.d.ts","./vite.config.ts","./node_modules/@types/aria-query/index.d.ts","./node_modules/@types/prop-types/index.d.ts","./node_modules/@types/react/global.d.ts","./node_modules/csstype/index.d.ts","./node_modules/@types/react/index.d.ts","./node_modules/@types/react-dom/index.d.ts"],"fileIdsList":[[98],[98,99,100,101,102],[98,100],[110],[107,108,109],[97,103],[12,13,16],[74],[13,14,16,17,18],[13],[13,14,16],[13,14],[53],[8,53,54],[8,53],[8,15],[9],[8,9,10,12],[8],[81,82],[81,82,83,84],[81,83],[81],[44],[42,44],[33,41,42,43,45,47],[31],[34,39,44,47],[30,47],[34,35,38,39,40,47],[34,35,36,38,39,47],[31,32,33,34,35,39,40,41,43,44,45,47],[47],[29,31,32,33,34,35,36,38,39,40,41,42,43,44,45,46],[29,47],[34,36,37,39,40,47],[38,47],[39,40,44,47],[32,42],[22,51,96,97],[21,22],[11],[58,59],[58],[52,58,59,72],[22,23,24,25,26,27,28,48,49,50,51,96,97],[22,23,48,51,87,88,90,91,92,93,94,95,96,97],[87,88,89,90],[87],[88],[22,51,97],[19,65,66,86],[8,19,55,56,86],[78],[8,13,19,20,52,55,57,60,61,62,64,67,68,72,73,86],[19,65,66,67,86],[52,69],[70],[19,20,55,57,60,86],[8,13,16,19,20,52,55,56,57,60,61,62,64,65,66,67,68,69,70,71,72,73,75,76,78,79,80,85,86],[77],[24,25,26,27],[24,25,26],[24],[25],[22,96,97],[86,97,104]],"fileInfos":[{"version":"a7297ff837fcdf174a9524925966429eb8e5feecc2cc55cc06574e6b092c1eaa","impliedFormat":1},{"version":"c430d44666289dae81f30fa7b2edebf186ecc91a2d4c71266ea6ae76388792e1","affectsGlobalScope":true,"impliedFormat":1},{"version":"080941d9f9ff9307f7e27a83bcd888b7c8270716c39af943532438932ec1d0b9","affectsGlobalScope":true,"impliedFormat":1},{"version":"80e18897e5884b6723488d4f5652167e7bb5024f946743134ecc4aa4ee731f89","affectsGlobalScope":true,"impliedFormat":1},{"version":"cd034f499c6cdca722b60c04b5b1b78e058487a7085a8e0d6fb50809947ee573","affectsGlobalScope":true,"impliedFormat":1},{"version":"8e7f8264d0fb4c5339605a15daadb037bf238c10b654bb3eee14208f860a32ea","affectsGlobalScope":true,"impliedFormat":1},{"version":"782dec38049b92d4e85c1585fbea5474a219c6984a35b004963b00beb1aab538","affectsGlobalScope":true,"impliedFormat":1},{"version":"d2e64a6f25013b099e83bfadb2c388d7bef3e8f3fdb25528225bbc841e7e7e3a","impliedFormat":99},{"version":"369ba5259e66ca8c7d35e3234f7a2a0863a770fdb8266505747c65cf346a0804","impliedFormat":99},{"version":"64d984f55025daf604f670b7dfd090ea765f2098aee871174ef2ee3e94479098","impliedFormat":99},{"version":"f147b6710441cf3ec3234adf63b0593ce5e8c9b692959d21d3babc8454bcf743","impliedFormat":99},{"version":"e96d5373a66c2cfbbc7e6642cf274055aa2c7ff6bd37be7480c66faf9804db6d","impliedFormat":99},{"version":"02bcdd7a76c5c1c485cbf05626d24c86ac8f9a1d8dc31f8924108bbaa4cf3ba9","impliedFormat":99},{"version":"c874ab6feac6e0fdf9142727c9a876065777a5392f14b0bbcf869b1e69eb46b5","impliedFormat":99},{"version":"7c553fc9e34773ddbaabe0fa1367d4b109101d0868a008f11042bee24b5a925d","impliedFormat":99},{"version":"9962ce696fbdce2421d883ca4b062a54f982496625437ae4d3633376c5ad4a80","impliedFormat":99},{"version":"e3ea467c4a7f743f3548c9ed61300591965b1d12c08c8bb9aaff8a002ba95fce","impliedFormat":99},{"version":"4c17183a07a63bea2653fbfc0a942b027160ddbee823024789a415f9589de327","impliedFormat":99},{"version":"3e2203c892297ea44b87470fde51b3d48cfe3eeb6901995de429539462894464","impliedFormat":99},{"version":"c84bf7a4abc5e7fdf45971a71b25b0e0d34ccd5e720a866dd78bb71d60d41a3f","impliedFormat":99},{"version":"751764bb94219b4ce8f5475dc35d3de2e432fea01a0c9610cd7f69ad05e398c6","impliedFormat":1},{"version":"1687ffc301558b6088bb048945a81c0cc5318b889e2bc8b4eee26f66b0e56685","affectsGlobalScope":true,"impliedFormat":1},{"version":"a660aa95476042d3fdcc1343cf6bb8fdf24772d31712b1db321c5a4dcc325434","impliedFormat":1},{"version":"282f98006ed7fa9bb2cd9bdbe2524595cfc4bcd58a0bb3232e4519f2138df811","impliedFormat":1},{"version":"6222e987b58abfe92597e1273ad7233626285bc2d78409d4a7b113d81a83496b","impliedFormat":1},{"version":"cbe726263ae9a7bf32352380f7e8ab66ee25b3457137e316929269c19e18a2be","impliedFormat":1},{"version":"8b96046bf5fb0a815cba6b0880d9f97b7f3a93cf187e8dcfe8e2792e97f38f87","impliedFormat":99},{"version":"bacf2c84cf448b2cd02c717ad46c3d7fd530e0c91282888c923ad64810a4d511","affectsGlobalScope":true,"impliedFormat":1},{"version":"402e5c534fb2b85fa771170595db3ac0dd532112c8fa44fc23f233bc6967488b","impliedFormat":1},{"version":"52dcc257df5119fb66d864625112ce5033ac51a4c2afe376a0b299d2f7f76e4a","impliedFormat":1},{"version":"e5bab5f871ef708d52d47b3e5d0aa72a08ee7a152f33931d9a60809711a2a9a3","impliedFormat":1},{"version":"e16dc2a81595736024a206c7d5c8a39bfe2e6039208ef29981d0d95434ba8fcf","impliedFormat":1},{"version":"38cb107048cd8ba54a70014ef9a30cf57bee0d9f10a0ca4cefa974056e1ee460","impliedFormat":1},{"version":"19ee8416e6473ed6c7adb868fa796b5653cf0fa2a337658e677eaa0d134388c3","impliedFormat":1},{"version":"1328ab4e442614b28cdb3d4b414cf68325c0da0dca07287a338d0654b7a00261","impliedFormat":1},{"version":"a039dc21f045919f3cbee2ec13812cc6cc3eebc99dae4be00973230f468d19a6","impliedFormat":1},{"version":"3fbe57af01460e49dcd29df55d6931e1672bc6f1be0fb073d11410bc16f9037d","impliedFormat":1},{"version":"f760be449e8562ec5c09bb5187e8e1eabf3c113c0c58cddda53ef8c69f3e2131","impliedFormat":1},{"version":"44325ed13294fce6ab825b82947bbeed2611db7dad9d9135260192f375e5a189","impliedFormat":1},{"version":"e392e8fb5b514eafc585601c1d781485aa6dd6a320e75daf1064a4c6918a1b45","impliedFormat":1},{"version":"46e4a36e8ddbdfb4e7330e11c81c970dc8b218611df9183d39c41c5f8c653b55","impliedFormat":1},{"version":"3cc8a3d123b6b232d48d34b51b785f9da8d193f5b5817fa521fcd2f3b9315c55","impliedFormat":1},{"version":"6332f565867cf4a740a70e30f31cefba37ef7cebcf74f22eab8d744fde6d193e","impliedFormat":1},{"version":"9a195d8476f48523446ece812e5450b5b1ec8c3b6abf99efb8ee2479524f6f56","impliedFormat":1},{"version":"17f2922d41ddd032830a91371c948cd9ce903b35c95adca72271a54584f19b0b","impliedFormat":1},{"version":"3eed76ede2a1a14d7c9bb0a642041282dcc264811139d3dd275c9fe14efc9840","impliedFormat":1},{"version":"354a7f8e1287d9d6b7561bc97fdd8cbc2f7c1dd79e4cb37b942e8a5cfaff1085","impliedFormat":1},{"version":"8d369483f0c2b9ee388129cfdb6a43bc8112b377e86a41884bd06e19ce04f4c1","impliedFormat":99},{"version":"82e687ebd99518bc63ea04b0c3810fb6e50aa6942decd0ca6f7a56d9b9a212a6","impliedFormat":99},{"version":"7f698624bbbb060ece7c0e51b7236520ebada74b747d7523c7df376453ed6fea","impliedFormat":1},{"version":"8f07f2b6514744ac96e51d7cb8518c0f4de319471237ea10cf688b8d0e9d0225","impliedFormat":1},{"version":"257b83faa134d971c738a6b9e4c47e59bb7b23274719d92197580dd662bfafc3","impliedFormat":99},{"version":"e01ea380015ed698c3c0e2ccd0db72f3fc3ef1abc4519f122aa1c1a8d419a505","impliedFormat":99},{"version":"5ada1f8a9580c0f7478fe03ae3e07e958f0b79bdfb9dd50eeb98c1324f40011b","impliedFormat":99},{"version":"a8301dc90b4bd9fba333226ee0f1681aeeff1bd90233a8f647e687cb4b7d3521","impliedFormat":99},{"version":"e3225dc0bec183183509d290f641786245e6652bc3dce755f7ef404060693c35","impliedFormat":99},{"version":"09a03870ed8c55d7453bc9ad684df88965f2f770f987481ca71b8a09be5205bc","impliedFormat":99},{"version":"e6233e1c976265e85aa8ad76c3881febe6264cb06ae3136f0257e1eab4a6cc5a","impliedFormat":99},{"version":"2cdd50ddc49e2d608ee848fc4ab0db9a2716624fabb4209c7c683d87e54d79c5","impliedFormat":99},{"version":"e431d664338b8470abb1750d699c7dfcebb1a25434559ef85bb96f1e82de5972","impliedFormat":99},{"version":"2c4254139d037c3caca66ce291c1308c1b5092cfcb151eb25980db932dd3b01a","impliedFormat":99},{"version":"970ae00ed018cb96352dc3f37355ef9c2d9f8aa94d7174ccd6d0ed855e462097","impliedFormat":99},{"version":"257b83faa134d971c738a6b9e4c47e59bb7b23274719d92197580dd662bfafc3","impliedFormat":99},{"version":"d2f8dee457ef7660b604226d471d55d927c3051766bdd80353553837492635c3","impliedFormat":99},{"version":"110a503289a2ef76141ffff3ffceb9a1c3662c32748eb9f6777a2bd0866d6fb1","impliedFormat":99},{"version":"69bf2422313487956e4dacf049f30cb91b34968912058d244cb19e4baa24da97","impliedFormat":99},{"version":"310e6b62c493ce991624169a1c1904015769d947be88dc67e00adc7ebebcfa87","impliedFormat":99},{"version":"62fefda288160bf6e435b21cc03d3fbac11193d8d3bd0e82d86623cca7691c29","impliedFormat":99},{"version":"fcc46a8bcbf9bef21023bba1995160a25f0bc590ca3563ec44c315b4f4c1b18a","impliedFormat":99},{"version":"0309a01650023994ed96edbd675ea4fdc3779a823ce716ad876cc77afb792b62","impliedFormat":99},{"version":"f13d7beeea58e219daef3a40e0dc4f2bd7d9581ac04cedec236102a12dfd2090","impliedFormat":99},{"version":"669573548930fb7d0a0761b827e203dc623581e21febf0be80fb02414f217d74","impliedFormat":99},{"version":"48c411efce1848d1ed55de41d7deb93cbf7c04080912fd87aa517ed25ef42639","affectsGlobalScope":true,"impliedFormat":1},{"version":"a094636c05f3e75cb072684dd42cd25a4c1324bec4a866706c85c04cecd49613","affectsGlobalScope":true,"impliedFormat":99},{"version":"fe2d63fcfdde197391b6b70daf7be8c02a60afa90754a5f4a04bdc367f62793d","impliedFormat":99},{"version":"9a3e2c85ec1ab7a0874a19814cc73c691b716282cb727914093089c5a8475955","impliedFormat":99},{"version":"cbdc781d2429935c9c42acd680f2a53a9f633e8de03290ec6ea818e4f7bff19a","impliedFormat":99},{"version":"9f6d9f5dd710922f82f69abf9a324e28122b5f31ae6f6ce78427716db30a377e","impliedFormat":99},{"version":"ac2414a284bdecfd6ab7b87578744ab056cd04dd574b17853cd76830ef5b72f2","impliedFormat":99},{"version":"c3f921bbc9d2e65bd503a56fbc66da910e68467baedb0b9db0cc939e1876c0d7","impliedFormat":99},{"version":"dd51e53752b310bd20c9b1a87bbf12b1fe2be7fe40f505b43199496481096275","impliedFormat":1},{"version":"a87be4662442b3feeffc331ecafe6b36cafd08727e2d7f2425a5099577e7fd18","impliedFormat":1},{"version":"cd4cd9220a1ba793bc935e76d8e5481c110a90d9868ae7866a182ee71cdb6abb","impliedFormat":1},{"version":"0a7fb8619b10bc05fd933ca9ac1c8b2ab2220be7a57b57565c3ac158595494ef","impliedFormat":1},{"version":"c4a5f91feb9c5a6b2a91089d959c38391b79a961db3b9cc73b8877d57ad7dcdc","impliedFormat":1},{"version":"0cc99fbb161d78729d71fad66c6c363e3095862d6277160f29fa960744b785c6","affectsGlobalScope":true,"impliedFormat":99},{"version":"a7ca8df4f2931bef2aa4118078584d84a0b16539598eaadf7dce9104dfaa381c","impliedFormat":1},{"version":"11443a1dcfaaa404c68d53368b5b818712b95dd19f188cab1669c39bee8b84b3","impliedFormat":1},{"version":"36977c14a7f7bfc8c0426ae4343875689949fb699f3f84ecbe5b300ebf9a2c55","impliedFormat":1},{"version":"035d0934d304483f07148427a5bd5b98ac265dae914a6b49749fe23fbd893ec7","impliedFormat":99},{"version":"e2ed5b81cbed3a511b21a18ab2539e79ac1f4bc1d1d28f8d35d8104caa3b429f","impliedFormat":99},{"version":"161c8e0690c46021506e32fda85956d785b70f309ae97011fd27374c065cac9b","affectsGlobalScope":true,"impliedFormat":1},{"version":"4ec16d7a4e366c06a4573d299e15fe6207fc080f41beac5da06f4af33ea9761e","impliedFormat":1},{"version":"7870becb94cbc11d2d01b77c4422589adcba4d8e59f726246d40cd0d129784d8","affectsGlobalScope":true,"impliedFormat":1},{"version":"7f698624bbbb060ece7c0e51b7236520ebada74b747d7523c7df376453ed6fea","impliedFormat":1},{"version":"f70b8328a15ca1d10b1436b691e134a49bc30dcf3183a69bfaa7ba77e1b78ecd","impliedFormat":1},{"version":"d9030fc0c412a31e7e13d189b9ad032b5177c20217add0f24fd3fff0cf272882","impliedFormat":99},{"version":"69d4b61c408556b97b796782a1110f7e01a03ed80f31741f2c59b722185830ed","impliedFormat":1},{"version":"b6d03c9cfe2cf0ba4c673c209fcd7c46c815b2619fd2aad59fc4229aaef2ed43","impliedFormat":1},{"version":"e6ca59368dce5a594dcde9bbb6ae640d668fa6c28c31639dd2a75b731bb036a2","impliedFormat":1},{"version":"670a76db379b27c8ff42f1ba927828a22862e2ab0b0908e38b671f0e912cc5ed","impliedFormat":1},{"version":"13b77ab19ef7aadd86a1e54f2f08ea23a6d74e102909e3c00d31f231ed040f62","impliedFormat":1},{"version":"069bebfee29864e3955378107e243508b163e77ab10de6a5ee03ae06939f0bb9","impliedFormat":1},{"version":"26e0ffceb2198feb1ef460d5d14111c69ad07d44c5a67fd4bfeb74c969aa9afb","impliedFormat":99},{"version":"bcd03d0c9e4bdbe79938e476a4cc5fb5a42dabd6ddeabf72ad3aca19318986b2","signature":"b67ea2724064c4fdae5150153933d1151f7d431aa45aeea35181f921bb7b98d4"},{"version":"ae77d81a5541a8abb938a0efedf9ac4bea36fb3a24cc28cfa11c598863aba571","impliedFormat":1},{"version":"87d9d29dbc745f182683f63187bf3d53fd8673e5fca38ad5eaab69798ed29fbc","impliedFormat":1},{"version":"eb5b19b86227ace1d29ea4cf81387279d04bb34051e944bc53df69f58914b788","affectsGlobalScope":true,"impliedFormat":1},{"version":"ac51dd7d31333793807a6abaa5ae168512b6131bd41d9c5b98477fc3b7800f9f","impliedFormat":1},{"version":"09ddcfcfbe77a8232d155ca1030005106b1328f6210df43629d0be750da07c16","affectsGlobalScope":true,"impliedFormat":1},{"version":"17ed71200119e86ccef2d96b73b02ce8854b76ad6bd21b5021d4269bec527b5f","impliedFormat":1}],"root":[105],"options":{"allowSyntheticDefaultImports":true,"composite":true,"module":99,"skipLibCheck":true,"strict":true},"referencedMap":[[100,1],[103,2],[99,1],[101,3],[102,1],[111,4],[110,5],[104,6],[74,7],[75,8],[19,9],[14,10],[17,11],[65,12],[56,13],[55,14],[68,14],[54,15],[16,16],[18,16],[10,17],[13,18],[61,17],[15,19],[83,20],[85,21],[84,22],[82,23],[45,24],[43,25],[44,26],[32,27],[33,25],[40,28],[31,29],[36,30],[37,31],[42,32],[48,33],[47,34],[30,35],[38,36],[39,37],[34,38],[41,24],[35,39],[23,40],[22,41],[12,42],[62,43],[59,44],[60,43],[64,45],[63,46],[97,47],[91,48],[90,49],[88,49],[89,50],[96,51],[67,52],[57,53],[79,54],[69,55],[80,56],[72,57],[71,58],[70,59],[86,60],[78,61],[52,46],[49,62],[27,63],[25,64],[26,65],[51,66],[105,67]],"semanticDiagnosticsPerFile":[[105,[{"start":145,"length":10,"messageText":"Cannot find module 'node:url' or its corresponding type declarations.","category":1,"code":2307},{"start":1150,"length":4,"code":2769,"category":1,"messageText":{"messageText":"No overload matches this call.","category":1,"code":2769,"next":[{"messageText":"The last overload gave the following error.","category":1,"code":2770,"next":[{"messageText":"Object literal may only specify known properties, and 'test' does not exist in type 'UserConfigExport'.","category":1,"code":2353}]}]},"relatedInformation":[{"file":"./node_modules/vite/dist/node/index.d.ts","start":128888,"length":12,"messageText":"The last overload is declared here.","category":1,"code":2771}]}]]],"latestChangedDtsFile":"./vite.config.d.ts","version":"5.9.3"}
\ No newline at end of file
diff --git a/frontend/tsconfig.tsbuildinfo b/frontend/tsconfig.tsbuildinfo
new file mode 100644
index 0000000..ffd4a62
--- /dev/null
+++ b/frontend/tsconfig.tsbuildinfo
@@ -0,0 +1 @@
+{"root":["./src/test-setup.ts","./src/vite-env.d.ts","./src/api/assistant.ts","./src/api/auth.ts","./src/api/client.test.ts","./src/api/client.ts","./src/api/config.test.ts","./src/api/config.ts","./src/api/gam.ts","./src/api/projects.test.ts","./src/api/projects.ts","./src/api/providers.ts","./src/api/renders.ts","./src/api/usage.ts","./src/spec/anchors.ts","./src/spec/edits.test.ts","./src/spec/edits.ts","./src/spec/footage.test.ts","./src/spec/footage.ts","./src/spec/overlays.test.ts","./src/spec/overlays.ts","./src/spec/scene.ts","./src/spec/soundtrack.test.ts","./src/spec/soundtrack.ts","./src/stores/assistant.ts","./src/stores/auth.ts","./src/stores/projects.test.ts","./src/stores/projects.ts","./src/stores/renders.ts","./src/stores/theme.ts","./src/utils/useSavedFlash.ts","./src/App.tsx","./src/main.tsx","./src/components/AnchorSelect.tsx","./src/components/AppShell.tsx","./src/components/AssistantMarker.tsx","./src/components/AssistantPanel.tsx","./src/components/CreditsSettings.tsx","./src/components/FootageSearch.test.tsx","./src/components/FootageSearch.tsx","./src/components/FrameEditor.tsx","./src/components/HistoryPanel.tsx","./src/components/IssueList.tsx","./src/components/JsonPanel.test.tsx","./src/components/JsonPanel.tsx","./src/components/OverlayEditor.test.tsx","./src/components/OverlayEditor.tsx","./src/components/ProviderPanel.test.tsx","./src/components/ProviderPanel.tsx","./src/components/RenderPanel.test.tsx","./src/components/RenderPanel.tsx","./src/components/RequireAuth.test.tsx","./src/components/RequireAuth.tsx","./src/components/SceneList.test.tsx","./src/components/SceneList.tsx","./src/components/SceneSettings.test.tsx","./src/components/SceneSettings.tsx","./src/components/SoundtrackPanel.test.tsx","./src/components/SoundtrackPanel.tsx","./src/components/UsagePanel.test.tsx","./src/components/UsagePanel.tsx","./src/components/VisualStrip.test.tsx","./src/components/VisualStrip.tsx","./src/views/ProjectListView.tsx","./src/views/ProjectView.tsx","./src/views/SettingsView.tsx"],"version":"5.9.3"}
\ No newline at end of file
diff --git a/frontend/vite.config.d.ts b/frontend/vite.config.d.ts
new file mode 100644
index 0000000..8ee6163
--- /dev/null
+++ b/frontend/vite.config.d.ts
@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig & Promise<import("vite").UserConfig> & import("vite").UserConfigFnObject & import("vite").UserConfigFnPromise & import("vite").UserConfigFn;
+export default _default;
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
new file mode 100644
index 0000000..cb68e23
--- /dev/null
+++ b/frontend/vite.config.js
@@ -0,0 +1,36 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { fileURLToPath, URL } from 'node:url';
+export default defineConfig({
+    plugins: [react()],
+    resolve: {
+        alias: {
+            '@': fileURLToPath(new URL('./src', import.meta.url)),
+        },
+    },
+    build: {
+        outDir: 'dist',
+        sourcemap: false,
+    },
+    server: {
+        // Notes runs on 5173/8000 and GAM on 5174/8001, and all three run side by side.
+        // Pinned, so which app is on which port does not depend on start order.
+        port: 5175,
+        proxy: {
+            // Same-origin in production (nginx proxies both), so the app never needs to
+            // know an API host. The dev server mimics that rather than using CORS.
+            //
+            // This target must track the port the dev backend is started on. Pointing it at
+            // a sibling's port does not fail cleanly: that backend shares JWT_SECRET_KEY, so
+            // it verifies the token and answers with another app's data.
+            '/api': { target: 'http://localhost:8002', changeOrigin: true, ws: true },
+            '/media': { target: 'http://localhost:8002', changeOrigin: true },
+        },
+    },
+    test: {
+        environment: 'jsdom',
+        setupFiles: ['./src/test-setup.ts'],
+        globals: true,
+    },
+});