opencode-skills-collection 3.1.2 → 3.1.3

package/bundled-skills/remote-gpu-trainer/evals/RESULTS.md

@@ -0,0 +1,44 @@
+# Agentic navigation results (Tier 2)
+
+Each row: a **fresh agent** was given the skill and one scenario `prompt` from
+[`cases.jsonl`](cases.jsonl), told to navigate **from SKILL.md only** (follow the documented
+routing, no blind grep), and graded on whether it reached a correct, specific answer covering the
+scenario's `must_cover` points within ~2 hops.
+
+**Methodology / honesty caveats** (so a reader can weight this correctly):
+- Runs to date were gathered **during development**, on the development model (Claude Opus class),
+  as subagent dispatches — not an independent third party, and **not yet** the
+  Haiku/Sonnet/Opus sweep Anthropic's best-practices recommend. Treat as *author-run smoke evals*,
+  not a neutral benchmark.
+- These prove **routing + retrieval** inside the skill, not the truth of platform facts on a live
+  box (only AutoDL is battle-tested — see the repo README's "Verification status").
+- Single run per scenario; no adversarial/perturbed phrasings yet.
+
+## Results — 2026-06
+
+| Scenario | Verdict | Hops | Navigation path observed |
+|---|---|---|---|
+| convergence-frozen-resnet | **PASS** | 1 | SKILL.md "When training breaks" → `convergence-debugging.md` O1 (overfit-one-batch) + O2 (params-not-in-optimizer) + O17 (frozen-still-in-optimizer) + O18 (frozen-BN drift) + O6 (Adam vs AdamW) |
+| data-worker-rng-dup | **PASS** | 1 | SKILL.md "When training breaks" → `data-pipeline.md` DP1 (numpy fork-RNG dup; worker_init_fn fix) |
+| oom-on-step-2 | **PASS** | ≤2 | SKILL.md "When training breaks" → `oom-memory.md` (fit-it ladder + OOM-at-step-2 / Adam lazy state) |
+| nccl-one-rank-hang | **PASS** | ≤2 | SKILL.md → `distributed-launch.md` (desync toolkit D19 / one-rank-diverged D20) |
+| diffusion-loss-low-samples-bad | **PASS** | ≤2 | SKILL.md → `by-domain.md` diffusion section (DF1 loss≠quality, DF2 EMA weights) |
+| nan-loss-spike-bf16 | **PASS** | ≤2 | SKILL.md "When training breaks" → `precision-stability.md` P8/P12/P15 (NaN-origin + warmup spike + z-loss) |
+| resume-epoch-reset | **PASS** | 1 | SKILL.md → `checkpoint-resume.md` C1/C12/C14 (save FULL state: epoch/step/scheduler/RNG/scaler) |
+| throughput-gpu-starved | **PASS** | ≤2 | SKILL.md → `throughput-profiling.md` T1/T4 (GPU-bound vs data-bound; num_workers/prefetch) |
+| runpod-spot-resume-teardown | **PASS** | ≤2 | SKILL.md → `profiles/runpod.md` §4/§5 → `spot-resilience.md` → `checkpoint-resume.md` C3 |
+| vastai-teardown-billing | **PASS** | ≤2 | SKILL.md → `profiles/vastai.md` §5 → `lifecycle_checklist.md` Phase 5 |
+| autodl-inode-disk-full | **PASS** | ≤2 | SKILL.md → the inode/disk gotcha (principle #5 / `gotchas_universal.md` U7) |
+| china-hf-download-stall | **PASS** | ≤2 | SKILL.md → `references/china-network.md` (HF_ENDPOINT=hf-mirror, hf_transfer caution) |
+| lambda-stop-vs-terminate | **PASS** | ≤2 | SKILL.md → `profiles/lambda.md` (no stop state; terminate irreversible) |
+| autodl-first-contact-15day | **PASS** | 1 | SKILL.md principle #10 → `profiles/autodl.md` Surface block + AD-DANGER (关机 auto-releases after 15 days) |
+
+**Summary: 14/14 scenarios routed correctly** (9 via workflow `w2r1t7mm9`, 5 standalone), each to a
+correct + specific answer within ≤2 hops. The Tier-1 structural check (`run_evals.py`) runs all 14
+cases and is the regression guard kept green in CI.
+
+## Known gaps (what these results do NOT yet cover)
+
+- No multi-model sweep (Haiku/Sonnet/Opus) — required to claim the best-practices testing bar.
+- No adversarial/paraphrased prompts (e.g. the user describes the symptom in non-canonical words).
+- No live-platform validation of the facts the agent retrieves (the verification-status caveat).

package/bundled-skills/remote-gpu-trainer/evals/cases.jsonl

@@ -0,0 +1,14 @@
+{"id": "convergence-frozen-resnet", "prompt": "Fine-tuning a ResNet50 on a rented GPU. Training runs with no errors and normal speed, but loss barely drops and val accuracy is stuck near chance. I froze the backbone with requires_grad=False and use Adam with weight_decay. How do I debug why it isn't learning?", "expect_files": ["references/training/convergence-debugging.md"], "expect_ids": ["O1", "O2", "O17", "O18", "O6"], "expect_grep": [], "must_cover": "overfit-one-batch smoke; frozen-param-still-in-optimizer; frozen-BN running-stats drift; Adam vs AdamW decoupled decay", "agentic": "PASS (1-hop, 2026-06): SKILL.md 'When training breaks' -> convergence-debugging.md O1/O2/O17/O18/O6"}
+{"id": "data-worker-rng-dup", "prompt": "My image augmentations seem to repeat: different DataLoader workers produce identical random crops, and every epoch looks the same. Linux, num_workers=8, numpy-based augmentation. Real bug? Fix?", "expect_files": ["references/training/data-pipeline.md"], "expect_ids": ["DP1"], "expect_grep": ["worker_init_fn", "torch.initial_seed"], "must_cover": "numpy global RNG inherited via fork, not reseeded per worker; fix via worker_init_fn or route RNG through torch", "agentic": "PASS (1-hop, 2026-06): SKILL.md 'When training breaks' -> data-pipeline.md DP1"}
+{"id": "oom-on-step-2", "prompt": "CUDA out of memory on step 2, right after the first optimizer step. Step 1 ran fine. Why does it OOM only on the second step?", "expect_files": ["references/training/oom-memory.md"], "expect_ids": ["M17"], "expect_grep": [], "must_cover": "Adam lazily allocates optimizer state (m,v) on the first step()", "agentic": "PASS (workflow w2r1t7mm9): routed to oom-memory.md ladder + step-2 entry"}
+{"id": "nccl-one-rank-hang", "prompt": "Multi-GPU training hangs partway through an epoch; one rank seems stuck and the others wait forever (NCCL timeout). How do I find which rank and why?", "expect_files": ["references/training/distributed-launch.md"], "expect_ids": ["D19", "D20"], "expect_grep": [], "must_cover": "one rank diverged/OOM'd; survivors hang on the absent collective; desync-debug toolkit", "agentic": "PASS (workflow w2r1t7mm9): routed to distributed-launch.md hang toolkit"}
+{"id": "diffusion-loss-low-samples-bad", "prompt": "My diffusion model's training loss is low and still decreasing, but the generated samples look bad/blurry. The loss says it's fine. What's wrong?", "expect_files": ["references/training/by-domain.md"], "expect_ids": ["DF1", "DF2"], "expect_grep": ["EMA"], "must_cover": "loss != sample quality; sampling from raw (non-EMA) weights; cross-link verifying-dl-experiments", "agentic": "PASS (workflow w2r1t7mm9): routed to by-domain.md diffusion section"}
+{"id": "nan-loss-spike-bf16", "prompt": "LLM pretraining in bf16: loss is stable then suddenly spikes to NaN. How do I find where the NaN comes from and stop the spikes?", "expect_files": ["references/training/precision-stability.md"], "expect_ids": ["P8", "P12", "P15"], "expect_grep": ["z-loss"], "must_cover": "NaN arithmetic origins + anomaly detection; LR-too-high/warmup spike; z-loss to bound logits", "agentic": "PASS (workflow w2r1t7mm9): routed to precision-stability.md"}
+{"id": "resume-epoch-reset", "prompt": "I resume training from a checkpoint but the epoch/step counter restarts from 0 and the LR schedule replays warmup. What did I forget to save/restore?", "expect_files": ["references/training/checkpoint-resume.md"], "expect_ids": ["C1", "C12", "C14"], "expect_grep": [], "must_cover": "save FULL state (epoch/step/scheduler/RNG/scaler), not just weights", "agentic": "PASS (1-hop): SKILL.md -> checkpoint-resume.md"}
+{"id": "throughput-gpu-starved", "prompt": "GPU utilization is low and training is slow on my rented box. I think the dataloader is starving the GPU. How do I confirm and fix it?", "expect_files": ["references/training/throughput-profiling.md"], "expect_ids": ["T1", "T4"], "expect_grep": ["num_workers"], "must_cover": "GPU-bound vs data-bound vs comms-bound triage; num_workers/prefetch knobs", "agentic": "PASS: SKILL.md -> throughput-profiling.md"}
+{"id": "runpod-spot-resume-teardown", "prompt": "On RunPod my spot training keeps getting preempted. How do I make it resume instead of restarting, and how do I stop the meter most cheaply afterwards without losing checkpoints?", "expect_files": ["profiles/runpod.md"], "expect_ids": [], "expect_grep": ["terminate", "Network Volume"], "must_cover": "Network Volume is the only durable store; ~5s grace; terminate (not stop) stops billing; verify ckpt before terminate", "agentic": "PASS (workflow w2r1t7mm9): SKILL.md -> profiles/runpod.md SS4/SS5 -> spot-resilience.md -> checkpoint-resume.md C3"}
+{"id": "vastai-teardown-billing", "prompt": "On vast.ai, what action actually stops billing, and how do I tear down without losing my checkpoints?", "expect_files": ["profiles/vastai.md"], "expect_ids": [], "expect_grep": ["destroy"], "must_cover": "destroy is the only meter-stop; stop still bills disk; copy + load-verify off-box before destroy", "agentic": "PASS (workflow w2r1t7mm9): SKILL.md -> profiles/vastai.md SS5 -> lifecycle_checklist Phase 5"}
+{"id": "autodl-inode-disk-full", "prompt": "On AutoDL my torch.save fails with a disk/iostream error, but df -h shows plenty of space left. What's going on?", "expect_files": ["references/gotchas_universal.md"], "expect_ids": [], "expect_grep": ["inode", "df -i"], "must_cover": "storage dies on inodes before bytes; monitor df -i not just df -h; millions of small files", "agentic": "PASS (workflow w2r1t7mm9): routed to the inode/disk gotcha (principle #5 / U7)"}
+{"id": "china-hf-download-stall", "prompt": "Training in mainland China: a huggingface model download stalls and hangs with no error. How do I fix the download?", "expect_files": ["references/china-network.md"], "expect_ids": [], "expect_grep": ["hf-mirror", "HF_ENDPOINT"], "must_cover": "HF_ENDPOINT=hf-mirror.com; keep hf_transfer OFF on flaky CN links; resumable-download ladder", "agentic": "PASS (workflow w2r1t7mm9): SKILL.md -> references/china-network.md"}
+{"id": "lambda-stop-vs-terminate", "prompt": "On Lambda Cloud, is there a stop action to pause billing while keeping my instance, or only terminate? How should I tear down?", "expect_files": ["profiles/lambda.md"], "expect_ids": [], "expect_grep": ["terminate"], "must_cover": "no stop state on Lambda on-demand; terminate is irreversible + wipes the instance; persistent FS is the only durable home", "agentic": "PASS (workflow w2r1t7mm9): SKILL.md -> profiles/lambda.md"}
+{"id": "autodl-first-contact-15day", "prompt": "First time on AutoDL. I'll 关机 (stop) my instance between sessions to save money — is my data safe if it stays stopped for a few weeks? Anything else I should know up front?", "expect_files": ["profiles/autodl.md"], "expect_ids": [], "expect_grep": ["Surface to the user", "免密", "AD-DANGER"], "must_cover": "关机 auto-releases after 15 days -> data disk deleted (not safe to park indefinitely); sync best to /root/autodl-fs for a longer pause; surface conveniences (one-click SSH免密, GPU notify, panels) + danger clocks (principle #10)", "agentic": "PASS (2026-06): principle #10 first-contact surfacing -> profiles/autodl.md Surface block + AD-DANGER 15-day clock"}

package/bundled-skills/remote-gpu-trainer/evals/run_evals.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""
+Structural retrieval-reachability check for the remote-gpu-trainer skill.
+
+For each scenario in cases.jsonl, assert that the answer is actually PRESENT in the
+skill, at the documented location, with the expected entry IDs / keywords intact:
+
+  - every `expect_files` path exists
+  - every `expect_ids` appears as a `### <ID>` header in one of those files
+  - every `expect_grep` keyword appears (case-insensitive) in one of those files
+
+This is the cheap, no-API-key tier: it does NOT prove an agent *navigates* there
+(that is the agentic tier — see RESULTS.md), and it does NOT prove the platform
+FACTS are correct on a live box (see the README "Verification status"). What it
+DOES catch is drift: a renamed/removed entry ID, a moved section, a deleted file,
+or a fact rewritten away from a key term — i.e. a regression in the skill's known
+load-bearing capabilities.
+
+Usage:  python evals/run_evals.py            # exits 1 if any case fails
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+CASES = Path(__file__).resolve().parent / "cases.jsonl"
+
+
+def header_present(text, id_):
+    # match `### O1 ...` but not `### O10 ...`
+    return re.search(r"(?m)^###\s+" + re.escape(id_) + r"\b", text) is not None
+
+
+def main():
+    cases = [json.loads(l) for l in CASES.read_text(encoding="utf-8").splitlines() if l.strip()]
+    passed = failed = 0
+    for c in cases:
+        problems = []
+        blobs = []
+        for f in c.get("expect_files", []):
+            p = REPO / f
+            if not p.exists():
+                problems.append(f"missing file: {f}")
+            else:
+                blobs.append(p.read_text(encoding="utf-8"))
+        joined = "\n".join(blobs)
+        low = joined.lower()
+        for i in c.get("expect_ids", []):
+            if not any(header_present(b, i) for b in blobs):
+                problems.append(f"missing entry id: {i}")
+        for kw in c.get("expect_grep", []):
+            if kw.lower() not in low:
+                problems.append(f"missing keyword: {kw!r}")
+        status = "PASS" if not problems else "FAIL"
+        if problems:
+            failed += 1
+        else:
+            passed += 1
+        print(f"[{status}] {c['id']}")
+        for pr in problems:
+            print(f"         - {pr}")
+    print(f"\n{passed}/{passed + failed} cases reachable" + ("" if not failed else f"  ({failed} FAILED)"))
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled-skills/remote-gpu-trainer/examples/autodl_sweep/README.md

@@ -0,0 +1,72 @@
+# Worked example — a 3-cell ablation sweep on AutoDL
+
+A complete, end-to-end run of the 6-phase lifecycle (SKILL.md) for the deepest profile
+(`profiles/autodl.md`). Substitute your own project name, alias, and configs. Two instances run
+their own queue file in parallel; this walkthrough ships `queue_1.txt` and shows one instance. **Read `profiles/autodl.md`
+first** — it owns every path and verb used below.
+
+The AutoDL `SCRIPT OVERRIDES` (profiles/autodl.md §8) that parameterize the templates:
+
+```bash
+export PROJECT_REPO_DIR=/root/myproj
+export DATA_DIR=/root/autodl-tmp          # fast per-instance scratch (checkpoints)
+export DURABLE_DIR=/root/autodl-fs        # region-locked shared FS (survives release)
+export PROXY_HOOK='source /etc/network_turbo'
+export CRED_FILE=/root/.wandb_key
+```
+
+### Phase 0 — Environment audit
+```bash
+ssh autodl-1 'df -h /root/autodl-tmp /root/autodl-fs / && df -i /root/autodl-fs && \
+              cat /sys/fs/cgroup/memory.max | numfmt --to=iec && nvidia-smi'
+bash scripts/gpu_health.sh 0     # run ON the box: Xid / throttle pre-flight (U22/U23)
+```
+Budget the disk: `ckpt_size × cells_in_queue + scratch`. **Verify:** `nvidia-smi` shows the expected
+GPU; `df -i /root/autodl-fs` is well under 100% (the inode cap, U7).
+
+### Phase 1 — SSH + credentials
+```bash
+# alias already in ~/.ssh/config (references/ssh_transport.md). Push the wandb key via stdin,
+# to the per-instance disk — NEVER the shared FS (U34, and AutoDL's classifier blocks it, AD-gotcha):
+printf '%s\n' "$WANDB_KEY_FROM_ENV" | ssh autodl-1 'umask 077; cat > /root/.wandb_key && chmod 600 /root/.wandb_key'
+```
+**Verify:** `ssh autodl-1 'python -c "import torch;print(torch.cuda.is_available())"'` prints `True`.
+
+### Phase 2 — Wrapper + CPU-smoke gate
+```bash
+# Parameterize the templates, drop the .template suffix, smoke locally on CPU BEFORE renting time:
+cp scripts/run_one.sh.template run_one.sh && cp scripts/run_queue.sh.template run_queue.sh
+python -m src.train -c configs/ablation/baseline.yaml --task reconstruction \
+       --limit-batches 2 --epochs 1   # logger off; catches import/shape/scale bugs for free
+```
+**Verify:** the smoke exits 0 on 2 batches. (Smoke *content* → **REQUIRED:** `verifying-dl-experiments`.)
+
+### Phase 3 — Detached launch
+```bash
+# Push the parameterized wrappers + queue to the shared FS (ONE copy, all instances read it):
+scp run_one.sh run_queue.sh examples/autodl_sweep/queue_1.txt autodl-1:/root/autodl-fs/
+ssh autodl-1 "RUN_ONE=/root/autodl-fs/run_one.sh tmux new -d -s q1 \
+  'bash /root/autodl-fs/run_queue.sh /root/autodl-fs/queue_1.txt 2>&1 | tee /root/autodl-tmp/runs/logs/q1_master.log'"
+```
+**Verify within 60 s:** `ssh autodl-1 'tmux ls && tail -5 /root/autodl-tmp/runs/logs/q1_master.log'` shows
+the session alive and a `STARTING baseline` line. Never overwrite the FS wrapper mid-run (U2 / principle #6).
+
+### Phase 4 — Durable monitoring
+```bash
+ssh autodl-1 'grep -hE "STARTING|FINISHED|QUEUE DONE|ERROR|Traceback" /root/autodl-tmp/runs/logs/q1_master.log | tail -8'
+```
+For a multi-hour sweep deploy the four-layer architecture (`references/monitoring_patterns.md`): a remote
+self-completion marker + a session patrol loop. Flag a FINISHED at <50% typical duration (probable
+early-stop) and re-launch the **identical** config (principle #7), never a patched one. Don't blind-retry.
+
+### Phase 5 — Aggregate + verify + teardown
+```bash
+ssh autodl-1 'DATA_DIR=/root/autodl-tmp DURABLE_DIR=/root/autodl-fs bash /root/autodl-fs/aggregate_to_fs.sh'  # gated sync (U33)
+LOCAL_TARGET=/path/to/local/final_ckpts REMOTE_ALIAS=autodl-1 \
+  REMOTE_PATH=/root/autodl-fs/final_ckpts bash scripts/download_loop.sh        # resumable per-dir pull
+python scripts/verify_local.py /path/to/local/final_ckpts/                     # LOAD each best.pth
+```
+**Verify:** `verify_local.py` reports 100% OK. **Iron Law:** only AFTER every cell is pulled AND
+load-verified AND the user approves does teardown run — on AutoDL `关机` stops the meter and keeps the
+disk (the reversible exception); `release` frees it irreversibly. Reconcile against the roster, not the
+log (`references/parallel_ablation.md` §6). **REQUIRED:** `superpowers:verification-before-completion`.

package/bundled-skills/remote-gpu-trainer/examples/autodl_sweep/queue_1.txt

@@ -0,0 +1,6 @@
+# Queue file for instance 1 — one ablation cell per line: <cfg_path> <task> [epochs]
+# Blank epochs => wrapper default (20). Detection needs more epochs (U32) => 50.
+# Split cells across queue_1.txt / queue_2.txt by COST so queues finish together.
+configs/ablation/baseline.yaml        reconstruction 20
+configs/ablation/no_aug.yaml          reconstruction 20
+configs/ablation/det_baseline.yaml    detection      50

package/bundled-skills/remote-gpu-trainer/profiles/_schema.md

@@ -0,0 +1,100 @@
+# Platform Profile Schema
+
+Every `profiles/<platform>.md` describes ONE platform with the **same 8 sections in the same order**, so
+they are scannable and diffable. A profile owns all the *slow-changing, per-platform* substrate that the
+SKILL.md phases delegate to. It does **not** describe a specific job (that's the portable job request,
+below) and never repeats the universal gotchas (those live in `references/gotchas_universal.md` — link,
+don't restate).
+
+Design rule borrowed from SkyPilot / dstack / Ray: **hardware is a CONSTRAINT, not a SKU.** A job asks
+for `gpu: A100:8`; the profile owns how that maps to this platform's instance types. **Secrets are
+referenced by env-var NAME or file path only — never inline a key**.
+
+---
+
+## Required structure of `profiles/<platform>.md`
+
+Start each profile with a compact frontmatter block (the machine-readable facts), then the 8 prose
+sections.
+
+```yaml
+---
+platform: <name>            # e.g. runpod
+kind: ssh-rental            # ssh-rental | cloud-api | kubernetes | slurm
+meter_stop_verb: terminate  # the action that STOPS billing (stop | terminate | destroy | release | 关机 | manual)
+meter_stop_irreversible: true
+detach_primitive: tmux      # tmux | sbatch | k8s-job | nohup | kaggle-commit
+spot_available: true
+spot_grace: ~5s             # SIGTERM→SIGKILL window, or n/a
+shared_fs: false            # is there a cross-instance shared filesystem?
+inode_cap: none             # ~200K | none | host-dependent
+free_egress: true           # download/upload to the wire free?
+china_mirror_needed: false  # does it sit behind the GFW?
+host_driver_cuda_max: "12.x"
+local_nvme: true
+---
+```
+
+### 1. LAUNCH
+Entry points (web console / CLI / REST API / SSH), the canonical create command, and the **env
+contract** — what IS the Python env (prebuilt base? a Docker image you choose? Lambda Stack?). State the
+rule "the image/base IS the env — do not `conda create` on a rental" if it applies.
+
+### 2. STORAGE MODEL  *(the survival matrix — principle #4)*
+List every storage tier with its path, speed, and size/inode cap. Then a **survival matrix**:
+
+| Tier | Path | Survives STOP? | Survives DESTROY? | Cap |
+|---|---|---|---|---|
+
+State region/DC-lock for any shared/network volume. Name the mount checkpoints MUST go to for the
+teardown verb in §5.
+
+### 3. NETWORK
+Egress/proxy story, China-mirror relevance (link `references/china-network.md` if applicable), how
+ports/services are exposed (TB/Jupyter), and the **SSH flavor(s)** — note if proxied/basic SSH cannot
+`scp`/`rsync` (then direct-TCP is required) and whether ports change on restart.
+
+### 4. SPOT / INTERRUPTION + RESUME  *(principle #7/#8)*
+The interruption model (spot bid? capacity? auto-shutdown clock? auto-release?), the **detection signal +
+grace window**, and the resume hook. Link `references/spot-resilience.md` for the cadence formula.
+
+### 5. TEARDOWN / BILLING  *(principle #9 + the Iron Law)*
+Exactly **what stops the meter** (stop vs terminate vs destroy vs 关机), what each preserves, what is
+**irreversible**, and the cost trap (e.g. "stop still bills storage 2×"). This is the most error-prone
+section — be precise.
+
+### 6. DAEMON TOOL
+The detach primitive (`tmux` / `sbatch` / Job manifest / commit), whether it survives an instance restart
+(not just an SSH drop), and any native queue/scheduler. Note if `tmux` must be `apt install`-ed or is
+absent (use `nohup … </dev/null >log 2>&1 &`).
+
+### 7. TOP GOTCHAS  (4–8, platform-pinned)
+Only the *platform-specific* ones, Symptom → Root cause → Fix. Universal gotchas are referenced, not
+repeated. Give each a stable local id (e.g. `RP1`, `VAST2`).
+
+### 8. SCRIPT OVERRIDES
+The exact values to parameterize the `scripts/` templates for this platform:
+`DATA_DIR=` (fast scratch) · `DURABLE_DIR=` (survives teardown) · `PROXY_HOOK=` · `CRED_FILE=` (file path; `""` if the key is an env var/secret) · `SCRATCH=` (what to prune) · `HF_HOME=` · `DETACH=`.
+The templates read exactly these env-var names. Two further knobs *derive* rather than being set per
+platform: `RUN_ONE` (the queue runner's path to `run_one.sh`) defaults to `$DURABLE_DIR/run_one.sh`, and
+`PROJECT_REPO_DIR` (where *this run's* code lives) is a per-run value — see "Portable job request" below;
+set either explicitly only if your layout differs.
+
+---
+
+## Portable job request (NOT in the profile — keep it per-run)
+
+A job is described separately so the *same* job runs against any profile. Document it in
+`references/parallel_ablation.md`; the shape:
+
+```yaml
+resources:
+  gpu: {name: A100, count: 8, memory: 40GB+}   # a CONSTRAINT (ranges ok), never a platform SKU
+  disk: 200GB
+candidates: [autodl, china, runpod]            # ordered fallback → "describe once, run anywhere"
+file_mounts: {/data: {source: ..., mode: MOUNT_CACHED}}   # MOUNT | COPY | MOUNT_CACHED
+run: "bash run_queue.sh queue.txt"
+```
+
+The launcher resolves a job against a profile; the profile supplies paths/verbs, the job supplies
+the work. Keeping them separate is what makes a profile reusable across every job.