From cad587dcf1a26a9c4422930ad7dd9c28bd52e33b Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 03:16:43 +0300
Subject: [PATCH 01/12] feat(phase-12.5): four data-curation polish items in
 one PR
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 12.5 (Data Curation Polish) ships the four follow-up items
deferred from Phase 12 — none require new architecture; each is a
small additive surface on top of the Phase 12 ingestion + audit
lineage. Will release with v0.5.3 alongside Phase 14.

Source of truth: docs/roadmap/phase-12-5-backlog.md (now updated to
"landed on development" for all four rows).

Item 3 — `forgelm ingest --all-mask` (XS, no new behaviour)
- One-flag shorthand for `--secrets-mask --pii-mask` in the
  documented mask order. Resolved at the CLI boundary; ingest_path's
  Python API stays untouched. Composes additively with explicit
  flags (set-union, no error).

Item 4 — Wizard "audit first" entry point (S)
- New _offer_audit_for_jsonl(path) helper in forgelm/wizard.py,
  invoked from the three JSONL-finalisation paths:
  _offer_ingest_for_directory (after ingest produces a JSONL),
  _validate_local_jsonl (BYOD path), and
  _prompt_dataset_path_with_ingest_offer (full wizard direct-JSONL).
  Mirrors the Phase 11.5 _offer_ingest_for_directory shape exactly.
  Audit is informational, not a gate — failures fall through to the
  "continue without audit" path so a malformed JSONL or transient
  audit error never crashes the wizard.

Item 2 — `forgelm audit --croissant` (S)
- Opt-in Google Croissant 1.0 dataset card emitted under a new
  ``croissant`` field on AuditReport. Card is conformant with
  http://mlcommons.org/croissant/1.0 — `@type: sc:Dataset`, full
  `@context` block, one `cr:FileObject` per JSONL split, one
  `cr:RecordSet` per split with `cr:Field` entries derived from the
  audit's column-detection layer.
- Existing audit JSON keys are byte-equivalent — block stays empty
  when the flag is off (precedent: secrets_summary / quality_summary).

Item 1 — Presidio PII ML adapter (S–M)
- New `[ingestion-pii-ml]` extra (`presidio-analyzer>=2.2.0,<3.0.0`).
- New `forgelm audit --pii-ml` flag layers Presidio NER on top of
  the regex detector. Adds the unstructured-identifier categories
  the regex inherently misses: `person`, `organization`, `location`.
- New `PII_ML_SEVERITY` table (`person → medium`, `organization →
  low`, `location → low`) merged into _build_pii_severity's
  severity_table snapshot so the new categories grade through the
  existing pii_severity block.
- Pre-flight `_require_presidio()` raises ImportError with an
  install hint when the extra is missing — failures surface before
  any rows are scanned. Per-row Presidio failures swallowed so a
  single malformed row never blocks the audit.

Touch points
- forgelm/cli.py — three new flags on existing subparsers; dispatcher
  signatures threaded.
- forgelm/data_audit.py — Presidio import block + sentinel; new
  PII_ML_SEVERITY / PII_ML_TYPES / _PRESIDIO_ENTITY_MAP constants;
  _require_presidio / _get_presidio_analyzer / detect_pii_ml; new
  croissant field on AuditReport; _build_croissant_metadata helper +
  _CROISSANT_CONTEXT; enable_pii_ml / emit_croissant params on
  audit_dataset / _process_split / _audit_split; enable_pii_ml field
  on _StreamingAggregator; _build_pii_severity now consults the
  merged regex+ML table.
- forgelm/wizard.py — _offer_audit_for_jsonl + three call-site
  injections.
- pyproject.toml — `[ingestion-pii-ml]` extra.
- tests/test_phase12_5.py — 11 new tests, four classes (one per item).
- tests/test_wizard_byod.py — three existing tests get an extra "n"
  to decline the new audit-first offer (offer behaviour has its own
  coverage in test_phase12_5.py).
- README, CHANGELOG, roadmap{,-tr}, phase-12-5-backlog.md,
  docs/standards/architecture.md, docs/guides/{ingestion,data_audit}{,-tr}.md,
  docs/reference/usage{,-tr}.md, notebooks/data_curation.ipynb.

Tests: 833 pass (was 822, +11 new). Ruff clean. Bilingual H2 parity
7/7. CLI smoke + new-flag help text verified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                       |  79 +++++++
 README.md                          |   2 +
 docs/guides/data_audit-tr.md       |  85 ++++++++
 docs/guides/data_audit.md          |  83 +++++++
 docs/guides/ingestion-tr.md        |  20 ++
 docs/guides/ingestion.md           |  20 ++
 docs/reference/usage-tr.md         |  10 +
 docs/reference/usage.md            |  10 +
 docs/roadmap-tr.md                 |   4 +-
 docs/roadmap.md                    |   4 +-
 docs/roadmap/phase-12-5-backlog.md |  10 +-
 docs/standards/architecture.md     |   1 +
 forgelm/cli.py                     |  47 +++-
 forgelm/data_audit.py              | 340 ++++++++++++++++++++++++++++-
 forgelm/wizard.py                  |  81 ++++++-
 notebooks/data_curation.ipynb      |  33 +--
 pyproject.toml                     |  10 +
 tests/test_phase12_5.py            | 292 +++++++++++++++++++++++++
 tests/test_wizard_byod.py          |  12 +-
 19 files changed, 1089 insertions(+), 54 deletions(-)
 create mode 100644 tests/test_phase12_5.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fc4ef21..4b7f34e7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,85 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
+### Added — Phase 12.5 (Data Curation Polish backlog)
+
+Four follow-up items from
+[`docs/roadmap/phase-12-5-backlog.md`](docs/roadmap/phase-12-5-backlog.md)
+ship together — none require new architecture; each is a small
+additive surface on top of the Phase 12 ingestion + audit lineage.
+
+- **`forgelm ingest --all-mask`** (item #3) — one-flag shorthand for
+  `--secrets-mask --pii-mask` in the documented mask order (secrets
+  first so combined detectors don't double-count overlapping spans).
+  Composes additively with explicit flags (set-union, no error). Pure
+  UX; no new behaviour.
+- **`forgelm audit --croissant`** (item #2) — opt-in
+  [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card
+  emitted under a new `croissant` key in `data_audit_report.json`. The
+  card carries dataset-level identity, one `cr:FileObject` per JSONL
+  split, and a `cr:RecordSet` per split with `cr:Field` entries
+  derived from the audit's column detection. Existing audit JSON keys
+  are byte-equivalent — the block stays empty when the flag is off
+  (same precedent as `secrets_summary` / `quality_summary`). Lets the
+  same JSON file double as both the EU AI Act Article 10 governance
+  artifact and a Croissant-consumer dataset card.
+- **`forgelm audit --pii-ml`** + new `[ingestion-pii-ml]` extra
+  (item #1) — opt-in [Presidio](https://github.com/microsoft/presidio)
+  ML-NER PII detector layered on top of the existing regex detector.
+  Adds the unstructured-identifier categories the regex inherently
+  misses (`person`, `organization`, `location`) into the same
+  `pii_summary` / `pii_severity` blocks under disjoint category
+  names. Severity tiers in the new `PII_ML_SEVERITY` table:
+  `person → medium`, `organization → low`, `location → low` (deliberately
+  below the regex `critical`/`high` tiers because NER false-positive
+  rates are materially higher than regex-anchored detection).
+  Pre-flight check raises `ImportError("...pip install
+  'forgelm[ingestion-pii-ml]'")` when the extra is missing — failures
+  surface before any rows are scanned. Per-row Presidio failures are
+  swallowed so a single malformed row never blocks the audit.
+- **Wizard "audit first" entry point** (item #4) — when the wizard
+  resolves a JSONL (either typed directly or produced by the
+  Phase 11.5 `_offer_ingest_for_directory` ingest flow), it now offers
+  to run `forgelm audit` on it inline and prints `summarize_report`'s
+  verdict before continuing. Mirrors the
+  `_offer_ingest_for_directory` shape exactly. Closes the BYOD audit
+  loop end-to-end. Audit is informational, not a gate — failures fall
+  through to the "continue without audit" path.
+
+Touch points (so the next reviewer can audit blast radius quickly):
+
+- `forgelm/ingestion.py` — no module changes (the flag composes at the
+  CLI boundary into the existing `pii_mask` / `secrets_mask` booleans).
+- `forgelm/cli.py` — three new flags on the existing subparsers
+  (`--all-mask` on `forgelm ingest`; `--croissant` and `--pii-ml` on
+  `forgelm audit`); dispatcher signatures threaded through.
+- `forgelm/data_audit.py` — `_HAS_PRESIDIO` sentinel, `_require_presidio`,
+  `_get_presidio_analyzer` (cached), `detect_pii_ml`,
+  `PII_ML_SEVERITY`, `PII_ML_TYPES`, `_PRESIDIO_ENTITY_MAP`,
+  `_build_croissant_metadata`, `_CROISSANT_CONTEXT`. New
+  `enable_pii_ml` / `emit_croissant` parameters on `audit_dataset` /
+  `_process_split` / `_audit_split`; new `enable_pii_ml` field on
+  `_StreamingAggregator`; new `croissant` field on `AuditReport`.
+  `_build_pii_severity` now consults the merged
+  `PII_SEVERITY ∪ PII_ML_SEVERITY` table.
+- `forgelm/wizard.py` — new `_offer_audit_for_jsonl(path)` helper;
+  invoked from `_offer_ingest_for_directory` (after ingest produces
+  a JSONL), `_validate_local_jsonl` (after a directly-provided JSONL
+  passes validation), and `_prompt_dataset_path_with_ingest_offer`
+  (after a non-directory JSONL is provided to the full wizard).
+- `pyproject.toml` — new `[ingestion-pii-ml]` extra
+  (`presidio-analyzer>=2.2.0,<3.0.0`).
+- `tests/test_phase12_5.py` — 11 new tests, four classes (one per
+  backlog row).
+- `tests/test_wizard_byod.py` — three existing tests get an extra
+  `"n"` answer to decline the new audit-first offer (the offer
+  behaviour has its own coverage in `test_phase12_5.py`).
+- Docs — `README.md` install matrix + Phase 12.5 feature line;
+  `docs/standards/architecture.md` extras matrix; `docs/guides/ingestion{,-tr}.md`
+  + `docs/guides/data_audit{,-tr}.md` get dedicated sections per
+  feature; `notebooks/data_curation.ipynb` mentions `--all-mask` and
+  the Phase 12.5 audit add-ons inline.
+
 ### Fixed — post-PR-#13 review-cycle batches (rounds 8-12)
 
 Inline-comment batches landing on top of PR #13 (now merged to `main`).
diff --git a/README.md b/README.md
index f09e8d32..d90a461f 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@
 - **PDF Page Header/Footer Dedup (v0.5.1)**: Lines that recur on ≥ 70 % of PDF pages (watermarks, page numbers, copyright lines) are stripped automatically — the audit's near-duplicate counts stop misfiring on long policy / book PDFs.
 - **Dataset Audit**: `forgelm audit data/sft.jsonl --output ./audit/` — produces `data_audit_report.json` with sample count, length distribution, top-3 language detection, LSH-banded near-duplicate rate (`O(n × k)` typical case, exact recall at the default Hamming threshold; v0.5.2 added optional **MinHash LSH** via `--dedup-method minhash` for >50K-row corpora), cross-split leakage check, null/empty rate, and PII flag counts with **severity tiers** (critical / high / medium / low + worst-tier verdict). v0.5.2 also added an always-on **secrets/credential scan** covering the nine families enumerated in `forgelm.data_audit.SECRET_TYPES` — AWS access keys, GitHub tokens, Slack tokens, OpenAI API keys, Google API keys, JWTs, full OpenSSH private-key blocks, full PGP private-key blocks, and Azure storage connection strings — and an opt-in **heuristic quality filter** (`--quality-filter`). CPU-only; streaming JSONL reader keeps memory bounded on multi-million-row splits; feeds EU AI Act Article 10 governance artifact automatically when present at training time. Legacy `--data-audit` flag still works as a deprecation alias.
 - **Secrets-Aware Ingest (v0.5.2)**: `forgelm ingest … --secrets-mask` scrubs credentials before chunks land in the JSONL — fine-tuning on text containing real API keys memorises them at training time. Pairs with `--pii-mask`; secrets run first so combined detectors don't double-count overlapping spans.
+- **Phase 12.5 polish (v0.5.3)**: `forgelm ingest --all-mask` shorthand for combined PII + secrets scrubbing; `forgelm audit --croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card alongside the existing report; `forgelm audit --pii-ml` layers [Presidio](https://github.com/microsoft/presidio) NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra (`person` / `organization` / `location` categories merged into the same `pii_severity` block); the wizard now offers to run `forgelm audit` automatically after a JSONL is selected (BYOD onboarding closes the audit loop).
 
 ### Quickstart Layer (v0.4.5)
 - **One-Command Templates**: `forgelm quickstart customer-support` — 4 bundled templates (SFT customer-support, code-assistant, medical-qa-tr, GRPO math-reasoning) plus a bring-your-own-data domain-expert scaffold. Auto-downsizes models on small GPUs.
@@ -172,6 +173,7 @@ pip install "forgelm[merging]"           # mergekit model merging
 pip install "forgelm[ingestion]"         # PDF/DOCX/EPUB/Markdown → JSONL + langdetect + xxhash
 pip install "forgelm[ingestion-scale]"   # MinHash LSH dedup (datasketch) for >50K-row corpora
 pip install "forgelm[ingestion-secrets]" # detect-secrets scanner for SFT corpora (falls back to regex if absent)
+pip install "forgelm[ingestion-pii-ml]"  # Presidio ML-NER for person/organization/location PII (Phase 12.5)
 pip install "forgelm[export]"            # GGUF export via llama-cpp-python
 pip install "forgelm[chat]"              # Rich terminal rendering for `forgelm chat`
 ```
diff --git a/docs/guides/data_audit-tr.md b/docs/guides/data_audit-tr.md
index 207d2068..980370b1 100644
--- a/docs/guides/data_audit-tr.md
+++ b/docs/guides/data_audit-tr.md
@@ -321,6 +321,91 @@ install ile uyumlu kalır.
 
 ---
 
+### ML-NER PII adaptörü — `--pii-ml` (Faz 12.5, opt-in)
+
+Varsayılan regex detector, EU AI Act Madde 10'un önemsediği yapılandırılmış
+identifier'ları (email, telefon, IBAN, kredi kartı, ulusal kimlik) kapsar.
+Faz 12.5, regex'in doğal olarak kaçırdığı yapılandırılmamış identifier
+kategorilerini ekleyen opt-in **Presidio** ([microsoft/presidio](https://github.com/microsoft/presidio))
+adaptörünü ML-NER olarak üstüne ekler: `person`, `organization`,
+`location`.
+
+```bash
+pip install 'forgelm[ingestion-pii-ml]'
+forgelm audit data/ --output ./audit/ --pii-ml
+```
+
+Yeni kategoriler mevcut `pii_summary` ve `pii_severity` bloklarına
+disjoint isimlerle birleşir, bu yüzden regex baseline ML sinyaliyle
+yan yana görünür kalır:
+
+```json
+{
+  "pii_summary": {
+    "email": 12,
+    "phone": 3,
+    "person": 47,         // ← Presidio
+    "organization": 18,   // ← Presidio
+    "location": 9         // ← Presidio
+  },
+  "pii_severity": {
+    "by_tier": {"critical": 0, "high": 0, "medium": 59, "low": 30},
+    "by_type": {
+      "email": {"count": 12, "tier": "medium"},
+      "person": {"count": 47, "tier": "medium"},
+      "organization": {"count": 18, "tier": "low"}
+    },
+    "worst_tier": "medium"
+  }
+}
+```
+
+Şiddet ataması `forgelm.data_audit.PII_ML_SEVERITY`'de yaşar:
+`person → medium`, `organization → low`, `location → low`. NER
+false-positive oranları regex-anchored detection'dan materyal olarak
+yüksektir — bu yüzden ML katmanları regex'in `critical` / `high`
+katlarının altında bilinçli konumlandırılır. Bir ML bulgusunu sert
+bir gate olarak değerlendirmeden önce satır bazında span'leri inceleyin.
+
+Presidio'nun ilk analyzer build'i bir spaCy İngilizce NER modeli
+indirir (~ 50 MB, tek seferlik). Sonraki çalışmalar cached modeli
+yeniden kullanır. Adaptör yalnızca opt-in; `--pii-ml` olmadan audit
+zero-extra-deps regex yolunda kalır.
+
+---
+
+### Croissant 1.0 dataset card — `--croissant` (Faz 12.5, opt-in)
+
+`--croissant`, `data_audit_report.json` içinde yeni bir top-level
+`croissant` bloğunu [Google Croissant 1.0](http://mlcommons.org/croissant/)
+dataset card'ı (`@type: sc:Dataset`) ile doldurur. Card, kanonik
+`mlcommons.org/croissant/1.0` context'iyle uyumludur — bu yüzden
+Croissant farkındalıklı consumer'lar (HuggingFace dataset cards,
+MLCommons referans loader'ları, Croissant validator) bloğu hiçbir
+modifikasyon olmadan parse edebilir.
+
+```bash
+forgelm audit data/ --output ./audit/ --croissant
+```
+
+Card şunları taşır:
+
+* dataset seviyesinde kimlik (`name`, `description`, `version`,
+  `datePublished`, `url`),
+* her JSONL split'i için bir `cr:FileObject` (Croissant consumer'ı
+  altta yatan dosyaları bulabilsin diye),
+* her split için audit'in column-detection katmanından türetilen
+  `cr:Field` girdileriyle bir `cr:RecordSet`.
+
+Flag kapalıyken blok boştur — mevcut consumer'lar byte-eşdeğer çıktı
+görür, `secrets_summary` / `quality_summary`'nin koyduğu emsalin
+aynısı. Card'ı HuggingFace / MLCommons'a yayınlamak isteyen operatörler
+audit'in birinci sınıf delili olmayan ek Croissant alanlarını
+(`license`, `citeAs`, `keywords`) audit'i yeniden çalıştırmadan
+elle düzenleyebilir.
+
+---
+
 ## Layout gereksinimleri
 
 | Girdi şekli | Ne elde edersin |
diff --git a/docs/guides/data_audit.md b/docs/guides/data_audit.md
index 2ae9f760..0052b1b6 100644
--- a/docs/guides/data_audit.md
+++ b/docs/guides/data_audit.md
@@ -319,6 +319,89 @@ the audit reproducible (Annex IV requirement) and bare-install-friendly.
 
 ---
 
+### ML-NER PII adapter — `--pii-ml` (Phase 12.5, opt-in)
+
+The default regex detector covers the structured identifiers EU AI Act
+Article 10 cares about (email, phone, IBAN, credit card, national IDs).
+Phase 12.5 adds an opt-in **Presidio** ([microsoft/presidio](https://github.com/microsoft/presidio))
+adapter that layers ML-NER on top — adding the unstructured-identifier
+categories regex inherently misses: `person`, `organization`, `location`.
+
+```bash
+pip install 'forgelm[ingestion-pii-ml]'
+forgelm audit data/ --output ./audit/ --pii-ml
+```
+
+The new categories merge into the existing `pii_summary` and
+`pii_severity` blocks under disjoint names so the regex baseline stays
+visible alongside the ML signal:
+
+```json
+{
+  "pii_summary": {
+    "email": 12,
+    "phone": 3,
+    "person": 47,         // ← Presidio
+    "organization": 18,   // ← Presidio
+    "location": 9         // ← Presidio
+  },
+  "pii_severity": {
+    "by_tier": {"critical": 0, "high": 0, "medium": 59, "low": 30},
+    "by_type": {
+      "email": {"count": 12, "tier": "medium"},
+      "person": {"count": 47, "tier": "medium"},
+      "organization": {"count": 18, "tier": "low"}
+    },
+    "worst_tier": "medium"
+  }
+}
+```
+
+Severity assignment lives in `forgelm.data_audit.PII_ML_SEVERITY`:
+`person → medium`, `organization → low`, `location → low`. NER
+false-positive rates are materially higher than regex-anchored
+detection, so the ML tiers sit deliberately below the regex
+`critical`/`high` floors — review the per-row spans before treating an
+ML finding as a hard gate.
+
+Presidio's first analyzer build downloads a spaCy English NER model
+(~ 50 MB, one-time). Subsequent runs reuse the cached model. The
+adapter is opt-in only; without `--pii-ml` the audit stays on the
+zero-extra-deps regex path.
+
+---
+
+### Croissant 1.0 dataset card — `--croissant` (Phase 12.5, opt-in)
+
+`--croissant` populates a new top-level `croissant` block in
+`data_audit_report.json` with a [Google Croissant 1.0](http://mlcommons.org/croissant/)
+dataset card (`@type: sc:Dataset`). The card is conformant with the
+canonical `mlcommons.org/croissant/1.0` context, so Croissant-aware
+consumers (HuggingFace dataset cards, MLCommons reference loaders, the
+Croissant validator) can parse the block without modification.
+
+```bash
+forgelm audit data/ --output ./audit/ --croissant
+```
+
+The card carries:
+
+* dataset-level identity (`name`, `description`, `version`,
+  `datePublished`, `url`),
+* one `cr:FileObject` per JSONL split (so a Croissant consumer can
+  locate the underlying files),
+* one `cr:RecordSet` per split with `cr:Field` entries derived from
+  the audit's column-detection layer.
+
+The block is empty when the flag is off — existing consumers see
+byte-equivalent output, the same precedent set by `secrets_summary` /
+`quality_summary`. Operators that want to publish the card to
+HuggingFace / MLCommons can hand-edit the additional Croissant fields
+the audit doesn't have first-class evidence for (`license`, `citeAs`,
+`keywords`) without re-running the audit.
+
+---
+
 ## Layout requirements
 
 | Input shape | What you get |
diff --git a/docs/guides/ingestion-tr.md b/docs/guides/ingestion-tr.md
index f470e0cb..e1a3fae2 100644
--- a/docs/guides/ingestion-tr.md
+++ b/docs/guides/ingestion-tr.md
@@ -141,6 +141,26 @@ yukarıdaki regex seti çalışır.
 
 ---
 
+## Hepsi bir arada maskeleme — `--all-mask` (Faz 12.5)
+
+`--all-mask`, `--secrets-mask --pii-mask` için tek-flag kısayoludur —
+"paylaşılan korpus üzerinde eğitime başlamadan tespit edilebilir her
+şeyi temizle" iş akışının yaygın hâlidir. İki detector belgelenen
+sıraya göre çalışır (önce secrets — birleşik PII detector'lar örtüşen
+span'leri çift saymasın diye); ortaya çıkan JSONL eşleşme bulunan
+yerlerde hem `[REDACTED-SECRET]` hem de `[REDACTED]` belirteçlerini
+taşır.
+
+```bash
+forgelm ingest ./mixed_corpus/ --recursive --all-mask --output data/clean.jsonl
+```
+
+Açık flag'lerle additive birleşir — `--all-mask --pii-mask` hata
+değildir; iki flag'in boolean unionu çalışır. Kısayol yalnızca
+ergonomi içindir; yeni bir detector eklemez.
+
+---
+
 ## Recursive dizin yürüyüşü
 
 ```text
diff --git a/docs/guides/ingestion.md b/docs/guides/ingestion.md
index 4ae8da99..55d0d272 100644
--- a/docs/guides/ingestion.md
+++ b/docs/guides/ingestion.md
@@ -130,6 +130,26 @@ installing it today does **not** change ingest masking behaviour.
 
 ---
 
+## All-in-one masking — `--all-mask` (Phase 12.5)
+
+`--all-mask` is a one-flag shorthand for `--secrets-mask --pii-mask` —
+the common "scrub everything detectable before training on a shared
+corpus" workflow. The two underlying detectors run in the documented
+order (secrets first so combined PII detectors don't double-count
+overlapping spans); the resulting JSONL carries both `[REDACTED-SECRET]`
+and `[REDACTED]` tokens where matches were found.
+
+```bash
+forgelm ingest ./mixed_corpus/ --recursive --all-mask --output data/clean.jsonl
+```
+
+Composes additively with explicit flags — `--all-mask --pii-mask` is
+not an error; the boolean union of the two flags is what runs. The
+shorthand exists purely as ergonomics; it does not introduce any new
+detector.
+
+---
+
 ## Recursive directory walk
 
 ```text
diff --git a/docs/reference/usage-tr.md b/docs/reference/usage-tr.md
index 31d7275b..5662ac44 100644
--- a/docs/reference/usage-tr.md
+++ b/docs/reference/usage-tr.md
@@ -142,6 +142,9 @@ forgelm ingest ./mixed_corpus/ --secrets-mask --output data/clean.jsonl
 # v0.5.2: secrets + PII maskelemeyi birleştir (önce secrets, sonra PII —
 # örtüşen span'ler iki kez sayılmasın)
 forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/scrubbed.jsonl
+
+# v0.5.3 (Faz 12.5): yukarıdaki kombinasyonun tek-flag kısayolu
+forgelm ingest ./mixed_corpus/ --all-mask --output data/scrubbed.jsonl
 ```
 
 ### Veri Seti Denetimi (v0.5.0+; v0.5.1 subcommand; v0.5.2 MinHash + quality + secrets)
@@ -168,6 +171,13 @@ forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold
 # v0.5.2: opt-in heuristik kalite filtresi (Gopher/C4 stili)
 forgelm audit data/ --quality-filter
 
+# v0.5.3 (Faz 12.5): audit'in yanında bir Google Croissant 1.0 dataset card emit et
+forgelm audit data/ --output ./audit/ --croissant
+
+# v0.5.3 (Faz 12.5): regex PII detector üzerine Presidio NER katmanı ekle
+# (`[ingestion-pii-ml]` extra'sını gerektirir — person/organization/location kategorileri ekler)
+forgelm audit data/ --output ./audit/ --pii-ml
+
 # stdout'a makine-okunabilir özet
 forgelm audit data/sft.jsonl --output ./audit/ --output-format json
 
diff --git a/docs/reference/usage.md b/docs/reference/usage.md
index ca354f5a..eb850c7c 100644
--- a/docs/reference/usage.md
+++ b/docs/reference/usage.md
@@ -160,6 +160,9 @@ forgelm ingest ./mixed_corpus/ --secrets-mask --output data/clean.jsonl
 
 # v0.5.2: combine secrets + PII masking (secrets first to avoid double-counting)
 forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/scrubbed.jsonl
+
+# v0.5.3 (Phase 12.5): one-flag shorthand for the same combination above
+forgelm ingest ./mixed_corpus/ --all-mask --output data/scrubbed.jsonl
 ```
 
 ### Dataset Audit (v0.5.0+; subcommand promoted in v0.5.1; MinHash + quality + secrets in v0.5.2)
@@ -185,6 +188,13 @@ forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold
 # v0.5.2: opt-in heuristic quality filter (Gopher/C4 style)
 forgelm audit data/ --quality-filter
 
+# v0.5.3 (Phase 12.5): emit a Google Croissant 1.0 dataset card alongside the audit
+forgelm audit data/ --output ./audit/ --croissant
+
+# v0.5.3 (Phase 12.5): layer Presidio NER on top of the regex PII detector
+# (needs `[ingestion-pii-ml]` extra — adds person/organization/location categories)
+forgelm audit data/ --output ./audit/ --pii-ml
+
 # Machine-readable summary on stdout
 forgelm audit data/sft.jsonl --output ./audit/ --output-format json
 
diff --git a/docs/roadmap-tr.md b/docs/roadmap-tr.md
index aa4cef5c..55fe8290 100644
--- a/docs/roadmap-tr.md
+++ b/docs/roadmap-tr.md
@@ -12,7 +12,7 @@
 | ✅ Tamam | [Faz 11 — Doküman Yutma ve Veri Denetimi](roadmap/phase-11-data-ingestion.md) | `forgelm ingest`, `forgelm --data-audit`, PII regex + simhash dedup — `v0.5.0` çıktı |
 | 🟡 Birleşti | [Faz 11.5 — Yutma / Denetim Cilası](roadmap/phase-11-5-backlog.md) | LSH banding, streaming reader, `forgelm audit` subcommand, PII şiddet katmanları, wizard ingest girişi — `main`'e indi (PR #11/#12); `v0.5.1` PyPI tag'i bekliyor |
 | 🟡 Birleşti | [Faz 12 — Veri Curation Olgunlaşması](roadmap/phase-12-data-curation-maturity.md) | MinHash LSH dedup, markdown-aware splitter, code/secrets tarama, kalite heuristic'leri, tablo yapısı koruma — Tier 1 `main`'e indi (PR #13, 2026-04-29); `v0.5.2` PyPI tag'i bekliyor; Tier 2/3 [Faz 12.5 backlog](roadmap/phase-12-5-backlog.md)'a ertelendi |
-| 📋 Planlandı | [Faz 12.5 — Veri Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adapter, Croissant metadata export, `--all-mask`, wizard "audit first" akışı → `v0.5.2` tag'inden sonra |
+| 🟡 Birleşti | [Faz 12.5 — Veri Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adaptörü (`[ingestion-pii-ml]`), Croissant 1.0 metadata (`--croissant`), `--all-mask`, wizard "audit first" — `development`'a indi; `v0.5.3` (Faz 14) ile çıkacak |
 | 📋 Planlandı | [Faz 14 — Çok Aşamalı Pipeline Zincirleri](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO config zinciri, pipeline kaynak izleri → `v0.5.3` |
 | 📋 Planlandı | [Faz 13 — Pro CLI ve Gözlemlenebilirlik Dashboard](roadmap/phase-13-pro-cli.md) | Lisans korumalı dashboard, HPO, zamanlanmış görevler, takım config store → `v0.6.0-pro` |
 
@@ -24,7 +24,7 @@
 
 **Daha öncesi:** `v0.4.0` — Post-Training Tamamlama (2026-04-26). Inference primitif'leri, etkileşimli chat REPL, GGUF export, VRAM fit advisor, deployment config üretimi.
 
-**Sonraki:** `v0.5.3` — Çok Aşamalı Pipeline Zincirleri (Faz 14). SFT → DPO → GRPO zincir konfigürasyonu, pipeline kaynak izleri. `v0.5.2` PyPI tag'inden sonra başlar; [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını kapsar.
+**Sonraki:** `v0.5.3` — Çok Aşamalı Pipeline Zincirleri (Faz 14) + Faz 12.5 cilası. SFT → DPO → GRPO zincir konfigürasyonu, pipeline kaynak izleri. `v0.5.2` PyPI tag'inden sonra başlar; [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını ve `development`'a inen dört Faz 12.5 backlog item'ını (Presidio NER, Croissant 1.0 card, `--all-mask`, wizard "audit first") kapsar.
 
 **Güncel durum:** 16 faz (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12) tamam. 3 faz (12.5, 13, 14) planlandı. `v0.5.3`: Faz 14 (12.5 backlog'u fırsat oldukça eklenir). `v0.6.0-pro` (Faz 13) adoption metriklerine bağlı.
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index cd3a5f04..25b67dcc 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -12,7 +12,7 @@
 | ✅ Done | [Phase 11 — Document Ingestion & Data Audit](roadmap/phase-11-data-ingestion.md) | `forgelm ingest`, `forgelm --data-audit`, PII regex + simhash dedup — shipped `v0.5.0` |
 | 🟡 Merged | [Phase 11.5 — Ingestion / Audit Polish](roadmap/phase-11-5-backlog.md) | LSH banding, streaming reader, `forgelm audit` subcommand, PII severity tiers, wizard ingest path — merged to `main` (PR #11/#12); PyPI tag pending as `v0.5.1` |
 | 🟡 Merged | [Phase 12 — Data Curation Maturity](roadmap/phase-12-data-curation-maturity.md) | MinHash LSH dedup, markdown-aware splitter, code/secrets scan, quality heuristics, table preservation — Tier 1 merged to `main` (PR #13, 2026-04-29); PyPI tag pending as `v0.5.2`; Tier 2/3 deferred to [Phase 12.5 backlog](roadmap/phase-12-5-backlog.md) |
-| 📋 Planned | [Phase 12.5 — Data Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adapter, Croissant metadata export, `--all-mask`, wizard "audit first" flow → after `v0.5.2` tag |
+| 🟡 Merged | [Phase 12.5 — Data Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adapter (`[ingestion-pii-ml]`), Croissant 1.0 metadata (`--croissant`), `--all-mask`, wizard "audit first" — implemented on `development`; ships with `v0.5.3` (Phase 14) |
 | 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.5.3` |
 | 📋 Planned | [Phase 13 — Pro CLI & Observability Dashboard](roadmap/phase-13-pro-cli.md) | License-gated dashboard, HPO, scheduled jobs, team config store → `v0.6.0-pro` |
 
@@ -24,7 +24,7 @@
 
 **Earlier:** `v0.4.0` — Post-Training Completion (2026-04-26). Inference primitives, interactive chat REPL, GGUF export, VRAM fit advisor, deployment config generation.
 
-**Next:** `v0.5.3` — Multi-Stage Pipeline Chains (Phase 14). SFT → DPO → GRPO chained config, pipeline provenance artifacts. Starts after the `v0.5.2` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14).
+**Next:** `v0.5.3` — Multi-Stage Pipeline Chains (Phase 14) + Phase 12.5 polish. SFT → DPO → GRPO chained config, pipeline provenance artifacts. Starts after the `v0.5.2` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) and the four Phase 12.5 backlog items now landed on `development` (Presidio NER, Croissant 1.0 card, `--all-mask`, wizard "audit first").
 
 **Current state:** 16 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12) complete. 3 phases (12.5, 13, 14) planned. `v0.5.3`: Phase 14 (12.5 backlog folded in opportunistically). `v0.6.0-pro` (Phase 13) gated on adoption metrics.
 
diff --git a/docs/roadmap/phase-12-5-backlog.md b/docs/roadmap/phase-12-5-backlog.md
index 45ec7806..88ee36f4 100644
--- a/docs/roadmap/phase-12-5-backlog.md
+++ b/docs/roadmap/phase-12-5-backlog.md
@@ -14,12 +14,12 @@
 > **Scope:** small additions only — none require new architecture.
 > Each row is one PR.
 
-| # | Item | Source | Effort | Impact |
+| # | Item | Source | Effort | Status |
 |---|---|---|---|---|
-| **1** | **Presidio adapter** (`[ingestion-pii-ml]` extra, optional) | Phase 12 plan Tier 2 #6 | S–M | ML-NER signal regex misses (person names, organisations, locations); maps into the existing `pii_severity` table with new tier rows. Default regex+Luhn+TC-Kimlik path stays. |
-| **2** | **Croissant metadata compatibility** (audit JSON) | Phase 12 plan Tier 2 #7 | S | Adds a Google Croissant-shaped subset to `data_audit_report.json` so the file doubles as both an EU AI Act Article 10 governance artifact and a Croissant-consumer dataset card. Opt-in `--croissant` flag; existing audit consumers unaffected. |
-| **3** | **`forgelm ingest --all-mask` composite flag** | Phase 12 plan Tier 3 #8 | XS | One-flag shorthand that runs `--secrets-mask` then `--pii-mask` in the documented order. Pure UX; no new behaviour. Test: combined-fixture roundtrip. |
-| **4** | **Wizard "audit first" entry point** | Phase 12 plan Tier 3 #9 | S | Mirrors Phase 11.5's `_offer_ingest_for_directory` pattern: when the user provides a JSONL, the wizard offers to run `forgelm audit` and prints the verdicts before continuing. Closes the audit loop in the BYOD path. |
+| **1** | ~~**Presidio adapter** (`[ingestion-pii-ml]` extra, optional)~~ | Phase 12 plan Tier 2 #6 | S–M | ✅ Landed on `development` — `forgelm audit --pii-ml`; new `PII_ML_SEVERITY` table; opt-in `[ingestion-pii-ml]` extra (`presidio-analyzer`); ships with `v0.5.3`. |
+| **2** | ~~**Croissant metadata compatibility** (audit JSON)~~ | Phase 12 plan Tier 2 #7 | S | ✅ Landed on `development` — `forgelm audit --croissant`; Croissant 1.0 card under report's `croissant` key; existing keys byte-equivalent when off. |
+| **3** | ~~**`forgelm ingest --all-mask` composite flag**~~ | Phase 12 plan Tier 3 #8 | XS | ✅ Landed on `development` — `forgelm ingest --all-mask`; set-union with explicit flags; resolved at the CLI boundary. |
+| **4** | ~~**Wizard "audit first" entry point**~~ | Phase 12 plan Tier 3 #9 | S | ✅ Landed on `development` — `_offer_audit_for_jsonl` invoked from the three JSONL-finalisation paths in `forgelm/wizard.py`. |
 
 ## Why these landed here, not in Phase 12
 
diff --git a/docs/standards/architecture.md b/docs/standards/architecture.md
index 63cc1222..6c9fb9a0 100644
--- a/docs/standards/architecture.md
+++ b/docs/standards/architecture.md
@@ -173,6 +173,7 @@ From [`pyproject.toml`](../../pyproject.toml):
 | `ingestion` | pypdf, python-docx, ebooklib, beautifulsoup4, langdetect, xxhash | Any |
 | `ingestion-scale` | datasketch (MinHash LSH dedup; Phase 12, opt-in) | Any |
 | `ingestion-secrets` | detect-secrets (credential leakage scanner; Phase 12, opt-in regex fallback when missing) | Any |
+| `ingestion-pii-ml` | presidio-analyzer (ML-NER for person/organization/location PII; Phase 12.5, opt-in) | Any |
 | `export` | llama-cpp-python (GGUF conversion) | Linux/macOS |
 | `chat` | rich (terminal rendering) | Any |
 | `dev` | pytest, ruff | Any (contributors) |
diff --git a/forgelm/cli.py b/forgelm/cli.py
index 1a4f2dd7..07d8413a 100644
--- a/forgelm/cli.py
+++ b/forgelm/cli.py
@@ -329,6 +329,16 @@ def _add_ingest_subcommand(subparsers) -> None:
             "stronger label first."
         ),
     )
+    p.add_argument(
+        "--all-mask",
+        action="store_true",
+        help=(
+            "Phase 12.5 shorthand: equivalent to --secrets-mask --pii-mask. "
+            "Convenience for the common 'scrub everything detectable before "
+            "training on shared corpora' workflow. Composes additively with "
+            "explicit --pii-mask / --secrets-mask flags (set-union, no error)."
+        ),
+    )
     p.add_argument(
         "--chunk-tokens",
         type=_non_negative_int,
@@ -465,6 +475,26 @@ def _add_audit_subcommand(subparsers) -> None:
             "deferred to Phase 13+."
         ),
     )
+    p.add_argument(
+        "--croissant",
+        action="store_true",
+        help=(
+            "Phase 12.5: emit a Google Croissant 1.0 dataset card (sc:Dataset / cr:RecordSet) "
+            "under the report's 'croissant' key so the same data_audit_report.json doubles as "
+            "both the EU AI Act Article 10 governance artifact and a Croissant-consumer dataset "
+            "card. Existing audit JSON keys are unchanged; the block is empty when this flag is off."
+        ),
+    )
+    p.add_argument(
+        "--pii-ml",
+        action="store_true",
+        help=(
+            "Phase 12.5 opt-in: layer Presidio's ML-NER PII detection (person / organization / "
+            "location categories) on top of the regex detector. Requires the optional "
+            "'forgelm[ingestion-pii-ml]' extra; raises an install-hint ImportError when missing. "
+            "Findings merge into pii_summary / pii_severity under disjoint category names."
+        ),
+    )
     _add_common_subparser_flags(p, include_output_format=True)
 
 
@@ -1277,6 +1307,13 @@ def _run_ingest_cmd(args, output_format: str) -> None:
     """Phase 11 dispatch: raw documents → SFT-ready JSONL."""
     from .ingestion import ingest_path, summarize_result
 
+    # Phase 12.5: --all-mask is a shorthand that ORs into the two individual
+    # masking flags. Resolve it here at the CLI boundary so ``ingest_path``
+    # keeps its narrow API (only ``pii_mask`` / ``secrets_mask`` booleans).
+    all_mask = getattr(args, "all_mask", False)
+    pii_mask = bool(args.pii_mask) or all_mask
+    secrets_mask = bool(getattr(args, "secrets_mask", False)) or all_mask
+
     try:
         result = ingest_path(
             args.input_path,
@@ -1285,8 +1322,8 @@ def _run_ingest_cmd(args, output_format: str) -> None:
             overlap=args.overlap,
             strategy=args.strategy,
             recursive=args.recursive,
-            pii_mask=args.pii_mask,
-            secrets_mask=getattr(args, "secrets_mask", False),
+            pii_mask=pii_mask,
+            secrets_mask=secrets_mask,
             chunk_tokens=getattr(args, "chunk_tokens", None),
             overlap_tokens=getattr(args, "overlap_tokens", 0),
             tokenizer=getattr(args, "tokenizer", None),
@@ -1349,6 +1386,8 @@ def _run_data_audit(
     dedup_method: str = "simhash",
     minhash_jaccard: Optional[float] = None,
     enable_quality_filter: bool = False,
+    enable_pii_ml: bool = False,
+    emit_croissant: bool = False,
     invoked_via_legacy_flag: bool = False,
 ) -> None:
     """Phase 11 / 11.5 / 12 dispatch: dataset quality + governance audit.
@@ -1383,6 +1422,8 @@ def _run_data_audit(
             dedup_method=dedup_method,
             minhash_jaccard=jaccard,
             enable_quality_filter=enable_quality_filter,
+            enable_pii_ml=enable_pii_ml,
+            emit_croissant=emit_croissant,
         )
     except OSError as exc:
         # OSError covers FileNotFoundError / PermissionError / ENOSPC /
@@ -1454,6 +1495,8 @@ def _run_audit_cmd(args, output_format: str) -> None:
         dedup_method=getattr(args, "dedup_method", "simhash"),
         minhash_jaccard=getattr(args, "jaccard_threshold", None),
         enable_quality_filter=getattr(args, "quality_filter", False),
+        enable_pii_ml=getattr(args, "pii_ml", False),
+        emit_croissant=getattr(args, "croissant", False),
         invoked_via_legacy_flag=False,
     )
 
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index 2e05d775..0e3cb4da 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -94,6 +94,23 @@
     _HAS_DATASKETCH = False
 
 
+# Phase 12.5: optional Presidio ML-NER PII detection. Layered ON TOP of
+# the regex detector so the default audit keeps its zero-extra-deps
+# guarantee. Presidio + spaCy are heavyweight (≈ 50 MB model download),
+# so we stay strictly opt-in and fail soft when missing — the regex set
+# already covers the GDPR-mandated structured identifiers (email, phone,
+# IBAN, credit card, national IDs) that the audit's compliance contract
+# is built around. ML adds the *unstructured* identifiers regex inherently
+# misses: person names, organisations, locations.
+try:  # pragma: no cover — exercised by the dedicated extras-skip tests
+    from presidio_analyzer import AnalyzerEngine as _PresidioAnalyzer
+
+    _HAS_PRESIDIO = True
+except ImportError:  # pragma: no cover
+    _PresidioAnalyzer = None  # type: ignore[assignment]
+    _HAS_PRESIDIO = False
+
+
 # ---------------------------------------------------------------------------
 # Public types
 # ---------------------------------------------------------------------------
@@ -135,6 +152,27 @@
 with the worst-case findings rather than burying them behind low tiers."""
 
 
+# Phase 12.5: severity for the ML-NER detector (Presidio adapter).  These
+# categories sit alongside the regex set and feed the same pii_severity
+# block, which is why they share the ``critical/high/medium/low`` tier
+# vocabulary.  Entries are deliberately on the lower end of the tier
+# table because NER false-positive rates are materially higher than the
+# regex-anchored detectors (a model name, a city, or an organization
+# string can be flagged with no privacy impact); compliance reviewers
+# can still upgrade the tier locally if their corpus warrants it.
+PII_ML_SEVERITY: Dict[str, str] = {
+    "person": "medium",
+    "organization": "low",
+    "location": "low",
+}
+
+
+PII_ML_TYPES: Tuple[str, ...] = tuple(PII_ML_SEVERITY.keys())
+"""Canonical category names for ML-detected PII.  Disjoint from
+:data:`PII_TYPES` (regex categories) so the two detectors can run side
+by side without double-counting the same span."""
+
+
 # Columns we treat as text payloads when computing length / language / dedup.
 # Order matters: first match wins per row.
 _TEXT_COLUMNS: Tuple[str, ...] = ("text", "content", "completion", "prompt")
@@ -191,6 +229,10 @@ class AuditReport:
     # dicts on default audits with no findings.
     secrets_summary: Dict[str, int] = field(default_factory=dict)
     quality_summary: Dict[str, Any] = field(default_factory=dict)
+    # Phase 12.5: optional Google Croissant 1.0 dataset card. Empty dict
+    # by default so existing consumers see byte-identical output; set
+    # via ``audit_dataset(..., emit_croissant=True)`` or ``--croissant``.
+    croissant: Dict[str, Any] = field(default_factory=dict)
     notes: List[str] = field(default_factory=list)
 
 
@@ -350,6 +392,100 @@ def _replace(match: re.Match, _t: str = pii_type) -> str:
     return (out, counts) if return_counts else out
 
 
+# ---------------------------------------------------------------------------
+# Phase 12.5: optional Presidio ML-NER PII adapter
+# ---------------------------------------------------------------------------
+
+
+# Presidio analyzer is heavy to construct (loads spaCy + an English NER
+# model on first call), so we cache a single instance for the duration
+# of the process. ``maxsize=1`` keeps the cache trivially eviction-free
+# while still letting test code blow the cache via ``cache_clear()``.
+@lru_cache(maxsize=1)
+def _get_presidio_analyzer() -> Any:
+    """Return a cached :class:`presidio_analyzer.AnalyzerEngine` instance.
+
+    Raises:
+        ImportError: when the ``[ingestion-pii-ml]`` extra is missing.
+            Also surfaced through the public :func:`_require_presidio`
+            helper so callers that gate on Presidio availability up
+            front can produce a clean message before processing starts.
+    """
+    _require_presidio()
+    return _PresidioAnalyzer()
+
+
+def _require_presidio() -> None:
+    """Raise a clear ImportError when the optional ML-NER backend is missing.
+
+    Mirrors :func:`_require_datasketch` so any audit code path that
+    needs Presidio fails with an actionable install hint instead of a
+    deep ``AttributeError`` the operator can't act on.
+    """
+    if not _HAS_PRESIDIO:
+        raise ImportError(
+            "Presidio PII ML detection requires the 'ingestion-pii-ml' extra. "
+            "Install with: pip install 'forgelm[ingestion-pii-ml]'"
+        )
+
+
+# Map of Presidio's canonical entity-type strings (which mirror the
+# spaCy NER label set) to the ForgeLM category names that feed
+# :data:`PII_ML_SEVERITY` / :data:`PII_ML_TYPES`.  Keys come from
+# Presidio's recognizer registry; multiple Presidio labels can collapse
+# into a single ForgeLM bucket (``GPE`` / ``LOCATION`` both → ``location``)
+# because the audit's downstream consumer (compliance reviewer) doesn't
+# need finer granularity than person / organization / location.
+_PRESIDIO_ENTITY_MAP: Dict[str, str] = {
+    "PERSON": "person",
+    "ORG": "organization",
+    "ORGANIZATION": "organization",
+    "LOCATION": "location",
+    "GPE": "location",
+    "NORP": "location",
+    "FAC": "location",
+}
+
+
+def detect_pii_ml(text: Any) -> Dict[str, int]:
+    """ML-NER PII detector — counts ``person`` / ``organization`` / ``location`` spans.
+
+    Layered ON TOP of :func:`detect_pii` (regex). The two detectors
+    return disjoint category sets so the merged ``pii_summary`` shows
+    both the structured-identifier signal (regex) and the
+    unstructured-identifier signal (ML) without double-counting the
+    same span.
+
+    Returns an empty dict when:
+    * ``text`` is not a non-empty string (defensive — callers pass JSONL
+      payloads that may be ``None`` / numbers / dicts);
+    * Presidio is not installed (the caller must opt in explicitly via
+      :func:`_require_presidio` if they want a hard failure);
+    * the analyzer raises on the input — Presidio can fail on
+      pathological strings, model-load races, or version skews. We
+      swallow per-row failures and return zero counts so a single bad
+      row never blocks the audit.
+    """
+    if not isinstance(text, str) or not text.strip():
+        return {}
+    if not _HAS_PRESIDIO:
+        return {}
+    try:
+        analyzer = _get_presidio_analyzer()
+        results = analyzer.analyze(text=text, language="en")
+    except Exception:  # pragma: no cover — Presidio raises on edge cases
+        # Per-row resilience: a single malformed row must not abort the
+        # audit. The aggregator counts no ML PII for this row, which is
+        # the correct behaviour for opt-in best-effort detection.
+        return {}
+    counts: Dict[str, int] = {}
+    for finding in results:
+        kind = _PRESIDIO_ENTITY_MAP.get(getattr(finding, "entity_type", ""))
+        if kind:
+            counts[kind] = counts.get(kind, 0) + 1
+    return counts
+
+
 # ---------------------------------------------------------------------------
 # Simhash + near-duplicate detection
 # ---------------------------------------------------------------------------
@@ -1376,6 +1512,8 @@ class _StreamingAggregator:
     # Phase 12 configuration (set once by the orchestrator; never mutated).
     dedup_method: str = "simhash"
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM
+    # Phase 12.5: opt-in ML-NER PII detection (Presidio). Off by default.
+    enable_pii_ml: bool = False
     enable_quality_filter: bool = False
 
 
@@ -1415,6 +1553,13 @@ def _record_text_metrics(agg: _StreamingAggregator, payload: str) -> None:
     _record_dedup_signature(agg, payload)
     for kind, count in detect_pii(payload).items():
         agg.pii_counts[kind] = agg.pii_counts.get(kind, 0) + count
+    if agg.enable_pii_ml:
+        # Phase 12.5: Presidio NER findings layer onto the same pii_counts
+        # bucket. The category names are disjoint from the regex set
+        # (person / organization / location vs. email / phone / *_id),
+        # so the merged counts present both views without double-counting.
+        for kind, count in detect_pii_ml(payload).items():
+            agg.pii_counts[kind] = agg.pii_counts.get(kind, 0) + count
     for kind, count in detect_secrets(payload).items():
         agg.secrets_counts[kind] = agg.secrets_counts.get(kind, 0) + count
     if agg.enable_quality_filter:
@@ -1584,6 +1729,7 @@ def _audit_split(
     minhash_jaccard: float = DEFAULT_MINHASH_JACCARD,
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
+    enable_pii_ml: bool = False,
 ) -> Tuple[Dict[str, Any], List[Any], Dict[str, int], int, int]:
     """Stream a JSONL split into a metrics record.
 
@@ -1621,6 +1767,7 @@ def _audit_split(
         dedup_method=dedup_method,
         minhash_num_perm=minhash_num_perm,
         enable_quality_filter=enable_quality_filter,
+        enable_pii_ml=enable_pii_ml,
     )
     for row, parse_err, decode_err in _read_jsonl_split(path):
         _ingest_row(agg, row, parse_err, decode_err)
@@ -1938,6 +2085,7 @@ def _process_split(
     minhash_jaccard: float = DEFAULT_MINHASH_JACCARD,
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
+    enable_pii_ml: bool = False,
 ) -> _SplitOutcome:
     """Stream + audit one split. Tolerates per-split filesystem failures.
 
@@ -1957,6 +2105,7 @@ def _process_split(
             minhash_jaccard=minhash_jaccard,
             minhash_num_perm=minhash_num_perm,
             enable_quality_filter=enable_quality_filter,
+            enable_pii_ml=enable_pii_ml,
         )
     except OSError as exc:
         logger.warning("Could not read split '%s' (%s): %s — skipping.", split_name, path, exc)
@@ -2009,12 +2158,15 @@ def _build_pii_severity(pii_summary: Dict[str, int]) -> Dict[str, Any]:
     from :data:`PII_SEVERITY` (forward-compat for new types) fall back to
     ``unknown``.
 
-    A snapshot of :data:`PII_SEVERITY` is taken at call time so a
-    test or downstream caller mutating the module-level dict cannot
-    corrupt the audit output mid-run; per-call audits see a stable
-    table for the duration of their work.
+    A snapshot of :data:`PII_SEVERITY` (regex categories) and
+    :data:`PII_ML_SEVERITY` (Phase 12.5 ML-NER categories) is taken at
+    call time so a test or downstream caller mutating either dict
+    cannot corrupt the audit output mid-run; per-call audits see a
+    stable merged table for the duration of their work. The two
+    tables share the same tier vocabulary (``critical/high/medium/low``)
+    on purpose so the verdict surface stays unified.
     """
-    severity_table = dict(PII_SEVERITY)
+    severity_table = {**PII_SEVERITY, **PII_ML_SEVERITY}
     if not pii_summary:
         return {
             "total": 0,
@@ -2189,6 +2341,146 @@ def _build_quality_summary(
     }
 
 
+# Phase 12.5: Google Croissant 1.0 dataset-card emission. Croissant is a
+# JSON-LD vocabulary built on top of schema.org; mlcommons.org/croissant
+# describes the canonical context. We emit a minimum-viable subset that's
+# valid against the spec — tools that consume Croissant (HuggingFace's
+# dataset-cards, Croissant validator, MLCommons reference loaders) can
+# parse the block without modification, while the rest of the audit JSON
+# stays untouched. The card lives under the new ``croissant`` key on the
+# ``AuditReport`` dataclass; callers that don't want it never see it.
+_CROISSANT_VOCAB_VERSION = "1.0"
+_CROISSANT_CONTEXT: Dict[str, Any] = {
+    "@language": "en",
+    "@vocab": "https://schema.org/",
+    "sc": "https://schema.org/",
+    "cr": "http://mlcommons.org/croissant/",
+    "data": {"@id": "cr:data", "@type": "@json"},
+    "dataType": {"@id": "cr:dataType", "@type": "@vocab"},
+    "extract": "cr:extract",
+    "field": "cr:field",
+    "fileProperty": "cr:fileProperty",
+    "format": "cr:format",
+    "includes": "cr:includes",
+    "isLiveDataset": "cr:isLiveDataset",
+    "jsonPath": "cr:jsonPath",
+    "key": "cr:key",
+    "parentField": "cr:parentField",
+    "path": "cr:path",
+    "recordSet": "cr:recordSet",
+    "references": "cr:references",
+    "regex": "cr:regex",
+    "repeated": "cr:repeated",
+    "replace": "cr:replace",
+    "separator": "cr:separator",
+    "source": "cr:source",
+    "subField": "cr:subField",
+    "transform": "cr:transform",
+}
+
+
+def _build_croissant_metadata(
+    *,
+    source_path: str,
+    source_input: str,
+    generated_at: str,
+    total_samples: int,
+    splits_info: Dict[str, Dict[str, Any]],
+    splits_paths: Dict[str, Path],
+) -> Dict[str, Any]:
+    """Render a minimum-viable Croissant 1.0 dataset card for the audited corpus.
+
+    The card exposes:
+    * dataset-level identity (name, description, version, datePublished),
+    * one ``cr:FileObject`` per JSONL split (so a Croissant consumer can
+      locate the underlying files),
+    * one ``cr:RecordSet`` per split with the columns the audit detected
+      under ``splits.<name>.columns`` mapped to ``cr:Field`` entries.
+
+    The mapping intentionally stays additive — Croissant supports many
+    optional fields (citeAs, license, keywords, sameAs, etc.) that the
+    audit does not have first-class evidence for. Operators that want to
+    publish the card to HuggingFace / MLCommons can hand-edit those
+    fields without re-running the audit.
+    """
+    # Derive a human-readable name from the source path. ``Path.stem`` for
+    # a JSONL ("policies.jsonl" → "policies"); for a directory we use the
+    # directory name. Fall back to ``source_input`` so HF Hub IDs survive
+    # in the card even though the audit is filesystem-only today.
+    src = Path(source_path)
+    if src.is_file():
+        name = src.stem
+    elif src.is_dir():
+        name = src.name
+    else:
+        name = source_input or "dataset"
+
+    distribution: List[Dict[str, Any]] = []
+    record_sets: List[Dict[str, Any]] = []
+    for split_name, info in splits_info.items():
+        split_path = splits_paths.get(split_name)
+        sample_count = int(info.get("sample_count", 0))
+        file_id = f"{split_name}.jsonl"
+        distribution.append(
+            {
+                "@type": "cr:FileObject",
+                "@id": file_id,
+                "name": file_id,
+                "contentUrl": str(split_path) if split_path is not None else file_id,
+                "encodingFormat": "application/jsonlines",
+                "description": f"Split {split_name!r}: {sample_count} sample(s).",
+            }
+        )
+
+        # Map the audit's detected columns to ``cr:Field`` entries.
+        # ``columns`` is a list of strings (the keys present in the JSONL
+        # rows). When the column is one of the canonical text-payload
+        # columns we type it as ``sc:Text``; everything else is ``sc:Text``
+        # too (the audit doesn't track per-column dtypes — that's a
+        # consumer-side concern).
+        columns = info.get("columns") or []
+        fields = [
+            {
+                "@type": "cr:Field",
+                "@id": f"{split_name}/{column}",
+                "name": column,
+                "dataType": "sc:Text",
+                "source": {
+                    "fileObject": {"@id": file_id},
+                    "extract": {"jsonPath": f"$.{column}"},
+                },
+            }
+            for column in columns
+        ]
+        record_sets.append(
+            {
+                "@type": "cr:RecordSet",
+                "@id": split_name,
+                "name": split_name,
+                "field": fields,
+                "description": f"Records from split {split_name!r}.",
+            }
+        )
+
+    return {
+        "@context": dict(_CROISSANT_CONTEXT),
+        "@type": "sc:Dataset",
+        "conformsTo": "http://mlcommons.org/croissant/1.0",
+        "name": name,
+        "description": (
+            "ForgeLM audit-generated dataset card. "
+            f"{total_samples} sample(s) across {len(splits_info)} split(s). "
+            "Inline counts/quality/PII summaries live in the parent "
+            "data_audit_report.json under the canonical audit keys."
+        ),
+        "url": str(source_path),
+        "version": _CROISSANT_VOCAB_VERSION,
+        "datePublished": generated_at,
+        "distribution": distribution,
+        "recordSet": record_sets,
+    }
+
+
 def _build_near_duplicate_summary(
     *,
     dedup_method: str,
@@ -2219,6 +2511,8 @@ def audit_dataset(
     minhash_jaccard: float = DEFAULT_MINHASH_JACCARD,
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
+    enable_pii_ml: bool = False,
+    emit_croissant: bool = False,
 ) -> AuditReport:
     """Run the audit pipeline over a JSONL file or split-keyed directory.
 
@@ -2240,6 +2534,18 @@ def audit_dataset(
             similarity terms.
         minhash_num_perm: Number of permutations for ``datasketch.MinHash``.
             Default ``128`` matches datasketch's own default.
+        enable_pii_ml: Phase 12.5 opt-in — layer Presidio's ML-NER PII
+            detector (``person`` / ``organization`` / ``location``) on
+            top of the regex detector. Requires the optional
+            ``[ingestion-pii-ml]`` extra; raises ``ImportError`` with an
+            install hint when missing so the failure surfaces before
+            any rows are scanned.
+        emit_croissant: Phase 12.5 opt-in flag — when ``True``, populate
+            the report's ``croissant`` field with a Google Croissant 1.0
+            dataset card (``@type: sc:Dataset``) so the same JSON file
+            doubles as both the EU AI Act Article 10 governance artifact
+            and a Croissant-consumer dataset card. Off by default — older
+            consumers see byte-identical output until they opt in.
         enable_quality_filter: Phase 12 opt-in flag — when ``True``, run
             the heuristic quality checks (Gopher / C4 / RefinedWeb-style)
             and surface findings under ``quality_summary``.
@@ -2257,6 +2563,11 @@ def audit_dataset(
         if not isinstance(minhash_num_perm, int) or isinstance(minhash_num_perm, bool) or minhash_num_perm <= 0:
             raise ValueError(f"minhash_num_perm must be a positive integer; got {minhash_num_perm!r}.")
         _require_datasketch()
+    if enable_pii_ml:
+        # Phase 12.5: pre-flight the optional extra so the caller learns
+        # the dep is missing BEFORE we open any files / scan any rows,
+        # mirroring the ``_require_datasketch`` shape above.
+        _require_presidio()
 
     splits_paths, resolution_notes = _resolve_input(source)
 
@@ -2283,6 +2594,7 @@ def audit_dataset(
             minhash_jaccard=minhash_jaccard,
             minhash_num_perm=minhash_num_perm,
             enable_quality_filter=enable_quality_filter,
+            enable_pii_ml=enable_pii_ml,
         )
         splits_info[split_name] = outcome.info
         signatures_by_split[split_name] = outcome.signatures
@@ -2344,9 +2656,22 @@ def audit_dataset(
         minhash_num_perm=minhash_num_perm,
     )
 
+    generated_at = datetime.now(timezone.utc).isoformat()
+    source_path_abs = os.fspath(Path(source).expanduser().resolve())
+    croissant: Dict[str, Any] = {}
+    if emit_croissant:
+        croissant = _build_croissant_metadata(
+            source_path=source_path_abs,
+            source_input=source,
+            generated_at=generated_at,
+            total_samples=total_samples,
+            splits_info=splits_info,
+            splits_paths=splits_paths,
+        )
+
     report = AuditReport(
-        generated_at=datetime.now(timezone.utc).isoformat(),
-        source_path=os.fspath(Path(source).expanduser().resolve()),
+        generated_at=generated_at,
+        source_path=source_path_abs,
         source_input=source,
         total_samples=total_samples,
         splits=splits_info,
@@ -2356,6 +2681,7 @@ def audit_dataset(
         near_duplicate_summary=near_duplicate_summary,
         secrets_summary=secrets_summary,
         quality_summary=quality_summary,
+        croissant=croissant,
         notes=notes,
     )
 
diff --git a/forgelm/wizard.py b/forgelm/wizard.py
index dd365c88..66c25da5 100644
--- a/forgelm/wizard.py
+++ b/forgelm/wizard.py
@@ -447,9 +447,74 @@ def _offer_ingest_for_directory(directory: Path) -> Optional[str]:
         return None
 
     print(f"  Ingest complete: {result.chunk_count} chunk(s) from {result.files_processed} file(s) → {out_path}")
+    # Phase 12.5: now that we have a JSONL produced from raw docs, offer to
+    # run a quality + governance audit on it before handing it to the wizard.
+    # Closes the BYOD loop — operators see length / language / dedup / PII
+    # / secrets / quality verdicts at config-time, not 30 minutes into a
+    # training run.
+    _offer_audit_for_jsonl(out_path)
     return str(out_path)
 
 
+def _offer_audit_for_jsonl(jsonl_path: Path) -> bool:
+    """Phase 12.5 wizard hook: optionally audit a JSONL the user just selected.
+
+    Mirrors :func:`_offer_ingest_for_directory`'s shape — a non-blocking
+    interactive offer that, on acceptance, runs the audit and prints a
+    short verdict before the wizard continues. Returns ``True`` when the
+    audit ran (regardless of findings) and ``False`` when the operator
+    declined or the audit could not start. Audit failures are surfaced
+    as warnings: the audit is informational, not a gate, and a malformed
+    JSONL or missing optional dep must NOT crash the wizard.
+    """
+    if not _prompt_yes_no(
+        f"\n  Run a quality + governance audit on '{jsonl_path}' before training? "
+        "(length stats, language, near-duplicates, PII, secrets — CPU-only, ~seconds)",
+        default=True,
+    ):
+        print("  Skipped — audit can be run later via:")
+        print(f"      forgelm audit {jsonl_path}")
+        return False
+
+    try:
+        # Lazy import — keeps the wizard cold-start cheap and matches the
+        # existing pattern used elsewhere in this file (see
+        # ``_offer_ingest_for_directory``'s ``ingest_path`` import).
+        from .data_audit import audit_dataset, summarize_report
+    except ImportError as exc:  # pragma: no cover — extras-skip path
+        print(f"  audit subsystem unavailable: {exc}")
+        return False
+
+    print(f"\n  Running audit on '{jsonl_path}'…")
+    try:
+        report = audit_dataset(str(jsonl_path))
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        # Filesystem / parse errors — same defensive shape we use for
+        # ``_offer_ingest_for_directory`` so the wizard never aborts on a
+        # courtesy step.
+        print(f"  Audit could not run: {exc}")
+        return False
+    except ImportError as exc:
+        # The wizard's audit hook never asks for ``--dedup-method=minhash``
+        # or any other feature gated on an optional extra; an ImportError
+        # here would only fire if a future feature inside ``audit_dataset``
+        # added an unguarded import. Surface and recover.
+        print(f"  Audit could not run (missing optional dep): {exc}")
+        return False
+    except Exception as exc:  # noqa: BLE001 — see docstring
+        # Last-ditch guard: a malformed JSONL row mid-file, a datasketch
+        # version-mismatch surfaced through datasketch's own internals, or
+        # an unanticipated edge case in a downstream audit module must NOT
+        # crash the wizard. The audit is informational; we log loudly and
+        # let the operator continue.
+        print(f"  Audit could not run: {exc}")
+        return False
+
+    print("\n  Audit complete. Summary:")
+    print(summarize_report(report, verbose=False))
+    return True
+
+
 def _prompt_dataset_path_with_ingest_offer(question: str) -> str:
     """Prompt for a dataset path; auto-offer ingestion when the user gives a directory.
 
@@ -468,10 +533,14 @@ def _prompt_dataset_path_with_ingest_offer(question: str) -> str:
             ingested = _offer_ingest_for_directory(candidate)
             if ingested is None:
                 continue
+            # ``_offer_ingest_for_directory`` already invoked the audit hook
+            # on the produced JSONL — don't double-prompt here.
             return ingested
-        # Files / Hub IDs / non-existent paths are returned verbatim. The
-        # trainer's data loader will fail later if the path is bogus —
-        # consistent with the wizard's pre-Phase-11.5 behaviour.
+        # Phase 12.5: when the path resolves to an existing local JSONL,
+        # offer to audit it before continuing. Hub IDs and non-existent
+        # paths flow through unchanged (no local file to audit).
+        if candidate.is_file() and candidate.suffix.lower() in (".jsonl", ".json"):
+            _offer_audit_for_jsonl(candidate.resolve())
         return raw
 
 
@@ -497,6 +566,8 @@ def _validate_local_jsonl(raw_path: str):
         ingested = _offer_ingest_for_directory(resolved)
         if ingested is None:
             return None
+        # ``_offer_ingest_for_directory`` already invokes the Phase 12.5
+        # audit hook on the produced JSONL — don't re-prompt here.
         return ingested
     if not resolved.is_file():
         return _BYOD_LOCAL_NOT_FOUND
@@ -509,6 +580,10 @@ def _validate_local_jsonl(raw_path: str):
     except (OSError, ValueError) as e:
         print(f"  File is not valid JSONL (first line failed to parse): {e}")
         return None
+    # Phase 12.5: confirmed local JSONL → offer to audit it before returning
+    # the path to the caller. Closes the BYOD audit loop documented in
+    # docs/roadmap/phase-12-5-backlog.md row #4.
+    _offer_audit_for_jsonl(resolved.resolve())
     return str(resolved.resolve())
 
 
diff --git a/notebooks/data_curation.ipynb b/notebooks/data_curation.ipynb
index 722ce003..adcba7dc 100644
--- a/notebooks/data_curation.ipynb
+++ b/notebooks/data_curation.ipynb
@@ -126,19 +126,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "## 2. Ingest with the markdown-aware splitter (Phase 12)\n",
-    "\n",
-    "`--strategy markdown` is the right choice when your corpus is structured\n",
-    "with headings: it splits at heading boundaries, keeps fenced code blocks\n",
-    "atomic, and **inlines the heading breadcrumb** at the top of every chunk\n",
-    "so SFT loss sees the document context. Falls back to paragraph mode for\n",
-    "non-markdown inputs (`.txt` here).\n",
-    "\n",
-    "We also pass `--secrets-mask` and `--pii-mask` (Phase 12) — secrets run\n",
-    "**before** PII masking so combined detectors don't double-count\n",
-    "overlapping spans."
-   ]
+   "source": "## 2. Ingest with the markdown-aware splitter (Phase 12)\n\n`--strategy markdown` is the right choice when your corpus is structured\nwith headings: it splits at heading boundaries, keeps fenced code blocks\natomic, and **inlines the heading breadcrumb** at the top of every chunk\nso SFT loss sees the document context. Falls back to paragraph mode for\nnon-markdown inputs (`.txt` here).\n\nWe also pass `--secrets-mask` and `--pii-mask` (Phase 12) — secrets run\n**before** PII masking so combined detectors don't double-count\noverlapping spans.\n\n> **Phase 12.5 shorthand (`v0.5.3`):** `--all-mask` is equivalent to\n> `--secrets-mask --pii-mask`. Use it when you want the\n> \"scrub-everything-detectable\" workflow without remembering both\n> flags. Composes additively with explicit flags (set-union)."
   },
   {
    "cell_type": "code",
@@ -411,22 +399,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "## What's next\n",
-    "\n",
-    "- **Train on the curated JSONL**: point any of the training notebooks at\n",
-    "  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n",
-    "  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n",
-    "  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n",
-    "    set with public datasets\n",
-    "- **Long-form guides**:\n",
-    "  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n",
-    "    — every flag, every chunking strategy, every extra\n",
-    "  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n",
-    "    — audit JSON schema, severity tiers, governance integration\n",
-    "- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n",
-    "  when you point it at a directory of raw docs (Phase 11.5+)."
-   ]
+   "source": "## What's next\n\n- **Train on the curated JSONL**: point any of the training notebooks at\n  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n    set with public datasets\n- **Long-form guides**:\n  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n    — every flag, every chunking strategy, every extra\n  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n    — audit JSON schema, severity tiers, governance integration\n- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n  when you point it at a directory of raw docs (Phase 11.5+), and as of\n  Phase 12.5 it also offers to run `forgelm audit` automatically once a\n  JSONL is selected — closes the BYOD audit loop end-to-end.\n- **Phase 12.5 audit add-ons (v0.5.3)**:\n  - `--croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/)\n    dataset card under the report's `croissant` key so the same JSON\n    file doubles as both the EU AI Act Article 10 governance artifact\n    and a Croissant-consumer dataset card.\n  - `--pii-ml` layers\n    [Presidio](https://github.com/microsoft/presidio) NER on top of\n    the regex detector — adds `person` / `organization` /\n    `location` categories to `pii_summary` / `pii_severity`. Requires\n    `pip install 'forgelm[ingestion-pii-ml]'`."
   }
  ],
  "metadata": {
@@ -441,4 +414,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index c5f40bfb..ca97fa0b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -112,6 +112,16 @@ ingestion-secrets = [
   "detect-secrets>=1.5.0,<2.0.0",
 ]
 
+# Phase 12.5: optional Presidio ML-NER PII detector. Adds the
+# unstructured-identifier categories (person / organization / location)
+# that the regex detector inherently misses. Heavyweight install
+# (≈ 50 MB spaCy model on first analyzer build), so opt-in only — the
+# regex set already covers the GDPR-mandated structured identifiers
+# (email, phone, IBAN, credit card, national IDs).
+ingestion-pii-ml = [
+  "presidio-analyzer>=2.2.0,<3.0.0",
+]
+
 # Phase 10: rich terminal rendering for the forgelm chat REPL.
 # Falls back to plain text output when not installed.
 chat = [
diff --git a/tests/test_phase12_5.py b/tests/test_phase12_5.py
new file mode 100644
index 00000000..2ca7946c
--- /dev/null
+++ b/tests/test_phase12_5.py
@@ -0,0 +1,292 @@
+"""Phase 12.5 — data curation polish backlog.
+
+Covers the four follow-up items from
+:mod:`docs/roadmap/phase-12-5-backlog.md`:
+
+1. ``forgelm ingest --all-mask`` composite shorthand (this file).
+2. Wizard "audit first" entry point (this file).
+3. ``forgelm audit --croissant`` Croissant 1.0 metadata (this file).
+4. Presidio ML-NER PII adapter via the ``[ingestion-pii-ml]`` extra
+   (this file).
+
+Each test class targets exactly one of those four items so a future
+re-shuffle can split this file along section boundaries cleanly.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from forgelm.cli import main
+
+# ---------------------------------------------------------------------------
+# Item 3 — `forgelm ingest --all-mask` composite shorthand
+# ---------------------------------------------------------------------------
+
+
+class TestIngestAllMask:
+    """Phase 12.5 #3: ``--all-mask`` is shorthand for ``--secrets-mask --pii-mask``."""
+
+    def _write_text(self, path: Path, body: str) -> None:
+        path.write_text(body, encoding="utf-8")
+
+    def test_all_mask_redacts_both_pii_and_secrets(self, tmp_path):
+        # Inert fragments at runtime so repo-wide secret scanners stay silent
+        # while the regex still has to match the canonical shape.
+        aws_key = "AKIA" + "IOSFODNN7" + "EXAMPLE"
+        email = "alice@example.com"
+        src = tmp_path / "input.txt"
+        self._write_text(src, f"contact: {email}\nkey={aws_key}\n")
+        out = tmp_path / "out.jsonl"
+
+        with patch(
+            "sys.argv",
+            ["forgelm", "ingest", str(src), "--output", str(out), "--all-mask"],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+
+        written = out.read_text(encoding="utf-8")
+        # Both kinds of redaction tokens land in the JSONL — proves the flag
+        # composes additively into both subsystems, not just one of them.
+        assert email not in written
+        assert aws_key not in written
+        assert "[REDACTED-SECRET]" in written
+        assert "[REDACTED]" in written
+
+    def test_all_mask_combines_with_individual_flags_no_error(self, tmp_path):
+        # Set-union semantics: passing ``--all-mask`` alongside ``--pii-mask``
+        # must not raise; both stay True.
+        src = tmp_path / "input.txt"
+        self._write_text(src, "alice@example.com plain text")
+        out = tmp_path / "out.jsonl"
+
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "ingest",
+                str(src),
+                "--output",
+                str(out),
+                "--all-mask",
+                "--pii-mask",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        assert "[REDACTED]" in out.read_text(encoding="utf-8")
+
+    def test_all_mask_does_not_redact_when_off(self, tmp_path):
+        # Sanity: without the flag, neither masking subsystem fires.
+        email = "alice@example.com"
+        src = tmp_path / "input.txt"
+        self._write_text(src, f"contact: {email}")
+        out = tmp_path / "out.jsonl"
+
+        with patch(
+            "sys.argv",
+            ["forgelm", "ingest", str(src), "--output", str(out)],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        assert email in out.read_text(encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Item 4 — Wizard "audit first" entry point
+# ---------------------------------------------------------------------------
+
+
+class TestWizardAuditFirstOffer:
+    """Phase 12.5 #4: when a JSONL is provided to the wizard, offer to audit it.
+
+    Mirrors the Phase 11.5 ``_offer_ingest_for_directory`` pattern: the
+    wizard surfaces the verdicts before continuing so the user can decide
+    whether to swap datasets at config-time, not at training-time.
+    """
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_audit_offer_runs_audit_when_user_accepts(self, tmp_path, capsys):
+        from forgelm.wizard import _offer_audit_for_jsonl
+
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}, {"text": "beta"}])
+
+        # Simulate "yes" to the offer.
+        with patch("forgelm.wizard._prompt_yes_no", return_value=True):
+            outcome = _offer_audit_for_jsonl(ds)
+
+        assert outcome is True
+        rendered = capsys.readouterr().out
+        assert "Audit complete" in rendered or "Audit results" in rendered
+
+    def test_audit_offer_skipped_when_user_declines(self, tmp_path, capsys):
+        from forgelm.wizard import _offer_audit_for_jsonl
+
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+
+        # Simulate "no" — must short-circuit before invoking audit_dataset.
+        with patch("forgelm.wizard._prompt_yes_no", return_value=False):
+            with patch("forgelm.data_audit.audit_dataset") as mock_audit:
+                outcome = _offer_audit_for_jsonl(ds)
+                mock_audit.assert_not_called()
+
+        assert outcome is False
+
+    def test_audit_offer_recovers_when_audit_raises(self, tmp_path, capsys):
+        # The wizard runs in interactive context; an unexpected audit failure
+        # must NOT crash the wizard. The function returns False so the caller
+        # falls through to the "continue without audit" path.
+        from forgelm.wizard import _offer_audit_for_jsonl
+
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+
+        with patch("forgelm.wizard._prompt_yes_no", return_value=True):
+            with patch(
+                "forgelm.data_audit.audit_dataset",
+                side_effect=RuntimeError("simulated audit failure"),
+            ):
+                outcome = _offer_audit_for_jsonl(ds)
+
+        assert outcome is False
+        assert "could not run" in capsys.readouterr().out.lower()
+
+
+# ---------------------------------------------------------------------------
+# Item 2 — Croissant 1.0 metadata
+# ---------------------------------------------------------------------------
+
+
+class TestCroissantMetadataExport:
+    """Phase 12.5 #2: ``--croissant`` adds a Google Croissant subset to the report."""
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_croissant_section_empty_by_default(self, tmp_path):
+        # Phase 12 precedent (``secrets_summary`` / ``quality_summary``):
+        # additive keys appear as empty dicts on default audits so consumers
+        # using ``report.get("...", {})`` keep working byte-equivalently.
+        # The Croissant block follows the same convention.
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+        out_dir = tmp_path / "audit"
+
+        with patch(
+            "sys.argv",
+            ["forgelm", "audit", str(ds), "--output", str(out_dir)],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+
+        report = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))
+        # Key may or may not be present depending on serializer; the contract
+        # is "no Croissant content unless --croissant is passed".
+        assert report.get("croissant", {}) == {}
+
+    def test_croissant_flag_emits_minimal_card(self, tmp_path):
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}, {"text": "beta"}])
+        out_dir = tmp_path / "audit"
+
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(ds),
+                "--output",
+                str(out_dir),
+                "--croissant",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+
+        report = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))
+        assert "croissant" in report
+        crois = report["croissant"]
+        # Pin the canonical Croissant 1.0 envelope so consumers / CI checks can
+        # rely on it. ``@type`` and ``@context`` are the minimum-viable subset
+        # that lets a Croissant-aware consumer parse the file without
+        # extending the audit JSON's other top-level keys.
+        assert crois.get("@type") == "sc:Dataset"
+        assert "@context" in crois
+        assert crois["@context"].get("sc") == "https://schema.org/"
+        # ForgeLM-specific fields the report already has should be carried
+        # across into the card so it stays a single self-contained document.
+        assert "name" in crois
+        assert "distribution" in crois  # describes the underlying JSONL
+
+
+# ---------------------------------------------------------------------------
+# Item 1 — Presidio adapter (``[ingestion-pii-ml]`` extra)
+# ---------------------------------------------------------------------------
+
+
+class TestPresidioPIIAdapter:
+    """Phase 12.5 #1: optional ML-NER PII signal layered onto the regex path."""
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_presidio_disabled_by_default(self, tmp_path):
+        # No --pii-ml flag → no Presidio counts; the regex path is unchanged.
+        from forgelm.data_audit import audit_dataset
+
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "Visit Acme Corp in Berlin next Monday."}])
+
+        report = audit_dataset(str(ds), output_dir=str(tmp_path / "audit"))
+        # No new ML-tier categories — the regex-only path didn't see any PII
+        # in this prose either, but we're really asserting the schema doesn't
+        # add the Presidio-only buckets when the feature is off.
+        for ml_only in ("person", "organization", "location"):
+            assert ml_only not in report.pii_summary
+
+    def test_presidio_missing_extra_raises_with_install_hint(self):
+        from forgelm.data_audit import _require_presidio
+
+        # When the extra isn't installed, the require-helper raises a typed
+        # ImportError pointing at the install command — same pattern as
+        # ``_require_datasketch`` / ``_require_detect_secrets``.
+        with patch("forgelm.data_audit._HAS_PRESIDIO", False):
+            with pytest.raises(ImportError) as exc_info:
+                _require_presidio()
+        msg = str(exc_info.value)
+        assert "ingestion-pii-ml" in msg
+        assert "pip install" in msg
+
+    def test_presidio_severity_table_exposes_ml_tiers(self):
+        # The severity table grows three new rows so the existing pii_severity
+        # block can grade ML-NER findings the same way it grades regex hits.
+        from forgelm.data_audit import PII_ML_SEVERITY
+
+        for kind in ("person", "organization", "location"):
+            assert kind in PII_ML_SEVERITY, f"missing severity tier for ML kind {kind!r}"
+        # All three categories are below the regex 'critical' tier — names /
+        # orgs / locations leak less identity than a credit-card number.
+        # Pin medium / low to keep audit verdicts stable across releases.
+        assert PII_ML_SEVERITY["person"] == "medium"
+        assert PII_ML_SEVERITY["organization"] == "low"
+        assert PII_ML_SEVERITY["location"] == "low"
diff --git a/tests/test_wizard_byod.py b/tests/test_wizard_byod.py
index 3e11c00f..c77607ae 100644
--- a/tests/test_wizard_byod.py
+++ b/tests/test_wizard_byod.py
@@ -85,7 +85,11 @@ def test_byod_rejects_malformed_jsonl(tmp_path, capsys):
 def test_byod_accepts_valid_jsonl(tmp_path):
     good = tmp_path / "good.jsonl"
     good.write_text('{"messages":[]}\n', encoding="utf-8")
-    answers = _PRELUDE + [str(good)]
+    # Phase 12.5: after a JSONL is validated, the wizard offers to run an
+    # audit on it. Decline ("n") so this test remains scoped to the BYOD
+    # validation path; the audit-offer behaviour has its own coverage in
+    # test_phase12_5.py::TestWizardAuditFirstOffer.
+    answers = _PRELUDE + [str(good), "n"]
 
     fake_result = type(
         "R",
@@ -149,7 +153,8 @@ def test_byod_expands_user_home(tmp_path, monkeypatch):
     # On POSIX Path.expanduser() reads $HOME; setting it is enough.
 
     typed = "~/data.jsonl"
-    answers = _PRELUDE + [typed]
+    # Phase 12.5: extra "n" declines the post-validation audit offer.
+    answers = _PRELUDE + [typed, "n"]
 
     fake_result = type(
         "R",
@@ -197,7 +202,8 @@ def test_byod_relative_local_path_not_misclassified_as_hub_id(tmp_path, monkeypa
     monkeypatch.chdir(tmp_path)  # so "data/train.jsonl" resolves under tmp_path
 
     typed = "data/train.jsonl"
-    answers = _PRELUDE + [typed]
+    # Phase 12.5: decline the post-validation audit offer.
+    answers = _PRELUDE + [typed, "n"]
 
     fake_result = type(
         "R",

From 734e4e781c5917269084b38c60a2cf84fcbc4bdc Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 18:15:56 +0300
Subject: [PATCH 02/12] =?UTF-8?q?fix(phase-12.5):=20apply=20review=20findi?=
 =?UTF-8?q?ngs=20=E2=80=94=20silent-failure=20guards,=20Presidio=20canonic?=
 =?UTF-8?q?als,=20Croissant=20cleanup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reviewer-driven follow-up to commit cad587d. Addresses every MAJOR
finding plus the actionable MINOR / doc-drift items. 7 new tests; 840
total pass (was 833).

MAJOR

- M1 — _require_presidio now pre-flights the analyzer build and
  re-raises spaCy's "Can't find model" OSError as ImportError with
  the two-line install recipe, so a missing en_core_web_lg surfaces
  before any rows are scanned. Previously the OSError was swallowed
  by detect_pii_ml's per-row bare-Exception, leaving the audit green
  with zero ML PII coverage and no diagnostic — direct violation of
  CLAUDE.md principle #6 (no silent failures). detect_pii_ml's catch
  is now narrowed to (ValueError, RuntimeError) so a model-load
  failure that slips through (e.g. lazy load triggered later) cannot
  be silenced; the install-hint string is consolidated into one
  module-level constant so the two failure surfaces stay in sync.
- M2 — _PRESIDIO_ENTITY_MAP trimmed from 7 keys to the 3 Presidio
  actually emits canonically (PERSON / ORGANIZATION / LOCATION).
  ORG / GPE / NORP / FAC were dead — Presidio's
  model_to_presidio_entity_mapping translates raw spaCy labels to
  canonical Presidio names before they reach AnalyzerResult, so
  raw-label keys never matched. NORP → location was also semantically
  wrong (nationality / religion / political group is a distinct
  privacy signal). The new comment explains the canonicalisation
  layer so a future maintainer doesn't reintroduce raw spaCy keys.
- M3 — Croissant version field dropped. Croissant's `version` is
  the dataset version (sc:version), not the vocabulary version;
  vocab conformance is declared via `conformsTo` (already correct).
  The audit doesn't have first-class evidence for dataset version,
  so the field is omitted entirely; operators who publish the card
  hand-edit `version` like they do `license` / `citeAs`. The
  misnamed _CROISSANT_VOCAB_VERSION constant is removed.
- M4 — `forgelm audit --output-format json` envelope now includes
  the `croissant` key (empty when --croissant is off, populated
  when on) so a CI consumer reading stdout doesn't have to re-slurp
  the on-disk file. Same precedent as secrets_summary /
  quality_summary.

MINOR

- m2 — New `--pii-ml-language LANG` flag (default "en") plumbed
  through audit_dataset → _process_split → _audit_split →
  _StreamingAggregator → detect_pii_ml. Lets a Turkish-majority
  corpus run with the matching spaCy model instead of silently
  scoring zero NER findings under English. Presidio raises a typed
  exception when no engine is registered for the requested language.
- m3 — Croissant card's `url` field now carries `source_input`
  (the as-typed string) instead of the resolved absolute filesystem
  path, and per-split `contentUrl` is the relative file_id. Cards
  published to HuggingFace / MLCommons no longer leak the auditor's
  /Users/... or /home/builder/... layout.
- m5 — Wizard's audit-offer copy now hedges against multi-million-
  row JSONL: under a 100 MB threshold it keeps the friendly "~
  seconds" tone, above it surfaces the file size and an "8-15 MB/s
  of JSONL on a single CPU" expectation so the operator can decide
  before saying yes.
- m7 — _offer_audit_for_jsonl docstring now explicitly cites
  docs/standards/error-handling.md for the bare-Exception ladder,
  making the durability of the swallow durable when the file is
  re-read in 6 months.

TESTS (+7, 840 total)

- test_croissant_section_empty_by_default now pins "key present,
  value empty" instead of the weaker "absent or empty" form.
- New: test_presidio_entity_map_only_canonical_keys — schema pin
  on the trimmed map.
- New: test_presidio_missing_spacy_model_surfaces_install_hint —
  exercises the M1 pre-flight by patching _PresidioAnalyzer to
  raise OSError; asserts ImportError carries the install recipe.
- New: test_presidio_entity_map_collapses_findings_to_buckets —
  behavioural test that would have caught the original M2 dead-key
  bug. Stubs the analyzer to emit canonical + raw spaCy labels
  and asserts only canonicals are honoured.
- New: TestCroissantMultiSplit — multi-split corpus produces one
  cr:FileObject + cr:RecordSet per split with relative contentUrl
  (anti-regression for m3).
- New: TestAllMaskSymmetric — symmetric set-union case
  (`--secrets-mask --all-mask`) so a future refactor that drops one
  branch trips a test.
- New: TestPiiMlJsonEnvelope — confirms M4: croissant present in
  stdout envelope when on, empty when off.

DOC DRIFT (5 places)

- README.md install matrix and Phase 12.5 feature line: spell out
  the spaCy model download as a separate step.
- CHANGELOG.md Phase 12.5 entry: recipe-first install instructions
  for --pii-ml, explicit OSError → ImportError contract,
  --pii-ml-language flag mention, Croissant url/contentUrl path
  leak fix, version field omission rationale.
- docs/guides/data_audit.md and docs/guides/data_audit-tr.md:
  replaced "Presidio's first analyzer build downloads a spaCy
  model (~ 50 MB)" — wrong on every supported Presidio version —
  with a two-step install block + non-English language hint.
- notebooks/data_curation.ipynb "What's next" cell: same fix.

Verification: ruff clean (78 files), 840 tests pass (13 skipped),
7/7 bilingual H2 parity, --pii-ml / --pii-ml-language / --croissant
all surface in `forgelm audit --help`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                  |  52 ++++++--
 README.md                     |   4 +-
 docs/guides/data_audit-tr.md  |  30 ++++-
 docs/guides/data_audit.md     |  28 +++-
 forgelm/cli.py                |  29 +++-
 forgelm/data_audit.py         | 164 ++++++++++++++++-------
 forgelm/wizard.py             |  57 +++++++-
 notebooks/data_curation.ipynb |   2 +-
 tests/test_phase12_5.py       | 242 +++++++++++++++++++++++++++++++++-
 9 files changed, 528 insertions(+), 80 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b7f34e7..b4f95c50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,20 +26,44 @@ additive surface on top of the Phase 12 ingestion + audit lineage.
   (same precedent as `secrets_summary` / `quality_summary`). Lets the
   same JSON file double as both the EU AI Act Article 10 governance
   artifact and a Croissant-consumer dataset card.
-- **`forgelm audit --pii-ml`** + new `[ingestion-pii-ml]` extra
-  (item #1) — opt-in [Presidio](https://github.com/microsoft/presidio)
-  ML-NER PII detector layered on top of the existing regex detector.
-  Adds the unstructured-identifier categories the regex inherently
-  misses (`person`, `organization`, `location`) into the same
-  `pii_summary` / `pii_severity` blocks under disjoint category
-  names. Severity tiers in the new `PII_ML_SEVERITY` table:
-  `person → medium`, `organization → low`, `location → low` (deliberately
-  below the regex `critical`/`high` tiers because NER false-positive
-  rates are materially higher than regex-anchored detection).
-  Pre-flight check raises `ImportError("...pip install
-  'forgelm[ingestion-pii-ml]'")` when the extra is missing — failures
-  surface before any rows are scanned. Per-row Presidio failures are
-  swallowed so a single malformed row never blocks the audit.
+  - `url` and `contentUrl` use the as-typed input string and the
+    relative split filename, never the resolved absolute filesystem
+    path, so cards published to HuggingFace / MLCommons don't leak
+    the auditor's local layout.
+  - Croissant `version` (`sc:version`, dataset version) is omitted
+    deliberately — the audit doesn't have first-class evidence for
+    it; vocab conformance is declared via `conformsTo`. Operators
+    that publish hand-edit `version` like they do `license` /
+    `citeAs`.
+  - The card is now also surfaced in the `--output-format json`
+    stdout envelope alongside the on-disk report so CI consumers
+    don't need a second file slurp.
+- **`forgelm audit --pii-ml [--pii-ml-language LANG]`** + new
+  `[ingestion-pii-ml]` extra (item #1) — opt-in
+  [Presidio](https://github.com/microsoft/presidio) ML-NER PII detector
+  layered on top of the existing regex detector. Adds the
+  unstructured-identifier categories the regex inherently misses
+  (`person`, `organization`, `location`) into the same `pii_summary` /
+  `pii_severity` blocks under disjoint category names. Severity tiers
+  in the new `PII_ML_SEVERITY` table: `person → medium`,
+  `organization → low`, `location → low` (deliberately below the regex
+  `critical`/`high` tiers because NER false-positive rates are
+  materially higher than regex-anchored detection). The pre-flight
+  check covers BOTH the missing-extra branch AND the missing-spaCy-model
+  branch — `presidio-analyzer` does *not* transitively ship a spaCy
+  NER model, so the install recipe is now two lines:
+  ```
+  pip install 'forgelm[ingestion-pii-ml]'
+  python -m spacy download en_core_web_lg
+  ```
+  Without either, `forgelm audit --pii-ml` raises `ImportError` with
+  the recipe before any rows are scanned. Per-row Presidio failures
+  are scoped to `(ValueError, RuntimeError)` so a single malformed row
+  never blocks the audit, but a deep `OSError` from a missing model
+  surfaces loudly instead of silently scoring zero ML coverage.
+  `--pii-ml-language` (default `"en"`) lets non-English corpora point
+  at the matching spaCy model; Presidio raises a typed exception when
+  no engine is registered for the requested language.
 - **Wizard "audit first" entry point** (item #4) — when the wizard
   resolves a JSONL (either typed directly or produced by the
   Phase 11.5 `_offer_ingest_for_directory` ingest flow), it now offers
diff --git a/README.md b/README.md
index d90a461f..320eb915 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@
 - **PDF Page Header/Footer Dedup (v0.5.1)**: Lines that recur on ≥ 70 % of PDF pages (watermarks, page numbers, copyright lines) are stripped automatically — the audit's near-duplicate counts stop misfiring on long policy / book PDFs.
 - **Dataset Audit**: `forgelm audit data/sft.jsonl --output ./audit/` — produces `data_audit_report.json` with sample count, length distribution, top-3 language detection, LSH-banded near-duplicate rate (`O(n × k)` typical case, exact recall at the default Hamming threshold; v0.5.2 added optional **MinHash LSH** via `--dedup-method minhash` for >50K-row corpora), cross-split leakage check, null/empty rate, and PII flag counts with **severity tiers** (critical / high / medium / low + worst-tier verdict). v0.5.2 also added an always-on **secrets/credential scan** covering the nine families enumerated in `forgelm.data_audit.SECRET_TYPES` — AWS access keys, GitHub tokens, Slack tokens, OpenAI API keys, Google API keys, JWTs, full OpenSSH private-key blocks, full PGP private-key blocks, and Azure storage connection strings — and an opt-in **heuristic quality filter** (`--quality-filter`). CPU-only; streaming JSONL reader keeps memory bounded on multi-million-row splits; feeds EU AI Act Article 10 governance artifact automatically when present at training time. Legacy `--data-audit` flag still works as a deprecation alias.
 - **Secrets-Aware Ingest (v0.5.2)**: `forgelm ingest … --secrets-mask` scrubs credentials before chunks land in the JSONL — fine-tuning on text containing real API keys memorises them at training time. Pairs with `--pii-mask`; secrets run first so combined detectors don't double-count overlapping spans.
-- **Phase 12.5 polish (v0.5.3)**: `forgelm ingest --all-mask` shorthand for combined PII + secrets scrubbing; `forgelm audit --croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card alongside the existing report; `forgelm audit --pii-ml` layers [Presidio](https://github.com/microsoft/presidio) NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra (`person` / `organization` / `location` categories merged into the same `pii_severity` block); the wizard now offers to run `forgelm audit` automatically after a JSONL is selected (BYOD onboarding closes the audit loop).
+- **Phase 12.5 polish (v0.5.3)**: `forgelm ingest --all-mask` shorthand for combined PII + secrets scrubbing; `forgelm audit --croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card alongside the existing report; `forgelm audit --pii-ml [--pii-ml-language LANG]` layers [Presidio](https://github.com/microsoft/presidio) NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra **plus a separate `python -m spacy download en_core_web_lg`** step (or the matching model for the chosen language); the wizard now offers to run `forgelm audit` automatically after a JSONL is selected (BYOD onboarding closes the audit loop).
 
 ### Quickstart Layer (v0.4.5)
 - **One-Command Templates**: `forgelm quickstart customer-support` — 4 bundled templates (SFT customer-support, code-assistant, medical-qa-tr, GRPO math-reasoning) plus a bring-your-own-data domain-expert scaffold. Auto-downsizes models on small GPUs.
@@ -173,7 +173,7 @@ pip install "forgelm[merging]"           # mergekit model merging
 pip install "forgelm[ingestion]"         # PDF/DOCX/EPUB/Markdown → JSONL + langdetect + xxhash
 pip install "forgelm[ingestion-scale]"   # MinHash LSH dedup (datasketch) for >50K-row corpora
 pip install "forgelm[ingestion-secrets]" # detect-secrets scanner for SFT corpora (falls back to regex if absent)
-pip install "forgelm[ingestion-pii-ml]"  # Presidio ML-NER for person/organization/location PII (Phase 12.5)
+pip install "forgelm[ingestion-pii-ml]"  # Presidio ML-NER for person/organization/location PII (Phase 12.5; ALSO needs `python -m spacy download en_core_web_lg`)
 pip install "forgelm[export]"            # GGUF export via llama-cpp-python
 pip install "forgelm[chat]"              # Rich terminal rendering for `forgelm chat`
 ```
diff --git a/docs/guides/data_audit-tr.md b/docs/guides/data_audit-tr.md
index 980370b1..54c9e5d3 100644
--- a/docs/guides/data_audit-tr.md
+++ b/docs/guides/data_audit-tr.md
@@ -367,10 +367,32 @@ yüksektir — bu yüzden ML katmanları regex'in `critical` / `high`
 katlarının altında bilinçli konumlandırılır. Bir ML bulgusunu sert
 bir gate olarak değerlendirmeden önce satır bazında span'leri inceleyin.
 
-Presidio'nun ilk analyzer build'i bir spaCy İngilizce NER modeli
-indirir (~ 50 MB, tek seferlik). Sonraki çalışmalar cached modeli
-yeniden kullanır. Adaptör yalnızca opt-in; `--pii-ml` olmadan audit
-zero-extra-deps regex yolunda kalır.
+**İki adımlı kurulum.** `presidio-analyzer` paketi spaCy NER modelini
+transitively içermez — tek seferlik ayrı bir indirme:
+
+```bash
+pip install 'forgelm[ingestion-pii-ml]'
+python -m spacy download en_core_web_lg   # ~ 50 MB; gerekli
+```
+
+Model yoksa `forgelm audit --pii-ml` hiçbir satır taranmadan **önce**
+aynı install hint ile `ImportError` raise eder
+(`forgelm.data_audit._require_presidio`'daki pre-flight, spaCy'nin
+`OSError`'unu yakalayıp typed install error'a dönüştürür). Bu fail-loud
+davranış bilinçli — önceki prototiplerde model eksikken sıfır ML
+bulgusu sessizce raporlanıyordu, opt-in bir detector için kritik bir
+compliance kör noktası.
+
+İngilizce olmayan korpuslar için eşleşen spaCy modelini kurup dil
+kodunu geçirin:
+
+```bash
+python -m spacy download xx_ent_wiki_sm        # çok dilli, daha küçük
+forgelm audit data/ --pii-ml --pii-ml-language xx
+```
+
+Adaptör yalnızca opt-in; `--pii-ml` olmadan audit zero-extra-deps
+regex yolunda kalır.
 
 ---
 
diff --git a/docs/guides/data_audit.md b/docs/guides/data_audit.md
index 0052b1b6..b02f9176 100644
--- a/docs/guides/data_audit.md
+++ b/docs/guides/data_audit.md
@@ -364,9 +364,31 @@ detection, so the ML tiers sit deliberately below the regex
 `critical`/`high` floors — review the per-row spans before treating an
 ML finding as a hard gate.
 
-Presidio's first analyzer build downloads a spaCy English NER model
-(~ 50 MB, one-time). Subsequent runs reuse the cached model. The
-adapter is opt-in only; without `--pii-ml` the audit stays on the
+**Two-step install.** `presidio-analyzer` does **not** transitively
+ship a spaCy NER model — that's a separate one-time download:
+
+```bash
+pip install 'forgelm[ingestion-pii-ml]'
+python -m spacy download en_core_web_lg   # ~ 50 MB; required
+```
+
+Without the model, `forgelm audit --pii-ml` raises an `ImportError`
+with the same install hint **before** any rows are scanned (the
+pre-flight check in `forgelm.data_audit._require_presidio` catches
+spaCy's `OSError` and re-raises it as the typed install error). This
+fail-loud behaviour exists because earlier prototypes silently scored
+zero ML findings on a missing model — a critical compliance blind
+spot for an opt-in detector that operators expect to actually run.
+
+For non-English corpora, install the matching spaCy model and pass
+the language code:
+
+```bash
+python -m spacy download xx_ent_wiki_sm        # multilingual, smaller
+forgelm audit data/ --pii-ml --pii-ml-language xx
+```
+
+The adapter is opt-in only; without `--pii-ml` the audit stays on the
 zero-extra-deps regex path.
 
 ---
diff --git a/forgelm/cli.py b/forgelm/cli.py
index 07d8413a..7ceeba7a 100644
--- a/forgelm/cli.py
+++ b/forgelm/cli.py
@@ -491,8 +491,23 @@ def _add_audit_subcommand(subparsers) -> None:
         help=(
             "Phase 12.5 opt-in: layer Presidio's ML-NER PII detection (person / organization / "
             "location categories) on top of the regex detector. Requires the optional "
-            "'forgelm[ingestion-pii-ml]' extra; raises an install-hint ImportError when missing. "
-            "Findings merge into pii_summary / pii_severity under disjoint category names."
+            "'forgelm[ingestion-pii-ml]' extra AND a spaCy NER model "
+            "(`python -m spacy download en_core_web_lg`); raises an install-hint ImportError "
+            "when either is missing. Findings merge into pii_summary / pii_severity under "
+            "disjoint category names."
+        ),
+    )
+    p.add_argument(
+        "--pii-ml-language",
+        type=str,
+        default="en",
+        metavar="LANG",
+        help=(
+            "Phase 12.5: language code passed to Presidio's NLP engine when --pii-ml is on "
+            "(default: 'en'). Presidio raises a typed exception if no engine is registered for "
+            "the requested language — surface it to the operator instead of silently "
+            "running an English NER on a non-English corpus. Set to e.g. 'tr' on a Turkish "
+            "corpus AND make sure the matching spaCy model is installed."
         ),
     )
     _add_common_subparser_flags(p, include_output_format=True)
@@ -1387,6 +1402,7 @@ def _run_data_audit(
     minhash_jaccard: Optional[float] = None,
     enable_quality_filter: bool = False,
     enable_pii_ml: bool = False,
+    pii_ml_language: str = "en",
     emit_croissant: bool = False,
     invoked_via_legacy_flag: bool = False,
 ) -> None:
@@ -1423,6 +1439,7 @@ def _run_data_audit(
             minhash_jaccard=jaccard,
             enable_quality_filter=enable_quality_filter,
             enable_pii_ml=enable_pii_ml,
+            pii_ml_language=pii_ml_language,
             emit_croissant=emit_croissant,
         )
     except OSError as exc:
@@ -1469,6 +1486,13 @@ def _run_data_audit(
             "near_duplicate_pairs_per_split": report.near_duplicate_summary.get("pairs_per_split", {}),
             "near_duplicate_summary": report.near_duplicate_summary,
             "cross_split_leakage_pairs": list((report.cross_split_overlap.get("pairs") or {}).keys()),
+            # Phase 12.5: Croissant 1.0 dataset card. Empty dict when the
+            # ``--croissant`` flag was not passed — same additive shape as
+            # ``secrets_summary`` / ``quality_summary``. Surfacing it here
+            # mirrors the on-disk report so a CI step that reads stdout
+            # via ``--output-format json`` does not need to slurp the
+            # file separately.
+            "croissant": report.croissant,
             "notes": report.notes,
         }
         print(json.dumps(summary, indent=2, ensure_ascii=False))
@@ -1496,6 +1520,7 @@ def _run_audit_cmd(args, output_format: str) -> None:
         minhash_jaccard=getattr(args, "jaccard_threshold", None),
         enable_quality_filter=getattr(args, "quality_filter", False),
         enable_pii_ml=getattr(args, "pii_ml", False),
+        pii_ml_language=getattr(args, "pii_ml_language", "en"),
         emit_croissant=getattr(args, "croissant", False),
         invoked_via_legacy_flag=False,
     )
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index 0e3cb4da..8aa7f00a 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -406,48 +406,78 @@ def _get_presidio_analyzer() -> Any:
     """Return a cached :class:`presidio_analyzer.AnalyzerEngine` instance.
 
     Raises:
-        ImportError: when the ``[ingestion-pii-ml]`` extra is missing.
-            Also surfaced through the public :func:`_require_presidio`
-            helper so callers that gate on Presidio availability up
-            front can produce a clean message before processing starts.
+        ImportError: when the ``[ingestion-pii-ml]`` extra is missing OR
+            when ``presidio-analyzer`` is installed but the spaCy NER
+            model it depends on is not — both surfaces produce the same
+            actionable install hint via :func:`_require_presidio` so
+            the operator never sees a deep ``OSError`` from spaCy
+            mid-stream.
     """
-    _require_presidio()
+    if not _HAS_PRESIDIO:
+        raise ImportError(_PRESIDIO_INSTALL_HINT)
     return _PresidioAnalyzer()
 
 
-def _require_presidio() -> None:
-    """Raise a clear ImportError when the optional ML-NER backend is missing.
+# A single, canonical install hint shared by the import-sentinel branch
+# and the spaCy-model-missing branch.  Both failure modes look identical
+# to the operator (``--pii-ml`` doesn't work; here is the recipe), so
+# we keep the message in one place to avoid drift.
+_PRESIDIO_INSTALL_HINT: str = (
+    "Presidio PII ML detection requires the 'ingestion-pii-ml' extra "
+    "AND a spaCy English NER model. Install with:\n"
+    "  pip install 'forgelm[ingestion-pii-ml]'\n"
+    "  python -m spacy download en_core_web_lg"
+)
 
-    Mirrors :func:`_require_datasketch` so any audit code path that
-    needs Presidio fails with an actionable install hint instead of a
-    deep ``AttributeError`` the operator can't act on.
+
+def _require_presidio() -> None:
+    """Raise a clear ImportError when the optional ML-NER backend is unusable.
+
+    Mirrors :func:`_require_datasketch` but extends the check to model
+    availability: a fresh ``[ingestion-pii-ml]`` install does **not**
+    transitively ship the spaCy NER model — that's a separate
+    ``python -m spacy download en_core_web_lg`` step. Without the model
+    the first per-row analyzer call would raise ``OSError`` deep inside
+    spaCy and (because :func:`detect_pii_ml`'s last-ditch ``except``
+    swallows per-row failures) the audit would silently report zero
+    ML PII coverage. Pre-flighting the analyzer build here surfaces
+    the missing-model case before any rows are scanned.
     """
     if not _HAS_PRESIDIO:
+        raise ImportError(_PRESIDIO_INSTALL_HINT)
+    try:
+        _get_presidio_analyzer()
+    except OSError as exc:
+        # spaCy raises ``OSError`` ("Can't find model 'en_core_web_lg'")
+        # when the model package isn't on the import path. Re-raise as
+        # ImportError so callers that already catch ImportError for the
+        # extras-missing branch see the same exception class for both
+        # failure modes.
+        _get_presidio_analyzer.cache_clear()
         raise ImportError(
-            "Presidio PII ML detection requires the 'ingestion-pii-ml' extra. "
-            "Install with: pip install 'forgelm[ingestion-pii-ml]'"
-        )
-
-
-# Map of Presidio's canonical entity-type strings (which mirror the
-# spaCy NER label set) to the ForgeLM category names that feed
-# :data:`PII_ML_SEVERITY` / :data:`PII_ML_TYPES`.  Keys come from
-# Presidio's recognizer registry; multiple Presidio labels can collapse
-# into a single ForgeLM bucket (``GPE`` / ``LOCATION`` both → ``location``)
-# because the audit's downstream consumer (compliance reviewer) doesn't
-# need finer granularity than person / organization / location.
+            f"Presidio analyzer build failed (likely missing spaCy NER model): {exc}\n{_PRESIDIO_INSTALL_HINT}"
+        ) from exc
+
+
+# Presidio canonicalises spaCy NER labels through its
+# ``model_to_presidio_entity_mapping`` (PER/PERSON → PERSON,
+# LOC/GPE → LOCATION, ORG → ORGANIZATION, NORP → NRP); what
+# ``analyzer.analyze()`` emits as ``entity_type`` is the canonical
+# Presidio name, never the raw spaCy tag. Keep this map keyed on
+# canonical Presidio names only so a future maintainer doesn't read
+# dead spaCy keys as live coverage.  ``NRP`` (nationality / religious /
+# political group) is deliberately not mapped — it's a distinct privacy
+# signal from ``location`` and Presidio's NRP precision is too low to
+# grade as ``person`` without further work; revisit if compliance
+# reviewers ask for it.
 _PRESIDIO_ENTITY_MAP: Dict[str, str] = {
     "PERSON": "person",
-    "ORG": "organization",
     "ORGANIZATION": "organization",
     "LOCATION": "location",
-    "GPE": "location",
-    "NORP": "location",
-    "FAC": "location",
 }
 
 
-def detect_pii_ml(text: Any) -> Dict[str, int]:
+def detect_pii_ml(text: Any, *, language: str = "en") -> Dict[str, int]:
     """ML-NER PII detector — counts ``person`` / ``organization`` / ``location`` spans.
 
     Layered ON TOP of :func:`detect_pii` (regex). The two detectors
@@ -456,15 +486,27 @@ def detect_pii_ml(text: Any) -> Dict[str, int]:
     unstructured-identifier signal (ML) without double-counting the
     same span.
 
+    Args:
+        text: Per-row payload; defensive against ``None`` / numbers / dicts.
+        language: Presidio NLP-engine language code. Default ``"en"``.
+            Set via :func:`audit_dataset`'s ``pii_ml_language`` parameter.
+            Presidio raises a typed exception if no NLP engine is
+            registered for the requested language — surfaced as the
+            same per-row swallow as any other analyzer failure.
+
     Returns an empty dict when:
     * ``text`` is not a non-empty string (defensive — callers pass JSONL
       payloads that may be ``None`` / numbers / dicts);
     * Presidio is not installed (the caller must opt in explicitly via
       :func:`_require_presidio` if they want a hard failure);
-    * the analyzer raises on the input — Presidio can fail on
-      pathological strings, model-load races, or version skews. We
-      swallow per-row failures and return zero counts so a single bad
-      row never blocks the audit.
+    * the analyzer raises a recoverable error on this row — pathological
+      strings, transient NLP engine state, language-specific recogniser
+      misses. We swallow narrowly-typed failures (``ValueError`` /
+      ``RuntimeError``) and let everything else propagate so genuine
+      bugs (``OSError`` on missing model, ``MemoryError``, ``KeyboardInterrupt``)
+      stay visible. The pre-flight in :func:`_require_presidio` covers
+      the missing-model case so it never reaches this path in the
+      common run.
     """
     if not isinstance(text, str) or not text.strip():
         return {}
@@ -472,11 +514,15 @@ def detect_pii_ml(text: Any) -> Dict[str, int]:
         return {}
     try:
         analyzer = _get_presidio_analyzer()
-        results = analyzer.analyze(text=text, language="en")
-    except Exception:  # pragma: no cover — Presidio raises on edge cases
-        # Per-row resilience: a single malformed row must not abort the
-        # audit. The aggregator counts no ML PII for this row, which is
-        # the correct behaviour for opt-in best-effort detection.
+        results = analyzer.analyze(text=text, language=language)
+    except (ValueError, RuntimeError):  # pragma: no cover — Presidio edge cases
+        # Per-row resilience for the narrow class of failures Presidio
+        # raises on bad input or transient engine state. ``OSError`` is
+        # deliberately NOT caught here — that's the missing-spaCy-model
+        # signal and ``_require_presidio``'s pre-flight should have
+        # converted it to ImportError before any row was scanned. If
+        # one slips through (e.g. lazy model load triggered later),
+        # surfacing it loudly is the correct behaviour.
         return {}
     counts: Dict[str, int] = {}
     for finding in results:
@@ -1514,6 +1560,7 @@ class _StreamingAggregator:
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM
     # Phase 12.5: opt-in ML-NER PII detection (Presidio). Off by default.
     enable_pii_ml: bool = False
+    pii_ml_language: str = "en"
     enable_quality_filter: bool = False
 
 
@@ -1558,7 +1605,10 @@ def _record_text_metrics(agg: _StreamingAggregator, payload: str) -> None:
         # bucket. The category names are disjoint from the regex set
         # (person / organization / location vs. email / phone / *_id),
         # so the merged counts present both views without double-counting.
-        for kind, count in detect_pii_ml(payload).items():
+        # ``pii_ml_language`` is plumbed through so a Turkish-majority
+        # corpus can be audited with a Turkish spaCy model rather than
+        # silently scoring zero NER findings under English.
+        for kind, count in detect_pii_ml(payload, language=agg.pii_ml_language).items():
             agg.pii_counts[kind] = agg.pii_counts.get(kind, 0) + count
     for kind, count in detect_secrets(payload).items():
         agg.secrets_counts[kind] = agg.secrets_counts.get(kind, 0) + count
@@ -1730,6 +1780,7 @@ def _audit_split(
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
     enable_pii_ml: bool = False,
+    pii_ml_language: str = "en",
 ) -> Tuple[Dict[str, Any], List[Any], Dict[str, int], int, int]:
     """Stream a JSONL split into a metrics record.
 
@@ -1768,6 +1819,7 @@ def _audit_split(
         minhash_num_perm=minhash_num_perm,
         enable_quality_filter=enable_quality_filter,
         enable_pii_ml=enable_pii_ml,
+        pii_ml_language=pii_ml_language,
     )
     for row, parse_err, decode_err in _read_jsonl_split(path):
         _ingest_row(agg, row, parse_err, decode_err)
@@ -2086,6 +2138,7 @@ def _process_split(
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
     enable_pii_ml: bool = False,
+    pii_ml_language: str = "en",
 ) -> _SplitOutcome:
     """Stream + audit one split. Tolerates per-split filesystem failures.
 
@@ -2106,6 +2159,7 @@ def _process_split(
             minhash_num_perm=minhash_num_perm,
             enable_quality_filter=enable_quality_filter,
             enable_pii_ml=enable_pii_ml,
+            pii_ml_language=pii_ml_language,
         )
     except OSError as exc:
         logger.warning("Could not read split '%s' (%s): %s — skipping.", split_name, path, exc)
@@ -2349,7 +2403,6 @@ def _build_quality_summary(
 # parse the block without modification, while the rest of the audit JSON
 # stays untouched. The card lives under the new ``croissant`` key on the
 # ``AuditReport`` dataclass; callers that don't want it never see it.
-_CROISSANT_VOCAB_VERSION = "1.0"
 _CROISSANT_CONTEXT: Dict[str, Any] = {
     "@language": "en",
     "@vocab": "https://schema.org/",
@@ -2418,15 +2471,21 @@ def _build_croissant_metadata(
     distribution: List[Dict[str, Any]] = []
     record_sets: List[Dict[str, Any]] = []
     for split_name, info in splits_info.items():
-        split_path = splits_paths.get(split_name)
         sample_count = int(info.get("sample_count", 0))
         file_id = f"{split_name}.jsonl"
+        # ``contentUrl`` deliberately uses the *file_id* (relative
+        # filename), not the absolute filesystem path: cards published
+        # to HuggingFace / MLCommons must not leak the auditor's local
+        # ``/Users/...`` / ``/home/builder/...`` layout. Operators that
+        # want a real ``contentUrl`` (HF Hub URL, S3 path, etc.) can
+        # hand-edit the field at publish time the same way they do
+        # ``license`` / ``citeAs``.
         distribution.append(
             {
                 "@type": "cr:FileObject",
                 "@id": file_id,
                 "name": file_id,
-                "contentUrl": str(split_path) if split_path is not None else file_id,
+                "contentUrl": file_id,
                 "encodingFormat": "application/jsonlines",
                 "description": f"Split {split_name!r}: {sample_count} sample(s).",
             }
@@ -2462,6 +2521,14 @@ def _build_croissant_metadata(
             }
         )
 
+    # ``url`` carries ``source_input`` (as-typed) rather than the
+    # resolved absolute path — see ``contentUrl`` rationale above.
+    # ``version`` (``sc:version``) describes the *dataset* version,
+    # not the Croissant vocabulary version (vocab conformance is
+    # declared via ``conformsTo``). The audit doesn't have first-class
+    # evidence for dataset version, so the field is omitted; operators
+    # that publish the card hand-edit ``version`` like they do
+    # ``license`` / ``citeAs``.
     return {
         "@context": dict(_CROISSANT_CONTEXT),
         "@type": "sc:Dataset",
@@ -2473,8 +2540,7 @@ def _build_croissant_metadata(
             "Inline counts/quality/PII summaries live in the parent "
             "data_audit_report.json under the canonical audit keys."
         ),
-        "url": str(source_path),
-        "version": _CROISSANT_VOCAB_VERSION,
+        "url": source_input,
         "datePublished": generated_at,
         "distribution": distribution,
         "recordSet": record_sets,
@@ -2512,6 +2578,7 @@ def audit_dataset(
     minhash_num_perm: int = DEFAULT_MINHASH_NUM_PERM,
     enable_quality_filter: bool = False,
     enable_pii_ml: bool = False,
+    pii_ml_language: str = "en",
     emit_croissant: bool = False,
 ) -> AuditReport:
     """Run the audit pipeline over a JSONL file or split-keyed directory.
@@ -2537,9 +2604,15 @@ def audit_dataset(
         enable_pii_ml: Phase 12.5 opt-in — layer Presidio's ML-NER PII
             detector (``person`` / ``organization`` / ``location``) on
             top of the regex detector. Requires the optional
-            ``[ingestion-pii-ml]`` extra; raises ``ImportError`` with an
-            install hint when missing so the failure surfaces before
-            any rows are scanned.
+            ``[ingestion-pii-ml]`` extra AND a spaCy NER model
+            (``python -m spacy download en_core_web_lg``); raises
+            ``ImportError`` with the install hint when either is
+            missing so the failure surfaces before any rows are scanned.
+        pii_ml_language: Phase 12.5 — language code passed to Presidio's
+            NLP engine. Default ``"en"``. Set to ``"tr"`` (or whichever
+            spaCy model the operator has loaded) for non-English
+            corpora; Presidio raises a typed exception when no engine
+            is registered for the requested language.
         emit_croissant: Phase 12.5 opt-in flag — when ``True``, populate
             the report's ``croissant`` field with a Google Croissant 1.0
             dataset card (``@type: sc:Dataset``) so the same JSON file
@@ -2595,6 +2668,7 @@ def audit_dataset(
             minhash_num_perm=minhash_num_perm,
             enable_quality_filter=enable_quality_filter,
             enable_pii_ml=enable_pii_ml,
+            pii_ml_language=pii_ml_language,
         )
         splits_info[split_name] = outcome.info
         signatures_by_split[split_name] = outcome.signatures
diff --git a/forgelm/wizard.py b/forgelm/wizard.py
index 66c25da5..43fd0fdc 100644
--- a/forgelm/wizard.py
+++ b/forgelm/wizard.py
@@ -456,6 +456,15 @@ def _offer_ingest_for_directory(directory: Path) -> Optional[str]:
     return str(out_path)
 
 
+_AUDIT_LARGE_FILE_THRESHOLD_BYTES: int = 100 * 1024 * 1024  # 100 MB
+"""Threshold above which the wizard's audit offer warns operators that the
+scan can take real time. Below 100 MB the runtime is dominated by Python
+startup; above 100 MB the dedup signature pass becomes a meaningful
+fraction of wall clock and the operator deserves to know before saying
+yes. Tuned empirically against the streaming reader's throughput
+(simhash + LSH banding ≈ 8-15 MB/s of JSONL on a single CPU)."""
+
+
 def _offer_audit_for_jsonl(jsonl_path: Path) -> bool:
     """Phase 12.5 wizard hook: optionally audit a JSONL the user just selected.
 
@@ -466,12 +475,41 @@ def _offer_audit_for_jsonl(jsonl_path: Path) -> bool:
     declined or the audit could not start. Audit failures are surfaced
     as warnings: the audit is informational, not a gate, and a malformed
     JSONL or missing optional dep must NOT crash the wizard.
+
+    Exception ladder (per :doc:`docs/standards/error-handling.md`'s
+    "log-and-swallow is permitted only on explicitly-non-fatal paths"
+    rule): the courtesy audit is one such path — the wizard's contract
+    is "produce a config", not "vouch for the dataset". The bare
+    ``except Exception`` at the bottom of the ladder is the exception
+    the standard mentions, scoped to a single short call (not a
+    library-wide swallow), and explicitly re-raises ``BaseException``
+    subclasses (``KeyboardInterrupt``, ``SystemExit``) by virtue of
+    matching ``Exception`` only.
     """
-    if not _prompt_yes_no(
-        f"\n  Run a quality + governance audit on '{jsonl_path}' before training? "
-        "(length stats, language, near-duplicates, PII, secrets — CPU-only, ~seconds)",
-        default=True,
-    ):
+    # File-size-aware copy: small JSONL → "~ seconds" is honest; large
+    # JSONL → warn the operator the scan takes real time before they
+    # commit to it. The streaming audit doesn't load the whole file into
+    # memory, so accepting on a large file is safe — just slow.
+    try:
+        size_bytes = jsonl_path.stat().st_size
+    except OSError:
+        size_bytes = 0  # Fall through to the small-file copy; the
+        # subsequent ``audit_dataset`` call surfaces the real OSError.
+    if size_bytes > _AUDIT_LARGE_FILE_THRESHOLD_BYTES:
+        size_mb = size_bytes / (1024 * 1024)
+        prompt = (
+            f"\n  Run a quality + governance audit on '{jsonl_path}' "
+            f"({size_mb:.0f} MB) before training? Scan is CPU-only and "
+            "streams the file; runtime depends on size (≈ 8–15 MB/s of "
+            "JSONL on a single CPU)."
+        )
+    else:
+        prompt = (
+            f"\n  Run a quality + governance audit on '{jsonl_path}' "
+            "before training? (length stats, language, near-duplicates, "
+            "PII, secrets — CPU-only, runtime depends on dataset size)"
+        )
+    if not _prompt_yes_no(prompt, default=True):
         print("  Skipped — audit can be run later via:")
         print(f"      forgelm audit {jsonl_path}")
         return False
@@ -487,6 +525,11 @@ def _offer_audit_for_jsonl(jsonl_path: Path) -> bool:
 
     print(f"\n  Running audit on '{jsonl_path}'…")
     try:
+        # Default flags only — the courtesy audit doesn't reach for
+        # ``--quality-filter`` / ``--pii-ml`` / ``--croissant`` because
+        # those need either an optional extra or a configuration choice
+        # the wizard hasn't asked the operator about. Operators that
+        # want the richer audit run ``forgelm audit`` directly.
         report = audit_dataset(str(jsonl_path))
     except (FileNotFoundError, ValueError, OSError) as exc:
         # Filesystem / parse errors — same defensive shape we use for
@@ -506,7 +549,9 @@ def _offer_audit_for_jsonl(jsonl_path: Path) -> bool:
         # version-mismatch surfaced through datasketch's own internals, or
         # an unanticipated edge case in a downstream audit module must NOT
         # crash the wizard. The audit is informational; we log loudly and
-        # let the operator continue.
+        # let the operator continue. ``KeyboardInterrupt`` /
+        # ``SystemExit`` propagate by virtue of being ``BaseException``
+        # subclasses, so Ctrl-C still aborts the wizard cleanly.
         print(f"  Audit could not run: {exc}")
         return False
 
diff --git a/notebooks/data_curation.ipynb b/notebooks/data_curation.ipynb
index adcba7dc..14a92109 100644
--- a/notebooks/data_curation.ipynb
+++ b/notebooks/data_curation.ipynb
@@ -399,7 +399,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "## What's next\n\n- **Train on the curated JSONL**: point any of the training notebooks at\n  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n    set with public datasets\n- **Long-form guides**:\n  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n    — every flag, every chunking strategy, every extra\n  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n    — audit JSON schema, severity tiers, governance integration\n- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n  when you point it at a directory of raw docs (Phase 11.5+), and as of\n  Phase 12.5 it also offers to run `forgelm audit` automatically once a\n  JSONL is selected — closes the BYOD audit loop end-to-end.\n- **Phase 12.5 audit add-ons (v0.5.3)**:\n  - `--croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/)\n    dataset card under the report's `croissant` key so the same JSON\n    file doubles as both the EU AI Act Article 10 governance artifact\n    and a Croissant-consumer dataset card.\n  - `--pii-ml` layers\n    [Presidio](https://github.com/microsoft/presidio) NER on top of\n    the regex detector — adds `person` / `organization` /\n    `location` categories to `pii_summary` / `pii_severity`. Requires\n    `pip install 'forgelm[ingestion-pii-ml]'`."
+   "source": "## What's next\n\n- **Train on the curated JSONL**: point any of the training notebooks at\n  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n    set with public datasets\n- **Long-form guides**:\n  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n    — every flag, every chunking strategy, every extra\n  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n    — audit JSON schema, severity tiers, governance integration\n- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n  when you point it at a directory of raw docs (Phase 11.5+), and as of\n  Phase 12.5 it also offers to run `forgelm audit` automatically once a\n  JSONL is selected — closes the BYOD audit loop end-to-end.\n- **Phase 12.5 audit add-ons (v0.5.3)**:\n  - `--croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/)\n    dataset card under the report's `croissant` key so the same JSON\n    file doubles as both the EU AI Act Article 10 governance artifact\n    and a Croissant-consumer dataset card.\n  - `--pii-ml [--pii-ml-language LANG]` layers\n    [Presidio](https://github.com/microsoft/presidio) NER on top of\n    the regex detector — adds `person` / `organization` /\n    `location` categories to `pii_summary` / `pii_severity`. **Two-step\n    install:**\n    ```bash\n    pip install 'forgelm[ingestion-pii-ml]'\n    python -m spacy download en_core_web_lg\n    ```\n    `presidio-analyzer` does not transitively ship a spaCy NER model;\n    without the model `--pii-ml` raises an `ImportError` with the\n    install recipe **before** any rows are scanned. Pass\n    `--pii-ml-language tr` (and download the matching spaCy model) to\n    audit Turkish corpora."
   }
  ],
  "metadata": {
diff --git a/tests/test_phase12_5.py b/tests/test_phase12_5.py
index 2ca7946c..8191e508 100644
--- a/tests/test_phase12_5.py
+++ b/tests/test_phase12_5.py
@@ -197,9 +197,14 @@ def test_croissant_section_empty_by_default(self, tmp_path):
             assert exc_info.value.code == 0
 
         report = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))
-        # Key may or may not be present depending on serializer; the contract
-        # is "no Croissant content unless --croissant is passed".
-        assert report.get("croissant", {}) == {}
+        # Pin the contract: ``croissant`` is *always* present in the
+        # serialised report (dataclass ``field(default_factory=dict)``)
+        # and is the empty dict when ``--croissant`` is off. This
+        # matches the precedent set by ``secrets_summary`` /
+        # ``quality_summary`` and prevents a future serializer change
+        # from silently dropping the key for empty dicts.
+        assert "croissant" in report
+        assert report["croissant"] == {}
 
     def test_croissant_flag_emits_minimal_card(self, tmp_path):
         ds = tmp_path / "data.jsonl"
@@ -290,3 +295,234 @@ def test_presidio_severity_table_exposes_ml_tiers(self):
         assert PII_ML_SEVERITY["person"] == "medium"
         assert PII_ML_SEVERITY["organization"] == "low"
         assert PII_ML_SEVERITY["location"] == "low"
+
+    def test_presidio_entity_map_only_canonical_keys(self):
+        # Presidio canonicalises spaCy NER labels (PER/PERSON → PERSON,
+        # LOC/GPE → LOCATION, ORG → ORGANIZATION, NORP → NRP) before
+        # they reach ``analyzer.analyze().entity_type``. Pin the map to
+        # the canonical names only so a future maintainer doesn't read
+        # raw spaCy keys (``ORG`` / ``GPE`` / ``NORP`` / ``FAC``) as
+        # live coverage. NRP is deliberately excluded — it's a distinct
+        # privacy signal from ``location``.
+        from forgelm.data_audit import _PRESIDIO_ENTITY_MAP
+
+        assert set(_PRESIDIO_ENTITY_MAP.keys()) == {"PERSON", "ORGANIZATION", "LOCATION"}
+        assert _PRESIDIO_ENTITY_MAP["PERSON"] == "person"
+        assert _PRESIDIO_ENTITY_MAP["ORGANIZATION"] == "organization"
+        assert _PRESIDIO_ENTITY_MAP["LOCATION"] == "location"
+
+    def test_presidio_missing_spacy_model_surfaces_install_hint(self):
+        # Even when ``presidio-analyzer`` is importable, the spaCy model
+        # is a separate ``python -m spacy download …`` step. spaCy
+        # raises ``OSError("Can't find model …")`` when the model
+        # package isn't on the import path; ``_require_presidio`` must
+        # catch that and re-raise as ``ImportError`` with the install
+        # recipe so the operator never gets a deep spaCy traceback.
+        from forgelm.data_audit import _get_presidio_analyzer, _require_presidio
+
+        # Reset the cache so our patched class is the one that gets
+        # constructed; otherwise a previous successful build could
+        # return a stale instance.
+        _get_presidio_analyzer.cache_clear()
+        try:
+
+            class _BoomAnalyzer:
+                def __init__(self):
+                    raise OSError("Can't find model 'en_core_web_lg'")
+
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with patch("forgelm.data_audit._PresidioAnalyzer", _BoomAnalyzer):
+                    with pytest.raises(ImportError) as exc_info:
+                        _require_presidio()
+        finally:
+            # Always restore the cache so subsequent tests in the same
+            # session don't see ``_BoomAnalyzer``.
+            _get_presidio_analyzer.cache_clear()
+        msg = str(exc_info.value)
+        assert "spacy" in msg.lower() or "spaCy" in msg
+        assert "ingestion-pii-ml" in msg
+        assert "en_core_web_lg" in msg
+
+    def test_presidio_entity_map_collapses_findings_to_buckets(self):
+        # Behavioural test for ``detect_pii_ml`` — a stub Presidio
+        # analyzer that emits canonical entity_type strings should
+        # produce the right counts; non-canonical ones (raw spaCy
+        # labels) should be ignored. This test would have caught the
+        # original review's M2 immediately.
+        from forgelm.data_audit import _get_presidio_analyzer, detect_pii_ml
+
+        class _Finding:
+            def __init__(self, entity_type):
+                self.entity_type = entity_type
+
+        class _StubAnalyzer:
+            def analyze(self, text, language):
+                # Emit the full Presidio canonical set + a couple of raw
+                # spaCy labels (which Presidio would never actually
+                # emit) to confirm our map only honours canonicals.
+                return [
+                    _Finding("PERSON"),
+                    _Finding("ORGANIZATION"),
+                    _Finding("LOCATION"),
+                    _Finding("LOCATION"),
+                    _Finding("NRP"),  # Presidio canonical, not mapped
+                    _Finding("ORG"),  # raw spaCy, must NOT be honoured
+                    _Finding("GPE"),  # raw spaCy, must NOT be honoured
+                ]
+
+        _get_presidio_analyzer.cache_clear()
+        try:
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with patch("forgelm.data_audit._get_presidio_analyzer", return_value=_StubAnalyzer()):
+                    counts = detect_pii_ml("Alice works at Acme Corp in Berlin.")
+        finally:
+            _get_presidio_analyzer.cache_clear()
+        assert counts == {"person": 1, "organization": 1, "location": 2}
+
+
+# ---------------------------------------------------------------------------
+# Cross-cutting tests — coverage gaps surfaced by the Phase 12.5 review
+# ---------------------------------------------------------------------------
+
+
+class TestCroissantMultiSplit:
+    """Multi-split layout produces one cr:FileObject + cr:RecordSet per split."""
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_multi_split_card_carries_one_record_per_split(self, tmp_path):
+        # train.jsonl / validation.jsonl / test.jsonl is the canonical
+        # multi-split layout the audit recognises. Each must produce
+        # its own ``cr:FileObject`` (in ``distribution``) and its own
+        # ``cr:RecordSet`` (with the right ``@id``).
+        data_dir = tmp_path / "splits"
+        data_dir.mkdir()
+        for split, rows in [
+            ("train", [{"text": "alpha"}, {"text": "beta"}]),
+            ("validation", [{"text": "gamma"}]),
+            ("test", [{"text": "delta"}]),
+        ]:
+            self._write_jsonl(data_dir / f"{split}.jsonl", rows)
+
+        out_dir = tmp_path / "audit"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(data_dir),
+                "--output",
+                str(out_dir),
+                "--croissant",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+
+        report = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))
+        crois = report["croissant"]
+        ids = {entry["@id"] for entry in crois["distribution"]}
+        assert ids == {"train.jsonl", "validation.jsonl", "test.jsonl"}
+        record_ids = {entry["@id"] for entry in crois["recordSet"]}
+        assert record_ids == {"train", "validation", "test"}
+        # contentUrl must be the relative file_id, not an absolute
+        # filesystem path — see the Phase 12.5 review m3 finding.
+        for entry in crois["distribution"]:
+            assert entry["contentUrl"] == entry["@id"]
+            assert "/" not in entry["contentUrl"]
+
+
+class TestAllMaskSymmetric:
+    """``--all-mask`` set-union covers the secrets-mask-already-true direction too."""
+
+    def test_all_mask_with_secrets_mask_already_set(self, tmp_path):
+        # Symmetric counterpart to test_all_mask_combines_with_individual_flags_no_error
+        # so a future refactor that drops one branch of the boolean
+        # union trips a test.
+        aws_key = "AKIA" + "IOSFODNN7" + "EXAMPLE"
+        src = tmp_path / "input.txt"
+        src.write_text(
+            f"alice@example.com mentioned key={aws_key}",
+            encoding="utf-8",
+        )
+        out = tmp_path / "out.jsonl"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "ingest",
+                str(src),
+                "--output",
+                str(out),
+                "--secrets-mask",
+                "--all-mask",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        written = out.read_text(encoding="utf-8")
+        assert "[REDACTED]" in written
+        assert "[REDACTED-SECRET]" in written
+        assert aws_key not in written
+
+
+class TestPiiMlJsonEnvelope:
+    """``forgelm audit --output-format json`` surfaces the Croissant card."""
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_envelope_carries_croissant_when_flag_on(self, tmp_path, capsys):
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+        out_dir = tmp_path / "audit"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(ds),
+                "--output",
+                str(out_dir),
+                "--croissant",
+                "--output-format",
+                "json",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        envelope = json.loads(capsys.readouterr().out)
+        assert "croissant" in envelope
+        assert envelope["croissant"]["@type"] == "sc:Dataset"
+
+    def test_envelope_croissant_is_empty_when_flag_off(self, tmp_path, capsys):
+        ds = tmp_path / "data.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+        out_dir = tmp_path / "audit"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(ds),
+                "--output",
+                str(out_dir),
+                "--output-format",
+                "json",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        envelope = json.loads(capsys.readouterr().out)
+        # Phase 12 precedent: present-and-empty when off.
+        assert "croissant" in envelope
+        assert envelope["croissant"] == {}

From 50c370d587f87dbf5161f765bff450e31955bc9a Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 18:46:05 +0300
Subject: [PATCH 03/12] release(0.5.0): consolidate Phases 11 + 11.5 + 12 +
 12.5 into one comprehensive v0.5.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Originally planned as four sequential PyPI tags (v0.5.0 / v0.5.1 /
v0.5.2 / v0.5.3). The four phases form one coherent surface (ingest →
polish → mature → polish) that's hard to use in parts; consolidating
into a single comprehensive v0.5.0 release keeps the user-facing
release notes focused while git history retains the four phases as
separate commit batches.

pyproject.toml
- version: 0.5.2rc1 → 0.5.0

CHANGELOG.md
- Collapse [Unreleased] + [0.5.2] + [0.5.1] + [0.5.0] (summary stub)
  into a single [0.5.0] — 2026-04-29 entry.
- Theme paragraph + consolidation note explaining the merger.
- Internal phase boundaries preserved as section markers
  (### Phase 12.5 / Phase 12 / Phase 11.5 / Phase 11) so reviewers can
  map back to PR history (#11, #12, #13, current).
- [Unreleased] is now empty (next minor picks up Phase 14).

README.md
- "Document Ingestion & Data Audit (v0.5.0 — polished in v0.5.1,
  matured in v0.5.2)" → "(v0.5.0 — Phases 11 + 11.5 + 12 + 12.5
  consolidated)".
- Drop "v0.5.2 added X" / "v0.5.1 added Y" / "Phase 12.5 polish
  (v0.5.3)" history phrasing — features now read as part of v0.5.0.

docs/roadmap.md + roadmap-tr.md
- Status table: four separate "🟡 Merged" rows for Phases 11 / 11.5 /
  12 / 12.5 collapsed into one combined row pointing at
  releases.md#v050. Phase 14 row reslotted from v0.5.3 to v0.5.1.
- "Latest PyPI: v0.4.5" wording trimmed (the v0.5.0/.1/.2 sentence
  about three pending tags is gone).
- "Next: v0.5.3" → "Next: v0.5.1" (Phase 14).
- Phase count: 16 complete + 3 planned → 17 complete + 2 planned
  (12.5 moves into the consolidated release; 13 + 14 remain planned).
- Mermaid diagram: P11 / P115 / P12 / P125 all point at the same
  V2[v0.5.0 pending] node; styling bumped to merged-but-not-tagged
  light-green.

docs/roadmap/releases.md
- v0.5.0 / v0.5.1 / v0.5.2 sections collapsed into a single comprehensive
  v0.5.0 entry organised by phase (### Phase 11 / 11.5 / 12 / 12.5).
- v0.5.3 (Phase 14) → v0.5.1 (Phase 14).

docs/roadmap/phase-{11-5,12-5,12-data-curation,14-pipeline}.md
- Consolidation note at the top of each historical phase plan
  ("originally targeted vX.Y.Z, ships as part of consolidated v0.5.0;
  see releases.md#v050"). Body kept intact as the historical planning
  trail.
- phase-14: Target release v0.5.3 → v0.5.1; "starts after v0.5.2 PyPI
  tag" → "starts after v0.5.0 PyPI tag".
- phase-12-5-backlog rows: "ships with v0.5.3" → "ships with v0.5.0".

docs/guides/{ingestion,data_audit}{,-tr}.md +
docs/reference/usage{,-tr}.md
- Drop the "v0.5.2 added" / "v0.5.1 promoted" history phrasing inside
  feature descriptions. Features now read as v0.5.0 capabilities;
  phase labels (Phase 11 / 11.5 / 12 / 12.5) are kept as breadcrumbs
  for reviewers.
- Section headings like "Document Ingestion (v0.5.0+; token-aware in
  v0.5.1; markdown + secrets-mask in v0.5.2)" → "(v0.5.0)".
- Inline comments in CLI examples drop "v0.5.2:" / "v0.5.3 (Phase 12.5):"
  prefixes since the features all ship in the same release.

notebooks/data_curation.ipynb
- Install pin: 0.5.2 → 0.5.0 (cells 1 + 16).
- "Phase 12.5 audit add-ons (v0.5.3)" markdown → "Other v0.5.0 audit
  add-ons".
- Section 2 header drops the "Phase 12.5 shorthand (v0.5.3)" framing
  for --all-mask; the flag is just part of the v0.5.0 release.

forgelm/cli.py
- One internal comment tweaked from "v0.5.1 consumers" to
  "any pre-Phase-12 JSON consumer" (the legacy envelope key still has
  a real reason to exist; the framing just stops referencing a
  release that won't exist as a separate PyPI tag).
- Phase labels in user-visible help text (Phase 11.5 / 12 / 12.5) kept
  intact — they're descriptive history, not version pins.

Verification
- ruff clean (78 files)
- 840 tests pass (13 skipped)
- 7/7 bilingual H2 parity (configuration / usage / distributed /
  data_preparation / architecture / ingestion / data_audit)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 104 +++++++-----------
 README.md                                     |  18 +--
 docs/guides/data_audit-tr.md                  |   6 +-
 docs/guides/data_audit.md                     |   6 +-
 docs/guides/ingestion-tr.md                   |  13 +--
 docs/guides/ingestion.md                      |  22 +++-
 docs/reference/usage-tr.md                    |  26 ++---
 docs/reference/usage.md                       |  26 ++---
 docs/roadmap-tr.md                            |  33 +++---
 docs/roadmap.md                               |  35 +++---
 docs/roadmap/phase-11-5-backlog.md            |   7 +-
 docs/roadmap/phase-12-5-backlog.md            |  16 ++-
 .../phase-12-data-curation-maturity.md        |   7 +-
 docs/roadmap/phase-14-pipeline-chains.md      |   4 +-
 docs/roadmap/releases.md                      |  81 ++++++--------
 forgelm/cli.py                                |   8 +-
 notebooks/data_curation.ipynb                 |  24 +---
 pyproject.toml                                |   2 +-
 18 files changed, 212 insertions(+), 226 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4f95c50..a7b2776f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,48 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
-### Added — Phase 12.5 (Data Curation Polish backlog)
+(no unreleased changes — next minor will pick up Phase 14, tracked in
+[docs/roadmap.md](docs/roadmap.md))
+
+---
+
+## [0.5.0] — 2026-04-29
+
+**Theme:** "Document Ingestion + Data Curation Pipeline" — Phases 11,
+11.5, 12, and 12.5 ship as one comprehensive release.
+
+> **Note on consolidation.** Originally planned as four sequential
+> PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`) but consolidated
+> into a single `v0.5.0` because the four phases form one coherent
+> surface (ingest → polish → mature → polish) that's hard to use in
+> parts. Git history retains the four phases as separate commit
+> batches; this entry collapses them into the user-facing release
+> notes. Section markers below preserve the phase boundary so
+> reviewers can map back to [docs/roadmap/releases.md](docs/roadmap/releases.md).
+
+The release adds:
+
+- **Phase 11** — `forgelm ingest` (PDF / DOCX / EPUB / TXT / Markdown
+  → SFT-ready JSONL) + `forgelm audit` (length / language /
+  near-duplicate / cross-split leakage / PII) + EU AI Act Article 10
+  governance integration.
+- **Phase 11.5** — operational polish on the Phase 11 surface: LSH
+  banding, streaming reader, token-aware chunking, PDF
+  header/footer dedup, PII severity tiers, atomic audit writes.
+- **Phase 12** — data curation maturity: MinHash LSH dedup option,
+  markdown-aware splitter, code/secrets leakage tagger, heuristic
+  quality filter, DOCX table preservation.
+- **Phase 12.5** — small additive polish: `--all-mask` shorthand,
+  Croissant 1.0 dataset card emission, optional Presidio ML-NER PII
+  adapter, wizard "audit first" entry point.
+
+CI / docs / standards bookkeeping accompanying every phase is folded
+into "Cross-cutting review hardening" at the bottom (rounds 1–12 of
+review-cycle fixes applied across the four phases above).
+
+---
+
+### Phase 12.5 — Data Curation Polish (backlog items #1–#4)
 
 Four follow-up items from
 [`docs/roadmap/phase-12-5-backlog.md`](docs/roadmap/phase-12-5-backlog.md)
@@ -470,67 +511,6 @@ Operational polish on top of `v0.5.0`'s ingestion + audit surface — no new tra
 
 ---
 
-## [0.5.2] — 2026-04-28
-
-**Theme:** "Data Curation Maturity" (Phase 12 Tier 1) — direct continuation of the Phase 11 / 11.5 ingestion + audit lineage. Closes the four gaps surfaced by the post-`v0.5.1` competitive review (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling). Tier 2/3 items (Presidio adapter, Croissant metadata, `--all-mask`, wizard "audit first") deferred to [Phase 12.5 backlog](docs/roadmap/phase-12-5-backlog.md).
-
-### Added
-
-- **MinHash LSH dedup option** — opt-in `--dedup-method minhash --jaccard-threshold 0.85` route via `datasketch` (`[ingestion-scale]` extra) for >50K-row corpora. Default simhash + LSH banding stays untouched.
-- **Markdown-aware splitter** — new `--strategy markdown` preserves heading hierarchy (`# H1` / `## H2`), keeps fenced code blocks atomic, and inlines a heading breadcrumb so SFT loss sees document context.
-- **Code / secrets leakage tagger** — new `secrets_summary` block in audit JSON (AWS / GitHub / Slack / OpenAI / Google / JWT / OpenSSH / PGP / Azure storage). Ingest gains `--secrets-mask` (mask order: secrets → PII so combined detectors don't double-count). `[ingestion-secrets]` extra is reserved for a follow-up release; the regex-only fallback is what runs today.
-- **Heuristic quality filter** — opt-in `--quality-filter` adds a `quality_summary` block with Gopher / C4 / RefinedWeb-style heuristics (mean-word-length, alphabetic ratio, end-of-line punctuation, short-paragraph ratio, repeated lines). ML classifiers stay deferred to Phase 13+.
-- **DOCX table preservation** — `_extract_docx` emits Markdown table syntax (header + `---` separator + body rows) at extraction time, **before any chunking strategy runs**, instead of the previous `" | "` flat join. Uneven rows padded; all-blank rows trimmed.
-- **`secrets_redaction_counts`** — added to the `--output-format json` envelope of `forgelm ingest` for CI/CD consumers; `{secret_type: count}` map of redacted spans.
-
-### Changed / Fixed (review-cycle hardening)
-
-- **Regex hygiene standard** ([`docs/standards/regex.md`](docs/standards/regex.md)) — codified 8 hard rules distilled from Phase 11 / 11.5 / 12 review cycles (Unicode-aware `\w`, no single-char classes, bounded quantifiers, no two competing unbounded greedy quantifiers, no `\s` under MULTILINE, no `.*?` + back-reference + DOTALL, intentional ASCII-only classes permitted with `re.ASCII`). The 8th rule covers `^.*` anti-pattern.
-- **Replaced `_MARKDOWN_CODE_FENCE` regex with `_parse_md_fence`** — non-regex per-line parser; provably O(n). The previous regex had two unbounded greedy quantifiers in sequence over overlapping character classes (SonarCloud `python:S5852`).
-- **`_strip_code_fences`** in `data_audit.py` rewritten as a per-line state machine; tracks the opening fence's run length per CommonMark §4.5 so a 4-backtick opener isn't prematurely closed by a 3-backtick line.
-- **`_markdown_sections` complexity refactor** — extracted `_advance_fence_state`, `_flush_section`, `_render_sections` helpers so the dispatch loop reads top-down (cognitive complexity below SonarCloud's 15-line threshold).
-- **`_parse_md_fence`** — now rejects backtick fence openers whose info string contains a backtick (CommonMark §4.5).
-- **MinHash knob validation** — `audit_dataset` validates `minhash_jaccard ∈ [0.0, 1.0]` and `minhash_num_perm > 0` at the API boundary.
-- **`re.ASCII` flag** on secret regexes (`github_token` / `openai_api_key` / `google_api_key` / `jwt`) so `\w` is restricted to ASCII; full BEGIN…END envelope matching for OpenSSH / RSA / DSA / EC / PGP private-key blocks.
-- **Documentation drift sweep** — multiple rounds of EN ↔ TR mirror sync (`data_audit-tr.md`, `ingestion-tr.md`, `regex.md`, `data_audit.md`); legacy JSON-key documentation now references the actual `splits.<name>.near_duplicate_pairs` path.
-- **ReDoS regression tests** — `tests/test_phase12_review_fixes.py` adds linearity benchmarks at 1K / 5K / 10K (median of 5 runs) for `_MARKDOWN_HEADING_PATTERN`, `_strip_code_fences`, and `_parse_md_fence`.
-
----
-
-## [0.5.1] — 2026-04-27
-
-**Theme:** "Ingestion / Audit Polish" (Phase 11.5) — operational polish on top of `v0.5.0`'s ingestion + audit surface. No new training capabilities, but materially better handling for large corpora and a cleaner CLI shape.
-
-### Added
-
-- **`forgelm audit` subcommand** — promoted from the `--data-audit` top-level flag; first-class subcommand with its own `--output` default. The flag is preserved as a deprecation alias.
-- **LSH-banded near-duplicate detection** — replaces the `O(n²)` pair scan inside each split (and across splits) with locality-sensitive-hashing bands (4 × 16-bit on the 64-bit fingerprint). Drops average-case to `O(n × k)` and unblocks audits on 100K+ row corpora.
-- **Streaming `_read_jsonl_split`** — JSONL reader yields rows lazily; per-split aggregator stays generator-based until simhash collection. Bounds memory on multi-million-row splits.
-- **Token-aware `--chunk-tokens`** — optional ingestion flag that sizes chunks against an HF tokenizer instead of raw character counts.
-- **PDF page-level header / footer dedup** — repeated page headers (company watermark, page number) used to inflate near-duplicate counts; common-prefix / common-suffix detection across pages strips them automatically.
-- **PII severity tiers** — audit output adds a `pii_severity` block grading each PII type as `low / medium / high / critical` (e.g. `credit_card` → critical, `phone` → low) so compliance reviewers get a one-glance verdict.
-- **`summarize_report` truncation policy** — multi-split summaries get a `verbose=False` default that suppresses zero-finding splits.
-- **Structured ingestion notes** — `IngestionResult.extra_notes` keeps the human-readable list but gains a parallel `notes_structured: {key: value}` map for programmatic consumers.
-- **Wizard "ingest first" entry point** — first-class wizard option that routes to `forgelm ingest`, surfaces a JSONL path, and folds it back into the BYOD prompt.
-- **xxhash backend for simhash + token-level memo** — drop-in faster non-crypto digest path (BLAKE2b kept as fallback). Token-level `lru_cache` memoizes repeat tokens for a 2–5× speedup on long corpora.
-- **Atomic audit report write** — `data_audit_report.json` is written via `tempfile.NamedTemporaryFile` + atomic rename so a crashed audit never leaves a half-written report on disk.
-
----
-
-## [0.5.0] — 2026-04-27
-
-**Theme:** "Document Ingestion & Data Audit" (Phase 11). Bridges raw enterprise corpora to ForgeLM's training data format and surfaces governance signals before training.
-
-### Added
-
-- **`forgelm/ingestion.py` + `forgelm ingest` subcommand** — multi-format document → JSONL pipeline with `paragraph` (default) and `sliding` chunking strategies, recursive directory walk, optional `--pii-mask`. Supported extensions: `.pdf` (`pypdf`), `.docx` (`python-docx`), `.epub` (`ebooklib` + `beautifulsoup4`), `.txt`, `.md`. Output is `{"text": ...}` JSONL recognised by ForgeLM's data loader as pre-formatted SFT input. OCR is intentionally out of scope; scanned PDFs warn and produce zero chunks.
-- **`forgelm/data_audit.py` + `forgelm --data-audit` flag** — per-split metrics (sample count, column schema, length distribution `min/max/mean/p50/p95`, top-3 language detection, null/empty rate), 64-bit simhash near-duplicate detection within each split, cross-split overlap report (catches train/test leakage), PII regex with Luhn-validated credit cards and TC Kimlik checksum-validated TR IDs.
-- **EU AI Act Article 10 integration** — `generate_data_governance_report` inlines `data_audit_report.json` under the `data_audit` key when present in the trainer's `output_dir`.
-- **`pyproject.toml` `[ingestion]` extra** — `pypdf`, `python-docx`, `ebooklib`, `beautifulsoup4`, `langdetect`. Cross-platform; no native compilation. Plain TXT / Markdown ingestion + the audit module work without installing the extra (PII regex, simhash, length stats are pure stdlib).
-- **Tests + docs** — `tests/test_ingestion.py` and `tests/test_data_audit.py` (54 tests; PDF round-trip skips when `pypdf` missing). New guides: `docs/guides/ingestion.md`, `docs/guides/data_audit.md`. README feature section, install matrix, and roadmap status updated.
-
----
-
 ## [0.4.5] — 2026-04-26
 
 ### Added
diff --git a/README.md b/README.md
index 320eb915..7323eeb3 100644
--- a/README.md
+++ b/README.md
@@ -27,14 +27,16 @@
 - **LLM-as-Judge**: API-based (OpenAI) or local model scoring for quality assessment
 - **Auto-Revert**: Opt-in (`evaluation.auto_revert: true`) — automatically discards models that fail loss, benchmark, or safety thresholds before artifacts are written
 
-### Document Ingestion & Data Audit (v0.5.0 — polished in v0.5.1, matured in v0.5.2)
-- **Multi-Format Ingestion**: `forgelm ingest ./policies/ --recursive --output data/policies.jsonl` — turns raw PDF / DOCX / EPUB / TXT / Markdown into the SFT-ready JSONL the trainer accepts. Optional dep: `pip install forgelm[ingestion]`. v0.5.2 added a **Markdown-aware splitter** (`--strategy markdown`) and DOCX table preservation in Markdown table syntax.
-- **Chunking Strategies**: `paragraph` (default; preserves boundaries), `sliding` (fixed window with overlap), or `markdown` (v0.5.2 — heading-aware splitter that keeps fenced code blocks atomic and inlines a heading breadcrumb at the top of each chunk for SFT context). A `semantic` strategy is reserved for a follow-up phase — the implementation in `forgelm.ingestion` raises `NotImplementedError` today and the CLI hides it from `--strategy` choices. Token-aware mode in v0.5.1: `--chunk-tokens 1024 --tokenizer Qwen/Qwen2.5-7B-Instruct` sizes chunks against your model's actual vocabulary.
+### Document Ingestion & Data Audit (v0.5.0 — Phases 11 + 11.5 + 12 + 12.5 consolidated)
+- **Multi-Format Ingestion**: `forgelm ingest ./policies/ --recursive --output data/policies.jsonl` — turns raw PDF / DOCX / EPUB / TXT / Markdown into the SFT-ready JSONL the trainer accepts. Optional dep: `pip install forgelm[ingestion]`. Includes a **Markdown-aware splitter** (`--strategy markdown`) and DOCX table preservation in Markdown table syntax.
+- **Chunking Strategies**: `paragraph` (default; preserves boundaries), `sliding` (fixed window with overlap), or `markdown` (heading-aware splitter that keeps fenced code blocks atomic and inlines a heading breadcrumb at the top of each chunk for SFT context). A `semantic` strategy is reserved for a follow-up phase — the implementation in `forgelm.ingestion` raises `NotImplementedError` today and the CLI hides it from `--strategy` choices. Token-aware mode: `--chunk-tokens 1024 --tokenizer Qwen/Qwen2.5-7B-Instruct` sizes chunks against your model's actual vocabulary.
 - **PII Masking on Ingest**: `--pii-mask` redacts emails, phones, credit cards (Luhn-validated), IBAN, and national IDs (TR / DE / FR / US-SSN) before chunks land in the JSONL.
-- **PDF Page Header/Footer Dedup (v0.5.1)**: Lines that recur on ≥ 70 % of PDF pages (watermarks, page numbers, copyright lines) are stripped automatically — the audit's near-duplicate counts stop misfiring on long policy / book PDFs.
-- **Dataset Audit**: `forgelm audit data/sft.jsonl --output ./audit/` — produces `data_audit_report.json` with sample count, length distribution, top-3 language detection, LSH-banded near-duplicate rate (`O(n × k)` typical case, exact recall at the default Hamming threshold; v0.5.2 added optional **MinHash LSH** via `--dedup-method minhash` for >50K-row corpora), cross-split leakage check, null/empty rate, and PII flag counts with **severity tiers** (critical / high / medium / low + worst-tier verdict). v0.5.2 also added an always-on **secrets/credential scan** covering the nine families enumerated in `forgelm.data_audit.SECRET_TYPES` — AWS access keys, GitHub tokens, Slack tokens, OpenAI API keys, Google API keys, JWTs, full OpenSSH private-key blocks, full PGP private-key blocks, and Azure storage connection strings — and an opt-in **heuristic quality filter** (`--quality-filter`). CPU-only; streaming JSONL reader keeps memory bounded on multi-million-row splits; feeds EU AI Act Article 10 governance artifact automatically when present at training time. Legacy `--data-audit` flag still works as a deprecation alias.
-- **Secrets-Aware Ingest (v0.5.2)**: `forgelm ingest … --secrets-mask` scrubs credentials before chunks land in the JSONL — fine-tuning on text containing real API keys memorises them at training time. Pairs with `--pii-mask`; secrets run first so combined detectors don't double-count overlapping spans.
-- **Phase 12.5 polish (v0.5.3)**: `forgelm ingest --all-mask` shorthand for combined PII + secrets scrubbing; `forgelm audit --croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card alongside the existing report; `forgelm audit --pii-ml [--pii-ml-language LANG]` layers [Presidio](https://github.com/microsoft/presidio) NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra **plus a separate `python -m spacy download en_core_web_lg`** step (or the matching model for the chosen language); the wizard now offers to run `forgelm audit` automatically after a JSONL is selected (BYOD onboarding closes the audit loop).
+- **PDF Page Header/Footer Dedup**: Lines that recur on ≥ 70 % of PDF pages (watermarks, page numbers, copyright lines) are stripped automatically — the audit's near-duplicate counts stop misfiring on long policy / book PDFs.
+- **Dataset Audit**: `forgelm audit data/sft.jsonl --output ./audit/` — produces `data_audit_report.json` with sample count, length distribution, top-3 language detection, LSH-banded near-duplicate rate (`O(n × k)` typical case, exact recall at the default Hamming threshold; optional **MinHash LSH** via `--dedup-method minhash` for >50K-row corpora), cross-split leakage check, null/empty rate, and PII flag counts with **severity tiers** (critical / high / medium / low + worst-tier verdict). Always-on **secrets/credential scan** covers the nine families enumerated in `forgelm.data_audit.SECRET_TYPES` — AWS access keys, GitHub tokens, Slack tokens, OpenAI API keys, Google API keys, JWTs, full OpenSSH private-key blocks, full PGP private-key blocks, and Azure storage connection strings — and an opt-in **heuristic quality filter** (`--quality-filter`). CPU-only; streaming JSONL reader keeps memory bounded on multi-million-row splits; feeds EU AI Act Article 10 governance artifact automatically when present at training time. Legacy `--data-audit` flag still works as a deprecation alias.
+- **Secrets-Aware Ingest**: `forgelm ingest … --secrets-mask` scrubs credentials before chunks land in the JSONL — fine-tuning on text containing real API keys memorises them at training time. Pairs with `--pii-mask`; secrets run first so combined detectors don't double-count overlapping spans. `--all-mask` is a one-flag shorthand for both.
+- **Optional ML-NER PII**: `forgelm audit --pii-ml [--pii-ml-language LANG]` layers [Presidio](https://github.com/microsoft/presidio) NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra **plus a separate `python -m spacy download en_core_web_lg`** step (or the matching model for the chosen language). Adds `person` / `organization` / `location` categories into the same `pii_summary` / `pii_severity` blocks under disjoint category names.
+- **Croissant 1.0 dataset card**: `forgelm audit --croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card under the report's `croissant` key so the same JSON file doubles as both the EU AI Act Article 10 governance artifact and a Croissant-consumer dataset card.
+- **Wizard "audit first"**: when the wizard resolves a JSONL (typed or produced by `forgelm ingest`) it offers to run `forgelm audit` inline and prints the verdict before continuing — closes the BYOD audit loop end-to-end.
 
 ### Quickstart Layer (v0.4.5)
 - **One-Command Templates**: `forgelm quickstart customer-support` — 4 bundled templates (SFT customer-support, code-assistant, medical-qa-tr, GRPO math-reasoning) plus a bring-your-own-data domain-expert scaffold. Auto-downsizes models on small GPUs.
@@ -73,7 +75,7 @@ forgelm quickstart customer-support           # render config + train + chat
 forgelm quickstart code-assistant --dry-run   # render config only
 forgelm quickstart medical-qa-tr --model your-org/your-model  # override
 
-# Have raw docs? Ingest them first (v0.5.0+; v0.5.1 added token-aware sizing)
+# Have raw docs? Ingest them first (v0.5.0; supports token-aware sizing)
 pip install -e ".[ingestion]"
 forgelm ingest ./policies/ --recursive --output data/policies.jsonl
 forgelm audit data/policies.jsonl --output ./audit/   # `forgelm --data-audit ...` still works as legacy alias
diff --git a/docs/guides/data_audit-tr.md b/docs/guides/data_audit-tr.md
index 54c9e5d3..56a4e07d 100644
--- a/docs/guides/data_audit-tr.md
+++ b/docs/guides/data_audit-tr.md
@@ -2,11 +2,11 @@
 
 `forgelm audit PATH` bir JSONL veri setini analiz eder ve kalite,
 governance ile PII sinyallerini kapsayan bir `data_audit_report.json`
-üretir. Faz 11 (`v0.5.0`'da tanıtıldı) altyapıyı, Faz 11.5 (`v0.5.1`)
+üretir. Faz 11 altyapıyı, Faz 11.5 (`v0.5.0`'da birleşti)
 ise top-level flag'i first-class subcommand'a yükseltti, LSH-banded
 near-duplicate tespitini, streaming JSONL okuyucusunu, PII şiddet
 katmanlarını, atomik disk yazımı ve verbose-by-default kısaltma
-politikasını ekledi. **Faz 12 (`v0.5.2`)** opt-in MinHash LSH dedup
+politikasını ekledi. **Faz 12 (`v0.5.0`'da birleşti)** opt-in MinHash LSH dedup
 yöntemini (`--dedup-method minhash`), her zaman çalışan
 code/credential leakage taramasını (`secrets_summary`), ve opt-in
 heuristic kalite filtresini (`--quality-filter`) ekledi.
@@ -268,7 +268,7 @@ forgelm ingest ./policies/ --recursive --output data/policies.jsonl --secrets-ma
 
 Opsiyonel / forward-compatibility: `[ingestion-secrets]` extra'sı bir
 `detect-secrets>=1.5.0` bağımlılığı tanımlar ama bu **bir sonraki sürüm
-için ayrılmıştır**. v0.5.2 itibarıyla `forgelm.data_audit.detect_secrets()`
+için ayrılmıştır**. v0.5.0 itibarıyla `forgelm.data_audit.detect_secrets()`
 yalnızca yukarıdaki regex setine dayanır; extra'yı kurmak bugün audit
 davranışını değiştirmez. Extra, `forgelm[ingestion-secrets]` pin'leyen
 operatörlerin entegrasyon geldiğinde forward-compatible olabilmesi
diff --git a/docs/guides/data_audit.md b/docs/guides/data_audit.md
index b02f9176..e6169326 100644
--- a/docs/guides/data_audit.md
+++ b/docs/guides/data_audit.md
@@ -3,11 +3,11 @@
 `forgelm audit PATH` analyzes a JSONL dataset and produces a
 `data_audit_report.json` covering quality, governance, PII, and (Phase 12
 onwards) credential-leakage and heuristic-quality signals. Phase 11
-(`v0.5.0`) shipped the underlying audit; Phase 11.5 (`v0.5.1`) promoted
+shipped the underlying audit; Phase 11.5 (consolidated into `v0.5.0`) promoted
 it from a top-level flag to a first-class subcommand and added
 LSH-banded near-duplicate detection, streaming JSONL reading, PII
 severity tiers, atomic on-disk write, and a verbose-by-default
-truncation policy. **Phase 12 (`v0.5.2`)** added an opt-in MinHash LSH
+truncation policy. **Phase 12 (consolidated into `v0.5.0`)** added an opt-in MinHash LSH
 dedup method (`--dedup-method minhash`), a code/credential leakage scan
 that runs always-on (`secrets_summary`), and an opt-in heuristic
 quality filter (`--quality-filter`).
@@ -268,7 +268,7 @@ forgelm ingest ./policies/ --recursive --output data/policies.jsonl --secrets-ma
 
 Optional / forward-compatibility: the `[ingestion-secrets]` extra
 declares a `detect-secrets>=1.5.0` dependency that is **reserved for a
-follow-up release**. As of v0.5.2 the audit's
+follow-up release**. As of v0.5.0 the audit's
 `forgelm.data_audit.detect_secrets()` relies solely on the regex set
 above; installing the extra today does not change audit behaviour. The
 extra exists so operators who pin `forgelm[ingestion-secrets]` in
diff --git a/docs/guides/ingestion-tr.md b/docs/guides/ingestion-tr.md
index e1a3fae2..76197911 100644
--- a/docs/guides/ingestion-tr.md
+++ b/docs/guides/ingestion-tr.md
@@ -1,12 +1,11 @@
 # Doküman Yutma Rehberi
 
 Ham kurumsal külliyatı (PDF / DOCX / EPUB / TXT / Markdown) ForgeLM'in
-eğittiği SFT-uyumlu JSONL'a dönüştürün. Faz 11; `v0.5.0`'da tanıtıldı.
-Faz 11.5 (`v0.5.1`) token-aware chunking, PDF sayfa header/footer dedup
-ve yapılandırılmış ingestion notları ekledi. **Faz 12 (`v0.5.2`)**
-markdown-aware splitter (`--strategy markdown`), code/credential
-leakage scrubbing (`--secrets-mask`) ve DOCX tablolarının markdown
-syntax'ı ile çıkarılmasını ekledi.
+eğittiği SFT-uyumlu JSONL'a dönüştürün. `v0.5.0` ile birlikte gelir
+(Faz 11 + 11.5 + 12 + 12.5 birleşmiş): paragraph / sliding /
+markdown-aware splitter, token-aware chunking, PDF sayfa header/footer
+dedup, code/credential scrubbing (`--secrets-mask`), DOCX tablolarının
+markdown syntax'ı ile çıkarılması, `--all-mask` kısayolu.
 
 > Sonrasında [`forgelm audit`](data_audit-tr.md) ile uzunluk dağılımı /
 > dil / near-duplicate / PII metriklerini yüzeye çıkarın; chunk'ları Q&A
@@ -296,7 +295,7 @@ sayfadan kısa belgelerde devre dışı kalır. Yapılandırılmış notlar
 ## Sınırlamalar
 
 - **OCR:** Kapsam dışı. Harici araçlar kullanın — aşağıdaki örneklere bakın.
-- **Tablolar / şekiller:** Faz 12'den (`v0.5.2`) itibaren `_extract_docx()`
+- **Tablolar / şekiller:** Faz 12'den (`v0.5.0`'da birleşti) itibaren `_extract_docx()`
   DOCX tablolarını **Markdown tablo syntax'ına** (header + `---` ayraç +
   body satırları) **chunking stratejisi çalışmadan önce, extraction
   aşamasında** dönüştürür — yani tüm stratejiler render edilmiş
diff --git a/docs/guides/ingestion.md b/docs/guides/ingestion.md
index 55d0d272..7068011c 100644
--- a/docs/guides/ingestion.md
+++ b/docs/guides/ingestion.md
@@ -1,10 +1,20 @@
 # Document Ingestion Guide
 
 Convert raw enterprise corpora (PDF / DOCX / EPUB / TXT / Markdown) into the
-SFT-ready JSONL ForgeLM trains on. Phase 11; introduced in `v0.5.0`. Phase
-11.5 (`v0.5.1`) added token-aware chunking, PDF page header/footer dedup,
-and structured ingestion notes — each documented inline in the relevant
-section below.
+SFT-ready JSONL ForgeLM trains on. Ships with `v0.5.0` (Phases 11 + 11.5
++ 12 + 12.5 consolidated): paragraph / sliding / markdown chunking,
+token-aware sizing, PDF page header/footer dedup, code/credential
+scrubbing (`--secrets-mask`), DOCX tables rendered as markdown, and the
+`--all-mask` shorthand for combined PII + secrets masking. Earlier
+phase boundaries kept inline as breadcrumbs for reviewers; the
+behaviours all ship in the same release.
+
+> **Phase trail (kept for reviewers):** Phase 11 introduced the
+> ingestion pipeline; Phase 11.5 added token-aware chunking + PDF page
+> header/footer dedup + structured ingestion notes; Phase 12 added
+> markdown-aware splitting + secrets scrubbing + DOCX table preservation;
+> Phase 12.5 added `--all-mask`. The four phases were consolidated into
+> a single `v0.5.0` release.
 
 > Pair with [`forgelm audit`](data_audit.md) afterwards to surface
 > length-distribution / language / near-duplicate / PII metrics, and with
@@ -20,7 +30,7 @@ pip install 'forgelm[ingestion]'
 ```
 
 The extra brings in `pypdf`, `python-docx`, `ebooklib`, `beautifulsoup4`,
-`langdetect`, and (since v0.5.1) the optional non-cryptographic `xxhash`
+`langdetect`, and the optional non-cryptographic `xxhash`
 backend used by the simhash digest. They are optional because plain text
 + Markdown work without any of them. Importing the module does not pull
 these in unless the matching extractor is exercised; `xxhash`'s absence
@@ -316,7 +326,7 @@ assistants, code-with-data prompts.
 ## Limitations
 
 - **OCR:** out of scope. Use external tooling — see the worked example below.
-- **Tables / figures:** Since Phase 12 (`v0.5.2`), `_extract_docx()`
+- **Tables / figures:** Since Phase 12 (consolidated into `v0.5.0`), `_extract_docx()`
   converts DOCX tables to **Markdown table syntax** (header + `---`
   separator + body rows) at extraction time, **before any chunking
   strategy runs** — so all strategies see the rendered Markdown, not a
diff --git a/docs/reference/usage-tr.md b/docs/reference/usage-tr.md
index 5662ac44..275f4745 100644
--- a/docs/reference/usage-tr.md
+++ b/docs/reference/usage-tr.md
@@ -110,7 +110,7 @@ forgelm --config my_config.yaml --generate-data
 
 Bu komut, eğitim başlamadan önce bir öğretmen modelden eğitim verisi üretmek için `synthetic` config bölümünü kullanır. Tüm sentetik veri seçenekleri için [Konfigürasyon Rehberi](configuration-tr.md)'ne bakın.
 
-### Doküman Yutma (v0.5.0+; v0.5.1 token-aware; v0.5.2 markdown + secrets-mask)
+### Doküman Yutma (v0.5.0)
 
 Ham PDF / DOCX / EPUB / TXT / Markdown'ı SFT'ye uygun JSONL'a dönüştürür. Opsiyonel bağımlılık: `pip install forgelm[ingestion]`. Ayrıntılar için [Doküman Yutma Rehberi](../guides/ingestion-tr.md).
 
@@ -128,31 +128,31 @@ forgelm ingest ./scan.pdf --strategy sliding --chunk-size 1024 --overlap 128 \
 # Yazmadan önce PII'yi maskele
 forgelm ingest ./customer_emails/ --pii-mask --output data/anon.jsonl
 
-# Token-aware chunking (v0.5.1) — chunk'ları modelinizin vocab'ına göre boyutlandırır
+# Token-aware chunking — chunk'ları modelinizin vocab'ına göre boyutlandırır
 forgelm ingest ./policies/ --recursive --output data/policies.jsonl \
   --chunk-tokens 1024 --tokenizer "Qwen/Qwen2.5-7B-Instruct"
 
-# v0.5.2: teknik wiki / README'ler için markdown-aware splitter
+# Teknik wiki / README'ler için markdown-aware splitter
 forgelm ingest ./engineering_wiki/ --recursive --strategy markdown \
   --output data/wiki.jsonl
 
-# v0.5.2: chunk'lar JSONL'a inmeden önce credential'ları temizle
+# Chunk'lar JSONL'a inmeden önce credential'ları temizle
 forgelm ingest ./mixed_corpus/ --secrets-mask --output data/clean.jsonl
 
-# v0.5.2: secrets + PII maskelemeyi birleştir (önce secrets, sonra PII —
+# Secrets + PII maskelemeyi birleştir (önce secrets, sonra PII —
 # örtüşen span'ler iki kez sayılmasın)
 forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/scrubbed.jsonl
 
-# v0.5.3 (Faz 12.5): yukarıdaki kombinasyonun tek-flag kısayolu
+# Yukarıdaki kombinasyonun tek-flag kısayolu
 forgelm ingest ./mixed_corpus/ --all-mask --output data/scrubbed.jsonl
 ```
 
-### Veri Seti Denetimi (v0.5.0+; v0.5.1 subcommand; v0.5.2 MinHash + quality + secrets)
+### Veri Seti Denetimi (v0.5.0)
 
 CPU-only kalite + governance denetimi. `data_audit_report.json` üretir. Ayrıntılar için [Denetim Rehberi](../guides/data_audit-tr.md).
 
 ```bash
-# Tek split (v0.5.1 subcommand)
+# Tek split (subcommand)
 forgelm audit data/sft.jsonl --output ./audit/
 
 # Çoklu split (train.jsonl / validation.jsonl / test.jsonl içeren dizin)
@@ -164,17 +164,17 @@ forgelm audit data/ --verbose
 # Özel Hamming eşiği
 forgelm audit data/ --near-dup-threshold 5
 
-# v0.5.2: >50K satırlık korpuslar için MinHash LSH dedup
+# >50K satırlık korpuslar için MinHash LSH dedup
 # Önce extra'yı kurun:  pip install forgelm[ingestion-scale]
 forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold 0.85
 
-# v0.5.2: opt-in heuristik kalite filtresi (Gopher/C4 stili)
+# Opt-in heuristik kalite filtresi (Gopher/C4 stili)
 forgelm audit data/ --quality-filter
 
-# v0.5.3 (Faz 12.5): audit'in yanında bir Google Croissant 1.0 dataset card emit et
+# Audit'in yanında bir Google Croissant 1.0 dataset card emit et
 forgelm audit data/ --output ./audit/ --croissant
 
-# v0.5.3 (Faz 12.5): regex PII detector üzerine Presidio NER katmanı ekle
+# Regex PII detector üzerine Presidio NER katmanı ekle
 # (`[ingestion-pii-ml]` extra'sını gerektirir — person/organization/location kategorileri ekler)
 forgelm audit data/ --output ./audit/ --pii-ml
 
@@ -185,7 +185,7 @@ forgelm audit data/sft.jsonl --output ./audit/ --output-format json
 forgelm --data-audit data/sft.jsonl --output ./audit/
 ```
 
-Denetim şunları yakalar: split başına örnek sayısı + uzunluk dağılımı, top-3 dil tespiti, **LSH-banded** simhash near-duplicate oranı (Faz 11.5; uç eşiklerde brute-force fallback; v0.5.2 opsiyonel **MinHash LSH** yolu ekledi), cross-split sızıntı (sessiz train-test örtüşmesi), PII flag sayıları + **şiddet katmanları** (`pii_severity` bloğu her PII tipini critical / high / medium / low olarak puanlar ve bir `worst_tier` verdict yüzdürür), her zaman açık **credentials/secrets taraması** (`secrets_summary` — `forgelm.data_audit.SECRET_TYPES`'ta tanımlı dokuz aile: `aws_access_key`, `github_token`, `slack_token`, `openai_api_key`, `google_api_key`, `jwt`, `openssh_private_key` (tam BEGIN…END bloğu), `pgp_private_key` (tam BEGIN…END bloğu), `azure_storage_key`), ve opt-in **heuristik kalite filtresi** (`--quality-filter`, `quality_summary` bloğu üretir).
+Denetim şunları yakalar: split başına örnek sayısı + uzunluk dağılımı, top-3 dil tespiti, **LSH-banded** simhash near-duplicate oranı (uç eşiklerde brute-force fallback; opsiyonel **MinHash LSH** yolu `--dedup-method minhash` ile), cross-split sızıntı (sessiz train-test örtüşmesi), PII flag sayıları + **şiddet katmanları** (`pii_severity` bloğu her PII tipini critical / high / medium / low olarak puanlar ve bir `worst_tier` verdict yüzdürür), her zaman açık **credentials/secrets taraması** (`secrets_summary` — `forgelm.data_audit.SECRET_TYPES`'ta tanımlı dokuz aile: `aws_access_key`, `github_token`, `slack_token`, `openai_api_key`, `google_api_key`, `jwt`, `openssh_private_key` (tam BEGIN…END bloğu), `pgp_private_key` (tam BEGIN…END bloğu), `azure_storage_key`), ve opt-in **heuristik kalite filtresi** (`--quality-filter`, `quality_summary` bloğu üretir).
 
 Trainer'ın `output_dir`'ünde `data_audit_report.json` mevcutsa, bulgular EU AI Act Madde 10 governance artifact'ında `data_audit` anahtarı altında otomatik olarak inline edilir.
 
diff --git a/docs/reference/usage.md b/docs/reference/usage.md
index eb850c7c..ca254fde 100644
--- a/docs/reference/usage.md
+++ b/docs/reference/usage.md
@@ -129,7 +129,7 @@ forgelm --config my_config.yaml --generate-data
 
 This uses the `synthetic` config section to generate training data from a teacher model before training begins. See the [Configuration Guide](configuration.md) for all synthetic data options.
 
-### Document Ingestion (v0.5.0+; token-aware in v0.5.1; markdown + secrets-mask in v0.5.2)
+### Document Ingestion (v0.5.0)
 
 Convert raw PDF / DOCX / EPUB / TXT / Markdown into SFT-ready JSONL. Optional dep: `pip install forgelm[ingestion]`. See [Ingestion Guide](../guides/ingestion.md).
 
@@ -147,30 +147,30 @@ forgelm ingest ./scan.pdf --strategy sliding --chunk-size 1024 --overlap 128 \
 # Mask PII before writing
 forgelm ingest ./customer_emails/ --pii-mask --output data/anon.jsonl
 
-# Token-aware chunking (v0.5.1) — sizes chunks against your model's vocab
+# Token-aware chunking — sizes chunks against your model's vocab
 forgelm ingest ./policies/ --recursive --output data/policies.jsonl \
   --chunk-tokens 1024 --tokenizer "Qwen/Qwen2.5-7B-Instruct"
 
-# v0.5.2: markdown-aware splitter for technical wikis / READMEs
+# Markdown-aware splitter for technical wikis / READMEs
 forgelm ingest ./engineering_wiki/ --recursive --strategy markdown \
   --output data/wiki.jsonl
 
-# v0.5.2: scrub credentials before chunks land in the JSONL
+# Scrub credentials before chunks land in the JSONL
 forgelm ingest ./mixed_corpus/ --secrets-mask --output data/clean.jsonl
 
-# v0.5.2: combine secrets + PII masking (secrets first to avoid double-counting)
+# Combine secrets + PII masking (secrets first to avoid double-counting)
 forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/scrubbed.jsonl
 
-# v0.5.3 (Phase 12.5): one-flag shorthand for the same combination above
+# One-flag shorthand for the same combination above
 forgelm ingest ./mixed_corpus/ --all-mask --output data/scrubbed.jsonl
 ```
 
-### Dataset Audit (v0.5.0+; subcommand promoted in v0.5.1; MinHash + quality + secrets in v0.5.2)
+### Dataset Audit (v0.5.0)
 
 CPU-only quality + governance audit. Produces `data_audit_report.json`. See [Audit Guide](../guides/data_audit.md).
 
 ```bash
-# Single split (v0.5.1 subcommand)
+# Single split (subcommand)
 forgelm audit data/sft.jsonl --output ./audit/
 
 # Multi-split directory (train.jsonl / validation.jsonl / test.jsonl)
@@ -182,16 +182,16 @@ forgelm audit data/ --verbose
 # Custom Hamming threshold for simhash near-duplicate detection
 forgelm audit data/ --near-dup-threshold 5
 
-# v0.5.2: MinHash LSH dedup for >50K-row corpora (needs `[ingestion-scale]` extra)
+# MinHash LSH dedup for >50K-row corpora (needs `[ingestion-scale]` extra)
 forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold 0.85
 
-# v0.5.2: opt-in heuristic quality filter (Gopher/C4 style)
+# Opt-in heuristic quality filter (Gopher/C4 style)
 forgelm audit data/ --quality-filter
 
-# v0.5.3 (Phase 12.5): emit a Google Croissant 1.0 dataset card alongside the audit
+# Emit a Google Croissant 1.0 dataset card alongside the audit
 forgelm audit data/ --output ./audit/ --croissant
 
-# v0.5.3 (Phase 12.5): layer Presidio NER on top of the regex PII detector
+# Layer Presidio NER on top of the regex PII detector
 # (needs `[ingestion-pii-ml]` extra — adds person/organization/location categories)
 forgelm audit data/ --output ./audit/ --pii-ml
 
@@ -202,7 +202,7 @@ forgelm audit data/sft.jsonl --output ./audit/ --output-format json
 forgelm --data-audit data/sft.jsonl --output ./audit/
 ```
 
-The audit captures: per-split sample count + length distribution, top-3 language detection, **LSH-banded** simhash near-duplicate rate (Phase 11.5; brute-force fallback at edge thresholds; v0.5.2 added optional **MinHash LSH** path), cross-split leakage (silent train-test overlap), PII flag counts with **severity tiers**, **always-on credentials/secrets scan** (`secrets_summary` — nine families per `forgelm.data_audit.SECRET_TYPES`: `aws_access_key`, `github_token`, `slack_token`, `openai_api_key`, `google_api_key`, `jwt`, `openssh_private_key` (full BEGIN…END block), `pgp_private_key` (full BEGIN…END block), `azure_storage_key`), and an opt-in **heuristic quality filter** (Gopher/C4 style) that adds a `quality_summary` block.
+The audit captures: per-split sample count + length distribution, top-3 language detection, **LSH-banded** simhash near-duplicate rate (brute-force fallback at edge thresholds; optional **MinHash LSH** path via `--dedup-method minhash`), cross-split leakage (silent train-test overlap), PII flag counts with **severity tiers**, **always-on credentials/secrets scan** (`secrets_summary` — nine families per `forgelm.data_audit.SECRET_TYPES`: `aws_access_key`, `github_token`, `slack_token`, `openai_api_key`, `google_api_key`, `jwt`, `openssh_private_key` (full BEGIN…END block), `pgp_private_key` (full BEGIN…END block), `azure_storage_key`), and an opt-in **heuristic quality filter** (Gopher/C4 style) that adds a `quality_summary` block.
 
 When `data_audit_report.json` is present in the trainer's `output_dir` at training time, its findings are inlined under the `data_audit` key of the EU AI Act Article 10 governance artifact automatically.
 
diff --git a/docs/roadmap-tr.md b/docs/roadmap-tr.md
index 55fe8290..dc5b0578 100644
--- a/docs/roadmap-tr.md
+++ b/docs/roadmap-tr.md
@@ -9,24 +9,26 @@
 | ✅ Tamam | [Faz 1-9](roadmap/completed-phases.md) | SOTA iyileştirmeleri, değerlendirme, güvenilirlik, kurumsal entegrasyon, ekosistem, hizalama stack'i, güvenlik, EU AI Act uyumluluğu (Madde 9-17 + Ek IV), gelişmiş güvenlik zekası |
 | ✅ Tamam | [Faz 10 — Post-Training Tamamlama](roadmap/phase-10-post-training.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — `v0.4.0` |
 | ✅ Tamam | [Faz 10.5 — Quickstart Katmanı ve Onboarding](roadmap/phase-10-5-quickstart.md) | `forgelm quickstart <template>`, 5 hazır template, seed veri setleri — `v0.4.5` |
-| ✅ Tamam | [Faz 11 — Doküman Yutma ve Veri Denetimi](roadmap/phase-11-data-ingestion.md) | `forgelm ingest`, `forgelm --data-audit`, PII regex + simhash dedup — `v0.5.0` çıktı |
-| 🟡 Birleşti | [Faz 11.5 — Yutma / Denetim Cilası](roadmap/phase-11-5-backlog.md) | LSH banding, streaming reader, `forgelm audit` subcommand, PII şiddet katmanları, wizard ingest girişi — `main`'e indi (PR #11/#12); `v0.5.1` PyPI tag'i bekliyor |
-| 🟡 Birleşti | [Faz 12 — Veri Curation Olgunlaşması](roadmap/phase-12-data-curation-maturity.md) | MinHash LSH dedup, markdown-aware splitter, code/secrets tarama, kalite heuristic'leri, tablo yapısı koruma — Tier 1 `main`'e indi (PR #13, 2026-04-29); `v0.5.2` PyPI tag'i bekliyor; Tier 2/3 [Faz 12.5 backlog](roadmap/phase-12-5-backlog.md)'a ertelendi |
-| 🟡 Birleşti | [Faz 12.5 — Veri Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adaptörü (`[ingestion-pii-ml]`), Croissant 1.0 metadata (`--croissant`), `--all-mask`, wizard "audit first" — `development`'a indi; `v0.5.3` (Faz 14) ile çıkacak |
-| 📋 Planlandı | [Faz 14 — Çok Aşamalı Pipeline Zincirleri](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO config zinciri, pipeline kaynak izleri → `v0.5.3` |
+| 🟡 Birleşti | [Faz 11 + 11.5 + 12 + 12.5 — Doküman Yutma ve Veri Curation Pipeline'ı](roadmap/releases.md#v050--document-ingestion--data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII şiddet katmanları, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets tarama, kalite heuristic'leri, DOCX tablo koruması, `--all-mask`, Croissant 1.0, Presidio NER — `main`'e indi; `v0.5.0` PyPI tag'i bekliyor |
+| 📋 Planlandı | [Faz 14 — Çok Aşamalı Pipeline Zincirleri](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO config zinciri, pipeline kaynak izleri → `v0.5.1` |
 | 📋 Planlandı | [Faz 13 — Pro CLI ve Gözlemlenebilirlik Dashboard](roadmap/phase-13-pro-cli.md) | Lisans korumalı dashboard, HPO, zamanlanmış görevler, takım config store → `v0.6.0-pro` |
 
-**`main`'e indi, tag + PyPI publish bekliyor:** `v0.5.1` — Yutma / Denetim Cilası (Faz 11.5). LSH bantlı near-duplicate tespiti, streaming JSONL okuyucu, token-aware chunking, PDF header/footer dedup, `forgelm audit` subcommand, PII şiddet katmanları, yapılandırılmış ingestion notları, wizard "ingest first" girişi.
+**`main`'e indi, tag + PyPI publish bekliyor:** `v0.5.0` — "Doküman Yutma + Veri Curation Pipeline'ı" (Faz 11 + 11.5 + 12 + 12.5 birleştirildi).
 
-**`main`'e indi (PR #13, 2026-04-29), tag + PyPI publish bekliyor:** `v0.5.2` — Veri Curation Olgunlaşması (Faz 12). 50K+ satır corpus için MinHash LSH dedup opsiyonu (`[ingestion-scale]` extra), markdown-aware splitter, code/secrets sızıntı taraması + ingest tarafı `--secrets-mask` (`[ingestion-secrets]` extra), heuristic kalite filtresi, DOCX/Markdown tablo yapısı koruma. Faz 11/11.5 ingestion + audit hattının doğal devamı; `v0.5.1` sonrası rekabet analizinin yüzeylediği boşlukları kapatır. Tier 2/3 follow-up'ları (Presidio adapter, Croissant metadata, `--all-mask`, wizard "audit first") [Faz 12.5 backlog](roadmap/phase-12-5-backlog.md)'a ertelendi. Hardening follow-up ayrıca takipte: [#14 — webhook SSRF DNS-rebinding TOCTOU](https://github.com/cemililik/ForgeLM/issues/14).
+- **Faz 11** — `forgelm ingest` (PDF / DOCX / EPUB / TXT / Markdown → SFT'ye uygun JSONL) + `forgelm audit` (uzunluk / dil / near-duplicate / cross-split sızıntı / Luhn + TC Kimlik validatörlü PII regex) + EU AI Act Madde 10 governance entegrasyonu.
+- **Faz 11.5** — operasyonel cila: LSH bantlı near-duplicate tespiti, streaming JSONL okuyucu, token-aware `--chunk-tokens`, PDF sayfa-seviyesi header/footer dedup, `forgelm audit` subcommand'i, PII şiddet katmanları, atomic audit yazımı, wizard "ingest first" girişi.
+- **Faz 12** — veri curation olgunlaşması: MinHash LSH dedup opsiyonu (`--dedup-method minhash`, `[ingestion-scale]` extra), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`--secrets-mask`, `secrets_summary` her zaman açık), heuristic kalite filtresi (`--quality-filter`), DOCX/Markdown tablo yapısı koruması.
+- **Faz 12.5** — küçük additive cila: birleşik PII + secrets temizliği için `--all-mask` kısayolu, `forgelm audit --croissant` Google Croissant 1.0 dataset card emit ediyor, opsiyonel Presidio ML-NER PII adaptörü (`--pii-ml`, `[ingestion-pii-ml]` extra), wizard "audit first" entry point.
 
-**PyPI'deki son sürüm:** `v0.4.5` — Quickstart Katmanı (2026-04-26). Tek komutla hazır template'ler: `forgelm quickstart customer-support`. `v0.5.0` / `v0.5.1` / `v0.5.2` `main`'e birleştirildi ama henüz tag + publish edilmedi; bir sonraki PyPI sürümü üçünü birden (veya sırayla — release-engineering kararı) yakalar.
+Başlangıçta dört ardışık PyPI tag'i (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`) olarak planlandı, dört faz tek tutarlı yüzey (yut → cila → olgunlaş → cila) oluşturduğu için tek kapsamlı `v0.5.0` release'inde birleştirildi.
+
+**PyPI'deki son sürüm:** `v0.4.5` — Quickstart Katmanı (2026-04-26). Tek komutla hazır template'ler: `forgelm quickstart customer-support`. Küçük GPU'larda model otomatik downsize ediliyor, mevcut trainer'ın değişiklik gerektirmeden kabul edeceği bir config üretiyor.
 
 **Daha öncesi:** `v0.4.0` — Post-Training Tamamlama (2026-04-26). Inference primitif'leri, etkileşimli chat REPL, GGUF export, VRAM fit advisor, deployment config üretimi.
 
-**Sonraki:** `v0.5.3` — Çok Aşamalı Pipeline Zincirleri (Faz 14) + Faz 12.5 cilası. SFT → DPO → GRPO zincir konfigürasyonu, pipeline kaynak izleri. `v0.5.2` PyPI tag'inden sonra başlar; [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını ve `development`'a inen dört Faz 12.5 backlog item'ını (Presidio NER, Croissant 1.0 card, `--all-mask`, wizard "audit first") kapsar.
+**Sonraki:** `v0.5.1` — Çok Aşamalı Pipeline Zincirleri (Faz 14). SFT → DPO → GRPO zincir konfigürasyonu, pipeline kaynak izleri. `v0.5.0` PyPI tag'inden sonra başlar. [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını kapsar.
 
-**Güncel durum:** 16 faz (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12) tamam. 3 faz (12.5, 13, 14) planlandı. `v0.5.3`: Faz 14 (12.5 backlog'u fırsat oldukça eklenir). `v0.6.0-pro` (Faz 13) adoption metriklerine bağlı.
+**Güncel durum:** 17 faz (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12, 12.5) tamam. 2 faz (13, 14) planlandı. `v0.5.1`: Faz 14. `v0.6.0-pro` (Faz 13) adoption metriklerine bağlı.
 
 ## Planlanan işlerin özeti
 
@@ -44,17 +46,18 @@ graph LR
     P10 -.-> V1[v0.4.0]
     P105 -.-> V15[v0.4.5]
     P11 -.-> V2[v0.5.0 pending]
-    P115 -.-> V21[v0.5.1 pending]
-    P12 -.-> V22[v0.5.2 pending]
-    P14 -.-> V23[v0.5.3]
+    P115 -.-> V2
+    P12 -.-> V2
+    P125 -.-> V2
+    P14 -.-> V23[v0.5.1]
     P13 -.-> V3[v0.6.0-pro]
 
     style P10 fill:#003300,stroke:#00ff88
     style P105 fill:#003300,stroke:#00ff88
-    style P11 fill:#003300,stroke:#00ff88
+    style P11 fill:#004400,stroke:#88ff88
     style P115 fill:#004400,stroke:#88ff88
     style P12 fill:#004400,stroke:#88ff88
-    style P125 fill:#002244,stroke:#00aaff
+    style P125 fill:#004400,stroke:#88ff88
     style P14 fill:#002244,stroke:#00aaff
     style P13 fill:#442200,stroke:#ffaa00
 ```
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 25b67dcc..7166ed8f 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -9,24 +9,26 @@
 | ✅ Done | [Phase 1-9](roadmap/completed-phases.md) | SOTA upgrades, evaluation, reliability, enterprise integration, ecosystem, alignment stack, safety, EU AI Act compliance (Articles 9-17 + Annex IV), advanced safety intelligence |
 | ✅ Done | [Phase 10 — Post-Training Completion](roadmap/phase-10-post-training.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — shipped `v0.4.0` |
 | ✅ Done | [Phase 10.5 — Quickstart Layer & Onboarding](roadmap/phase-10-5-quickstart.md) | `forgelm quickstart <template>`, 5 bundled templates with seed datasets — shipped `v0.4.5` |
-| ✅ Done | [Phase 11 — Document Ingestion & Data Audit](roadmap/phase-11-data-ingestion.md) | `forgelm ingest`, `forgelm --data-audit`, PII regex + simhash dedup — shipped `v0.5.0` |
-| 🟡 Merged | [Phase 11.5 — Ingestion / Audit Polish](roadmap/phase-11-5-backlog.md) | LSH banding, streaming reader, `forgelm audit` subcommand, PII severity tiers, wizard ingest path — merged to `main` (PR #11/#12); PyPI tag pending as `v0.5.1` |
-| 🟡 Merged | [Phase 12 — Data Curation Maturity](roadmap/phase-12-data-curation-maturity.md) | MinHash LSH dedup, markdown-aware splitter, code/secrets scan, quality heuristics, table preservation — Tier 1 merged to `main` (PR #13, 2026-04-29); PyPI tag pending as `v0.5.2`; Tier 2/3 deferred to [Phase 12.5 backlog](roadmap/phase-12-5-backlog.md) |
-| 🟡 Merged | [Phase 12.5 — Data Curation Follow-up](roadmap/phase-12-5-backlog.md) | Presidio PII adapter (`[ingestion-pii-ml]`), Croissant 1.0 metadata (`--croissant`), `--all-mask`, wizard "audit first" — implemented on `development`; ships with `v0.5.3` (Phase 14) |
-| 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.5.3` |
+| 🟡 Merged | [Phase 11 + 11.5 + 12 + 12.5 — Document Ingestion & Data Curation Pipeline](roadmap/releases.md#v050--document-ingestion--data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII severity tiers, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets scan, quality heuristics, DOCX table preservation, `--all-mask`, Croissant 1.0, Presidio NER — merged to `main`; PyPI tag pending as `v0.5.0` |
+| 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.5.1` |
 | 📋 Planned | [Phase 13 — Pro CLI & Observability Dashboard](roadmap/phase-13-pro-cli.md) | License-gated dashboard, HPO, scheduled jobs, team config store → `v0.6.0-pro` |
 
-**Merged on `main`, tag + PyPI publish pending:** `v0.5.1` — Ingestion / Audit Polish (Phase 11.5). LSH-banded near-duplicate detection, streaming JSONL reader, token-aware chunking, PDF header/footer dedup, `forgelm audit` subcommand, PII severity tiers, structured ingestion notes, and a wizard "ingest first" entry point that converts a directory of raw documents inline.
+**Merged on `main`, tag + PyPI publish pending:** `v0.5.0` — "Document Ingestion + Data Curation Pipeline" (Phases 11 + 11.5 + 12 + 12.5 consolidated).
 
-**Merged on `main` (PR #13, 2026-04-29), tag + PyPI publish pending:** `v0.5.2` — Data Curation Maturity (Phase 12). MinHash LSH dedup option for >50K-row corpora (`[ingestion-scale]` extra), markdown-aware splitter, code/secrets leakage scan + ingest-side `--secrets-mask` (`[ingestion-secrets]` extra), heuristic quality filter, DOCX/Markdown table preservation. Direct continuation of the Phase 11/11.5 ingestion + audit lineage; closes the gaps surfaced by the post-`v0.5.1` competitive review. Tier 2/3 follow-ups (Presidio adapter, Croissant metadata, `--all-mask`, wizard "audit first") deferred to [Phase 12.5 backlog](roadmap/phase-12-5-backlog.md). Hardening follow-up tracked separately: [#14 — webhook SSRF DNS-rebinding TOCTOU](https://github.com/cemililik/ForgeLM/issues/14).
+- **Phase 11** — `forgelm ingest` (PDF / DOCX / EPUB / TXT / Markdown → SFT-ready JSONL) + `forgelm audit` (length / language / near-duplicate / cross-split leakage / PII regex with Luhn + TC Kimlik validators) + EU AI Act Article 10 governance integration.
+- **Phase 11.5** — operational polish: LSH-banded near-duplicate detection, streaming JSONL reader, token-aware `--chunk-tokens`, PDF page-level header/footer dedup, `forgelm audit` subcommand, PII severity tiers, atomic audit writes, wizard "ingest first" entry point.
+- **Phase 12** — data curation maturity: MinHash LSH dedup option (`--dedup-method minhash`, `[ingestion-scale]` extra), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`--secrets-mask`, `secrets_summary` always-on), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation.
+- **Phase 12.5** — small additive polish: `--all-mask` shorthand for combined PII + secrets scrubbing, `forgelm audit --croissant` emits a Google Croissant 1.0 dataset card, optional Presidio ML-NER PII adapter (`--pii-ml`, `[ingestion-pii-ml]` extra), wizard "audit first" entry point.
 
-**Latest release on PyPI:** `v0.4.5` — Quickstart Layer (2026-04-26). One-command bundled templates: `forgelm quickstart customer-support`. Auto-downsizes models on small GPUs, generates a config that the existing trainer accepts unchanged. `v0.5.0` / `v0.5.1` / `v0.5.2` are merged on `main` but have not yet been tagged + published; the next PyPI release will catch all three together (or in sequence — release-engineering call).
+Originally planned as four sequential PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`), consolidated into one comprehensive `v0.5.0` release because the four phases form one coherent surface (ingest → polish → mature → polish) hard to use in parts.
+
+**Latest release on PyPI:** `v0.4.5` — Quickstart Layer (2026-04-26). One-command bundled templates: `forgelm quickstart customer-support`. Auto-downsizes models on small GPUs, generates a config that the existing trainer accepts unchanged.
 
 **Earlier:** `v0.4.0` — Post-Training Completion (2026-04-26). Inference primitives, interactive chat REPL, GGUF export, VRAM fit advisor, deployment config generation.
 
-**Next:** `v0.5.3` — Multi-Stage Pipeline Chains (Phase 14) + Phase 12.5 polish. SFT → DPO → GRPO chained config, pipeline provenance artifacts. Starts after the `v0.5.2` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) and the four Phase 12.5 backlog items now landed on `development` (Presidio NER, Croissant 1.0 card, `--all-mask`, wizard "audit first").
+**Next:** `v0.5.1` — Multi-Stage Pipeline Chains (Phase 14). SFT → DPO → GRPO chained config, pipeline provenance artifacts. Starts after the `v0.5.0` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14).
 
-**Current state:** 16 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12) complete. 3 phases (12.5, 13, 14) planned. `v0.5.3`: Phase 14 (12.5 backlog folded in opportunistically). `v0.6.0-pro` (Phase 13) gated on adoption metrics.
+**Current state:** 17 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12, 12.5) complete. 2 phases (13, 14) planned. `v0.5.1`: Phase 14. `v0.6.0-pro` (Phase 13) gated on adoption metrics.
 
 ## Quick summary of what's planned
 
@@ -43,18 +45,19 @@ graph LR
 
     P10 -.-> V1[v0.4.0]
     P105 -.-> V15[v0.4.5]
-    P11 -.-> V2[v0.5.0]
-    P115 -.-> V21[v0.5.1 pending]
-    P12 -.-> V22[v0.5.2 pending]
-    P14 -.-> V23[v0.5.3]
+    P11 -.-> V2[v0.5.0 pending]
+    P115 -.-> V2
+    P12 -.-> V2
+    P125 -.-> V2
+    P14 -.-> V23[v0.5.1]
     P13 -.-> V3[v0.6.0-pro]
 
     style P10 fill:#003300,stroke:#00ff88
     style P105 fill:#003300,stroke:#00ff88
-    style P11 fill:#003300,stroke:#00ff88
+    style P11 fill:#004400,stroke:#88ff88
     style P115 fill:#004400,stroke:#88ff88
     style P12 fill:#004400,stroke:#88ff88
-    style P125 fill:#002244,stroke:#00aaff
+    style P125 fill:#004400,stroke:#88ff88
     style P14 fill:#002244,stroke:#00aaff
     style P13 fill:#442200,stroke:#ffaa00
 ```
diff --git a/docs/roadmap/phase-11-5-backlog.md b/docs/roadmap/phase-11-5-backlog.md
index 2b9d70a5..ca5da228 100644
--- a/docs/roadmap/phase-11-5-backlog.md
+++ b/docs/roadmap/phase-11-5-backlog.md
@@ -1,6 +1,11 @@
 # Phase 11.5 — Ingestion / Audit Polish
 
-> **Status:** ✅ Landed for the `v0.5.1` cycle. All 12 follow-ups carved
+> **Note (post-consolidation):** Originally targeted `v0.5.1`, now ships
+> as part of the consolidated `v0.5.0` release alongside Phases 11, 12,
+> and 12.5 — see [releases.md](releases.md#v050--document-ingestion--data-curation-pipeline).
+> Version-label references below preserve the historical planning trail.
+>
+> **Status:** ✅ Landed for the (originally) `v0.5.1` cycle. All 12 follow-ups carved
 > out of Phase 11's review backlog have shipped. Modules touched:
 > [`forgelm/data_audit.py`](../../forgelm/data_audit.py),
 > [`forgelm/ingestion.py`](../../forgelm/ingestion.py),
diff --git a/docs/roadmap/phase-12-5-backlog.md b/docs/roadmap/phase-12-5-backlog.md
index 88ee36f4..e2c8f5c7 100644
--- a/docs/roadmap/phase-12-5-backlog.md
+++ b/docs/roadmap/phase-12-5-backlog.md
@@ -1,6 +1,12 @@
 # Phase 12.5 — Data Curation Polish Backlog
 
-> **Follow-up to Phase 12.** Phase 12 (`v0.5.2`) shipped the five Tier 1
+> **Note (post-consolidation):** Originally targeted `v0.5.3`; all four
+> backlog items now ship together with Phases 11 / 11.5 / 12 in the
+> consolidated `v0.5.0` release (see [releases.md](releases.md#v050--document-ingestion--data-curation-pipeline)).
+> The version-label references below preserve the historical planning
+> trail.
+>
+> **Follow-up to Phase 12.** Phase 12 (originally targeted `v0.5.2`) shipped the five Tier 1
 > must-haves: MinHash LSH dedup option, markdown-aware splitter,
 > code/secrets leakage tagger, heuristic quality filter, DOCX/Markdown
 > table preservation. Three Tier 2/3 items were tagged "if scope allows"
@@ -16,10 +22,10 @@
 
 | # | Item | Source | Effort | Status |
 |---|---|---|---|---|
-| **1** | ~~**Presidio adapter** (`[ingestion-pii-ml]` extra, optional)~~ | Phase 12 plan Tier 2 #6 | S–M | ✅ Landed on `development` — `forgelm audit --pii-ml`; new `PII_ML_SEVERITY` table; opt-in `[ingestion-pii-ml]` extra (`presidio-analyzer`); ships with `v0.5.3`. |
-| **2** | ~~**Croissant metadata compatibility** (audit JSON)~~ | Phase 12 plan Tier 2 #7 | S | ✅ Landed on `development` — `forgelm audit --croissant`; Croissant 1.0 card under report's `croissant` key; existing keys byte-equivalent when off. |
-| **3** | ~~**`forgelm ingest --all-mask` composite flag**~~ | Phase 12 plan Tier 3 #8 | XS | ✅ Landed on `development` — `forgelm ingest --all-mask`; set-union with explicit flags; resolved at the CLI boundary. |
-| **4** | ~~**Wizard "audit first" entry point**~~ | Phase 12 plan Tier 3 #9 | S | ✅ Landed on `development` — `_offer_audit_for_jsonl` invoked from the three JSONL-finalisation paths in `forgelm/wizard.py`. |
+| **1** | ~~**Presidio adapter** (`[ingestion-pii-ml]` extra, optional)~~ | Phase 12 plan Tier 2 #6 | S–M | ✅ Landed on `development` — `forgelm audit --pii-ml`; new `PII_ML_SEVERITY` table; opt-in `[ingestion-pii-ml]` extra (`presidio-analyzer`); ships with `v0.5.0` (consolidated release). |
+| **2** | ~~**Croissant metadata compatibility** (audit JSON)~~ | Phase 12 plan Tier 2 #7 | S | ✅ Landed on `development` — `forgelm audit --croissant`; Croissant 1.0 card under report's `croissant` key; existing keys byte-equivalent when off. Ships with `v0.5.0`. |
+| **3** | ~~**`forgelm ingest --all-mask` composite flag**~~ | Phase 12 plan Tier 3 #8 | XS | ✅ Landed on `development` — `forgelm ingest --all-mask`; set-union with explicit flags; resolved at the CLI boundary. Ships with `v0.5.0`. |
+| **4** | ~~**Wizard "audit first" entry point**~~ | Phase 12 plan Tier 3 #9 | S | ✅ Landed on `development` — `_offer_audit_for_jsonl` invoked from the three JSONL-finalisation paths in `forgelm/wizard.py`. Ships with `v0.5.0`. |
 
 ## Why these landed here, not in Phase 12
 
diff --git a/docs/roadmap/phase-12-data-curation-maturity.md b/docs/roadmap/phase-12-data-curation-maturity.md
index 55852da4..e7f62179 100644
--- a/docs/roadmap/phase-12-data-curation-maturity.md
+++ b/docs/roadmap/phase-12-data-curation-maturity.md
@@ -1,6 +1,11 @@
 # Phase 12: Data Curation Maturity
 
-> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to Phase 11.5 → `phase-11-5-backlog.md`). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit.py), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli.py); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
+> **Note (post-consolidation):** Originally targeted `v0.5.2`, now ships
+> as part of the consolidated `v0.5.0` release alongside Phases 11, 11.5,
+> and 12.5 — see [releases.md](releases.md#v050--document-ingestion--data-curation-pipeline).
+> Version-label references below preserve the historical planning trail.
+>
+> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the (originally) `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to Phase 11.5 → `phase-11-5-backlog.md`). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit.py), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli.py); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
 
 > **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md). Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
 
diff --git a/docs/roadmap/phase-14-pipeline-chains.md b/docs/roadmap/phase-14-pipeline-chains.md
index dea32652..e8491bc5 100644
--- a/docs/roadmap/phase-14-pipeline-chains.md
+++ b/docs/roadmap/phase-14-pipeline-chains.md
@@ -70,7 +70,7 @@
 - `--dry-run` validates all stages' configs before any GPU allocation.
 
 ### Delivery:
-- Target release: `v0.5.3` (reslotted from `v0.5.2`; Phase 12 — Data Curation Maturity — now occupies `v0.5.2` as the direct continuation of the Phase 11/11.5 ingestion + audit lineage).
-- No hard blockers; Phase 12 is merged to `main` (PR #13). Starts after the `v0.5.2` PyPI tag is published.
+- Target release: `v0.5.1` (reslotted from `v0.5.3`; Phases 11 / 11.5 / 12 / 12.5 were consolidated into a single `v0.5.0` release because the four phases form one coherent ingestion + audit + curation surface — see [releases.md](releases.md#v050--document-ingestion--data-curation-pipeline)).
+- No hard blockers; Phase 12.5 (the most recent of the consolidated phases) is merged to `main`. Starts after the `v0.5.0` PyPI tag is published.
 
 ---
diff --git a/docs/roadmap/releases.md b/docs/roadmap/releases.md
index e10891d8..88dc51bb 100644
--- a/docs/roadmap/releases.md
+++ b/docs/roadmap/releases.md
@@ -80,68 +80,57 @@ Odak: [Phase 10](phase-10-post-training.md). Full post-training handoff: inferen
 
 ---
 
-## v0.5.0 — "Document Ingestion & Data Audit"
+## v0.5.0 — "Document Ingestion + Data Curation Pipeline"
 
-**Status:** Shipped (PR #11 merged to `main` 2026-04-27). Focus: [Phase 11](phase-11-data-ingestion.md). Bridges raw enterprise corpora to ForgeLM's training data format and surfaces governance signals before training.
+**Status:** Merged on `main` (Phases 11 + 11.5 + 12 + 12.5 consolidated; 2026-04-29). The `v0.5.0` git tag and PyPI publish are the remaining release-engineering steps. One hardening follow-up tracked outside the release: [#14 — webhook SSRF DNS-rebinding TOCTOU](https://github.com/cemililik/ForgeLM/issues/14) (defence-in-depth on top of the existing `allow_private_destinations: false` default).
 
-### Features:
-
-1. [x] **`forgelm/ingestion.py`** + **`forgelm ingest`** subcommand — Multi-format document → JSONL pipeline with `paragraph` (default) and `sliding` chunking strategies, recursive directory walk, optional `--pii-mask`. Supported extensions: `.pdf` (`pypdf`), `.docx` (`python-docx`), `.epub` (`ebooklib` + `beautifulsoup4`), `.txt`, `.md`. Output is `{"text": ...}` JSONL recognized by ForgeLM's data loader as pre-formatted SFT input — no further preprocessing needed. OCR is intentionally out of scope; scanned PDFs warn and produce zero chunks.
-
-2. [x] **`forgelm/data_audit.py`** + **`forgelm --data-audit`** top-level flag — Per-split metrics (sample count, column schema, length distribution `min/max/mean/p50/p95`, top-3 language detection, null/empty rate), 64-bit simhash near-duplicate detection within each split, cross-split overlap report (catches train-test leakage), PII regex with Luhn-validated credit cards and TC Kimlik checksum-validated TR IDs. Layout: single `.jsonl` → treated as `train`; directory → split-keyed (`train.jsonl` / `validation.jsonl` / `test.jsonl`) auto-discovered. Writes `data_audit_report.json` to `--output` (default `./audit/`); `--output-format json` mirrors the report on stdout for CI/CD. CPU-only, no network.
+> **Note on consolidation.** Originally planned as four sequential PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`), the four phases were consolidated into a single `v0.5.0` because they form one coherent surface (ingest → polish → mature → polish) hard to use in parts. Git history retains the four phases as separate commit batches; this entry collapses them into one user-facing release. CHANGELOG.md preserves the phase boundaries inside the `[0.5.0]` section so reviewers can map back to PR history (#11, #12, #13, #18).
 
-3. [x] **EU AI Act Article 10 integration** — `generate_data_governance_report` now inlines `data_audit_report.json` under the `data_audit` key when present in the trainer's `output_dir`. Compliance bundle becomes a single self-contained document.
+### Phase 11 — Document Ingestion & Data Audit
 
-4. [x] **`pyproject.toml` `[ingestion]` extra** — `pypdf`, `python-docx`, `ebooklib`, `beautifulsoup4`, `langdetect`. Cross-platform; no native compilation. Plain TXT / Markdown ingestion + the audit module work without installing the extra (PII regex, simhash, length stats are pure stdlib).
-
-5. [x] **Tests + docs** — `tests/test_ingestion.py` and `tests/test_data_audit.py` (54 tests; PDF round-trip skips when `pypdf` missing). New guides: [`docs/guides/ingestion.md`](../guides/ingestion.md), [`docs/guides/data_audit.md`](../guides/data_audit.md). README feature section, install matrix, and roadmap status updated.
-
----
+1. [x] **`forgelm/ingestion.py` + `forgelm ingest` subcommand** — Multi-format document → JSONL pipeline with `paragraph` (default) and `sliding` chunking strategies, recursive directory walk, optional `--pii-mask`. Supported extensions: `.pdf` (`pypdf`), `.docx` (`python-docx`), `.epub` (`ebooklib` + `beautifulsoup4`), `.txt`, `.md`. Output is `{"text": ...}` JSONL recognised by ForgeLM's data loader as pre-formatted SFT input. OCR is intentionally out of scope; scanned PDFs warn and produce zero chunks.
+2. [x] **`forgelm/data_audit.py` + `forgelm --data-audit` flag** — Per-split metrics (sample count, column schema, length distribution `min/max/mean/p50/p95`, top-3 language detection, null/empty rate), 64-bit simhash near-duplicate detection within each split, cross-split overlap report (catches train-test leakage), PII regex with Luhn-validated credit cards and TC Kimlik checksum-validated TR IDs. CPU-only, no network.
+3. [x] **EU AI Act Article 10 integration** — `generate_data_governance_report` inlines `data_audit_report.json` under the `data_audit` key when present in the trainer's `output_dir`.
+4. [x] **`pyproject.toml` `[ingestion]` extra** — `pypdf`, `python-docx`, `ebooklib`, `beautifulsoup4`, `langdetect`. Cross-platform; no native compilation.
 
-## v0.5.1 — "Ingestion / Audit Polish"
+### Phase 11.5 — Ingestion / Audit Polish
 
-**Status:** Merged on `main` (carried in via Phase 11/12 PRs). The `v0.5.1` git tag and PyPI publish are the remaining release-engineering steps. Focus: [Phase 11.5](phase-11-5-backlog.md). Operational polish on top of `v0.5.0`'s ingestion + audit surface — no new training capabilities, but materially better handling for large corpora and a cleaner CLI shape.
-
-### Features:
-
-1. [x] **`forgelm audit` subcommand** — Promotes the `--data-audit` top-level flag to a first-class subcommand with its own `--output` default. The flag is preserved as a deprecation alias; existing pipelines keep working.
-2. [x] **LSH-banded near-duplicate detection** — Replaces the `O(n²)` pair scan inside each split (and across splits) with locality-sensitive-hashing bands (4 × 16-bit on the 64-bit fingerprint, hash-bucket lookup). Drops average-case to `O(n × k)` and unblocks audits on 100K+ row corpora.
-3. [x] **Streaming `_read_jsonl_split`** — The audit's JSONL reader now yields rows lazily and the per-split aggregator stays generator-based until simhash collection. Bounds memory on multi-million-row splits.
-4. [x] **Token-aware `--chunk-tokens`** — Optional ingestion flag that sizes chunks against an HF tokenizer instead of raw character counts. Removes a class of "my chunks blew through `max_length`" surprises.
-5. [x] **PDF page-level header / footer dedup** — Repeated page headers (company watermark, page number) used to inflate near-duplicate counts; common-prefix / common-suffix detection across pages now strips them.
-6. [x] **PII severity tiers** — Audit output adds a `pii_severity` block grading each PII type as `low / medium / high / critical` (e.g. `credit_card` → critical, `phone` → low) so compliance reviewers get a one-glance verdict.
-7. [x] **`summarize_report` truncation policy** — Multi-split summaries get a `verbose=False` default that suppresses zero-finding splits. Operators see issues, not 100 lines of "all clean" rows.
-8. [x] **Structured ingestion notes** — `IngestionResult.extra_notes` keeps the human-readable list but gains a parallel `notes_structured: {key: value}` map (e.g. `{"skipped_files": 3, "pii_redactions": {...}}`) for programmatic consumers.
-9. [x] **Wizard "ingest first" entry point** — A first-class wizard option ("I have raw documents") routes to `forgelm ingest`, surfaces a JSONL path, and folds it back into the BYOD prompt — closing the onboarding loop end-to-end.
-10. [x] **xxhash backend for simhash + token-level memo** — Drop-in faster non-crypto digest path (BLAKE2b kept as fallback for sites that can't add the optional dep). Token-level `lru_cache` memoizes repeat tokens (the/and/etc.) for a 2–5× speedup on long corpora.
-11. [x] **Atomic audit report write** — `data_audit_report.json` is written via `tempfile.NamedTemporaryFile` + atomic rename so a crashed audit never leaves a half-written report on disk.
-
----
+1. [x] **`forgelm audit` subcommand** — promotes the `--data-audit` flag to a first-class subcommand. Flag preserved as a deprecation alias.
+2. [x] **LSH-banded near-duplicate detection** — replaces the `O(n²)` pair scan with locality-sensitive-hashing bands; drops average-case to `O(n × k)` and unblocks 100K+ row corpora.
+3. [x] **Streaming `_read_jsonl_split`** — JSONL reader yields rows lazily; per-split aggregator stays generator-based until simhash collection.
+4. [x] **Token-aware `--chunk-tokens`** — sizes chunks against an HF tokenizer instead of raw character counts.
+5. [x] **PDF page-level header / footer dedup** — repeated page headers (company watermark, page number) stripped automatically.
+6. [x] **PII severity tiers** — `pii_severity` block grades each PII type as `low / medium / high / critical` + worst-tier verdict.
+7. [x] **`summarize_report` truncation policy** — multi-split summaries default to `verbose=False`.
+8. [x] **Structured ingestion notes** — parallel `notes_structured: {key: value}` map for programmatic consumers.
+9. [x] **Wizard "ingest first" entry point** — first-class wizard option that routes to `forgelm ingest`.
+10. [x] **xxhash backend + token-level memo** — drop-in faster non-crypto digest path; `lru_cache`-memoised repeat tokens for 2–5× speedup.
+11. [x] **Atomic audit report write** — tempfile + atomic rename.
 
-## v0.5.2 — "Data Curation Maturity"
+### Phase 12 — Data Curation Maturity (Tier 1)
 
-**Status:** Tier 1 merged on `main` via PR #13 (2026-04-29). The `v0.5.2` git tag and PyPI publish are the remaining release-engineering steps. One hardening follow-up tracked outside the release: [#14 — webhook SSRF DNS-rebinding TOCTOU](https://github.com/cemililik/ForgeLM/issues/14) (defence-in-depth on top of the existing `allow_private_destinations: false` default). Focus: [Phase 12](phase-12-data-curation-maturity.md). Direct continuation of the Phase 11/11.5 ingestion + audit lineage — closes the four gaps surfaced by the post-`v0.5.1` competitive review (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling).
+1. [x] **MinHash LSH dedup option** — opt-in `--dedup-method minhash --jaccard-threshold 0.85` via `datasketch` (`[ingestion-scale]` extra). Default simhash + LSH banding stays untouched.
+2. [x] **Markdown-aware splitter** — `--strategy markdown` preserves heading hierarchy (`# H1` / `## H2`), keeps fenced code blocks atomic, and inlines a heading breadcrumb so SFT loss sees document context.
+3. [x] **Code / secrets leakage tagger** — new `secrets_summary` block in audit JSON (nine families per `forgelm.data_audit.SECRET_TYPES`). Ingest gains `--secrets-mask` (mask order: secrets → PII).
+4. [x] **Heuristic quality filter** — opt-in `--quality-filter` adds a `quality_summary` block with Gopher / C4 / RefinedWeb-style heuristics.
+5. [x] **DOCX / Markdown table preservation** — `_extract_docx` emits markdown table syntax instead of the previous `" | "` flat join.
 
-### Tier 1 features (shipped):
+### Phase 12.5 — Data Curation Polish (backlog items #1–#4)
 
-1. [x] **MinHash LSH dedup option** — Opt-in `--dedup-method minhash --jaccard-threshold 0.85` route via `datasketch` (`[ingestion-scale]` extra) for >50K-row corpora. Default simhash + LSH banding stays untouched.
-2. [x] **Markdown-aware splitter** — New `--strategy markdown` preserves heading hierarchy (`# H1` / `## H2`), code-block boundaries, and inlines a heading breadcrumb so SFT loss sees document context.
-3. [x] **Code / secrets leakage tagger** — New `secrets_summary` block in audit JSON (AWS / GitHub / Slack / OpenAI / Google / JWT / OpenSSH / PGP / Azure storage). Ingest gains `--secrets-mask` (mask order: secrets → PII so combined detectors don't double-count). `[ingestion-secrets]` extra (`detect-secrets`); regex-only fallback when missing.
-4. [x] **Heuristic quality filter** — Opt-in `--quality-filter` adds a `quality_summary` block with Gopher / C4 / RefinedWeb-style heuristics (mean-word-length, alphabetic ratio, end-of-line punctuation, short-paragraph ratio). ML classifiers stay deferred to Phase 13+.
-5. [x] **DOCX / Markdown table preservation** — `_extract_docx` emits markdown table syntax (header + separator + body rows) instead of the previous `" | "` flat join; uneven rows padded; all-blank rows trimmed; the new markdown chunker keeps these blocks intact across chunks.
+1. [x] **Presidio adapter (item #1)** — `forgelm audit --pii-ml [--pii-ml-language LANG]` layers Presidio NER on top of the regex detector via the optional `[ingestion-pii-ml]` extra. Adds `person` / `organization` / `location` categories. Pre-flight check covers BOTH the missing-extra branch AND the missing-spaCy-model branch (`presidio-analyzer` does NOT transitively ship `en_core_web_lg`; the install recipe is two lines, raised as `ImportError` before any rows are scanned).
+2. [x] **Croissant 1.0 metadata (item #2)** — `forgelm audit --croissant` populates a new `croissant` key in `data_audit_report.json` with a Google Croissant 1.0 dataset card. Card carries `cr:FileObject` per JSONL split, `cr:RecordSet` per split with `cr:Field` entries from column detection. Conformant with `mlcommons.org/croissant/1.0`.
+3. [x] **`forgelm ingest --all-mask` (item #3)** — one-flag shorthand for `--secrets-mask --pii-mask` in the documented order. Set-union with explicit flags.
+4. [x] **Wizard "audit first" (item #4)** — when the wizard resolves a JSONL (typed or produced by ingest), it offers to run `forgelm audit` inline and prints the verdict. Closes the BYOD audit loop.
 
-### Tier 2/3 (deferred to [Phase 12.5 backlog](phase-12-5-backlog.md)):
+### Hardening follow-up (tracked outside this release)
 
-- Presidio adapter (`--pii-engine presidio` + `[ingestion-pii-ml]` extra).
-- Croissant metadata compatibility (audit JSON `--croissant` flag).
-- `forgelm ingest --all-mask` composite flag.
-- Wizard "audit first" entry point (mirrors Phase 11.5's ingest-first hook).
+- [#14 — webhook SSRF DNS-rebinding TOCTOU](https://github.com/cemililik/ForgeLM/issues/14): defence-in-depth on top of the existing `allow_private_destinations: false` default. Slated for `v0.5.1`.
 
 ---
 
-## v0.5.3 — "Pipeline Chains" (Planned)
+## v0.5.1 — "Pipeline Chains" (Planned)
 
-**Status:** Planned. Focus: [Phase 14](phase-14-pipeline-chains.md). Multi-stage SFT → DPO → GRPO chained config, pipeline provenance artifacts for EU AI Act Annex IV compliance. Reslotted from `v0.5.2` so the ingestion / audit lineage finishes uninterrupted; no hard blockers, starts after the `v0.5.2` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) (defence-in-depth on top of the existing `allow_private_destinations: false` default).
+**Status:** Planned. Focus: [Phase 14](phase-14-pipeline-chains.md). Multi-stage SFT → DPO → GRPO chained config, pipeline provenance artifacts for EU AI Act Annex IV compliance. Starts after the `v0.5.0` PyPI tag is published. Folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) (defence-in-depth on top of the existing `allow_private_destinations: false` default).
 
 ---
 
diff --git a/forgelm/cli.py b/forgelm/cli.py
index 7ceeba7a..ffd76115 100644
--- a/forgelm/cli.py
+++ b/forgelm/cli.py
@@ -1479,10 +1479,10 @@ def _run_data_audit(
             "pii_severity": report.pii_severity,
             "secrets_summary": report.secrets_summary,
             "quality_summary": report.quality_summary,
-            # Pre-Phase-12 envelope key — kept verbatim so v0.5.1 consumers
-            # (e.g. ``jq '.near_duplicate_pairs_per_split.train'``) keep working.
-            # The richer ``near_duplicate_summary`` below carries the same
-            # data plus method/threshold metadata.
+            # Pre-Phase-12 envelope key — kept verbatim so any pre-Phase-12
+            # JSON consumer (e.g. ``jq '.near_duplicate_pairs_per_split.train'``)
+            # keeps working. The richer ``near_duplicate_summary`` below
+            # carries the same data plus method/threshold metadata.
             "near_duplicate_pairs_per_split": report.near_duplicate_summary.get("pairs_per_split", {}),
             "near_duplicate_summary": report.near_duplicate_summary,
             "cross_split_leakage_pairs": list((report.cross_split_overlap.get("pairs") or {}).keys()),
diff --git a/notebooks/data_curation.ipynb b/notebooks/data_curation.ipynb
index 14a92109..aa947646 100644
--- a/notebooks/data_curation.ipynb
+++ b/notebooks/data_curation.ipynb
@@ -21,13 +21,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# Step 1: Install ForgeLM with the ingestion extra (PDF/DOCX/EPUB/Markdown parsers + langdetect)\n",
-    "# Pinned to v0.5.2 — the release that introduced the markdown splitter,\n",
-    "# secrets tagger, MinHash dedup option, and quality filter exercised below.\n",
-    "!pip install -q --no-cache-dir 'forgelm[ingestion]==0.5.2'\n",
-    "!forgelm --version"
-   ]
+   "source": "# Step 1: Install ForgeLM with the ingestion extra (PDF/DOCX/EPUB/Markdown parsers + langdetect)\n# Pinned to v0.5.0 — the consolidated release that bundles Phases 11+11.5+12+12.5\n# (markdown splitter, secrets tagger, MinHash dedup option, quality filter,\n# Croissant card, optional Presidio adapter, --all-mask shorthand).\n!pip install -q --no-cache-dir 'forgelm[ingestion]==0.5.0'\n!forgelm --version"
   },
   {
    "cell_type": "markdown",
@@ -126,7 +120,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "## 2. Ingest with the markdown-aware splitter (Phase 12)\n\n`--strategy markdown` is the right choice when your corpus is structured\nwith headings: it splits at heading boundaries, keeps fenced code blocks\natomic, and **inlines the heading breadcrumb** at the top of every chunk\nso SFT loss sees the document context. Falls back to paragraph mode for\nnon-markdown inputs (`.txt` here).\n\nWe also pass `--secrets-mask` and `--pii-mask` (Phase 12) — secrets run\n**before** PII masking so combined detectors don't double-count\noverlapping spans.\n\n> **Phase 12.5 shorthand (`v0.5.3`):** `--all-mask` is equivalent to\n> `--secrets-mask --pii-mask`. Use it when you want the\n> \"scrub-everything-detectable\" workflow without remembering both\n> flags. Composes additively with explicit flags (set-union)."
+   "source": "## 2. Ingest with the markdown-aware splitter\n\n`--strategy markdown` is the right choice when your corpus is structured\nwith headings: it splits at heading boundaries, keeps fenced code blocks\natomic, and **inlines the heading breadcrumb** at the top of every chunk\nso SFT loss sees the document context. Falls back to paragraph mode for\nnon-markdown inputs (`.txt` here).\n\nWe also pass `--secrets-mask` and `--pii-mask` — secrets run **before**\nPII masking so combined detectors don't double-count overlapping spans.\n\n> **Shorthand:** `--all-mask` is equivalent to `--secrets-mask\n> --pii-mask`. Use it when you want the\n> \"scrub-everything-detectable\" workflow without remembering both\n> flags. Composes additively with explicit flags (set-union)."
   },
   {
    "cell_type": "code",
@@ -337,17 +331,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# Install the optional [ingestion-scale] extra so the install hint baked\n",
-    "# into ``forgelm.data_audit._require_datasketch`` matches the recipe used\n",
-    "# here. This pulls ``datasketch>=1.6.0,<2.0.0`` along with any future\n",
-    "# scale-tier deps the extra absorbs.\n",
-    "!pip install -q 'forgelm[ingestion-scale]==0.5.2'\n",
-    "!forgelm audit ./curated/policies.jsonl \\\n",
-    "    --output ./audit_minhash/ \\\n",
-    "    --dedup-method minhash \\\n",
-    "    --jaccard-threshold 0.85"
-   ]
+   "source": "# Install the optional [ingestion-scale] extra so the install hint baked\n# into ``forgelm.data_audit._require_datasketch`` matches the recipe used\n# here. This pulls ``datasketch>=1.6.0,<2.0.0`` along with any future\n# scale-tier deps the extra absorbs.\n!pip install -q 'forgelm[ingestion-scale]==0.5.0'\n!forgelm audit ./curated/policies.jsonl \\\n    --output ./audit_minhash/ \\\n    --dedup-method minhash \\\n    --jaccard-threshold 0.85"
   },
   {
    "cell_type": "code",
@@ -399,7 +383,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "## What's next\n\n- **Train on the curated JSONL**: point any of the training notebooks at\n  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n    set with public datasets\n- **Long-form guides**:\n  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n    — every flag, every chunking strategy, every extra\n  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n    — audit JSON schema, severity tiers, governance integration\n- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n  when you point it at a directory of raw docs (Phase 11.5+), and as of\n  Phase 12.5 it also offers to run `forgelm audit` automatically once a\n  JSONL is selected — closes the BYOD audit loop end-to-end.\n- **Phase 12.5 audit add-ons (v0.5.3)**:\n  - `--croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/)\n    dataset card under the report's `croissant` key so the same JSON\n    file doubles as both the EU AI Act Article 10 governance artifact\n    and a Croissant-consumer dataset card.\n  - `--pii-ml [--pii-ml-language LANG]` layers\n    [Presidio](https://github.com/microsoft/presidio) NER on top of\n    the regex detector — adds `person` / `organization` /\n    `location` categories to `pii_summary` / `pii_severity`. **Two-step\n    install:**\n    ```bash\n    pip install 'forgelm[ingestion-pii-ml]'\n    python -m spacy download en_core_web_lg\n    ```\n    `presidio-analyzer` does not transitively ship a spaCy NER model;\n    without the model `--pii-ml` raises an `ImportError` with the\n    install recipe **before** any rows are scanned. Pass\n    `--pii-ml-language tr` (and download the matching spaCy model) to\n    audit Turkish corpora."
+   "source": "## What's next\n\n- **Train on the curated JSONL**: point any of the training notebooks at\n  `./curated/policies.jsonl` via `data.dataset_name_or_path`.\n  - [`quickstart_sft.ipynb`](./quickstart_sft.ipynb) — first SFT run\n  - [`multi_dataset.ipynb`](./multi_dataset.ipynb) — mix the curated\n    set with public datasets\n- **Long-form guides**:\n  - [`docs/guides/ingestion.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/ingestion.md)\n    — every flag, every chunking strategy, every extra\n  - [`docs/guides/data_audit.md`](https://github.com/cemililik/ForgeLM/blob/main/docs/guides/data_audit.md)\n    — audit JSON schema, severity tiers, governance integration\n- **Wizard**: `forgelm --wizard` offers to run `forgelm ingest` inline\n  when you point it at a directory of raw docs, and offers to run\n  `forgelm audit` automatically once a JSONL is selected — closes the\n  BYOD audit loop end-to-end.\n- **Other v0.5.0 audit add-ons**:\n  - `--croissant` emits a [Google Croissant 1.0](http://mlcommons.org/croissant/)\n    dataset card under the report's `croissant` key so the same JSON\n    file doubles as both the EU AI Act Article 10 governance artifact\n    and a Croissant-consumer dataset card.\n  - `--pii-ml [--pii-ml-language LANG]` layers\n    [Presidio](https://github.com/microsoft/presidio) NER on top of\n    the regex detector — adds `person` / `organization` /\n    `location` categories to `pii_summary` / `pii_severity`. **Two-step\n    install:**\n    ```bash\n    pip install 'forgelm[ingestion-pii-ml]'\n    python -m spacy download en_core_web_lg\n    ```\n    `presidio-analyzer` does not transitively ship a spaCy NER model;\n    without the model `--pii-ml` raises an `ImportError` with the\n    install recipe **before** any rows are scanned. Pass\n    `--pii-ml-language tr` (and download the matching spaCy model) to\n    audit Turkish corpora."
   }
  ],
  "metadata": {
diff --git a/pyproject.toml b/pyproject.toml
index ca97fa0b..da84b133 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "forgelm"
-version = "0.5.2rc1"
+version = "0.5.0"
 description = "Config-driven LLM fine-tuning with safety evaluation, EU AI Act compliance, 6 alignment methods, and one-command bundled quickstart templates."
 readme = "README.md"
 requires-python = ">=3.10"

From 7d0f150911f383240a99030ceb7bf08f55bd24f2 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 19:15:09 +0300
Subject: [PATCH 04/12] docs(0.5.0): site + user manuals reflect Phase 12.5 +
 v0.5.0 release
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Site: hero badge v0.5.2 → v0.5.0 across 6 locales + index fallback;
  quickstart shows --all-mask shorthand; compliance Article 10 card
  mentions Presidio ML-NER + Croissant 1.0 in all 6 translations.
- _meta.yaml: register all-mask, pii-ml, croissant-card under data/
  with titles in all 6 supported locales.
- New EN + TR pages (3 each): all-mask shorthand semantics, Presidio
  ML-NER opt-in adapter (two-step install + severity tiers + pre-flight
  rationale), Croissant 1.0 dataset card emission.
- Cross-link sweep: ingestion + audit + pii-masking pages updated to
  reference the three new pages on both EN and TR sides.

Localization: only EN + TR carry authored content; de/fr/es/zh fall
back to EN via the build script (56 pages each, build clean).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/usermanuals/_meta.yaml                |  24 ++++
 docs/usermanuals/en/data/all-mask.md       |  78 ++++++++++++
 docs/usermanuals/en/data/audit.md          |   3 +
 docs/usermanuals/en/data/croissant-card.md | 132 +++++++++++++++++++
 docs/usermanuals/en/data/ingestion.md      |   6 +-
 docs/usermanuals/en/data/pii-masking.md    |   2 +
 docs/usermanuals/en/data/pii-ml.md         | 140 +++++++++++++++++++++
 docs/usermanuals/tr/data/all-mask.md       |  78 ++++++++++++
 docs/usermanuals/tr/data/audit.md          |   3 +
 docs/usermanuals/tr/data/croissant-card.md | 132 +++++++++++++++++++
 docs/usermanuals/tr/data/ingestion.md      |   6 +-
 docs/usermanuals/tr/data/pii-masking.md    |   2 +
 docs/usermanuals/tr/data/pii-ml.md         | 140 +++++++++++++++++++++
 site/compliance.html                       |   2 +-
 site/index.html                            |   2 +-
 site/js/translations.js                    |  24 ++--
 site/quickstart.html                       |   9 +-
 17 files changed, 764 insertions(+), 19 deletions(-)
 create mode 100644 docs/usermanuals/en/data/all-mask.md
 create mode 100644 docs/usermanuals/en/data/croissant-card.md
 create mode 100644 docs/usermanuals/en/data/pii-ml.md
 create mode 100644 docs/usermanuals/tr/data/all-mask.md
 create mode 100644 docs/usermanuals/tr/data/croissant-card.md
 create mode 100644 docs/usermanuals/tr/data/pii-ml.md

diff --git a/docs/usermanuals/_meta.yaml b/docs/usermanuals/_meta.yaml
index e47445ba..64f2a4ce 100644
--- a/docs/usermanuals/_meta.yaml
+++ b/docs/usermanuals/_meta.yaml
@@ -185,6 +185,30 @@ sections:
           fr: Nettoyage des secrets
           es: Limpieza de secretos
           zh: Secrets 清洗
+      - id: all-mask
+        title:
+          en: Combined Masking (--all-mask)
+          tr: Birleşik Maskeleme (--all-mask)
+          de: Kombinierte Maskierung (--all-mask)
+          fr: Masquage combiné (--all-mask)
+          es: Enmascaramiento combinado (--all-mask)
+          zh: 组合遮罩 (--all-mask)
+      - id: pii-ml
+        title:
+          en: ML-NER PII (Presidio)
+          tr: ML-NER PII (Presidio)
+          de: ML-NER-PII (Presidio)
+          fr: PII ML-NER (Presidio)
+          es: PII ML-NER (Presidio)
+          zh: ML-NER PII (Presidio)
+      - id: croissant-card
+        title:
+          en: Croissant 1.0 Dataset Card
+          tr: Croissant 1.0 Dataset Kartı
+          de: Croissant-1.0-Datensatzkarte
+          fr: Carte de jeu de données Croissant 1.0
+          es: Tarjeta de dataset Croissant 1.0
+          zh: Croissant 1.0 数据集卡片
       - id: deduplication
         title:
           en: Deduplication
diff --git a/docs/usermanuals/en/data/all-mask.md b/docs/usermanuals/en/data/all-mask.md
new file mode 100644
index 00000000..4c75df11
--- /dev/null
+++ b/docs/usermanuals/en/data/all-mask.md
@@ -0,0 +1,78 @@
+---
+title: Combined Masking (--all-mask)
+description: One-flag shorthand for combined PII + secrets scrubbing on ingest.
+---
+
+# Combined Masking — `--all-mask`
+
+`--all-mask` is a CLI shorthand that runs both [Secrets Scrubbing](#/data/secrets) and [PII Masking](#/data/pii-masking) on the same ingest pass, in the documented order (secrets first, PII second). It exists purely as ergonomics — no new detector, no new behaviour.
+
+## Why it exists
+
+The "scrub everything detectable before training on shared corpora" workflow is common enough that operators were typing both flags together every time:
+
+```shell
+$ forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/clean.jsonl
+```
+
+`--all-mask` collapses that to one flag:
+
+```shell
+$ forgelm ingest ./mixed_corpus/ --all-mask --output data/clean.jsonl
+```
+
+The two forms produce byte-identical output. The shorthand is purely UX.
+
+## How it composes
+
+`--all-mask` is **additive** with the explicit flags. All three of these run the same two detectors:
+
+```shell
+$ forgelm ingest ./input/ --all-mask                    --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --pii-mask         --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --secrets-mask     --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --pii-mask --secrets-mask --output out.jsonl
+```
+
+This is a deliberate design choice — set-union semantics mean a future script that always passes `--pii-mask` (because it's an old habit) won't break when `--all-mask` enters the mix. There's no error, no conflict; both flags just stay True.
+
+## Mask order
+
+When both subsystems run, **secrets are masked first**, then PII. This ordering matters because:
+
+1. Some credential shapes (e.g. JWTs) overlap with email-like substrings; running secrets first prevents the email regex from chewing into the middle of a JWT.
+2. The `[REDACTED-SECRET]` placeholder is structurally different from `[REDACTED]`, so a downstream auditor can still tell which kind of span was rewritten.
+
+The order is internal to the ingest pipeline; you don't have to think about it when using `--all-mask`.
+
+## What lands in the JSONL
+
+Both detectors share the same JSONL after the pass — secrets become `[REDACTED-SECRET]`, PII becomes `[REDACTED]`:
+
+```text
+Before: "Reach me at alice@example.com or use AKIAIOSFODNN7EXAMPLE."
+After:  "Reach me at [REDACTED] or use [REDACTED-SECRET]."
+```
+
+## When NOT to use `--all-mask`
+
+- **You want only one of the two.** Pass the explicit flag instead.
+- **You want a different mask token.** The two detectors carry their own placeholders; if you need a different scheme, mask programmatically via `forgelm.data_audit.mask_pii` / `mask_secrets`.
+- **You're auditing without modifying.** Use [`forgelm audit`](#/data/audit) instead — it scans the same patterns but reports counts without rewriting.
+
+## Common pitfalls
+
+:::warn
+**`--all-mask` is not a compliance certification.** It's a defence-in-depth measure. For high-stakes corpora (legal, medical), pair it with manual review and the audit step.
+:::
+
+:::tip
+For corpora that legitimately contain credentials (security training, CTF data) or PII (anonymisation research), don't reach for `--all-mask`. Document the exception in your dataset card and skip ingest masking entirely.
+:::
+
+## See also
+
+- [PII Masking](#/data/pii-masking) — the underlying personal-data detector.
+- [Secrets Scrubbing](#/data/secrets) — the underlying credentials detector.
+- [Document Ingestion](#/data/ingestion) — where `--all-mask` is invoked.
+- [Dataset Audit](#/data/audit) — the audit-only counterpart that detects without rewriting.
diff --git a/docs/usermanuals/en/data/audit.md b/docs/usermanuals/en/data/audit.md
index 026a89c1..76011a3f 100644
--- a/docs/usermanuals/en/data/audit.md
+++ b/docs/usermanuals/en/data/audit.md
@@ -98,6 +98,9 @@ For **binary** (KTO) datasets:
 | `--dedup-threshold N` | Hamming distance threshold for simhash (default 3). |
 | `--skip-pii / --skip-secrets / ...` | Selectively disable individual checks. |
 | `--sample-rate FLOAT` | Audit a random subsample (e.g. `0.1` for 10%). For very large datasets. |
+| `--quality-filter` | Run heuristic quality checks (Gopher / C4 / RefinedWeb-style). Adds `quality_summary`. See [Quality Filter](#/data/quality-filter). |
+| `--pii-ml [--pii-ml-language LANG]` | Layer Presidio NER on top of the regex PII detector — adds `person` / `organization` / `location` categories into the same `pii_summary` block. Requires the `[ingestion-pii-ml]` extra **and** a spaCy NER model. See [ML-NER PII (Presidio)](#/data/pii-ml). |
+| `--croissant` | Emit a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card under the report's `croissant` key — same JSON file doubles as both the audit and a Croissant-consumer card. See [Croissant 1.0 Dataset Card](#/data/croissant-card). |
 
 ## What's in the report
 
diff --git a/docs/usermanuals/en/data/croissant-card.md b/docs/usermanuals/en/data/croissant-card.md
new file mode 100644
index 00000000..0da898b1
--- /dev/null
+++ b/docs/usermanuals/en/data/croissant-card.md
@@ -0,0 +1,132 @@
+---
+title: Croissant 1.0 Dataset Card
+description: Optional Google Croissant 1.0 metadata emitted alongside the audit report — turns the same JSON file into both an EU AI Act Article 10 artifact and a Croissant-consumer dataset card.
+---
+
+# Croissant 1.0 Dataset Card — `--croissant`
+
+The audit report (`data_audit_report.json`) already carries every signal an EU AI Act Article 10 reviewer needs: PII counts, secrets summary, near-duplicate pairs, cross-split leakage, language distribution. With `--croissant`, the same file picks up a top-level `croissant` block that conforms to the [Google Croissant 1.0](http://mlcommons.org/croissant/) specification. One file, two consumers.
+
+## Why bother?
+
+Croissant is the emerging standard for ML dataset cards (Hugging Face dataset pages, MLCommons reference loaders, the Croissant validator all consume it). Emitting a card alongside the audit means:
+
+- The dataset can be published to HuggingFace / MLCommons with the metadata block already in place.
+- A Croissant-aware loader can locate the underlying JSONL splits directly from the card.
+- Compliance reviewers and data scientists read the same source of truth.
+
+When `--croissant` is off, the `croissant` key in the audit report is an empty dict (`{}`). Existing audit consumers that ignore unknown keys see no behavioural change.
+
+## Quick example
+
+```shell
+$ forgelm audit data/policies/ --output ./audit/ --croissant
+✓ format: instructions (12,400 rows, 3 splits)
+✓ croissant card emitted
+   distribution: 3 file objects (train.jsonl, validation.jsonl, test.jsonl)
+   record sets: 3
+```
+
+The card lands under the `croissant` key:
+
+```json
+{
+  "croissant": {
+    "@context": { "@vocab": "https://schema.org/", "sc": "https://schema.org/", "cr": "http://mlcommons.org/croissant/", ... },
+    "@type": "sc:Dataset",
+    "conformsTo": "http://mlcommons.org/croissant/1.0",
+    "name": "policies",
+    "description": "ForgeLM audit-generated dataset card. 12400 sample(s) across 3 split(s). ...",
+    "url": "data/policies/",
+    "datePublished": "2026-04-29T...",
+    "distribution": [
+      { "@type": "cr:FileObject", "@id": "train.jsonl",      "name": "train.jsonl",      "contentUrl": "train.jsonl",      "encodingFormat": "application/jsonlines", "description": "..." },
+      { "@type": "cr:FileObject", "@id": "validation.jsonl", "name": "validation.jsonl", "contentUrl": "validation.jsonl", "encodingFormat": "application/jsonlines", "description": "..." },
+      { "@type": "cr:FileObject", "@id": "test.jsonl",       "name": "test.jsonl",       "contentUrl": "test.jsonl",       "encodingFormat": "application/jsonlines", "description": "..." }
+    ],
+    "recordSet": [
+      { "@type": "cr:RecordSet", "@id": "train",      "name": "train",      "field": [...] },
+      { "@type": "cr:RecordSet", "@id": "validation", "name": "validation", "field": [...] },
+      { "@type": "cr:RecordSet", "@id": "test",       "name": "test",       "field": [...] }
+    ]
+  }
+}
+```
+
+## What the card carries
+
+| Field | Source |
+|---|---|
+| `@context` | Canonical Croissant 1.0 context block (vocabulary). |
+| `@type` | `sc:Dataset` — required for Croissant validators. |
+| `conformsTo` | `http://mlcommons.org/croissant/1.0` — vocab declaration. |
+| `name` | Derived from the source path (file stem or directory name). |
+| `description` | Auto-generated summary of sample count + split count. |
+| `url` | The as-typed input path (HF Hub ID, relative path, etc.) — not the resolved absolute filesystem path, so cards published to HuggingFace / MLCommons don't leak the auditor's local layout. |
+| `datePublished` | ISO 8601 timestamp of the audit run. |
+| `distribution` | One `cr:FileObject` per JSONL split. `contentUrl` is the relative file_id (same anti-leakage rationale as `url`). |
+| `recordSet` | One `cr:RecordSet` per split with `cr:Field` entries derived from the audit's column-detection layer. |
+
+## What's deliberately NOT emitted
+
+The audit doesn't have first-class evidence for these Croissant fields, so they're omitted rather than guessed:
+
+- `version` (`sc:version`) — the dataset version. Operators that publish hand-edit this at publish time the same way they hand-edit other publish-only fields.
+- `license` — same; the audit can't infer the licence of an arbitrary corpus.
+- `citeAs` — citation string; up to the publisher.
+- `creator` / `keywords` — depend on publish context.
+
+If you want these fields populated, edit the JSON post-audit before publishing. They don't change the audit's compliance role.
+
+## Conformance
+
+The emitted card is conformant against the canonical [Croissant 1.0 spec](http://mlcommons.org/croissant/1.0). It's been validated against:
+
+- The [Croissant validator](https://github.com/mlcommons/croissant) (`mlcroissant validate`).
+- HuggingFace's dataset card parser (the `datasets` library reads Croissant if present in the dataset directory).
+
+Validation runs on minimum-viable subset; if your tooling expects optional fields not in this list, hand-edit before publish.
+
+## When to use
+
+- **Publishing the dataset.** The card lives in the same JSON file as the audit, so the publish step is a single artefact.
+- **Cross-team handoff.** Data engineers and ML engineers can both consume one file.
+- **Compliance bundles.** EU AI Act Article 10 governance bundles can include the Croissant card as the dataset-identity layer.
+
+## When NOT to use
+
+- **Internal-only audits** that never leave the team's bucket. The card is harmless but you don't need it.
+- **Datasets with non-standard file layouts** (unsupervised clustering of unrelated `.jsonl` files in one directory). Croissant assumes the splits-per-file convention; for arbitrary layouts, hand-write the card.
+
+## Programmatic API
+
+The card is built by `forgelm.data_audit._build_croissant_metadata` (private helper) and is populated on `AuditReport.croissant` when `audit_dataset(emit_croissant=True)` is called:
+
+```python
+from forgelm.data_audit import audit_dataset
+
+report = audit_dataset(
+    "data/policies/",
+    output_dir="./audit/",
+    emit_croissant=True,
+)
+print(report.croissant["@type"])           # "sc:Dataset"
+print(report.croissant["conformsTo"])      # "http://mlcommons.org/croissant/1.0"
+print(len(report.croissant["distribution"]))  # 3 (one per JSONL split)
+```
+
+## Common pitfalls
+
+:::warn
+**Editing the card and then re-running the audit.** Re-running `forgelm audit` overwrites the file. Either edit *after* the final audit, or feed the edited card forward via your own publish-step script.
+:::
+
+:::tip
+For Hugging Face publishing, save the card as `croissant.json` in the dataset repo (HF expects it there). A simple `jq '.croissant' data_audit_report.json > croissant.json` does the trick.
+:::
+
+## See also
+
+- [Dataset Audit](#/data/audit) — where `--croissant` is invoked.
+- [Annex IV](#/compliance/annex-iv) — the EU AI Act Article 11 artefact that the audit feeds into.
+- [GDPR / KVKK](#/compliance/gdpr) — broader regulatory context.
diff --git a/docs/usermanuals/en/data/ingestion.md b/docs/usermanuals/en/data/ingestion.md
index 50b6ca57..02aeb917 100644
--- a/docs/usermanuals/en/data/ingestion.md
+++ b/docs/usermanuals/en/data/ingestion.md
@@ -27,7 +27,7 @@ $ forgelm ingest ./policies/ \
     --recursive \
     --strategy markdown \
     --max-tokens 1024 \
-    --pii-mask --secrets-mask \
+    --all-mask \
     --output data/policies.jsonl
 ✓ scanned 47 files (12 PDF, 8 DOCX, 27 MD)
 ✓ extracted 12,240 chunks (avg 743 tokens)
@@ -35,6 +35,10 @@ $ forgelm ingest ./policies/ \
 ✓ wrote data/policies.jsonl (8.2 MB)
 ```
 
+`--all-mask` is the documented shorthand for `--secrets-mask --pii-mask`
+in the right order. See [Combined Masking](#/data/all-mask) for the
+full behaviour and set-union semantics.
+
 ## Supported formats
 
 | Format | Extractor | Notes |
diff --git a/docs/usermanuals/en/data/pii-masking.md b/docs/usermanuals/en/data/pii-masking.md
index a9c81e1d..945650ba 100644
--- a/docs/usermanuals/en/data/pii-masking.md
+++ b/docs/usermanuals/en/data/pii-masking.md
@@ -135,5 +135,7 @@ print(masked)
 ## See also
 
 - [Dataset Audit](#/data/audit) — runs PII detection without modifying data.
+- [ML-NER PII (Presidio)](#/data/pii-ml) — optional opt-in layer for unstructured identifiers (person / organization / location) that the regex layer can't catch.
+- [Combined Masking](#/data/all-mask) — `--all-mask` shorthand for running PII + secrets masking in the right order.
 - [Secrets Scrubbing](#/data/secrets) — sister feature for credentials.
 - [GDPR / KVKK](#/compliance/gdpr) — regulatory context.
diff --git a/docs/usermanuals/en/data/pii-ml.md b/docs/usermanuals/en/data/pii-ml.md
new file mode 100644
index 00000000..ee343d90
--- /dev/null
+++ b/docs/usermanuals/en/data/pii-ml.md
@@ -0,0 +1,140 @@
+---
+title: ML-NER PII (Presidio)
+description: Optional Microsoft Presidio adapter that adds person / organization / location detection on top of the regex PII layer.
+---
+
+# ML-NER PII Detection — `--pii-ml`
+
+The default [PII Masking](#/data/pii-masking) layer is regex-anchored and covers the *structured* identifiers GDPR Article 10 cares about (email, phone, IBAN, credit card, national IDs). Presidio NER adds the *unstructured* identifiers regex inherently misses: person names, organisation names, geographic locations.
+
+This is an **opt-in** layer. The default audit + ingest behaviour is unchanged when `--pii-ml` is not passed.
+
+## When to use it
+
+Reach for `--pii-ml` when:
+
+- The corpus is free-form prose (interviews, customer letters, internal communication) where names aren't formatted as structured fields.
+- Your compliance reviewer specifically asks about person/org/location coverage in addition to identifiers.
+- You're auditing a multilingual corpus (Presidio supports localisation; see [Language Selection](#language-selection) below).
+
+Don't reach for it when:
+
+- The corpus is already heavily structured (CSV-shaped JSON, API logs); the regex layer's recall is already where you want it.
+- You're running on a tight CPU budget — Presidio is materially slower than regex (NER forward pass per row).
+- You're operating in an air-gapped environment without a pre-staged spaCy NER model — see [Air-Gap Operation](#/operations/air-gap).
+
+## Two-step install
+
+`presidio-analyzer` does **not** transitively ship a spaCy NER model. The install is two lines:
+
+```shell
+$ pip install 'forgelm[ingestion-pii-ml]'
+$ python -m spacy download en_core_web_lg
+```
+
+Without the spaCy model, `forgelm audit --pii-ml` raises a typed `ImportError` **before any rows are scanned** — pre-flight checking is a deliberate design choice (see [Why pre-flight matters](#why-pre-flight-matters)).
+
+## Quick example
+
+```shell
+$ forgelm audit data/customer-letters.jsonl --output ./audit/ --pii-ml
+✓ format: instructions (8,400 rows)
+⚠ PII: 12 emails, 3 phone, 1 IBAN (regex layer)
+⚠ PII (ML): 47 person, 18 organization, 9 location (Presidio)
+   worst tier: medium
+```
+
+The Presidio findings merge into the same `pii_summary` and `pii_severity` blocks under disjoint category names, so the regex baseline stays visible alongside the ML signal:
+
+```json
+{
+  "pii_summary": {
+    "email": 12,
+    "phone": 3,
+    "person": 47,
+    "organization": 18,
+    "location": 9
+  },
+  "pii_severity": {
+    "by_tier": {"critical": 0, "high": 0, "medium": 59, "low": 30},
+    "worst_tier": "medium"
+  }
+}
+```
+
+## Severity tiers
+
+The new categories sit under a dedicated table in `forgelm.data_audit.PII_ML_SEVERITY`:
+
+| Category | Tier | Reason |
+|---|---|---|
+| `person` | medium | A name attached to other context can re-identify; alone it's weaker than a national ID. |
+| `organization` | low | Public-record entities; leakage is closer to "this person works at X" than "this is X's home address." |
+| `location` | low | Same logic — geographic strings are usually de-identification-resistant on their own. |
+
+These tiers sit **deliberately below** the regex `critical`/`high` floors (credit cards, national IDs). NER false-positive rates are materially higher than regex-anchored detection, so a "person" finding shouldn't gate a deployment the way a "credit_card" finding does.
+
+## Language selection
+
+Pass `--pii-ml-language` to point at a non-English NLP engine. Presidio raises a typed exception when no engine is registered for the requested language — surfaced loudly so you can install the matching spaCy model:
+
+```shell
+$ python -m spacy download xx_ent_wiki_sm     # multilingual, smaller
+$ forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
+```
+
+Default is `en`. If you run `--pii-ml` on a Turkish-majority corpus without setting the language, Presidio's English NER will return zero or near-zero findings — the audit honestly reports "0 person" but you've effectively run a no-op.
+
+## Why pre-flight matters
+
+`forgelm.data_audit._require_presidio()` checks **both** the import sentinel (extra installed?) **and** the analyzer build (spaCy model present?) before any rows are scanned. Earlier prototypes only checked the import; that produced a particularly bad failure mode:
+
+1. The audit launched, started scanning rows.
+2. The first per-row Presidio call raised `OSError("Can't find model 'en_core_web_lg'")`.
+3. `detect_pii_ml`'s per-row exception handler swallowed the error.
+4. **Every** subsequent row also returned zero ML findings.
+5. The audit finished green with no diagnostic — a critical compliance blind spot for an opt-in detector that operators expected to run.
+
+The current pre-flight closes that gap by surfacing missing-model failures up front with the install recipe.
+
+## Programmatic API
+
+```python
+from forgelm.data_audit import detect_pii_ml, _require_presidio
+
+# Hard pre-flight; raises ImportError with the install recipe if missing.
+_require_presidio()
+
+text = "Alice Williams visits Acme Corp's Berlin office on Monday."
+counts = detect_pii_ml(text, language="en")
+print(counts)
+# {'person': 1, 'organization': 1, 'location': 1}
+```
+
+The function returns an empty dict for non-string input, missing extras, or transient analyzer errors (a single bad row never blocks the audit). Hard failures (missing spaCy model, language not registered) propagate to the caller.
+
+## What's NOT in this layer
+
+- **DATE / TIME / NUMBER detection.** Presidio supports more entity types than the three ForgeLM maps; the others (DATE, NRP, CRYPTO, IP_ADDRESS, …) are not currently mapped because their privacy semantics are different. Open an issue if your compliance flow needs them.
+- **PII *masking* via Presidio.** The current adapter is detection-only — for masking, the regex `--pii-mask` flag still owns ingest-side rewriting. Presidio's anonymizer module is a separate dependency and not wired up in v0.5.0.
+
+## Common pitfalls
+
+:::warn
+**Treating ML-NER as a hard gate.** False-positive rates are materially higher than regex-anchored detection. Use Presidio findings as a *signal* to investigate, not as auto-revert criteria.
+:::
+
+:::warn
+**Running `--pii-ml` on a non-English corpus without `--pii-ml-language`.** The default English NER returns near-zero findings on Turkish, German, Chinese text — and the audit honestly reports zero. Set the language explicitly.
+:::
+
+:::tip
+**Air-gapped deployments:** Pre-stage the spaCy model on the target host (`python -m spacy download en_core_web_lg` from a mirror) and verify with `python -m spacy validate`. The pre-flight check passes once the model is on the import path.
+:::
+
+## See also
+
+- [PII Masking](#/data/pii-masking) — the always-on regex layer.
+- [Dataset Audit](#/data/audit) — where `--pii-ml` is invoked.
+- [GDPR / KVKK](#/compliance/gdpr) — regulatory context.
+- [Air-Gap Operation](#/operations/air-gap) — pre-staging the spaCy model.
diff --git a/docs/usermanuals/tr/data/all-mask.md b/docs/usermanuals/tr/data/all-mask.md
new file mode 100644
index 00000000..b700cc2c
--- /dev/null
+++ b/docs/usermanuals/tr/data/all-mask.md
@@ -0,0 +1,78 @@
+---
+title: Birleşik Maskeleme (--all-mask)
+description: Ingest sırasında PII + secrets temizlemesini birlikte çalıştıran tek-flag kısayolu.
+---
+
+# Birleşik Maskeleme — `--all-mask`
+
+`--all-mask`, [Sırların Temizlenmesi](#/data/secrets) ve [PII Maskeleme](#/data/pii-masking) detector'larını aynı ingest pass'inde belgelenen sırayla (önce secrets, sonra PII) çalıştıran bir CLI kısayoludur. Yeni bir detector, yeni bir davranış getirmez — sadece ergonomi.
+
+## Niye var
+
+"Paylaşılan korpusta eğitime başlamadan tespit edilebilir her şeyi temizle" iş akışı, operatörlerin her seferinde iki flag'i birden yazması yetecek kadar yaygındı:
+
+```shell
+$ forgelm ingest ./mixed_corpus/ --secrets-mask --pii-mask --output data/clean.jsonl
+```
+
+`--all-mask` bunu tek flag'e indirir:
+
+```shell
+$ forgelm ingest ./mixed_corpus/ --all-mask --output data/clean.jsonl
+```
+
+İki form byte-eşdeğer çıktı üretir. Kısayol tamamen UX'tir.
+
+## Nasıl birleşir
+
+`--all-mask`, açık flag'lerle **additive**'tir. Aşağıdaki üç çağrı da aynı iki detector'ı çalıştırır:
+
+```shell
+$ forgelm ingest ./input/ --all-mask                    --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --pii-mask         --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --secrets-mask     --output out.jsonl
+$ forgelm ingest ./input/ --all-mask --pii-mask --secrets-mask --output out.jsonl
+```
+
+Bu bilinçli bir tasarım kararı — set-union semantiği, alışkanlıkla `--pii-mask`'i her zaman geçen eski bir scriptin `--all-mask` eklendiğinde kırılmamasını sağlar. Hata yok, çelişki yok; iki flag de True kalır.
+
+## Mask sırası
+
+İki alt sistem birden çalıştığında **önce secrets** maskelenir, sonra PII. Bu sıra önemli çünkü:
+
+1. Bazı credential şekilleri (örn. JWT'ler) email-benzeri substring'lerle çakışır; secrets'ı önce çalıştırmak email regex'inin bir JWT'nin ortasını yememesini sağlar.
+2. `[REDACTED-SECRET]` placeholder'ı, `[REDACTED]`'ten yapısal olarak farklı — downstream auditor hangi span'in nasıl yeniden yazıldığını ayırt edebilir.
+
+Sıra ingest pipeline'ının iç meselesidir; `--all-mask` kullanırken düşünmeniz gerekmez.
+
+## JSONL'a inen şey
+
+Her iki detector aynı JSONL'ı paylaşır — secrets `[REDACTED-SECRET]` olur, PII `[REDACTED]`:
+
+```text
+Önce: "Bana alice@example.com'dan ulaşın veya AKIAIOSFODNN7EXAMPLE kullanın."
+Sonra: "Bana [REDACTED]'dan ulaşın veya [REDACTED-SECRET] kullanın."
+```
+
+## `--all-mask`'i NE zaman kullanmamalı
+
+- **Yalnızca birini istiyorsan.** Açık flag'i kullan.
+- **Farklı bir mask token'ı istiyorsan.** İki detector kendi placeholder'larını taşır; farklı bir şema lazımsa programatik olarak `forgelm.data_audit.mask_pii` / `mask_secrets` çağır.
+- **Modifiye etmeden audit ediyorsan.** [`forgelm audit`](#/data/audit) kullan — aynı pattern'leri tarar ama yeniden yazmadan sayılarını raporlar.
+
+## Yaygın tuzaklar
+
+:::warn
+**`--all-mask` bir compliance sertifikası değildir.** Defence-in-depth bir önlemdir. Yüksek-riskli korpuslar (hukuk, sağlık) için manuel review ve audit adımıyla eşleştirin.
+:::
+
+:::tip
+Meşru olarak credential içeren (güvenlik eğitimi, CTF verileri) veya PII içeren (anonimleştirme araştırması) korpuslarda `--all-mask`'e uzanmayın. İstisna durumu dataset card'ınıza yazıp ingest maskelemesini tamamen atlayın.
+:::
+
+## Bakınız
+
+- [PII Maskeleme](#/data/pii-masking) — alttaki personal-data detector'ı.
+- [Sırların Temizlenmesi](#/data/secrets) — alttaki credentials detector'ı.
+- [Doküman Ingest'i](#/data/ingestion) — `--all-mask`'in çağrıldığı yer.
+- [Veri Seti Denetimi](#/data/audit) — yeniden yazmadan tespit eden audit-only karşılığı.
diff --git a/docs/usermanuals/tr/data/audit.md b/docs/usermanuals/tr/data/audit.md
index 71e6ea9e..31236b30 100644
--- a/docs/usermanuals/tr/data/audit.md
+++ b/docs/usermanuals/tr/data/audit.md
@@ -98,6 +98,9 @@ Train vs validation vs test satırları arasında kesin ve near-duplicate eşle
 | `--dedup-threshold N` | simhash için Hamming eşiği (varsayılan 3). |
 | `--skip-pii / --skip-secrets / ...` | Tek tek kontrolleri kapat. |
 | `--sample-rate FLOAT` | Rastgele alt-örnek (`0.1` = %10). Çok büyük dataset için. |
+| `--quality-filter` | Heuristik kalite kontrolleri (Gopher / C4 / RefinedWeb stili). `quality_summary` ekler. Bkz. [Kalite Filtresi](#/data/quality-filter). |
+| `--pii-ml [--pii-ml-language LANG]` | Regex PII detector'ın üzerine Presidio NER katmanı ekler — aynı `pii_summary` bloğuna `person` / `organization` / `location` kategorileri ekler. `[ingestion-pii-ml]` extra'sını **ve** bir spaCy NER modelini gerektirir. Bkz. [ML-NER PII (Presidio)](#/data/pii-ml). |
+| `--croissant` | Raporun `croissant` anahtarı altına bir [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card emit eder — aynı JSON dosyası hem audit hem Croissant-tüketicisi card görevi görür. Bkz. [Croissant 1.0 Dataset Kartı](#/data/croissant-card). |
 
 ## Rapor içeriği
 
diff --git a/docs/usermanuals/tr/data/croissant-card.md b/docs/usermanuals/tr/data/croissant-card.md
new file mode 100644
index 00000000..c88671f0
--- /dev/null
+++ b/docs/usermanuals/tr/data/croissant-card.md
@@ -0,0 +1,132 @@
+---
+title: Croissant 1.0 Dataset Kartı
+description: Audit raporunun yanında yayınlanan opsiyonel Google Croissant 1.0 metadata — aynı JSON dosyasını hem EU AI Act Madde 10 artifact'ı hem de Croissant tüketicisi dataset card'ı haline getirir.
+---
+
+# Croissant 1.0 Dataset Kartı — `--croissant`
+
+Audit raporu (`data_audit_report.json`) bir EU AI Act Madde 10 reviewer'ının ihtiyacı olan her sinyali zaten taşır: PII sayıları, secrets özeti, near-duplicate çiftleri, cross-split sızıntı, dil dağılımı. `--croissant` ile aynı dosya, [Google Croissant 1.0](http://mlcommons.org/croissant/) spec'ine uyan top-level bir `croissant` bloğu kazanır. Tek dosya, iki tüketici.
+
+## Niye uğraşalım?
+
+Croissant, ML dataset card'ları için ortaya çıkan standart (Hugging Face dataset sayfaları, MLCommons referans loader'ları, Croissant validator'ı bunu tüketir). Audit'in yanında bir card yayınlamak şu anlama gelir:
+
+- Dataset metadata bloğu önceden hazır halde HuggingFace / MLCommons'a yayınlanabilir.
+- Croissant farkındalıklı bir loader, alttaki JSONL split'lerini doğrudan card'dan bulabilir.
+- Compliance reviewer'ları ve veri bilimciler aynı kaynak gerçeği okur.
+
+`--croissant` kapalıyken audit raporundaki `croissant` anahtarı boş bir dict (`{}`) olur. Bilinmeyen anahtarları ignore eden mevcut audit tüketicileri davranış değişikliği görmez.
+
+## Hızlı örnek
+
+```shell
+$ forgelm audit data/policies/ --output ./audit/ --croissant
+✓ format: instructions (12.400 satır, 3 split)
+✓ croissant card yayınlandı
+   distribution: 3 file object (train.jsonl, validation.jsonl, test.jsonl)
+   record sets: 3
+```
+
+Card `croissant` anahtarının altında oluşur:
+
+```json
+{
+  "croissant": {
+    "@context": { "@vocab": "https://schema.org/", "sc": "https://schema.org/", "cr": "http://mlcommons.org/croissant/", ... },
+    "@type": "sc:Dataset",
+    "conformsTo": "http://mlcommons.org/croissant/1.0",
+    "name": "policies",
+    "description": "ForgeLM audit-generated dataset card. 12400 sample(s) across 3 split(s). ...",
+    "url": "data/policies/",
+    "datePublished": "2026-04-29T...",
+    "distribution": [
+      { "@type": "cr:FileObject", "@id": "train.jsonl",      "name": "train.jsonl",      "contentUrl": "train.jsonl",      "encodingFormat": "application/jsonlines", "description": "..." },
+      { "@type": "cr:FileObject", "@id": "validation.jsonl", "name": "validation.jsonl", "contentUrl": "validation.jsonl", "encodingFormat": "application/jsonlines", "description": "..." },
+      { "@type": "cr:FileObject", "@id": "test.jsonl",       "name": "test.jsonl",       "contentUrl": "test.jsonl",       "encodingFormat": "application/jsonlines", "description": "..." }
+    ],
+    "recordSet": [
+      { "@type": "cr:RecordSet", "@id": "train",      "name": "train",      "field": [...] },
+      { "@type": "cr:RecordSet", "@id": "validation", "name": "validation", "field": [...] },
+      { "@type": "cr:RecordSet", "@id": "test",       "name": "test",       "field": [...] }
+    ]
+  }
+}
+```
+
+## Card neyi taşır
+
+| Alan | Kaynak |
+|---|---|
+| `@context` | Kanonik Croissant 1.0 context bloğu (vocabulary). |
+| `@type` | `sc:Dataset` — Croissant validator'lar için zorunlu. |
+| `conformsTo` | `http://mlcommons.org/croissant/1.0` — vocab declaration. |
+| `name` | Kaynak path'inden türetilir (dosya stem'i veya dizin adı). |
+| `description` | Sample sayısı + split sayısı için otomatik özet. |
+| `url` | As-typed input path'i (HF Hub ID, relative path, vb.) — resolve edilmiş absolute filesystem path değil; HuggingFace / MLCommons'a yayınlanan card'lar auditor'ın yerel layout'unu sızdırmaz. |
+| `datePublished` | Audit çalışmasının ISO 8601 timestamp'i. |
+| `distribution` | Her JSONL split'i için bir `cr:FileObject`. `contentUrl` relative file_id'dir (aynı anti-leakage gerekçesi). |
+| `recordSet` | Her split için audit'in column-detection katmanından türetilen `cr:Field` girdileriyle bir `cr:RecordSet`. |
+
+## Bilinçli olarak EMIT EDİLMEYEN şeyler
+
+Audit'in şu Croissant alanları için birinci sınıf delili yok, bu yüzden tahmin etmek yerine atlanırlar:
+
+- `version` (`sc:version`) — dataset versiyonu. Yayınlayan operatörler diğer publish-only alanları nasıl elle düzenliyorlarsa bunu da publish anında elle düzenler.
+- `license` — aynı; audit keyfi bir korpusun lisansını çıkaramaz.
+- `citeAs` — citation string; publisher'a kalmış.
+- `creator` / `keywords` — publish bağlamına bağlı.
+
+Bu alanların doldurulmasını istiyorsanız, publish öncesi audit-sonrası JSON'u düzenleyin. Audit'in compliance rolünü değiştirmezler.
+
+## Conformance
+
+Yayınlanan card kanonik [Croissant 1.0 spec](http://mlcommons.org/croissant/1.0)'ine uyumludur. Şunlara karşı doğrulanmıştır:
+
+- [Croissant validator](https://github.com/mlcommons/croissant) (`mlcroissant validate`).
+- HuggingFace'in dataset card parser'ı (`datasets` kütüphanesi dataset dizininde varsa Croissant'ı okur).
+
+Doğrulama minimum-viable subset üzerinde çalışır; tooling'iniz bu listede olmayan opsiyonel alanlar bekliyorsa publish öncesi elle düzenleyin.
+
+## Ne zaman kullanılır
+
+- **Dataset'i yayınlarken.** Card audit ile aynı JSON dosyasında yaşar; publish adımı tek bir artefakt olur.
+- **Ekipler arası handoff.** Veri mühendisleri ve ML mühendisleri aynı dosyayı tüketebilir.
+- **Compliance bundle'ları.** EU AI Act Madde 10 governance bundle'ları Croissant card'ını dataset-identity katmanı olarak içerebilir.
+
+## Ne zaman kullanılmaz
+
+- **Ekibin bucket'ından çıkmayan iç audit'ler.** Card zararsızdır ama gerek de yoktur.
+- **Standart-olmayan dosya layout'ları olan dataset'ler** (alakasız `.jsonl` dosyalarının bir dizinde unsupervised cluster'lanması). Croissant splits-per-file conventionunu varsayar; keyfi layout'lar için card'ı elle yazın.
+
+## Programatik API
+
+Card `forgelm.data_audit._build_croissant_metadata` (private helper) tarafından inşa edilir ve `audit_dataset(emit_croissant=True)` çağrıldığında `AuditReport.croissant`'a doldurulur:
+
+```python
+from forgelm.data_audit import audit_dataset
+
+report = audit_dataset(
+    "data/policies/",
+    output_dir="./audit/",
+    emit_croissant=True,
+)
+print(report.croissant["@type"])           # "sc:Dataset"
+print(report.croissant["conformsTo"])      # "http://mlcommons.org/croissant/1.0"
+print(len(report.croissant["distribution"]))  # 3 (her JSONL split başına bir)
+```
+
+## Yaygın tuzaklar
+
+:::warn
+**Card'ı düzenleyip sonra audit'i yeniden çalıştırma.** `forgelm audit`'i yeniden çalıştırmak dosyanın üzerine yazar. Ya son audit *sonrası* düzenleyin ya da düzenlenmiş card'ı kendi publish-step script'inizle ileri besleyin.
+:::
+
+:::tip
+Hugging Face yayını için card'ı dataset repo'sunda `croissant.json` olarak kaydedin (HF orada bekler). Basit bir `jq '.croissant' data_audit_report.json > croissant.json` işi görür.
+:::
+
+## Bakınız
+
+- [Veri Seti Denetimi](#/data/audit) — `--croissant`'ın çağrıldığı yer.
+- [Annex IV](#/compliance/annex-iv) — audit'in beslediği EU AI Act Madde 11 artefaktı.
+- [GDPR / KVKK](#/compliance/gdpr) — daha geniş düzenleyici bağlam.
diff --git a/docs/usermanuals/tr/data/ingestion.md b/docs/usermanuals/tr/data/ingestion.md
index 42139564..cb1dca93 100644
--- a/docs/usermanuals/tr/data/ingestion.md
+++ b/docs/usermanuals/tr/data/ingestion.md
@@ -27,7 +27,7 @@ $ forgelm ingest ./policies/ \
     --recursive \
     --strategy markdown \
     --max-tokens 1024 \
-    --pii-mask --secrets-mask \
+    --all-mask \
     --output data/policies.jsonl
 ✓ 47 dosya tarandı (12 PDF, 8 DOCX, 27 MD)
 ✓ 12,240 chunk çıkarıldı (ortalama 743 token)
@@ -35,6 +35,10 @@ $ forgelm ingest ./policies/ \
 ✓ data/policies.jsonl yazıldı (8.2 MB)
 ```
 
+`--all-mask`, `--secrets-mask --pii-mask`'in doğru sıradaki belgelenen
+kısayoludur. Tam davranış ve set-union semantiği için
+[Birleşik Maskeleme](#/data/all-mask)'ye bakın.
+
 ## Desteklenen formatlar
 
 | Format | Çıkarıcı | Notlar |
diff --git a/docs/usermanuals/tr/data/pii-masking.md b/docs/usermanuals/tr/data/pii-masking.md
index fe1330e1..6e57e3e5 100644
--- a/docs/usermanuals/tr/data/pii-masking.md
+++ b/docs/usermanuals/tr/data/pii-masking.md
@@ -135,5 +135,7 @@ print(masked)
 ## Bkz.
 
 - [Veri Seti Denetimi](#/data/audit) — modifiye etmeden PII tespiti koşturur.
+- [ML-NER PII (Presidio)](#/data/pii-ml) — regex katmanının yakalayamadığı yapılandırılmamış identifier'lar (person / organization / location) için opsiyonel opt-in katman.
+- [Birleşik Maskeleme](#/data/all-mask) — PII + sırlar maskelemesini doğru sırada koşturmak için `--all-mask` kısayolu.
 - [Sırların Temizlenmesi](#/data/secrets) — kimlik bilgileri için kardeş özellik.
 - [GDPR / KVKK](#/compliance/gdpr) — regülatif bağlam.
diff --git a/docs/usermanuals/tr/data/pii-ml.md b/docs/usermanuals/tr/data/pii-ml.md
new file mode 100644
index 00000000..569df51e
--- /dev/null
+++ b/docs/usermanuals/tr/data/pii-ml.md
@@ -0,0 +1,140 @@
+---
+title: ML-NER PII (Presidio)
+description: Regex PII katmanının üzerine person / organization / location tespiti ekleyen, opsiyonel Microsoft Presidio adaptörü.
+---
+
+# ML-NER PII Tespiti — `--pii-ml`
+
+Varsayılan [PII Maskeleme](#/data/pii-masking) katmanı regex-anchored'dır ve GDPR Madde 10'un önemsediği *yapılandırılmış* identifier'ları (email, telefon, IBAN, kredi kartı, ulusal kimlikler) kapsar. Presidio NER, regex'in doğal olarak kaçırdığı *yapılandırılmamış* identifier'ları ekler: kişi isimleri, organizasyon isimleri, coğrafi yerler.
+
+Bu katman **opt-in**'dir. `--pii-ml` geçilmediğinde varsayılan audit + ingest davranışı değişmez.
+
+## Ne zaman kullanılır
+
+`--pii-ml`'e şunlarda uzanın:
+
+- Korpus serbest formlu prose (mülakat, müşteri mektubu, iç iletişim) ve isimler yapılandırılmış alanlarda değil.
+- Compliance reviewer'ınız identifier'lara ek olarak person/org/location kapsamı hakkında soru soruyor.
+- Çok dilli bir korpus audit ediyorsunuz (Presidio yerelleştirmeyi destekler; aşağıdaki [Dil Seçimi](#dil-secimi) bölümüne bakın).
+
+Şunlarda kullanmayın:
+
+- Korpus zaten yoğun yapılandırılmış (CSV-şeklinde JSON, API logları); regex katmanın recall'u zaten istediğiniz yerde.
+- CPU bütçeniz dar — Presidio regex'ten materyal olarak yavaştır (satır başına NER forward pass).
+- Pre-staged spaCy NER modeli olmadan air-gap ortamda çalışıyorsunuz — [Air-Gap Operasyonu](#/operations/air-gap)'na bakın.
+
+## İki adımlı kurulum
+
+`presidio-analyzer` bir spaCy NER modelini transitively içermez. Kurulum iki satır:
+
+```shell
+$ pip install 'forgelm[ingestion-pii-ml]'
+$ python -m spacy download en_core_web_lg
+```
+
+spaCy modeli yoksa `forgelm audit --pii-ml` hiçbir satır taranmadan **önce** typed bir `ImportError` raise eder — pre-flight checking bilinçli bir tasarım kararıdır (bkz. [Pre-flight neden önemli](#pre-flight-neden-onemli)).
+
+## Hızlı örnek
+
+```shell
+$ forgelm audit data/customer-letters.jsonl --output ./audit/ --pii-ml
+✓ format: instructions (8.400 satır)
+⚠ PII: 12 email, 3 telefon, 1 IBAN (regex katmanı)
+⚠ PII (ML): 47 person, 18 organization, 9 location (Presidio)
+   en kötü kat: medium
+```
+
+Presidio bulguları aynı `pii_summary` ve `pii_severity` bloklarına disjoint kategori isimleriyle birleşir, böylece regex baseline ML sinyaliyle yan yana görünür kalır:
+
+```json
+{
+  "pii_summary": {
+    "email": 12,
+    "phone": 3,
+    "person": 47,
+    "organization": 18,
+    "location": 9
+  },
+  "pii_severity": {
+    "by_tier": {"critical": 0, "high": 0, "medium": 59, "low": 30},
+    "worst_tier": "medium"
+  }
+}
+```
+
+## Şiddet katmanları
+
+Yeni kategoriler `forgelm.data_audit.PII_ML_SEVERITY` adında özel bir tabloda yaşar:
+
+| Kategori | Kat | Sebep |
+|---|---|---|
+| `person` | medium | Diğer bağlamla birlikte bir isim re-identify edebilir; tek başına ulusal kimlikten daha zayıf. |
+| `organization` | low | Kamu-kayıtlı varlıklar; sızıntı "bu kişi X'te çalışıyor" düzeyinde, "X'in ev adresi" değil. |
+| `location` | low | Aynı mantık — coğrafi string'ler tek başına genellikle de-identification-resistant'tır. |
+
+Bu katmanlar **bilinçli olarak** regex'in `critical`/`high` zeminlerinin (kredi kartları, ulusal kimlikler) altındadır. NER false-positive oranları regex-anchored detection'dan materyal olarak yüksektir; bu yüzden bir "person" bulgusu bir "credit_card" bulgusunun yaptığı gibi bir deployment'ı gate'lememeli.
+
+## Dil Seçimi {#dil-secimi}
+
+Non-English NLP engine'e işaret etmek için `--pii-ml-language` geçin. Talep edilen dil için bir engine kayıtlı değilse Presidio typed bir exception raise eder — eşleşen spaCy modelini kurabilmeniz için yüksek sesle yüzeye çıkar:
+
+```shell
+$ python -m spacy download xx_ent_wiki_sm     # çok dilli, daha küçük
+$ forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
+```
+
+Varsayılan `en`. Türkçe ağırlıklı bir korpusta `--pii-ml`'i dil ayarlamadan çalıştırırsanız, Presidio'nun İngilizce NER'i sıfır veya sıfıra yakın bulgu döndürür — audit dürüstçe "0 person" raporlar ama efektif olarak no-op çalıştırmış olursunuz.
+
+## Pre-flight neden önemli {#pre-flight-neden-onemli}
+
+`forgelm.data_audit._require_presidio()` **iki şeyi birden** kontrol eder: import sentinel (extra kurulu mu?) **ve** analyzer build (spaCy modeli mevcut mu?). Hiçbir satır taranmadan önce. Önceki prototipler sadece import'u kontrol ediyordu; bu özellikle kötü bir failure mode üretiyordu:
+
+1. Audit başladı, satırları taramaya başladı.
+2. İlk satır başına Presidio çağrısı `OSError("Can't find model 'en_core_web_lg'")` raise etti.
+3. `detect_pii_ml`'in satır başına exception handler'ı hatayı yuttu.
+4. Sonraki **her** satır da sıfır ML bulgusu döndürdü.
+5. Audit hiç diagnostic olmadan yeşil tamamlandı — operatörün çalıştığını sandığı opt-in bir detector için kritik bir compliance kör noktası.
+
+Mevcut pre-flight, eksik-model arızalarını install recipe ile peşinen yüzeye çıkararak bu boşluğu kapatır.
+
+## Programatik API
+
+```python
+from forgelm.data_audit import detect_pii_ml, _require_presidio
+
+# Sert pre-flight; eksikse install recipe ile ImportError raise eder.
+_require_presidio()
+
+text = "Alice Williams Pazartesi Acme Corp'un Berlin ofisini ziyaret ediyor."
+counts = detect_pii_ml(text, language="en")
+print(counts)
+# {'person': 1, 'organization': 1, 'location': 1}
+```
+
+Fonksiyon non-string input, eksik extra'lar veya geçici analyzer hataları için boş dict döndürür (tek bir kötü satır audit'i bloke etmez). Sert arızalar (eksik spaCy modeli, kayıtlı olmayan dil) caller'a propagate olur.
+
+## Bu katmanda OLMAYAN şeyler
+
+- **DATE / TIME / NUMBER tespiti.** Presidio ForgeLM'in haritaladığı üç entity tipinden fazlasını destekler; diğerleri (DATE, NRP, CRYPTO, IP_ADDRESS, …) şu anda haritalı değil çünkü gizlilik semantikleri farklı. Compliance akışınız bunlara ihtiyaç duyuyorsa bir issue açın.
+- **Presidio üzerinden PII *maskeleme*.** Mevcut adaptör tespit-only — maskeleme için regex `--pii-mask` flag'i hâlâ ingest tarafı yeniden yazımına sahiptir. Presidio'nun anonymizer modülü ayrı bir bağımlılıktır ve v0.5.0'da bağlı değildir.
+
+## Yaygın tuzaklar
+
+:::warn
+**ML-NER'i sert bir gate olarak değerlendirme.** False-positive oranları regex-anchored detection'dan materyal olarak yüksek. Presidio bulgularını araştırma için *sinyal* olarak kullanın, auto-revert kriteri olarak değil.
+:::
+
+:::warn
+**`--pii-ml`'i `--pii-ml-language` olmadan non-English korpus üzerinde çalıştırma.** Varsayılan İngilizce NER, Türkçe / Almanca / Çince metinde sıfıra yakın bulgu döndürür — ve audit dürüstçe sıfır raporlar. Dili açıkça ayarlayın.
+:::
+
+:::tip
+**Air-gap deployment'lar:** spaCy modelini hedef hostta ön-stage edin (mirror'dan `python -m spacy download en_core_web_lg`) ve `python -m spacy validate` ile doğrulayın. Model import path'inde olduğunda pre-flight check geçer.
+:::
+
+## Bakınız
+
+- [PII Maskeleme](#/data/pii-masking) — her zaman açık olan regex katmanı.
+- [Veri Seti Denetimi](#/data/audit) — `--pii-ml`'in çağrıldığı yer.
+- [GDPR / KVKK](#/compliance/gdpr) — düzenleyici bağlam.
+- [Air-Gap Operasyonu](#/operations/air-gap) — spaCy modelini ön-stage etme.
diff --git a/site/compliance.html b/site/compliance.html
index 2b310335..cd04a45e 100644
--- a/site/compliance.html
+++ b/site/compliance.html
@@ -91,7 +91,7 @@ <h3 data-i18n="compliance.art9.title">Risk management</h3>
       <article class="article-card">
         <span class="article-num">Article 10</span>
         <h3 data-i18n-html="compliance.art10.title">Data &amp; data governance</h3>
-        <p data-i18n="compliance.art10.body">Quality, relevance, representativeness criteria. Bias detection, PII redaction.</p>
+        <p data-i18n="compliance.art10.body">Quality, relevance, representativeness criteria. Bias detection, PII redaction. Optional <b>Presidio</b> ML-NER for unstructured PII; optional <b>Croissant 1.0</b> dataset card emitted alongside the audit.</p>
         <div class="article-evidence"><b>forgelm/data_audit.py</b> · <b>forgelm/ingestion.py</b></div>
       </article>
 
diff --git a/site/index.html b/site/index.html
index e1ee3544..de510dcc 100644
--- a/site/index.html
+++ b/site/index.html
@@ -84,7 +84,7 @@
     <div>
       <span class="hero-badge">
         <span class="dot"></span>
-        <span data-i18n="home.hero.badge">Open source · Apache 2.0 · v0.5.2</span>
+        <span data-i18n="home.hero.badge">Open source · Apache 2.0 · v0.5.0</span>
       </span>
 
       <h1 data-i18n-html="home.hero.title">YAML in.<br><span class="text-gradient">Fine-tuned model</span> out.</h1>
diff --git a/site/js/translations.js b/site/js/translations.js
index a5c34c1f..370d8c1e 100644
--- a/site/js/translations.js
+++ b/site/js/translations.js
@@ -284,7 +284,7 @@
   Object.assign(T.en, {
     "meta.title.home":           "ForgeLM — Config-driven LLM fine-tuning toolkit",
     "meta.desc.home":            "ForgeLM is a YAML-driven, enterprise-ready LLM fine-tuning toolkit. SFT, DPO, SimPO, KTO, ORPO, GRPO — with safety evaluation, EU AI Act compliance, and CI/CD-integrated design.",
-    "home.hero.badge":           "Open source · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "Open source · Apache 2.0 · v0.5.0",
     "home.hero.title":           "YAML in.<br><span class=\"text-gradient\">Fine-tuned model</span> out.",
     "home.hero.lead":            "ForgeLM is the config-driven LLM fine-tuning toolkit for teams that ship into regulated environments. The full alignment stack — SFT, DPO, SimPO, KTO, ORPO, GRPO — with integrated safety evaluation, EU AI Act audit trails, and auto-revert on quality regression.",
     "home.hero.cta1":            "Get started",
@@ -359,7 +359,7 @@
   Object.assign(T.tr, {
     "meta.title.home":           "ForgeLM — Konfigürasyon odaklı LLM fine-tuning araç seti",
     "meta.desc.home":            "ForgeLM, YAML temelli kurumsal seviyede LLM fine-tuning araç setidir. SFT, DPO, SimPO, KTO, ORPO, GRPO — güvenlik değerlendirmesi, EU AI Act uyumu ve CI/CD ile entegre tasarımıyla.",
-    "home.hero.badge":           "Açık kaynak · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "Açık kaynak · Apache 2.0 · v0.5.0",
     "home.hero.title":           "YAML gir.<br><span class=\"text-gradient\">Fine-tuned model</span> al.",
     "home.hero.lead":            "ForgeLM, regülasyonlu ortamlara üretim çıkaran ekipler için konfigürasyon odaklı LLM fine-tuning araç setidir. Tam alignment yığını — SFT, DPO, SimPO, KTO, ORPO, GRPO — entegre güvenlik değerlendirmesi, EU AI Act denetim kayıtları ve kalite regresyonunda otomatik geri alma ile.",
     "home.hero.cta1":            "Hemen başla",
@@ -434,7 +434,7 @@
   Object.assign(T.de, {
     "meta.title.home":           "ForgeLM — Konfigurationsgesteuertes LLM-Fine-Tuning-Toolkit",
     "meta.desc.home":            "ForgeLM ist ein YAML-getriebenes, unternehmensreifes LLM-Fine-Tuning-Toolkit. SFT, DPO, SimPO, KTO, ORPO, GRPO — mit Sicherheitsbewertung, EU-AI-Act-Compliance und CI/CD-integriertem Design.",
-    "home.hero.badge":           "Open Source · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "Open Source · Apache 2.0 · v0.5.0",
     "home.hero.title":           "YAML rein.<br><span class=\"text-gradient\">Fine-Tuned Modell</span> raus.",
     "home.hero.lead":            "ForgeLM ist das konfigurationsgesteuerte LLM-Fine-Tuning-Toolkit für Teams, die in regulierte Umgebungen liefern. Der vollständige Alignment-Stack — SFT, DPO, SimPO, KTO, ORPO, GRPO — mit integrierter Sicherheitsbewertung, EU-AI-Act-Audit-Trails und automatischem Rollback bei Qualitätsregression.",
     "home.hero.cta1":            "Loslegen",
@@ -509,7 +509,7 @@
   Object.assign(T.fr, {
     "meta.title.home":           "ForgeLM — Boîte à outils de fine-tuning LLM pilotée par configuration",
     "meta.desc.home":            "ForgeLM est une boîte à outils de fine-tuning LLM pilotée par YAML, prête pour l'entreprise. SFT, DPO, SimPO, KTO, ORPO, GRPO — avec évaluation de sécurité, conformité EU AI Act et conception intégrée à CI/CD.",
-    "home.hero.badge":           "Open source · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "Open source · Apache 2.0 · v0.5.0",
     "home.hero.title":           "Du YAML.<br>Un <span class=\"text-gradient\">modèle fine-tuné</span>.",
     "home.hero.lead":            "ForgeLM est la boîte à outils de fine-tuning LLM pilotée par configuration pour les équipes qui livrent en environnement régulé. La pile d'alignement complète — SFT, DPO, SimPO, KTO, ORPO, GRPO — avec évaluation de sécurité intégrée, pistes d'audit EU AI Act et rollback automatique en cas de régression de qualité.",
     "home.hero.cta1":            "Commencer",
@@ -584,7 +584,7 @@
   Object.assign(T.es, {
     "meta.title.home":           "ForgeLM — Toolkit de fine-tuning de LLM basado en configuración",
     "meta.desc.home":            "ForgeLM es un toolkit de fine-tuning de LLM impulsado por YAML y listo para empresas. SFT, DPO, SimPO, KTO, ORPO, GRPO — con evaluación de seguridad, cumplimiento del EU AI Act y diseño integrado con CI/CD.",
-    "home.hero.badge":           "Código abierto · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "Código abierto · Apache 2.0 · v0.5.0",
     "home.hero.title":           "YAML entra.<br><span class=\"text-gradient\">Modelo fine-tuned</span> sale.",
     "home.hero.lead":            "ForgeLM es el toolkit de fine-tuning de LLM basado en configuración para equipos que despliegan en entornos regulados. El stack de alignment completo — SFT, DPO, SimPO, KTO, ORPO, GRPO — con evaluación de seguridad integrada, registros de auditoría EU AI Act y reversión automática ante regresiones de calidad.",
     "home.hero.cta1":            "Empezar",
@@ -659,7 +659,7 @@
   Object.assign(T.zh, {
     "meta.title.home":           "ForgeLM — 基于配置的 LLM 微调工具包",
     "meta.desc.home":            "ForgeLM 是一个基于 YAML、面向企业的 LLM 微调工具包。SFT、DPO、SimPO、KTO、ORPO、GRPO — 配备安全评估、EU AI Act 合规以及与 CI/CD 集成的设计。",
-    "home.hero.badge":           "开源 · Apache 2.0 · v0.5.2",
+    "home.hero.badge":           "开源 · Apache 2.0 · v0.5.0",
     "home.hero.title":           "输入 YAML。<br>输出<span class=\"text-gradient\">微调模型</span>。",
     "home.hero.lead":            "ForgeLM 是面向需要在受监管环境中交付的团队的、基于配置的 LLM 微调工具包。完整对齐栈 — SFT、DPO、SimPO、KTO、ORPO、GRPO — 配备内置安全评估、EU AI Act 审计轨迹,以及质量回归时的自动回滚。",
     "home.hero.cta1":            "开始使用",
@@ -1340,7 +1340,7 @@
     "compliance.art9.title":      "Risk management",
     "compliance.art9.body":       "A continuous, iterative process: identify foreseeable risks, evaluate, mitigate. Auto-revert on threshold breach is the technical mitigation; trend tracking is the monitoring loop.",
     "compliance.art10.title":     "Data &amp; data governance",
-    "compliance.art10.body":      "Quality, relevance, representativeness criteria. Bias detection, PII redaction, cross-split leakage gate. Every audit report becomes a Article 10 evidence document.",
+    "compliance.art10.body":      "Quality, relevance, representativeness criteria. Bias detection, PII redaction, cross-split leakage gate. Optional Presidio ML-NER PII layer and Croissant 1.0 dataset card emitted alongside the audit. Every audit report becomes an Article 10 evidence document.",
     "compliance.art11.title":     "Technical documentation",
     "compliance.art11.body":      "Annex IV's eight required sections — auto-populated from the run: general description, detailed system, monitoring, risk management, lifecycle, standards, declaration, post-market.",
     "compliance.art12.title":     "Record-keeping (logs)",
@@ -1383,7 +1383,7 @@
     "compliance.art9.title":      "Risk yönetimi",
     "compliance.art9.body":       "Sürekli, iteratif süreç: öngörülebilir riskleri tanımla, değerlendir, azalt. Eşik aşımında otomatik geri alma teknik mitigasyon; trend izleme monitoring döngüsü.",
     "compliance.art10.title":     "Veri ve veri yönetimi",
-    "compliance.art10.body":      "Kalite, uygunluk, temsiliyet kriterleri. Bias tespiti, PII redaksiyonu, split-arası sızıntı kapısı. Her audit raporu Madde 10 kanıt belgesi olur.",
+    "compliance.art10.body":      "Kalite, uygunluk, temsiliyet kriterleri. Bias tespiti, PII redaksiyonu, split-arası sızıntı kapısı. Opsiyonel Presidio ML-NER PII katmanı ve audit ile birlikte yayınlanan Croissant 1.0 dataset card. Her audit raporu Madde 10 kanıt belgesi olur.",
     "compliance.art11.title":     "Teknik dokümantasyon",
     "compliance.art11.body":      "Annex IV'ün sekiz zorunlu bölümü — koşudan otomatik doldurulur: genel açıklama, detay sistem, izleme, risk yönetimi, yaşam döngüsü, standartlar, beyan, post-market.",
     "compliance.art12.title":     "Kayıt tutma (loglar)",
@@ -1426,7 +1426,7 @@
     "compliance.art9.title":      "Risikomanagement",
     "compliance.art9.body":       "Ein kontinuierlicher, iterativer Prozess: vorhersehbare Risiken identifizieren, bewerten, mindern. Auto-Rollback bei Schwellenüberschreitung ist die technische Maßnahme; Trend-Tracking ist die Monitoring-Schleife.",
     "compliance.art10.title":     "Daten &amp; Datengovernance",
-    "compliance.art10.body":      "Kriterien für Qualität, Relevanz, Repräsentativität. Bias-Erkennung, PII-Schwärzung, Split-übergreifender Leak-Check. Jeder Audit-Bericht wird zu einem Artikel-10-Beweisdokument.",
+    "compliance.art10.body":      "Kriterien für Qualität, Relevanz, Repräsentativität. Bias-Erkennung, PII-Schwärzung, Split-übergreifender Leak-Check. Optionale Presidio-ML-NER-PII-Schicht und Croissant-1.0-Datensatzkarte, die zusammen mit dem Audit ausgegeben wird. Jeder Audit-Bericht wird zu einem Artikel-10-Beweisdokument.",
     "compliance.art11.title":     "Technische Dokumentation",
     "compliance.art11.body":      "Die acht Pflichtabschnitte von Annex IV — automatisch aus dem Lauf befüllt: allgemeine Beschreibung, detailliertes System, Monitoring, Risikomanagement, Lebenszyklus, Normen, Erklärung, Post-Market.",
     "compliance.art12.title":     "Aufzeichnungen (Logs)",
@@ -1469,7 +1469,7 @@
     "compliance.art9.title":      "Gestion des risques",
     "compliance.art9.body":       "Un processus continu et itératif : identifier les risques prévisibles, évaluer, atténuer. Le rollback automatique en cas de dépassement de seuil est la mitigation technique ; le suivi de tendance est la boucle de surveillance.",
     "compliance.art10.title":     "Données &amp; gouvernance des données",
-    "compliance.art10.body":      "Critères de qualité, pertinence, représentativité. Détection de biais, masquage des PII, gate de fuite inter-split. Chaque rapport d'audit devient un document de preuve pour l'Article 10.",
+    "compliance.art10.body":      "Critères de qualité, pertinence, représentativité. Détection de biais, masquage des PII, gate de fuite inter-split. Couche PII Presidio ML-NER optionnelle et carte de jeu de données Croissant 1.0 émise aux côtés de l'audit. Chaque rapport d'audit devient un document de preuve pour l'Article 10.",
     "compliance.art11.title":     "Documentation technique",
     "compliance.art11.body":      "Les huit sections obligatoires d'Annex IV — auto-remplies à partir de l'exécution : description générale, système détaillé, surveillance, gestion des risques, cycle de vie, normes, déclaration, post-marché.",
     "compliance.art12.title":     "Tenue de registres (logs)",
@@ -1512,7 +1512,7 @@
     "compliance.art9.title":      "Gestión de riesgos",
     "compliance.art9.body":       "Un proceso continuo e iterativo: identifique riesgos previsibles, evalúe, mitigue. La reversión automática ante violación de umbral es la mitigación técnica; el seguimiento de tendencias es el bucle de monitorización.",
     "compliance.art10.title":     "Datos y gobernanza de datos",
-    "compliance.art10.body":      "Criterios de calidad, relevancia, representatividad. Detección de sesgos, redacción de PII, puerta de fuga entre splits. Cada informe de auditoría se convierte en un documento probatorio del Artículo 10.",
+    "compliance.art10.body":      "Criterios de calidad, relevancia, representatividad. Detección de sesgos, redacción de PII, puerta de fuga entre splits. Capa PII de Presidio ML-NER opcional y tarjeta de dataset Croissant 1.0 emitida junto con la auditoría. Cada informe de auditoría se convierte en un documento probatorio del Artículo 10.",
     "compliance.art11.title":     "Documentación técnica",
     "compliance.art11.body":      "Las ocho secciones obligatorias del Annex IV — auto-rellenadas desde la ejecución: descripción general, sistema detallado, monitorización, gestión de riesgos, ciclo de vida, normas, declaración, post-mercado.",
     "compliance.art12.title":     "Registro (logs)",
@@ -1555,7 +1555,7 @@
     "compliance.art9.title":      "风险管理",
     "compliance.art9.body":       "一个持续的、迭代的过程:识别可预见的风险、评估、缓解。阈值越界时自动回滚是技术缓解;趋势跟踪是监控回路。",
     "compliance.art10.title":     "数据 &amp; 数据治理",
-    "compliance.art10.body":      "质量、相关性、代表性标准。偏见检测、PII 屏蔽、split 间泄漏 gate。每份审计报告都成为 Article 10 的证据文档。",
+    "compliance.art10.body":      "质量、相关性、代表性标准。偏见检测、PII 屏蔽、split 间泄漏 gate。可选的 Presidio ML-NER PII 层,以及与审计一同输出的 Croissant 1.0 数据集卡片。每份审计报告都成为 Article 10 的证据文档。",
     "compliance.art11.title":     "技术文档",
     "compliance.art11.body":      "Annex IV 的八个必需章节 — 由运行自动填充:总体描述、详细系统、监控、风险管理、生命周期、标准、声明、上市后。",
     "compliance.art12.title":     "记录保存 (日志)",
diff --git a/site/quickstart.html b/site/quickstart.html
index 267e580c..393b2460 100644
--- a/site/quickstart.html
+++ b/site/quickstart.html
@@ -133,11 +133,14 @@ <h3 data-i18n="quickstart.step3.title">Audit your data first</h3>
               <span class="lang">terminal</span>
               <button class="copy-btn" type="button" data-i18n="common.copy.idle">copy</button>
             </div>
-            <pre class="code-block-body"><span class="comment"># have raw documents? Ingest first.</span>
+            <pre class="code-block-body"><span class="comment"># have raw documents? Ingest first. --all-mask is shorthand for</span>
+<span class="comment"># --secrets-mask --pii-mask (the documented combined-scrub flow).</span>
 <span class="prompt">$</span> forgelm ingest ./policies/ <span class="flag">--recursive</span> <span class="flag">--strategy</span> markdown \
-    <span class="flag">--secrets-mask</span> <span class="flag">--pii-mask</span> <span class="flag">--output</span> data/policies.jsonl
+    <span class="flag">--all-mask</span> <span class="flag">--output</span> data/policies.jsonl
 
-<span class="comment"># then audit (PII / secrets / leakage / quality / language).</span>
+<span class="comment"># then audit (PII / secrets / leakage / quality / language). Add</span>
+<span class="comment"># --croissant for a Google Croissant 1.0 dataset card; --pii-ml for</span>
+<span class="comment"># Presidio NER on top (needs `forgelm[ingestion-pii-ml]` extra).</span>
 <span class="prompt">$</span> forgelm audit data/policies.jsonl <span class="flag">--output</span> ./audit/
 
 <span class="prompt">$</span> jq <span class="string">'.pii_summary, .near_duplicate_pairs, .cross_split_overlap'</span> \

From 6add171ad04a94de319ab529d439c92bc410fcde Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 21:16:08 +0300
Subject: [PATCH 05/12] fix(phase-12.5 review): apply CodeRabbit + Sonar
 findings on PR #18
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Major (CodeRabbit):
- data_audit.py: pre-flight `--pii-ml-language` against the analyzer's
  `supported_languages` so unsupported languages raise ValueError before
  any rows are scanned, instead of being silently swallowed by the
  per-row except handler in detect_pii_ml().
- data_audit.py: derive Croissant `file_id` from the real source filename
  (Path.name) instead of the canonical split label, so single-file audits
  (`policies.jsonl`) and alias layouts (`dev.jsonl` → split `validation`)
  reference the file actually on disk.
- data_audit.py: sanitize the Croissant `url` field to a basename so
  cards published to HuggingFace / MLCommons don't leak the auditor's
  absolute filesystem path (`/Users/...` / `/home/builder/...`).

Docs alignment:
- pii-ml.md (en + tr): rewrite the language-selection + programmatic-API
  sections to describe the actual pre-flight behaviour instead of the
  earlier "errors propagate to the caller" claim.
- data_audit.md / data_audit-tr.md: drop `version` from the Croissant
  field list (the generator omits it by design) and add `--pii-ml`,
  `--pii-ml-language`, `--croissant` to the CLI synopsis blocks.
- ingestion.md / ingestion-tr.md: add `--all-mask` to the CLI synopsis.
- roadmap.md / roadmap-tr.md: align the documentation map with the
  v0.5.0 consolidation narrative (no more orphan v0.5.1/v0.5.2/v0.5.3
  references for already-merged phases).
- audit.md (tr) + croissant-card.md (en + tr) + data_audit.md guides:
  upgrade prose links to mlcommons.org from http to https. Code-example
  references to the JSON-LD `cr:` namespace IRI stay http to match the
  spec-canonical identifier the audit emits.
- CHANGELOG.md: add `bash` language tag to the install-recipe fence
  (markdownlint MD040).

Tests:
- TestCroissantFileIdReflectsRealFilename — single-file + alias layouts
  + url-no-leak regression.
- TestPresidioLanguagePreflight — ValueError for unsupported language,
  default English passes.

Skipped (false positives):
- 42 Codacy MD051 link-fragment warnings on `#/...` hash-router links —
  established convention used in 488 places under docs/usermanuals/.
- 2 SonarCloud HOTSPOT-LOW on `http://mlcommons.org/croissant/` JSON-LD
  identifiers (canonical Croissant 1.0 namespace IRIs, not network
  endpoints) — requires manual "Safe" review in the SonarCloud UI.
- Sourcery: PR diff exceeded their 150KB limit.
- Qodo: free-tier limit reached.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                               |   2 +-
 docs/guides/data_audit-tr.md               |  11 +-
 docs/guides/data_audit.md                  |  11 +-
 docs/guides/ingestion-tr.md                |   1 +
 docs/guides/ingestion.md                   |   1 +
 docs/roadmap-tr.md                         |  10 +-
 docs/roadmap.md                            |  10 +-
 docs/usermanuals/en/data/audit.md          |   2 +-
 docs/usermanuals/en/data/croissant-card.md |   4 +-
 docs/usermanuals/en/data/pii-ml.md         |  12 +-
 docs/usermanuals/tr/data/audit.md          |   2 +-
 docs/usermanuals/tr/data/croissant-card.md |   4 +-
 docs/usermanuals/tr/data/pii-ml.md         |  12 +-
 forgelm/data_audit.py                      |  73 +++++++---
 tests/test_phase12_5.py                    | 156 +++++++++++++++++++++
 15 files changed, 260 insertions(+), 51 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7b2776f..48a8fd5e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -93,7 +93,7 @@ additive surface on top of the Phase 12 ingestion + audit lineage.
   check covers BOTH the missing-extra branch AND the missing-spaCy-model
   branch — `presidio-analyzer` does *not* transitively ship a spaCy
   NER model, so the install recipe is now two lines:
-  ```
+  ```bash
   pip install 'forgelm[ingestion-pii-ml]'
   python -m spacy download en_core_web_lg
   ```
diff --git a/docs/guides/data_audit-tr.md b/docs/guides/data_audit-tr.md
index 56a4e07d..be7c8ada 100644
--- a/docs/guides/data_audit-tr.md
+++ b/docs/guides/data_audit-tr.md
@@ -399,7 +399,7 @@ regex yolunda kalır.
 ### Croissant 1.0 dataset card — `--croissant` (Faz 12.5, opt-in)
 
 `--croissant`, `data_audit_report.json` içinde yeni bir top-level
-`croissant` bloğunu [Google Croissant 1.0](http://mlcommons.org/croissant/)
+`croissant` bloğunu [Google Croissant 1.0](https://mlcommons.org/croissant/)
 dataset card'ı (`@type: sc:Dataset`) ile doldurur. Card, kanonik
 `mlcommons.org/croissant/1.0` context'iyle uyumludur — bu yüzden
 Croissant farkındalıklı consumer'lar (HuggingFace dataset cards,
@@ -412,8 +412,10 @@ forgelm audit data/ --output ./audit/ --croissant
 
 Card şunları taşır:
 
-* dataset seviyesinde kimlik (`name`, `description`, `version`,
-  `datePublished`, `url`),
+* dataset seviyesinde kimlik (`name`, `description`, `datePublished`,
+  `url`) — `version` bilinçli olarak çıkarılmıştır, audit'in dataset
+  sürümü için first-class kanıtı yoktur; card'ı yayınlayan operatörler
+  `version`'ı `license` / `citeAs` gibi elle düzenler,
 * her JSONL split'i için bir `cr:FileObject` (Croissant consumer'ı
   altta yatan dosyaları bulabilsin diye),
 * her split için audit'in column-detection katmanından türetilen
@@ -480,6 +482,9 @@ forgelm audit PATH \
   [--dedup-method {simhash,minhash}] \
   [--jaccard-threshold X] \
   [--quality-filter] \
+  [--pii-ml] \
+  [--pii-ml-language LANG] \
+  [--croissant] \
   [--output-format {text,json}] \
   [--quiet | --log-level {DEBUG,INFO,WARNING,ERROR}]
 ```
diff --git a/docs/guides/data_audit.md b/docs/guides/data_audit.md
index e6169326..98591d92 100644
--- a/docs/guides/data_audit.md
+++ b/docs/guides/data_audit.md
@@ -396,7 +396,7 @@ zero-extra-deps regex path.
 ### Croissant 1.0 dataset card — `--croissant` (Phase 12.5, opt-in)
 
 `--croissant` populates a new top-level `croissant` block in
-`data_audit_report.json` with a [Google Croissant 1.0](http://mlcommons.org/croissant/)
+`data_audit_report.json` with a [Google Croissant 1.0](https://mlcommons.org/croissant/)
 dataset card (`@type: sc:Dataset`). The card is conformant with the
 canonical `mlcommons.org/croissant/1.0` context, so Croissant-aware
 consumers (HuggingFace dataset cards, MLCommons reference loaders, the
@@ -408,8 +408,10 @@ forgelm audit data/ --output ./audit/ --croissant
 
 The card carries:
 
-* dataset-level identity (`name`, `description`, `version`,
-  `datePublished`, `url`),
+* dataset-level identity (`name`, `description`, `datePublished`,
+  `url`) — `version` is intentionally omitted because the audit has
+  no first-class evidence for dataset version; operators that publish
+  the card hand-edit `version` like they do `license` / `citeAs`,
 * one `cr:FileObject` per JSONL split (so a Croissant consumer can
   locate the underlying files),
 * one `cr:RecordSet` per split with `cr:Field` entries derived from
@@ -474,6 +476,9 @@ forgelm audit PATH \
   [--dedup-method {simhash,minhash}] \
   [--jaccard-threshold X] \
   [--quality-filter] \
+  [--pii-ml] \
+  [--pii-ml-language LANG] \
+  [--croissant] \
   [--output-format {text,json}] \
   [--quiet | --log-level {DEBUG,INFO,WARNING,ERROR}]
 ```
diff --git a/docs/guides/ingestion-tr.md b/docs/guides/ingestion-tr.md
index 76197911..16919f22 100644
--- a/docs/guides/ingestion-tr.md
+++ b/docs/guides/ingestion-tr.md
@@ -233,6 +233,7 @@ forgelm ingest INPUT_PATH \
   [--recursive] \
   [--pii-mask] \
   [--secrets-mask] \
+  [--all-mask] \
   [--output-format {text,json}] \
   [--quiet | --log-level {DEBUG,INFO,WARNING,ERROR}]
 ```
diff --git a/docs/guides/ingestion.md b/docs/guides/ingestion.md
index 7068011c..769ab1f5 100644
--- a/docs/guides/ingestion.md
+++ b/docs/guides/ingestion.md
@@ -234,6 +234,7 @@ forgelm ingest INPUT_PATH \
   [--recursive] \
   [--pii-mask] \
   [--secrets-mask] \
+  [--all-mask] \
   [--output-format {text,json}] \
   [--quiet | --log-level {DEBUG,INFO,WARNING,ERROR}]
 ```
diff --git a/docs/roadmap-tr.md b/docs/roadmap-tr.md
index dc5b0578..6ecc748c 100644
--- a/docs/roadmap-tr.md
+++ b/docs/roadmap-tr.md
@@ -79,12 +79,12 @@ docs/
     ├── completed-phases.md                     # Faz 1-10 arşivi (detaylı, İngilizce)
     ├── phase-10-post-training.md               # Tamamlandı — v0.4.0
     ├── phase-10-5-quickstart.md                # Tamam (Faz 10.5) — v0.4.5 olarak yayınlandı
-    ├── phase-11-data-ingestion.md              # Tamam (Faz 11) — v0.5.0 olarak çıktı
-    ├── phase-11-5-backlog.md                   # Tamam (Faz 11.5) — v0.5.1 için indi; ingestion/audit cilası
-    ├── phase-12-data-curation-maturity.md      # Tamam (Faz 12 Tier 1) — v0.5.2 için indi; MinHash LSH, markdown splitter, secrets scan
-    ├── phase-12-5-backlog.md                   # Faz 12.5 follow-up backlog (Presidio, Croissant, --all-mask, wizard audit-first)
+    ├── phase-11-data-ingestion.md              # Tamam (Faz 11) — v0.5.0'a birleştirildi
+    ├── phase-11-5-backlog.md                   # Tamam (Faz 11.5) — v0.5.0'a birleştirildi; ingestion/audit cilası
+    ├── phase-12-data-curation-maturity.md      # Tamam (Faz 12 Tier 1) — v0.5.0'a birleştirildi; MinHash LSH, markdown splitter, secrets scan
+    ├── phase-12-5-backlog.md                   # Tamam (Faz 12.5) — v0.5.0'a birleştirildi; Presidio, Croissant, --all-mask, wizard audit-first
     ├── phase-13-pro-cli.md                     # Planlandı — v0.6.0-pro (gated)
-    ├── phase-14-pipeline-chains.md             # Planlandı — v0.5.3 (v0.5.2'den kaydırıldı)
+    ├── phase-14-pipeline-chains.md             # Planlandı — v0.5.1 (v0.5.0 birleştirmesinin takip release'i)
     ├── releases.md                             # v0.3.0 → v0.6.0 sürüm notları
     └── risks-and-decisions.md                  # Risk matrisi, fırsatlar, rekabet analizi, karar günlüğü
 ```
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 7166ed8f..fc3eb4ef 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -79,12 +79,12 @@ docs/
     ├── completed-phases.md                     # Phase 1-10 archive (detailed)
     ├── phase-10-post-training.md               # Completed — v0.4.0
     ├── phase-10-5-quickstart.md                # Done (Phase 10.5) — shipped as v0.4.5
-    ├── phase-11-data-ingestion.md              # Done (Phase 11) — shipped v0.5.0
-    ├── phase-11-5-backlog.md                   # Done (Phase 11.5) — landed for v0.5.1; ingestion/audit polish
-    ├── phase-12-data-curation-maturity.md      # Done (Phase 12 Tier 1) — landed for v0.5.2; MinHash LSH, markdown splitter, secrets scan
-    ├── phase-12-5-backlog.md                   # Phase 12.5 follow-up backlog (Presidio adapter, Croissant metadata, --all-mask, wizard audit-first)
+    ├── phase-11-data-ingestion.md              # Done (Phase 11) — consolidated into v0.5.0
+    ├── phase-11-5-backlog.md                   # Done (Phase 11.5) — consolidated into v0.5.0; ingestion/audit polish
+    ├── phase-12-data-curation-maturity.md      # Done (Phase 12 Tier 1) — consolidated into v0.5.0; MinHash LSH, markdown splitter, secrets scan
+    ├── phase-12-5-backlog.md                   # Done (Phase 12.5) — consolidated into v0.5.0; Presidio adapter, Croissant metadata, --all-mask, wizard audit-first
     ├── phase-13-pro-cli.md                     # Planned — v0.6.0-pro (gated)
-    ├── phase-14-pipeline-chains.md             # Planned — v0.5.3 (reslotted from v0.5.2)
+    ├── phase-14-pipeline-chains.md             # Planned — v0.5.1 (follow-up to the v0.5.0 consolidation)
     ├── releases.md                             # v0.3.0 → v0.6.0 release notes
     └── risks-and-decisions.md                  # Risk matrix, opportunities, competitive positioning, decision log
 ```
diff --git a/docs/usermanuals/en/data/audit.md b/docs/usermanuals/en/data/audit.md
index 76011a3f..74e0d1c5 100644
--- a/docs/usermanuals/en/data/audit.md
+++ b/docs/usermanuals/en/data/audit.md
@@ -100,7 +100,7 @@ For **binary** (KTO) datasets:
 | `--sample-rate FLOAT` | Audit a random subsample (e.g. `0.1` for 10%). For very large datasets. |
 | `--quality-filter` | Run heuristic quality checks (Gopher / C4 / RefinedWeb-style). Adds `quality_summary`. See [Quality Filter](#/data/quality-filter). |
 | `--pii-ml [--pii-ml-language LANG]` | Layer Presidio NER on top of the regex PII detector — adds `person` / `organization` / `location` categories into the same `pii_summary` block. Requires the `[ingestion-pii-ml]` extra **and** a spaCy NER model. See [ML-NER PII (Presidio)](#/data/pii-ml). |
-| `--croissant` | Emit a [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card under the report's `croissant` key — same JSON file doubles as both the audit and a Croissant-consumer card. See [Croissant 1.0 Dataset Card](#/data/croissant-card). |
+| `--croissant` | Emit a [Google Croissant 1.0](https://mlcommons.org/croissant/) dataset card under the report's `croissant` key — same JSON file doubles as both the audit and a Croissant-consumer card. See [Croissant 1.0 Dataset Card](#/data/croissant-card). |
 
 ## What's in the report
 
diff --git a/docs/usermanuals/en/data/croissant-card.md b/docs/usermanuals/en/data/croissant-card.md
index 0da898b1..0ac11e00 100644
--- a/docs/usermanuals/en/data/croissant-card.md
+++ b/docs/usermanuals/en/data/croissant-card.md
@@ -5,7 +5,7 @@ description: Optional Google Croissant 1.0 metadata emitted alongside the audit
 
 # Croissant 1.0 Dataset Card — `--croissant`
 
-The audit report (`data_audit_report.json`) already carries every signal an EU AI Act Article 10 reviewer needs: PII counts, secrets summary, near-duplicate pairs, cross-split leakage, language distribution. With `--croissant`, the same file picks up a top-level `croissant` block that conforms to the [Google Croissant 1.0](http://mlcommons.org/croissant/) specification. One file, two consumers.
+The audit report (`data_audit_report.json`) already carries every signal an EU AI Act Article 10 reviewer needs: PII counts, secrets summary, near-duplicate pairs, cross-split leakage, language distribution. With `--croissant`, the same file picks up a top-level `croissant` block that conforms to the [Google Croissant 1.0](https://mlcommons.org/croissant/) specification. One file, two consumers.
 
 ## Why bother?
 
@@ -80,7 +80,7 @@ If you want these fields populated, edit the JSON post-audit before publishing.
 
 ## Conformance
 
-The emitted card is conformant against the canonical [Croissant 1.0 spec](http://mlcommons.org/croissant/1.0). It's been validated against:
+The emitted card is conformant against the canonical [Croissant 1.0 spec](https://mlcommons.org/croissant/). It's been validated against:
 
 - The [Croissant validator](https://github.com/mlcommons/croissant) (`mlcroissant validate`).
 - HuggingFace's dataset card parser (the `datasets` library reads Croissant if present in the dataset directory).
diff --git a/docs/usermanuals/en/data/pii-ml.md b/docs/usermanuals/en/data/pii-ml.md
index ee343d90..68b78cc2 100644
--- a/docs/usermanuals/en/data/pii-ml.md
+++ b/docs/usermanuals/en/data/pii-ml.md
@@ -76,14 +76,14 @@ These tiers sit **deliberately below** the regex `critical`/`high` floors (credi
 
 ## Language selection
 
-Pass `--pii-ml-language` to point at a non-English NLP engine. Presidio raises a typed exception when no engine is registered for the requested language — surfaced loudly so you can install the matching spaCy model:
+Pass `--pii-ml-language` to point at a non-English NLP engine. ForgeLM's pre-flight (`_require_presidio(language=...)`) verifies the requested language is registered on Presidio's `AnalyzerEngine` before any rows are scanned and raises a `ValueError` with the registered-languages list when it isn't — failing fast instead of silently returning empty findings. Default `AnalyzerEngine` only loads English; for non-English corpora you need a custom NlpEngine ([Presidio docs](https://microsoft.github.io/presidio/analyzer/languages/)) plus the matching spaCy model:
 
-```shell
-$ python -m spacy download xx_ent_wiki_sm     # multilingual, smaller
-$ forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
+```bash
+python -m spacy download xx_ent_wiki_sm     # multilingual, smaller
+forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
 ```
 
-Default is `en`. If you run `--pii-ml` on a Turkish-majority corpus without setting the language, Presidio's English NER will return zero or near-zero findings — the audit honestly reports "0 person" but you've effectively run a no-op.
+Default is `en`. If you run `--pii-ml` on a Turkish-majority corpus without configuring the language, the pre-flight aborts with the registered-languages list — no silent zero-findings audit.
 
 ## Why pre-flight matters
 
@@ -111,7 +111,7 @@ print(counts)
 # {'person': 1, 'organization': 1, 'location': 1}
 ```
 
-The function returns an empty dict for non-string input, missing extras, or transient analyzer errors (a single bad row never blocks the audit). Hard failures (missing spaCy model, language not registered) propagate to the caller.
+The function returns an empty dict for non-string input, missing extras, or transient analyzer errors (a single bad row never blocks the audit). Hard failures (missing spaCy model, language not registered) are caught up front by `_require_presidio(language=...)` and raised before any rows are scanned — call it explicitly when you bypass `audit_dataset` and want the same pre-flight guarantees.
 
 ## What's NOT in this layer
 
diff --git a/docs/usermanuals/tr/data/audit.md b/docs/usermanuals/tr/data/audit.md
index 31236b30..0bcb177b 100644
--- a/docs/usermanuals/tr/data/audit.md
+++ b/docs/usermanuals/tr/data/audit.md
@@ -100,7 +100,7 @@ Train vs validation vs test satırları arasında kesin ve near-duplicate eşle
 | `--sample-rate FLOAT` | Rastgele alt-örnek (`0.1` = %10). Çok büyük dataset için. |
 | `--quality-filter` | Heuristik kalite kontrolleri (Gopher / C4 / RefinedWeb stili). `quality_summary` ekler. Bkz. [Kalite Filtresi](#/data/quality-filter). |
 | `--pii-ml [--pii-ml-language LANG]` | Regex PII detector'ın üzerine Presidio NER katmanı ekler — aynı `pii_summary` bloğuna `person` / `organization` / `location` kategorileri ekler. `[ingestion-pii-ml]` extra'sını **ve** bir spaCy NER modelini gerektirir. Bkz. [ML-NER PII (Presidio)](#/data/pii-ml). |
-| `--croissant` | Raporun `croissant` anahtarı altına bir [Google Croissant 1.0](http://mlcommons.org/croissant/) dataset card emit eder — aynı JSON dosyası hem audit hem Croissant-tüketicisi card görevi görür. Bkz. [Croissant 1.0 Dataset Kartı](#/data/croissant-card). |
+| `--croissant` | Raporun `croissant` anahtarı altına bir [Google Croissant 1.0](https://mlcommons.org/croissant/) dataset card emit eder — aynı JSON dosyası hem audit hem Croissant-tüketicisi card görevi görür. Bkz. [Croissant 1.0 Dataset Kartı](#/data/croissant-card). |
 
 ## Rapor içeriği
 
diff --git a/docs/usermanuals/tr/data/croissant-card.md b/docs/usermanuals/tr/data/croissant-card.md
index c88671f0..28d50db2 100644
--- a/docs/usermanuals/tr/data/croissant-card.md
+++ b/docs/usermanuals/tr/data/croissant-card.md
@@ -5,7 +5,7 @@ description: Audit raporunun yanında yayınlanan opsiyonel Google Croissant 1.0
 
 # Croissant 1.0 Dataset Kartı — `--croissant`
 
-Audit raporu (`data_audit_report.json`) bir EU AI Act Madde 10 reviewer'ının ihtiyacı olan her sinyali zaten taşır: PII sayıları, secrets özeti, near-duplicate çiftleri, cross-split sızıntı, dil dağılımı. `--croissant` ile aynı dosya, [Google Croissant 1.0](http://mlcommons.org/croissant/) spec'ine uyan top-level bir `croissant` bloğu kazanır. Tek dosya, iki tüketici.
+Audit raporu (`data_audit_report.json`) bir EU AI Act Madde 10 reviewer'ının ihtiyacı olan her sinyali zaten taşır: PII sayıları, secrets özeti, near-duplicate çiftleri, cross-split sızıntı, dil dağılımı. `--croissant` ile aynı dosya, [Google Croissant 1.0](https://mlcommons.org/croissant/) spec'ine uyan top-level bir `croissant` bloğu kazanır. Tek dosya, iki tüketici.
 
 ## Niye uğraşalım?
 
@@ -80,7 +80,7 @@ Bu alanların doldurulmasını istiyorsanız, publish öncesi audit-sonrası JSO
 
 ## Conformance
 
-Yayınlanan card kanonik [Croissant 1.0 spec](http://mlcommons.org/croissant/1.0)'ine uyumludur. Şunlara karşı doğrulanmıştır:
+Yayınlanan card kanonik [Croissant 1.0 spec](https://mlcommons.org/croissant/)'ine uyumludur. Şunlara karşı doğrulanmıştır:
 
 - [Croissant validator](https://github.com/mlcommons/croissant) (`mlcroissant validate`).
 - HuggingFace'in dataset card parser'ı (`datasets` kütüphanesi dataset dizininde varsa Croissant'ı okur).
diff --git a/docs/usermanuals/tr/data/pii-ml.md b/docs/usermanuals/tr/data/pii-ml.md
index 569df51e..826dee9e 100644
--- a/docs/usermanuals/tr/data/pii-ml.md
+++ b/docs/usermanuals/tr/data/pii-ml.md
@@ -76,14 +76,14 @@ Bu katmanlar **bilinçli olarak** regex'in `critical`/`high` zeminlerinin (kredi
 
 ## Dil Seçimi {#dil-secimi}
 
-Non-English NLP engine'e işaret etmek için `--pii-ml-language` geçin. Talep edilen dil için bir engine kayıtlı değilse Presidio typed bir exception raise eder — eşleşen spaCy modelini kurabilmeniz için yüksek sesle yüzeye çıkar:
+Non-English NLP engine'e işaret etmek için `--pii-ml-language` geçin. ForgeLM'in pre-flight'ı (`_require_presidio(language=...)`) hiçbir satır taranmadan önce talep edilen dilin Presidio `AnalyzerEngine`'inde kayıtlı olduğunu doğrular; değilse kayıtlı dil listesini içeren bir `ValueError` raise eder — sessizce boş bulgu döndürmek yerine peşinen başarısız olur. Varsayılan `AnalyzerEngine` yalnızca İngilizce yükler; non-English korpuslar için özel bir NlpEngine ([Presidio dokümanı](https://microsoft.github.io/presidio/analyzer/languages/)) ve eşleşen spaCy modeli gerekir:
 
-```shell
-$ python -m spacy download xx_ent_wiki_sm     # çok dilli, daha küçük
-$ forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
+```bash
+python -m spacy download xx_ent_wiki_sm     # çok dilli, daha küçük
+forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
 ```
 
-Varsayılan `en`. Türkçe ağırlıklı bir korpusta `--pii-ml`'i dil ayarlamadan çalıştırırsanız, Presidio'nun İngilizce NER'i sıfır veya sıfıra yakın bulgu döndürür — audit dürüstçe "0 person" raporlar ama efektif olarak no-op çalıştırmış olursunuz.
+Varsayılan `en`. Türkçe ağırlıklı bir korpusta `--pii-ml`'i dil yapılandırmadan çalıştırırsanız, pre-flight kayıtlı dil listesiyle birlikte abort olur — sessiz sıfır-bulgu audit'i yoktur.
 
 ## Pre-flight neden önemli {#pre-flight-neden-onemli}
 
@@ -111,7 +111,7 @@ print(counts)
 # {'person': 1, 'organization': 1, 'location': 1}
 ```
 
-Fonksiyon non-string input, eksik extra'lar veya geçici analyzer hataları için boş dict döndürür (tek bir kötü satır audit'i bloke etmez). Sert arızalar (eksik spaCy modeli, kayıtlı olmayan dil) caller'a propagate olur.
+Fonksiyon non-string input, eksik extra'lar veya geçici analyzer hataları için boş dict döndürür (tek bir kötü satır audit'i bloke etmez). Sert arızalar (eksik spaCy modeli, kayıtlı olmayan dil) `_require_presidio(language=...)` tarafından peşinen yakalanır ve hiçbir satır taranmadan önce raise edilir — `audit_dataset`'i bypass ettiğinizde aynı pre-flight garantilerini istiyorsanız bunu açıkça çağırın.
 
 ## Bu katmanda OLMAYAN şeyler
 
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index 8aa7f00a..2dec13a5 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -430,8 +430,8 @@ def _get_presidio_analyzer() -> Any:
 )
 
 
-def _require_presidio() -> None:
-    """Raise a clear ImportError when the optional ML-NER backend is unusable.
+def _require_presidio(language: str = "en") -> None:
+    """Raise a clear ImportError / ValueError when the optional ML-NER backend is unusable.
 
     Mirrors :func:`_require_datasketch` but extends the check to model
     availability: a fresh ``[ingestion-pii-ml]`` install does **not**
@@ -442,11 +442,19 @@ def _require_presidio() -> None:
     swallows per-row failures) the audit would silently report zero
     ML PII coverage. Pre-flighting the analyzer build here surfaces
     the missing-model case before any rows are scanned.
+
+    When ``language`` is non-default, also verify the requested language
+    is registered on the analyzer's supported list. Presidio's default
+    ``AnalyzerEngine`` only loads English; ``--pii-ml --pii-ml-language tr``
+    against a default install would otherwise return ``{}`` per row
+    (``analyzer.analyze`` raises ``ValueError`` which
+    :func:`detect_pii_ml` swallows). Failing fast with an actionable
+    message is the only way the operator notices the misconfiguration.
     """
     if not _HAS_PRESIDIO:
         raise ImportError(_PRESIDIO_INSTALL_HINT)
     try:
-        _get_presidio_analyzer()
+        analyzer = _get_presidio_analyzer()
     except OSError as exc:
         # spaCy raises ``OSError`` ("Can't find model 'en_core_web_lg'")
         # when the model package isn't on the import path. Re-raise as
@@ -457,6 +465,15 @@ def _require_presidio() -> None:
         raise ImportError(
             f"Presidio analyzer build failed (likely missing spaCy NER model): {exc}\n{_PRESIDIO_INSTALL_HINT}"
         ) from exc
+    supported = getattr(analyzer, "supported_languages", None) or ["en"]
+    if language not in supported:
+        raise ValueError(
+            f"Presidio analyzer has no NLP engine registered for language {language!r}. "
+            f"Registered languages: {sorted(supported)}. "
+            "The default AnalyzerEngine only loads English; for non-English corpora "
+            "configure a custom NlpEngine before invoking the audit (see "
+            "https://microsoft.github.io/presidio/analyzer/languages/)."
+        )
 
 
 # Presidio canonicalises spaCy NER labels through its
@@ -490,9 +507,11 @@ def detect_pii_ml(text: Any, *, language: str = "en") -> Dict[str, int]:
         text: Per-row payload; defensive against ``None`` / numbers / dicts.
         language: Presidio NLP-engine language code. Default ``"en"``.
             Set via :func:`audit_dataset`'s ``pii_ml_language`` parameter.
-            Presidio raises a typed exception if no NLP engine is
-            registered for the requested language — surfaced as the
-            same per-row swallow as any other analyzer failure.
+            The unsupported-language case is caught up-front by
+            :func:`_require_presidio` (called from ``audit_dataset`` when
+            ``enable_pii_ml`` is set), so the per-row ``ValueError``
+            swallow below only fires for pathological inputs / transient
+            engine state, not for misconfiguration.
 
     Returns an empty dict when:
     * ``text`` is not a non-empty string (defensive — callers pass JSONL
@@ -505,8 +524,8 @@ def detect_pii_ml(text: Any, *, language: str = "en") -> Dict[str, int]:
       ``RuntimeError``) and let everything else propagate so genuine
       bugs (``OSError`` on missing model, ``MemoryError``, ``KeyboardInterrupt``)
       stay visible. The pre-flight in :func:`_require_presidio` covers
-      the missing-model case so it never reaches this path in the
-      common run.
+      the missing-model and unsupported-language cases so neither
+      reaches this path in the common run.
     """
     if not isinstance(text, str) or not text.strip():
         return {}
@@ -2472,7 +2491,16 @@ def _build_croissant_metadata(
     record_sets: List[Dict[str, Any]] = []
     for split_name, info in splits_info.items():
         sample_count = int(info.get("sample_count", 0))
-        file_id = f"{split_name}.jsonl"
+        # Derive ``file_id`` from the real source filename (basename
+        # only, never the absolute path) so single-file audits like
+        # ``policies.jsonl`` don't show up as ``train.jsonl`` in the
+        # generated card and alias layouts (``dev.jsonl`` → split
+        # ``validation``) keep their on-disk filename. Falls back to
+        # the canonical ``{split}.jsonl`` shape when no path is
+        # registered — defensive for callers that bypass
+        # ``_resolve_input``.
+        split_path = splits_paths.get(split_name)
+        file_id = split_path.name if split_path else f"{split_name}.jsonl"
         # ``contentUrl`` deliberately uses the *file_id* (relative
         # filename), not the absolute filesystem path: cards published
         # to HuggingFace / MLCommons must not leak the auditor's local
@@ -2521,14 +2549,22 @@ def _build_croissant_metadata(
             }
         )
 
-    # ``url`` carries ``source_input`` (as-typed) rather than the
-    # resolved absolute path — see ``contentUrl`` rationale above.
+    # ``url`` carries the basename of ``source_input`` so we never
+    # publish an auditor's absolute filesystem path
+    # (``/Users/...`` / ``/home/builder/...``) into a card that may be
+    # shipped to HuggingFace / MLCommons. ``Path.name`` gives the
+    # relative form for both files (``policies.jsonl``) and directories
+    # (``data/`` → ``data``); when ``source_input`` is empty we fall
+    # back to the dataset name. Operators that want a real public URL
+    # (HF Hub, S3) hand-edit at publish time, the same way they do
+    # ``license`` / ``citeAs``.
     # ``version`` (``sc:version``) describes the *dataset* version,
     # not the Croissant vocabulary version (vocab conformance is
     # declared via ``conformsTo``). The audit doesn't have first-class
     # evidence for dataset version, so the field is omitted; operators
     # that publish the card hand-edit ``version`` like they do
     # ``license`` / ``citeAs``.
+    url_safe = Path(source_input).name if source_input else name
     return {
         "@context": dict(_CROISSANT_CONTEXT),
         "@type": "sc:Dataset",
@@ -2540,7 +2576,7 @@ def _build_croissant_metadata(
             "Inline counts/quality/PII summaries live in the parent "
             "data_audit_report.json under the canonical audit keys."
         ),
-        "url": source_input,
+        "url": url_safe,
         "datePublished": generated_at,
         "distribution": distribution,
         "recordSet": record_sets,
@@ -2637,10 +2673,15 @@ def audit_dataset(
             raise ValueError(f"minhash_num_perm must be a positive integer; got {minhash_num_perm!r}.")
         _require_datasketch()
     if enable_pii_ml:
-        # Phase 12.5: pre-flight the optional extra so the caller learns
-        # the dep is missing BEFORE we open any files / scan any rows,
-        # mirroring the ``_require_datasketch`` shape above.
-        _require_presidio()
+        # Phase 12.5: pre-flight the optional extra AND the requested
+        # language so the caller learns the dep / model / language is
+        # missing BEFORE we open any files / scan any rows, mirroring
+        # the ``_require_datasketch`` shape above. Without the language
+        # check, ``--pii-ml-language tr`` against a default Presidio
+        # install would silently return ``{}`` per row (analyzer raises
+        # ``ValueError`` which ``detect_pii_ml`` deliberately swallows
+        # for per-row resilience on pathological strings).
+        _require_presidio(language=pii_ml_language)
 
     splits_paths, resolution_notes = _resolve_input(source)
 
diff --git a/tests/test_phase12_5.py b/tests/test_phase12_5.py
index 8191e508..315ad03a 100644
--- a/tests/test_phase12_5.py
+++ b/tests/test_phase12_5.py
@@ -526,3 +526,159 @@ def test_envelope_croissant_is_empty_when_flag_off(self, tmp_path, capsys):
         # Phase 12 precedent: present-and-empty when off.
         assert "croissant" in envelope
         assert envelope["croissant"] == {}
+
+
+# ---------------------------------------------------------------------------
+# Phase 12.5 review fixes — verified-by-test follow-ups from PR #18
+# ---------------------------------------------------------------------------
+
+
+class TestCroissantFileIdReflectsRealFilename:
+    """``file_id`` must come from the real source filename, not the split label.
+
+    Single-file audits and alias layouts (``dev.jsonl`` → split
+    ``validation``) used to fabricate ``file_id = f"{split_name}.jsonl"``
+    which mismatched the file actually on disk and broke any consumer
+    that tried to resolve the card's ``contentUrl`` back to the JSONL.
+    """
+
+    def _write_jsonl(self, path: Path, rows) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+
+    def test_single_file_audit_keeps_real_filename(self, tmp_path):
+        # ``policies.jsonl`` must show up in the card as ``policies.jsonl``,
+        # not as ``train.jsonl`` (the canonical split label _resolve_input
+        # assigns to single-file inputs).
+        ds = tmp_path / "policies.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}, {"text": "beta"}])
+        out_dir = tmp_path / "audit"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(ds),
+                "--output",
+                str(out_dir),
+                "--croissant",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        crois = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))["croissant"]
+        ids = {entry["@id"] for entry in crois["distribution"]}
+        assert ids == {"policies.jsonl"}
+        for entry in crois["distribution"]:
+            assert entry["contentUrl"] == "policies.jsonl"
+            assert entry["name"] == "policies.jsonl"
+
+    def test_alias_layout_keeps_real_filename(self, tmp_path):
+        # ``dev.jsonl`` is folded onto canonical split name ``validation``
+        # by _resolve_input. The card must still reference the real file
+        # (``dev.jsonl``), otherwise the contentUrl points to a file
+        # that doesn't exist on disk.
+        data_dir = tmp_path / "splits"
+        data_dir.mkdir()
+        self._write_jsonl(data_dir / "train.jsonl", [{"text": "alpha"}])
+        self._write_jsonl(data_dir / "dev.jsonl", [{"text": "beta"}])
+        out_dir = tmp_path / "audit"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                str(data_dir),
+                "--output",
+                str(out_dir),
+                "--croissant",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        crois = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))["croissant"]
+        ids = {entry["@id"] for entry in crois["distribution"]}
+        assert ids == {"train.jsonl", "dev.jsonl"}, (
+            "alias layout must keep the real filename, not the canonical split label"
+        )
+
+    def test_url_does_not_leak_absolute_path(self, tmp_path):
+        # When the operator passes an absolute path, the published card
+        # must not carry ``/Users/...`` / ``/home/builder/...`` — those
+        # leak the auditor's local layout to whoever reads the card.
+        ds = tmp_path / "policies.jsonl"
+        self._write_jsonl(ds, [{"text": "alpha"}])
+        out_dir = tmp_path / "audit"
+        absolute_input = str(ds.resolve())
+        assert absolute_input.startswith("/"), "test precondition: absolute path"
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "audit",
+                absolute_input,
+                "--output",
+                str(out_dir),
+                "--croissant",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        crois = json.loads((out_dir / "data_audit_report.json").read_text(encoding="utf-8"))["croissant"]
+        assert "/" not in crois["url"], f"url field leaks absolute path: {crois['url']!r}"
+        assert crois["url"] == "policies.jsonl"
+
+
+class TestPresidioLanguagePreflight:
+    """Pre-flight rejects unsupported ``--pii-ml-language`` instead of swallowing.
+
+    Without the pre-flight, ``analyzer.analyze(text, language='xx')``
+    raises ``ValueError`` per row inside ``detect_pii_ml`` and the
+    handler swallows it — so ``--pii-ml --pii-ml-language xx`` against
+    a default Presidio install (which only registers English) returns
+    zero ML findings without a peep. That's exactly the silent-failure
+    anti-pattern Phase 12.5 set out to remove, so we pin the loud-fail
+    behaviour with a regression test.
+    """
+
+    def test_unsupported_language_raises_value_error(self):
+        from forgelm.data_audit import _get_presidio_analyzer, _require_presidio
+
+        class _StubAnalyzer:
+            supported_languages = ["en"]
+
+        _get_presidio_analyzer.cache_clear()
+        try:
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with patch(
+                    "forgelm.data_audit._get_presidio_analyzer",
+                    return_value=_StubAnalyzer(),
+                ):
+                    with pytest.raises(ValueError) as exc_info:
+                        _require_presidio(language="xx")
+        finally:
+            _get_presidio_analyzer.cache_clear()
+        msg = str(exc_info.value)
+        assert "xx" in msg
+        assert "en" in msg  # registered list shows what is available
+
+    def test_default_english_language_passes_preflight(self):
+        from forgelm.data_audit import _get_presidio_analyzer, _require_presidio
+
+        class _StubAnalyzer:
+            supported_languages = ["en"]
+
+        _get_presidio_analyzer.cache_clear()
+        try:
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with patch(
+                    "forgelm.data_audit._get_presidio_analyzer",
+                    return_value=_StubAnalyzer(),
+                ):
+                    _require_presidio(language="en")  # must not raise
+        finally:
+            _get_presidio_analyzer.cache_clear()

From 53a8a087b2f07c0aef33c87324d4738920184a6e Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 21:21:20 +0300
Subject: [PATCH 06/12] fix(phase-12.5 review): suppress two false-positive
 linter findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codacy MD051 (42 link-fragment warnings):
- Add docs/usermanuals/.markdownlint-cli2.yaml disabling MD051 only for
  the user-manual SPA tree. The `#/<section>/<page>` pattern is the
  hash-router scheme parsed at runtime by site/js/guide.js::parseHash;
  these are route identifiers consumed after the markdown is baked into
  site/js/usermanuals/<lang>.js by tools/build_usermanuals.py — they
  are NOT in-page anchors and MD051 cannot validate them. The
  convention is part of the public navigation contract (used in 488
  places). MD051 stays enabled everywhere else (CHANGELOG, README,
  docs/standards, docs/guides, docs/roadmap).

SonarCloud python:S5332 (2 LOW security hotspots):
- Annotate the two http:// strings in `_CROISSANT_CONTEXT` and the
  emitted `conformsTo` value with `# NOSONAR` + an explanatory comment.
  These are JSON-LD canonical namespace IRIs as defined by the Croissant
  1.0 spec — RDF identifiers, not network endpoints. Strict consumers
  (mlcroissant validator, MLCommons reference loaders) compare these
  strings lexically; switching to `https://` would diverge from the
  spec-canonical form and break exact-match consumers. Note: SonarCloud
  may still surface these as hotspots-to-review even with NOSONAR
  because hotspots have a separate "human review" workflow; the user
  may need to mark them "Safe" once in the SonarCloud UI to clear the
  Quality Gate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/usermanuals/.markdownlint-cli2.yaml | 15 +++++++++++++++
 forgelm/data_audit.py                    | 16 ++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)
 create mode 100644 docs/usermanuals/.markdownlint-cli2.yaml

diff --git a/docs/usermanuals/.markdownlint-cli2.yaml b/docs/usermanuals/.markdownlint-cli2.yaml
new file mode 100644
index 00000000..3b337d51
--- /dev/null
+++ b/docs/usermanuals/.markdownlint-cli2.yaml
@@ -0,0 +1,15 @@
+# Per-directory markdownlint config for the user-manual SPA source.
+#
+# MD051 (link-fragments) is disabled here because the user manuals use
+# the SPA hash-router scheme `#/<section>/<page>` (parsed at runtime by
+# site/js/guide.js::parseHash). These are NOT in-page anchors that
+# MD051 can validate — they are route identifiers consumed by the
+# guide-page renderer once the markdown is baked into
+# site/js/usermanuals/<lang>.js by tools/build_usermanuals.py.
+#
+# The convention is used in 488 places across docs/usermanuals/ and is
+# part of the public navigation contract; we keep MD051 enabled for the
+# rest of the docs tree (CHANGELOG, README, docs/standards, docs/guides,
+# docs/roadmap) where standard anchors are the right shape.
+config:
+  MD051: false
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index 2dec13a5..cc61fead 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -2426,7 +2426,14 @@ def _build_quality_summary(
     "@language": "en",
     "@vocab": "https://schema.org/",
     "sc": "https://schema.org/",
-    "cr": "http://mlcommons.org/croissant/",
+    # ``cr:`` is the canonical Croissant 1.0 JSON-LD namespace IRI as
+    # defined by the mlcommons.org/croissant spec — an RDF identifier,
+    # not a network endpoint. Strict consumers (mlcroissant validator,
+    # MLCommons reference loaders) compare this string lexically; using
+    # ``https://`` here would diverge from the spec-canonical form and
+    # break exact-match consumers. The S5332 hotspot is a false positive
+    # for this dual-purpose URI.
+    "cr": "http://mlcommons.org/croissant/",  # NOSONAR — JSON-LD namespace IRI, not a fetch URL
     "data": {"@id": "cr:data", "@type": "@json"},
     "dataType": {"@id": "cr:dataType", "@type": "@vocab"},
     "extract": "cr:extract",
@@ -2568,7 +2575,12 @@ def _build_croissant_metadata(
     return {
         "@context": dict(_CROISSANT_CONTEXT),
         "@type": "sc:Dataset",
-        "conformsTo": "http://mlcommons.org/croissant/1.0",
+        # ``conformsTo`` declares the Croissant vocabulary version the
+        # card adheres to. Like ``cr:`` above, this is a JSON-LD URI
+        # identifier (RDF reference), not a network endpoint — strict
+        # consumers exact-match the canonical spec form. Same S5332
+        # false-positive rationale as ``cr:`` in ``_CROISSANT_CONTEXT``.
+        "conformsTo": "http://mlcommons.org/croissant/1.0",  # NOSONAR — JSON-LD identifier
         "name": name,
         "description": (
             "ForgeLM audit-generated dataset card. "

From 06894c1b61e65478d056d181f6343c436e93aecb Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 21:28:36 +0300
Subject: [PATCH 07/12] fix(codacy): move markdownlint config to repo root
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The per-directory .markdownlint-cli2.yaml under docs/usermanuals/ did
not clear the 42 MD051 warnings because Codacy's markdownlint
integration invokes the linter once with a fixed root-config flag and
does not walk per-directory config inheritance the way a local
markdownlint-cli2 run would.

Move the config to the repo root and disable MD051 globally with a
detailed rationale comment explaining the trade-off. The user-manual
SPA at site/guide.html uses `#/<section>/<page>` hash-router links
parsed by site/js/guide.js::parseHash — these are route identifiers,
not in-page anchors, so MD051 produces 42 false positives that drown
out genuine signal across 488 link sites.

Trade-off: a small number of standards/guides files use real
`#anchor-name` links that MD051 would otherwise validate. We accept
the loss because those files are human-edited and code review catches
obvious anchor breakage; all other markdownlint rules stay enforced.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .markdownlint-cli2.yaml                  | 25 ++++++++++++++++++++++++
 docs/usermanuals/.markdownlint-cli2.yaml | 15 --------------
 2 files changed, 25 insertions(+), 15 deletions(-)
 create mode 100644 .markdownlint-cli2.yaml
 delete mode 100644 docs/usermanuals/.markdownlint-cli2.yaml

diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
new file mode 100644
index 00000000..86a02c51
--- /dev/null
+++ b/.markdownlint-cli2.yaml
@@ -0,0 +1,25 @@
+# Root markdownlint-cli2 config.
+#
+# MD051 (link-fragments) is disabled because the user-manual SPA at
+# site/guide.html uses the hash-router scheme `#/<section>/<page>`
+# (parsed at runtime by site/js/guide.js::parseHash). These are NOT
+# in-page anchors — they are route identifiers consumed after the
+# markdown is baked into site/js/usermanuals/<lang>.js by
+# tools/build_usermanuals.py.
+#
+# The convention is used in 488 places across docs/usermanuals/ and is
+# part of the public navigation contract. MD051 cannot distinguish
+# these route IDs from broken anchors, so it produces 42 noisy false
+# positives that drown out genuine signal. Codacy's markdownlint
+# integration does not honour per-directory config files (it runs each
+# file with a single root-config invocation), so the rule has to be
+# disabled at the root.
+#
+# Trade-off: a small number of standards/guides files use real
+# `#anchor-name` links that MD051 would otherwise validate. We accept
+# the loss because (a) those files are human-edited and code review
+# catches obvious anchor breakage, (b) markdown previewers visualise
+# broken anchors at edit time, and (c) all other markdownlint rules
+# (MD001-MD050, MD052+) remain enforced.
+config:
+  MD051: false
diff --git a/docs/usermanuals/.markdownlint-cli2.yaml b/docs/usermanuals/.markdownlint-cli2.yaml
deleted file mode 100644
index 3b337d51..00000000
--- a/docs/usermanuals/.markdownlint-cli2.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
-# Per-directory markdownlint config for the user-manual SPA source.
-#
-# MD051 (link-fragments) is disabled here because the user manuals use
-# the SPA hash-router scheme `#/<section>/<page>` (parsed at runtime by
-# site/js/guide.js::parseHash). These are NOT in-page anchors that
-# MD051 can validate — they are route identifiers consumed by the
-# guide-page renderer once the markdown is baked into
-# site/js/usermanuals/<lang>.js by tools/build_usermanuals.py.
-#
-# The convention is used in 488 places across docs/usermanuals/ and is
-# part of the public navigation contract; we keep MD051 enabled for the
-# rest of the docs tree (CHANGELOG, README, docs/standards, docs/guides,
-# docs/roadmap) where standard anchors are the right shape.
-config:
-  MD051: false

From e71a783e535b133bd679bbac1880567a290d65c6 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 21:33:56 +0300
Subject: [PATCH 08/12] fix(codacy): use .markdownlint.yaml instead of
 .markdownlint-cli2.yaml

Codacy's markdownlint integration reads the original markdownlint
config format (.markdownlint.yaml / .markdownlint.json) at the repo
root, not the markdownlint-cli2 variant. The previous
.markdownlint-cli2.yaml was silently ignored by Codacy, leaving the 42
MD051 warnings in place across two re-runs.

Switch to .markdownlint.yaml with the same MD051: false setting and
the same documented rationale. The format is also forward-compatible
with markdownlint-cli2 (which reads both shapes).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .markdownlint-cli2.yaml | 25 -------------------------
 .markdownlint.yaml      | 21 +++++++++++++++++++++
 2 files changed, 21 insertions(+), 25 deletions(-)
 delete mode 100644 .markdownlint-cli2.yaml
 create mode 100644 .markdownlint.yaml

diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
deleted file mode 100644
index 86a02c51..00000000
--- a/.markdownlint-cli2.yaml
+++ /dev/null
@@ -1,25 +0,0 @@
-# Root markdownlint-cli2 config.
-#
-# MD051 (link-fragments) is disabled because the user-manual SPA at
-# site/guide.html uses the hash-router scheme `#/<section>/<page>`
-# (parsed at runtime by site/js/guide.js::parseHash). These are NOT
-# in-page anchors — they are route identifiers consumed after the
-# markdown is baked into site/js/usermanuals/<lang>.js by
-# tools/build_usermanuals.py.
-#
-# The convention is used in 488 places across docs/usermanuals/ and is
-# part of the public navigation contract. MD051 cannot distinguish
-# these route IDs from broken anchors, so it produces 42 noisy false
-# positives that drown out genuine signal. Codacy's markdownlint
-# integration does not honour per-directory config files (it runs each
-# file with a single root-config invocation), so the rule has to be
-# disabled at the root.
-#
-# Trade-off: a small number of standards/guides files use real
-# `#anchor-name` links that MD051 would otherwise validate. We accept
-# the loss because (a) those files are human-edited and code review
-# catches obvious anchor breakage, (b) markdown previewers visualise
-# broken anchors at edit time, and (c) all other markdownlint rules
-# (MD001-MD050, MD052+) remain enforced.
-config:
-  MD051: false
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 00000000..9433d915
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1,21 @@
+# Root markdownlint config — read by Codacy's markdownlint integration
+# AND by markdownlint / markdownlint-cli2 locally.
+#
+# MD051 (link-fragments) is disabled because the user-manual SPA at
+# site/guide.html uses the hash-router scheme `#/<section>/<page>`
+# (parsed at runtime by site/js/guide.js::parseHash). These are NOT
+# in-page anchors — they are route identifiers consumed after the
+# markdown is baked into site/js/usermanuals/<lang>.js by
+# tools/build_usermanuals.py.
+#
+# The convention is used in 488 places across docs/usermanuals/ and is
+# part of the public navigation contract. MD051 cannot distinguish
+# these route IDs from broken anchors, so it produces 42 noisy false
+# positives that drown out genuine signal. Disabling it globally is
+# the simplest safe fix; standards/guides files using real
+# `#anchor-name` links lose MD051 protection but stay readable in
+# previewers and code review still catches obvious anchor breakage.
+#
+# All other markdownlint rules (MD001-MD050, MD052+) remain enforced.
+default: true
+MD051: false

From 42676af692c0567741624dc5e8f90c42730c74fd Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 21:39:25 +0300
Subject: [PATCH 09/12] =?UTF-8?q?revert(codacy):=20drop=20.markdownlint.ya?=
 =?UTF-8?q?ml=20=E2=80=94=20it=20was=20triggering=20MORE=20noise?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adding a markdownlint config file caused Codacy to switch from its own
narrow rule set (42 MD051 warnings) to markdownlint's default rule set
(229 issues including MD013 line-length, MD004 list-style, MD014
dollar-sign, MD025 single-h1, etc.). The trade-off was clearly worse:
229 cosmetic warnings drown out signal far more than the 42
documented-false-positive MD051 hash-router warnings.

Drop the config file. Path forward for the remaining 42 false
positives:
1. Mark them \"False Positive\" in the Codacy UI on a per-finding
   basis (preserves Codacy as a useful gate going forward), OR
2. Disable rule MD051 at project level in Codacy UI (admin action,
   one-time, applies to all future PRs), OR
3. Accept that Codacy reports them as ACTION_REQUIRED — this is a
   soft check that does not block merge unless the branch-protection
   policy requires it.

SonarCloud remains green (Quality Gate passed, 0 hotspots).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .markdownlint.yaml | 21 ---------------------
 1 file changed, 21 deletions(-)
 delete mode 100644 .markdownlint.yaml

diff --git a/.markdownlint.yaml b/.markdownlint.yaml
deleted file mode 100644
index 9433d915..00000000
--- a/.markdownlint.yaml
+++ /dev/null
@@ -1,21 +0,0 @@
-# Root markdownlint config — read by Codacy's markdownlint integration
-# AND by markdownlint / markdownlint-cli2 locally.
-#
-# MD051 (link-fragments) is disabled because the user-manual SPA at
-# site/guide.html uses the hash-router scheme `#/<section>/<page>`
-# (parsed at runtime by site/js/guide.js::parseHash). These are NOT
-# in-page anchors — they are route identifiers consumed after the
-# markdown is baked into site/js/usermanuals/<lang>.js by
-# tools/build_usermanuals.py.
-#
-# The convention is used in 488 places across docs/usermanuals/ and is
-# part of the public navigation contract. MD051 cannot distinguish
-# these route IDs from broken anchors, so it produces 42 noisy false
-# positives that drown out genuine signal. Disabling it globally is
-# the simplest safe fix; standards/guides files using real
-# `#anchor-name` links lose MD051 protection but stay readable in
-# previewers and code review still catches obvious anchor breakage.
-#
-# All other markdownlint rules (MD001-MD050, MD052+) remain enforced.
-default: true
-MD051: false

From 502ff8866da6696ced9cef62987d2d17b57de453 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 23:09:33 +0300
Subject: [PATCH 10/12] feat(phase-12.5 review): make --pii-ml-language
 actually functional + log per-row Presidio failures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two CodeRabbit findings on the previous review pass were valid and code-tractable:

1. _get_presidio_analyzer was hardcoded to AnalyzerEngine() (English-only).
   The --pii-ml-language flag added in the previous commit only validated
   the request against the analyzer's supported_languages — for non-English
   it always raised because the analyzer never registered anything but
   English. Now _get_presidio_analyzer accepts a language parameter and
   builds a per-language NlpEngineProvider for the codes in
   _SPACY_MODEL_FOR_LANGUAGE (en, de, es, fr, it, ja, ko, nl, pl, pt, ru,
   zh, plus 'xx' multilingual fallback). Languages outside the map raise
   ValueError up front with a hint pointing at xx or the Python-API custom
   path. lru_cache widened to maxsize=8 for realistic multi-language audits.

2. The per-row (ValueError, RuntimeError) handler in detect_pii_ml swallowed
   silently, leaving operators with zero diagnostic when ML coverage was
   unexpectedly empty. Now logs at DEBUG with exc_info, language, and the
   exception — visible under --log-level DEBUG, silent in normal runs so
   pathological-corpora floods don't drown out audit findings.

Tests:
- TestPresidioLanguagePreflight.test_unmapped_language_raises_value_error_at_analyzer_build
- TestPresidioPerRowErrorLogging.test_per_row_value_error_emits_debug_log

Docs: pii-ml.md (en + tr) updated with the supported-language list, the
de_core_news_lg example, and the xx multilingual-fallback recipe.

CodeRabbit's remaining 4 findings (convert #/data/... links to relative .md
paths) were rejected:

- The #/<section>/<page> pattern is the SPA hash-router convention used
  in 488 places across docs/usermanuals/, parsed at runtime by
  site/js/guide.js::parseHash. tools/build_usermanuals.py does NOT
  rewrite link targets — switching to ../foo.md would render as a literal
  href that the browser navigates to a non-existent static URL, breaking
  the user-manual SPA navigation. The MD051 false positives stay; the
  documented path forward is to disable MD051 in the Codacy UI at project
  level (one-time admin action). SonarCloud is already passing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/usermanuals/en/data/pii-ml.md |  13 ++-
 docs/usermanuals/tr/data/pii-ml.md |  13 ++-
 forgelm/data_audit.py              | 130 ++++++++++++++++++++++++-----
 tests/test_phase12_5.py            |  61 ++++++++++++++
 4 files changed, 190 insertions(+), 27 deletions(-)

diff --git a/docs/usermanuals/en/data/pii-ml.md b/docs/usermanuals/en/data/pii-ml.md
index 68b78cc2..c7271fbb 100644
--- a/docs/usermanuals/en/data/pii-ml.md
+++ b/docs/usermanuals/en/data/pii-ml.md
@@ -76,14 +76,21 @@ These tiers sit **deliberately below** the regex `critical`/`high` floors (credi
 
 ## Language selection
 
-Pass `--pii-ml-language` to point at a non-English NLP engine. ForgeLM's pre-flight (`_require_presidio(language=...)`) verifies the requested language is registered on Presidio's `AnalyzerEngine` before any rows are scanned and raises a `ValueError` with the registered-languages list when it isn't — failing fast instead of silently returning empty findings. Default `AnalyzerEngine` only loads English; for non-English corpora you need a custom NlpEngine ([Presidio docs](https://microsoft.github.io/presidio/analyzer/languages/)) plus the matching spaCy model:
+Pass `--pii-ml-language` to audit non-English corpora. ForgeLM auto-builds a Presidio `AnalyzerEngine` for the requested language when you pass a code from the supported map (English defaults plus `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `zh`); install the conventional spaCy model first:
 
 ```bash
-python -m spacy download xx_ent_wiki_sm     # multilingual, smaller
+python -m spacy download de_core_news_lg
+forgelm audit data/german-corpus.jsonl --pii-ml --pii-ml-language de
+```
+
+For languages without a maintained spaCy model (Turkish, Arabic, etc.), use the multilingual fallback `xx`:
+
+```bash
+python -m spacy download xx_ent_wiki_sm
 forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
 ```
 
-Default is `en`. If you run `--pii-ml` on a Turkish-majority corpus without configuring the language, the pre-flight aborts with the registered-languages list — no silent zero-findings audit.
+The pre-flight (`_require_presidio(language=...)`) validates both the spaCy model availability and the language registration before any rows are scanned; misconfiguration aborts with an actionable error instead of silently returning zero findings.
 
 ## Why pre-flight matters
 
diff --git a/docs/usermanuals/tr/data/pii-ml.md b/docs/usermanuals/tr/data/pii-ml.md
index 826dee9e..8a7efc59 100644
--- a/docs/usermanuals/tr/data/pii-ml.md
+++ b/docs/usermanuals/tr/data/pii-ml.md
@@ -76,14 +76,21 @@ Bu katmanlar **bilinçli olarak** regex'in `critical`/`high` zeminlerinin (kredi
 
 ## Dil Seçimi {#dil-secimi}
 
-Non-English NLP engine'e işaret etmek için `--pii-ml-language` geçin. ForgeLM'in pre-flight'ı (`_require_presidio(language=...)`) hiçbir satır taranmadan önce talep edilen dilin Presidio `AnalyzerEngine`'inde kayıtlı olduğunu doğrular; değilse kayıtlı dil listesini içeren bir `ValueError` raise eder — sessizce boş bulgu döndürmek yerine peşinen başarısız olur. Varsayılan `AnalyzerEngine` yalnızca İngilizce yükler; non-English korpuslar için özel bir NlpEngine ([Presidio dokümanı](https://microsoft.github.io/presidio/analyzer/languages/)) ve eşleşen spaCy modeli gerekir:
+Non-English korpusları audit etmek için `--pii-ml-language` geçin. ForgeLM, desteklenen haritadaki bir kod (varsayılan İngilizce'ye ek olarak `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `zh`) verildiğinde istenen dil için otomatik olarak bir Presidio `AnalyzerEngine` inşa eder; önce konvansiyonel spaCy modelini kurun:
 
 ```bash
-python -m spacy download xx_ent_wiki_sm     # çok dilli, daha küçük
+python -m spacy download de_core_news_lg
+forgelm audit data/german-corpus.jsonl --pii-ml --pii-ml-language de
+```
+
+Bakımdaki bir spaCy modeli olmayan diller için (Türkçe, Arapça, vb.) çok-dilli fallback `xx`'i kullanın:
+
+```bash
+python -m spacy download xx_ent_wiki_sm
 forgelm audit data/turkish-corpus.jsonl --pii-ml --pii-ml-language xx
 ```
 
-Varsayılan `en`. Türkçe ağırlıklı bir korpusta `--pii-ml`'i dil yapılandırmadan çalıştırırsanız, pre-flight kayıtlı dil listesiyle birlikte abort olur — sessiz sıfır-bulgu audit'i yoktur.
+Pre-flight (`_require_presidio(language=...)`) hiçbir satır taranmadan önce hem spaCy modelinin mevcudiyetini hem de dil kaydını doğrular; yanlış yapılandırma sessizce sıfır-bulgu döndürmek yerine actionable bir hata ile abort olur.
 
 ## Pre-flight neden önemli {#pre-flight-neden-onemli}
 
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index cc61fead..f1e3b0f9 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -397,25 +397,91 @@ def _replace(match: re.Match, _t: str = pii_type) -> str:
 # ---------------------------------------------------------------------------
 
 
-# Presidio analyzer is heavy to construct (loads spaCy + an English NER
-# model on first call), so we cache a single instance for the duration
-# of the process. ``maxsize=1`` keeps the cache trivially eviction-free
-# while still letting test code blow the cache via ``cache_clear()``.
-@lru_cache(maxsize=1)
-def _get_presidio_analyzer() -> Any:
-    """Return a cached :class:`presidio_analyzer.AnalyzerEngine` instance.
+# Conventional spaCy model name per language code. Covers the languages
+# spaCy publishes a maintained ``*_core_news_lg`` / ``*_core_web_lg``
+# model for; operators auditing in a language not in this map should
+# pass ``"xx"`` for the multilingual fallback (and install
+# ``xx_ent_wiki_sm``) or hand-build a Presidio ``NlpEngine`` and feed
+# it to :func:`audit_dataset` programmatically. The map is small on
+# purpose — auto-mapping more languages without verifying each model's
+# NER quality risks silent under-detection in compliance-critical
+# workflows.
+_SPACY_MODEL_FOR_LANGUAGE: Dict[str, str] = {
+    "en": "en_core_web_lg",
+    "de": "de_core_news_lg",
+    "es": "es_core_news_lg",
+    "fr": "fr_core_news_lg",
+    "it": "it_core_news_lg",
+    "ja": "ja_core_news_lg",
+    "ko": "ko_core_news_lg",
+    "nl": "nl_core_news_lg",
+    "pl": "pl_core_news_lg",
+    "pt": "pt_core_news_lg",
+    "ru": "ru_core_news_lg",
+    "zh": "zh_core_web_lg",
+    # Multilingual fallback — coarser NER but works for any Unicode
+    # script; useful for languages without a dedicated spaCy model
+    # (e.g. Turkish, Arabic at time of writing).
+    "xx": "xx_ent_wiki_sm",
+}
+
+
+# Presidio analyzer is heavy to construct (loads spaCy + a NER model on
+# first call), so we cache instances per-language. ``maxsize=8`` covers
+# the realistic set of audit-language combinations a single process
+# would request without unbounded growth; test code blows the cache via
+# ``cache_clear()``.
+@lru_cache(maxsize=8)
+def _get_presidio_analyzer(language: str = "en") -> Any:
+    """Return a cached :class:`presidio_analyzer.AnalyzerEngine` for ``language``.
+
+    English uses Presidio's default constructor (loads ``en_core_web_lg``
+    via spaCy). Non-English builds an :class:`NlpEngineProvider` keyed
+    on the conventional spaCy model from
+    :data:`_SPACY_MODEL_FOR_LANGUAGE` and instantiates the analyzer with
+    ``supported_languages=[language]`` so the pre-flight in
+    :func:`_require_presidio` sees the requested language as registered.
 
     Raises:
-        ImportError: when the ``[ingestion-pii-ml]`` extra is missing OR
-            when ``presidio-analyzer`` is installed but the spaCy NER
-            model it depends on is not — both surfaces produce the same
-            actionable install hint via :func:`_require_presidio` so
-            the operator never sees a deep ``OSError`` from spaCy
-            mid-stream.
+        ImportError: when the ``[ingestion-pii-ml]`` extra is missing —
+            the actionable install hint surfaces via
+            :func:`_require_presidio` so the operator never sees a deep
+            ``OSError`` from spaCy mid-stream.
+        ValueError: when ``language`` has no entry in
+            :data:`_SPACY_MODEL_FOR_LANGUAGE`. Operators auditing in
+            unsupported languages should use ``"xx"`` (multilingual
+            fallback) or configure a custom Presidio analyzer
+            programmatically.
     """
     if not _HAS_PRESIDIO:
         raise ImportError(_PRESIDIO_INSTALL_HINT)
-    return _PresidioAnalyzer()
+    if language == "en":
+        return _PresidioAnalyzer()
+    model_name = _SPACY_MODEL_FOR_LANGUAGE.get(language)
+    if model_name is None:
+        raise ValueError(
+            f"No default spaCy model registered for Presidio language {language!r}. "
+            f"Supported language codes: {sorted(_SPACY_MODEL_FOR_LANGUAGE)}. "
+            "For other languages, use 'xx' (multilingual fallback, install "
+            "'xx_ent_wiki_sm') or configure a custom Presidio AnalyzerEngine "
+            "via the Python API (see "
+            "https://microsoft.github.io/presidio/analyzer/languages/)."
+        )
+    # Local import: NlpEngineProvider is part of presidio-analyzer, so
+    # gating on ``_HAS_PRESIDIO`` above is sufficient. Importing here
+    # rather than at module top keeps the audit module importable when
+    # the optional extra is missing.
+    from presidio_analyzer.nlp_engine import NlpEngineProvider  # type: ignore[import-not-found]
+
+    nlp_configuration = {
+        "nlp_engine_name": "spacy",
+        "models": [{"lang_code": language, "model_name": model_name}],
+    }
+    nlp_engine = NlpEngineProvider(nlp_configuration=nlp_configuration).create_engine()
+    return _PresidioAnalyzer(
+        nlp_engine=nlp_engine,
+        supported_languages=[language],
+    )
 
 
 # A single, canonical install hint shared by the import-sentinel branch
@@ -426,7 +492,9 @@ def _get_presidio_analyzer() -> Any:
     "Presidio PII ML detection requires the 'ingestion-pii-ml' extra "
     "AND a spaCy English NER model. Install with:\n"
     "  pip install 'forgelm[ingestion-pii-ml]'\n"
-    "  python -m spacy download en_core_web_lg"
+    "  python -m spacy download en_core_web_lg\n"
+    "For non-English audits also install the matching spaCy model "
+    "(e.g. 'python -m spacy download de_core_news_lg' for --pii-ml-language de)."
 )
 
 
@@ -454,7 +522,7 @@ def _require_presidio(language: str = "en") -> None:
     if not _HAS_PRESIDIO:
         raise ImportError(_PRESIDIO_INSTALL_HINT)
     try:
-        analyzer = _get_presidio_analyzer()
+        analyzer = _get_presidio_analyzer(language)
     except OSError as exc:
         # spaCy raises ``OSError`` ("Can't find model 'en_core_web_lg'")
         # when the model package isn't on the import path. Re-raise as
@@ -463,15 +531,23 @@ def _require_presidio(language: str = "en") -> None:
         # failure modes.
         _get_presidio_analyzer.cache_clear()
         raise ImportError(
-            f"Presidio analyzer build failed (likely missing spaCy NER model): {exc}\n{_PRESIDIO_INSTALL_HINT}"
+            f"Presidio analyzer build failed (likely missing spaCy NER model for "
+            f"language {language!r}): {exc}\n{_PRESIDIO_INSTALL_HINT}"
         ) from exc
+    # Defence in depth: ``_get_presidio_analyzer`` builds the analyzer
+    # for the requested language so this should always pass, but a stub
+    # / mock injected by tests or a future Presidio API change could
+    # produce a mismatch — fail loud instead of letting per-row scans
+    # silently return ``{}`` when the analyzer doesn't actually support
+    # what was asked for.
     supported = getattr(analyzer, "supported_languages", None) or ["en"]
     if language not in supported:
         raise ValueError(
             f"Presidio analyzer has no NLP engine registered for language {language!r}. "
             f"Registered languages: {sorted(supported)}. "
-            "The default AnalyzerEngine only loads English; for non-English corpora "
-            "configure a custom NlpEngine before invoking the audit (see "
+            "Use one of the codes in forgelm.data_audit._SPACY_MODEL_FOR_LANGUAGE, "
+            "use 'xx' for the multilingual fallback (install 'xx_ent_wiki_sm'), or "
+            "configure a custom Presidio analyzer via the Python API (see "
             "https://microsoft.github.io/presidio/analyzer/languages/)."
         )
 
@@ -532,9 +608,9 @@ def detect_pii_ml(text: Any, *, language: str = "en") -> Dict[str, int]:
     if not _HAS_PRESIDIO:
         return {}
     try:
-        analyzer = _get_presidio_analyzer()
+        analyzer = _get_presidio_analyzer(language)
         results = analyzer.analyze(text=text, language=language)
-    except (ValueError, RuntimeError):  # pragma: no cover — Presidio edge cases
+    except (ValueError, RuntimeError) as exc:  # pragma: no cover — Presidio edge cases
         # Per-row resilience for the narrow class of failures Presidio
         # raises on bad input or transient engine state. ``OSError`` is
         # deliberately NOT caught here — that's the missing-spaCy-model
@@ -542,6 +618,18 @@ def detect_pii_ml(text: Any, *, language: str = "en") -> Dict[str, int]:
         # converted it to ImportError before any row was scanned. If
         # one slips through (e.g. lazy model load triggered later),
         # surfacing it loudly is the correct behaviour.
+        #
+        # Log at DEBUG (not WARNING): per-row failures can fire on
+        # every row in pathological corpora, and warning-level spam
+        # would drown out the audit's real findings. Operators
+        # debugging "why is ML PII coverage zero" can rerun with
+        # ``--log-level DEBUG`` to see the per-row exception trail.
+        logger.debug(
+            "detect_pii_ml: per-row Presidio failure (language=%s): %s",
+            language,
+            exc,
+            exc_info=True,
+        )
         return {}
     counts: Dict[str, int] = {}
     for finding in results:
diff --git a/tests/test_phase12_5.py b/tests/test_phase12_5.py
index 315ad03a..a0788c1e 100644
--- a/tests/test_phase12_5.py
+++ b/tests/test_phase12_5.py
@@ -682,3 +682,64 @@ class _StubAnalyzer:
                     _require_presidio(language="en")  # must not raise
         finally:
             _get_presidio_analyzer.cache_clear()
+
+    def test_unmapped_language_raises_value_error_at_analyzer_build(self):
+        # Languages without a default spaCy model in
+        # _SPACY_MODEL_FOR_LANGUAGE must fail fast at _get_presidio_analyzer
+        # time with an actionable hint that points at the 'xx' multilingual
+        # fallback or the Python-API custom-engine path. Exercises the
+        # "language not in map" branch directly without needing Presidio
+        # installed.
+        from forgelm.data_audit import _get_presidio_analyzer
+
+        _get_presidio_analyzer.cache_clear()
+        try:
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with pytest.raises(ValueError) as exc_info:
+                    _get_presidio_analyzer(language="qq")
+        finally:
+            _get_presidio_analyzer.cache_clear()
+        msg = str(exc_info.value)
+        assert "qq" in msg
+        assert "xx" in msg  # message points at the multilingual fallback
+
+
+class TestPresidioPerRowErrorLogging:
+    """Per-row Presidio failures must surface at DEBUG level, not silently.
+
+    The handler stays narrow ((ValueError, RuntimeError)) and still
+    returns ``{}`` so a single bad row doesn't block the audit, but a
+    deluge of failures (zero ML coverage) is now diagnosable via
+    ``--log-level DEBUG`` instead of being invisible.
+    """
+
+    def test_per_row_value_error_emits_debug_log(self, caplog):
+        import logging
+
+        from forgelm.data_audit import _get_presidio_analyzer, detect_pii_ml
+
+        class _AngryAnalyzer:
+            def analyze(self, text, language):
+                raise ValueError("simulated per-row failure")
+
+        _get_presidio_analyzer.cache_clear()
+        try:
+            with patch("forgelm.data_audit._HAS_PRESIDIO", True):
+                with patch(
+                    "forgelm.data_audit._get_presidio_analyzer",
+                    return_value=_AngryAnalyzer(),
+                ):
+                    with caplog.at_level(logging.DEBUG, logger="forgelm.data_audit"):
+                        result = detect_pii_ml("some text", language="en")
+        finally:
+            _get_presidio_analyzer.cache_clear()
+        # Behaviour: per-row failure swallowed (returns empty dict)
+        # but a DEBUG-level diagnostic record was emitted with the
+        # language and exception so operators can trace why ML PII
+        # coverage is zero in a noisy corpus.
+        assert result == {}
+        debug_records = [r for r in caplog.records if r.levelno == logging.DEBUG]
+        assert any("per-row Presidio failure" in r.getMessage() for r in debug_records), (
+            "expected DEBUG log for per-row Presidio failure"
+        )
+        assert any("language=en" in r.getMessage() for r in debug_records)

From 7fae240e892b207a82c40b551adbfe6326cf563a Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 23:41:09 +0300
Subject: [PATCH 11/12] docs(changelog): clarify Unreleased section is
 finalized, point at v0.5.1 plan
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses Gemini-medium suggestion on PR #18: the prior phrasing
'(no unreleased changes — next minor will pick up Phase 14, tracked in
docs/roadmap.md)' was ambiguous about whether the v0.5.0 release was
finalized vs. still mid-flight. Reword to 'Empty — v0.5.0 is finalized.
The next minor (v0.5.1) covers Phase 14 ...' so the section state is
explicit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48a8fd5e..4f3038ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,9 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
-(no unreleased changes — next minor will pick up Phase 14, tracked in
-[docs/roadmap.md](docs/roadmap.md))
+_Empty — v0.5.0 is finalized. The next minor (`v0.5.1`) covers Phase 14
+(Multi-Stage Pipeline Chains); see [docs/roadmap.md](docs/roadmap.md)
+for the active phase plan._
 
 ---
 

From a4b2bb23d9f9b31445fbc1770394caace30b88f6 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Wed, 29 Apr 2026 23:58:49 +0300
Subject: [PATCH 12/12] =?UTF-8?q?fix(phase-12.5=20review):=20organisation?=
 =?UTF-8?q?=E2=86=92organization=20+=20extract=20JSON-LD=20key=20constants?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit findings on commit 7fae240:

1. docs/usermanuals/en/data/pii-ml.md:8 — switch British 'organisation
   names' to American 'organization names' to match the rest of the
   file (frontmatter, sample output, severity table, code category
   name 'organization' from _PRESIDIO_ENTITY_MAP).

2. forgelm/data_audit.py — extract _JSONLD_TYPE_KEY and _JSONLD_ID_KEY
   module-level constants, replace literal '@type' / '@id' uses inside
   _build_croissant_metadata. The literals only remain inside
   _CROISSANT_CONTEXT (the verbatim JSON-LD spec snippet) where they
   are part of the spec data, not duplicated keys. Drops the literal
   count from 6× '@type' / 7× '@id' down to 2× of each — below
   SonarCloud S1192's default threshold (3+) so the informational
   issues clear without affecting runtime behaviour.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/usermanuals/en/data/pii-ml.md |  2 +-
 forgelm/data_audit.py              | 26 ++++++++++++++++++--------
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/docs/usermanuals/en/data/pii-ml.md b/docs/usermanuals/en/data/pii-ml.md
index c7271fbb..bd78401c 100644
--- a/docs/usermanuals/en/data/pii-ml.md
+++ b/docs/usermanuals/en/data/pii-ml.md
@@ -5,7 +5,7 @@ description: Optional Microsoft Presidio adapter that adds person / organization
 
 # ML-NER PII Detection — `--pii-ml`
 
-The default [PII Masking](#/data/pii-masking) layer is regex-anchored and covers the *structured* identifiers GDPR Article 10 cares about (email, phone, IBAN, credit card, national IDs). Presidio NER adds the *unstructured* identifiers regex inherently misses: person names, organisation names, geographic locations.
+The default [PII Masking](#/data/pii-masking) layer is regex-anchored and covers the *structured* identifiers GDPR Article 10 cares about (email, phone, IBAN, credit card, national IDs). Presidio NER adds the *unstructured* identifiers regex inherently misses: person names, organization names, geographic locations.
 
 This is an **opt-in** layer. The default audit + ingest behaviour is unchanged when `--pii-ml` is not passed.
 
diff --git a/forgelm/data_audit.py b/forgelm/data_audit.py
index f1e3b0f9..089b819a 100644
--- a/forgelm/data_audit.py
+++ b/forgelm/data_audit.py
@@ -2510,6 +2510,16 @@ def _build_quality_summary(
 # parse the block without modification, while the rest of the audit JSON
 # stays untouched. The card lives under the new ``croissant`` key on the
 # ``AuditReport`` dataclass; callers that don't want it never see it.
+
+# JSON-LD reserved keywords used as dict keys in the Croissant card body.
+# The W3C JSON-LD 1.1 spec fixes these tokens — they're vocabulary
+# constants, not arbitrary strings, but Sonar's S1192 (string-literals-
+# duplicated) flags the repeated literal use across the metadata
+# builder. Hoisting them here keeps the rule satisfied without
+# obscuring that we're emitting standardized JSON-LD framing.
+_JSONLD_TYPE_KEY: str = "@type"
+_JSONLD_ID_KEY: str = "@id"
+
 _CROISSANT_CONTEXT: Dict[str, Any] = {
     "@language": "en",
     "@vocab": "https://schema.org/",
@@ -2605,8 +2615,8 @@ def _build_croissant_metadata(
         # ``license`` / ``citeAs``.
         distribution.append(
             {
-                "@type": "cr:FileObject",
-                "@id": file_id,
+                _JSONLD_TYPE_KEY: "cr:FileObject",
+                _JSONLD_ID_KEY: file_id,
                 "name": file_id,
                 "contentUrl": file_id,
                 "encodingFormat": "application/jsonlines",
@@ -2623,12 +2633,12 @@ def _build_croissant_metadata(
         columns = info.get("columns") or []
         fields = [
             {
-                "@type": "cr:Field",
-                "@id": f"{split_name}/{column}",
+                _JSONLD_TYPE_KEY: "cr:Field",
+                _JSONLD_ID_KEY: f"{split_name}/{column}",
                 "name": column,
                 "dataType": "sc:Text",
                 "source": {
-                    "fileObject": {"@id": file_id},
+                    "fileObject": {_JSONLD_ID_KEY: file_id},
                     "extract": {"jsonPath": f"$.{column}"},
                 },
             }
@@ -2636,8 +2646,8 @@ def _build_croissant_metadata(
         ]
         record_sets.append(
             {
-                "@type": "cr:RecordSet",
-                "@id": split_name,
+                _JSONLD_TYPE_KEY: "cr:RecordSet",
+                _JSONLD_ID_KEY: split_name,
                 "name": split_name,
                 "field": fields,
                 "description": f"Records from split {split_name!r}.",
@@ -2662,7 +2672,7 @@ def _build_croissant_metadata(
     url_safe = Path(source_input).name if source_input else name
     return {
         "@context": dict(_CROISSANT_CONTEXT),
-        "@type": "sc:Dataset",
+        _JSONLD_TYPE_KEY: "sc:Dataset",
         # ``conformsTo`` declares the Croissant vocabulary version the
         # card adheres to. Like ``cr:`` above, this is a JSON-LD URI
         # identifier (RDF reference), not a network endpoint — strict