chemenu/instructions/setup-instance.md

type, name, description

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

Contents

• When to run
• Steps
• Scope

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

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

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

      curl -fLO <browser_download_url of preflight.sh>
      

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

      pwsh -NoProfile -ExecutionPolicy Bypass -File preflight.ps1
      

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

   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:

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

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

      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, 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. Ask the user for the KB language.

      kb/CONVENTIONS.md.template defaults to English; 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. 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. 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 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). 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. **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, 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:

   tools/wikitool instructions sync
   

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

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

9. **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 § 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 § 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 says how.

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

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

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

13. Make the first commit:

    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.

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

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.