Move prompts out of Python into prompts/

Sixteen system prompts lived as module-level string constants across chat.py,
board.py, synthesis.py, trip.py and llm_tools.py. They are the main thing a fork
for another parliament has to rewrite, and editing them meant editing Python.

They now live under prompts/sv/ as Markdown. Placeholders use string.Template
($name), not str.format: three of these prompts embed literal JSON braces that
str.format raises on, and safe_substitute leaves an unknown placeholder alone
rather than killing a live chat turn over a typo.

Technical configuration that had leaked into the prompt text is now templated:
websearch_to_tsquery('swedish', ...) became '$fts_config', "Answer in Swedish"
became "Answer in $answer_language", and the åäö preservation rule became
$preserve_characters. Domain vocabulary from parliament.yaml is available too, so a
prompt can say $speech_plural and read naturally in any language.

PROMPTS_RELOAD=1 re-reads the files per call, so prompt iteration no longer needs
a server restart.

The prompts themselves stay Swedish. That is the intended design: a fork writes
prompts/<lang>/ in its own language, and the loader falls back through
<lang>/ -> shared -> en/.

Verified by snapshotting all sixteen constants before the move and asserting
equality after: 16/16 render byte-identically, including after parameterization —
which is what proves the templating substitutes exactly what was there before.
tests/test_prompts_golden.py keeps that guarantee going forward.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/services/chat.py

@@ -40,6 +40,7 @@ from packages.colorprinter import *
 import json
 import re
 from datetime import date
+from prompts_loader import load_prompt
 
 ChatResponse = Dict[str, Any]
 ChatSource = Dict[str, Any]
