diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e0ff9c3b..2c57bf69 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -51,3 +51,10 @@ jobs:
       - name: Test
         if: ${{ !cancelled() }}
         run: pnpm test
+      # Docs integrity (#102): fail on a dangling docs reference in source or an
+      # unindexed doc. The checker self-tests first, so the gate is itself gated.
+      - name: Docs integrity
+        if: ${{ !cancelled() }}
+        run: |
+          pnpm check:docs:test
+          pnpm check:docs
diff --git a/README.md b/README.md
index 1c3deecc..3a65a504 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,11 @@
 
 Дизайнът и решенията живеят в [`docs/`](docs/) — започнете оттам:
 
+- [`docs/architecture.md`](docs/architecture.md) — преглед на системата и карта към решенията.
+- [`docs/adr/`](docs/adr/README.md) — Architecture Decision Records (по едно решение на файл).
+- [`docs/core-scope.md`](docs/core-scope.md) — доменен модел и речник на данните.
 - [`docs/etl.md`](docs/etl.md) — ETL pipeline-ът и емисията от ЦАИС ЕОП.
 - [`docs/deploy.md`](docs/deploy.md) — деплой към Cloudflare.
-- [`docs/architecture.md`](docs/architecture.md) — архитектурни решения (ADR).
 - [`docs/spec/ai-assistant.md`](docs/spec/ai-assistant.md) — спецификация на AI асистента (планиран).
 - [`docs/README.md`](docs/README.md) — **пълен индекс** на документацията, вкл. достъпност и стандартите за ревю.
 
diff --git a/apps/web/app/routes/contract.tsx b/apps/web/app/routes/contract.tsx
index 344060af..bddb9119 100644
--- a/apps/web/app/routes/contract.tsx
+++ b/apps/web/app/routes/contract.tsx
@@ -306,7 +306,7 @@ export default function Contract({ loaderData }: Route.ComponentProps) {
                     <span className="muted">не е посочен в данните</span>
                   ),
                 // Break the gross count down by status/category — surfaces what „Брой оферти" actually
-                // means (it's the gross submitted count, including rejections — see docs/etl-pipeline.md
+                // means (it's the gross submitted count, including rejections — see docs/etl.md
                 // and the staging columns at packages/db/migrations/0000_init.sql:363-365). Each clause
                 // only appears when the source published a non-zero value, so contracts without any
                 // rejection/SME data fall back to the original „самите оферти…" footnote.
diff --git a/docs/README.md b/docs/README.md
index 278e4ffe..568550ad 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,12 +2,20 @@
 
 Дизайнът, решенията и спецификациите на платформата за прозрачност на обществените поръчки живеят тук. За преглед на продукта и бърз старт вижте [`README.md`](../README.md) в корена; работните конвенции са в [`AGENTS.md`](../AGENTS.md).
 
-- [`architecture.md`](architecture.md) — архитектурните решения: рендериране (React Router v7 SSR на Workers), сигурност и достъп до D1.
+- [`architecture.md`](architecture.md) — преглед на системата (поток на данните, двата Worker-а) и карта към решенията.
+- [`adr/`](adr/README.md) — Architecture Decision Records: по едно архитектурно решение на файл, с индекс и шаблон.
+- [`core-scope.md`](core-scope.md) — доменният модел и **речникът на данните**: таблици, rollup-и, `value_flag`/`date_flag`, семантиката на `amount_eur`.
 - [`etl.md`](etl.md) — ETL pipeline-ът и open-data емисията на ЦАИС ЕОП (`storage.eop.bg`): зареждане, опресняване и производни таблици.
+- [`etl-pipeline-state.md`](etl-pipeline-state.md) — анализ на текущото състояние на ETL pipeline-а.
+- [`etl-architecture.md`](etl-architecture.md) — целевата ETL архитектура (RFC): предложение за състоянието и реда на изпълнение.
+- [`v1-implementation-plan.md`](v1-implementation-plan.md) — precompute слоят и пагинацията (защо rollup-и и keyset вместо per-request GROUP BY / OFFSET).
+- [`integrity-gate.md`](integrity-gate.md) — reconciliation gate-ът: hard asserts върху тоталите при import/CI.
+- [`anomaly-report.md`](anomaly-report.md) — cross-row аномалии при опресняване: какво `value_flag` не хваща на ниво отделен договор.
 - [`deploy.md`](deploy.md) — деплой към Cloudflare: двата Worker-а (`sigma`, `sigma-etl`) и споделеният D1 per environment.
 - [`api.md`](api.md) — публичните данни и машинно четими endpoint-и (CSV/JSON/sitemap), query грамата на филтрите и лицензът — за разработчици, които строят върху данните.
 - [`accessibility.md`](accessibility.md) — достъпност (WCAG 2.1 AA / EN 301 549): какво покрива платформата и наблюденията за вградената приставка за достъпност.
 - [`spec/ai-assistant.md`](spec/ai-assistant.md) — спецификация на разговорния аналитичен слой над СИГМА (BgGPT, текст и глас).
+- [`spec/assistant-contracts.md`](spec/assistant-contracts.md) — контрактите BE↔FE за AI асистента (Фаза 1 → Фаза 2).
 
 ## Стандарти за ревю
 
