# Documentation guide

Start at the [repository README](../README.md) for the CPU quickstart, workflow
selection and current results. This index covers the complete recipe collection.
Run examples from the repository root and use fresh output paths. Individual
guides specify which optional environment and hardware their commands require.
The [programme status](programme-status.md) provides the implementation/gaps map;
the [environment framework comparison](environment-frameworks.md) explains
OpenEnv, NeMo Gym and the difference between a harness and a resource server.

## Learn and run

| Topic | Guide | Executable examples and inputs |
| --- | --- | --- |
| Evaluation kit and regression checks | [Evaluation](evaluation.md) | [Core CLI](../src/hessian_recipes/cli.py), [development specifications](../benchmarks/README.md), [real CPU generation smoke](../examples/evaluation_cpu_smoke.py). |
| Existing evaluator SDK | [Inspect integration](evaluation.md#inspect-integration) | [Inspect task/scorer](../src/hessian_recipes/inspect_tasks.py), [dependency snapshot](../requirements/inspect.txt). |
| Reasoning adaptation | [Training](training.md) | [SFT recipe](../recipes/reasoning-sft.json), [GRPO recipe](../recipes/reasoning-grpo.json), [CPU trainer smoke](../examples/training/cpu_smoke.py). |
| Offline sequence distillation | [Teacher generation and filtering](training.md#distillation-without-a-hosted-teacher) | [Generation recipe](../recipes/teacher-generation.json), [teacher-sequence fixtures](../examples/training/teacher_sequences.jsonl). |
| German Qwen SFT | [End-to-end use case](use-cases/german-reasoning.md) | [Data notes](../examples/german-reasoning/DATA.md), [data preparation](../src/hessian_recipes/german_data.py), [pilot driver](../src/hessian_recipes/german_pilot.py). |
| German Qwen multi-turn RL | [Agent-RL use case](use-cases/german-agent-rl.md) | [Bounded environment/verifier](../src/hessian_recipes/agent_rl_tasks.py), [pilot driver](../src/hessian_recipes/agent_rl_pilot.py), [verified summary tool](../src/hessian_recipes/agent_rl_report.py). |
| Native NeMo Gym | [Gym setup and TRL bridge](agent-gyms.md#nemo-gym-with-online-trl) | [Resource server](../examples/agent_gyms/nemo_gym_server.py), [service smoke](../examples/agent_gyms/nemo_gym_smoke.py), [client smoke](../examples/agent_gyms/nemo_gym_client_smoke.py), [online trainer](../src/hessian_recipes/gym_training.py). |
| Longer NeMo Gym experiment | [Frozen protocol and recovery](use-cases/german-nemo-long-run.md) | [Experiment driver](../src/hessian_recipes/gym_experiment.py), [sealed native checkpoints](../src/hessian_recipes/gym_training_long.py), [DEV selection and final assessment](../src/hessian_recipes/gym_experiment_evaluation.py); the 20 October GPU resume attempt failed its token audit. Fresh JAIF plans and qualification are required. |
| Matched native OpenEnv experiment | [Protocol, tutorial compatibility and sequencing](use-cases/german-openenv-comparison.md) | [SDK client](../src/hessian_recipes/openenv_client.py), [training bridge](../src/hessian_recipes/openenv_training.py), [experiment driver](../src/hessian_recipes/openenv_experiment.py), [native service](../examples/agent_gyms/openenv_server.py) and [sequential queue controller](../scripts/run-openenv-after-nemo.py). CPU-qualified; the 20 October GPU resume attempt failed its token audit. No longer-run quality result is available. |
| Native Prime Intellect Verifiers | [Verifiers setup](agent-gyms.md#prime-intellect-verifiers) | [Loadable environment](../examples/agent_gyms/verifiers_environment.py), [explicit scripted smoke](../examples/agent_gyms/verifiers_smoke.py), [dependency pins](../requirements/verifiers.txt). |
| An existing team's harness | [Trajectory contract and adoption](agent-harness.md) | [Callable example](../examples/agent_harness.py), [Agent Lightning recipe](../recipes/agent-lightning.json), [optional launcher](../examples/agent_lightning/launch.py). |
| LoRA checkpoint merging | [Merge guide](training.md#merge-a-local-lora-adapter-for-evaluation) | [Explicit local base/adapter merge](../src/hessian_recipes/checkpoints.py). |

The generic training fixtures verify integration. The German SFT and agent-RL
guides contain the actual local-model experiments. Gym qualification has its own
evidence; Lightning and native Prime-RL GPU training are separate, unqualified
paths. A validated trajectory file is not automatically a trainer input.

## Evidence and current status

- [Current validation overview](validation.md): software checks, hardware runs,
  practical limits and repeat commands. Its linked `validation.json` describes the
  historical foundation, rather than the later GPU experiments.
- [German SFT results](use-cases/german-reasoning-results.md) and
  [aggregate JSON](use-cases/german-reasoning-results.json): matched MGSM outcomes,
  language/format inspection, resource use and saved artifacts.
- [German agent-RL results](use-cases/german-agent-rl-results.md) and
  [aggregate JSON](use-cases/german-agent-rl-results.json): strict tool-workflow
  outcomes, mathematical retention regression and full provenance.
- [Gym integration guide](agent-gyms.md) and
  [aggregate validation](agent-gyms-validation.json): native CPU checks plus the
  NeMo Gym A100 update qualification, without a new held-out quality claim.
- [Roadmap and acceptance criteria](roadmap.md): remaining quality, partner
  adoption, benchmark, service, domain and publication work.

Full data, model outputs, adapters and weights live in ignored `runs/` directories;
they are not downloaded by opening this documentation or cloning the repository.
The results name their local artifact directories and model cards. Reproduction
requires access to the documented model/data sources and suitable hardware.

## Programme, infrastructure and publication

| Element | Reference | Current boundary |
| --- | --- | --- |
| Architecture and provenance | [Architecture](architecture.md) | Common configuration/evidence contracts with upstream optimization and environment backends. |
| Academic and industrial related work | [Reuse map](related-work.md) | Adopted components, integration pins, candidate systems and research extensions. |
| Two open benchmarks | [Proposed designs and existing benchmarks](benchmark-designs.md), [development tracks](../benchmarks/README.md) | German RAG with cited evidence and business-communication agent sequences are the proposed topics; current fixtures remain plumbing, with expert data/scorers and released benchmarks still pending. |
| Evaluation kit → service | [Remaining service work](evaluation.md#regression-gate-and-remaining-release-work), [roadmap](roadmap.md) | Local kit exists; managed service execution has not been built. |
| Robotics, Bio/Med and materials | [Domain sketches](domains.md) | Native model/tool choices and proposed metrics; no domain implementation or container qualification. |
| Cluster and containers | [Operations](operations.md) | Recorded Determined A100 runs; [Dockerfile](../containers/Dockerfile) and [Slurm script](../scripts/slurm-train.sbatch) remain examples needing separate qualification. |
| Hugging Face candidate bundles | [Release guide](releases.md) | Local checksummed packaging and review material, with no automatic Hub uploads. |
| Hugging Face recipe home | [Layout, institutional examples and source mirror](../examples/huggingface/README.md) | Private personal Static Space with upstream links; our weights, data and raw run artifacts remain on the cluster. |
| hessian.AI organization and artifact cards | [Organization profile draft](../templates/huggingface/organization.md), [model card](../templates/huggingface/model-card.md), [dataset card](../templates/huggingface/dataset-card.md) | Drafts/templates; namespace, authority and publication terms remain to be established. |

The initial delivery excludes JUPITER work. General multi-GPU/multi-node support,
scientific benchmark validity and deployment readiness require separate evidence.
Use the validation level actually demonstrated when describing any recipe.