---
type: types/instruction.md
name: setup-instance
description: Install a new, self-contained wiki instance from the latest release into an empty folder - preflight asset, git repo, identity/author, optional remote, conventions, personalization, first commit.
---

# Set up a new wiki instance

This instruction takes an empty folder to a working, self-contained wiki instance, starting from
the latest release - 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.

The same file is read in two places: as the asset `setup-instance.md` of a release, before
anything is installed, and inside the installed instance as `instructions/setup-instance.md`.
Its links to other instructions resolve only in the second place; step 0 says how to reach the
one it needs before that.

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

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

## When to run

- The user wants a new wiki instance - their own subject, a different person - in a folder they
  name. The folder is empty, or holds nothing but `.git`: an empty clone of the repository the
  instance will push to.
- Not for a further checkout of an instance that already exists (a second machine): clone that
  instance's repository and follow [bootstrap.md](bootstrap.md).
- Not for working on the stack itself. That happens in a clone of the origin repository; a
  release leaves out stack development (`instructions/dev/`) permanently, and nothing in an
  instance restores it.

## Steps

0. **Install the release into the folder.** Skip this step when `tools/preflight.sh` already
   exists in the folder - then the release is installed and this file is being read from inside
   it; continue with step 1.

   1. **Settle the folder.** It is the one the user named, and every later step runs in it. It
      has to be empty or hold only `.git`; on Windows with long paths switched off, its path may
      be at most 95 characters (`C:\Chemenu`, for instance). The preflight checks both, so do
      not measure anything yourself.

   2. **Read `preflight.md` before running anything.** It is an asset of the same release as
      this file: in the release description this file came from (the answer of
      `.../api/v1/repos/<owner>/<repo>/releases/latest`), the entry under `assets` named
      `preflight.md`, at its `browser_download_url`. It says how the preflight is started and
      what to do when it stops - and the release's preflight is the next thing to run.

   3. **Download the preflight for the shell you run in**, from the same release's `assets`,
      into the folder - with the shell's own download command, never through a browser, so the
      file carries no Mark of the Web. In PowerShell 7:

      ```powershell
      Invoke-WebRequest -Uri <browser_download_url of preflight.ps1> -OutFile preflight.ps1
      ```

      In a POSIX shell (Linux, macOS, Git Bash on Windows):

      ```bash
      curl -fLO <browser_download_url of preflight.sh>
      ```

   4. **Run it, exactly as `preflight.md` step 1 says** - the path is the downloaded file:

      ```powershell
      pwsh -NoProfile -ExecutionPolicy Bypass -File preflight.ps1
      ```

      ```bash
      sh preflight.sh
      ```

      It downloads the release's tarball, refuses unless its sha256 matches, unpacks it into
      this folder, removes the downloaded script and runs the preflight of the installed tree.
      Read its exit code as `preflight.md` step 2 says; on exit 42 follow its step 3 - show the
      output verbatim and wait. Every later run, including the retry after an exit 42, is the
      tree's own `tools/preflight.sh` or `pwsh -NoProfile -ExecutionPolicy Bypass -File
      tools/preflight.ps1`.

   Continue only after it exits 0. From here on, [preflight.md](preflight.md) and every other
   instruction this file links to lie under `instructions/` in the folder.

1. **Initialize the git repo.** If the folder has no `.git` yet:

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

   If it has one - an empty clone - keep it. `git branch --show-current` must print `main`; if
   it prints anything else, switch before the first commit:

   ```bash
   git checkout -b main
   ```

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

2. <!-- setup-question: identity --> **Decision point - identity.** Ask the user for their name and
   email address; never guess them, and never quietly carry them over from another repository (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.

3. <!-- setup-question: remote --> **Decision point - remote.** An empty clone already has one:
   show the user `git remote -v` and confirm that `origin` is where this instance is to be
   published. Otherwise ask 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 1). Without it, `publish` ends with exit 1
     before it commits anything, because there is no remote to publish to.

4. **Decision point - authoring conventions.** The release 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
      tools/wikitool dist adopt
      ```

      The `.template` files stay where they are; they are what the next `dist upgrade` compares
      against.

      Under `types/` this covers exactly the type-specs with `root: kb` - `entity`, `concept`,
      `source`, `comparison`, `project` - 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 - none of them ships as a `.template` in the first place.
      The subtype templates beside them (`types/entity.person.md`, `types/concept.decision.md`:
      the page skeleton `wikitool new` uses for that one subtype instead of the type's
      `## Template` block) are adopted the same way and are page material like that block, so
      they are translated with it. Whether this instance wants further ones is a question for
      later, once pages exist to show it - [subtype-templates.md](subtype-templates.md), not
      part of this setup.

      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. <!-- setup-question: kb-language --> 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. 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. Write `kb/CONVENTIONS.md` from `kb/CONVENTIONS.md.template`, filled in along the chosen
      profile - language, section names, naming forms, tone, relationship labels, hedging rule -
      and without the sentinel line (`wikitool:template-unfilled`). The placeholders in curly
      braces **are** the list of questions.

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

   5. <!-- setup-question: domain --> 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. 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 page type-specs have belonged to this instance since sub-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 12 (`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`.

5. <!-- setup-question: personalization --> **Decision point - personalization.** The release 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 anywhere
   else. 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 what the next `dist upgrade` compares against, 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 12 (`personalization`): a missing file is a
   `FAIL`, and so is one still carrying the sentinel - a renamed template is not a filled-in
   one.

6. **Publish the skills:**

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

7. <!-- setup-question: environment --> **Decision point - record the environment.** The release
   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 5, 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 12, not a `FAIL`. The file is gitignored and enters
   no commit - it describes this checkout, not the repo.

8. <!-- setup-question: telemetry --> **Decision point - telemetry.** Every instance installed from
   a release 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 12 (`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".

9. <!-- setup-question: task-tracker --> **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 12 (`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.

10. **Scope the session budget** with the line for the shell you run in, from
    [session-setup.md](session-setup.md) § Steps. Under GitHub Copilot this is what step 12's
    `doctor` reads: Copilot sets no session variable of its own, so without the line `doctor`
    reports `session-id: WARN` and the budget falls back to the parent process. If your harness
    starts a fresh shell for every command, put the line in front of each `tools/wikitool`
    call instead, in the same command - [session-setup.md](session-setup.md) says how.

11. **Build the generated indexes** - the release deliberately does not ship them:

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

12. **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,
    say) is not a blocker. A `FAIL` names its own fix command; run it and call `doctor` again.

13. **Make the first commit:**

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

    The Mass-Update Gate fires here as expected: a fresh instance 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).

    A local-only instance (step 3) adds `--no-push` here too. Without it the call ends with exit
    1 before the gate, because there is no remote to publish to, and commits nothing.

14. **Restart the agent session in this folder.** Harnesses read `AGENTS.md` and the skill
    directories at startup; only afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`,
    `wiki-lint`, `wiki-status` and `gtd-weekly-review` available.

**A step fails and the cause is not obvious?** Do not improvise around it (invariant 7). Offer the
user a bug report - [bug-report.md](bug-report.md) - and run it only if they agree; the collector
works even when `wikitool` does not start.

## Scope

Applies only to an empty folder (or an empty clone) and a release. A further checkout of an
instance that already exists has its git repo, author and content already; it needs only the
preflight and the skills - see [bootstrap.md](bootstrap.md).

One exception: the personalization step (5) also applies to an existing checkout 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.