docs/usermanuals/en/operations/air-gap.md: broken example — Pre-cache with forgelm cache-models ... --output ./airgap-bundle/ and forgelm cache-tasks ... --output ./airgap-bundle/, then on the ho… (DOC-D3B02-014) #215

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

Summary

On the isolated host no model or dataset is found and the offline run fails, after the transfer has already been done.

Primary finding

DOC-D3B02-014 — docs/usermanuals/en/operations/air-gap.md: broken example — Pre-cache with forgelm cache-models ... --output ./airgap-bundle/ and forgelm cache-tasks ... --output ./airgap-bundle/, then on the ho…

severity High

Where. docs/usermanuals/en/operations/air-gap.md:24-45,102 (Turkish mirror: docs/usermanuals/tr/operations/air-gap.md:24-45,102) · type: broken example

The document says. Pre-cache with forgelm cache-models ... --output ./airgap-bundle/ and forgelm cache-tasks ... --output ./airgap-bundle/, then on the host export HF_HOME="$(pwd)/airgap-bundle/huggingface". The cache is "picked up automatically".

What the code does. --output is the cache dir itself. cache-models calls snapshot_download(cache_dir=./airgap-bundle/), writing models--* directly there. cache-tasks sets HF_DATASETS_CACHE=./airgap-bundle/. With HF_HOME=airgap-bundle/huggingface, HF reads airgap-bundle/huggingface/hub and airgap-bundle/huggingface/datasets, neither of which exists. The command itself warns about this divergence.

Code references. forgelm/cli/subcommands/_cache.py:138-160, forgelm/cli/subcommands/_cache.py:185-220, forgelm/cli/subcommands/_cache.py:259, forgelm/cli/subcommands/_cache.py:338

User impact. On the isolated host no model or dataset is found and the offline run fails, after the transfer has already been done.

Proposed correction. Pre-cache with --output ./airgap-bundle/hub (models) and --output ./airgap-bundle/datasets (tasks); on the host export HF_HOME="$(pwd)/airgap-bundle" (or set HF_HUB_CACHE and HF_DATASETS_CACHE to those two directories).

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