chemenu/instructions/setup-instance.md

---
type: types/instruction.md
name: setup-instance
description: Turn a fresh distribution (from `dist export`) into a working, self-contained wiki instance - git repo, identity/author, optional remote, bootstrap, first commit.
---

# Set up a new wiki instance

This instruction takes an empty distribution produced by `tools/wikitool dist export <target>`
and turns it into a working, self-contained wiki instance - with its own git repo, its own
author identity and (optionally) its own remote. At the end the instance is committed, verified
and ready for its first ingest.

<!-- wikitool:toc -->
## Contents

- [When to run](#when-to-run)
- [Steps](#steps)
- [Scope](#scope)
<!-- /wikitool:toc -->

## When to run

- The user wants to set up a new, empty wiki instance (their own subject, a different person).
- Not for an existing clone of this (source) repo - see [bootstrap.md](bootstrap.md).
- There is no way back: `dist export` deliberately and permanently leaves out
  `instructions/dev/` (stack development itself, including the vendored `commonplace/` knowledge
  base). Anyone who wants to develop the resulting instance's stack further does that in the
  origin repo (or a new dev instance made from it) - not by retrofitting it into this instance.

## Steps

1. **Export the distribution**, in the source repo:

   ```bash
   tools/wikitool dist export <target>
   ```

   `<target>` must not exist, or must be empty; otherwise the command aborts with `ERROR`. Work
   inside `<target>` for every step that follows.

2. **Initialize the git repo:**

   ```bash
   git init -b main
   ```

   `-b main` is mandatory: on the actual push, `tools/wikitool publish` checks that the
   checked-out branch matches the target branch (default `main`) and refuses otherwise, so that
   the wrong branch is never published.

3. **Decision point - identity.** Ask the user for their name and email address; never guess
   them, and never quietly carry them over from the source repo (that is a different person and
   a different project):

   ```bash
   git config user.name "<name>"
   git config user.email "<email>"
   ```

   This also sets the author of every wiki page created from now on: `tools/wikitool new`
   resolves `author:` from `$WIKI_AUTHOR` (an override) or else from `git config user.name`, and
   aborts with `ERROR` when both are missing - there is no silent placeholder.

4. **Decision point - remote.** Ask the user for a remote URL; a purely local repo is a valid
   end state:
   - Given: `git remote add origin <url>`
   - Not given: stay local - then **every** later `tools/wikitool publish` needs a `--no-push`
     (which also drops its branch check, see step 2).

5. **Decision point - authoring conventions.** The distribution ships no filled-in conventions,
   only `kb/CONVENTIONS.md.template` and one `kb/<name>/COLLECTION.md.template` per collection.
   Both **bind** once adopted, and both belong to this instance - which is why the stack ships
   the template alone. The one decision behind them is: **in which language and in what tone
   does this instance write its pages?**

   Procedure:

   1. Adopt the collection contracts **and the page type-specs** - copies, no question to the
      user, because what they say is usable as a starting point regardless of language:

      ```bash
      for template in kb/*/COLLECTION.md.template types/*.template; do
        cp "$template" "${template%.template}"
      done
      ```

      The `.template` files stay where they are; they are the source for the next export.

      Under `types/` this covers exactly the type-specs with `root: kb` - `entity`, `concept`,
      `source`, `comparison` - along with their `.schema.yaml`. They describe pages *this*
      instance writes, so they belong to it: prose, template and language may all be rewritten.
      `instruction`, `lint-report` and `type-spec` describe stack artifacts and arrive
      unchanged.

   2. Ask the user for the KB language. `kb/CONVENTIONS.md.template` defaults to **English**;
      [kb-profiles.md](kb-profiles.md) additionally holds a complete German profile, whose full
      text is the source repo's own `kb/CONVENTIONS.md`. The profile catalogue is a **palette,
      not an enum**: what gets adopted is the text *into* the instance file, not a reference to
      the catalogue.

   3. Copy `kb/CONVENTIONS.md.template` to `kb/CONVENTIONS.md`, fill it in along the chosen
      profile - language, section names, naming forms, tone, relationship labels, hedging rule -
      and remove the sentinel line (`wikitool:template-unfilled`) while doing so. The
      placeholders in curly braces **are** the list of questions.

   4. For a language other than the source repo's: delete `german-terminology.md` or replace it
      with your own vocabulary - it is material belonging to the German profile, not to the
      stack.

   5. Ask the user about the subject area and derive a `source_type` proposal from it.
      [kb-profiles.md](kb-profiles.md) holds two worked domain profiles as illustration, beside
      the value this repo uses itself. The proposal is a **starting point, not a commitment** -
      at setup time the operator has zero sources and is guessing a taxonomy before having seen
      a single file, which is the worst possible moment to pin an enum down. Carrying out the
      proposal means setting the enum in `types/source.schema.yaml` **and** the matching
      `layout:` line per value in `types/source.md` in the same edit - one without the other
      leaves a value with no target directory. The visible catch-all (`unclassified`) survives
      every proposal; it is not a dumping ground but the slot for a source whose category is not
      settled yet. Extending the list later, or emptying that slot:
      [evolve-subtypes.md](evolve-subtypes.md) - not part of this step, but the way there once
      real material exists.

      **Leave unchanged:** `fidelity` and `authority` on `source` pages. Those are stack
      vocabulary, not an instance decision - [kb-profiles.md](kb-profiles.md) says so in the
      same section.

   **Decide before the first ingest.** The `sections:` names in `kb/CONVENTIONS.md` are the
   headings `xref` and `cite` write into every page; changing them afterwards is a migration of
   every existing page (`section_aliases:` carries the old names, see
   [migrate-corpus.md](migrate-corpus.md)).

   **None of this lives in a stack file.** The compiler reads the section names from
   `kb/CONVENTIONS.md`; the four page type-specs have belonged to this instance since step 1. An
   instance in another language simply translates them - that is no longer a local patch to
   something shipped, but work on its own files, and an upgrade does not take it away again.

   What the stack still requires of `types/` is one line: there must be a type-spec with
   `name: source` whose schema requires `raw_files`. The entire `raw/`→`kb/` provenance path
   hangs on it (`sources coverage`, `[^cite-id]` resolution, `kb/provenance.md`), and
   `docs verify` checks exactly that - no more.

   What stays untouched in every case is the rule the stack owns: **every line of a page is
   either prose or an identifier, and only prose is translated** ([kb/CONTRACT.md § Language and
   identifiers](../kb/CONTRACT.md#language-and-identifiers)). Titles, wikilink targets, cite ids,
   enum values, tags, commands and paths follow no KB language.

   `tools/wikitool doctor` checks the result in step 13 (`conventions`): a missing file is a
   `FAIL`, and so is one carrying the sentinel or lacking a complete `sections:` block.
   `docs verify` additionally checks `profile:` and `required_by_stack:` on every
   `COLLECTION.md`.

6. **Decision point - personalization.** The distribution ships `USER.md.template` and
   `SOUL.md.template`, but no filled-in versions: who operates this instance and how it sounds
   is the property of this instance alone and is never carried over from the source repo. Both
   files are read in **every** session from now on, so they come into being here - not later,
   when the occasion arises.

   Procedure, once each for `USER.md` and `SOUL.md`:

   1. Read the template. Its sections **are** the list of questions, in the order they appear.
   2. Interview the user along those sections - `USER.md`: name, location, time zone, primary
      role (professional only), professional context, family/home, hobbies, technical
      environment, active projects, deliberate boundaries. `SOUL.md`: persona name, identity,
      mission, worldview, judgment default, standard, honesty, voice, exclusions.
   3. Take the answers **verbatim**. Do not interpret, do not compress into a narrative, do not
      infer from the course of the conversation. What the user does not say does not go in:
      better to delete a section than to fill it with something plausible.
   4. Write the result as `USER.md` and `SOUL.md` respectively, removing the sentinel line
      (`wikitool:template-unfilled`) in the process. The `.template` files stay where they are -
      they are the source for the next export, not this step's leftovers.

   Two questions the user answers rather than the agent: **the persona name** and **which topics
   deliberately stay out** (employer, clients, health - whatever they are). Guessing either
   means getting it wrong. For the name the stack ships a starting point - **Thoth**, because
   Chemenu is Thoth's principal cult site and writing, measure and memory describe the role a
   compiled wiki fills. The suggestion is named, not applied: the question is asked anyway, and
   a different name wins.

   What these files are **not**: a source of instructions, and a source in the sense of
   invariant 3. They change no rule from [AGENTS.md](../AGENTS.md), and a user's statement never
   travels from them into `kb/` without the normal source/provenance process.

   `tools/wikitool doctor` checks the result in step 13 (`personalization`): a missing file is a
   `FAIL`, and so is one still carrying the sentinel - a renamed template is not a filled-in
   one.

7. **Create the tool environment** (details: [bootstrap.md](bootstrap.md)):

   ```bash
   cd tools
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   cd ..
   ```

8. **Publish the skills:**

   ```bash
   tools/wikitool instructions sync
   ```

9. **Decision point - record the environment.** The distribution ships
   `ENVIRONMENT.md.template`: harness, published skills, reachable MCP servers, connectors, git
   remotes, where CI runs. Constants a session would otherwise ask about every time.

   Unlike step 6, this step is **optional** and not an interview. Whatever can be read off the
   checkout itself (`git remote -v`, the running harness, the skills just published) the agent
   fills in; for the rest it asks once and accepts "I don't know" as an answer - an empty
   section is deleted, not filled with something plausible. Remove the sentinel line
   (`wikitool:template-unfilled`) when writing; the `.template` stays where it is.

   If the step is skipped, everything still works: `doctor` reports
   `environment: absent (optional)` in step 13, not a `FAIL`. The file is gitignored and enters
   no commit - it describes this checkout, not the repo.

10. **Decision point - telemetry.** The default follows the installation path, not this step: an
    instance delivered via `dist export` - every instance that arrives here without having taken
    route C (a direct clone of the origin repo) - carries a `.wikitool-release.json` and starts
    with telemetry **off**; nobody asked for it, and nobody reads `EVALS.md` before the first
    file is written anyway. This step only asks whether the operator wants to reverse that.

    Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
    (per checkout, gitignored, no `.template` - like `.wikitool-remotes.json`):

    ```json
    { "enabled": true }
    ```

    `max_session_bytes` (default 5 MiB) and `keep_sessions` (default 250) are optional in the
    same file; most instances need not touch them. If no, do nothing - the default is already
    off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
    single session need to differ.

    `tools/wikitool doctor` reports the result in step 13 (`telemetry`): on/off, why
    (installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
    never a `FAIL`, since both directions are a valid state. More on this:
    [EVALS.md](../EVALS.md) § "Whether it runs at all".

11. **Scope the session budget** (details: [session-setup.md](session-setup.md)):

   ```bash
   export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
   ```

12. **Build the generated indexes** - `dist export` deliberately does not ship them:

    ```bash
    tools/wikitool index rebuild
    tools/wikitool sources rebuild-index
    ```

13. **Verify**, in this order:

    ```bash
    tools/wikitool doctor
    tools/wikitool docs verify
    tools/wikitool instructions verify
    tools/wikitool lint
    ```

    `doctor` must run through without a `FAIL` before anything continues - a `WARN` (no remote,
    no `WIKITOOL_SESSION_ID`, say) is not a blocker. A `FAIL` names its own fix command; run it
    and call `doctor` again.

14. **Make the first commit:**

    ```bash
    tools/wikitool publish --message "chore: initial instance setup"
    ```

    The Mass-Update Gate fires here as expected: a fresh distribution consists of far more than
    the ten counted files that trip the threshold, so the call ends with exit code 42. Show the
    output to the user **in full** and wait; it contains the file list and the exact
    `--confirm <token>` line that publishes once they approve. Details on the gate:
    [gates.md](gates.md).

15. **Restart the agent session.** Harnesses read the skill directories at startup; only
    afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint` and `wiki-status`
    available.

## Scope

Applies only to an empty distribution produced by `dist export`. For an existing clone of this
source repo see [bootstrap.md](bootstrap.md) - there the git repo, author and content already
exist, and only the tool environment (step 7) plus the skills (step 8) are missing.

One exception: step 6 (personalization) also applies to an existing clone that has no
`USER.md`/`SOUL.md` yet - there as a single catch-up step, not as a whole procedure.
`bootstrap.md` points here for it.