HF upload tooling: env-only auth, scoped-token guidance, optional ladder auto-upload

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GkgLsACEF6CCP7EUfA5fZe

1 files changed, 12 insertions, 0 deletions

diff --git a/README.md b/README.md
index 128eed0..7b4f7a3 100644
--- a/README.md
+++ b/README.md
@@ -53,3 +53,15 @@ git add results && git commit -m "ladder results" && git push
 Analysis (anywhere): `python scripts/plot_ladder.py --results results/h200node1` -> per-run table, loss
 curves, and the gap-vs-scale figure (the paper's part-2 headline). If a specific checkpoint is needed for
 the estimator audits, scp just that `runs/<name>/ckpt.pt`.
+
+## HF upload & security (shared nodes)
+Results (and optionally checkpoints) can go to a **private** HF repo: `HF_UPLOAD=1 [HF_CKPT=1] ./scripts/run_ladder.sh`
+or manually `python scripts/upload_hf.py --results results/<tag> [--with-ckpt runs]` (default repo
+`<whoami>/zbp-scaling-runs`, created private if missing).
+
+Uploads authenticate ONLY via the `HF_TOKEN` environment variable or a standard `hf auth login`; tokens are
+never CLI arguments (argv is world-readable via /proc on shared machines), never written by our scripts, and
+`.gitignore` excludes token-like files. On a shared node, mint a **fine-grained HF token scoped to the single
+private repo** (write permission only), `export HF_TOKEN=...` per session, and revoke it after the campaign.
+Zero-token alternative: push only the small JSONL results to GitHub (a repo-scoped deploy key suffices) and
+upload checkpoints from a trusted machine.