docs/reference/usage.md: broken example — Multi-GPU: docker run --gpus all --shm-size=16g forgelm torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml. (DOC-D1B02-003) #157

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

Summary

The documented multi-GPU container command fails immediately.

Primary finding

DOC-D1B02-003 — docs/reference/usage.md: broken example — Multi-GPU: docker run --gpus all --shm-size=16g forgelm 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/usage.md:387-389 (Turkish mirror: docs/reference/usage-tr.md) · type: broken example

The document says. Multi-GPU: docker run --gpus all --shm-size=16g forgelm torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml.

What the code does. The image sets ENTRYPOINT ["forgelm"], so the arguments after the image name are passed to forgelm. The command becomes forgelm torchrun ... and argparse exits with "invalid choice: 'torchrun'" (reproduced). The torchrun form needs --entrypoint torchrun.

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

User impact. The documented multi-GPU container command fails immediately.

Proposed correction. Use: docker run --gpus all --shm-size=16g --entrypoint torchrun forgelm --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml.

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