From d2e14418ca2239854d18a773c2878e150a04814f Mon Sep 17 00:00:00 2001
From: Mads Lorentzen <50207393+MadsLorentzen@users.noreply.github.com>
Date: Fri, 17 Jul 2026 22:05:43 +0200
Subject: [PATCH] docs(setup): document upstream-pull workflow and
 failure-isolate install loops (#176)

Adds SETUP.md section 8 (pulling upstream updates into a personalized fork: commit-first, check_upstream_updates.py preview, conflicts-as-signal) closing #174, reported by @sharique. Also brings SETUP.md's duplicate install loops up to #157's failure-isolated pattern.
---
 SETUP.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/SETUP.md b/SETUP.md
index bf3a42f..3d92d7a 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -124,16 +124,16 @@ Run these from the repository root.
 ```powershell
 $tools = @("jobbank-search", "jobdanmark-search", "jobindex-search", "jobnet-search", "linkedin-search", "freehire-search")
 foreach ($tool in $tools) {
-  Set-Location ".agents/skills/$tool/cli"
+  Push-Location ".agents/skills/$tool/cli"
   bun install
-  Set-Location "..\..\..\.."
+  Pop-Location
 }
 ```
 
 - Bash / zsh / Git Bash:
 ```bash
 for tool in jobbank-search jobdanmark-search jobindex-search jobnet-search linkedin-search freehire-search; do
-  cd .agents/skills/$tool/cli && bun install && cd ../../../..
+  (cd .agents/skills/$tool/cli && bun install)
 done
 ```
 
@@ -240,6 +240,19 @@ Set-Location cover_letters; xelatex cover_<company>_<role>.tex; Set-Location ..
 
 These commands apply to the stock templates (moderncv CV, `cover.cls` cover letter). If you'd rather use your own LaTeX template, run `/add-template` — it captures the template's compile engine, fonts, style rules, and page limit, test-compiles it, and wires it into `/apply`. See the "LaTeX templates" section in the README.
 
+## 8. Pulling upstream updates into your fork
+
+Upstream keeps improving the methodology files your fork has personalized, so plan for updates from day one:
+
+1. **Commit your personalization to your fork.** `/setup` edits CLAUDE.md and the profile skill files in place — those edits are *yours*, and your fork is private working space, so commit them. The genuinely sensitive files (tracker, salary data, `documents/`, application archives) are gitignored and never enter git either way. An uncommitted working tree is the most common reason `git pull` refuses to merge at all (`Your local changes ... would be overwritten`).
+2. **Preview what changed before pulling:**
+   ```bash
+   git fetch upstream    # or origin, if you cloned the template directly
+   python3 tools/check_upstream_updates.py
+   ```
+   It compares the `framework_version` markers in your framework files against upstream and lists exactly which methodology files changed, with the diff command for each.
+3. **Merge normally.** `git merge upstream/master` (or `git pull`) three-way-merges upstream's edits around your personalization; because methodology edits rarely touch the lines `/setup` filled in, most updates land cleanly. A conflict in a personalized file is a *feature*, not a failure — it means upstream changed methodology in a section you customized, and the version marker plus its changelog commit tell you why. Resolve by keeping your data and adopting the methodology change around it.
+
 ## Troubleshooting
 
 ### "salary_data.json not found"