docs(releases): add CHANGELOG + release-based update guidance; sharpen real-path bar (#225)

Addresses #213 (how to keep up with a fast-moving upstream) and closes the
verification loophole surfaced in the 2026-07-22 triage audit.

- Add CHANGELOG.md (Keep a Changelog + semver), with v1.0.0 as the first
  tagged baseline and an Unreleased section for going forward.
- SETUP.md section 8: recommend updating to a tagged release (a vetted,
  described checkpoint) over pulling raw master; fetch --tags and merge a tag.
- README: add a "Staying up to date" pointer to Releases, the CHANGELOG, and
  check_upstream_updates.py.
- CONTRIBUTING.md: sharpen "Claims get verified" - a test that distinguishes
  master from the fix is necessary but not sufficient; the failing input must
  be one the workflow actually produces, not one the test hand-builds. Fixes
  demonstrated only through a synthetic input the real code path never receives
  get declined even when their test is green.

Note: the git tag / GitHub Release for v1.0.0 is intentionally left for the
maintainer to cut.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Releases are vetted checkpoints of `master`. If you maintain a personalized fork,
+prefer updating to a tagged release over pulling raw `master` (see
+[SETUP.md, section 8](SETUP.md#8-pulling-upstream-updates-into-your-fork)). The
+`framework_version` markers on methodology files tell you which of your customized
+files a release touched; `python3 tools/check_upstream_updates.py` lists them with
+per-file diff commands.
+
+## [Unreleased]
+
+_Changes landed on `master` since the last release will be listed here._
+
+## [1.0.0] - 2026-07-22
+
+First tagged release. This marks the framework as stable and gives forks a described
+checkpoint to update against instead of a moving `master`. It is a baseline of what
+already exists rather than a set of new changes; subsequent releases will document
+what changed since the previous tag.
+
+At this baseline the framework provides:
+
+- **Application workflow** - a drafter/reviewer `/apply` pipeline (CV + cover letter),
+  plus `/setup`, `/scrape`, `/rank`, `/interview`, `/outcome`, `/upskill`,
+  `/expand`, `/html-report`, `/gmail-sync`, `/notion-sync`, `/add-portal`,
+  `/add-template`, and `/reset`.
+- **Portal search skills** - country-agnostic job-board CLIs (LinkedIn, freehire, and
+  the Danish boards) in the portable Agent Skills format under `.agents/skills/`,
+  discovered and orchestrated by `/scrape`, with an `enabled:` toggle for skipping
+  portals.
+- **Framework versioning** - `framework_version` markers on methodology files plus
+  `tools/check_framework_version.py` (CI guard) and `tools/check_upstream_updates.py`
+  (fork-side update preview).
+- **Privacy and safety guards** - `.gitignore` protection for personal data, the
+  `tools/security_guards.py` allowlist for `.gitignore` negations, and a CI policy of
+  making no live portal requests.
+- **Cross-runtime support** - a root `AGENTS.md` pointer so Codex and Antigravity can
+  discover the portable portal skills, with Claude Code as the reference runtime.
+
+[Unreleased]: https://github.com/MadsLorentzen/ai-job-search/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/MadsLorentzen/ai-job-search/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -32,6 +32,7 @@ A new command therefore faces a high bar. The test that admitted the existing on
 Reviews here are empirical. Bug reports are reproduced on master before the fix is considered; "all tests green" is checked against whether the tests can distinguish master from the fix. PRs whose premise doesn't reproduce get declined even when the code is fine - it has happened ([#35]'s converter fix, [#52]'s first version). You can make this fast:
 
 - State the failing case and how to reproduce it.
+- **Reproduce on the real path, not a constructed input.** A test that fails on master and passes on the fix is necessary but not sufficient: the failing input has to be one the workflow actually produces, not one the test hand-builds. Show the failure through the path the code really runs - the documented CLI invocation, real portal output, an actual data file - not a synthetic value fed straight to the function. A fix whose only demonstration is an input the real code path never receives gets declined even though its test is green.
 - Put CLI tests in `.agents/skills/<name>/cli/tests/` (bun test, network-free where possible); Python tool tests in `tests/`.
 - Run what CI runs: `python3 tools/lint_skills.py`, `python3 tools/check_framework_version.py`, `bun run typecheck` in touched CLIs, and the relevant test suites.
 

README.md

@@ -318,6 +318,10 @@ To wipe your profile data and start fresh:
 
 `/reset` shows exactly what will be deleted and requires you to type `RESET` to confirm. Nothing is deleted until you do.
 
+### Staying up to date
+
+Upstream moves fast. Rather than pulling raw `master` and hoping, update your fork to a tagged [release](../../releases) - a vetted checkpoint described in [CHANGELOG.md](CHANGELOG.md). `python3 tools/check_upstream_updates.py` previews exactly which of your personalized files an update touches before you merge. Full walkthrough in [SETUP.md, section 8](SETUP.md#8-pulling-upstream-updates-into-your-fork).
+
 ## Tips for better results
 
 ### Profile depth matters

SETUP.md

@@ -288,6 +288,8 @@ These commands apply to the stock templates (moderncv CV, `cover.cls` cover lett
 
 Upstream keeps improving the methodology files your fork has personalized, so plan for updates from day one:
 
+**Prefer releases over raw `master`.** Tagged [releases](../../releases) are vetted checkpoints, each described in [CHANGELOG.md](CHANGELOG.md). Updating to a tag pulls a stable, documented state instead of whatever `master` happens to be mid-review. Fetch tags with `git fetch upstream --tags` and merge a release (for example `git merge v1.0.0`) when you want stability; pull `master` directly only when you specifically want the latest unreleased changes. The steps below apply either way - substitute the release tag for `upstream/master` where you see it.
+
 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