feat(v0.8.5): add run_special.py — special runner with configurable start date

- scripts/run_special.py: new standalone runner for evolution reports and
  comparison matrices starting from a configurable date (--start YYYY-MM,
  default: 2025-07). Start date is used as year label in filenames
  (e.g. evolutie-care-2025-07-nl_...md) and output follows normal per-pillar
  folder structure. Supports --chart, --no-matrix, --force-csv, --output.
- docs/03-operationeel/tools/run-special.md: full user guide for run_special.py
  (summary, when-to-use, usage examples, arguments, period logic, output
  structure, troubleshooting, related scripts)
- docs/03-operationeel/operations-runbook.md v1.3: added section 10 (special
  run procedure) and reference to run-special.md in section 8
- docs/CHANGELOG.md v0.8.5: documented all changes
- output/2026-05-11/*/: generated special run output (2025-07 start date)

Author: ZorgiDannyDepecker

docs/03-operationeel/operations-runbook.md

@@ -163,6 +163,7 @@ Lokale lint voor commit:
 | Document | Beschrijving |
 |---|---|
 | `docs/03-operationeel/tools/run-monthly.md` | Gebruiksgids batch-runner |
+| `docs/03-operationeel/tools/run-special.md` | Gebruiksgids special runner (instelbare begindatum) |
 | `docs/03-operationeel/tools/export-data.md` | Gebruiksgids data-export |
 | `docs/03-operationeel/kwaliteitscontrole.md` | Kwaliteitscontroles op output |
 | `docs/02-tactisch/implementatie-gids.md` | Overzicht alle implementatiefasen |
@@ -237,11 +238,64 @@ Dan in Copilot Chat:
 
 ---
 
+## 10. Special run — intern beeld met instelbare begindatum
+
+Naast de standaard maandelijkse run bestaat er een **special runner** voor analyses
+die starten op een andere datum dan januari. Typisch gebruik: intern PHARMA-beeld
+vanaf **juli 2025**.
+
+> Volledig verschil met de standaardrun: zie `docs/03-operationeel/tools/run-special.md`.
+
+### 10.1 — Wanneer uitvoeren
+
+Voer `run_special.py` uit wanneer:
+
+- een intern beeld gewenst is op basis van data **vanaf juli 2025** (of een andere maand)
+- de PHARMA-pijler apart geanalyseerd moet worden t.o.v. het ZORGI-totaalplaatje
+- maandelijks, aanvullend aan `run_monthly.py` — niet ter vervanging
+
+### 10.2 — Volledige run (aanbevolen)
+
+```powershell
+cd C:\Users\danndepe\Documents\AI\CSAT-Compass
+.venv\Scripts\Activate.ps1
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart
+```
+
+Verwacht: **30 bestanden** in `output\YYYY-MM-DD\{pijler}\`
+(10 matrices + 10 evolutierapporten + 10 PNG's)
+
+### 10.3 — Uitvoerstructuur
+
+Bestanden staan in **dezelfde mappenstructuur** als de standaard run.
+Het onderscheid is zichtbaar in de bestandsnaam:
+
+| Type | Standaard | Special |
+|---|---|---|
+| Evolutierapport NL | `evolutie-care-2026-nl_...md` | `evolutie-care-2025-07-nl_...md` |
+| Matrix NL | `matrix-care-2026-nl_...md` | `matrix-care-2025-07-nl_...md` |
+
+### 10.4 — Checklist special run
+
+- [ ] Omgeving actief (`Activate.ps1`)
+- [ ] Run uitgevoerd met `--start 2025-07 --chart`
+- [ ] 30 bestanden aanwezig — geen `[FOUT]`-meldingen
+- [ ] Bestandsnamen bevatten `2025-07` als jaarlabel
+- [ ] PDF-conversie indien gewenst (zie §9.3)
+
+### 10.5 — Noodrun (SQL niet beschikbaar)
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart --force-csv
+```
+
+---
+
 ## Versiehistorie
 
 | Versie | Datum | Wijzigingen | Auteur |
 | ------ | ---------- | --------------- | ------ |
 | 1.0 | 26/03/2026 | Initiële versie — fasen 1 t/m 3e operationeel | Danny Depecker + GHC |
 | 1.1 | 21/04/2026 | §8 referenties uitgebreid | Danny Depecker + GHC |
 | 1.2 | 05/05/2026 | §9 Nieuw maand checklist toegevoegd incl. PDF-procedure met PNG-vereiste | Danny Depecker + GHC |
-| 1.2 | 04/05/2026 | §9 Nieuw maand checklist toegevoegd (data run, verificatie, PDF, distributie, dashboard, periodiek onderhoud, statustracking) | Danny Depecker + GHC |
+| 1.3 | 11/05/2026 | §10 Special run toegevoegd; §8 run-special.md toegevoegd aan referenties | Danny Depecker + GHC |

docs/03-operationeel/tools/run-special.md

@@ -0,0 +1,194 @@
+# CSAT-Compass - run_special.py
+
+**Versie:** 1.0
+**Laatst bijgewerkt:** 11/05/2026
+
+**Doel:** Operationele gebruiksgids voor de special runner (instelbare begindatum)
+**Type:** Tool-documentatie
+**Auteur:** Danny Depecker + GHC
+**Status:** Actief
+
+**Bestandsnaam:** run-special.md
+**Path:** docs/03-operationeel/tools/
+
+---
+
+## Samenvatting
+
+`scripts/run_special.py` genereert dezelfde output als de standaard maandelijkse run,
+maar met een **instelbare begindatum**. Hiermee is het mogelijk om analyses te beperken
+tot een specifieke startperiode — onafhankelijk van de reguliere ZORGI-rapportage.
+
+**Typisch gebruik:** intern PHARMA-beeld op basis van data **vanaf juli 2025** t/m de
+volledige afgelopen maand, ter aanvulling van (niet ter vervanging van) het ZORGI-geheel.
+
+Per pijler worden **6 bestanden** gegenereerd — identiek aan de standaardstructuur:
+
+| Bestand | Inhoud |
+|---|---|
+| `matrix-{pijler}-{start}-nl/fr_...md` | Maandmatrix NL + FR (start t/m huidig) |
+| `evolutie-{pijler}-{start}-nl/fr_...md` | Evolutierapport NL + FR |
+| `evolutie-{pijler}-{start}-nl/fr_...png` | Visualisatie NL + FR |
+
+**Bestandsnamen bevatten altijd de begindatum** — zo is het onderscheid met de
+standaard output (`evolutie-care-2026-nl_...md`) direct zichtbaar
+(`evolutie-care-2025-07-nl_...md`).
+
+**Volledig commando:**
+
+```powershell
+cd C:\Users\danndepe\Documents\AI\CSAT-Compass
+.venv\Scripts\Activate.ps1
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart
+```
+
+---
+
+## Wanneer gebruiken
+
+| Situatie | Script |
+|---|---|
+| Maandelijkse standaardrapportage (volledig jaar 2025 als baseline) | `run_monthly.py` |
+| Intern PHARMA-beeld — data enkel vanaf een specifieke maand | `run_special.py` |
+| Adhoc evolutie voor één pijler met vrije periodes | `generate_evolution.py` |
+
+---
+
+## Gebruik
+
+### Standaardrun (begindatum = juli 2025, vorige maand als einddatum)
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart
+```
+
+### Specifieke doelmaand
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --month 2026-04 --chart
+```
+
+### Selectie van pijlers
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --pillar pharma care --chart
+```
+
+### Zonder PNG-visualisaties
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07
+```
+
+### Zonder vergelijkingsmatrix
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart --no-matrix
+```
+
+### Noodrun (SQL niet beschikbaar)
+
+```powershell
+.venv\Scripts\python.exe scripts/run_special.py --start 2025-07 --chart --force-csv
+```
+
+Vereist dat `data/fallback/` een recente CSV-export bevat (zie `export_data.py`).
+
+---
+
+## Argumenten
+
+| Argument | Beschrijving | Standaard |
+|---|---|---|
+| `--start YYYY-MM` | Begindatum van de analyse — baseline start hier | `2025-07` |
+| `--month YYYY-MM` | Einddatum huidige periode | vorige maand |
+| `--pillar ...` | Pijlers (een of meer) | alle 5: zorgi pharma care care_admin erp4hc |
+| `--chart` | Genereer PNG-visualisaties (NL + FR per pijler) | uit |
+| `--no-matrix` | Sla vergelijkingsmatrices over | uit (matrix AAN) |
+| `--force-csv` | SQL omzeilen, CSV-fallback forceren | uit |
+| `--output MAP` | Alternatieve basisuitvoermap | `output/` |
+
+---
+
+## Periodelogica
+
+De begindatum (`--start`) bepaalt automatisch de splitsing:
+
+| Parameter | Afleiding | Voorbeeld (--start 2025-07 --month 2026-04) |
+|---|---|---|
+| Baseline van | `--start` | `2025-07` |
+| Baseline tot | einde van het startjaar | `2025-12` |
+| Current van | 1 januari volgend jaar | `2026-01` |
+| Current tot | `--month` | `2026-04` |
+| Matrix van | `--start` | `2025-07` |
+| Matrix tot | `--month` | `2026-04` |
+
+> ⚠️ `--start` en `--month` **moeten in verschillende jaren vallen**.
+> De splitsing baseline/current loopt altijd op de jaargrens (31 december / 1 januari).
+
+---
+
+## Output
+
+Bestanden worden weggeschreven naar de **gewone per-pijler mappenstructuur** in `output/`:
+
+```text
+output/
+  YYYY-MM-DD/
+    zorgi/
+      matrix-zorgi-2025-07-nl_TIMESTAMP.md
+      matrix-zorgi-2025-07-fr_TIMESTAMP.md
+      evolutie-zorgi-2025-07-nl_TIMESTAMP.md
+      evolutie-zorgi-2025-07-fr_TIMESTAMP.md
+      evolutie-zorgi-2025-07-nl_TIMESTAMP.png
+      evolutie-zorgi-2025-07-fr_TIMESTAMP.png
+    pharma/
+      matrix-pharma-2025-07-nl_TIMESTAMP.md  ← let op: "2025-07" i.p.v. "2026"
+      ...
+    care/      ...
+    care_admin/ ...
+    erp4hc/    ...
+```
+
+**Totaal bij volledige run** (`--chart`): **30 bestanden**
+(10 matrices + 10 evolutierapporten + 10 PNG's)
+
+### Onderscheid met standaard output
+
+| | Standaard (`run_monthly.py`) | Special (`run_special.py`) |
+|---|---|---|
+| Bestandsnaam | `evolutie-care-2026-nl_...md` | `evolutie-care-2025-07-nl_...md` |
+| Baseline | volledig 2025 (jan–dec) | H2 2025 (jul–dec) |
+| Mappenstructuur | `output/.../care/` | `output/.../care/` (zelfde) |
+
+---
+
+## Probleemoplossing
+
+| Symptoom | Oorzaak | Oplossing |
+|---|---|---|
+| `ValueError: --start moet in een eerder jaar liggen` | `--start` en `--month` vallen in hetzelfde jaar | Kies een `--start` in het jaar vóór `--month` |
+| `ConnectionError` bij start | SQL Server niet bereikbaar | Gebruik `--force-csv` |
+| `0 rijen geladen` voor een pijler | Geen data in die periode | Controleer of de startdatum niet te recent is |
+| Matrix-bestand mist | Pijler-fout tijdens matrix-stap | Bekijk `[FOUT]`-regel in console + `logs/` |
+| PNG ontbreekt | `--chart` niet meegegeven | Herrun met `--chart --no-matrix` (matrix niet opnieuw aanmaken) |
+
+---
+
+## Gerelateerde scripts
+
+| Script | Gebruik |
+|---|---|
+| `scripts/run_monthly.py` | Standaard maandelijkse run (volledig jaar 2025 als baseline) |
+| `scripts/generate_evolution.py` | Evolutierapport voor één pijler met vrije periodes |
+| `scripts/generate_matrix.py` | Enkel de matrix genereren |
+| `scripts/export_data.py` | CSV-snapshot aanmaken voor fallback |
+
+---
+
+## Versiehistorie
+
+| Versie | Datum | Wijzigingen | Auteur |
+| ------ | ---------- | --------------- | ------ |
+| 1.0 | 11/05/2026 | Initiële versie | Danny Depecker + GHC |
+

docs/CHANGELOG.md

@@ -3,6 +3,19 @@
 Alle noemenswaardige wijzigingen aan dit project worden hier gedocumenteerd.
 Formaat gebaseerd op [Keep a Changelog](https://keepachangelog.com/nl/1.0.0/).
 
+## [0.8.5] — 11/05/2026
+
+### Toegevoegd
+
+- `scripts/run_special.py` — nieuwe standalone runner voor evolutierapporten én vergelijkingsmatrices met instelbare begindatum (`--start YYYY-MM`, standaard: `2025-07`). De begindatum fungeert als jaarlabel in de bestandsnamen (bv. `evolutie-care-2025-07-nl_...md`), waardoor de bestanden direct te onderscheiden zijn van de standaard output (`evolutie-care-2026-nl_...md`). Genereert NL + FR matrix + evolutierapport voor alle 5 pijlers (of subset via `--pillar`), in de gewone per-pijler mappenstructuur (`output/YYYY-MM-DD/{pijler}/`). Ondersteunt `--chart`, `--no-matrix`, `--force-csv`, `--output`.
+- `docs/03-operationeel/tools/run-special.md` — volledige gebruiksgids voor `run_special.py`: samenvatting, wanneer-gebruiken tabel, alle gebruik-voorbeelden, argumententabel, periodelogica, outputstructuur, probleemoplossing en gerelateerde scripts.
+
+### Gewijzigd
+
+- `docs/03-operationeel/operations-runbook.md` → versie 1.3: §10 Special run toegevoegd (wanneer uitvoeren, volledig commando, uitvoerstructuur, checklist, noodrun); §8 referentie naar `run-special.md` toegevoegd.
+
+---
+
 ## [0.8.4] — 05/05/2026
 
 ### Toegevoegd