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