[Wave 4] Low/info — Docs: docs/usermanuals/en/operations/ #789

Wave 4 · 17 finding(s) in 17 fix package(s). Documents with fewer than five findings each in this wave, grouped by directory.

Findings

• DOC-D3B02-056 (docs, Low) — docs/usermanuals/en/operations/air-gap.md: wrong detail — lm-evaluation-harness task definitions are cached at ~/.cache/lm-evaluation-harness/.
  severity Low
  Where. docs/usermanuals/en/operations/air-gap.md:19 (Turkish mirror: docs/usermanuals/tr/operations/air-gap.md:19) · type: wrong detail
  The document says. lm-evaluation-harness task definitions are cached at ~/.cache/lm-evaluation-harness/.
  What the code does. cache-tasks downloads into the HF Datasets cache (HF_DATASETS_CACHE > HF_HOME/datasets > ~/.cache/huggingface/datasets), as the page itself says at L102.
  Code references. forgelm/cli/subcommands/_cache.py:118-136, forgelm/cli/subcommands/_cache.py:162-182
  Proposed correction. "| lm-evaluation-harness task datasets | ~/.cache/huggingface/datasets/ (HF_DATASETS_CACHE) |"
  Turkish mirror. the Turkish page has no such statement

• DOC-D3B02-057 (docs, Low) — docs/usermanuals/en/operations/air-gap.md: broken example — Local teacher snippet synthetic: {enabled: true, teacher_model: ..., teacher_backend: "local"}.
  severity Low
  Where. docs/usermanuals/en/operations/air-gap.md:72-77 (Turkish mirror: docs/usermanuals/tr/operations/air-gap.md:72-77) · type: broken example
  The document says. Local teacher snippet synthetic: {enabled: true, teacher_model: ..., teacher_backend: "local"}.
  What the code does. With enabled: true and no seed_file or seed_prompts, validation fails: "synthetic.enabled is true but no seeds are provided" (dry-run exit 1, reproduced).
  Code references. forgelm/config.py (SyntheticConfig validator)
  Proposed correction. Add seed_file: "data/seed_prompts.jsonl" to the snippet.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-058 (docs, Low) — docs/usermanuals/en/operations/cicd.md: misleading — A "Fit-check VRAM" step inside a pipeline whose "every gate either passes or fails".
  severity Low
  Where. docs/usermanuals/en/operations/cicd.md:59-60,95,131 (Turkish mirror: docs/usermanuals/tr/operations/cicd.md:59-60,96,132) · type: misleading
  The document says. A "Fit-check VRAM" step inside a pipeline whose "every gate either passes or fails".
  What the code does. --fit-check always exits 0, whatever the verdict (OOM included). Reproduced: verdict UNKNOWN, exit 0.
  Code references. forgelm/cli/_no_train_modes.py:269-271, forgelm/cli/_fit_check.py:10-31
  Proposed correction. "--fit-check is advisory (always exit 0); to gate, parse it: forgelm --config run.yaml --fit-check --output-format json | jq -e '.verdict != \"OOM\"'."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-059 (docs, Low) — docs/usermanuals/en/operations/docker.md: wrong detail — Multi-stage: a builder stage installs heavy dependencies, "then a runtime stage copies in the compiled artefacts".
  severity Low · already tracked: KNOWN-OPEN C31-DOCKER-RUNBOOK docs/roadmap/phase-16-trust-surface-hardening.md:694-695
  Where. docs/usermanuals/en/operations/docker.md:90 (Turkish mirror: docs/usermanuals/tr/operations/docker.md:90) · type: wrong detail
  The document says. Multi-stage: a builder stage installs heavy dependencies, "then a runtime stage copies in the compiled artefacts".
  What the code does. The stages are base → deps → runtime, and runtime is FROM deps (the CUDA devel image with everything installed). Nothing is copied from a builder stage.
  Code references. Dockerfile:25-70
  Proposed correction. "Three stages (CUDA base → dependency install → runtime with a non-root user); the runtime stage builds on the dependency stage."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-060 (docs, Low) — docs/usermanuals/en/operations/docker.md: broken example — RUN forgelm cache-tasks --tasks hellaswag,... inside an image built from the default image.
  severity Low · already tracked: KNOWN-OPEN C31-DOCKER-RUNBOOK docs/roadmap/phase-16-trust-surface-hardening.md:694-695
  Where. docs/usermanuals/en/operations/docker.md:106-107 (Turkish mirror: docs/usermanuals/tr/operations/docker.md:106-107) · type: broken example
  The document says. RUN forgelm cache-tasks --tasks hellaswag,... inside an image built from the default image.
  What the code does. cache-tasks needs lm-eval ([eval]), which the default build does not install (INSTALL_EVAL=false).
  Code references. Dockerfile:58-61, forgelm/cli/subcommands/_cache.py:394-415
  Proposed correction. Build the base with --build-arg INSTALL_EVAL=true before running cache-tasks.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-061 (docs, Low) — docs/usermanuals/en/operations/iso-soc2-deployer.md: wrong detail — bandit CI "for static + dynamic security scanning".
  severity Low
  Where. docs/usermanuals/en/operations/iso-soc2-deployer.md:17 (Turkish mirror: docs/usermanuals/tr/operations/iso-soc2-deployer.md:17) · type: wrong detail
  The document says. bandit CI "for static + dynamic security scanning".
  What the code does. bandit is a static analyser. The workflows run no dynamic security scanning.
  Code references. .github/workflows/ci.yml:511-524, .github/workflows/nightly.yml:330-335
  Proposed correction. "bandit static security analysis in CI and nightly."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-062 (docs, Low) — docs/usermanuals/en/operations/supply-chain.md: wrong detail — pip-audit --strict ...; python3 tools/check_pip_audit.py (local review artefact) is "the same check ForgeLM's nightly enforces".
  severity Low
  Where. docs/usermanuals/en/operations/supply-chain.md:41-47 (Turkish mirror: docs/usermanuals/tr/operations/supply-chain.md:41-47) · type: wrong detail
  The document says. pip-audit --strict ...; python3 tools/check_pip_audit.py (local review artefact) is "the same check ForgeLM's nightly enforces".
  What the code does. Nightly runs pip-audit --format json --output ... without --strict and passes --ignores tools/pip_audit_ignores.yaml. The local mirror differs on both points.
  Code references. .github/workflows/nightly.yml:310-328
  Proposed correction. Show the nightly form, or state the two differences explicitly.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-063 (docs, Low) — docs/usermanuals/en/operations/supply-chain.md: misleading — See also: Air-gap Pre-cache, "pre-caching deps for SBOM determinism".
  severity Low
  Where. docs/usermanuals/en/operations/supply-chain.md:98 (Turkish mirror: docs/usermanuals/tr/operations/supply-chain.md:98) · type: misleading
  The document says. See also: Air-gap Pre-cache, "pre-caching deps for SBOM determinism".
  What the code does. The air-gap page covers HF model and dataset caches (cache-models, cache-tasks). It offers no dependency pre-cache tooling, and SBOM determinism does not depend on it. The SBOM was verified identical across two emissions apart from serialNumber and timestamp.
  Code references. forgelm/cli/subcommands/_cache.py:243-344, tools/generate_sbom.py:99-121
  Proposed correction. "— pre-caching models and eval datasets for offline hosts."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-064 (docs, Low) — docs/usermanuals/en/operations/webhooks.md: wrong detail — training.start fires when "train() enters, before model load".
  severity Low
  Where. docs/usermanuals/en/operations/webhooks.md:42 (Turkish mirror: docs/usermanuals/tr/operations/webhooks.md:42) · type: wrong detail
  The document says. training.start fires when "train() enters, before model load".
  What the code does. The CLI loads the model and prepares the dataset first. notify_start fires inside train() after both.
  Code references. forgelm/cli/_training.py:141-149, forgelm/trainer.py:1669
  Proposed correction. "train() enters, after the model and dataset are loaded."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-065 (docs, Low) — docs/usermanuals/en/operations/webhooks.md: misleading — training.success: All gates pass; no human-approval requirement.
  severity Low
  Where. docs/usermanuals/en/operations/webhooks.md:43 · type: misleading
  The document says. training.success: All gates pass; no human-approval requirement.
  What the code does. With the default auto_revert: false, training.success also fires after a failed gate (the reference doc says so at webhook_schema.md:46).
  Code references. forgelm/trainer.py:1486-1489
  Proposed correction. Mirror webhook_schema.md:46.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-067 (docs, Low) — docs/usermanuals/en/operations/webhooks.md: false claim — url_env: Env-var name carrying the URL. Overrides url when set.
  severity Low
  Where. docs/usermanuals/en/operations/webhooks.md:100; forgelm/config.py:1469 · type: false claim
  The document says. url_env: Env-var name carrying the URL. Overrides url when set.
  What the code does. webhook.url wins. url_env is read only when url is empty.
  Code references. forgelm/webhook.py:80-82, docs/reference/webhook_schema.md:19 (states the correct precedence)
  Proposed correction. 'Used only when url is unset' in both the manual and the Field description.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B04B-038 (docs, Low) — docs/usermanuals/en/operations/troubleshooting.md: misleading — For fp16 gradient overflow, 'Switch to bfloat16: model.bnb_4bit_compute_dtype: "bfloat16"'.
  severity Low
  Where. docs/usermanuals/en/operations/troubleshooting.md:49 (Turkish mirror: docs/usermanuals/tr/operations/troubleshooting.md:49) · type: misleading
  The document says. For fp16 gradient overflow, 'Switch to bfloat16: model.bnb_4bit_compute_dtype: "bfloat16"'.
  What the code does. bnb_4bit_compute_dtype affects only the 4-bit QLoRA compute dtype (forgelm/config.py:294-297). Training mixed precision is chosen automatically, bf16 if supported else fp16 (forgelm/trainer.py:516-517), so on a GPU without bf16 this key does not remove fp16 training.
  Code references. forgelm/config.py:294-297, forgelm/trainer.py:516-517
  Proposed correction. Clarify: with 4-bit loading set model.bnb_4bit_compute_dtype: "bfloat16"; the trainer itself uses bf16 automatically on bf16-capable GPUs (fp16 otherwise) — on fp16-only GPUs lower the learning rate.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B04B-039 (docs, Low) — docs/usermanuals/en/operations/troubleshooting.md: wrong detail — Reduce epochs; add neftune_noise_alpha: 5.0.
  severity Low
  Where. docs/usermanuals/en/operations/troubleshooting.md:58-59 (Turkish mirror: docs/usermanuals/tr/operations/troubleshooting.md:58-59) · type: wrong detail
  The document says. Reduce epochs; add neftune_noise_alpha: 5.0.
  What the code does. The keys are training.num_train_epochs and training.neftune_noise_alpha (config introspection). A bare top-level neftune_noise_alpha or training.epochs fails validation.
  Code references. forgelm/config.py:443
  Proposed correction. Reduce training.num_train_epochs …; add training.neftune_noise_alpha: 5.0.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B04B-040 (docs, Low) — docs/usermanuals/en/operations/troubleshooting.md: wrong detail — The error reads audit_log.jsonl chain hash invalid; fix by re-running training.
  severity Low
  Where. docs/usermanuals/en/operations/troubleshooting.md:140-144 (Turkish mirror: docs/usermanuals/tr/operations/troubleshooting.md:140-144) · type: wrong detail
  The document says. The error reads audit_log.jsonl chain hash invalid; fix by re-running training.
  What the code does. The verifier reports 'chain broken at line N: prev_hash=... expected=...' (forgelm/compliance.py:2567). Detection is through forgelm verify-audit, which exits 6 on tampering. The page does not mention the verifier.
  Code references. forgelm/compliance.py:2567, forgelm/cli/_parser.py:701-714
  Proposed correction. Title: forgelm verify-audit reports 'chain broken at line N' (exit 6). Fix: treat as a tamper/integrity incident; keep the file for forensics; artifacts from that run are not trustworthy.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B06-032 (docs, Low) — docs/usermanuals/en/operations/experiment-tracking.md: broken example — "a small jq over each run's JSON envelope": jq '{… hellaswag: .benchmark.hellaswag, … S5_max: .safety.S5}' runs/$v/eval.json… severity **Low** **Where.** [docs/usermanuals/en/operations/experiment-tracking.md:110-119](https://github.com/HodeTech/ForgeLM/blob/cab2947/docs/usermanuals/en/operations/experiment-tracking.md#L110-L119) (Turkish mirror: [docs/usermanuals/tr/operations/experiment-tracking.md:117](https://github.com/HodeTech/ForgeLM/blob/cab2947/docs/usermanuals/tr/operations/experiment-tracking.md#L117)) · type: broken example **The document says.** "a small jqover each run's JSON envelope":jq '{… hellaswag: .benchmark.hellaswag, … S5_max: .safety.S5}' runs/$v/eval.json. **What the code does.** ForgeLM writes no eval.json. The JSON envelope nests scores as .benchmark.scores.and safety as.safety.categories (forgelm/cli/_result.py:33-50), so the paths shown return null. **Code references.** [forgelm/cli/_result.py:9-50](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/cli/_result.py#L9-L50) **Proposed correction.** Capture the envelope (forgelm --config … --output-format json > runs/$v/result.json) and use .benchmark.scores.hellaswagand.safety.categories`.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B06-033 (docs, Low) — docs/usermanuals/en/operations/gpu-cost.md: misleading — fit-check "runs alongside cost estimation"; the Configuration Reference holds the "full cost_tracking block".
  severity Low
  Where. docs/usermanuals/en/operations/gpu-cost.md:153,155 (Turkish mirror: docs/usermanuals/tr/operations/gpu-cost.md) · type: misleading
  The document says. fit-check "runs alongside cost estimation"; the Configuration Reference holds the "full cost_tracking block".
  What the code does. There is no pre-flight cost estimation, and cost_tracking does not exist in the schema (output is rejected as extra_forbidden; this audit).
  Code references. forgelm/config.py:1604-1650
  Proposed correction. Link to training.gpu_cost_per_hour instead of a cost_tracking block.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B06-034 (docs, Low) — docs/usermanuals/en/operations/vram-fit-check.md: misleading — fit-check answers "in seconds" versus "a 5-minute fit-check".
  severity Low
  Where. docs/usermanuals/en/operations/vram-fit-check.md:8,147 (Turkish mirror: docs/usermanuals/tr/operations/vram-fit-check.md:147) · type: misleading
  The document says. fit-check answers "in seconds" versus "a 5-minute fit-check".
  What the code does. The page contradicts itself; the estimator does only arithmetic plus one AutoConfig fetch (fit_check.py:344-415).
  Code references. forgelm/fit_check.py:344-415
  Proposed correction. "A few-second fit-check saves you…"
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

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.}