docs: add konfai-cli skill and fix AGENTS.md workspace/trust drifts

.claude/skills/konfai-cli/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: konfai-cli
+description: >-
+  Run KonfAI deep-learning workflows for medical imaging (segmentation, synthesis,
+  registration) from the command line: author or adapt a YAML config, then train, resume,
+  predict, and evaluate with the `konfai` CLI, or run a packaged model with the `konfai-apps`
+  CLI. Use when the user wants to train / fine-tune / run inference / evaluate a KonfAI model
+  from the terminal, adapt an example (Segmentation / Synthesis) config, understand the
+  workspace outputs (Checkpoints / Predictions / Evaluations), reference a custom model or
+  loss by classpath, or run and serve a published app (impact-synth, impact-seg, konfai-apps,
+  konfai-apps-server). Triggers: "train a KonfAI model", "konfai TRAIN / PREDICTION /
+  EVALUATION", "run konfai on the CLI", "konfai-apps infer", "run the segmentation example",
+  "evaluate my predictions", "fine-tune this app".
+---
+
+# Running KonfAI from the command line
+
+KonfAI is **config-driven**: a model, its data pipeline, losses/metrics, optimizer, and the
+whole train/predict/evaluate workflow are described in **YAML** and mapped onto Python objects
+by a reflection engine — no experiment-specific code for standard tasks. **The config is the
+experiment**, and every run leaves a fully-resolved config on disk.
+
+There are two command-line surfaces:
+
+- **`konfai`** — the low-level engine: author a config and `TRAIN` / `RESUME` / `PREDICTION` /
+  `EVALUATION`. This is the main path for building and training a workflow.
+- **`konfai-apps`** — the packaged-app runtime: run inference/evaluation with an already-trained
+  model bundled as an *app* (local, HuggingFace, or a remote server). Use this to *run* a
+  stable model, not to build one. See [references/apps-layer.md](references/apps-layer.md).
+
+## The canonical loop (`konfai`)
+
+Three workflows map to three files, each with one mandatory root key:
+
+| Command | File | Root key |
+|---|---|---|
+| `TRAIN` / `RESUME` | `Config.yml` | `Trainer:` |
+| `PREDICTION` | `Prediction.yml` | `Predictor:` |
+| `EVALUATION` | `Evaluation.yml` | `Evaluator:` |
+
+**Don't write configs from scratch — copy a runnable template from `examples/`** (Segmentation
+or Synthesis) and adapt it. Then:
+
+```bash
+cd examples/Segmentation                 # always run from the dir holding the configs + Dataset/
+
+konfai TRAIN      -y --gpu 0 --config Config.yml
+konfai PREDICTION -y --gpu 0 --config Prediction.yml --models Checkpoints/<train_name>/<checkpoint>.pt
+konfai EVALUATION -y          --config Evaluation.yml
+```
+
+Outputs are namespaced by the `train_name` in the config: `Checkpoints/<train_name>/`,
+`Statistics/<train_name>/`, `Predictions/<train_name>/`, `Evaluations/<train_name>/`. To
+iterate: edit the YAML (or bump `train_name`), re-run. See
+[references/examples-and-recipes.md](references/examples-and-recipes.md) for the verified
+Segmentation and Synthesis recipes, and
+[references/cli-reference.md](references/cli-reference.md) for every flag.
+
+## Rules that keep runs correct
+
+- **Run from the directory that holds the configs** (and `Dataset/`). KonfAI resolves relative
+  paths — configs, `Dataset/`, output dirs, and local `File:Class` classpaths — against the
+  current working directory (it prepends CWD to `sys.path`).
+- **Reading a config rewrites it on disk.** A run materialises resolved defaults back into the
+  YAML (`None` becomes the literal `"None"`). Expect a post-run git diff; keep configs under
+  version control. There is no read-only path. (Details:
+  [references/workspace-and-runtime.md](references/workspace-and-runtime.md).)
+- **`train_name` is the join key.** `Prediction.yml` and `Evaluation.yml` must use the *same*
+  `train_name` as the training run whose checkpoints/predictions they consume — the most common
+  failure is "evaluation can't find predictions" from a mismatched `train_name`.
+- **`--gpu` and `--cpu` are mutually exclusive**; with neither, it runs on CPU. `--gpu` ids are
+  validated against the visible CUDA devices. `--cpu N` needs `N > 0`.
+- **Install the imaging extra** to read `.mha` / medical formats: `pip install "konfai[imaging]"`
+  (a bare install fails on the first data read).
+- **`-y/--overwrite` overwrites existing outputs without prompting** — a destructive flag;
+  don't add it blindly when a prior run's outputs matter. `RESUME` needs `--model`; `PREDICTION`
+  needs `--models`.
+- **Custom models/losses/transforms** live in a `.py` beside the config and are referenced by
+  classpath `File:Class` (e.g. `Model:UNetpp5`). Write the `.py` before running.
+
+## Running a packaged app (`konfai-apps`)
+
+When a workflow is stable, it can be shipped as an **app** and run without touching YAML:
+
+```bash
+konfai-apps infer VBoussot/ImpactSynth:sCT -i patient/mr.nii.gz -o ./Output --gpu 0
+```
+
+`konfai-apps` also does `eval`, `uncertainty`, `pipeline`, `fine-tune`, `bundle`, and
+`download`; `konfai-apps-server` serves apps over HTTP (bearer auth by default). The published
+bundles under `apps/` (e.g. `impact-synth-konfai synthesize ...`, `impact-seg-konfai segment ...`)
+are thin task-named wrappers.
+
+> ⚠️ **Trust model.** Resolving/running an app **copies and imports the app's `.py` files**
+> (runs arbitrary code) and can pip-install its `requirements.txt`. **Only run apps from sources
+> you trust.** See [references/apps-layer.md](references/apps-layer.md).
+
+## Reference material (load on demand)
+
+- [references/cli-reference.md](references/cli-reference.md) — the `konfai` / `konfai-cluster` commands and every flag.
+- [references/config-authoring.md](references/config-authoring.md) — writing KonfAI YAML: files, root keys, classpaths, conventions, the mutation invariant.
+- [references/examples-and-recipes.md](references/examples-and-recipes.md) — verified Segmentation + Synthesis train→predict→evaluate recipes.
+- [references/workspace-and-runtime.md](references/workspace-and-runtime.md) — outputs keyed by `train_name`, env vars, DDP, SLURM, config modes.
+- [references/apps-layer.md](references/apps-layer.md) — `konfai-apps` / `konfai-apps-server`, app resolution, trust model, published bundles.
+
+The authoritative user-facing catalogue lives in `docs/source/config_guide/` (`training.md`,
+`prediction.md`, `evaluation.md`) and `docs/source/reference/cli.md`; `AGENTS.md` is the source
+of truth for framework internals and conventions.

