From b5023799d34ee0f7064c2d0f0591aef22eaa2288 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 25 Feb 2026 15:14:07 -0500
Subject: [PATCH] Document pinned-commit TORCH installs and verification checks

---
 README.md       | 12 ++++++++----
 docs/removal.md |  2 +-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c06dfbf..bec9b94 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ Prerequisites:
 First 5 minutes:
 
 ```bash
-npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz \
+npm install https://github.com/PR0M3TH3AN/TORCH/archive/<commit-sha>.tar.gz --force \
   && npx --no-install torch-lock init
 
 # sanity check (optional, but recommended)
@@ -34,13 +34,14 @@ npx --no-install torch-lock dashboard --port 4173 --host 127.0.0.1
 ```
 
 > TORCH is distributed from GitHub tarballs and is not currently published to the npm registry.
+> Use pinned commit tarballs (`archive/<commit-sha>.tar.gz`) for repeatable installs. Avoid `refs/heads/main.tar.gz` for production rollouts.
 
 ### Upgrade TORCH In An Existing Repository
 
 Use this when the repository already has a `torch/` directory:
 
 ```bash
-npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz
+npm install https://github.com/PR0M3TH3AN/TORCH/archive/<commit-sha>.tar.gz --force
 npx --no-install torch-lock update --force
 npm install --prefix torch
 npm run --prefix torch lock:check:daily -- --json --quiet
@@ -49,7 +50,7 @@ npm run --prefix torch lock:check:daily -- --json --quiet
 Use this for first-time setup in a repository without `torch/`:
 
 ```bash
-npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz
+npm install https://github.com/PR0M3TH3AN/TORCH/archive/<commit-sha>.tar.gz --force
 npx --no-install torch-lock init --force
 npm install --prefix torch
 npm run --prefix torch lock:check:daily -- --json --quiet
@@ -58,7 +59,7 @@ npm run --prefix torch lock:check:daily -- --json --quiet
 One-liner (auto-detect existing vs new install):
 
 ```bash
-npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz && \
+npm install https://github.com/PR0M3TH3AN/TORCH/archive/<commit-sha>.tar.gz --force && \
 if [ -d torch ]; then npx --no-install torch-lock update --force; else npx --no-install torch-lock init --force; fi && \
 npm install --prefix torch && \
 npm run --prefix torch lock:check:daily -- --json --quiet
@@ -71,6 +72,9 @@ Post-upgrade validation checklist:
 3. Confirm host install dependencies exist: `test -d torch/node_modules`.
 4. Run one scheduler cycle (expected to fail on Linux simulation due to artifact checks, but not due to missing config/handoff):
    - `AGENT_PLATFORM=linux npm run --prefix torch scheduler:daily`
+5. Verify installed package matches expected resolver behavior:
+   - `rg -n "cwdBaseName === 'torch' && fs.existsSync\\(parentPath\\)" node_modules/torch-lock/src/torch-config.mjs`
+   - `rg -n "cwdBaseName === 'torch' && fs.existsSync\\(parentPath\\)" torch/src/torch-config.mjs`
 
 ## Development
 
diff --git a/docs/removal.md b/docs/removal.md
index 0d993dd..8da61fd 100644
--- a/docs/removal.md
+++ b/docs/removal.md
@@ -151,5 +151,5 @@ grep '"torch:' package.json
 If you want to re-install TORCH later:
 
 ```bash
-npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz && npx torch-lock init
+npm install https://github.com/PR0M3TH3AN/TORCH/archive/<commit-sha>.tar.gz --force && npx torch-lock init
 ```