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, stack-build and stack-close along with the content skills; all three 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 (telemetry-and-evaluation.md)	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/, docs/dev/, commonplace/ and .gitea/ are present	Never shipped
   testfiles/ may hold the private test corpus (step 6)	Never present

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.

6. Clone the private test corpus, if you have access. The real documents the converters are tested against, and the harness that runs them, are a repository of their own and not part of this one:

   git clone ssh://git@gitea.nehmer.net:10101/torben/chemenu-testfiles.git testfiles
   cd tools && .venv/bin/python -m pytest -c pytest.ini ../testfiles/harness
   

   The clone sits in testfiles/, which .gitignore excludes; it is deliberately not a submodule. Without access nothing breaks: pytest in tools/ needs none of it, and a session that changes a converter leaves the real-document run to the converters workflow (publish-and-ci.md step 3). What is missing without the clone is the local run of that harness, nothing else. The corpus holds files that may not be public, so nothing from it is copied into this repository, an issue or a bug report without its README saying the file could be public.

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 (docs/dev/development.md for humans, version-parts.md for the version part). Not shipped: dist export prunes instructions/dev/ wholesale.