---
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`, `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](../../docs/explanation/telemetry-and-evaluation.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/`, `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:

   ```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.

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:

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