chemenu/instructions/dev/dev-setup.md

type, name, description

type	name	description
types/instruction.md	dev-setup	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); 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 - 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:

   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; 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 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 for the version part). Not shipped: dist export prunes instructions/dev/ wholesale.