feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153)

Files changed: - .gitea/workflows/ci.yml - .gitea/workflows/release.yml - AGENTS.md - CHANGES.md - DEVELOPMENT.md - EVALS.md - INSTALL.md - README.md - VERSION - docs/ownership-and-templates.md - instructions/CONTRACT.md - instructions/bootstrap.md - instructions/dev/dev-setup.md - instructions/dev/stack-dev/SKILL.md - instructions/gates.md - instructions/ingest-large-tree.md - instructions/kb-profiles.md - instructions/mcp-read-server.md - instructions/migrations/3.0.0-authoring-conventions.md - instructions/preflight.md - instructions/private-instance.md - instructions/session-setup.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upstream_cmd.py - tools/chemenu/commands/work_cmd.py - tools/chemenu/config.py - tools/chemenu/ownership.py - tools/chemenu/tests/test_cli.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/tests/test_preflight_pwsh.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_upstream_cmd.py - tools/chemenu/toc.py - tools/preflight.ps1 - tools/preflight.sh
2026-10-01 22:12:09 +02:00
1 parent d0f08d1fba
commit a6d07f97c4
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.

 ---

-## 8.0.0-beta.19 - 2026-10-01 - Windows-Portabilität: Pfadtrenner, Zeilenenden, Encoding und Locks
+## 8.0.0-beta.20 - 2026-10-01 - Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)

 **Author:** Torben Nehmer

@@ -68,8 +68,9 @@ concern - readable here, never shipped as something to parse.
 - publish without --no-push now exits 1 before committing when the remote is unreachable or not configured, where it used to commit locally and fail at the push - an offline session or a local-only instance must pass --no-push
 - new, rename, move and raw accept refuse a target whose path below the instance root is over 160 characters (UTF-16 code units); lint reports existing files over it as Long Paths (advisory) - rename each affected page with tools/wikitool rename, and shorten an incoming/ file name before raw accept
 - tools/wikitool now refuses to start (exit 42) until tools/preflight.sh (PowerShell 7: tools/preflight.ps1) has passed in the checkout - after updating, run it once: it checks Python, git and ripgrep, records their paths in .wikitool-tools.json and sets up tools/.venv
+- An instance is installed only from a release, into an empty folder (instructions/setup-instance.md); dist export, a clone of the origin repo and a private clone with the origin as upstream are no install paths any more, and wikitool upstream merge, upstream verify and instructions/private-instance.md are gone - an instance built one of those ways is reinstalled from a release into an empty folder and its kb/, raw/ and personal files are copied over. The preflight release asset installs into its own folder, which must be empty apart from the script and a .git, instead of creating a chemenu/ subfolder

-**Migration:** none required - No page format changes; the rule only refuses titles, and each affected page is renamed individually with tools/wikitool rename
+**Migration:** none required - No page format changes: the title and path rules only refuse names, each affected page is renamed with tools/wikitool rename, and the removed install paths touch no page

 <!-- wikitool:bumps -->
 **High impact**
@@ -77,6 +78,7 @@ concern - readable here, never shipped as something to parse.
 - dist upgrade --latest: one-command update from the release feed
 - Page titles must form valid, unique file names on Windows and macOS
 - Preflight: prerequisites checked and tool paths recorded before wikitool runs (#151, POSIX half)
+- Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)

 **Medium impact**
 - CalDAV task-tracker provider (Nextcloud Tasks, iOS Reminders); review reports unknown-value findings instead of skipping them
@@ -130,6 +132,63 @@ concern - readable here, never shipped as something to parse.
 - preflight.ps1: the asset-mode error helper is Exit-Asset, so PSScriptAnalyzer passes
 <!-- /wikitool:bumps -->

+### Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)
+
+The install run analysed in Gitea #140 failed on an instruction that contradicted itself, and the
+path it took (Weg D, a private clone with this repo as `upstream`) was one of four. All four were
+cut down to one (D2, D3): an instance is installed from the latest release into an empty folder,
+`dist export` is a build tool, and a clone of this repository is development. None of the removed
+paths was in use, so the break has no transition.
+
+- **Removed.** `wikitool upstream merge` and `upstream verify` (`commands/upstream_cmd.py` and its
+  tests, the "Private instances" group of command records) and `instructions/private-instance.md`.
+  Every reference in the shipped tree goes with them; `ownership.is_stack_owned` stays, because
+  `dist export` uses it. The 3.0.0 migration document dates its reference in words. The
+  Publish-Remote Gate stays: any checkout with two remotes needs it, and only its rationale lost
+  the reference to the removed path. `gates.md` loses its section on `upstream merge` bypassing
+  the Mass-Update Gate.
+- **The install path.** `instructions/setup-instance.md` starts at the release: it is attached
+  to every release as an asset, together with `instructions/preflight.md` (E1), and the
+  installation sentence in `INSTALL.md` points the agent at both through the API's
+  `releases/latest` - Gitea 1.26 has no stable "latest" download link. Step 0 downloads the
+  preflight asset with the shell's own command (E2, so no Mark of the Web) and runs it with the
+  bypass prefix. The export step is gone, `git init` runs only where there is no repository yet,
+  and an empty clone keeps its `origin`. The steps are renumbered; references to the
+  personalization step name it rather than its number.
+- **The preflight asset installs in place (E6, changes D40).** It installs into its own folder,
+  which has to be empty apart from the script and a `.git`, unpacks into a temporary folder
+  inside it, moves the stack up and removes itself, so the first commit carries the stack and
+  nothing else. `--into` installs elsewhere under the same rule. A non-empty target is refused
+  with exit 1. Tests cover both shells, an empty clone, and the self-removal. Under bash the
+  folder-too-long guidance printed `C:\\Chemenu` with a doubled backslash; it now prints one.
+- **`wikitool dist adopt` (E3).** Copies `kb/*/COLLECTION.md.template` and `types/*.template` to
+  their unsuffixed names, never over an existing file. It replaces the `for … cp` loop in
+  `setup-instance.md`, the two `cp` lines in `upgrade-instance.md` and the loop in the CI replay.
+- **Shell-neutral instructions (E4).** A command block in a shipped instruction is a
+  `tools/wikitool` or `git` call or the preflight's own call; `instructions/CONTRACT.md` states
+  it, and `tests/test_instructions_shell.py` holds it, with two exceptions of one line per shell:
+  the session id (D26) and the preflight download (E2). Migration documents are out of scope.
+  The same test checks that every PowerShell preflight call in a shipped file carries
+  `pwsh -NoProfile -ExecutionPolicy Bypass -File`. `session-setup.md` loses the bash-only inline
+  form and the `$(date +%s)` id; `upgrade-instance.md`, `ingest-large-tree.md` and
+  `mcp-read-server.md` follow, as does the hint `work new` prints.
+- **Session id under Copilot (E5).** Neither Copilot CLI nor Copilot's agent mode in VS Code sets
+  a session variable (checked against their documentation), so `session.HARNESS_ENV_VARS` is
+  unchanged. `setup-instance.md` has the agent set `WIKITOOL_SESSION_ID` with the line for its
+  shell before `doctor`, and `session-setup.md` says why.
+- **CI.** The replay builds a release tarball the way `release.yml` does and starts the preflight
+  asset with `--archive` in an empty folder (D41). It no longer asserts the launcher's exit 42
+  before the preflight - the asset runs the tree preflight itself, and the launcher's refusal is
+  tested in `test_preflight.py`. `release.yml` attaches `setup-instance.md` and `preflight.md`
+  from the exported tree.
+- **Docs.** `INSTALL.md` describes one path: what has to be there first (Windows: PowerShell 7,
+  `RemoteSigned`, Git for Windows, a folder of at most 95 characters), the sentence for the
+  agent, the questions it asks, and what to do at every stop of the preflight in both modes.
+  `DEVELOPMENT.md` gains the development checkout, `dist export` as a build and test tool, and the
+  private release feed that used to sit in `INSTALL.md`; `instructions/dev/dev-setup.md` is its
+  agent-side counterpart. `bootstrap.md` is for a further checkout of an existing instance (D11).
+  `docs/ownership-and-templates.md` records why an instance comes only from a release.
+
 ### Windows-Portabilität: Pfadtrenner, Zeilenenden, Encoding und Locks

 The Python package assumed POSIX in several places that nothing on Linux would ever reveal