Guide: driving ForgeLM from another program (process model, exit codes, audit log, events) #1033

Embeddable engine · EMB-06 · Kind: docs (English and Turkish) · Size S · background: #1027

Summary

ForgeLM already offers most of what a calling program needs: public exit codes, a JSON result envelope, an append-only audit log, --dry-run, --fit-check and doctor. None of it is described from the point of view of a program that spawns ForgeLM. This issue writes that guide, and records the architecture decision in the project documents. Writing it first is deliberate: it will expose the remaining gaps (and feed EMB-01 to EMB-05) before any front-end depends on them.

Content of docs/guides/embedding.md (and embedding-tr.md)

1. Process model. Run ForgeLM as a child process in its own Python environment (python -m forgelm …), not as an in-process import of a GUI or server process: the install pulls in torch, and a sidecar environment keeps the host application small and restartable. Library import remains right for notebooks and orchestrators (library API guide).
2. YAML is the source of truth. The calling program generates or edits a config file and passes --config; it validates with --dry-run first and checks hardware fit with --fit-check; forgelm doctor --output-format json reports the environment.
3. Reading the result. The --output-format json envelope, the fields to rely on, and the stdout caveat that holds until Training --output-format json stdout is not a JSON document: print_trainable_parameters and HF Trainer log dicts precede the envelope (CR-A03-008) #412 is fixed (parse the last JSON object).
4. The exit-code contract, 0 to 6, with the 1-versus-6 distinction for verifiers and what to alarm on (error-handling.md).
5. The audit log as a read-only source. Append-only, hash-chained; a calling program never writes to it, reads by byte offset, tolerates a torn last line, and uses forgelm verify-audit for integrity (EMB-03 defines the concurrent-reader contract).
6. Observing a run (EMB-01) and stopping a run (EMB-02): until they land, say what to do (poll the process, hard kill and its consequences); after they land, document the file schema and the control file.
7. Approvals. Exit code 4, forgelm approvals, approve and reject, and the staging directory.
8. Offline and secrets. --offline, forgelm cache-models; tokens and FORGELM_AUDIT_SECRET through the environment, never on a command line or in the YAML.
9. One output directory per run, and what is safe to share on each platform (Windows until EMB-03 lands).
10. Version pinning. __version__ versus __api_version__, the library stability tiers, and that the JSON and event schemas carry versions.
11. Platform notes. What is tested where, and the support tier from EMB-05 once it exists.

Decision record (same pull request)

• One sentence in product_strategy.md under "What ForgeLM Is NOT": front-ends are separate programs built on ForgeLM and live in other repositories.
• A dated row in docs/roadmap/risks-and-decisions.md recording the owner's decision of 2026-10-20 (ForgeLM stays headless; the engine never depends on a front-end) and the six EMB issues as its consequences.
• The Turkish mirror of the strategy sentence in docs/product_strategy-tr.md. Sub-files of docs/roadmap/ are English-only (localization.md), so the decision row has no mirror.
• Phase 13. The Pro dashboard is still planned inside ForgeLM: task 2 of phase-13-pro-cli.md (forgelm pro dashboard, FastAPI + HTMX), the Phase 13 row and diagram node in docs/roadmap.md and docs/roadmap-tr.md, and the two sentences in product_strategy.md saying the "Pro CLI will add a dashboard for paying users" (What ForgeLM Is NOT and Strategic Decision 2) with their Turkish mirrors. Reconcile them with the decision: the dashboard becomes one of the separate applications built on ForgeLM, and any engine-side need it implies enters the core only as a general CLI or library feature (principle 1 of [Epic] Embeddable engine: stable contracts for front-ends, orchestrators and CI dashboards that drive ForgeLM #1027).

Acceptance criteria

• docs/guides/embedding.md and docs/guides/embedding-tr.md exist with the eleven sections above, structurally identical (tools/check_bilingual_parity.py --strict).
• Every command, flag and field in the guide is real: tools/check_cli_help_consistency.py, check_yaml_snippets.py, check_anchor_resolution.py and check_doc_numerical_claims.py pass in --strict mode.
• Sections that depend on EMB-01 to EMB-03 state the current behaviour and name the issue; they are rewritten when those issues land (a checklist line on each of them).
• The strategy sentence exists in English and Turkish; the decision row exists in docs/roadmap/risks-and-decisions.md (English-only under the localization standard).
• No roadmap or strategy document still plans a UI inside ForgeLM: Phase 13's dashboard task, its docs/roadmap.md / docs/roadmap-tr.md row and diagram node, and the two product_strategy.md sentences (with their Turkish mirrors) are reconciled with the decision in the same pull request.
• The guide is linked from the README documentation list and from the library API guide, and tools/check_readme_links.py --strict still passes.
• No claim in the guide is untested: each statement about exit codes, envelope fields and the audit log has a test or a CI guard behind it, or is marked as a convention.

Sequencing and dependencies

Stage A of #1027: a first version can be written now, because it documents contracts that exist. Re-open it as EMB-01, EMB-02 and EMB-03 land. It depends on nothing but #412 for one caveat.

Related

#412 (stdout is not a JSON document), #415 (the same caveat for forgelm quickstart --output-format json: the training child inherits stdout), #400 (distributed launchers collapse exit codes 2–6 into 1; the exit-code section must say so until it is fixed), #901 (S15: documentation claims bound to code), #902 (S16: documentation governance).

_{Raised on 2026-10-20 as part of the embeddable-engine decision. Links point at 2059b59. Tracking ID: EMB-06.}