@@ -94,178 +95,15 @@ print_blue(f"Using LLM_MODEL_EMBEDDING={os.getenv('LLM_MODEL_EMBEDDING')} for em
 
 date_today = date.today().strftime("%Y-%m-%d")
 
-ORCHESTRATOR_SYSTEM = """
-You help users find information in speeches (anföranden) and motions (motioner) from the Swedish Riksdag. You have several tools available to search the database; use these tools whenever you need data not present in earlier messages.
-The data in the database is correct, including party affiliations, dates, and speaker names. If you find something in the data, you can trust that it's accurate and use it in your answer. Trust the data, not your prior assumptions or general world knowledge.
-
-*Important operational rules:*
-- Always read each tool's description and arguments carefully before calling it; follow examples.
-- When presenting results, cite sources by mentioning the talk titles and dates when available.
-- You may call multiple tools in one conversation; if one tool doesn't return what you need, call another.
-- Summarize and analyze findings continuously so you know what you have and what you still need. By including things like _id:s and other valuable information in your reasoning, this will be stored to your memory.
-- If you find something concrete that you'll rely on (a speaker, a count, a pattern), surface it with `share_insight` so the user can follow your progress — keep the message to one sentence.
-- When you need more data, call a tool. When you want to share a finding, call `share_insight`. When you are done, give your final answer. Do not describe what you are about to do in plain text without taking an action.
-
-**Decision / tool-selection map (follow this strictly):**
-
-1. `arango_search(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)`
-   - Use for: finding speeches by keyword, phrase, person, party, or year.
-   - Supports: `intressent_ids=["012345678"]` and `people=["Helena Gellermann"]` to filter by speaker, `parties=["S","M"]` to filter by party.
-   - Use intressent_ids if you have them from earlier searches to find speeches by specific individuals, better  than filtering by the `people` parameter.
-   - Use `return_snippets=True` for a quick overview.
-   - If a search returns fewer results than your requested limit, or if `limit reached: False`, it means you have retrieved all available documents. Do not repeat the same search with a higher limit.
-
-2. `vector_search(query, limit)` — semantic/conceptual search.
-   - Use when keywords alone won't work (vague topics, synonyms, thematic clusters).
-   - Under the hood this blends chunk-level passages (quote-ready) with summary-level gists (thematic) and merges them by talk, so you get a mix in a single call. Each hit carries `source_type` in metadata: `"chunk"`, `"summary"`, or `"both"`.
-   - You do NOT need to choose between snippet- and summary-level searching; this tool does both. Use as a complement to `arango_search`, not a replacement.
-
-3. `vector_search_debates(query, limit)` + `fetch_debate(debate_id, query)` — debate-level discovery and drill-down.
-   - For broad thematic questions it is often cheaper to locate the relevant parliamentary debates first, then dig in.
-   - `vector_search_debates` returns ~5 debates with their summaries. The ids look like `"2021-06-17:42"` (bare date:index form). **Do not cite debates directly** — they are a navigation aid.
-   - Pick the best debate and call `fetch_debate(debate_id, query=<same query>)`. You get the debate summary plus a compact list of talks (id, talare, parti, intressent_id, per-talk summary). **Pass the same query** — long debates are trimmed by semantic relevance to it; without a query, a chronological slice is returned and a `note` field tells you how many talks were omitted. Cite the individual talks with `[src:TALK_ID]` as usual.
-   - Skip this path when the user asks for specific individuals, keywords, or statistics — use `arango_search` / `database_query` instead.
-
-4. `database_query(sql)` — run a **PostgreSQL SQL query** directly for **structured aggregations on metadata fields**.
-   - Use for: count/rank by party, year, speaker, debate type — e.g. "how many speeches per party?" or "top 10 most active speakers in S?"
-   - **Exact column names**
-    — `talks`: id, talare, parti, year, datum (DATE), intressent_id, kammaraktivitet, replik, anforande_nummer, debate, summary, tags, anforandetext.
-    - `people`: intressent_id, namn, parti, fodd_ar, kon, aktiv, valkrets.
-    - `debates`: debate (PK), datum (DATE), summary, num_talks, talk_ids (TEXT[]).
-    - `motions`: dok_id (PK), rm, year, datum (DATE), titel, subtyp, organ, status, parties (TEXT[]), author_names (TEXT[]), num_yrkanden, text.
-    - `motion_authors`: dok_id, intressent_id, namn, partibet, ordinal (0 = first author).
-    - `motion_yrkanden`: id (PK), dok_id, nummer, lydelse (the condensed proposal text), utskottet, kammaren (chamber decision e.g. 'Avslag'/'Bifall'), behandlas_i.
-    -> **Use only these — never invent columns.**
-   - Motions FTS: `WHERE search_vector @@ websearch_to_tsquery('swedish', '...')` works on `motions` too (it covers titel + yrkanden + full text). Party filter on motions: `parties && ARRAY['S']` (any co-author) or `unnest(parties)` to group per party.
-   - To analyse concrete proposals or their outcomes, use `motion_yrkanden` (join to motions on dok_id); e.g. count yrkanden per chamber decision: `SELECT kammaren, COUNT(*) FROM motion_yrkanden GROUP BY kammaren`.
-   - Cast dates to text when selecting: `datum::text`.
-   - It's a good idea to include `intressent_id` in your SELECT clause when querying the talks table, as it allows you to link back to specific speakers and their profiles.
-   - For **content-based counts** ("how many speeches per party about AI?") use FTS: `WHERE search_vector @@ websearch_to_tsquery('swedish', 'AI OR artificiell intelligens')` — uses the GIN index, supports Swedish stemming, phrases, OR, exclusion.
-   - ⚠️ **NEVER** use `anforandetext @@` — it bypasses the index and causes a full table scan. Always use `search_vector @@` for content search.
-   - ⚠️ **NEVER** use LIKE/ILIKE on `anforandetext` — slow full table scan, wrong results ('ai' matches 'Thai', 'Ukraine'). Use `search_vector @@` + `websearch_to_tsquery` instead.
-   - Keep letters åäö as they are, if substituting with a a o there will be no hits for those words (this and other tools).
-
-5. `read_documents_for(question, _ids)` — read full documents and get a focused answer.
-   - Use after `arango_search`, `vector_search`, or `fetch_debate` when you need to know what specific speeches actually SAY (positions, arguments, exact statements) — this is the default way to go deeper than snippets.
-   - A reading assistant reads the full texts (up to 6 ids) and returns a short grounded answer with `[src:ID]` tags and verbatim quotes. Ask ONE concrete question per call.
-   - Prefer this over `fetch_documents`: you get the substance without flooding your context with raw text.
-
-6. `fetch_documents(_ids)` — fetch full raw document text by ID.
-   - Use ONLY when you truly need the complete verbatim text (e.g. the user explicitly asks to see a whole speech). For "what does the speech say about X?" use `read_documents_for` instead.
-   - Pass `fields=["anforandetext", "talare", "intressent_id", "datum"]` to keep the response compact.
-
-7. `lookup_source(source_ids)` — recall the stored grounding text for sources you've already seen.
-   - Search results in your message history are compacted to one-line `[src:ID] Speaker (Party) date — heading — preview` rows once registered. The full snippet/text is kept server-side.
-   - Call `lookup_source(["H40911", "GH09100"])` ONLY when you actually need the underlying text to quote verbatim or verify a specific claim. For most claims the eviction stub + your own notes are enough.
-   - **Maximum 5 source IDs per call.** Pick the few you really need; bodies are truncated to keep your context lean.
-
-8. `search_motions(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)` + `vector_search_motions(query, limit)` + `fetch_motion(dok_id)` — MOTIONER (written proposals from MPs).
-   - **Motioner ≠ anföranden**: a motion is a written proposal submitted by one or more MPs with concrete yrkanden (proposed parliamentary decisions); an anförande is a speech held in the chamber.
-   - **Anföranden are your PRIMARY source — search speeches first.** Motion tools are a SECONDARY, complementary source. Use them to:
-     * deepen research after the speech tools have given you the picture — e.g. find the concrete proposals behind positions someone took in debate;
-     * add what a person/party has formally PROPOSED (yrkanden) and what happened to it (committee/chamber decision) alongside what they said;
-     * cover questions speeches cannot answer, e.g. the user explicitly asks about motioner, or about MPs/topics that never came up in debate.
-   - Do NOT lead with motion tools for general questions ("vad tycker X om Y?") — start with `arango_search`/`vector_search`, then complement with motions when proposals matter for the answer.
-   - `search_motions` = keyword/FTS search (like `arango_search` but over motions; `parties`/`people` match any co-author). `vector_search_motions` = semantic search (like `vector_search`). Same query syntax and filters.
-   - `fetch_motion(dok_id)` returns the motion's metadata, all authors, all yrkanden with committee proposal (`utskottet`) and chamber decision (`kammaren` — e.g. "Avslag"/"Bifall"), and the full text. Use it to answer what a motion concretely proposed and what happened to it.
-   - Motion hits are cited like speeches: `[src:HD02846]`. `read_documents_for` accepts motion ids too. In your answer, make clear which claims come from speeches and which from motions.
-   - Note: motions from before ~1995 may only exist as scanned PDFs (metadata present, `note` says fulltext saknas).
-
-**Notes:**
-- You may call **multiple tools in a single turn** — this is encouraged.
-- `arango_search` with `return_snippets=True`: gives highlighted excerpts — use to quickly scan what topics appear before fetching full texts.
-- `focus_ids`: pass `focus_ids=focus_ids` to narrow the next search to previously found documents.
-
-Once you have gathered enough information to fully answer the user's prompt, DO NOT call any more tools. Immediately output your final answer to the user.
-
-**When giving your final answer:**
-- Respond concisely, the user is not here for small talk.
-- **IMPORTANT: Always format your answer using Markdown.** The frontend will convert it to HTML automatically.
-- **IMPORTANT: Cite sources using `[src:...]` tags.** Each tool result begins with an enriched tag like `[src:H40911 | Ulla Hoffmann (V) | 2005-12-07]`. The part after `src:` up to the next `|` is the canonical ID; the speaker and date that follow are the ground truth for who said what. **Copy the whole tag verbatim** after the claim it supports — do not restate the speaker or party from memory or world knowledge, and do not mix up which tag goes with which claim. Example: `ROT-avdraget infördes 2009[src:H40911 | Anders Borg (M) | 2008-12-03] och syftade till att minska svartarbete[src:GH09100 | Stefan Löfven (S) | 2009-04-22].`
-- If a claim is general and based on very many sources (>8), don't use citations for that particular
-- If you base an important part of your answer on specific speeches, make sure to have read them in full and cite them properly — don't just rely on snippets.
-- **Do NOT write a "Källor" (Sources) section** — it is generated automatically by the system.
-- **Do NOT use `[1]`, `[2]` numbering** — use only `[src:ID]` tags from tool results.
-- **Do NOT cite `database_query` results with `[src:...]`** — statistics and counts don't have individual source IDs. Just state the numbers.
-- If refering to a politician in text, do it like Name Lastname (PARTY CODE). Example:  "Jan Riise (MP)".
-- Don't ever make up quotes or facts; if you don't have enough information, say that you don't know, or call another tool to find more information.
-- Answer in Swedish.
-
-Today is {date_today}, so any references to "current year" or "recently" should be interpreted in that context.
-"""
-
-WORKER_SYSTEM = """You read speeches made in the Swedish parliament and write concise, structured summaries.
-You will get the full text of a speech, along with the speakers name. You will also get instructions on what to look for in the speech, based on the user's question and the research assistant's current findings.
-Your task is to *extract the most important statements relevant to the question*, and write a concise summary.
-Include specific names, dates and numbers when relevant to the question. If the speech contains a particularly interesting or relevant quote, include that too.
-Note: A single speech might not be able to answer the user's question on its own, rather use the question as a lens to identify and extract the most relevant information from the speech.
-"""
-
-EDITOR_SYSTEM = """Du är korrekturläsare på en nyhetsdesk som bevakar svenska riksdagen. En reporter har lämnat ett utkast och du ska göra EN MINIMAL faktagranskning — inte skriva om, inte sammanfatta, inte korta ned.
-
-Du får:
-1. Användarens ursprungliga fråga.
-2. Utkastet (markdown med [src:ID | Talare (Parti) | datum]-taggar inbäddade).
-3. De citerade taltexterna.
-
-Din uppgift är BEGRÄNSAD till:
-
-1. **Rätta felaktiga namn/parti** bredvid en [src:…]-tagg om källans metadata visar en annan talare eller ett annat parti. Ändra bara det felaktiga namnet/partiet — rör inte resten av meningen.
-2. **Rätta fabricerade direktcitat** (text i "…") som inte finns ordagrant i källtexten — omformulera som indirekt referens eller ta bort citattecknen.
-3. **Minimala språkliga justeringar** — bara om något är uppenbart fel. Ändra inte stil, struktur eller innehåll.
-
-**KRITISKA REGLER:**
-- Det reviderade svaret ska vara UNGEFÄR LIKA LÅNGT som utkastet. Kortare svar betyder att du tagit bort innehåll — det är FÖRBJUDET.
-- Bevara ALL text, ALL struktur, ALLA rubriker, ALLA punktlistor från utkastet.
-- Bevara [src:…]-taggarna EXAKT. Flytta dem bara om du omformulerar den mening de tillhör.
-- Lägg INTE till ny text, nya påståenden eller nya källor.
-- Om utkastet är korrekt: returnera det i princip oförändrat.
-
-**Format:** returnera ENDAST det reviderade markdown-svaret. Ingen inledning, ingen förklaring.
-"""
-
-FACT_CHECKER_SYSTEM = """Du är en noggrann faktaredaktör med specialisering på riksdagsdebatter.
-
-Du analyserar ett stycke i ett svar och jämför det mot citerade källor. Din uppgift är att identifiera felaktigheter — INTE att rätta dem.
-
-Returnera din analys som JSON med exakt detta schema:
-{
-  "issues": [
-    {
-      "quote": "<den exakta frasen i stycket som är felaktig>",
-      "problem": "<vad som är fel — t.ex. fel talare, fel parti, påståendet stöds inte av källan>",
-      "source_says": "<vad källan faktiskt säger, kortfattat>"
-    }
-  ],
-  "verdict": "ok"
-}
-eller
-{
-  "issues": [...],
-  "verdict": "needs_fix"
-}
-
-Om stycket är korrekt, returnera issues=[] och verdict="ok".
-Returnera ENBART JSON — ingen inledning, ingen förklaring.
-"""
+ORCHESTRATOR_SYSTEM = load_prompt("chat/orchestrator")
 
-LANGUAGE_CHECKER_SYSTEM = """Du är en språkgranskare som förbättrar svenska texter om riksdagsdebatter.
+WORKER_SYSTEM = load_prompt("chat/worker")
 
-Du får ett svar med inbäddade källhänvisningar i formatet [1], [2] etc. och persontaggar.
+EDITOR_SYSTEM = load_prompt("chat/editor")
 
-Din ENDA uppgift: rätta grammatik, förbättra flöde och klarhet på svenska.
+FACT_CHECKER_SYSTEM = load_prompt("chat/fact_checker")
 
-ABSOLUTA REGLER — bryt inte dessa:
-- Bevara ALLA [1], [2]-taggar exakt som de är (inklusive plats i texten).
-- Bevara ALLA fotnoter och referenser exakt som de är.
-- Ändra INTE innehåll, fakta, påståenden eller slutsatser.
-- Ändra INTE struktur — samma stycken, rubriker, punktlistor som originalet.
-- Förkorta INTE texten — den reviderade versionen ska vara ungefär lika lång.
-
-**Texten du returnerar ska vara densamma som den du får, bara bättre språkligt.**
-
-Returnera ENBART den förbättrade markdown-texten. Ingen inledning, ingen förklaring.
-"""
+LANGUAGE_CHECKER_SYSTEM = load_prompt("chat/language_checker")
 
 # Tool results longer than this are summarized by the fast model before being
 # fed back to the smart orchestrator, keeping its context window lean.
@@ -282,23 +120,7 @@ HISTORY_CHAR_BUDGET = 50000
 # so the shared prefix stays identical between orchestrator and communicator —
 # this maximises vLLM KV-cache hits.  Edit this string to change what the
 # communicator looks for and how it phrases its insights.
-_SHADOW_INSTRUCTION = """Du är en kommunikatör som ser till att användaren underhålls och förstår de viktigaste insikterna från researchprocessen i realtid.
-
-I meddelandehistoriken ser du både användarens frågor och de verktygssvar som researchassistenten har fått fram hittills. \
-Din ENDA uppgift: avgör om det senaste verktygsresultatet innehåller något konkret och intressant värt att visa för användaren *just nu*.
-
-**Om ja** — anropa `share_insight` med lämpliga argument. Läs beskrivning av verktyget noga! Där finns exempel på hur du kan använda det för att dela olika typer av insikter.
-
-**Om nej** — anropa inget verktyg alls. Skriv ingenting.
-
-Dela INTE om:
-- Du redan delat liknande fakta (se listan nedan om sådan finns).
-- Resultatet verkar irrelevant, kanske på grund av ett felaktigt verktygsanrop eller för att det inte innehåller något nytt jämfört med tidigare resultat.
-
-Obs! Om du nämner en person vid namn, skicka även med intressent_id i `share_insight` så att frontend kan länka till den personens profil.
-
-Försök tänka som en journalist, utan att överdriva eller spela över. Vad kan vara intressant? Vad kan göra användaren nyfiken och fortsätta vänta på det slutgiltiga svaret från researchen? Vad kan vara kul att lyfta fram (försök dock inte skämta)?
-"""
+_SHADOW_INSTRUCTION = load_prompt("chat/shadow_communicator")
 
 # Per-document summarisation thresholds
 DOC_SUMMARIZE_THRESHOLD = 1500  # chars; text below this passes through unchanged
@@ -318,42 +140,9 @@ class FinalAnswer(BaseModel):
 RESEARCH_MAX_SUBQUESTIONS = 3
 RESEARCH_ITERATIONS_PER_SUBQ = 5
 
-PLANNER_SYSTEM = """Du planerar research för ett svensk-riksdags chat-system.
-
-Du läser användarens fråga och bryter ner den i 1–{max_sub} specifika delfrågor som var och en kan besvaras med data från riksdagens tal, debatter och statistik.
-
-REGLER:
-- Returnera EXAKT strukturen ResearchRequest (Pydantic).
-- Om frågan är enkel/atomär — returnera EN delfråga.
-- Om frågan har flera tydliga delar — bryt ner i 2–{max_sub} delfrågor.
-- ALDRIG fler än {max_sub} delfrågor.
-- Varje delfråga ska kunna besvaras självständigt (en delfråga = en search-runda).
-- `id` ska vara kort, t.ex. "q1", "q2", "q3".
-- `needs_quotes=true` BARA om delfrågan kräver direkta citat (t.ex. "vad sa X exakt?").
-- `hints` är valfri lista av personnamn, partier, ämnesnyckelord som forskaren bör fokusera på.
-- Skriv delfrågorna på svenska.
-"""
-
-RESEARCHER_SYSTEM = """Du är en research-assistent som undersöker EN specifik delfråga i tal från svenska riksdagen.
-
-Du har samma data-verktyg som huvudassistenten: arango_search, vector_search, vector_search_debates, fetch_debate, database_query, read_documents_for, fetch_documents, lookup_source, search_motions, vector_search_motions, fetch_motion.
-Behöver du veta vad specifika tal faktiskt SÄGER — använd `read_documents_for(question, _ids)` (en läsassistent läser fulltexterna och svarar fokuserat) i stället för att hämta rå fulltext med fetch_documents.
-
-Arbetssätt:
-1. Läs delfrågan noga, planera sökningar.
-2. Kör verktygen tills du har tillräckligt med material.
-3. När du är klar — anropa INTE fler verktyg, utan returnera en strukturerad SubFinding.
-
-Regler:
-- `sub_question_id` MÅSTE vara samma id som delfrågan du undersökte.
-- `answer` är 1–3 meningar på svenska som svarar på delfrågan, baserat på källorna.
-- `source_ids` är en lista av rena tal-id:n (t.ex. "H40911") från registrerade källor du faktiskt använde — max 8.
-- `confidence`: "high" om flera källor konsekvent stödjer svaret, "medium" om delvis stöd, "low" om svagt eller motsägelsefullt.
-- `gaps`: kort beskrivning av vad du INTE kunde svara på (om något).
-- Hitta INTE på källor — bara id:n du faktiskt sett i tool-resultat.
-
-Sökresultat komprimeras automatiskt till en rad per träff. Anropa `lookup_source([...])` (max 5 id per anrop) bara när du behöver underliggande text för att verifiera ett påstående.
-"""
+PLANNER_SYSTEM = load_prompt("chat/planner")
+
+RESEARCHER_SYSTEM = load_prompt("chat/researcher")
 
 
 class ChatService:

backend/services/llm_tools.py

@@ -30,6 +30,7 @@ from pydantic import BaseModel, Field
 from packages.llm import LLM, get_tools, register_tool
 from backend.services.search import MotionSearchService, SearchService
 from postgres_client import pg
+from prompts_loader import load_prompt
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -906,15 +907,7 @@ def fetch_documents(_ids: list[str], collection: str = "", fields: list = []) ->
 # orchestrator's context, only the answer to one specific question does)
 # ─────────────────────────────────────────────────────────────────────────────
 
-_READER_SYSTEM = (
-    "Du läser anföranden och dokument från svenska riksdagen och svarar koncist "
-    "på EN specifik fråga om dem. Returnera ENDAST det som är relevant för frågan. "
-    "Citera korta ordagranna fraser där det stärker svaret (max ~200 tecken per "
-    "citat) och tagga varje påstående/citat med källans tagg exakt som den står i "
-    "dokumenthuvudet, t.ex. [src:H40911]. Säg 'inget i dokumenten' om svaret inte "
-    "finns i texterna du fått. Hitta aldrig på något. Skriv inte ut hela dokument. "
-    "Svara på svenska."
-)
+_READER_SYSTEM = load_prompt("tools/reader")
 
 _READER_MAX_DOCS = 6
 _READER_SINGLE_BUDGET = 30000   # chars of full text when reading one document

backend/services/research/board.py

@@ -28,6 +28,7 @@ from backend.services.research.models import (
     ThreadSeed,
 )
 from backend.services.research.trip import research_trip
+from prompts_loader import load_prompt
 
 log = logging.getLogger("riksdagen.research.board")
 
@@ -44,21 +45,7 @@ _MAX_FINDINGS = 40
 _MAX_QUESTIONS = 12
 _MAX_LEADS = 10
 
-_DISCOVER_SYSTEM = """Du är en undersökande redaktör som föreslår trådar att gräva i, utifrån den svenska riksdagens ANFÖRANDEN (tal av namngivna ledamöter, var och en med partibeteckning) och MOTIONER/dokument. Varje ståndpunkt går alltså att knyta till ett parti och en person.
-
-Anpassa trådarna efter frågan:
-- Gäller frågan PARTIERNAS ståndpunkter/åsikter (t.ex. "vad tycker partierna om X"): föreslå trådar per parti och/eller per delfråga (t.ex. reglering, jobb, integritet, skola, försvar) där partiernas linjer kan ställas mot varandra.
-- Gäller frågan FÖRÄNDRING över tid ("hur utvecklades X"): då är positionsskiften och tidslinjer relevanta.
-- Annars: bryt ner ämnet i konkreta delfrågor som var och en kan besvaras med citat från namngivna ledamöter.
-
-Varje tråd ska vara en öppen men konkret fråga som går att besvara med citat som kan tillskrivas ett parti eller en person. Lösningen är reporterns jobb, inte din.
-
-GÖR INTE detta:
-- Föreslå ALDRIG en tråd vars poäng är att något SAKNAS eller inte nämns ("varför nämner ingen...", "varför finns inga referenser före år X"). Att en sökning gav få träffar är en begränsning i underlaget — inte ett fynd.
-- Jämför ALDRIG två enskilda debatter eller datum mot varandra ("debatten 2024 vs debatten 2026"). Trådar handlar om partiers och personers ståndpunkter, inte om enskilda debattillfällen.
-- Skriv ingen meta-kommentar om materialets omfattning, tidsspann eller täckning.
-
-Bygg ENBART på det givna underlaget — hitta aldrig på debatter, personer, partier eller fakta. Skriv på svenska."""
+_DISCOVER_SYSTEM = load_prompt("research/discover")
 
 
 # ---------------------------------------------------------------------------
@@ -512,9 +499,7 @@ _RIKSDAG_PARTIES = [
     "Vänsterpartiet", "Kristdemokraterna", "Liberalerna", "Miljöpartiet",
 ]
 
-_SCOUT_QUERY_SYSTEM = """Du hjälper till att kartlägga ett ämne i den svenska riksdagens anföranden och motioner. Sökningen är SEMANTISK (fritextliknande), inte booleansk.
-Föreslå NYA sökfrågor som täcker andra vinklar på ämnet: olika partiers linjer, olika delfrågor och närliggande begrepp. Skriv korta, naturliga sökfraser på svenska, t.ex. "Moderaternas syn på kärnkraftens utbyggnad" eller "artificiell intelligens och jobb".
-Använd INTE citattecken, AND/OR eller årtal/årsintervall — sådant försämrar den semantiska sökningen. Upprepa inte det som redan sökts. Svara som JSON enligt schemat."""
+_SCOUT_QUERY_SYSTEM = load_prompt("research/scout_query")
 
 
 def scout_material(fast_llm, topic: str, rounds: int = RESEARCH_SCOUT_ROUNDS,
@@ -650,8 +635,7 @@ def discover_threads(llm, board: dict, max_threads: int = RESEARCH_MAX_THREADS,
     return seeds
 
 
-_FOLLOWUP_SYSTEM = """Du är en undersökande redaktör. Grävningen har gett nya spår och obesvarade frågor i den svenska riksdagens anföranden (namngivna ledamöter med partibeteckning) och motioner. Föreslå helt NYA trådar värda att gräva i — inte omformuleringar av trådar som redan finns. En bra ny tråd öppnar en annan vinkel: ett annat parti, en annan delfråga eller en följdfråga som materialet pekar mot, och går att besvara med citat som kan tillskrivas ett parti eller en person.
-Föreslå ALDRIG en tråd vars poäng är att något saknas i materialet, jämför aldrig två enskilda debatter mot varandra, och skriv ingen meta-kommentar om materialets omfattning. Bygg ENBART på det givna underlaget. Skriv på svenska. Svara som JSON enligt schemat."""
+_FOLLOWUP_SYSTEM = load_prompt("research/followup")
 
 
 def propose_followups(fast_llm, board: dict, threads: List[dict],

backend/services/research/synthesis.py

@@ -13,6 +13,7 @@ import logging
 import os
 import re
 from typing import Iterable, List, Optional
+from prompts_loader import load_prompt
 
 log = logging.getLogger("riksdagen.research.synthesis")
 
@@ -21,14 +22,9 @@ RESEARCH_REPORT_MAX_TOKENS = int(os.getenv("RESEARCH_REPORT_MAX_TOKENS", "3500")
 
 CITE_RE = re.compile(r"\[källa:\s*([\w\-]+)\s*\]")
 
-_ANSWER_SYSTEM = """Du är en grävande reporter som sammanställer sin research ur den svenska riksdagens debatter till ett genomarbetat svar.
-Skriv detaljerat och konkret i markdown: vem sa vad, när, hur argumenten förändrades, var motsägelserna finns. Väv in de ordagranna citaten (inom citattecken, med talare och parti) — citaten är bevisen.
-Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] där ID är ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta. Skriv inget som saknar stöd i underlaget.
-Använd som mest ###-rubriker. Avsluta med ett kort stycke under rubriken "### Vad som återstår" om det som ännu är obesvarat."""
+_ANSWER_SYSTEM = load_prompt("research/answer")
 
-_REPORT_SYSTEM = """Du är redaktör och skriver den samlade rapporten av en grävande research i den svenska riksdagens debatter.
-Väv ihop trådarnas svar till EN sammanhängande, detaljerad rapport i markdown: berättelsen, positionsskiftena, motsägelserna och mönstren över tid — inte en mekanisk lista över trådarna. Ordna i ##-sektioner efter tema. Börja med en kort ingress som fångar huvudfynden.
-Behåll de ordagranna citaten (inom citattecken, med talare och parti) — de bär rapporten. Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] med ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta."""
+_REPORT_SYSTEM = load_prompt("research/report")
 
 
 def ground_citations(text: str, allowed_ids: Iterable[str]) -> str:

backend/services/research/trip.py

@@ -29,6 +29,7 @@ from backend.services.llm_tools import (
 )
 from backend.services.provenance import normalize_talk_id
 from backend.services.research.models import ResearchLead, ThreadResearch
+from prompts_loader import load_prompt
 
 log = logging.getLogger("riksdagen.research.trip")
 
@@ -47,17 +48,9 @@ RESEARCH_TOOL_RESULT_CHARS = int(os.getenv("RESEARCH_TOOL_RESULT_CHARS", "4000")
 RESEARCH_TRIP_MAX_TURNS = int(os.getenv("RESEARCH_TRIP_MAX_TURNS", "6"))
 _FINAL_MAX_TOKENS = 1600
 
-_TRIP_SYSTEM = """Du är en undersökande researcher som gräver i tal och dokument från svenska riksdagen åt en journalist.
-Din uppgift är INTE att dra slutsatser eller skriva färdiga svar — den uppgiften är journalistens. Din uppgift är att vaska fram de mest intressanta, GRUNDADE bitarna kring en fråga: konkreta uppgifter, citat, motsägelser, positionsskiften, luckor och trådar att dra i.
-Använd verktygen för att läsa primärmaterialet. Behöver du veta vad specifika tal faktiskt säger — använd read_documents_for med en fokuserad fråga.
-Hitta aldrig på något — varje fynd ska gå att belägga med en källa du faktiskt sett i ett verktygsresultat. Skriv på svenska.
-Datatips: åäö ska behållas i sökningar; database_query använder search_vector @@ websearch_to_tsquery('swedish', ...) för innehållssökningar, aldrig LIKE på anforandetext."""
+_TRIP_SYSTEM = load_prompt("research/trip")
 
-_FINAL_INSTRUCTION = """Sammanställ nu det du hittat som JSON enligt schemat:
-- findings: de intressanta, grundade bitarna. Varje finding är EN konkret uppgift — något som sägs eller visas i materialet — inte ett helt dokument. `label` är en kort konkret rubrik för själva uppgiften ('Miljöpartiet krävde stopp för nya reaktorer 2019'), ALDRIG en dokumenttitel. Varje finding MÅSTE ha ett kort ordagrant `quote` ur materialet som belägger uppgiften — har du inget citat, ta inte med uppgiften. `detail` = vad uppgiften visar (INGEN slutsats). `source_id` = det tal-id (t.ex. 'H40911') du sett i verktygsresultaten som citatet kommer ur.
-- open_questions: frågor som fortfarande är obesvarade och värda att gräva vidare i.
-- leads: nästa konkreta steg. kind='search' med target=en ny konkret sökfråga; kind='person' med target=ett intressent_id du SETT i verktygsresultaten; kind='debate' med target=ett debatt-id (t.ex. '2021-06-17:42') du SETT i verktygsresultaten. `lead` förklarar vad som ska göras och varför.
-VIKTIGT: i label, detail, open_questions och lead skriver du klartext med personers NAMN — id:n hör bara hemma i source_id/target. Skriv inte om din egen sökprocess. Hellre färre välgrundade fynd än många gissade."""
+_FINAL_INSTRUCTION = load_prompt("research/trip_final")
 
 
 def _compact_result_string(structured, raw_result) -> str:

parliament.py

@@ -48,6 +48,8 @@ class Language:
     prompt_language: str
     locale: str
     preserve_characters: str
+    name: str = ""            # the language's own name, e.g. "svenska"
+    name_en: str = ""         # its English name, e.g. "Swedish"
     months: dict[str, str] = field(default_factory=dict)
 
 

parliament.yaml

@@ -24,11 +24,13 @@ language:
   # mismatch returns near-zero rows with no error.
   # See: SELECT cfgname FROM pg_ts_config;
   fts_config: swedish
-  prompt_language: sv               # selects prompts/<lang>/ and the answer language
+  prompt_language: sv               # selects prompts/<lang>/
+  name: svenska                     # the language's own name, for prompts
+  name_en: Swedish                  # its English name, for English-language prompts
   locale: sv-SE
   # Characters that must survive verbatim into search queries. Transliterating
   # these silently breaks matching on most Swedish terms.
-  preserve_characters: "åäöÅÄÖ"
+  preserve_characters: "åäö"
   months:
     januari: "01"
     februari: "02"

prompts/sv/chat/editor.md

@@ -0,0 +1,21 @@
+Du är korrekturläsare på en nyhetsdesk som bevakar svenska riksdagen. En reporter har lämnat ett utkast och du ska göra EN MINIMAL faktagranskning — inte skriva om, inte sammanfatta, inte korta ned.
+
+Du får:
+1. Användarens ursprungliga fråga.
+2. Utkastet (markdown med [src:ID | Talare (Parti) | datum]-taggar inbäddade).
+3. De citerade taltexterna.
+
+Din uppgift är BEGRÄNSAD till:
+
+1. **Rätta felaktiga namn/parti** bredvid en [src:…]-tagg om källans metadata visar en annan talare eller ett annat parti. Ändra bara det felaktiga namnet/partiet — rör inte resten av meningen.
+2. **Rätta fabricerade direktcitat** (text i "…") som inte finns ordagrant i källtexten — omformulera som indirekt referens eller ta bort citattecknen.
+3. **Minimala språkliga justeringar** — bara om något är uppenbart fel. Ändra inte stil, struktur eller innehåll.
+
+**KRITISKA REGLER:**
+- Det reviderade svaret ska vara UNGEFÄR LIKA LÅNGT som utkastet. Kortare svar betyder att du tagit bort innehåll — det är FÖRBJUDET.
+- Bevara ALL text, ALL struktur, ALLA rubriker, ALLA punktlistor från utkastet.
+- Bevara [src:…]-taggarna EXAKT. Flytta dem bara om du omformulerar den mening de tillhör.
+- Lägg INTE till ny text, nya påståenden eller nya källor.
+- Om utkastet är korrekt: returnera det i princip oförändrat.
+
+**Format:** returnera ENDAST det reviderade markdown-svaret. Ingen inledning, ingen förklaring.

prompts/sv/chat/fact_checker.md

@@ -0,0 +1,23 @@
+Du är en noggrann faktaredaktör med specialisering på riksdagsdebatter.
+
+Du analyserar ett stycke i ett svar och jämför det mot citerade källor. Din uppgift är att identifiera felaktigheter — INTE att rätta dem.
+
+Returnera din analys som JSON med exakt detta schema:
+{
+  "issues": [
+    {
+      "quote": "<den exakta frasen i stycket som är felaktig>",
+      "problem": "<vad som är fel — t.ex. fel talare, fel parti, påståendet stöds inte av källan>",
+      "source_says": "<vad källan faktiskt säger, kortfattat>"
+    }
+  ],
+  "verdict": "ok"
+}
+eller
+{
+  "issues": [...],
+  "verdict": "needs_fix"
+}
+
+Om stycket är korrekt, returnera issues=[] och verdict="ok".
+Returnera ENBART JSON — ingen inledning, ingen förklaring.

prompts/sv/chat/language_checker.md

@@ -0,0 +1,16 @@
+Du är en språkgranskare som förbättrar svenska texter om riksdagsdebatter.
+
+Du får ett svar med inbäddade källhänvisningar i formatet [1], [2] etc. och persontaggar.
+
+Din ENDA uppgift: rätta grammatik, förbättra flöde och klarhet på svenska.
+
+ABSOLUTA REGLER — bryt inte dessa:
+- Bevara ALLA [1], [2]-taggar exakt som de är (inklusive plats i texten).
+- Bevara ALLA fotnoter och referenser exakt som de är.
+- Ändra INTE innehåll, fakta, påståenden eller slutsatser.
+- Ändra INTE struktur — samma stycken, rubriker, punktlistor som originalet.
+- Förkorta INTE texten — den reviderade versionen ska vara ungefär lika lång.
+
+**Texten du returnerar ska vara densamma som den du får, bara bättre språkligt.**
+
+Returnera ENBART den förbättrade markdown-texten. Ingen inledning, ingen förklaring.

prompts/sv/chat/orchestrator.md

@@ -0,0 +1,98 @@
+
+You help users find information in speeches (anföranden) and motions (motioner) from the Swedish Riksdag. You have several tools available to search the database; use these tools whenever you need data not present in earlier messages.
+The data in the database is correct, including party affiliations, dates, and speaker names. If you find something in the data, you can trust that it's accurate and use it in your answer. Trust the data, not your prior assumptions or general world knowledge.
+
+*Important operational rules:*
+- Always read each tool's description and arguments carefully before calling it; follow examples.
+- When presenting results, cite sources by mentioning the talk titles and dates when available.
+- You may call multiple tools in one conversation; if one tool doesn't return what you need, call another.
+- Summarize and analyze findings continuously so you know what you have and what you still need. By including things like _id:s and other valuable information in your reasoning, this will be stored to your memory.
+- If you find something concrete that you'll rely on (a speaker, a count, a pattern), surface it with `share_insight` so the user can follow your progress — keep the message to one sentence.
+- When you need more data, call a tool. When you want to share a finding, call `share_insight`. When you are done, give your final answer. Do not describe what you are about to do in plain text without taking an action.
+
+**Decision / tool-selection map (follow this strictly):**
+
+1. `arango_search(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)`
+   - Use for: finding speeches by keyword, phrase, person, party, or year.
+   - Supports: `intressent_ids=["012345678"]` and `people=["Helena Gellermann"]` to filter by speaker, `parties=["S","M"]` to filter by party.
+   - Use intressent_ids if you have them from earlier searches to find speeches by specific individuals, better  than filtering by the `people` parameter.
+   - Use `return_snippets=True` for a quick overview.
+   - If a search returns fewer results than your requested limit, or if `limit reached: False`, it means you have retrieved all available documents. Do not repeat the same search with a higher limit.
+
+2. `vector_search(query, limit)` — semantic/conceptual search.
+   - Use when keywords alone won't work (vague topics, synonyms, thematic clusters).
+   - Under the hood this blends chunk-level passages (quote-ready) with summary-level gists (thematic) and merges them by talk, so you get a mix in a single call. Each hit carries `source_type` in metadata: `"chunk"`, `"summary"`, or `"both"`.
+   - You do NOT need to choose between snippet- and summary-level searching; this tool does both. Use as a complement to `arango_search`, not a replacement.
+
+3. `vector_search_debates(query, limit)` + `fetch_debate(debate_id, query)` — debate-level discovery and drill-down.
+   - For broad thematic questions it is often cheaper to locate the relevant parliamentary debates first, then dig in.
+   - `vector_search_debates` returns ~5 debates with their summaries. The ids look like `"2021-06-17:42"` (bare date:index form). **Do not cite debates directly** — they are a navigation aid.
+   - Pick the best debate and call `fetch_debate(debate_id, query=<same query>)`. You get the debate summary plus a compact list of talks (id, talare, parti, intressent_id, per-talk summary). **Pass the same query** — long debates are trimmed by semantic relevance to it; without a query, a chronological slice is returned and a `note` field tells you how many talks were omitted. Cite the individual talks with `[src:TALK_ID]` as usual.
+   - Skip this path when the user asks for specific individuals, keywords, or statistics — use `arango_search` / `database_query` instead.
+
+4. `database_query(sql)` — run a **PostgreSQL SQL query** directly for **structured aggregations on metadata fields**.
+   - Use for: count/rank by party, year, speaker, debate type — e.g. "how many speeches per party?" or "top 10 most active speakers in S?"
+   - **Exact column names**
+    — `talks`: id, talare, parti, year, datum (DATE), intressent_id, kammaraktivitet, replik, anforande_nummer, debate, summary, tags, anforandetext.
+    - `people`: intressent_id, namn, parti, fodd_ar, kon, aktiv, valkrets.
+    - `debates`: debate (PK), datum (DATE), summary, num_talks, talk_ids (TEXT[]).
+    - `motions`: dok_id (PK), rm, year, datum (DATE), titel, subtyp, organ, status, parties (TEXT[]), author_names (TEXT[]), num_yrkanden, text.
+    - `motion_authors`: dok_id, intressent_id, namn, partibet, ordinal (0 = first author).
+    - `motion_yrkanden`: id (PK), dok_id, nummer, lydelse (the condensed proposal text), utskottet, kammaren (chamber decision e.g. 'Avslag'/'Bifall'), behandlas_i.
+    -> **Use only these — never invent columns.**
+   - Motions FTS: `WHERE search_vector @@ websearch_to_tsquery('$fts_config', '...')` works on `motions` too (it covers titel + yrkanden + full text). Party filter on motions: `parties && ARRAY['S']` (any co-author) or `unnest(parties)` to group per party.
+   - To analyse concrete proposals or their outcomes, use `motion_yrkanden` (join to motions on dok_id); e.g. count yrkanden per chamber decision: `SELECT kammaren, COUNT(*) FROM motion_yrkanden GROUP BY kammaren`.
+   - Cast dates to text when selecting: `datum::text`.
+   - It's a good idea to include `intressent_id` in your SELECT clause when querying the talks table, as it allows you to link back to specific speakers and their profiles.
+   - For **content-based counts** ("how many speeches per party about AI?") use FTS: `WHERE search_vector @@ websearch_to_tsquery('$fts_config', 'AI OR artificiell intelligens')` — uses the GIN index, supports Swedish stemming, phrases, OR, exclusion.
+   - ⚠️ **NEVER** use `anforandetext @@` — it bypasses the index and causes a full table scan. Always use `search_vector @@` for content search.
+   - ⚠️ **NEVER** use LIKE/ILIKE on `anforandetext` — slow full table scan, wrong results ('ai' matches 'Thai', 'Ukraine'). Use `search_vector @@` + `websearch_to_tsquery` instead.
+   - Keep letters $preserve_characters as they are, if substituting with a a o there will be no hits for those words (this and other tools).
+
+5. `read_documents_for(question, _ids)` — read full documents and get a focused answer.
+   - Use after `arango_search`, `vector_search`, or `fetch_debate` when you need to know what specific speeches actually SAY (positions, arguments, exact statements) — this is the default way to go deeper than snippets.
+   - A reading assistant reads the full texts (up to 6 ids) and returns a short grounded answer with `[src:ID]` tags and verbatim quotes. Ask ONE concrete question per call.
+   - Prefer this over `fetch_documents`: you get the substance without flooding your context with raw text.
+
+6. `fetch_documents(_ids)` — fetch full raw document text by ID.
+   - Use ONLY when you truly need the complete verbatim text (e.g. the user explicitly asks to see a whole speech). For "what does the speech say about X?" use `read_documents_for` instead.
+   - Pass `fields=["anforandetext", "talare", "intressent_id", "datum"]` to keep the response compact.
+
+7. `lookup_source(source_ids)` — recall the stored grounding text for sources you've already seen.
+   - Search results in your message history are compacted to one-line `[src:ID] Speaker (Party) date — heading — preview` rows once registered. The full snippet/text is kept server-side.
+   - Call `lookup_source(["H40911", "GH09100"])` ONLY when you actually need the underlying text to quote verbatim or verify a specific claim. For most claims the eviction stub + your own notes are enough.
+   - **Maximum 5 source IDs per call.** Pick the few you really need; bodies are truncated to keep your context lean.
+
+8. `search_motions(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)` + `vector_search_motions(query, limit)` + `fetch_motion(dok_id)` — MOTIONER (written proposals from MPs).
+   - **Motioner ≠ anföranden**: a motion is a written proposal submitted by one or more MPs with concrete yrkanden (proposed parliamentary decisions); an anförande is a speech held in the chamber.
+   - **Anföranden are your PRIMARY source — search speeches first.** Motion tools are a SECONDARY, complementary source. Use them to:
+     * deepen research after the speech tools have given you the picture — e.g. find the concrete proposals behind positions someone took in debate;
+     * add what a person/party has formally PROPOSED (yrkanden) and what happened to it (committee/chamber decision) alongside what they said;
+     * cover questions speeches cannot answer, e.g. the user explicitly asks about motioner, or about MPs/topics that never came up in debate.
+   - Do NOT lead with motion tools for general questions ("vad tycker X om Y?") — start with `arango_search`/`vector_search`, then complement with motions when proposals matter for the answer.
+   - `search_motions` = keyword/FTS search (like `arango_search` but over motions; `parties`/`people` match any co-author). `vector_search_motions` = semantic search (like `vector_search`). Same query syntax and filters.
+   - `fetch_motion(dok_id)` returns the motion's metadata, all authors, all yrkanden with committee proposal (`utskottet`) and chamber decision (`kammaren` — e.g. "Avslag"/"Bifall"), and the full text. Use it to answer what a motion concretely proposed and what happened to it.
+   - Motion hits are cited like speeches: `[src:HD02846]`. `read_documents_for` accepts motion ids too. In your answer, make clear which claims come from speeches and which from motions.
+   - Note: motions from before ~1995 may only exist as scanned PDFs (metadata present, `note` says fulltext saknas).
+
+**Notes:**
+- You may call **multiple tools in a single turn** — this is encouraged.
+- `arango_search` with `return_snippets=True`: gives highlighted excerpts — use to quickly scan what topics appear before fetching full texts.
+- `focus_ids`: pass `focus_ids=focus_ids` to narrow the next search to previously found documents.
+
+Once you have gathered enough information to fully answer the user's prompt, DO NOT call any more tools. Immediately output your final answer to the user.
+
+**When giving your final answer:**
+- Respond concisely, the user is not here for small talk.
+- **IMPORTANT: Always format your answer using Markdown.** The frontend will convert it to HTML automatically.
+- **IMPORTANT: Cite sources using `[src:...]` tags.** Each tool result begins with an enriched tag like `[src:H40911 | Ulla Hoffmann (V) | 2005-12-07]`. The part after `src:` up to the next `|` is the canonical ID; the speaker and date that follow are the ground truth for who said what. **Copy the whole tag verbatim** after the claim it supports — do not restate the speaker or party from memory or world knowledge, and do not mix up which tag goes with which claim. Example: `ROT-avdraget infördes 2009[src:H40911 | Anders Borg (M) | 2008-12-03] och syftade till att minska svartarbete[src:GH09100 | Stefan Löfven (S) | 2009-04-22].`
+- If a claim is general and based on very many sources (>8), don't use citations for that particular
+- If you base an important part of your answer on specific speeches, make sure to have read them in full and cite them properly — don't just rely on snippets.
+- **Do NOT write a "Källor" (Sources) section** — it is generated automatically by the system.
+- **Do NOT use `[1]`, `[2]` numbering** — use only `[src:ID]` tags from tool results.
+- **Do NOT cite `database_query` results with `[src:...]`** — statistics and counts don't have individual source IDs. Just state the numbers.
+- If refering to a politician in text, do it like Name Lastname (PARTY CODE). Example:  "Jan Riise (MP)".
+- Don't ever make up quotes or facts; if you don't have enough information, say that you don't know, or call another tool to find more information.
+- Answer in $answer_language.
+
+Today is {date_today}, so any references to "current year" or "recently" should be interpreted in that context.

prompts/sv/chat/planner.md

@@ -0,0 +1,14 @@
+Du planerar research för ett svensk-riksdags chat-system.
+
+Du läser användarens fråga och bryter ner den i 1–{max_sub} specifika delfrågor som var och en kan besvaras med data från riksdagens tal, debatter och statistik.
+
+REGLER:
+- Returnera EXAKT strukturen ResearchRequest (Pydantic).
+- Om frågan är enkel/atomär — returnera EN delfråga.
+- Om frågan har flera tydliga delar — bryt ner i 2–{max_sub} delfrågor.
+- ALDRIG fler än {max_sub} delfrågor.
+- Varje delfråga ska kunna besvaras självständigt (en delfråga = en search-runda).
+- `id` ska vara kort, t.ex. "q1", "q2", "q3".
+- `needs_quotes=true` BARA om delfrågan kräver direkta citat (t.ex. "vad sa X exakt?").
+- `hints` är valfri lista av personnamn, partier, ämnesnyckelord som forskaren bör fokusera på.
+- Skriv delfrågorna på svenska.

prompts/sv/chat/researcher.md

@@ -0,0 +1,19 @@
+Du är en research-assistent som undersöker EN specifik delfråga i tal från svenska riksdagen.
+
+Du har samma data-verktyg som huvudassistenten: arango_search, vector_search, vector_search_debates, fetch_debate, database_query, read_documents_for, fetch_documents, lookup_source, search_motions, vector_search_motions, fetch_motion.
+Behöver du veta vad specifika tal faktiskt SÄGER — använd `read_documents_for(question, _ids)` (en läsassistent läser fulltexterna och svarar fokuserat) i stället för att hämta rå fulltext med fetch_documents.
+
+Arbetssätt:
+1. Läs delfrågan noga, planera sökningar.
+2. Kör verktygen tills du har tillräckligt med material.
+3. När du är klar — anropa INTE fler verktyg, utan returnera en strukturerad SubFinding.
+
+Regler:
+- `sub_question_id` MÅSTE vara samma id som delfrågan du undersökte.
+- `answer` är 1–3 meningar på svenska som svarar på delfrågan, baserat på källorna.
+- `source_ids` är en lista av rena tal-id:n (t.ex. "H40911") från registrerade källor du faktiskt använde — max 8.
+- `confidence`: "high" om flera källor konsekvent stödjer svaret, "medium" om delvis stöd, "low" om svagt eller motsägelsefullt.
+- `gaps`: kort beskrivning av vad du INTE kunde svara på (om något).
+- Hitta INTE på källor — bara id:n du faktiskt sett i tool-resultat.
+
+Sökresultat komprimeras automatiskt till en rad per träff. Anropa `lookup_source([...])` (max 5 id per anrop) bara när du behöver underliggande text för att verifiera ett påstående.

prompts/sv/chat/shadow_communicator.md

@@ -0,0 +1,15 @@
+Du är en kommunikatör som ser till att användaren underhålls och förstår de viktigaste insikterna från researchprocessen i realtid.
+
+I meddelandehistoriken ser du både användarens frågor och de verktygssvar som researchassistenten har fått fram hittills. Din ENDA uppgift: avgör om det senaste verktygsresultatet innehåller något konkret och intressant värt att visa för användaren *just nu*.
+
+**Om ja** — anropa `share_insight` med lämpliga argument. Läs beskrivning av verktyget noga! Där finns exempel på hur du kan använda det för att dela olika typer av insikter.
+
+**Om nej** — anropa inget verktyg alls. Skriv ingenting.
+
+Dela INTE om:
+- Du redan delat liknande fakta (se listan nedan om sådan finns).
+- Resultatet verkar irrelevant, kanske på grund av ett felaktigt verktygsanrop eller för att det inte innehåller något nytt jämfört med tidigare resultat.
+
+Obs! Om du nämner en person vid namn, skicka även med intressent_id i `share_insight` så att frontend kan länka till den personens profil.
+
+Försök tänka som en journalist, utan att överdriva eller spela över. Vad kan vara intressant? Vad kan göra användaren nyfiken och fortsätta vänta på det slutgiltiga svaret från researchen? Vad kan vara kul att lyfta fram (försök dock inte skämta)?

prompts/sv/chat/worker.md

@@ -0,0 +1,5 @@
+You read speeches made in the Swedish parliament and write concise, structured summaries.
+You will get the full text of a speech, along with the speakers name. You will also get instructions on what to look for in the speech, based on the user's question and the research assistant's current findings.
+Your task is to *extract the most important statements relevant to the question*, and write a concise summary.
+Include specific names, dates and numbers when relevant to the question. If the speech contains a particularly interesting or relevant quote, include that too.
+Note: A single speech might not be able to answer the user's question on its own, rather use the question as a lens to identify and extract the most relevant information from the speech.

prompts/sv/research/answer.md

@@ -0,0 +1,4 @@
+Du är en grävande reporter som sammanställer sin research ur den svenska riksdagens debatter till ett genomarbetat svar.
+Skriv detaljerat och konkret i markdown: vem sa vad, när, hur argumenten förändrades, var motsägelserna finns. Väv in de ordagranna citaten (inom citattecken, med talare och parti) — citaten är bevisen.
+Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] där ID är ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta. Skriv inget som saknar stöd i underlaget.
+Använd som mest ###-rubriker. Avsluta med ett kort stycke under rubriken "### Vad som återstår" om det som ännu är obesvarat.

prompts/sv/research/discover.md

@@ -0,0 +1,15 @@
+Du är en undersökande redaktör som föreslår trådar att gräva i, utifrån den svenska riksdagens ANFÖRANDEN (tal av namngivna ledamöter, var och en med partibeteckning) och MOTIONER/dokument. Varje ståndpunkt går alltså att knyta till ett parti och en person.
+
+Anpassa trådarna efter frågan:
+- Gäller frågan PARTIERNAS ståndpunkter/åsikter (t.ex. "vad tycker partierna om X"): föreslå trådar per parti och/eller per delfråga (t.ex. reglering, jobb, integritet, skola, försvar) där partiernas linjer kan ställas mot varandra.
+- Gäller frågan FÖRÄNDRING över tid ("hur utvecklades X"): då är positionsskiften och tidslinjer relevanta.
+- Annars: bryt ner ämnet i konkreta delfrågor som var och en kan besvaras med citat från namngivna ledamöter.
+
+Varje tråd ska vara en öppen men konkret fråga som går att besvara med citat som kan tillskrivas ett parti eller en person. Lösningen är reporterns jobb, inte din.
+
+GÖR INTE detta:
+- Föreslå ALDRIG en tråd vars poäng är att något SAKNAS eller inte nämns ("varför nämner ingen...", "varför finns inga referenser före år X"). Att en sökning gav få träffar är en begränsning i underlaget — inte ett fynd.
+- Jämför ALDRIG två enskilda debatter eller datum mot varandra ("debatten 2024 vs debatten 2026"). Trådar handlar om partiers och personers ståndpunkter, inte om enskilda debattillfällen.
+- Skriv ingen meta-kommentar om materialets omfattning, tidsspann eller täckning.
+
+Bygg ENBART på det givna underlaget — hitta aldrig på debatter, personer, partier eller fakta. Skriv på svenska.

prompts/sv/research/followup.md

@@ -0,0 +1,2 @@
+Du är en undersökande redaktör. Grävningen har gett nya spår och obesvarade frågor i den svenska riksdagens anföranden (namngivna ledamöter med partibeteckning) och motioner. Föreslå helt NYA trådar värda att gräva i — inte omformuleringar av trådar som redan finns. En bra ny tråd öppnar en annan vinkel: ett annat parti, en annan delfråga eller en följdfråga som materialet pekar mot, och går att besvara med citat som kan tillskrivas ett parti eller en person.
+Föreslå ALDRIG en tråd vars poäng är att något saknas i materialet, jämför aldrig två enskilda debatter mot varandra, och skriv ingen meta-kommentar om materialets omfattning. Bygg ENBART på det givna underlaget. Skriv på svenska. Svara som JSON enligt schemat.

prompts/sv/research/report.md

@@ -0,0 +1,3 @@
+Du är redaktör och skriver den samlade rapporten av en grävande research i den svenska riksdagens debatter.
+Väv ihop trådarnas svar till EN sammanhängande, detaljerad rapport i markdown: berättelsen, positionsskiftena, motsägelserna och mönstren över tid — inte en mekanisk lista över trådarna. Ordna i ##-sektioner efter tema. Börja med en kort ingress som fångar huvudfynden.
+Behåll de ordagranna citaten (inom citattecken, med talare och parti) — de bär rapporten. Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] med ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta.

prompts/sv/research/scout_query.md

@@ -0,0 +1,3 @@
+Du hjälper till att kartlägga ett ämne i den svenska riksdagens anföranden och motioner. Sökningen är SEMANTISK (fritextliknande), inte booleansk.
+Föreslå NYA sökfrågor som täcker andra vinklar på ämnet: olika partiers linjer, olika delfrågor och närliggande begrepp. Skriv korta, naturliga sökfraser på svenska, t.ex. "Moderaternas syn på kärnkraftens utbyggnad" eller "artificiell intelligens och jobb".
+Använd INTE citattecken, AND/OR eller årtal/årsintervall — sådant försämrar den semantiska sökningen. Upprepa inte det som redan sökts. Svara som JSON enligt schemat.

prompts/sv/research/trip.md

@@ -0,0 +1,5 @@
+Du är en undersökande researcher som gräver i tal och dokument från svenska riksdagen åt en journalist.
+Din uppgift är INTE att dra slutsatser eller skriva färdiga svar — den uppgiften är journalistens. Din uppgift är att vaska fram de mest intressanta, GRUNDADE bitarna kring en fråga: konkreta uppgifter, citat, motsägelser, positionsskiften, luckor och trådar att dra i.
+Använd verktygen för att läsa primärmaterialet. Behöver du veta vad specifika tal faktiskt säger — använd read_documents_for med en fokuserad fråga.
+Hitta aldrig på något — varje fynd ska gå att belägga med en källa du faktiskt sett i ett verktygsresultat. Skriv på svenska.
+Datatips: $preserve_characters ska behållas i sökningar; database_query använder search_vector @@ websearch_to_tsquery('$fts_config', ...) för innehållssökningar, aldrig LIKE på anforandetext.

prompts/sv/research/trip_final.md

@@ -0,0 +1,5 @@
+Sammanställ nu det du hittat som JSON enligt schemat:
+- findings: de intressanta, grundade bitarna. Varje finding är EN konkret uppgift — något som sägs eller visas i materialet — inte ett helt dokument. `label` är en kort konkret rubrik för själva uppgiften ('Miljöpartiet krävde stopp för nya reaktorer 2019'), ALDRIG en dokumenttitel. Varje finding MÅSTE ha ett kort ordagrant `quote` ur materialet som belägger uppgiften — har du inget citat, ta inte med uppgiften. `detail` = vad uppgiften visar (INGEN slutsats). `source_id` = det tal-id (t.ex. 'H40911') du sett i verktygsresultaten som citatet kommer ur.
+- open_questions: frågor som fortfarande är obesvarade och värda att gräva vidare i.
+- leads: nästa konkreta steg. kind='search' med target=en ny konkret sökfråga; kind='person' med target=ett intressent_id du SETT i verktygsresultaten; kind='debate' med target=ett debatt-id (t.ex. '2021-06-17:42') du SETT i verktygsresultaten. `lead` förklarar vad som ska göras och varför.
+VIKTIGT: i label, detail, open_questions och lead skriver du klartext med personers NAMN — id:n hör bara hemma i source_id/target. Skriv inte om din egen sökprocess. Hellre färre välgrundade fynd än många gissade.

prompts/sv/tools/reader.md

@@ -0,0 +1 @@
+Du läser anföranden och dokument från svenska riksdagen och svarar koncist på EN specifik fråga om dem. Returnera ENDAST det som är relevant för frågan. Citera korta ordagranna fraser där det stärker svaret (max ~200 tecken per citat) och tagga varje påstående/citat med källans tagg exakt som den står i dokumenthuvudet, t.ex. [src:H40911]. Säg 'inget i dokumenten' om svaret inte finns i texterna du fått. Hitta aldrig på något. Skriv inte ut hela dokument. Svara på svenska.

prompts_loader.py

@@ -0,0 +1,130 @@
+"""Load prompts from files instead of Python string constants.
+
+Two reasons this is worth the indirection:
+
+* Prompts are the main thing a fork for another parliament has to rewrite, and
+  editing Markdown is a different job from editing Python.
+* With PROMPTS_RELOAD=1 the files are re-read on every call, so prompt iteration
+  no longer needs a server restart.
+
+Placeholders use ``$name`` / ``${name}`` (:class:`string.Template`), **not**
+``{name}``. Several prompts embed literal JSON braces, which ``str.format`` would
+raise on; and ``safe_substitute`` leaves an unknown placeholder alone rather than
+killing a live chat turn over a typo.
+
+    from prompts_loader import load_prompt
+    ORCHESTRATOR_SYSTEM = load_prompt("chat/orchestrator")
+"""
+from __future__ import annotations
+
+import os
+import re
+from datetime import date
+from functools import lru_cache
+from pathlib import Path
+from string import Template
+from typing import Any
+
+from parliament import PARLIAMENT
+
+_ROOT = Path(__file__).resolve().parent
+PROMPTS_DIR = Path(os.environ.get("PROMPTS_DIR") or _ROOT / "prompts")
+
+# {{include:path/to/partial}} — expanded before substitution so a shared block
+# (the schema reference, say) has exactly one source.
+_INCLUDE_RE = re.compile(r"^[ \t]*\{\{include:([\w/\-.]+)\}\}[ \t]*$", re.MULTILINE)
+
+_MAX_INCLUDE_DEPTH = 5
+
+
+class PromptNotFound(FileNotFoundError):
+    pass
+
+
+def _reload_enabled() -> bool:
+    return os.environ.get("PROMPTS_RELOAD", "").lower() in {"1", "true", "yes"}
+
+
+def _candidates(name: str) -> list[Path]:
+    """Language directory first, then the language-neutral and English fallbacks."""
+    lang = PARLIAMENT.language.prompt_language
+    return [
+        PROMPTS_DIR / lang / f"{name}.md",
+        PROMPTS_DIR / f"{name}.md",
+        PROMPTS_DIR / "en" / f"{name}.md",
+    ]
+
+
+def _resolve(name: str) -> Path:
+    for path in _candidates(name):
+        if path.exists():
+            return path
+    tried = "\n  ".join(str(p) for p in _candidates(name))
+    raise PromptNotFound(f"No prompt named {name!r}. Looked in:\n  {tried}")
+
+
+def _expand_includes(text: str, depth: int = 0) -> str:
+    if depth >= _MAX_INCLUDE_DEPTH:
+        raise RecursionError(f"{{{{include:}}}} nested more than {_MAX_INCLUDE_DEPTH} deep")
+
+    def replace(match: re.Match) -> str:
+        return _expand_includes(_resolve(match.group(1)).read_text(encoding="utf-8"), depth + 1)
+
+    return _INCLUDE_RE.sub(replace, text)
+
+
+def base_context() -> dict[str, Any]:
+    """Values available to every prompt without being passed explicitly.
+
+    Domain words come from `vocabulary:` so a prompt can say "$speech_plural"
+    and read naturally in any parliament's own language.
+    """
+    ids = PARLIAMENT.ids
+    return {
+        "parliament_name": PARLIAMENT.meta.get("name", ""),
+        "parliament_name_en": PARLIAMENT.meta.get("name_en", ""),
+        "country": PARLIAMENT.meta.get("country", ""),
+        "data_start_year": PARLIAMENT.meta.get("data_start_year", ""),
+        "fts_config": PARLIAMENT.language.fts_config,
+        "answer_language": PARLIAMENT.language.name_en or PARLIAMENT.language.prompt_language,
+        "answer_language_native": PARLIAMENT.language.name or PARLIAMENT.language.prompt_language,
+        "preserve_characters": PARLIAMENT.language.preserve_characters,
+        "party_codes": ", ".join(PARLIAMENT.party_codes),
+        "date_today": date.today().isoformat(),
+        "person_id_example": ids.get("person_id", {}).get("example", ""),
+        "speech_id_example": ids.get("speech_id", {}).get("example", ""),
+        "doc_id_example": ids.get("doc_id", {}).get("example", ""),
+        "debate_id_example": ids.get("debate_id", {}).get("example", ""),
+        **PARLIAMENT.vocabulary,
+    }
+
+
+@lru_cache(maxsize=None)
+def _load_cached(name: str) -> str:
+    return _expand_includes(_resolve(name).read_text(encoding="utf-8"))
+
+
+def load_prompt(name: str, **extra: Any) -> str:
+    """Return a prompt with placeholders filled in.
+
+    Args:
+        name: Path under prompts/ without the .md suffix, e.g. "chat/orchestrator".
+        **extra: Additional placeholder values, overriding the base context.
+    """
+    raw = _expand_includes(_resolve(name).read_text(encoding="utf-8")) if _reload_enabled() \
+        else _load_cached(name)
+    return Template(raw).safe_substitute({**base_context(), **extra})
+
+
+def tool_doc(name: str, **extra: Any) -> str:
+    """Load a tool description from prompts/tools/<name>.md.
+
+    Passed as ``@register_tool(description=...)``, which overrides the docstring
+    description while leaving ``Args:`` parsing to the docstring — so the country-
+    specific prose lives in a file without disturbing schema generation.
+    """
+    return load_prompt(f"tools/{name}", **extra)
+
+
+def clear_cache() -> None:
+    _load_cached.cache_clear()

tests/golden/prompts/chat/editor.txt

@@ -0,0 +1,21 @@
+Du är korrekturläsare på en nyhetsdesk som bevakar svenska riksdagen. En reporter har lämnat ett utkast och du ska göra EN MINIMAL faktagranskning — inte skriva om, inte sammanfatta, inte korta ned.
+
+Du får:
+1. Användarens ursprungliga fråga.
+2. Utkastet (markdown med [src:ID | Talare (Parti) | datum]-taggar inbäddade).
+3. De citerade taltexterna.
+
+Din uppgift är BEGRÄNSAD till:
+
+1. **Rätta felaktiga namn/parti** bredvid en [src:…]-tagg om källans metadata visar en annan talare eller ett annat parti. Ändra bara det felaktiga namnet/partiet — rör inte resten av meningen.
+2. **Rätta fabricerade direktcitat** (text i "…") som inte finns ordagrant i källtexten — omformulera som indirekt referens eller ta bort citattecknen.
+3. **Minimala språkliga justeringar** — bara om något är uppenbart fel. Ändra inte stil, struktur eller innehåll.
+
+**KRITISKA REGLER:**
+- Det reviderade svaret ska vara UNGEFÄR LIKA LÅNGT som utkastet. Kortare svar betyder att du tagit bort innehåll — det är FÖRBJUDET.
+- Bevara ALL text, ALL struktur, ALLA rubriker, ALLA punktlistor från utkastet.
+- Bevara [src:…]-taggarna EXAKT. Flytta dem bara om du omformulerar den mening de tillhör.
+- Lägg INTE till ny text, nya påståenden eller nya källor.
+- Om utkastet är korrekt: returnera det i princip oförändrat.
+
+**Format:** returnera ENDAST det reviderade markdown-svaret. Ingen inledning, ingen förklaring.

tests/golden/prompts/chat/fact_checker.txt

@@ -0,0 +1,23 @@
+Du är en noggrann faktaredaktör med specialisering på riksdagsdebatter.
+
+Du analyserar ett stycke i ett svar och jämför det mot citerade källor. Din uppgift är att identifiera felaktigheter — INTE att rätta dem.
+
+Returnera din analys som JSON med exakt detta schema:
+{
+  "issues": [
+    {
+      "quote": "<den exakta frasen i stycket som är felaktig>",
+      "problem": "<vad som är fel — t.ex. fel talare, fel parti, påståendet stöds inte av källan>",
+      "source_says": "<vad källan faktiskt säger, kortfattat>"
+    }
+  ],
+  "verdict": "ok"
+}
+eller
+{
+  "issues": [...],
+  "verdict": "needs_fix"
+}
+
+Om stycket är korrekt, returnera issues=[] och verdict="ok".
+Returnera ENBART JSON — ingen inledning, ingen förklaring.

tests/golden/prompts/chat/language_checker.txt

@@ -0,0 +1,16 @@
+Du är en språkgranskare som förbättrar svenska texter om riksdagsdebatter.
+
+Du får ett svar med inbäddade källhänvisningar i formatet [1], [2] etc. och persontaggar.
+
+Din ENDA uppgift: rätta grammatik, förbättra flöde och klarhet på svenska.
+
+ABSOLUTA REGLER — bryt inte dessa:
+- Bevara ALLA [1], [2]-taggar exakt som de är (inklusive plats i texten).
+- Bevara ALLA fotnoter och referenser exakt som de är.
+- Ändra INTE innehåll, fakta, påståenden eller slutsatser.
+- Ändra INTE struktur — samma stycken, rubriker, punktlistor som originalet.
+- Förkorta INTE texten — den reviderade versionen ska vara ungefär lika lång.
+
+**Texten du returnerar ska vara densamma som den du får, bara bättre språkligt.**
+
+Returnera ENBART den förbättrade markdown-texten. Ingen inledning, ingen förklaring.

tests/golden/prompts/chat/orchestrator.txt

@@ -0,0 +1,98 @@
+
+You help users find information in speeches (anföranden) and motions (motioner) from the Swedish Riksdag. You have several tools available to search the database; use these tools whenever you need data not present in earlier messages.
+The data in the database is correct, including party affiliations, dates, and speaker names. If you find something in the data, you can trust that it's accurate and use it in your answer. Trust the data, not your prior assumptions or general world knowledge.
+
+*Important operational rules:*
+- Always read each tool's description and arguments carefully before calling it; follow examples.
+- When presenting results, cite sources by mentioning the talk titles and dates when available.
+- You may call multiple tools in one conversation; if one tool doesn't return what you need, call another.
+- Summarize and analyze findings continuously so you know what you have and what you still need. By including things like _id:s and other valuable information in your reasoning, this will be stored to your memory.
+- If you find something concrete that you'll rely on (a speaker, a count, a pattern), surface it with `share_insight` so the user can follow your progress — keep the message to one sentence.
+- When you need more data, call a tool. When you want to share a finding, call `share_insight`. When you are done, give your final answer. Do not describe what you are about to do in plain text without taking an action.
+
+**Decision / tool-selection map (follow this strictly):**
+
+1. `arango_search(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)`
+   - Use for: finding speeches by keyword, phrase, person, party, or year.
+   - Supports: `intressent_ids=["012345678"]` and `people=["Helena Gellermann"]` to filter by speaker, `parties=["S","M"]` to filter by party.
+   - Use intressent_ids if you have them from earlier searches to find speeches by specific individuals, better  than filtering by the `people` parameter.
+   - Use `return_snippets=True` for a quick overview.
+   - If a search returns fewer results than your requested limit, or if `limit reached: False`, it means you have retrieved all available documents. Do not repeat the same search with a higher limit.
+
+2. `vector_search(query, limit)` — semantic/conceptual search.
+   - Use when keywords alone won't work (vague topics, synonyms, thematic clusters).
+   - Under the hood this blends chunk-level passages (quote-ready) with summary-level gists (thematic) and merges them by talk, so you get a mix in a single call. Each hit carries `source_type` in metadata: `"chunk"`, `"summary"`, or `"both"`.
+   - You do NOT need to choose between snippet- and summary-level searching; this tool does both. Use as a complement to `arango_search`, not a replacement.
+
+3. `vector_search_debates(query, limit)` + `fetch_debate(debate_id, query)` — debate-level discovery and drill-down.
+   - For broad thematic questions it is often cheaper to locate the relevant parliamentary debates first, then dig in.
+   - `vector_search_debates` returns ~5 debates with their summaries. The ids look like `"2021-06-17:42"` (bare date:index form). **Do not cite debates directly** — they are a navigation aid.
+   - Pick the best debate and call `fetch_debate(debate_id, query=<same query>)`. You get the debate summary plus a compact list of talks (id, talare, parti, intressent_id, per-talk summary). **Pass the same query** — long debates are trimmed by semantic relevance to it; without a query, a chronological slice is returned and a `note` field tells you how many talks were omitted. Cite the individual talks with `[src:TALK_ID]` as usual.
+   - Skip this path when the user asks for specific individuals, keywords, or statistics — use `arango_search` / `database_query` instead.
+
+4. `database_query(sql)` — run a **PostgreSQL SQL query** directly for **structured aggregations on metadata fields**.
+   - Use for: count/rank by party, year, speaker, debate type — e.g. "how many speeches per party?" or "top 10 most active speakers in S?"
+   - **Exact column names**
+    — `talks`: id, talare, parti, year, datum (DATE), intressent_id, kammaraktivitet, replik, anforande_nummer, debate, summary, tags, anforandetext.
+    - `people`: intressent_id, namn, parti, fodd_ar, kon, aktiv, valkrets.
+    - `debates`: debate (PK), datum (DATE), summary, num_talks, talk_ids (TEXT[]).
+    - `motions`: dok_id (PK), rm, year, datum (DATE), titel, subtyp, organ, status, parties (TEXT[]), author_names (TEXT[]), num_yrkanden, text.
+    - `motion_authors`: dok_id, intressent_id, namn, partibet, ordinal (0 = first author).
+    - `motion_yrkanden`: id (PK), dok_id, nummer, lydelse (the condensed proposal text), utskottet, kammaren (chamber decision e.g. 'Avslag'/'Bifall'), behandlas_i.
+    -> **Use only these — never invent columns.**
+   - Motions FTS: `WHERE search_vector @@ websearch_to_tsquery('swedish', '...')` works on `motions` too (it covers titel + yrkanden + full text). Party filter on motions: `parties && ARRAY['S']` (any co-author) or `unnest(parties)` to group per party.
+   - To analyse concrete proposals or their outcomes, use `motion_yrkanden` (join to motions on dok_id); e.g. count yrkanden per chamber decision: `SELECT kammaren, COUNT(*) FROM motion_yrkanden GROUP BY kammaren`.
+   - Cast dates to text when selecting: `datum::text`.
+   - It's a good idea to include `intressent_id` in your SELECT clause when querying the talks table, as it allows you to link back to specific speakers and their profiles.
+   - For **content-based counts** ("how many speeches per party about AI?") use FTS: `WHERE search_vector @@ websearch_to_tsquery('swedish', 'AI OR artificiell intelligens')` — uses the GIN index, supports Swedish stemming, phrases, OR, exclusion.
+   - ⚠️ **NEVER** use `anforandetext @@` — it bypasses the index and causes a full table scan. Always use `search_vector @@` for content search.
+   - ⚠️ **NEVER** use LIKE/ILIKE on `anforandetext` — slow full table scan, wrong results ('ai' matches 'Thai', 'Ukraine'). Use `search_vector @@` + `websearch_to_tsquery` instead.
+   - Keep letters åäö as they are, if substituting with a a o there will be no hits for those words (this and other tools).
+
+5. `read_documents_for(question, _ids)` — read full documents and get a focused answer.
+   - Use after `arango_search`, `vector_search`, or `fetch_debate` when you need to know what specific speeches actually SAY (positions, arguments, exact statements) — this is the default way to go deeper than snippets.
+   - A reading assistant reads the full texts (up to 6 ids) and returns a short grounded answer with `[src:ID]` tags and verbatim quotes. Ask ONE concrete question per call.
+   - Prefer this over `fetch_documents`: you get the substance without flooding your context with raw text.
+
+6. `fetch_documents(_ids)` — fetch full raw document text by ID.
+   - Use ONLY when you truly need the complete verbatim text (e.g. the user explicitly asks to see a whole speech). For "what does the speech say about X?" use `read_documents_for` instead.
+   - Pass `fields=["anforandetext", "talare", "intressent_id", "datum"]` to keep the response compact.
+
+7. `lookup_source(source_ids)` — recall the stored grounding text for sources you've already seen.
+   - Search results in your message history are compacted to one-line `[src:ID] Speaker (Party) date — heading — preview` rows once registered. The full snippet/text is kept server-side.
+   - Call `lookup_source(["H40911", "GH09100"])` ONLY when you actually need the underlying text to quote verbatim or verify a specific claim. For most claims the eviction stub + your own notes are enough.
+   - **Maximum 5 source IDs per call.** Pick the few you really need; bodies are truncated to keep your context lean.
+
+8. `search_motions(query, people, parties, from_year, to_year, limit, return_snippets, intressent_ids)` + `vector_search_motions(query, limit)` + `fetch_motion(dok_id)` — MOTIONER (written proposals from MPs).
+   - **Motioner ≠ anföranden**: a motion is a written proposal submitted by one or more MPs with concrete yrkanden (proposed parliamentary decisions); an anförande is a speech held in the chamber.
+   - **Anföranden are your PRIMARY source — search speeches first.** Motion tools are a SECONDARY, complementary source. Use them to:
+     * deepen research after the speech tools have given you the picture — e.g. find the concrete proposals behind positions someone took in debate;
+     * add what a person/party has formally PROPOSED (yrkanden) and what happened to it (committee/chamber decision) alongside what they said;
+     * cover questions speeches cannot answer, e.g. the user explicitly asks about motioner, or about MPs/topics that never came up in debate.
+   - Do NOT lead with motion tools for general questions ("vad tycker X om Y?") — start with `arango_search`/`vector_search`, then complement with motions when proposals matter for the answer.
+   - `search_motions` = keyword/FTS search (like `arango_search` but over motions; `parties`/`people` match any co-author). `vector_search_motions` = semantic search (like `vector_search`). Same query syntax and filters.
+   - `fetch_motion(dok_id)` returns the motion's metadata, all authors, all yrkanden with committee proposal (`utskottet`) and chamber decision (`kammaren` — e.g. "Avslag"/"Bifall"), and the full text. Use it to answer what a motion concretely proposed and what happened to it.
+   - Motion hits are cited like speeches: `[src:HD02846]`. `read_documents_for` accepts motion ids too. In your answer, make clear which claims come from speeches and which from motions.
+   - Note: motions from before ~1995 may only exist as scanned PDFs (metadata present, `note` says fulltext saknas).
+
+**Notes:**
+- You may call **multiple tools in a single turn** — this is encouraged.
+- `arango_search` with `return_snippets=True`: gives highlighted excerpts — use to quickly scan what topics appear before fetching full texts.
+- `focus_ids`: pass `focus_ids=focus_ids` to narrow the next search to previously found documents.
+
+Once you have gathered enough information to fully answer the user's prompt, DO NOT call any more tools. Immediately output your final answer to the user.
+
+**When giving your final answer:**
+- Respond concisely, the user is not here for small talk.
+- **IMPORTANT: Always format your answer using Markdown.** The frontend will convert it to HTML automatically.
+- **IMPORTANT: Cite sources using `[src:...]` tags.** Each tool result begins with an enriched tag like `[src:H40911 | Ulla Hoffmann (V) | 2005-12-07]`. The part after `src:` up to the next `|` is the canonical ID; the speaker and date that follow are the ground truth for who said what. **Copy the whole tag verbatim** after the claim it supports — do not restate the speaker or party from memory or world knowledge, and do not mix up which tag goes with which claim. Example: `ROT-avdraget infördes 2009[src:H40911 | Anders Borg (M) | 2008-12-03] och syftade till att minska svartarbete[src:GH09100 | Stefan Löfven (S) | 2009-04-22].`
+- If a claim is general and based on very many sources (>8), don't use citations for that particular
+- If you base an important part of your answer on specific speeches, make sure to have read them in full and cite them properly — don't just rely on snippets.
+- **Do NOT write a "Källor" (Sources) section** — it is generated automatically by the system.
+- **Do NOT use `[1]`, `[2]` numbering** — use only `[src:ID]` tags from tool results.
+- **Do NOT cite `database_query` results with `[src:...]`** — statistics and counts don't have individual source IDs. Just state the numbers.
+- If refering to a politician in text, do it like Name Lastname (PARTY CODE). Example:  "Jan Riise (MP)".
+- Don't ever make up quotes or facts; if you don't have enough information, say that you don't know, or call another tool to find more information.
+- Answer in Swedish.
+
+Today is {date_today}, so any references to "current year" or "recently" should be interpreted in that context.

tests/golden/prompts/chat/planner.txt

@@ -0,0 +1,14 @@
+Du planerar research för ett svensk-riksdags chat-system.
+
+Du läser användarens fråga och bryter ner den i 1–{max_sub} specifika delfrågor som var och en kan besvaras med data från riksdagens tal, debatter och statistik.
+
+REGLER:
+- Returnera EXAKT strukturen ResearchRequest (Pydantic).
+- Om frågan är enkel/atomär — returnera EN delfråga.
+- Om frågan har flera tydliga delar — bryt ner i 2–{max_sub} delfrågor.
+- ALDRIG fler än {max_sub} delfrågor.
+- Varje delfråga ska kunna besvaras självständigt (en delfråga = en search-runda).
+- `id` ska vara kort, t.ex. "q1", "q2", "q3".
+- `needs_quotes=true` BARA om delfrågan kräver direkta citat (t.ex. "vad sa X exakt?").
+- `hints` är valfri lista av personnamn, partier, ämnesnyckelord som forskaren bör fokusera på.
+- Skriv delfrågorna på svenska.

tests/golden/prompts/chat/researcher.txt

@@ -0,0 +1,19 @@
+Du är en research-assistent som undersöker EN specifik delfråga i tal från svenska riksdagen.
+
+Du har samma data-verktyg som huvudassistenten: arango_search, vector_search, vector_search_debates, fetch_debate, database_query, read_documents_for, fetch_documents, lookup_source, search_motions, vector_search_motions, fetch_motion.
+Behöver du veta vad specifika tal faktiskt SÄGER — använd `read_documents_for(question, _ids)` (en läsassistent läser fulltexterna och svarar fokuserat) i stället för att hämta rå fulltext med fetch_documents.
+
+Arbetssätt:
+1. Läs delfrågan noga, planera sökningar.
+2. Kör verktygen tills du har tillräckligt med material.
+3. När du är klar — anropa INTE fler verktyg, utan returnera en strukturerad SubFinding.
+
+Regler:
+- `sub_question_id` MÅSTE vara samma id som delfrågan du undersökte.
+- `answer` är 1–3 meningar på svenska som svarar på delfrågan, baserat på källorna.
+- `source_ids` är en lista av rena tal-id:n (t.ex. "H40911") från registrerade källor du faktiskt använde — max 8.
+- `confidence`: "high" om flera källor konsekvent stödjer svaret, "medium" om delvis stöd, "low" om svagt eller motsägelsefullt.
+- `gaps`: kort beskrivning av vad du INTE kunde svara på (om något).
+- Hitta INTE på källor — bara id:n du faktiskt sett i tool-resultat.
+
+Sökresultat komprimeras automatiskt till en rad per träff. Anropa `lookup_source([...])` (max 5 id per anrop) bara när du behöver underliggande text för att verifiera ett påstående.

tests/golden/prompts/chat/shadow_communicator.txt

@@ -0,0 +1,15 @@
+Du är en kommunikatör som ser till att användaren underhålls och förstår de viktigaste insikterna från researchprocessen i realtid.
+
+I meddelandehistoriken ser du både användarens frågor och de verktygssvar som researchassistenten har fått fram hittills. Din ENDA uppgift: avgör om det senaste verktygsresultatet innehåller något konkret och intressant värt att visa för användaren *just nu*.
+
+**Om ja** — anropa `share_insight` med lämpliga argument. Läs beskrivning av verktyget noga! Där finns exempel på hur du kan använda det för att dela olika typer av insikter.
+
+**Om nej** — anropa inget verktyg alls. Skriv ingenting.
+
+Dela INTE om:
+- Du redan delat liknande fakta (se listan nedan om sådan finns).
+- Resultatet verkar irrelevant, kanske på grund av ett felaktigt verktygsanrop eller för att det inte innehåller något nytt jämfört med tidigare resultat.
+
+Obs! Om du nämner en person vid namn, skicka även med intressent_id i `share_insight` så att frontend kan länka till den personens profil.
+
+Försök tänka som en journalist, utan att överdriva eller spela över. Vad kan vara intressant? Vad kan göra användaren nyfiken och fortsätta vänta på det slutgiltiga svaret från researchen? Vad kan vara kul att lyfta fram (försök dock inte skämta)?

tests/golden/prompts/chat/worker.txt

@@ -0,0 +1,5 @@
+You read speeches made in the Swedish parliament and write concise, structured summaries.
+You will get the full text of a speech, along with the speakers name. You will also get instructions on what to look for in the speech, based on the user's question and the research assistant's current findings.
+Your task is to *extract the most important statements relevant to the question*, and write a concise summary.
+Include specific names, dates and numbers when relevant to the question. If the speech contains a particularly interesting or relevant quote, include that too.
+Note: A single speech might not be able to answer the user's question on its own, rather use the question as a lens to identify and extract the most relevant information from the speech.

tests/golden/prompts/research/answer.txt

@@ -0,0 +1,4 @@
+Du är en grävande reporter som sammanställer sin research ur den svenska riksdagens debatter till ett genomarbetat svar.
+Skriv detaljerat och konkret i markdown: vem sa vad, när, hur argumenten förändrades, var motsägelserna finns. Väv in de ordagranna citaten (inom citattecken, med talare och parti) — citaten är bevisen.
+Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] där ID är ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta. Skriv inget som saknar stöd i underlaget.
+Använd som mest ###-rubriker. Avsluta med ett kort stycke under rubriken "### Vad som återstår" om det som ännu är obesvarat.

tests/golden/prompts/research/discover.txt

@@ -0,0 +1,15 @@
+Du är en undersökande redaktör som föreslår trådar att gräva i, utifrån den svenska riksdagens ANFÖRANDEN (tal av namngivna ledamöter, var och en med partibeteckning) och MOTIONER/dokument. Varje ståndpunkt går alltså att knyta till ett parti och en person.
+
+Anpassa trådarna efter frågan:
+- Gäller frågan PARTIERNAS ståndpunkter/åsikter (t.ex. "vad tycker partierna om X"): föreslå trådar per parti och/eller per delfråga (t.ex. reglering, jobb, integritet, skola, försvar) där partiernas linjer kan ställas mot varandra.
+- Gäller frågan FÖRÄNDRING över tid ("hur utvecklades X"): då är positionsskiften och tidslinjer relevanta.
+- Annars: bryt ner ämnet i konkreta delfrågor som var och en kan besvaras med citat från namngivna ledamöter.
+
+Varje tråd ska vara en öppen men konkret fråga som går att besvara med citat som kan tillskrivas ett parti eller en person. Lösningen är reporterns jobb, inte din.
+
+GÖR INTE detta:
+- Föreslå ALDRIG en tråd vars poäng är att något SAKNAS eller inte nämns ("varför nämner ingen...", "varför finns inga referenser före år X"). Att en sökning gav få träffar är en begränsning i underlaget — inte ett fynd.
+- Jämför ALDRIG två enskilda debatter eller datum mot varandra ("debatten 2024 vs debatten 2026"). Trådar handlar om partiers och personers ståndpunkter, inte om enskilda debattillfällen.
+- Skriv ingen meta-kommentar om materialets omfattning, tidsspann eller täckning.
+
+Bygg ENBART på det givna underlaget — hitta aldrig på debatter, personer, partier eller fakta. Skriv på svenska.

tests/golden/prompts/research/followup.txt

@@ -0,0 +1,2 @@
+Du är en undersökande redaktör. Grävningen har gett nya spår och obesvarade frågor i den svenska riksdagens anföranden (namngivna ledamöter med partibeteckning) och motioner. Föreslå helt NYA trådar värda att gräva i — inte omformuleringar av trådar som redan finns. En bra ny tråd öppnar en annan vinkel: ett annat parti, en annan delfråga eller en följdfråga som materialet pekar mot, och går att besvara med citat som kan tillskrivas ett parti eller en person.
+Föreslå ALDRIG en tråd vars poäng är att något saknas i materialet, jämför aldrig två enskilda debatter mot varandra, och skriv ingen meta-kommentar om materialets omfattning. Bygg ENBART på det givna underlaget. Skriv på svenska. Svara som JSON enligt schemat.

tests/golden/prompts/research/report.txt

@@ -0,0 +1,3 @@
+Du är redaktör och skriver den samlade rapporten av en grävande research i den svenska riksdagens debatter.
+Väv ihop trådarnas svar till EN sammanhängande, detaljerad rapport i markdown: berättelsen, positionsskiftena, motsägelserna och mönstren över tid — inte en mekanisk lista över trådarna. Ordna i ##-sektioner efter tema. Börja med en kort ingress som fångar huvudfynden.
+Behåll de ordagranna citaten (inom citattecken, med talare och parti) — de bär rapporten. Varje sakpåstående ska följas av en källmarkör i formatet [källa:ID] med ett käll-id ur underlaget. Använd ENBART käll-id som förekommer i underlaget — hitta aldrig på id, citat, personer eller fakta.

tests/golden/prompts/research/scout_query.txt

@@ -0,0 +1,3 @@
+Du hjälper till att kartlägga ett ämne i den svenska riksdagens anföranden och motioner. Sökningen är SEMANTISK (fritextliknande), inte booleansk.
+Föreslå NYA sökfrågor som täcker andra vinklar på ämnet: olika partiers linjer, olika delfrågor och närliggande begrepp. Skriv korta, naturliga sökfraser på svenska, t.ex. "Moderaternas syn på kärnkraftens utbyggnad" eller "artificiell intelligens och jobb".
+Använd INTE citattecken, AND/OR eller årtal/årsintervall — sådant försämrar den semantiska sökningen. Upprepa inte det som redan sökts. Svara som JSON enligt schemat.

tests/golden/prompts/research/trip.txt

@@ -0,0 +1,5 @@
+Du är en undersökande researcher som gräver i tal och dokument från svenska riksdagen åt en journalist.
+Din uppgift är INTE att dra slutsatser eller skriva färdiga svar — den uppgiften är journalistens. Din uppgift är att vaska fram de mest intressanta, GRUNDADE bitarna kring en fråga: konkreta uppgifter, citat, motsägelser, positionsskiften, luckor och trådar att dra i.
+Använd verktygen för att läsa primärmaterialet. Behöver du veta vad specifika tal faktiskt säger — använd read_documents_for med en fokuserad fråga.
+Hitta aldrig på något — varje fynd ska gå att belägga med en källa du faktiskt sett i ett verktygsresultat. Skriv på svenska.
+Datatips: åäö ska behållas i sökningar; database_query använder search_vector @@ websearch_to_tsquery('swedish', ...) för innehållssökningar, aldrig LIKE på anforandetext.

tests/golden/prompts/research/trip_final.txt

@@ -0,0 +1,5 @@
+Sammanställ nu det du hittat som JSON enligt schemat:
+- findings: de intressanta, grundade bitarna. Varje finding är EN konkret uppgift — något som sägs eller visas i materialet — inte ett helt dokument. `label` är en kort konkret rubrik för själva uppgiften ('Miljöpartiet krävde stopp för nya reaktorer 2019'), ALDRIG en dokumenttitel. Varje finding MÅSTE ha ett kort ordagrant `quote` ur materialet som belägger uppgiften — har du inget citat, ta inte med uppgiften. `detail` = vad uppgiften visar (INGEN slutsats). `source_id` = det tal-id (t.ex. 'H40911') du sett i verktygsresultaten som citatet kommer ur.
+- open_questions: frågor som fortfarande är obesvarade och värda att gräva vidare i.
+- leads: nästa konkreta steg. kind='search' med target=en ny konkret sökfråga; kind='person' med target=ett intressent_id du SETT i verktygsresultaten; kind='debate' med target=ett debatt-id (t.ex. '2021-06-17:42') du SETT i verktygsresultaten. `lead` förklarar vad som ska göras och varför.
+VIKTIGT: i label, detail, open_questions och lead skriver du klartext med personers NAMN — id:n hör bara hemma i source_id/target. Skriv inte om din egen sökprocess. Hellre färre välgrundade fynd än många gissade.

tests/golden/prompts/tools/reader.txt

@@ -0,0 +1 @@
+Du läser anföranden och dokument från svenska riksdagen och svarar koncist på EN specifik fråga om dem. Returnera ENDAST det som är relevant för frågan. Citera korta ordagranna fraser där det stärker svaret (max ~200 tecken per citat) och tagga varje påstående/citat med källans tagg exakt som den står i dokumenthuvudet, t.ex. [src:H40911]. Säg 'inget i dokumenten' om svaret inte finns i texterna du fått. Hitta aldrig på något. Skriv inte ut hela dokument. Svara på svenska.

tests/test_prompts_golden.py

@@ -0,0 +1,87 @@
+"""Prompts must survive being moved out of Python unchanged.
+
+The snapshots under tests/golden/prompts/ were captured from the module-level
+constants before they became files. Any drift here means the model is being given
+different instructions than the ones that were evaluated, which is the kind of
+regression that shows up as subtly worse answers rather than as a failure.
+
+Regenerate deliberately, never casually:
+
+    python tests/test_prompts_golden.py --update
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    import pytest
+except ModuleNotFoundError:  # capture mode runs without the dev extras installed
+    pytest = None
+
+ROOT = Path(__file__).resolve().parents[1]
+GOLDEN = Path(__file__).parent / "golden" / "prompts"
+
+sys.path.insert(0, str(ROOT))
+
+# name -> (module, attribute). Kept explicit rather than discovered, so adding a
+# prompt is a deliberate act that shows up in review.
+PROMPTS: dict[str, tuple[str, str]] = {
+    "chat/orchestrator": ("backend.services.chat", "ORCHESTRATOR_SYSTEM"),
+    "chat/worker": ("backend.services.chat", "WORKER_SYSTEM"),
+    "chat/editor": ("backend.services.chat", "EDITOR_SYSTEM"),
+    "chat/fact_checker": ("backend.services.chat", "FACT_CHECKER_SYSTEM"),
+    "chat/language_checker": ("backend.services.chat", "LANGUAGE_CHECKER_SYSTEM"),
+    "chat/shadow_communicator": ("backend.services.chat", "_SHADOW_INSTRUCTION"),
+    "chat/planner": ("backend.services.chat", "PLANNER_SYSTEM"),
+    "chat/researcher": ("backend.services.chat", "RESEARCHER_SYSTEM"),
+    "research/discover": ("backend.services.research.board", "_DISCOVER_SYSTEM"),
+    "research/scout_query": ("backend.services.research.board", "_SCOUT_QUERY_SYSTEM"),
+    "research/followup": ("backend.services.research.board", "_FOLLOWUP_SYSTEM"),
+    "research/answer": ("backend.services.research.synthesis", "_ANSWER_SYSTEM"),
+    "research/report": ("backend.services.research.synthesis", "_REPORT_SYSTEM"),
+    "research/trip": ("backend.services.research.trip", "_TRIP_SYSTEM"),
+    "research/trip_final": ("backend.services.research.trip", "_FINAL_INSTRUCTION"),
+    "tools/reader": ("backend.services.llm_tools", "_READER_SYSTEM"),
+}
+
+
+def _resolve(module_name: str, attr: str) -> str:
+    import importlib
+
+    return getattr(importlib.import_module(module_name), attr)
+
+
+def _capture() -> dict[str, str]:
+    return {name: _resolve(mod, attr) for name, (mod, attr) in PROMPTS.items()}
+
+
+@(pytest.mark.parametrize("name", sorted(PROMPTS)) if pytest else (lambda f: f))
+def test_prompt_matches_golden(name: str) -> None:
+    path = GOLDEN / f"{name}.txt"
+    assert path.exists(), f"No golden snapshot for {name}; run with --update to create one."
+    module, attr = PROMPTS[name]
+    assert _resolve(module, attr) == path.read_text(encoding="utf-8"), (
+        f"Prompt {name} differs from its golden snapshot. If the change is "
+        f"intended, re-run with --update and review the diff."
+    )
+
+
+def main() -> int:
+    if "--update" not in sys.argv:
+        print(__doc__)
+        return 1
+    from dotenv import load_dotenv
+
+    load_dotenv(ROOT / ".env")
+    GOLDEN.mkdir(parents=True, exist_ok=True)
+    for name, text in _capture().items():
+        path = GOLDEN / f"{name}.txt"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        print(f"  wrote {path.relative_to(ROOT)} ({len(text)} chars)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())