docs/reference/distributed_training.md: broken example — docker run --gpus all ... forgelm:full torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml (DOC-D1B03-004) #159

Wave 1 · theme D1-10: Documentation-only fixes · highest severity High · 1 finding(s) · effort docs fix

Summary

The only documented Docker multi-GPU invocation exits at argument parsing and never starts training.

Primary finding

DOC-D1B03-004 — docs/reference/distributed_training.md: broken example — docker run --gpus all ... forgelm:full torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml

severity High · already tracked: KNOWN-OPEN C31-DOCKER-RUNBOOK — docs/roadmap/phase-16-trust-surface-hardening.md:691-692

Where. docs/reference/distributed_training.md:195-201 (Turkish mirror: docs/reference/distributed_training-tr.md (section 'Docker + Multi-GPU' / Docker + Çoklu-GPU)) · type: broken example

The document says. docker run --gpus all ... forgelm:full torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml

What the code does. The image sets ENTRYPOINT ["forgelm"] (Dockerfile:112), so everything after the image name is passed to the forgelm CLI. Verified with the installed package: 'forgelm torchrun --nproc_per_node=4 -m forgelm.cli --config ...' fails with 'argument COMMAND: invalid choice: torchrun'. The command needs --entrypoint torchrun, and the image would also need --entrypoint to run python -m forgelm.cli under torchrun.

Code references. Dockerfile:112-113, forgelm/cli/_parser.py (subcommand choices)

User impact. The only documented Docker multi-GPU invocation exits at argument parsing and never starts training.

Proposed correction. Use: docker run --gpus all --shm-size=16g --entrypoint torchrun -v $(pwd)/my_config.yaml:/workspace/config.yaml forgelm:full --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml (and see the next finding on the image content).

Turkish mirror. the Turkish page has the same error; fix both in the same PR

Acceptance criteria

• Each statement is re-checked against the code at fix time.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.

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