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: frontmatter, template and language may all be
      rewritten. `instruction`, `lint-report`, `type-spec` and `type-guidance` describe stack
      artifacts and arrive unchanged - the glob above never matches them because none of them
      ships as a `.template` in the first place.

      A `root: kb` type-spec's generic authoring guidance (when to use the type, when not to)
      is not part of this adoption at all: it lives in a sibling `types/<name>.guidance.md`
      this instance never renames, the same as `instruction.md` - it ships verbatim and a later
      `dist upgrade` improves it directly, without the type-spec that links it needing to be
      touched. `types/type-spec.md` § "Anatomy of a type" has the shape.

   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 14 (`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. **Decision point - task tracker.** The instance ships the `project` type and the collection
    its type-spec's `base_dir:` names (`kb/gtd/` here), so committed initiatives have a page from
    the start. What they do *not* have until this step is the other half of the weekly review:
    the tracker that owns the open items, which `tools/wikitool review` joins those pages against
    over the project name. No tracker configured is a legitimate end state - the pages work
    alone, `review` simply says so and refuses - so ask rather than assume.

    Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
    in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like
    `.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
    the three thresholds the review reads as configuration rather than schema. The shape, the
    shipped providers, and what Super Productivity in particular needs are in
    [INSTALL.md](../INSTALL.md) § Konfiguration; do not restate them here. If no, do nothing - no
    file is created, and adding one later needs nothing from this procedure.

    `doctor` reports the result in step 14 (`tasks`): absent is `OK`, a malformed file is the one
    `FAIL` here (a broken opt-in must not read as "no tracker configured"), and a configured
    provider that is simply not running is never a fault.

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

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

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

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

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

15. **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).

16. **Restart the agent session.** Harnesses read the skill directories at startup; only
    afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint`, `wiki-status` and
    `weekly-review` 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.