diff --git a/docs/adr/0001-rendering-and-security.md b/docs/adr/0001-rendering-and-security.md
new file mode 100644
index 00000000..e251f26a
--- /dev/null
+++ b/docs/adr/0001-rendering-and-security.md
@@ -0,0 +1,81 @@
+# ADR-0001 — Стратегия за рендиране на front-end-а и модел на сигурност
+
+- **Статус:** Прието
+- **Дата:** 2026-05-21
+- **Обхват:** Итерация 1 — публичният, read-only explorer на обществените поръчки (АОП). Документът отбелязва и пътя напред към по-широката платформа (оценка на риска, аномалии, картелен анализ — roadmap).
+
+> **Актуализация (2026-05-21):** Решението за фреймуърк по-долу беше променено от SvelteKit на **React Router v7 върху Cloudflare Workers** след претегляне на екосистемата, набирането на хора и контрибутори, primitives за достъпност и екосистемата за визуализации/AI. Решенията за рендиране (§2) и за сигурност (§3) са независими от фреймуърка и остават непроменени; обновени бяха само техните специфични за фреймуърка механики.
+
+## Контекст
+
+Итерация 1 е **публичен, read-only** отчетен и визуализационен слой върху ~190 хил. реда договори от АОП в Cloudflare D1, насочен към граждани, журналисти и НПО, с интерфейс на български. Уеб приложението първоначално беше скелетирано върху **SvelteKit**; този ADR преразглежда този избор. Сървърната среда е **Cloudflare Workers**, които четат D1. Данните пристигат като **периодични bulk зареждания** (`scripts/import.mjs`), а не като жива емисия; в тази итерация **няма публичен write път и няма автентикация**.
+
+Три въпроса стояха в основата на решението:
+
+1. Трябва ли front-end-ът да премине от Svelte към React?
+2. Трябва ли страниците да се рендират на сървъра (SSR), да се пре-рендират (статично), или да са класическо клиентско SPA срещу API?
+3. Променят ли отговора атаките през SSR / „hydration“?
+
+## Решение
+
+### 1. React с React Router v7 (framework mode) върху Cloudflare Workers
+
+Избран пред първоначалния SvelteKit скелет след претегляне на дълготрайните фактори:
+
+- **Екосистема и преизползване** — най-голямата екосистема от компоненти/библиотеки и най-богатите опции точно за повърхностите, върху които СИГМА стъпва: мрежови графи на връзки (`@xyflow/react`), таблици за големи данни (TanStack Table / AG Grid), графики (visx / Recharts), а за по-късния асистент — AI SDK (`@ai-sdk/react`) и зрели UI-та за асистенти.
+- **Набиране на хора и open-source контрибутори** — значително по-голям talent pool; релевантно за вероятно OSS гражданска платформа („Лицензът ще бъде определен преди публичното пускане“).
+- **Primitives за достъпност** — React Aria / Radix са сред най-добрите в класа си за изричната цел **WCAG 2.2 AA**.
+- **Дълготрайност** — най-защитимият дългосрочен избор за дълголетна платформа от обществена полза.
+
+**React Router v7 (framework mode), а не Next.js** — той върви чисто върху **Cloudflare Workers** (през `@cloudflare/vite-plugin`) и запазва модела SSR-на-edge и хибридното рендиране от §2. Приети компромиси спрямо SvelteKit: по-голям клиентски runtime (смекчен от SSR + кеширане) и липса на first-party CF *Pages* адаптер — RR7 се деплойва като Worker, което освен това уеднаквява `apps/web` с останалите `apps/*`.
+
+### 2. Рендиране: хибридно, избрано според повърхността
+
+По подразбиране **SSR + edge кеширане**; пре-рендиране само за реално статичните страници; клиентско рендиране само за интерактивните „острови“. **Не** чисто SPA за публично съдържание (SEO/споделяемост + цена на първото изрисуване); **не** build-time пре-рендиране на целия корпус (десетки хиляди страници за компании/институции, а търсенето изобщо не може да се пре-рендира).
+
+| Повърхност | Стратегия | Защо |
+| --- | --- | --- |
+| Начало, За проекта, **методология / „как работят червените флагове“**, документация за отворените данни | Пре-рендиране (статично) | Рядко се променят → надеждно + безплатно |
+| Профил на компания (по ЕИК), страница на институция, детайл на поръчка/обособена позиция | **SSR + edge кеш** (`s-maxage` + `stale-while-revalidate`), purge при презареждане на набора данни | Голям обем, променя се само при bulk презареждане → скорост като при статика + устойчивост на DDoS, актуалност след презареждане |
+| Explorer: търсене / филтри / класации („най-големи бенефициенти“) | SSR, кратък кеш, варира според заявката | Безкрайно URL пространство; задвижван от SQL |
+| Интерактивни визуализации (граф на мрежа/потоци, карта на България, сортируеми таблици) | Клиентски рендиран **остров**, хидриран върху SSR-ната страница + първоначални данни | Нуждае се от клиентска интерактивност; SSR на обвивката заради SEO/първо изрисуване |
+
+Тъй като наборът данни е периодична снимка (а не жив), кеш TTL-ите може да са дълги, а едно презареждане просто **purge-ва** кеша — почти всички предимства на статиката, без да се изброява корпусът при build.
+
+### 3. Модел на сигурност
+
+Приоритети за публичен сайт за прозрачност: **интегритет ≈ наличност ≫ конфиденциалност** — данните са публични по дизайн; тяхната *достоверност* и *uptime* са продуктът.
+
+**Контроли в итерация 1:**
+
+- **Read път да остане read-only.** Ingestion-ът е офлайн (`scripts/import.mjs`); няма публичен write endpoint. Това се запазва — без публична мутация, без админ в итерация 1.
+- **Edge модел + кеширане като поглъщане на DDoS.** Cloudflare поглъща L3/4; кешираният HTML означава, че атакуващ / scrape трафик удря кеша, а не D1.
+- **WAF + rate limiting** върху задвижвания от SQL explorer/търсене и върху всеки export на отворени данни; ограничаване на `limit` / пагинация / размер на export-а, така че нито една заявка да не сканира цялата таблица.
+- **Строг CSP + security headers** — генериране на per-request nonce в `entry.server.tsx`, подаван към `<Scripts nonce>` / `<ScrollRestoration nonce>` на React Router и към header-а `Content-Security-Policy` (за да са разрешени hydration скриптовете на фреймуърка без `unsafe-inline`). Добавяне на HSTS, `X-Content-Type-Options`, `Referrer-Policy`.
+- **D1 prepared statements само с bound параметри**; никога конкатениране на SQL чрез низове.
+
+**По въпроса за „hydration атаките“** — реалните класове и как този дизайн ги адресира:
+
+- **Изтичане между потребители през кеширан персонализиран SSR** — неприложимо в итерация 1 (без автентикация; всяка страница е анонимна и идентична → безопасна за кеширане). Остава предотвратено и по-късно, като се кешират *само* анонимни публични страници и никога автентикираните.
+- **Свръх-сериализиране на тайни в hydration payload-а** — смекчено чрез типизираните response DTO-та в `packages/api-contract` (отдават проекции на същностите, никога сурови редове) и чрез държане на код, носещ credentials, извън уеб/read пътя. DTO-тата да остават без вътрешни-само полета.
+- **XSS през сериализирано състояние / рендирани данни** — разчита се на авто-escaping-а на React/JSX; **никога `dangerouslySetInnerHTML`** върху текст от АОП (институция / компания / предмет са от външен източник); строгият CSP е резервната защита.
+
+**Отложено за по-късни фази** (повърхностите на по-широката платформа):
+
+- **Workflow-и за възложители/участници + админ** → Cloudflare Access (SSO + MFA) за админ; строго разделяне на публичен/персонализиран кеш; изолация на write пътя в отделен worker.
+- **AI асистент за обществени поръчки** → маршрутизиране през **AI Gateway** (лимити за rate/разход, кеширане, логване); read-only, параметризирани инструменти; заземяване на всяко твърдение в изчислени данни (риск от клевета); никакво кеширане; рендиране на изхода като текст. Спецификация — [`spec/ai-assistant.md`](../spec/ai-assistant.md).
+
+## Последствия / scaffold follow-up-и
+
+- Конфигуриране на пре-рендирането в `react-router.config.ts` (`prerender` пътища) за статичните информационни route-ове.
+- Задаване на `Cache-Control` (`s-maxage` + `stale-while-revalidate`) през `headers` export-ите на route-овете при SSR data route-овете; иницииране на cache purge (по URL/таг) в края на скрипта за зареждане на данните.
+- Задаване на CSP + security headers в `entry.server.tsx` (или Worker middleware) с per-request nonce върху `<Scripts>`.
+- Добавяне на Cloudflare rate-limit правило + WAF managed ruleset за explorer/export endpoint-ите (infra конфигурация, проследявана отделно).
+- Премахване или auth-gate на отворения `POST /etl/run` от скелета в `apps/etl` преди какъвто и да е деплой.
+
+## Свързани документи
+
+- [`etl.md`](../etl.md) — ETL pipeline-ът и емисията от ЦАИС ЕОП.
+- [`deploy.md`](../deploy.md) — деплой към Cloudflare и оперативна сигурност.
+- [`spec/ai-assistant.md`](../spec/ai-assistant.md) — спецификация на планирания AI асистент.
+- [`README.md`](../../README.md) на хранилището и [`AGENTS.md`](../../AGENTS.md) — общ преглед и работни конвенции.
diff --git a/docs/adr/0002-d1-as-datastore.md b/docs/adr/0002-d1-as-datastore.md
new file mode 100644
index 00000000..1678c308
--- /dev/null
+++ b/docs/adr/0002-d1-as-datastore.md
@@ -0,0 +1,29 @@
+# ADR-0002 — Cloudflare D1 като обслужващо хранилище
+
+- **Статус:** Прието
+- **Дата:** 2026-06-30 (записано със задна дата)
+- **Обхват:** Итерация 1 — обслужваната база за explorer-а и ETL-а.
+
+## Контекст
+
+Данните пристигат като **периодични bulk зареждания** от ЦАИС ЕОП, не като жива емисия; v1 е
+публичен, read-only слой без write път. Изпълнението е на **Cloudflare Workers** на edge.
+Търси се хранилище, което: е колокирано с Workers (нисък latency без отделен DB слой), има
+релационни/SQL семантики за класациите и join-овете, и е евтино за read-heavy публичен трафик.
+
+## Решение
+
+Ползваме **Cloudflare D1** (SQLite на edge) като единствено обслужвано хранилище — **един D1 на
+среда**, споделян от двата Worker-а: `sigma` чете, `sigma-etl` пише (виж [`deploy.md`](../deploy.md)).
+Схемата е **консолидиран baseline** ([`0000_init.sql`](../../packages/db/migrations/0000_init.sql)) плюс
+тънки добавъчни миграции (напр. `0001_flow_pairs_bidder_index.sql`), а не верига от самото начало —
+v1 е pre-production и всеки импорт стартира от свежа база; пълна верига инкрементални миграции се
+въвежда чак когато има деплойнати данни, които не може да се загубят.
+
+## Последствия
+
+- **D1 таксува прочетените редове, не върнатите** — това директно мотивира precompute слоя и
+  keyset пагинацията (виж [`v1-implementation-plan.md`](../v1-implementation-plan.md)).
+- FK се налагат от D1 → пълните ребилди трият в child→parent ред; `normalize-raw.sql` се изпълнява
+  като един атомарен batch (явен `BEGIN/COMMIT` се отхвърля), така че провален run се отменя.
+- Rollback на refresh се прави на ниво слот, не на ниво ред (виж [ADR-0005](0005-blue-green-d1-rollback.md)).
diff --git a/docs/adr/0003-value-flag-data-quality.md b/docs/adr/0003-value-flag-data-quality.md
new file mode 100644
index 00000000..0c98b1f8
--- /dev/null
+++ b/docs/adr/0003-value-flag-data-quality.md
@@ -0,0 +1,34 @@
+# ADR-0003 — Verdict за качество на данните (`value_flag` / `date_flag`) и единна стойностна база
+
+- **Статус:** Прието
+- **Дата:** 2026-06-30 (записано със задна дата)
+- **Обхват:** Итерация 1 — `contracts` и всички сумирани повърхности.
+
+## Контекст
+
+Изходните стойности от регистъра са шумни: подозрителни анекси, нереалистични суми, договори,
+подписани преди публикуване. На **министерски-видим** сайт мълчаливото сумиране на боклук е
+недопустимо, но и мълчаливото изтриване на редове крие данни. Нужен е **недеструктивен verdict**:
+редовете остават видими, но проблемните се изключват от тоталите по едно ясно правило.
+
+## Решение
+
+Всеки договор носи `value_flag` (`ok` | `review` | `value_low` | `value_suspect` | `annex_suspect`)
+и `date_flag` (`ok` | `signed_after_publication`). Каноничната сумирана колона е **`amount_eur`** —
+попълнена за **всичките пет** флага (`value_suspect` се repair-ва до процедурната оценка,
+`annex_suspect` пада към `signing`/`current`). Оттук — едно правило за всички суми:
+
+> Сумирай само `amount_eur` с предиката `amount_eur IS NOT NULL` — единната стойностна база за
+> rollup-ите и за страниците. `amount_eur` е `NULL` (и така изключен) само когато няма надеждна EUR
+> стойност: чуждовалутен ред без покрит ECB курс, `value_suspect` без процедурна оценка, или ред без
+> `signing`/`current` стойност.
+
+`home_totals.suspect` е отделен KPI — брой на `value_suspect` редовете, които сами се сумират — а не
+множеството, изключено от сумите. Пълната семантика е в [`core-scope.md`](../core-scope.md).
+
+## Последствия
+
+- Всяка нова заявка/страница, която сумира, трябва да ползва същия предикат — иначе rollup ↔ страница
+  се разминават. Това е merge-блокер по точност.
+- [`integrity-gate.md`](../integrity-gate.md) налага инварианта като hard assert на import/CI.
+- `annex_suspect` е частичен случай: брои се в `amount_eur`, но `current_value_eur` се потиска.
diff --git a/docs/adr/0004-style-src-unsafe-inline.md b/docs/adr/0004-style-src-unsafe-inline.md
new file mode 100644
index 00000000..002dd6a8
--- /dev/null
+++ b/docs/adr/0004-style-src-unsafe-inline.md
@@ -0,0 +1,26 @@
+# ADR-0004 — `style-src` запазва `'unsafe-inline'` (CSP)
+
+- **Статус:** Прието
+- **Дата:** 2026-06-30 (записано със задна дата)
+- **Обхват:** Итерация 1 — CSP в [`apps/web/app/lib/security.ts`](../../apps/web/app/lib/security.ts). Свързано с #11 (follow-up от security-audit PR #6).
+
+## Контекст
+
+`script-src` вече е строг: per-request nonce за некешираната SSR и per-script SHA-256 hash-ове за
+edge-кеширания HTML (`workers/app.ts`) — без `'unsafe-inline'`. `style-src` обаче пази
+`'unsafe-inline'`, защото приложението слага inline `style={…}` атрибути за динамични стойности.
+
+Ключов факт: **CSP nonce се прилага към `<style>`/`<script>` _елементи_, не към inline `style=`
+_атрибути_.** Затова единственият начин да падне `'unsafe-inline'` от `style-src` е SSR HTML-ът да
+съдържа **нула** inline `style=` атрибута.
+
+## Решение
+
+Запазваме `'unsafe-inline'` в `style-src` засега. Понеже днес няма HTML-injection sink (текстът от
+АОП се escape-ва от React, никога `dangerouslySetInnerHTML`), това е **defense-in-depth с нисък
+приоритет**, а не активна дупка.
+
+## Последствия
+
+- Проследено като follow-up: премахване на inline `style=` атрибутите → сваляне на `'unsafe-inline'`.
+- Не е merge-блокер; преразглежда се, когато динамичните стилове минат към класове/CSS променливи.
diff --git a/docs/adr/0005-blue-green-d1-rollback.md b/docs/adr/0005-blue-green-d1-rollback.md
new file mode 100644
index 00000000..805fb91f
--- /dev/null
+++ b/docs/adr/0005-blue-green-d1-rollback.md
@@ -0,0 +1,25 @@
+# ADR-0005 — Blue/green D1 слотове за rollback на refresh
+
+- **Статус:** Прието
+- **Дата:** 2026-06-30 (записано със задна дата)
+- **Обхват:** Итерация 1 — деплой и опресняване на данните. Пълна механика в [`deploy.md`](../deploy.md).
+
+## Контекст
+
+Опресняването презарежда обслужваната база. Reseed-ът на D1 е деструктивен — ако refresh внесе
+повредени данни от източника, трябва да има **бърз rollback без downtime**. Едновременно с това
+имената на ресурсите трябва да са независими от средата (същото дърво с код се деплойва към prod,
+staging, втори акаунт).
+
+## Решение
+
+Поддържат се **два постоянни D1 слота** (blue/green) и **указател** (секрет/binding), който сочи
+кой слот е „на живо". Refresh-ът пише в **празния** слот; при успех указателят се **флипва** към
+него. Rollback = флип обратно към предишния слот. Идентично за staging и prod — затова **името на
+слота спира да има значение**: два стабилни етикета + указател.
+
+## Последствия
+
+- ~2× storage за обслужваните данни (двата слота).
+- Промоцията/rollback-ът са атомарни на ниво указател, не миграция на редове.
+- Rollback drill-ът и „как да проверя последния успешен refresh" са оперативни runbook-ове (#104).
diff --git a/docs/adr/0006-eop-wins-dedup.md b/docs/adr/0006-eop-wins-dedup.md
new file mode 100644
index 00000000..9f77c9bb
--- /dev/null
+++ b/docs/adr/0006-eop-wins-dedup.md
@@ -0,0 +1,26 @@
+# ADR-0006 — Dedup на два източника: EOP печели по `contract_number`
+
+- **Статус:** Прието
+- **Дата:** 2026-06-30 (записано със задна дата)
+- **Обхват:** Итерация 1 — `scripts/normalize-raw.sql` (стъпка 5), нормализация на договорите.
+
+## Контекст
+
+Договорите идват от **два** feed-а: EOP open-data емисията (`eop:%`) е авторитетната база за
+2020–2026, а OCDS JSON feed-ът (`ocds:%`) е go-forward делтата за нови данни от 2026 г. нататък.
+OCDS **препубликува** договори, които вече са в EOP → застъпване. Нужен е детерминистичен dedup,
+който не дублира при OCDS go-live catch-up.
+
+## Решение
+
+Dedup по **`contract_number`** — номерът на договора, общ за двата feed-а (OCDS държи своя `ocid`
+в `unp`, който никога не съвпада с формата на EOP УНП, затова `contract_number` е cross-source
+ключът). **EOP печели**: OCDS договор се взема само когато **нито един** EOP ред не споделя неговия
+`contract_number`. Истински новите OCDS договори се добавят. УНП без tenders-export ред получава
+синтетичен `неизвестна` tender (стъпка 2b), за да има всеки договор родител.
+
+## Последствия
+
+- OCDS go-live catch-up е безопасен, дори да препубликува вече заредени договори.
+- `idx_contracts_cnum` поддържа dedup-а при дневния refresh.
+- `data_freshness` записва границата „данни към" per feed (`admin` / `ocds`).
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 00000000..600cc7a6
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,16 @@
+# Architecture Decision Records
+
+Архитектурните решения на СИГМА се записват тук като **ADR** — по едно решение на файл, така че
+контекстът да не се губи в код-коментари и PR-и. Новите решения се добавят със следващия пореден
+номер; приетите не се пренаписват — заменят се с нов ADR със статус „Заменено от ADR-MMMM".
+
+Нов ADR: копирай [`_template.md`](_template.md), вземи следващия номер, добави ред в таблицата долу.
+
+| # | Решение | Статус |
+| --- | --- | --- |
+| [0001](0001-rendering-and-security.md) | Стратегия за рендиране (React Router v7 на Workers) и модел на сигурност | Прието |
+| [0002](0002-d1-as-datastore.md) | Cloudflare D1 като обслужващо хранилище | Прието |
+| [0003](0003-value-flag-data-quality.md) | `value_flag`/`date_flag` verdict + единна стойностна база | Прието |
+| [0004](0004-style-src-unsafe-inline.md) | `style-src` запазва `'unsafe-inline'` (CSP) | Прието |
+| [0005](0005-blue-green-d1-rollback.md) | Blue/green D1 слотове за rollback на refresh | Прието |
+| [0006](0006-eop-wins-dedup.md) | Dedup на два източника: EOP печели по `contract_number` | Прието |
diff --git a/docs/adr/_template.md b/docs/adr/_template.md
new file mode 100644
index 00000000..86c0adb1
--- /dev/null
+++ b/docs/adr/_template.md
@@ -0,0 +1,18 @@
+# ADR-NNNN — <заглавие на решението>
+
+- **Статус:** Предложено | Прието | Заменено от ADR-MMMM | Оттеглено
+- **Дата:** YYYY-MM-DD
+- **Обхват:** <коя итерация / коя повърхност засяга>
+
+## Контекст
+
+<Какъв беше проблемът или въпросът. Силите в действие — ограничения, алтернативи, нефункционални
+изисквания. Достатъчно, за да се разбере решението без външен контекст.>
+
+## Решение
+
+<Какво решихме, в сегашно време („Ползваме X"). Ако има отхвърлени алтернативи — защо.>
+
+## Последствия
+
+<Какво следва — положително и отрицателно. Приети компромиси. Follow-up задачи, ако има.>
diff --git a/docs/architecture.md b/docs/architecture.md
index d5c2de34..ab598c09 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,80 +1,52 @@
-# ADR-0001 — Стратегия за рендиране на front-end-а и модел на сигурност
+# Архитектура
 
-- **Статус:** Прието
-- **Обхват:** Итерация 1 — публичният, read-only explorer на обществените поръчки (АОП). Документът отбелязва и пътя напред към по-широката платформа (оценка на риска, аномалии, картелен анализ — roadmap).
+Преглед на системата на едно място и указател към записаните решения. **Архитектурните решения
+живеят като ADR в [`adr/`](adr/README.md)** — този файл е картата, не източникът на истина за
+отделните решения.
 
-> **Актуализация (2026-05-21):** Решението за фреймуърк по-долу беше променено от SvelteKit на **React Router v7 върху Cloudflare Workers** след претегляне на екосистемата, набирането на хора и контрибутори, primitives за достъпност и екосистемата за визуализации/AI. Решенията за рендиране (§2) и за сигурност (§3) са независими от фреймуърка и остават непроменени; обновени бяха само техните специфични за фреймуърка механики.
+## Поток на данните
 
-## Контекст
+```
+ЦАИС ЕОП (storage.eop.bg)  ──bulk/cron──▶  sigma-etl (Worker + Workflow)
+                                                │  load → normalize → derive → precompute
+                                                ▼
+                                          D1 (една база на среда)
+                                                ▲
+                                                │  read-only
+                          граждани / журналисти ──▶  sigma (RR v7 SSR Worker)
+```
 
-Итерация 1 е **публичен, read-only** отчетен и визуализационен слой върху ~129 хил. реда договори от АОП в Cloudflare D1, насочен към граждани, журналисти и НПО, с интерфейс на български. Уеб приложението първоначално беше скелетирано върху **SvelteKit**; този ADR преразглежда този избор. Сървърната среда е **Cloudflare Workers**, които четат D1. Данните пристигат като **периодични bulk зареждания** (`scripts/import.mjs`), а не като жива емисия; в тази итерация **няма публичен write път и няма автентикация**.
+Данните пристигат като **периодични bulk зареждания**, не като жива емисия. ETL-ът пише в D1; explorer-ът
+чете от **същия** D1. В v1 няма публичен write път и няма автентикация.
 
-Три въпроса стояха в основата на решението:
+## Двата Worker-а
 
-1. Трябва ли front-end-ът да премине от Svelte към React?
-2. Трябва ли страниците да се рендират на сървъра (SSR), да се пре-рендират (статично), или да са класическо клиентско SPA срещу API?
-3. Променят ли отговора атаките през SSR / „hydration“?
+| Worker     | Роля                                                              |
+| ---------- | ----------------------------------------------------------------- |
+| `sigma`    | SSR explorer (`apps/web`) — чете D1 директно, edge-кешира HTML.    |
+| `sigma-etl`| cron-задействан refresh Workflow (`apps/etl`) — пише в D1.         |
 
-## Решение
+## Рендиране и сигурност (резюме)
 
-### 1. React с React Router v7 (framework mode) върху Cloudflare Workers
+- **Рендиране:** хибридно според повърхността — пре-рендиране за статичните страници, SSR + edge
+  кеш за обемните детайлни/explorer страници, клиентски „острови" за интерактивните визуализации.
+- **Сигурност:** приоритет интегритет ≈ наличност ≫ конфиденциалност (данните са публични). Read
+  пътят остава read-only; строг CSP + security headers; D1 само с bound параметри.
 
-Избран пред първоначалния SvelteKit скелет след претегляне на дълготрайните фактори:
+Пълната обосновка и приетите компромиси — [ADR-0001](adr/0001-rendering-and-security.md).
 
-- **Екосистема и преизползване** — най-голямата екосистема от компоненти/библиотеки и най-богатите опции точно за повърхностите, върху които СИГМА стъпва: мрежови графи на връзки (`@xyflow/react`), таблици за големи данни (TanStack Table / AG Grid), графики (visx / Recharts), а за по-късния асистент — AI SDK (`@ai-sdk/react`) и зрели UI-та за асистенти.
-- **Набиране на хора и open-source контрибутори** — значително по-голям talent pool; релевантно за вероятно OSS гражданска платформа („Лицензът ще бъде определен преди публичното пускане“).
-- **Primitives за достъпност** — React Aria / Radix са сред най-добрите в класа си за изричната цел **WCAG 2.2 AA**.
-- **Дълготрайност** — най-защитимият дългосрочен избор за дълголетна платформа от обществена полза.
+## Решения (ADR)
 
-**React Router v7 (framework mode), а не Next.js** — той върви чисто върху **Cloudflare Workers** (през `@cloudflare/vite-plugin`) и запазва модела SSR-на-edge и хибридното рендиране от §2. Приети компромиси спрямо SvelteKit: по-голям клиентски runtime (смекчен от SSR + кеширане) и липса на first-party CF *Pages* адаптер — RR7 се деплойва като Worker, което освен това уеднаквява `apps/web` с останалите `apps/*`.
+Виж индекса в [`adr/README.md`](adr/README.md). Ключовите за v1: рендиране/сигурност (0001),
+D1 като хранилище (0002), `value_flag` стойностна база (0003), CSP `style-src` (0004), blue/green
+rollback (0005), dedup на двата източника (0006).
 
-### 2. Рендиране: хибридно, избрано според повърхността
+## Справочни документи
 
-По подразбиране **SSR + edge кеширане**; пре-рендиране само за реално статичните страници; клиентско рендиране само за интерактивните „острови“. **Не** чисто SPA за публично съдържание (SEO/споделяемост + цена на първото изрисуване); **не** build-time пре-рендиране на целия корпус (десетки хиляди страници за компании/институции, а търсенето изобщо не може да се пре-рендира).
-
-| Повърхност | Стратегия | Защо |
-| --- | --- | --- |
-| Начало, За проекта, **методология / „как работят червените флагове“**, документация за отворените данни | Пре-рендиране (статично) | Рядко се променят → надеждно + безплатно |
-| Профил на компания (по ЕИК), страница на институция, детайл на поръчка/обособена позиция | **SSR + edge кеш** (`s-maxage` + `stale-while-revalidate`), purge при презареждане на набора данни | Голям обем, променя се само при bulk презареждане → скорост като при статика + устойчивост на DDoS, актуалност след презареждане |
-| Explorer: търсене / филтри / класации („най-големи бенефициенти“) | SSR, кратък кеш, варира според заявката | Безкрайно URL пространство; задвижван от SQL |
-| Интерактивни визуализации (граф на мрежа/потоци, карта на България, сортируеми таблици) | Клиентски рендиран **остров**, хидриран върху SSR-ната страница + първоначални данни | Нуждае се от клиентска интерактивност; SSR на обвивката заради SEO/първо изрисуване |
-
-Тъй като наборът данни е периодична снимка (а не жив), кеш TTL-ите може да са дълги, а едно презареждане просто **purge-ва** кеша — почти всички предимства на статиката, без да се изброява корпусът при build.
-
-### 3. Модел на сигурност
-
-Приоритети за публичен сайт за прозрачност: **интегритет ≈ наличност ≫ конфиденциалност** — данните са публични по дизайн; тяхната *достоверност* и *uptime* са продуктът.
-
-**Контроли в итерация 1:**
-
-- **Read път да остане read-only.** Ingestion-ът е офлайн (`scripts/import.mjs`); няма публичен write endpoint. Това се запазва — без публична мутация, без админ в итерация 1.
-- **Edge модел + кеширане като поглъщане на DDoS.** Cloudflare поглъща L3/4; кешираният HTML означава, че атакуващ / scrape трафик удря кеша, а не D1.
-- **WAF + rate limiting** върху задвижвания от SQL explorer/търсене и върху всеки export на отворени данни; ограничаване на `limit` / пагинация / размер на export-а, така че нито една заявка да не сканира цялата таблица.
-- **Строг CSP + security headers** — генериране на per-request nonce в `entry.server.tsx`, подаван към `<Scripts nonce>` / `<ScrollRestoration nonce>` на React Router и към header-а `Content-Security-Policy` (за да са разрешени hydration скриптовете на фреймуърка без `unsafe-inline`). Добавяне на HSTS, `X-Content-Type-Options`, `Referrer-Policy`.
-- **D1 prepared statements само с bound параметри**; никога конкатениране на SQL чрез низове.
-
-**По въпроса за „hydration атаките“** — реалните класове и как този дизайн ги адресира:
-
-- **Изтичане между потребители през кеширан персонализиран SSR** — неприложимо в итерация 1 (без автентикация; всяка страница е анонимна и идентична → безопасна за кеширане). Остава предотвратено и по-късно, като се кешират *само* анонимни публични страници и никога автентикираните.
-- **Свръх-сериализиране на тайни в hydration payload-а** — смекчено чрез типизираните response DTO-та в `packages/api-contract` (отдават проекции на същностите, никога сурови редове) и чрез държане на код, носещ credentials, извън уеб/read пътя. DTO-тата да остават без вътрешни-само полета.
-- **XSS през сериализирано състояние / рендирани данни** — разчита се на авто-escaping-а на React/JSX; **никога `dangerouslySetInnerHTML`** върху текст от АОП (институция / компания / предмет са от външен източник); строгият CSP е резервната защита.
-
-**Отложено за по-късни фази** (повърхностите на по-широката платформа):
-
-- **Workflow-и за възложители/участници + админ** → Cloudflare Access (SSO + MFA) за админ; строго разделяне на публичен/персонализиран кеш; изолация на write пътя в отделен worker.
-- **AI асистент за обществени поръчки** → маршрутизиране през **AI Gateway** (лимити за rate/разход, кеширане, логване); read-only, параметризирани инструменти; заземяване на всяко твърдение в изчислени данни (риск от клевета); никакво кеширане; рендиране на изхода като текст. Спецификация — [`spec/ai-assistant.md`](spec/ai-assistant.md).
-
-## Последствия / scaffold follow-up-и
-
-- Конфигуриране на пре-рендирането в `react-router.config.ts` (`prerender` пътища) за статичните информационни route-ове.
-- Задаване на `Cache-Control` (`s-maxage` + `stale-while-revalidate`) през `headers` export-ите на route-овете при SSR data route-овете; иницииране на cache purge (по URL/таг) в края на скрипта за зареждане на данните.
-- Задаване на CSP + security headers в `entry.server.tsx` (или Worker middleware) с per-request nonce върху `<Scripts>`.
-- Добавяне на Cloudflare rate-limit правило + WAF managed ruleset за explorer/export endpoint-ите (infra конфигурация, проследявана отделно).
-- Премахване или auth-gate на отворения `POST /etl/run` от скелета в `apps/etl` преди какъвто и да е деплой.
-
-## Свързани документи
-
-- [`etl.md`](etl.md) — ETL pipeline-ът и емисията от ЦАИС ЕОП.
-- [`deploy.md`](deploy.md) — деплой към Cloudflare и оперативна сигурност.
-- [`spec/ai-assistant.md`](spec/ai-assistant.md) — спецификация на планирания AI асистент.
-- [`README.md`](../README.md) на репозиторието и [`../AGENTS.md`](../AGENTS.md) — общ преглед и работни конвенции.
+- [`core-scope.md`](core-scope.md) — доменен модел и речник на данните.
+- [`etl.md`](etl.md) — ETL pipeline и емисията от ЦАИС ЕОП.
+- [`v1-implementation-plan.md`](v1-implementation-plan.md) — precompute слой и пагинация.
+- [`integrity-gate.md`](integrity-gate.md) — reconciliation gate (hard asserts върху тоталите).
+- [`deploy.md`](deploy.md) — деплой към Cloudflare.
+- [`accessibility.md`](accessibility.md) — достъпност (WCAG 2.1 AA).
+- [`spec/ai-assistant.md`](spec/ai-assistant.md) — спецификация на AI асистента (планиран).
diff --git a/docs/core-scope.md b/docs/core-scope.md
new file mode 100644
index 00000000..ccf892fa
--- /dev/null
+++ b/docs/core-scope.md
@@ -0,0 +1,139 @@
+# Основен обхват и речник на данните
+
+Този документ описва **доменния модел на v1** — кои същности съществуват, как се
+ключират и как се почиства стойността — и служи като **речник на данните**: бизнес-значението
+на всяка domain таблица, на rollup-ите и на изброимите полета (`value_flag`, `date_flag`),
+плюс семантиката на `amount_eur`.
+
+Каноничната дефиниция на схемата е [`packages/db/migrations/0000_init.sql`](../packages/db/migrations/0000_init.sql) —
+тук е обяснено _какво означават_ колоните, не как са декларирани. За процеса на зареждане и
+почистване виж [`etl.md`](etl.md); за решенията зад модела — [`adr/`](adr/README.md).
+
+## Обхват на v1
+
+Публичен, read-only справочник върху три същности и връзките им:
+
+- **Институция** (`authorities`) — възложителят, ключ ЕИК.
+- **Компания** (`bidders`) — получателят (печелившият участник), ключ ЕИК.
+- **Договор** (`contracts`) — сключеният договор, който свързва институция и компания.
+
+Около тях: `tenders` (поръчката/процедурата) и `lots` (обособени позиции) дават контекст;
+`amendments` пази историята на анексите; `parties` е проекция на OCDS данните за обогатяване
+по ЕИК. **Няма `bids` таблица** — нито един източник не публикува офертите ред по ред, само
+агрегиран брой (`contracts.bids_received`), затова таблица за оферти не се въвежда, докато не
+се появи източник на ниво оферта.
+
+## Конвенция за идентификатори
+
+Всички PK са текстови с префикс на типа, за да са глобално уникални и четими в URL/лог:
+
+| Същност    | `id`                            | Естествен ключ        |
+| ---------- | ------------------------------- | --------------------- |
+| authorities | `auth:` + ЕИК                  | ЕИК на възложителя    |
+| tenders    | `t:` + УНП                      | УНП (ЦАИС ЕОП)        |
+| lots       | `lot:` + УНП + `:` + lot_id     | (УНП, lot_id)         |
+| bidders    | `eik:` + ЕИК, иначе `name:` + нормализирано име | ЕИК, иначе името |
+| contracts  | `c:e:`/`c:o:` + композит (УНП, contract_number, lot, bidder) | (УНП, contract_number) при dedup |
+
+`bidders` се ключира по ЕИК, когато е валиден; иначе по нормализирано име — затова различни
+фирми, споделящи едно име без ЕИК, се сливат, а това е известен компромис (виж `is_consortium`).
+
+## Стойностна база — `amount_eur` и флаговете
+
+Това е **единната база за всички суми** и най-честият капан при ревю. Едно правило:
+
+> **Сумирай само `amount_eur`, с предиката `amount_eur IS NOT NULL` — това е единната база за
+> rollup-ите и за страниците.** `amount_eur` е попълнена за **всичките пет** флага (`value_suspect`
+> и `annex_suspect` минават през repair/fallback, не се нулират); `NULL` е само когато няма надеждна
+> EUR стойност (виж по-долу), и точно тези `NULL` редове са изключени от сумите.
+
+### `contracts.value_flag` — verdict за качеството на стойността
+
+`TEXT NOT NULL DEFAULT 'ok'`. **Пет стойности**; присвояват се в [`normalize-raw.sql`](../scripts/normalize-raw.sql).
+И петте се сумират (`amount_eur` е попълнена) — освен в NULL-случаите, изброени под таблицата:
+
+| Стойност        | Значение                                                                                       | `amount_eur`               |
+| --------------- | ---------------------------------------------------------------------------------------------- | -------------------------- |
+| `ok`            | Стойността е приета.                                                                            | реалната EUR стойност      |
+| `review`        | ≥10× процедурната оценка — задържан, но маркиран.                                               | реалната EUR стойност      |
+| `value_low`     | Нула/отрицателна, или дребна (<1000 EUR **и** <5% от оценката) — задържан, но маркиран.         | реалната EUR стойност      |
+| `value_suspect` | >2 млрд. EUR, или >200× оценката (при оценка ≥1000 EUR) — **repair-ва се до процедурната оценка**. | процедурната оценка в EUR  |
+| `annex_suspect` | Анекс е вдигнал стойността ≥100× или до отрицателна — пада към `signing`/`current`.             | `signing`/`current` в EUR  |
+
+> **Кога `amount_eur` е `NULL`** (и редът е изключен от сумите): когато няма надеждна EUR стойност —
+> чуждовалутен ред без покрит ECB курс (липсва latest-prior rate до 10 дни преди подписването),
+> `value_suspect` без процедурна оценка за fallback, или ред без никаква `signing`/`current` стойност.
+> Това **не** е „флаг = `value_suspect`" — точно затова FX-безкурсовите редове не се бъркат с
+> подозрителните в KPI-то `suspect`.
+
+### `contracts.date_flag` — verdict за качеството на датата
+
+`TEXT NOT NULL DEFAULT 'ok'`. Недеструктивен (не нулира стойност):
+
+| Стойност                   | Значение                                       |
+| -------------------------- | ---------------------------------------------- |
+| `ok`                       | Датите са консистентни.                        |
+| `signed_after_publication` | Подписан след публикуване — изнесено, не скрито. |
+
+### Свързаните EUR полета
+
+- `amount` / `currency` — display стойността _както е записана_, в оригиналната валута: за
+  `value_suspect` това е процедурната оценка, за `annex_suspect` — `signing`/`current` fallback, иначе `current` (или `signing`).
+- `amount_eur` — канонична EUR, **безопасна за сумиране**; `NULL` само в случаите, изброени по-горе.
+- `fx_converted` (`0/1`) — `1`, ако редът е чуждовалутен (≠ BGN/EUR) и `amount_eur` идва от пазарен курс.
+- `fx_rate` — EUR за 1 единица `currency` (`amount × fx_rate = amount_eur`); latest-prior ECB курс ≤10 дни преди подписването.
+- `signing_value_eur` — `signing_value` в EUR; `NULL` за `value_suspect` (и когато `signing` липсва).
+- `current_value_eur` — `current_value` в EUR; `NULL` за `value_suspect`/`annex_suspect` (и когато `current` липсва).
+
+Валутата **не** се коерцира в staging — пази се per ред (BGN преди 2026, EUR от 2026, няколко
+чужди). Преобразуването в EUR става само в domain слоя срещу `fx_rates` (ECB reference rates).
+
+## Domain таблици
+
+| Таблица      | Грен (един ред =)            | Бизнес-роля                                                       |
+| ------------ | ---------------------------- | ---------------------------------------------------------------- |
+| `authorities` | възложител                  | Институцията; локацията (`nuts`/`settlement`/`address`) се пълни от OCDS, `NULL` дотогава. |
+| `tenders`    | поръчка (УНП)                | Процедурата. `procedure_type = 'неизвестна'` за синтетичните (само-договор) tender-и. |
+| `lots`       | обособена позиция            | Под-единица на поръчка.                                          |
+| `bidders`    | участник/фирма               | Получателят. `is_consortium`/`kind` за ДЗЗД/обединения; `ownership_kind` за публична собственост. |
+| `contracts`  | сключен договор              | Връзката институция→фирма + стойност, флагове, FX, анекс-броячи. |
+| `amendments` | анекс                        | История на промените в стойността; natural-keyed → идемпотентен re-import. |
+| `parties`    | OCDS party проекция (по ЕИК) | Обогатяване (адрес/контакт/NUTS) по ЕИК; не се чете директно от UI. |
+
+## Rollups — какво чете explorer-ът вместо per-request GROUP BY
+
+D1 таксува **прочетени** редове, затова класациите/началото/потоците четат предварително
+сметнати таблици вместо да агрегират 190 хил. договора при всяка заявка (виж
+[`v1-implementation-plan.md`](v1-implementation-plan.md) „Precompute layer"). Сумите
+(`won_eur`/`spent_eur`/`value_eur`) минават през `amount_eur IS NOT NULL`; но `home_totals.contracts`
+и `facet_counts.contracts` са `COUNT(*)` върху целия корпус (record count, не броячът зад сумата).
+
+| Rollup            | Грен                  | Захранва                                  |
+| ----------------- | --------------------- | ----------------------------------------- |
+| `home_totals`     | един ред (`id = 1`)   | KPI на началото; `suspect` = брой на `value_suspect` редовете (data-quality KPI; сумират се при налична процедурна оценка). |
+| `company_totals`  | фирма                 | Класация компании, headline на профила.   |
+| `authority_totals`| институция            | Класация институции, headline.            |
+| `sector_totals`   | CPV дивизия           | Sector facet + филтър-броячи.             |
+| `facet_counts`    | (facet, key)          | Броячи за филтрите (year/procedure/eu).   |
+| `flow_pairs`      | (институция, фирма)   | Sankey на потоците + таблицата.           |
+| `search_index`    | FTS5 ред              | Глобално търсене (Кирилица+Латиница, accent/case-folded). |
+
+`home_totals.contracts` е `COUNT(*)` върху целия корпус (всички договори), а `home_totals.value_eur`
+е `SUM(amount_eur)` само върху чистите редове — двете **не** покриват едно и също множество
+(`contracts` е headline record count). За `company_totals`/`authority_totals` броят и сумата **да**
+покриват едно множество — и двете под `amount_eur IS NOT NULL`.
+
+## Сектори (CPV дивизия)
+
+Секторът на договора е неговата **CPV дивизия** — първите 2 цифри от 8-цифрения CPV код.
+CPV (Reg. (EC) No 213/2008) се влага строго отляво надясно, така че 2-цифрената дивизия е
+детерминистична, каталожно-заземена таксономия — без евристики по име/ключови думи. Таксономията
+и featured („curated") секторите живеят в [`packages/config`](../packages/config/src/index.ts)
+(`CPV_SECTORS`); `sector_totals` се join-ва по дивизия. Двата featured сектора са **45
+Строителство** и **15 Храни**.
+
+## Справочни таблици
+
+- `fx_rates` — ECB euro reference rates (`ecb:frankfurter`) за чуждовалутни дати на подписване.
+- `nuts_regions` — NUTS класификация за BG (28 области → 6 NUTS2 → 2 NUTS1); етикетира кодовете от OCDS.
+- `data_freshness` — „данни към" per feed (`admin` / `ocds`): последната реална дата на договор + брой редове.
diff --git a/docs/v1-implementation-plan.md b/docs/v1-implementation-plan.md
new file mode 100644
index 00000000..5141e4e4
--- /dev/null
+++ b/docs/v1-implementation-plan.md
@@ -0,0 +1,44 @@
+# v1 — модел на изпълнение (precompute + пагинация)
+
+Дизайн-бележки за двете решения, които правят explorer-а бърз и евтин върху D1 без жив бекенд:
+**precompute слоят** (защо четем rollup-и вместо да агрегираме на всяка заявка) и **пагинацията**
+(защо keyset, а не `OFFSET`). И двете са продиктувани от един факт: **D1 таксува прочетените
+редове, не върнатите** — затова всяка повърхност, която иначе би сканирала 190 хил. договора, е
+или предсметната, или ограничена по индекс.
+
+За пълния доменен модел и rollup грановете виж [`core-scope.md`](core-scope.md); за схемата —
+[`packages/db/migrations/0000_init.sql`](../packages/db/migrations/0000_init.sql).
+
+## Precompute layer
+
+Класациите, началната страница, потоците (flows) и sector facet-ите четат **read-optimised
+rollup таблици** (`home_totals`, `company_totals`, `authority_totals`, `sector_totals`,
+`facet_counts`, `flow_pairs`, `search_index`) вместо per-request `GROUP BY` върху договори × join-ове.
+
+- **Кой пише.** [`scripts/precompute.sql`](../scripts/precompute.sql) — пълен ребилд след
+  `normalize-raw.sql`; на дневния Workflow — scoped re-derive само върху докоснатото множество.
+- **Какво заместват.** Едно агрегиране върху ~190 хил. реда на заявка → едно четене от
+  предсметнат ред. На министерски-видим сайт това е и цена, и предвидим latency.
+- **Каноничност на стойността.** Всички суми в rollup-ите минават през `amount_eur IS NOT NULL`,
+  т.е. покриват същото множество като страниците (виж [`core-scope.md`](core-scope.md)). Това е
+  инвариантът, който [`integrity-gate.md`](integrity-gate.md) налага като hard assert.
+- **Кое НЕ е предсметнато.** Детайлните страници (профил на фирма/институция, договор) **скопират
+  `GROUP BY` до една същност** — малък, индексиран обхват — затова не им трябва rollup.
+
+## Pagination
+
+Списъчните страници (договори, фирми, институции) пагинират с **keyset (cursor) пагинация**, не
+с `OFFSET`.
+
+- **Защо не `OFFSET`.** `LIMIT n OFFSET k` кара D1 да прочете (и таксува) `k + n` реда, за да
+  върне `n` — page-jump-ове дълбоко в корпуса стават все по-скъпи и по-бавни. Keyset чете само
+  страницата.
+- **Как.** Курсорът е (sort-стойност, tiebreak id); следващата страница е `WHERE (sort, id) >`/`<`
+  курсора `LIMIT n`. Сортирането по стойност ползва покриващите индекси
+  `idx_contracts_value_desc` / `idx_contracts_value_asc` (върху `COALESCE(amount_eur, …)`, така че
+  редовете с `NULL` `amount_eur` сортират детерминистично в края), а keyset по стойност —
+  `idx_contracts_amount_eur`.
+- **Следствие за UI.** Тоталът за „страница N от M" идва от отделен `COUNT(*)` върху (малкия) rollup
+  на всяка заявка; `pageCursors` дава скоковете по страница, а `filterSignature` инвалидира курсора
+  при смяна на филтрите. Несъответствие между показаната последна страница и курсора е било реален
+  bug (виж #87).
diff --git a/package.json b/package.json
index ba5f2abb..29473a34 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,8 @@
     "typecheck": "turbo run typecheck",
     "test": "turbo run test",
     "lint": "prettier --check .",
+    "check:docs": "node scripts/check-docs.mjs",
+    "check:docs:test": "node --test scripts/check-docs.test.mjs",
     "format": "prettier --write .",
     "setup": "node scripts/setup.mjs",
     "import": "node scripts/import.mjs",
diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts
index a60c443d..483dd008 100644
--- a/packages/config/src/index.ts
+++ b/packages/config/src/index.ts
@@ -8,7 +8,7 @@
 //
 // Coverage verified against the local corpus (May 2026): every one of the 45 divisions below is
 // present, together covering 190,422 contracts / 50.8 bn EUR. The two `curated` divisions — 45
-// Строителство and 15 Храни — are the featured sectors. See docs/mock-coverage.md.
+// Строителство and 15 Храни — are the featured sectors. See docs/core-scope.md § Сектори.
 
 export interface CpvSector {
   /** 2-digit CPV division code. */
diff --git a/packages/db/migrations/0000_init.sql b/packages/db/migrations/0000_init.sql
index 13fb9d80..0888ef93 100644
--- a/packages/db/migrations/0000_init.sql
+++ b/packages/db/migrations/0000_init.sql
@@ -8,7 +8,7 @@
 -- then ship-domain copies the served tables into the served D1 and runs precompute on it).
 --
 -- Modelling rationale (cleaning policy, value_flag, consortium model, canonical EUR + FX, the
--- synthetic-tender rule) lives in docs/etl-pipeline.md and docs/core-scope.md.
+-- synthetic-tender rule) lives in docs/etl.md and docs/core-scope.md.
 --
 -- Layout: (1) domain tables the explorer reads (+ amendments history + the OCDS parties projection),
 -- (1b) rollups + FTS search, (3) fx_rates / nuts_regions / data_freshness reference, (4) indexes.
@@ -123,9 +123,9 @@ CREATE TABLE contracts (
   bids_received    INTEGER,
   contract_kind    TEXT,                   -- Доставки / Услуги / Строителство
   awarded_to_group INTEGER,                -- this AWARD went to an обединение (per-contract, distinct from bidders.is_consortium)
-  value_flag       TEXT NOT NULL DEFAULT 'ok',  -- ok | review | annex_suspect | value_suspect (data-quality verdict)
+  value_flag       TEXT NOT NULL DEFAULT 'ok',  -- ok | review | value_low | value_suspect | annex_suspect (data-quality verdict; assigned in scripts/normalize-raw.sql)
   date_flag        TEXT NOT NULL DEFAULT 'ok',  -- ok | signed_after_publication (non-destructive date-quality verdict)
-  amount_eur       REAL,                   -- canonical EUR, SAFE TO SUM; NULL = excluded (value_suspect)
+  amount_eur       REAL,                   -- canonical EUR, SAFE TO SUM; populated for all flags (value_suspect repaired to the procedure estimate); NULL only when no trustworthy EUR figure (FX-rateless foreign / value_suspect w/o estimate / no signing+current)
   fx_converted     INTEGER NOT NULL DEFAULT 0,  -- 1 = amount_eur came from a foreign-currency market rate
   fx_rate          REAL,                   -- EUR per 1 unit of `currency` for foreign rows (amount × fx_rate = amount_eur)
   signing_value_eur REAL,                  -- signing_value in EUR (peg/fx); NULL for value_suspect — for the contract value timeline
@@ -198,11 +198,11 @@ CREATE INDEX idx_parties_eik ON parties(eik);
 -- One row (id = 1). Index KPIs + freshness for the home page.
 CREATE TABLE home_totals (
   id           INTEGER PRIMARY KEY CHECK (id = 1),
-  contracts    INTEGER NOT NULL,          -- contracts with a clean (non-NULL) amount_eur
-  value_eur    REAL NOT NULL,             -- SUM(amount_eur) over those same rows (count/sum cover one set)
+  contracts    INTEGER NOT NULL,          -- corpus record count: COUNT(*) over ALL contracts (precompute.sql), NOT the clean-amount_eur count behind value_eur
+  value_eur    REAL NOT NULL,             -- SUM(amount_eur), clean rows only; paired with the (larger) corpus contracts count — the two do NOT cover one set
   authorities  INTEGER NOT NULL,
   bidders      INTEGER NOT NULL,
-  suspect      INTEGER NOT NULL,          -- value_suspect rows (NULL amount_eur): surfaced, never summed
+  suspect      INTEGER NOT NULL,          -- COUNT of value_suspect rows (data-quality KPI); summed via repair to the procedure estimate, except a value_suspect row with no estimate (amount_eur NULL, excluded like other NULL rows)
   first_date   TEXT,
   last_date    TEXT,
   as_of        TEXT,                       -- data_freshness 'admin' as_of (latest real contract date)
diff --git a/packages/shared/src/format.ts b/packages/shared/src/format.ts
index d9c0ad86..6c7d16e1 100644
--- a/packages/shared/src/format.ts
+++ b/packages/shared/src/format.ts
@@ -162,7 +162,7 @@ export function unp(value: string | null | undefined): string {
  *
  * `null` is the explicit „nothing-to-show" signal so the renderer can skip the whole block instead
  * of emitting an empty heading. Resolving each member name → ЕИК is parked on the Trade Register
- * backfill (docs/etl-pipeline.md § Multi-source); until that lands the caller stamps every
+ * backfill (docs/core-scope.md — parked Trade Register pipeline); until that lands the caller stamps every
  * participant with `ЕИК неустановен`.
  */
 export type ConsortiumMembership =
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
new file mode 100644
index 00000000..2b19d80e
--- /dev/null
+++ b/scripts/check-docs.mjs
@@ -0,0 +1,165 @@
+// Docs integrity gate (#102). Two asserts, mirroring the philosophy of
+// scripts/integrity-checks.mjs: don't just print — fail CI on drift.
+//
+//   1. No dangling refs. Every repo-root-relative `docs/<path>.md` mentioned in
+//      source (code comments, README, the docs themselves) must resolve to a
+//      real file. Refs inside a URL/longer path are ignored, and test files
+//      (*.test.*) are skipped — their doc-shaped strings are fixtures, not refs.
+//   2. No orphan docs. Every `docs/**/*.md` must be reachable from the docs index
+//      (docs/README.md), or — for ADRs — from docs/adr/README.md. Keeps the
+//      index honest so a new doc can't land unlinked.
+//
+// The scanning/matching logic is pure (strings + path lists) and is exercised
+// adversarially by scripts/check-docs.test.mjs; main() wires it to the real repo
+// and exits non-zero on the first violation kind found.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Where source-level doc references can live. Excludes node_modules, build
+// output and the lockfile by construction (we never descend into them).
+const SCAN_ROOTS = [
+  'README.md',
+  'AGENTS.md',
+  'CONTRIBUTING.md',
+  'docs',
+  'packages',
+  'apps',
+  'scripts',
+];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.turbo', '.wrangler']);
+const TEXT_EXT = /\.(md|ts|tsx|js|mjs|cjs|jsx|sql|json|yml|yaml)$/;
+const DOCS_REF = /\bdocs\/[A-Za-z0-9_./-]+\.md\b/g;
+// Inline `](path.md)`, with optional `#anchor` and optional `"title"`.
+const MD_LINK = /\]\(\s*([^)\s#]+\.md)(?:#[^)\s]*)?(?:\s+"[^"]*")?\s*\)/g;
+// Reference-style definition `[label]: path.md`.
+const MD_REF_LINK = /^\s*\[[^\]]+\]:\s*([^\s#]+\.md)/gm;
+
+// ── pure helpers (unit-tested in check-docs.test.mjs) ──────────────────────────
+
+/** `true` for a markdown doc path. Non-.md files under docs/ (schemas, fixtures) are not docs. */
+export function isMarkdown(path) {
+  return path.endsWith('.md');
+}
+
+/** `true` for a test/spec file — excluded from the ref scan (its doc paths are fixtures). */
+export function isTestFile(path) {
+  return /\.(test|spec)\.[mc]?[jt]sx?$/.test(path);
+}
+
+/** `true` iff this module is the entry point — URL-safe (percent-encoded paths, spaces, non-ASCII). */
+export function isMain(importMetaUrl, argvPath) {
+  return Boolean(argvPath) && importMetaUrl === pathToFileURL(argvPath).href;
+}
+
+/**
+ * Root-relative `docs/<path>.md` refs in a blob of text. Excludes any occurrence
+ * that is a segment inside a URL or a longer path (immediately preceded by `/`):
+ * a ref we validate is repo-root-relative, so it is never preceded by `/`.
+ */
+export function extractDocsRefs(text) {
+  const refs = [];
+  for (const m of text.matchAll(DOCS_REF)) {
+    if (m.index > 0 && text[m.index - 1] === '/') continue; // URL / non-root path segment
+    refs.push(m[0]);
+  }
+  return refs;
+}
+
+/**
+ * Repo-internal markdown link targets in an index file's text; external URLs skipped.
+ * Handles inline links (incl. `#anchor` and `"title"`) and reference-style definitions,
+ * so a doc linked in any of those forms is not miscounted as an orphan.
+ */
+export function linkTargets(text) {
+  const targets = [];
+  for (const re of [MD_LINK, MD_REF_LINK]) {
+    for (const m of text.matchAll(re)) {
+      if (/^(https?:)?\/\//.test(m[1])) continue; // external
+      targets.push(m[1]);
+    }
+  }
+  return targets;
+}
+
+/** Docs not reachable from an index and not explicitly exempt. */
+export function computeOrphans(mdDocs, indexed, exempt) {
+  return mdDocs.filter((p) => !exempt.has(p) && !indexed.has(p));
+}
+
+// ── fs wiring ──────────────────────────────────────────────────────────────────
+
+function walk(abs, out = []) {
+  if (!existsSync(abs)) return out;
+  const st = statSync(abs);
+  if (st.isFile()) {
+    if (TEXT_EXT.test(abs)) out.push(abs);
+    return out;
+  }
+  for (const entry of readdirSync(abs)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    walk(join(abs, entry), out);
+  }
+  return out;
+}
+
+// Markdown link targets of an index file, resolved to repo-relative doc paths.
+function linkedFrom(indexAbs) {
+  const dir = dirname(indexAbs);
+  const linked = new Set();
+  for (const target of linkTargets(readFileSync(indexAbs, 'utf8'))) {
+    linked.add(relative(ROOT, resolve(dir, target)));
+  }
+  return linked;
+}
+
+export function findDanglingRefs(files) {
+  const dangling = [];
+  for (const abs of files) {
+    for (const ref of extractDocsRefs(readFileSync(abs, 'utf8'))) {
+      if (!existsSync(join(ROOT, ref))) {
+        dangling.push({ file: relative(ROOT, abs), ref });
+      }
+    }
+  }
+  return dangling;
+}
+
+export function findOrphanDocs() {
+  const docsRoot = join(ROOT, 'docs');
+  const allDocs = walk(docsRoot)
+    .map((abs) => relative(ROOT, abs))
+    .filter(isMarkdown); // only markdown is a "doc" that must be indexed
+  const indexed = new Set();
+  const topIndex = join(docsRoot, 'README.md');
+  const adrIndex = join(docsRoot, 'adr', 'README.md');
+  if (existsSync(topIndex)) for (const p of linkedFrom(topIndex)) indexed.add(p);
+  if (existsSync(adrIndex)) for (const p of linkedFrom(adrIndex)) indexed.add(p);
+
+  // The index files themselves and the ADR template are reachable by definition.
+  const exempt = new Set(['docs/README.md', 'docs/adr/README.md', 'docs/adr/_template.md']);
+  return computeOrphans(allDocs, indexed, exempt);
+}
+
+function main() {
+  const files = SCAN_ROOTS.flatMap((r) => walk(join(ROOT, r))).filter((abs) => !isTestFile(abs));
+  const dangling = findDanglingRefs(files);
+  const orphans = findOrphanDocs();
+
+  for (const d of dangling) console.error(`dangling docs ref: ${d.ref} (in ${d.file})`);
+  for (const o of orphans)
+    console.error(`orphan doc (not linked from docs/README.md or docs/adr/README.md): ${o}`);
+
+  if (dangling.length || orphans.length) {
+    console.error(
+      `\ncheck-docs: ${dangling.length} dangling ref(s), ${orphans.length} orphan doc(s).`,
+    );
+    process.exit(1);
+  }
+  console.log('check-docs: ok — all docs refs resolve and every doc is indexed.');
+}
+
+if (isMain(import.meta.url, process.argv[1])) main();
diff --git a/scripts/check-docs.test.mjs b/scripts/check-docs.test.mjs
new file mode 100644
index 00000000..12961014
--- /dev/null
+++ b/scripts/check-docs.test.mjs
@@ -0,0 +1,88 @@
+// Adversarial unit tests for the docs-integrity gate. These exist because the
+// gate shipped with three edge-case bugs a happy-path run could not surface
+// (PR #182 review): a URL false-positive, a non-.md false-positive, and a
+// main-module guard that silently no-oped on encoded paths. Each is pinned here.
+//
+// Run: node --test scripts/check-docs.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { pathToFileURL } from 'node:url';
+import {
+  extractDocsRefs,
+  linkTargets,
+  isMarkdown,
+  isTestFile,
+  computeOrphans,
+  isMain,
+} from './check-docs.mjs';
+
+test('extractDocsRefs finds root-relative docs refs', () => {
+  assert.deepEqual(extractDocsRefs('see docs/etl.md and docs/adr/README.md.'), [
+    'docs/etl.md',
+    'docs/adr/README.md',
+  ]);
+});
+
+test('extractDocsRefs ignores docs/*.md inside an external URL (finding #2)', () => {
+  const text = 'ref https://github.com/other/repo/blob/main/docs/foo.md end';
+  assert.deepEqual(extractDocsRefs(text), []);
+});
+
+test('extractDocsRefs ignores a non-root path segment', () => {
+  assert.deepEqual(extractDocsRefs('packages/x/docs/y.md'), []);
+});
+
+test('extractDocsRefs does not false-match .markdown', () => {
+  assert.deepEqual(extractDocsRefs('see docs/etl.markdown'), []);
+});
+
+test('linkTargets keeps internal links (inline, anchored, titled, reference-style) and skips external URLs', () => {
+  const text = [
+    '[a](core-scope.md) [b](https://x.dev/y/z.md) [c](adr/README.md#top)',
+    '[d](etl.md "ETL doc")',
+    '[ref]: v1-implementation-plan.md',
+  ].join('\n');
+  assert.deepEqual(linkTargets(text).sort(), [
+    'adr/README.md',
+    'core-scope.md',
+    'etl.md',
+    'v1-implementation-plan.md',
+  ]);
+});
+
+test('isMarkdown rejects non-.md files that live under docs/ (finding #1)', () => {
+  assert.equal(isMarkdown('docs/spec/contracts.md'), true);
+  assert.equal(isMarkdown('docs/spec/schema.json'), false);
+  assert.equal(isMarkdown('docs/fixtures/sample.yaml'), false);
+});
+
+test('isTestFile matches test/spec files so their fixture paths are not scanned as refs', () => {
+  assert.equal(isTestFile('scripts/check-docs.test.mjs'), true);
+  assert.equal(isTestFile('apps/web/app/lib/riskLogic.test.ts'), true);
+  assert.equal(isTestFile('packages/x/foo.spec.tsx'), true);
+  assert.equal(isTestFile('scripts/check-docs.mjs'), false);
+  assert.equal(isTestFile('docs/core-scope.md'), false);
+});
+
+test('computeOrphans excludes indexed and exempt docs', () => {
+  const orphans = computeOrphans(
+    ['docs/a.md', 'docs/b.md', 'docs/README.md'],
+    new Set(['docs/a.md']),
+    new Set(['docs/README.md']),
+  );
+  assert.deepEqual(orphans, ['docs/b.md']);
+});
+
+test('isMain is robust to a checkout path with a space (finding #3)', () => {
+  const argv = '/tmp/a b/scripts/check-docs.mjs';
+  const url = pathToFileURL(argv).href; // file:///tmp/a%20b/scripts/check-docs.mjs
+  assert.equal(isMain(url, argv), true);
+  // the old idiom `file://${argv}` would have produced an unencoded, mismatching string
+  assert.notEqual(url, `file://${argv}`);
+});
+
+test('isMain is false when imported (argv points elsewhere) and safe when argv is undefined', () => {
+  assert.equal(isMain('file:///a/check-docs.mjs', '/a/some-test.mjs'), false);
+  assert.equal(isMain('file:///a/check-docs.mjs', undefined), false);
+});
diff --git a/scripts/normalize-raw.sql b/scripts/normalize-raw.sql
index 2bdb9e25..17cad66e 100644
--- a/scripts/normalize-raw.sql
+++ b/scripts/normalize-raw.sql
@@ -3,7 +3,7 @@
 -- (+ scripts/derive-amendments.sql for current_value/annex_count) have populated staging:
 --   (cd apps/web && wrangler d1 execute sigma --local --file ../../scripts/normalize-raw.sql)
 --
--- SOURCE MODEL (see docs/etl-pipeline.md): the EOP open-data feed is the authoritative base for
+-- SOURCE MODEL (see docs/etl.md): the EOP open-data feed is the authoritative base for
 -- 2020-2026 (raw_contracts + raw_tenders, source 'eop:%'). The OCDS JSON feed is the
 -- go-forward delta for new 2026+ data (source 'ocds:%'); its rows carry their procedure fields on
 -- the contract row, so they flow through here automatically and a UNP with no tenders-export row