Sample doctor output in first-run.md (EN+TR) and site/quickstart.html does not match the renderer: Unicode glyphs, 'Installed' extras wording, 9 of 19 rows (CR-A18-080) #534

Wave 2 · theme D2-7: Next-release technology updates · highest severity Medium · 7 finding(s) · effort trivial

Summary

An operator who greps CI logs for '✓ pass' or 'Installed (' as the first-run page shows matches nothing, and reads 'Installed' as a stronger guarantee than doctor gives.

Primary finding

CR-A18-080 — Sample doctor output in first-run.md (EN+TR) and site/quickstart.html does not match the renderer: Unicode glyphs, 'Installed' extras wording, 9 of 19 rows

severity Low · reachability default · intent contract-violation · confidence likely · independently confirmed · reproduced end to end

What happens. first-run.md:33-45 (TR identical) shows the header 'forgelm doctor — environment check' with an em-dash and '[✓ pass]' glyphs. The renderer prints the ASCII 'forgelm doctor - environment check' with '+ / ! / x' glyphs (_doctor.py:1072-1104), deliberately, for strict-ASCII locales. Passing extras are shown as 'Installed (module bitsandbytes, ...)'; the code prints 'Discoverable, not import-tested (module ...)' (_doctor.py:441), wording that was changed so a pass would not over-promise. The sample has 9 rows and 'Summary: 7 pass, 2 warn', but real output always has 19 rows (forgelm.install, numpy.torch_abi, pypdf_normalise.turkish and 7 extras are missing). The hub row omits 'at ' (_doctor.py:535). site/quickstart.html:220-221 shows a one-line '✓ Python 3.11.7 · CUDA 12.1 · bitsandbytes ok · disk 142 GB free' output that no renderer produces. Separately, troubleshooting.md:8 (TR :8 '%80') says doctor 'catches 80% of environment problems', a figure with no measurement behind it. Verdict: doc-drift (samples), overclaim (80%). This extends M-A15-015's 'importable' point to a different surface; it is not a re-raise.

Where.

• docs/usermanuals/en/getting-started/first-run.md:31-45
• docs/usermanuals/tr/getting-started/first-run.md:31-45
• site/quickstart.html:219-220
• docs/usermanuals/en/operations/troubleshooting.md:8
• docs/usermanuals/tr/operations/troubleshooting.md:8
• forgelm/cli/subcommands/_doctor.py:441
• forgelm/cli/subcommands/_doctor.py:1095
• forgelm/cli/subcommands/_doctor.py:535
• forgelm/cli/subcommands/_doctor.py:1074-1078

Evidence.

• Renderer header literal at _doctor.py:1095: "forgelm doctor - environment check". Pass detail at :441: "Discoverable, not import-tested (module {module}, purpose: {purpose})." The real run printed 19 rows.

Recommended fix. Regenerate the samples from a real run (ASCII glyphs, all 19 rows, current wording) and drop the 80% figure.

Other findings with the same root cause

These close with the same fix; update them in the same pull request.

