--- 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 ` 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. ## Contents - [When to run](#when-to-run) - [Steps](#steps) - [Scope](#scope) ## 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 ``` `` must not exist, or must be empty; otherwise the command aborts with `ERROR`. Work inside `` 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 "" git config user.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 ` - 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//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/.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 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 ` 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.