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
@@ -0,0 +1,73 @@
+---
+type: types/instruction.md
+name: dev-setup
+description: Set up a clone of the origin repository for stack development - preflight, skills, the demo corpus and its persona, telemetry on - and use dist export as a build and test tool, never as a way to install an instance.
+---
+# Set up a development checkout of the stack
+
+A clone of the origin repository is where the stack is developed. It is not an instance: it
+carries a demo corpus that documents the stack itself, a demo persona in `USER.md`/`SOUL.md`, the
+development material under `instructions/dev/` and `commonplace/`, and no
+`.wikitool-release.json`. Instances are installed from releases
+([setup-instance.md](../setup-instance.md)); nothing here produces one.
+
+## When to run
+
+- A fresh clone of the origin repository, before the first stack-dev session in it.
+- A clone that was moved, or whose `tools/.venv` was removed - only step 2 again.
+- Before testing a change to the install path itself (`setup-instance.md`, the preflight, the
+  release workflow) - step 5.
+
+## Steps
+
+1. **Clone** the origin repository. The tree is complete as checked out: `kb/`, `raw/`,
+   `USER.md`, `SOUL.md` and the filled `kb/CONVENTIONS.md` are committed here, unlike in an
+   instance.
+
+2. **Run [bootstrap.md](../bootstrap.md)** - the preflight, then `tools/wikitool instructions
+   sync`. That publishes `stack-dev` and `stack-close` along with the content skills; both exist
+   only in this repository.
+
+3. **Record the environment** (bootstrap.md step 5). Here it is worth the minute: which harness,
+   that `gitea-mcp` reaches the tracker and CI, which remote `publish` talks to. Every stack-dev
+   session reads it instead of asking.
+
+4. **Know what differs from an instance before relying on a default.**
+
+   | Here | In an instance |
+   |---|---|
+   | No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument (`EVALS.md` § "Whether it runs at all") | Telemetry is off until the operator turns it on |
+   | `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
+   | `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
+   | `instructions/dev/`, `commonplace/`, `DEVELOPMENT.md` and `.gitea/` are present | Never shipped |
+
+5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
+   it is how a change to the shipped surface is looked at before it is released:
+
+   ```bash
+   tools/wikitool dist export <empty scratch folder> --dry-run
+   tools/wikitool dist export <empty scratch folder>
+   ```
+
+   To replay the install path the way a user meets it, build the release tarball from that tree
+   the way `.gitea/workflows/release.yml` does (one top-level folder, a `.sha256` beside it) and
+   start the tree's `tools/preflight.sh` as the asset, from an empty folder, with
+   `--archive <tarball>` - the step "The distribution works as a fresh instance" in
+   `.gitea/workflows/ci.yml` is that replay and the reference for it. Keep scratch trees outside
+   this checkout.
+
+## Decision points
+
+- **Asked to set up an instance from this checkout** (`dist export` into the user's folder, or a
+  clone that "becomes" their wiki)? Neither is an install path. An instance is installed from a
+  release, by [setup-instance.md](../setup-instance.md); a stack state that has no release yet is
+  released first, or tested with the replay in step 5 and thrown away.
+- **The demo corpus is in the way of a test?** Do not delete or rewrite corpus content to make
+  room: [corpus-policy.md](corpus-policy.md) says what may be changed and how. Use a scratch
+  export (step 5) for a clean tree instead.
+
+## Scope
+
+Not for operating an instance, and not for the release workflow itself (`DEVELOPMENT.md` for
+humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
+prunes `instructions/dev/` wholesale.
@@ -67,6 +67,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
   demo/testbed `kb/`, the measurable floors that define it, and what a reactive fix may and may
   not do to corpus content. Read it before judging whether the corpus can exercise a change, or
   before any fix that would touch `kb/` content.
+   `instructions/dev/dev-setup.md` - setting up a clone of the origin repo for this work, what
+   differs from an instance there (telemetry on, demo persona, no release stamp), and
+   `dist export` as a build and test tool rather than an install path. Read it in a fresh clone,
+   or before testing a change to the install path.
   `instructions/dev/doc-pull-through.md` - which document makes a claim about a touched
   surface (a `wikitool` command, a stage's rules, an `AGENTS.md` rule/gate/invariant, a
   README-shaped human doc, a `docs/` page's reasoning) and therefore needs updating alongside