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