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
@@ -42,7 +42,6 @@ file end to end is for changing the CLI itself.
  - [Telemetry](#telemetry)
  - [Distribution and versioning](#distribution-and-versioning)
  - [Content migrations](#content-migrations)
-  - [Private instances](#private-instances)
  - [Instance health](#instance-health)
 - [Design notes](#design-notes)
 - [Tests](#tests)
@@ -137,6 +136,7 @@ docs contract         write idempotent     budget:counted              exit:0,1
 eval sessions         read  idempotent     budget:exempt               exit:0      List the sessions that have a trace under `reports/telemetry/`.
 eval score            read  idempotent     budget:exempt               exit:0,1    Score one traced session.
 dist export           write idempotent     budget:counted              exit:0,1    Write a contentless, distributable copy of this repo's machinery.
+dist adopt            write idempotent     budget:counted              exit:0,1    Take shipped templates as this instance's own: copy each to its unsuffixed name.
 dist upgrade          write non-idempotent budget:counted              exit:0,1    Apply a stack update `dist export` produced - the write half of `version check`.
 version show          read  idempotent     budget:exempt               exit:0,1    Print this instance's stack version and where it came from.
 version check         read  idempotent     budget:exempt               exit:0,1    Ask the origin's release feed whether a newer stack exists.
@@ -149,8 +149,6 @@ migrate status        read  idempotent     budget:exempt               exit:0,1
 migrate verify        read  idempotent     budget:exempt               exit:0,1    Compare `kb/` against a git revision on the invariants a content migration must not change.
 migrate done          write non-idempotent budget:counted              exit:0,1    Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
 migrate baseline      write idempotent     budget:counted              exit:0,1    Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
-upstream merge        write non-idempotent budget:counted              exit:0,1    Take a stack update into a private instance's branch, machinery only.
-upstream verify       read  idempotent     budget:exempt               exit:0,1    Compare two revisions: did anything under a content stage change except through a stack-owned path?
 doctor                read  idempotent     budget:exempt               exit:0,1    Check that this instance is correctly configured.
 ```

@@ -2437,15 +2435,66 @@ Write a contentless, distributable copy of this repo's machinery.
 - Ships templates, never the filled files: `USER.md.template`/`SOUL.md.template`, `kb/CONVENTIONS.md.template`, and each collection's contract re-keyed as `kb/<name>/COLLECTION.md.template`. The filled `USER.md`/`SOUL.md`/`kb/CONVENTIONS.md`/`kb/<name>/COLLECTION.md`/`types/<page-type>.md` bind their instance; `find_leaks` refuses a plan carrying one.
 - Writes a generated `.wikitool-release.json` stamp: version, export date, origin, and a sha256 per exported file - the base a later upgrade compares against.
 - The four origin options only fill stamp fields: `export` never calls git and cannot discover them.
- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in the origin repo, or in a new dev instance exported from it.
+- A build and test tool: every release is an export packed as a tarball, and an instance is installed from such a release, never from an export directly.
+- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in a clone of the origin repo.
 - `--dry-run` lists every file it would write, and writes nothing.

 **SEE ALSO**

- `instructions/setup-instance.md` - what comes after the export
+- `instructions/setup-instance.md` - installs a release, which is this export as a tarball
 - `wikitool dist upgrade` - applies a later export to an existing instance
 - `wikitool version show` - reads the stamp this writes

+#### `dist adopt`
+
+Take shipped templates as this instance's own: copy each to its unsuffixed name.
+
+**SYNOPSIS**
+
+- `wikitool dist adopt [<template>...] [--dry-run]`
+
+**PROPERTIES**
+
+- effect: write
+- idempotent: yes
+- atomic: No - files are copied one by one; a re-run completes an interrupted one
+- budget: counted
+- network: no
+
+**EXAMPLES**
+
+- `tools/wikitool dist adopt`
+- `tools/wikitool dist adopt types/project.md.template types/project.schema.yaml.template`
+- `tools/wikitool dist adopt --dry-run`
+
+**EXIT STATUS**
+
+- 0    success
+- 1    A named path does not exist, or is not a collection contract or page type-spec template
+
+**ON FAILURE**
+
+- A named path does not exist, or is not a collection contract or page type-spec template -> Not transient - name a template from the set in NOTES, or call it without a path
+
+**NEVER**
+
+- Never delete a target to make `dist adopt` replace it - a filled file is the instance's own work.
+
+**NOTES**
+
+- Copies `<name>.template` to `<name>` byte for byte; the template stays where it is, as the base the next `dist upgrade` compares against.
+- Without a path: every `kb/<collection>/COLLECTION.md.template` and every `types/*.template` (the `root: kb` page type-specs and their schemas).
+- With paths: exactly those templates, each of which has to be one of the set above.
+- Never overwrites: a target that already exists is reported as kept and left untouched.
+- Not for `kb/CONVENTIONS.md.template` or the personalization templates - those carry a sentinel and are filled in, not copied.
+- `--dry-run` lists what it would copy and keep, and writes nothing.
+
+**SEE ALSO**
+
+- `instructions/setup-instance.md` - adopts every template on a fresh instance
+- `instructions/upgrade-instance.md` - adopts a template a release added
+- `wikitool dist export` - re-keys these files as `.template` in the first place
+
 #### `dist upgrade`

 Apply a stack update `dist export` produced - the write half of `version check`.
@@ -2492,7 +2541,7 @@ Apply a stack update `dist export` produced - the write half of `version check`.
 **ON FAILURE**

 - Both `<source>` and `--latest`, or neither; or `--expect` without `--latest` -> Not transient - name exactly one source, and pass `--expect` only with `--latest`
- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A checkout with shared git history takes stack updates with `wikitool upstream merge` instead
+- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A clone of the origin repo is a development checkout and takes no `dist upgrade` at all
 - `.wikitool-kb.json` is missing -> Run `wikitool migrate baseline <version>`, then retry
 - A migration is already outstanding against the *installed* machinery -> Finish it first - `wikitool migrate status` names it - then retry
 - The working tree is dirty -> Commit or stash first, then retry
@@ -2537,7 +2586,6 @@ Apply a stack update `dist export` produced - the write half of `version check`.
 - `wikitool version notes` - the notes of the release `--expect` should name
 - `instructions/upgrade-instance.md` - the order after the swap
 - `INSTALL.md` § "Version und Updates" - which release, whether to take it, where the tarball comes from
- `wikitool upstream merge` - the update path for a checkout with shared git history
 - `wikitool migrate status` - the migrations the report names

 #### `version show`
@@ -3081,118 +3129,6 @@ Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
 - `wikitool migrate done` - advances the version after a migration
 - `wikitool migrate status` - what is owed from the declared version

-### Private instances
-
-#### `upstream merge`
-
-Take a stack update into a private instance's branch, machinery only.
-
-**SYNOPSIS**
-
- `wikitool upstream merge [--remote upstream] [--branch main] [--no-fetch]`
-
-**PROPERTIES**
-
- effect: write
- idempotent: no
- atomic: **No** - can leave an open, uncommitted merge behind on refusal after fetching
- budget: counted
- network: yes
-
-**EXAMPLES**
-
- `tools/wikitool upstream merge`
- `tools/wikitool upstream merge --remote upstream --branch main --no-fetch`
-
-**EXIT STATUS**
-
- 0    success
- 1    Dirty working tree, or a merge already in progress
- 1    The remote does not resolve, the fetch failed, or `HEAD` does not resolve
- 1    git refused to open the merge at all (unrelated histories); nothing was touched
- 1    A real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored; the merge is left open
- 1    A git step failed inside the open merge (`git checkout MERGE_HEAD -- <path>` or `git commit --no-edit`)
- 1    The postcheck after the commit found a leak; the merge commit already exists
-
-**ON FAILURE**
-
- Dirty working tree, or a merge already in progress -> Fix the named precondition and retry once
- The remote does not resolve, the fetch failed, or `HEAD` does not resolve -> Fix `--remote`/`--branch` or the repository state, then retry once
- git refused to open the merge at all (unrelated histories); nothing was touched -> Do not retry unchanged - report it to the user
- A real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored; the merge is left open -> **Do not retry, do not force** - resolve the named paths by hand (take the upstream side, or re-file the local change as an issue against the public repo per `instructions/private-instance.md`) and either `git commit --no-edit` yourself or `git merge --abort`
- A git step failed inside the open merge (`git checkout MERGE_HEAD -- <path>` or `git commit --no-edit`) -> Do not retry unchanged - inspect the open merge by hand
- The postcheck after the commit found a leak; the merge commit already exists -> It is **not** rolled back automatically - inspect it by hand; this is a bug report, not a retry
-
-**NEVER**
-
- Never retry a failed merge unchanged, and never force.
-
-**NOTES**
-
- Refuses on a dirty working tree, a merge already in progress, or a remote that does not resolve. WARNs (does not block) when `.wikitool-remotes.json` is absent, pointing at the setup step that arms it.
- Fetches `<remote>/<branch>` (unless `--no-fetch`) and reports "already up to date" if nothing new exists.
- Otherwise opens `git merge --no-commit --no-ff <remote>/<branch>`, and stops, untouched, if git refused to open a merge at all (unrelated histories).
- Forces every content stage (`kb/`, `raw/`, `work/`, `reports/`) back to the local side by removing **only the paths tracked in either tree** and checking `HEAD`'s back out - never the stage directory wholesale, so untracked and ignored local data under a stage (telemetry traces, saved eval and lint reports) is never deleted.
- Then restores from the upstream side exactly the machinery paths - `<stage>/CONTRACT.md` and anything ending `.template` under a content stage - including a deletion, if the upstream removed one.
- A real conflict left in `tools/`, `types/` or `instructions/` after that leaves the merge open, uncommitted, and exits 1 rather than guessing.
- Commits with `git commit --no-edit`, then re-checks the resulting range with the `upstream verify` check; a finding there is a loud error, and the merge commit is not rolled back.
- Never pushes.
- Not idempotent, and not safe to retry unchanged.
-
-**SEE ALSO**
-
- `instructions/private-instance.md` § "Taking a stack update" - the procedure this implements
- `wikitool upstream verify` - the same check on any revision range
- `wikitool publish` - pushes the merge afterwards
-
-#### `upstream verify`
-
-Compare two revisions: did anything under a content stage change except through a stack-owned path?
-
-**SYNOPSIS**
-
- `wikitool upstream verify --since <rev> [--until HEAD]`
-
-**PROPERTIES**
-
- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no
-
-**EXAMPLES**
-
- `tools/wikitool upstream verify --since HEAD~1`
- `tools/wikitool upstream verify --since v7.0.0 --until HEAD`
-
-**EXIT STATUS**
-
- 0    success
- 1    A leak: content changed under a content stage through a path that is not stack-owned
- 1    `--since`/`--until` is not a revision in this repository
-
-**ON FAILURE**
-
- A leak: content changed under a content stage through a path that is not stack-owned -> A finding is not fixed by re-running - it names the paths that leaked
- `--since`/`--until` is not a revision in this repository -> Fix the revision argument and retry
-
-**NEVER**
-
- Never re-run to make a leak finding go away.
-
-**NOTES**
-
- Compares `--since` with `--until` (default `HEAD`): did anything under a content stage change except through a stack-owned path?
- The same check `upstream merge` runs after its commit, so a hand-resolved merge conflict, or a `dist upgrade`, can be verified the same way.
- Exits 1 with the offending paths if anything leaked; otherwise reports which stack-owned paths legitimately moved.
- Read-only and exempt from the Iteration Budget Gate.
-
-**SEE ALSO**
-
- `wikitool upstream merge` - runs this check after its commit
- `instructions/private-instance.md` - the private-instance workflow
-
 ### Instance health

 #### `doctor`