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.
This commit is contained in:
Mads Lorentzen
2026-07-17 22:05:43 +02:00
committed by GitHub
parent da2c3bbec9
commit d2e14418ca
+16 -3
View File
@@ -124,16 +124,16 @@ Run these from the repository root.
```powershell ```powershell
$tools = @("jobbank-search", "jobdanmark-search", "jobindex-search", "jobnet-search", "linkedin-search", "freehire-search") $tools = @("jobbank-search", "jobdanmark-search", "jobindex-search", "jobnet-search", "linkedin-search", "freehire-search")
foreach ($tool in $tools) { foreach ($tool in $tools) {
Set-Location ".agents/skills/$tool/cli" Push-Location ".agents/skills/$tool/cli"
bun install bun install
Set-Location "..\..\..\.." Pop-Location
} }
``` ```
- Bash / zsh / Git Bash: - Bash / zsh / Git Bash:
```bash ```bash
for tool in jobbank-search jobdanmark-search jobindex-search jobnet-search linkedin-search freehire-search; do 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 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. 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 ## Troubleshooting
### "salary_data.json not found" ### "salary_data.json not found"