[Wave 3] Medium — Docs: README.md #78

Wave 3 · 5 finding(s) in 5 fix package(s). One pass over this document; keep the Turkish mirror in sync.

Findings

• DOC-D4B01-015 (docs, Medium) — README.md: stale — The README omits the pre-1.0 compatibility warning the release standard requires
  severity Medium
  Where. README.md (no pre-1.0 notice anywhere) · type: stale
  The document says. The README omits the pre-1.0 compatibility warning the release standard requires
  What the code does. docs/standards/release.md:25 says "Pre-1.0 rule: every minor bump is potentially breaking. Users are warned in README." release.md:145 requires updating README's "compatibility" section on breaking changes. The README has neither, while the version is 0.11.1rc1 and [Unreleased] carries six Breaking items.
  Code references. docs/standards/release.md:25, docs/standards/release.md:145, pyproject.toml:19, CHANGELOG.md:7-63
  Proposed correction. Add a short "Compatibility" note: "ForgeLM is pre-1.0: any minor release may contain breaking changes (exit codes, accepted config values). Read the CHANGELOG's ### Breaking section before upgrading a pinned pipeline."

• DOC-D4B01-016 (docs, Medium) — README.md: broken example — After training: forgelm export ./checkpoints/final_model ... and forgelm deploy ./checkpoints/final_model --target ollama
  severity Medium
  Where. README.md:63-66 · type: broken example
  The document says. After training: forgelm export ./checkpoints/final_model ... and forgelm deploy ./checkpoints/final_model --target ollama
  What the code does. With the default training.merge_adapters: false, final_model/ holds a PEFT adapter only (adapter_config.json plus adapter weights, no base config.json). export and deploy do not detect adapter checkpoints; --benchmark-only does. Export passes the adapter directory straight to convert_hf_to_gguf.py unless --adapter is given with a base model, and the Ollama Modelfile becomes FROM <adapt… **Code references.** [forgelm/config.py:457-460](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/config.py#L457-L460), [forgelm/trainer.py:1716-1730](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/trainer.py#L1716-L1730), [forgelm/export.py:424-436](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/export.py#L424-L436), [forgelm/deploy.py:98](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/deploy.py#L98) **Proposed correction.** "forgelm export <base-model-id> --adapter ./checkpoints/final_model --output model.gguf" (or set training.merge_adapters: truebefore training), and note thatdeploy` expects a merged model directory.

• DOC-D4B01-017 (docs, Medium) — README.md: misleading — "What comes out" lists compliance/annex_iv_metadata.json as an output of the config above
  severity Medium
  Where. README.md:76-84 · type: misleading
  The document says. "What comes out" lists compliance/annex_iv_metadata.json as an output of the config above
  What the code does. annex_iv_metadata.json is written only when the config has a compliance: block with a non-blank provider_name, system_name or intended_purpose. Otherwise build_annex_iv_artifact returns None and the file is silently skipped (no warning). The README config has no compliance block.
  Code references. forgelm/compliance.py:1551-1561, forgelm/compliance.py:1803-1816, forgelm/compliance.py:2226-2236
  Proposed correction. Annotate the tree: "annex_iv_metadata.json # EU AI Act Annex IV — written only when the config has a compliance: block (provider_name / system_name / intended_purpose)"

• DOC-D4B01-019 (docs, Medium) — README.md: misleading — "data_governance_report.json # Article 10 — inlines the dataset audit report"; "that report is inlined into data_governance_report.json at compliance-export time"
  severity Medium
  Where. README.md:81; README.md:145 · type: misleading
  The document says. "data_governance_report.json # Article 10 — inlines the dataset audit report"; "that report is inlined into data_governance_report.json at compliance-export time"
  What the code does. The report is inlined only if data_audit_report.json exists in training.output_dir. forgelm audit writes to ./audit/ by default. Otherwise a WARNING and a compliance.governance_section_missing event are emitted and the Article 10 data-quality section is absent.
  Code references. forgelm/compliance.py:668-705, forgelm/cli/_parser.py:520-530, forgelm/trainer.py:2113-2118
  Proposed correction. "...inlined into data_governance_report.json when data_audit_report.json is in training.output_dir — run forgelm audit <data> --output <training.output_dir> before training."

• DOC-D4B01-021 (docs, Medium) — README.md: misleading — forgelm audit scans a corpus for "length and language distribution" (after pip install forgelm)
  severity Medium
  Where. README.md:130 · type: misleading
  The document says. forgelm audit scans a corpus for "length and language distribution" (after pip install forgelm)
  What the code does. langdetect ships only in the [ingestion] extra. Without it _detect_language swallows the ImportError and returns "unknown" for every row, with no warning. Probe auditrun/lang.jsonl (English and Turkish sentences, core env): languages = unknown=2.
  Code references. forgelm/data_audit/_streaming.py:25-41, pyproject.toml:141-148
  Proposed correction. "...length and language distribution (language detection needs pip install \"forgelm[ingestion]\"; without it every row reports unknown)..."

Done when

• Every finding above is fixed or closed with a reason (tick it here).
• Code fixes carry a test; doc fixes update the Turkish mirror in the same PR.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}