Decision log

Not fully verified against the current code

These are maintained by hand and can drift from the actual code. Check the referenced code before relying on a specific claim.

#	Title	Status	Summary
0001	Agents and tools	Accepted	Generation and retrieval both run through ai_agents; on follow-ups, retrieval is a real tool call the agent's LLM chooses to make, except the first turn, which the module forces directly.
0003	Event subscriber bridge	Accepted	An event-subscriber bridge injects the citation contract and captures tool results without driving the agent loop directly.
0004	Forced index required	Accepted	An agent must have a forced, hidden rag_search index; an LLM-pickable index is a prompt-injection risk.
0005	No-answer guarantee paths	Accepted	The JSON path is deterministic on no sources; the SSE path relies on the citation contract because tokens may already be in flight.
0006	Agent decides freshness	Accepted	The agent itself decides whether to re-retrieve on a follow-up, instead of a separate freshness-check LLM call.
0007	Runner id log correlation	Accepted-stopgap	Log/trace correlation uses a runner UUID set before the run and captured once afterward, until ai_agents exposes caller-supplied tags.
0009	Front-end contracts	Accepted	Blocks are cacheable static shells; markup attributes, CSS scoping, and JS dispatch path are load-bearing contracts.
0011	Citation finalization	Accepted	The Sources list only ever shows what the generated text actually cited, renumbered to close the gaps.
0012	Langfuse trace open timing	Accepted	generate() opens a Langfuse trace best-effort before running the agent, so captureIds() has something to correlate afterward.
0013	Entity cap skips rather than breaks	Accepted	The entity cap skips chunks of new entities past the limit but keeps chunks of already-included entities, instead of stopping the loop outright.
0014	Reference links prefer a configurable field over canonical	Accepted	An optional per-agent field name lets a reference link cite an entity's original external source instead of this site's copy, falling back to canonical when unset.

Template

New ADRs use a MADR-lite format:

# NNNN Title

## Status
Accepted / Accepted-stopgap / Superseded by NNNN

## Context
What forces made a decision necessary.

## Decision
What was decided.

## Consequences
What this makes easier or harder; what it rules out.

Rule

A new architectural choice requires a new ADR added in the same commit as the code that makes it. An ADR with no defended alternative design, that only describes an acknowledged limitation tracked against an upstream fix, belongs in known-gaps.md instead (ADR 0008 was moved there for this reason).