From 49f8939bfda42f1134c9ad37fd4acfedda44f0d3 Mon Sep 17 00:00:00 2001
From: Torben Nehmer <torben@nehmer.net>
Date: Wed, 7 Oct 2026 16:19:56 +0200
Subject: [PATCH] docs(tools): README describes the asset mode as it is - own
 folder, retry, rollback (#197)

tools/README.md still said the asset unpacks into <script folder>/chemenu and
refuses an existing target, which stopped being true before #197; it now also
describes the retry and the rollback #197 added.

Files changed:
- CHANGES.md
- VERSION
- tools/README.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
---
 CHANGES.md      |  3 ++-
 VERSION         |  2 +-
 tools/README.md | 12 ++++++++----
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9c7ae1e..8c6ef95 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,7 +14,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
 
 ---
 
-## 9.0.0-beta.11 - 2026-10-07 - Asset-Preflight: Verschieben aus dem Entpackordner wird bis ca. 30 s wiederholt, nennt die Systemmeldung und rollt nach endgültigem Scheitern zurück
+## 9.0.0-beta.12 - 2026-10-07 - tools/README.md: Asset-Modus beschreibt Entpacken in den eigenen Ordner, Wiederholung und Zurückrollen
 
 **Author:** Torben Nehmer
 
@@ -41,6 +41,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
 - AGENTS.md routing line and a toc.py docstring describe docs/ as the whole human documentation
 - tools/README.md module tree names reference_doc.py and the fourth view cli_contract renders
 - Rebase-Review Gate: Anzeigename in Hilfe- und Fehlertexten von sync und publish angeglichen
+- tools/README.md: Asset-Modus beschreibt Entpacken in den eigenen Ordner, Wiederholung und Zurückrollen
 <!-- /wikitool:bumps -->
 
 ### Tutorials: installation in English, and a first source to a first answer (#191)
diff --git a/VERSION b/VERSION
index 9ec2163..7c4757e 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-9.0.0-beta.11
+9.0.0-beta.12
diff --git a/tools/README.md b/tools/README.md
index 893f35f..9c1d28a 100644
--- a/tools/README.md
+++ b/tools/README.md
@@ -38,10 +38,14 @@ placeholder lines of the copy (`RELEASE_ARCHIVE_URL`/`RELEASE_CHECKSUM_URL` in t
 `$ReleaseArchiveUrl`/`$ReleaseChecksumUrl` in the PowerShell one; the tree copy leaves them
 empty). With no `prerequisites.txt` beside it, the script is in *asset mode*: it downloads the
 tarball and its `.sha256`, refuses on a mismatch, reads the folder limit out of the archive,
-unpacks into `<script folder>/chemenu` (`--into <path>` to choose, an existing target is refused),
-and runs the tree copy of itself, passing `--set` and its exit code through. `--archive <tarball>`
-takes a local tarball instead of a download (its `.sha256` has to lie next to it); that is also
-how the tests drive it.
+unpacks into the folder it lies in (`--into <path>` to choose; a target holding anything but the
+script and a `.git` is refused), and runs the tree copy of itself, passing `--set` and its exit
+code through. It unpacks into a `.chemenu-unpack.<pid>` folder inside the target and then moves
+each top-level entry up; a move that fails is retried for about 30 seconds, each time from a
+fresh copy of the entry out of the archive, and one that still fails makes the script take back
+everything it moved before it exits 1. `--archive <tarball>` takes a local tarball instead of a
+download (its `.sha256` has to lie next to it); that is also how the tests drive it, and
+`CHEMENU_PREFLIGHT_MOVE_FAIL` stands in for a move that fails.
 
 `tools/wikitool` refuses to start (exit 42) until the preflight has written a
 *complete* `.wikitool-tools.json` and the venv exists. Past that, every `git`