fix: private-instance - Demo-Korpus wandert beim Merge mit, Prozedur korrigiert (2.2.1)

Files changed:
- CHANGES.md
- VERSION
- instructions/private-instance.md

instructions/private-instance.md

@@ -25,9 +25,24 @@ merge, so it cannot notice that the receiving instance changed a file, and it ha
 surface, so nobody learns when upstream and local both touched the same one. It overwrites
 silently.
 
-A clone gets all of that from git. The private `main` deletes the upstream's demo corpus once;
-every later `git merge upstream/main` sees *deleted-in-ours, unmodified-in-theirs* and resolves
-without asking. Stack changes land as real merges, with real conflicts where they conflict.
+A clone gets all of that from git. Stack changes land as real merges, with real conflicts where
+they conflict.
+
+**What a plain `git merge` does *not* give you is protection from the upstream's content.** The
+private `main` deletes the demo corpus once, but that deletion does not make later upstream
+changes to those paths go away. Measured, not assumed:
+
+| Upstream does | `git merge upstream/main` does |
+|---|---|
+| modifies a page you deleted | `CONFLICT (modify/delete)` - and **leaves the upstream version in your working tree**. Resolve it with `git add -A` and the demo page is back. |
+| adds a new page | stages it **silently**. No conflict, no prompt, no mention. |
+| deletes a page you also deleted | nothing. The only harmless case. |
+
+The middle row is the one that matters, because nothing announces it. An upstream that ships a
+demo corpus *and* uses it as a test bed will add pages, and each one arrives in your instance
+and starts showing up in your `lint`, your `index`, your `search` and your `confidence decay`.
+
+So the merge has to be scoped. That is the procedure below, and it is not optional.
 
 ## Steps
 
@@ -87,15 +102,43 @@ without asking. Stack changes land as real merges, with real conflicts where the
 
 ## Taking a stack update
 
+Take the machinery, never the content. The merge is held open, the content stages are forced
+back to your own state, and only then does it close:
+
 ```bash
+BEFORE=$(git rev-parse HEAD)
 git fetch upstream
-git merge upstream/main
+
+# --no-commit holds the merge open; it may report conflicts under kb/ or raw/,
+# which the next three lines are about to make irrelevant.
+git merge --no-commit --no-ff upstream/main || true
+
+# Whatever the merge did to the content stages, undo it. HEAD is still your
+# pre-merge commit while the merge is open, so this restores exactly your side.
+git rm -rq --cached --ignore-unmatch kb raw
+rm -rf kb raw
+git checkout HEAD -- kb raw
+
+git commit --no-edit
 ```
 
+Then **check that it worked**, rather than trusting that it did:
+
+```bash
+git diff --name-only $BEFORE HEAD -- kb raw     # must print nothing
+```
+
+An empty result is the proof that the update touched machinery only. A non-empty one means a
+path slipped through - inspect it before going further.
+
 Then, as after any stack change: `doctor`, `docs verify`, `instructions verify`, `migrate status`,
 `lint`. A `migrate status` with outstanding links means the update crossed a compatibility
 boundary - follow [migrate-corpus.md](migrate-corpus.md) before doing anything else.
 
+**Why not just `git merge upstream/main`?** Because of the table above: a page the upstream
+*adds* arrives with no conflict and no message. You would find out when `lint` starts reporting
+pages you never wrote - if you noticed at all.
+
 ## Where stack development happens
 
 **In the public repo, not here.** That is not a preference; the stack is built that way. The
@@ -110,9 +153,12 @@ merge above. Nothing is lost by the detour: the fix has to pass that CI either w
 
 ## Decision points
 
-- **Merge conflict in `kb/` or `raw/`?** Something changed the upstream's corpus after you cut
-  it. Resolve as "keep deleted" - your instance's content is yours, and the upstream's demo
-  corpus has no business in it.
+- **Merge conflict in `kb/` or `raw/`?** Expected, and already handled: the update procedure
+  above overwrites those stages with your own afterwards, so the conflict resolves itself.
+  Never resolve one by hand with `git add -A` - that is exactly how the upstream version, which
+  git left sitting in your working tree, gets committed into your instance.
+- **`git diff` after the merge shows something under `kb/` or `raw/`?** Stop. The scoping step
+  did not take. Do not publish; find out which path came through and where from.
 - **Conflict in `tools/`, `types/` or `instructions/`?** You changed the stack locally, which
   step "Where stack development happens" says not to do. Take the upstream side and re-file the
   change as an issue there.