• TECH-T13-010 (technology, Next release) — Python, platform, CI, container and GPU prices: Docs doctor transcripts (torch 2.4.0 with CUDA 12.4, numpy 1.26.4), cu121 reinstall hint, site demo 'CUDA 12.1' (outdated)
  severity Next release
  Item. Docs doctor transcripts (torch 2.4.0 with CUDA 12.4, numpy 1.26.4), cu121 reinstall hint, site demo 'CUDA 12.1' · verdict: outdated · urgency: Next release
  State in ForgeLM. 'torch 2.4.0 with CUDA 12.4.' at docs/reference/doctor_subcommand.md:88, docs/guides/getting-started.md:49 (numpy 1.26.4 at :50), docs/guides/air_gap_deployment.md:109-110, docs/usermanuals/en/getting-started/first-run.md:36, docs/usermanuals/en/operations/air-gap.md:111, all TR mirrors at the same lines. cu121 hint at docs/usermanuals/en/getting-started/installation.md:145 and docs/usermanuals/e…
  State of the ecosystem on 2026-10-01. Latest torch 2.14.1; its CUDA variants are cu126, cu130 (PyPI default, CUDA 13.0.3) and cu132, plus rocm7.2, rocm7.14, xpu and cpu. Arbiter parse of the download.pytorch.org index: the last torch built for cu121 is 2.5.1, for cu124 2.6.0, for cu128 2.11.0, for cu129 2.13.0. transformers >=5.15.0 disables torch < 2.5 at runtime, so the transcript's torch 2.4.0 pairing no longer works with a fresh…
  Recommendation. Regenerate the transcripts from a real current doctor run (or neutral placeholders); change the hint to cu126 / cu130 with 'match your driver (>=580 for CUDA 13)'; update site/quickstart.html:221; run the doc guards after the change.
  Sources.

  • PyTorch wheel index for torch (latest per variant: cu121 2.5.1, cu124 2.6.0, cu128 2.11.0, cu126/cu130/cu132/rocm7.2/ro… (2026-10-01)
  • PyTorch RELEASE.md (compatibility matrix, CUDA architectures, Python policy, release cadence) (2026-10-01 (main))

• DOC-D4B08-020 (docs, Medium) — site/quickstart.html: misleading — Install steps (pip install forgelm==0.11.0 plus ingestion/ingestion-scale/export extras) then train the template; the doctor mock shows 'bitsandbytes ok'.
  severity Medium
  Where. site/quickstart.html:212-221 · type: misleading
  The document says. Install steps (pip install forgelm==0.11.0 plus ingestion/ingestion-scale/export extras) then train the template; the doctor mock shows 'bitsandbytes ok'.
  What the code does. The quickstart templates set model.load_in_4bit: true (generated config). On a CUDA host the loader builds a BitsAndBytesConfig (forgelm/model.py:439-448), which needs bitsandbytes. bitsandbytes ships only in the [qlora] extra (pyproject.toml:73-75), which the page never installs. Not reproduced on CUDA (no GPU in this lane); this is reasoned from the code.
  Code references. forgelm/model.py:439-448, pyproject.toml:73-75
  Proposed correction. Add the line: $ pip install 'forgelm[qlora]==0.11.0' # 4-bit QLoRA (Linux + CUDA; templates default to load_in_4bit)

• DOC-BLEGAL-236 (docs, Low) — docs/usermanuals/en/operations/troubleshooting.md: stale — [IS-T13-07] '$ pip install torch --index-url https://download.pytorch.org/whl/cu121 # match your CUDA'
  severity Low
  Where. docs/usermanuals/en/operations/troubleshooting.md:30 (Turkish mirror: docs/usermanuals/tr/operations/troubleshooting.md:30) · type: stale
  The document says. [IS-T13-07] '$ pip install torch --index-url https://download.pytorch.org/whl/cu121 # match your CUDA'
  What the code does. The cu121 index ends at torch 2.5.1; current builds are cu126/cu130/cu132.
  Proposed correction. $ pip install torch --index-url https://download.pytorch.org/whl/cu126 # match your CUDA (cu126 / cu130 / cu132)
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B02-068 (docs, Low) — docs/usermanuals/en/operations/air-gap.md: wrong detail — Offline doctor sample with [✓ pass] glyphs, em-dash header and 'Installed (module ...)' details
  severity Low
  Where. docs/usermanuals/en/operations/air-gap.md:108-121 (Turkish mirror: docs/usermanuals/tr/operations/air-gap.md) · type: wrong detail
  The document says. Offline doctor sample with [✓ pass] glyphs, em-dash header and 'Installed (module ...)' details
  What the code does. Same divergence as first-run.md. The real output uses [+ pass] and an ASCII header, the extras detail is 'Discoverable, not import-tested ...', and a forgelm.install row comes first (_doctor.py:441,1073-1099).
  Code references. forgelm/cli/subcommands/_doctor.py:441,1073-1099
  Proposed correction. Regenerate the sample from a real forgelm doctor --offline run.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D3B04B-021 (docs, Low) — docs/usermanuals/en/getting-started/first-run.md: wrong detail — Sample doctor output with ✓ glyphs, the header 'forgelm doctor — environment check', 9 rows, extras.qlora 'Installed (...)' and 'Summa…
  severity Low
  Where. docs/usermanuals/en/getting-started/first-run.md:32-45 (Turkish mirror: docs/usermanuals/tr/getting-started/first-run.md:35-42) · type: wrong detail
  The document says. Sample doctor output with ✓ glyphs, the header 'forgelm doctor — environment check', 9 rows, extras.qlora 'Installed (...)' and 'Summary: 7 pass, 2 warn'.
  What the code does. The renderer uses ASCII glyphs +/!/x and the header 'forgelm doctor - environment check' (forgelm/cli/subcommands/_doctor.py:1071-1101). A pass on an extra reads 'Discoverable, not import-tested (...)' (_doctor.py:441). Output always has 19 rows, including forgelm.install, numpy.torch_abi, all 10 extras and pypdf_normalise.turkish (_doctor.py:993-1020).
  Code references. forgelm/cli/subcommands/_doctor.py:1071-1101, forgelm/cli/subcommands/_doctor.py:993-1020
  Proposed correction. Regenerate the sample from a real forgelm doctor run.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D4B08-032 (docs, Low) — site/quickstart.html: wrong detail — Mock terminal outputs: doctor '✓ Python 3.11.7 · CUDA 12.1 · bitsandbytes ok · disk 142 GB free'; quickstart --list one-line rows; fit-check 'FITS est. peak 11.4…
  severity Low
  Where. site/quickstart.html:221, 239-243, 301 · type: wrong detail
  The document says. Mock terminal outputs: doctor '✓ Python 3.11.7 · CUDA 12.1 · bitsandbytes ok · disk 142 GB free'; quickstart --list one-line rows; fit-check 'FITS est. peak 11.4 GB / 12 GB available'.
  What the code does. Real formats: doctor prints '[+ pass] ' rows plus a Summary line (I ran it). quickstart --list prints 'Available quickstart templates:' then three lines per template (title — description, primary/fallback/trainer/~min/bundled), in the order customer-support, code-assistant, domain-expert, medical-qa-tr, grpo-math (forgelm/quickstart.py:509-521). fit-check prints 'Estimated peak:…
  Code references. forgelm/quickstart.py:509-521, forgelm/fit_check.py:483-488
  Proposed correction. Paste real (abridged) outputs, or mark the blocks '# abridged / illustrative output'.

Acceptance criteria

• A regression test reproduces the failure scenario and asserts the corrected behaviour.
• 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.}