> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossary

> Names the CLI, JobSpec, and console actually use

These words show up in error messages. Using a nearby synonym (run vs job, image vs recipe) usually sends you to the wrong page.

## Lab and console

| Term                 | Meaning                                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lab / repository** | Directory created by `sf init`. Marker file is `starforge.yaml`. `sf` walks up from the current directory to find it, same idea as git.                       |
| **Project**          | The `name` field in `starforge.yaml`. The console groups every job from this lab under `@<user>/<name>`. Names are unique per user, not globally.             |
| **Experiment**       | A directory under `experiments/<name>/`. Holds `config.yaml`, `recipe.lock.json`, and for custom jobs `train.sh`. Creating an experiment does not start GPUs. |
| **Job / run**        | One admitted submission. It has a run id, a ledger status, and (once launched) a backend handle. One experiment can produce many jobs.                        |
| **Profile**          | A named GPU shape in the server hardware registry (`h200`, `h100`, …). `--profile h200:8` means that series and 8 GPUs total.                                 |

## Methods and packaging

| Term                 | Meaning                                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recipe**           | Versioned declaration of a method: entrypoint, params, metrics, artifacts, runtime matrix. Files live in `starforge-core` under `recipes/catalog/`. |
| **Catalog**          | The set of recipes the connected server has published. Client and server must agree on digest and version.                                          |
| **Method id**        | `<framework>/<method>`, for example `trl/kto`.                                                                                                      |
| **recipe.lock.json** | Written by `sf new`. Pins recipe digest and framework version. Submit refuses a stale lock.                                                         |
| **JobSpec**          | `forge/v2` JSON the CLI builds and the server admits. You do not hand-write it. See [JobSpec](/en/reference/jobspec).                               |
| **Job Capsule**      | `capsule.json` + `bootstrap.sh` + `runner.pex` injected by the server after admit. Training images do not preinstall the platform package.          |
| **runtime\_id**      | Key for the deployment artifact (OCI image, SIF, SQSH). Resolved from catalog, `FORGE_IMAGE_*`, the runtime registry file, or `--image`.            |

## Execution

| Term                | Meaning                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Executor**        | How the control plane starts a container: `local` (Docker on the console host), `agent` (`forgelet` on a node), `kuberay` (RayJob), `slurm` (slurmrestd only).             |
| **Pool**            | One homogeneous GPU group in the JobSpec. Heterogeneous jobs use two pools (train + rollout) and only work on `kuberay` / `slurm`.                                         |
| **FORGE\_OUT\_DIR** | The one directory whose contents survive the job. Checkpoints written elsewhere disappear with the scratch tree.                                                           |
| **Ingest**          | HTTP path from the training container back to the console (logs, metrics, samples). `FORGE_INGEST_URL` must be reachable from the GPU node, not `127.0.0.1` on the laptop. |

## Custom jobs

| Term                         | Meaning                                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **custom/custom**            | Catalog recipe that runs `experiments/<name>/train.sh` and nothing else. No framework detection. No fallback from a failed adapter.                     |
| **Observability `platform`** | Recipe option: runner injects `PYTHONPATH` so `import starforge` works without installing the wheel in the image.                                       |
| **Observability `external`** | Current catalog default for `custom/custom`. Submit requires `--observability-url`. Console charts still need `starforge.report` if you also want them. |