.claude/skills/konfai-cli/references/apps-layer.md

@@ -0,0 +1,92 @@
+# The apps layer (`konfai-apps`)
+
+Once a KonfAI workflow is stable, package it as an **app** for a clean inference interface.
+`konfai-apps` is a separate package (own `pyproject.toml`, tests, CI) that layers on KonfAI's
+public API. Use it when you want inference/evaluation/packaging rather than authoring raw YAML.
+
+Two console scripts: `konfai-apps` (local or remote execution) and `konfai-apps-server`
+(host apps behind an HTTP API). There is also a Python API under `konfai_apps`.
+
+## What an app is, and where it resolves from
+
+An **app bundle** contains a KonfAI config + custom `.py` module(s) + model weights
+(+ an optional `requirements.txt`). The app id (and `--host`) decides the source:
+
+| How you name the app | Source |
+|---|---|
+| a filesystem path or bare local name | **Local directory** |
+| `repo_id:app_name` (one `:`, e.g. `VBoussot/ImpactSynth:sCT`) | **HuggingFace repo** (weights/config pulled via `huggingface_hub`) |
+| any app id **with `--host`/`--port`/`--token`** | **Remote server** (`konfai-apps-server`) |
+
+## ⚠️ Trust model — read before resolving an app
+
+Resolving or running an app is **not** a pure data download. It:
+
+- **copies the app's `.py` files into a run workspace and imports them** (the workspace is put
+  on `sys.path`, and KonfAI imports the custom modules) — i.e. it **runs arbitrary code**;
+- can **pip-install `requirements.txt`** — this mechanism is **opt-in and off by default**
+  (`install_requirements=True`); when enabled it installs the app's declared dependencies;
+- for HuggingFace apps, **downloads weights/config over the network**;
+- in remote mode, **uploads your inputs and config** to the server.
+
+**Only resolve/run apps from sources you trust.** This is the same trust boundary as any
+"download and execute" tool.
+
+## `konfai-apps` subcommands
+
+Inputs use `-i/--inputs` (repeatable; a file or a dataset dir), output goes to `-o/--output`
+(default `./Output`), device is `--gpu` XOR `--cpu`.
+
+| Command | Purpose | Example |
+|---|---|---|
+| `infer` | Run inference with an app | `konfai-apps infer VBoussot/ImpactSynth:sCT -i mr.nii.gz -o ./Output --gpu 0 --tta 4 --ensemble 3` |
+| `eval` | Inference + evaluation vs ground truth | `konfai-apps eval my_app -i ./inputs --gt ./gt --mask ./masks -o ./Eval` |
+| `uncertainty` | Uncertainty estimation | `konfai-apps uncertainty my_app -i mr.nii.gz -o ./Output` |
+| `pipeline` | Infer, then eval and optionally uncertainty in one run | `konfai-apps pipeline my_app -i ./in --gt ./gt -o ./Out --ensemble 3 -uncertainty` |
+| `fine-tune` | Fine-tune an app's checkpoint(s) into a new named app | `konfai-apps fine-tune my_app MyFT -d ./Dataset --models CV_0 CV_1 --epochs 20 --lr 1e-4` |
+| `bundle` | Assemble a bundle (config + checkpoints + optional `Model.py`), optionally export ONNX | `konfai-apps bundle sCT --out ./bundles --app-json app.json --config Prediction.yml --checkpoint CV_0.pt --onnx` |
+| `download` | Fetch a HuggingFace app's files into the local cache | `konfai-apps download VBoussot/ImpactSynth:sCT Prediction.yml` |
+
+Inference knobs on `infer`/`pipeline`: `--tta N` (test-time augmentations), `--ensemble N` /
+`--ensemble-models ...` (checkpoint ensembling), `--mc N` (Monte-Carlo dropout),
+`--patch-size` / `--batch-size` (override inference patch/batch), `-uncertainty` (also write
+the inference stack).
+
+### Serving apps over HTTP
+
+`konfai-apps-server` hosts a FastAPI app (uvicorn `konfai_apps.app_server:app`) and, unlike
+the internal MCP server, **defaults to bearer auth** (`--auth bearer`, token from
+`KONFAI_API_TOKEN`):
+
+```bash
+KONFAI_API_TOKEN=secret konfai-apps-server --apps ./apps.json --host 0.0.0.0 --port 8000
+# clients then run konfai-apps with --host/--port/--token to execute remotely
+konfai-apps infer my_app -i mr.nii.gz -o ./Out --host 127.0.0.1 --port 8000 --token secret
+```
+
+`--apps` is a required JSON file listing the app ids to serve; `--check` validates them
+(no download) and `--download` pre-fetches them. Relevant env vars: `KONFAI_API_TOKEN`
+(bearer token, client and server) and `KONFAI_IMPACTREG_REPO` (used by the IMPACT-Reg app).
+
+## Published app bundles (`apps/`)
+
+The `apps/` directory holds ready-to-use bundles — each an **independent pip package** that
+layers on `konfai` + `konfai-apps` (excluded from the `konfai` wheel):
+
+| Bundle | Task | Entry / usage |
+|---|---|---|
+| `impact_synth` | Synthesis (e.g. MR→CT) | `pip install impact-synth-konfai` → `impact-synth-konfai synthesize MR -i input.nii.gz -o ./Output/` |
+| `impact_seg` | Segmentation | `pip install impact-seg-konfai` → `impact-seg-konfai segment body -i image.nii.gz -o ./Output/` |
+| `impact_reg` | Registration | IMPACT-Reg orchestrator (`KONFAI_IMPACTREG_REPO`) |
+| `mrsegmentator` | MR segmentation | thin wrapper over `konfai-apps` |
+| `totalsegmentator` | CT segmentation | thin wrapper over `konfai-apps` |
+
+The thin wrappers (`impact_synth`, `impact_seg`, `mrsegmentator`, `totalsegmentator`) just
+call `konfai-apps` with a fixed app id, giving a task-named command
+(`impact-synth-konfai synthesize ...`) instead of `konfai-apps infer <id> ...`.
+
+## Where this fits
+
+- Author + train a workflow → raw `konfai` CLI (this skill's main path).
+- Ship a stable workflow for others to run inference → package as a `konfai-apps` app.
+- Integrate into an external tool (e.g. 3D Slicer) or a lightweight client → `konfai-apps-server`.

.claude/skills/konfai-cli/references/cli-reference.md

@@ -0,0 +1,98 @@
+# The `konfai` command-line reference
+
+KonfAI installs two console scripts (`konfai` and `konfai-cluster`, entry points
+`konfai.main:main` / `konfai.main:cluster`). Everything runs through four subcommands.
+
+```
+konfai <TRAIN|RESUME|PREDICTION|EVALUATION> [options]
+konfai --version
+```
+
+The subcommand (`dest="command"`) is **required** and maps to the KonfAI `State`. TRAIN and
+RESUME dispatch to `konfai.trainer.train`, PREDICTION to `konfai.predictor.predict`,
+EVALUATION to `konfai.evaluator.evaluate`.
+
+## Common options (every subcommand)
+
+| Option | Meaning |
+|---|---|
+| `-c`, `--config PATH` | Path to the workflow YAML. If omitted, a command-specific default filename is used — **always pass it explicitly** to avoid ambiguity. |
+| `-y`, `--overwrite` | Overwrite existing outputs (checkpoints, logs, predictions) without prompting. |
+| `--gpu ID [ID ...]` | GPU device ids, constrained to the visible devices, e.g. `--gpu 0` or `--gpu 0 1 2`. Omit to run on CPU. |
+| `--cpu N` | Run on CPU with `N` (>0) worker processes. **Mutually exclusive with `--gpu`.** |
+| `-q`, `--quiet` | Suppress console output. |
+| `-tb`, `--tensorboard` | Launch TensorBoard. |
+
+`--gpu` and `--cpu` are a mutually-exclusive group. With neither, execution falls back to CPU.
+
+## `TRAIN` — train from scratch
+
+Reads a `Trainer:` config and runs the full training loop.
+
+| Extra option | Default | Meaning |
+|---|---|---|
+| `--checkpoints-dir DIR` | `./Checkpoints/` | Where checkpoints are saved. |
+| `--statistics-dir DIR` | `./Statistics/` | Where training statistics / TensorBoard logs are saved. |
+
+```bash
+konfai TRAIN -y --gpu 0 --config Config.yml
+```
+
+## `RESUME` — continue an existing run
+
+Same as TRAIN plus checkpoint reload.
+
+| Extra option | Default | Meaning |
+|---|---|---|
+| `--model PATH` | *(required)* | Checkpoint to resume from. |
+| `-checkpoints-dir DIR` | `./Checkpoints/` | Checkpoints directory. |
+| `-statistics-dir DIR` | `./Statistics/` | Statistics directory. |
+| `--lr FLOAT` | *(unset)* | Override the learning rate. If omitted, the checkpoint LR resumes and the scheduler continues; if set, LR restarts from this value. |
+
+```bash
+konfai RESUME -y --gpu 0 --config Config.yml --model Checkpoints/TRAIN_01/last.pt
+```
+
+## `PREDICTION` — inference with a trained model
+
+Reads a `Predictor:` config. The `--config` value is passed as `prediction_file`.
+
+| Extra option | Default | Meaning |
+|---|---|---|
+| `--models PATH [PATH ...]` | *(required)* | One or more checkpoints. Passing several enables **ensembling**. |
+| `--predictions-dir DIR` | `./Predictions/` | Where predictions are written. |
+
+```bash
+konfai PREDICTION -y --gpu 0 --config Prediction.yml --models Checkpoints/TRAIN_01/best.pt
+```
+
+## `EVALUATION` — score predictions against ground truth
+
+Reads an `Evaluator:` config. The `--config` value is passed as `evaluations_file`.
+
+| Extra option | Default | Meaning |
+|---|---|---|
+| `--evaluations-dir DIR` | `./Evaluations/` | Where per-case + aggregate metric JSON is written. |
+
+```bash
+konfai EVALUATION -y --config Evaluation.yml
+```
+
+## `konfai-cluster` — SLURM submission
+
+Same four subcommands, plus a "Cluster manager arguments" group that submits via `submitit`
+instead of running locally:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--name NAME` | *(required)* | Job name. |
+| `--num-nodes N` | `1` | Number of nodes. |
+| `--memory GB` | `16` | Memory per node. |
+| `--time-limit MIN` | `1440` | Job time limit (minutes). |
+| `--resubmit` | off | Auto-resubmit just before timeout. |
+
+```bash
+konfai-cluster TRAIN --name seg_run --num-nodes 1 --gpu 0 --config Config.yml
+```
+
+Requires the `cluster` extra (`pip install konfai[cluster]`).