Deploy docs and --help misdescribe the Hub-ID rule and TGI/ollama outputs (CR-A05-004) #435

Wave 1 · theme D1-8: Docs describing features that do not exist (doc side of code findings) · highest severity High · 1 finding(s) · effort small

Summary

An operator follows the TGI docs (--output tgi/) and gets exit 2, or trusts --help and passes a Hub ID to tgi and gets exit 1.

Primary finding

CR-A05-004 — Deploy docs and --help misdescribe the Hub-ID rule and TGI/ollama outputs

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN CLI-10 — docs/roadmap/phase-16-trust-surface-hardening.md:613-622,624-625 (S11 open; unit id inferred from exit ordering)

What happens. The parser help for model_path reads 'Path to a saved HuggingFace model directory or HF Hub ID.' (forgelm/cli/_parser.py:113). It does not say that tgi and ollama reject Hub IDs (forgelm/deploy.py:274-282). docs/usermanuals/en/deployment/deploy-targets.md:28 and :86-106 say the tgi target emits launcher.sh, Dockerfile and config.json into a directory (--output tgi/). The code writes a single docker-compose.yaml (forgelm/deploy.py:36-41, :153-180), and --output tgi/ fails with FileNotFoundError, exit 2. The ollama and vllm sample outputs (:39-80) show content the generators never emit: stop tokens picked from the tokenizer, served_model_name, tokenizer_mode, and tensor-parallel sizing. A further possible defect is uncertain: the ollama Modelfile writes FROM <model_path> verbatim (deploy.py:98), validated relative to the CWD, whereas tgi absolutises its path (deploy.py:166). If Ollama resolves relative FROM paths against the Modelfile's directory (an outside fact this review could not check), then --output deploy/Modelfile with ./model yields a broken FROM.

Where.

• forgelm/cli/_parser.py:113
• docs/usermanuals/en/deployment/deploy-targets.md:39-83
• docs/usermanuals/en/deployment/deploy-targets.md:39-106
• forgelm/deploy.py:36-41
• forgelm/deploy.py:98
• forgelm/deploy.py:153-180 (_tgi_compose)
• forgelm/deploy.py:274-282 (Hub-ID rejection for tgi and ollama)
• forgelm/deploy.py:309-311
• docs/usermanuals/en/deployment/deploy-targets.md:86-106
• docs/usermanuals/tr/deployment/deploy-targets.md:28

Evidence.

• fpy -m forgelm deploy ./model --target tgi --output tgi/ gave '[Errno 2] No such file or directory: tgi/' and EXIT=2. deploy ./model --target ollama --output deploy/Modelfile wrote 'FROM ./model'.

Recommended fix. Fix the help text and rewrite deploy-targets.md to match the generators. Absolutise the ollama FROM path, or write it relative to the Modelfile.

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