chemenu/instructions/setup-instance.md

type, name, description

type	name	description
types/instruction.md	setup-instance	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.

Contents

• When to run
• Steps
• 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.
• 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:

   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:

   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):

   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:

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

   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). 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, 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):

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

8. Publish the skills:

   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):

    { "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 § "Whether it runs at all".

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

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

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

    tools/wikitool index rebuild
    tools/wikitool sources rebuild-index
    

13. Verify, in this order:

    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:

    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.

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