chemenu/INSTALL.md

Install a Chemenu instance

This tutorial takes you from an empty folder to a running Chemenu instance. There is exactly one way to get one: an agent installs the latest release into an empty folder you choose. The agent runs the steps, following instructions/setup-instance.md from that same release. This page covers what you prepare beforehand, the sentence you give the agent, what it asks you, and what to do when it stops. The full command reference is in tools/CONTRACT.md.

The optional MCP read server is set up separately, once the instance runs: docs/how-to/set-up-the-mcp-server.md. It serves the same corpus, read-only, to a consumer that is not a terminal on this machine.

To work on the stack itself, clone this repository instead. That is a development checkout with a demo corpus, not an instance; it is described in docs/dev/development.md.

What you need first

The preflight checks these programs before any wikitool command runs. You install them yourself - the agent never does, not even with your permission. Where one is missing, the preflight names the install command for your system. The list is generated from tools/prerequisites.txt, the same file the preflight reads:

• Python ≥ 3.11
• Git
• ripgrep (rg)

Optional: the 1Password CLI (op), if you want secrets and private values in the settings to come from 1Password (use-1password-for-settings.md). The preflight records it when it finds it and never asks for it.

You also need:

• An agent harness: Claude Code, GitHub Copilot (in VS Code or as a CLI), Codex CLI or Mistral Vibe.
• An empty folder for the instance, with your harness opened in it. Empty means nothing but a .git. A freshly cloned, empty repository for your instance is exactly right: if your repository torben/nathan lives in ~/src/nathan, install there, and the agent keeps its origin as the target for publish.

On Windows, additionally, also checked by the preflight:

• PowerShell 7 (pwsh) ≥ 7

And on Windows also:

• PowerShell 7 as the default terminal in VS Code. Windows PowerShell 5.1 is not enough, and WSL is not supported.
• Execution policy RemoteSigned - the factory setting on many machines (Get-ExecutionPolicy -List shows it).
• Git for Windows. It brings Git Bash, which Claude Code runs its commands in.
• An installation folder of at most 95 characters, for example C:\Chemenu. Without long paths switched on, Windows allows only 259 characters per path, and the wiki's files need the rest. If you have administrator rights you can switch long paths on instead (LongPathsEnabled); that is not required.

The sentence for the agent

Open the empty folder in your harness and give the agent this sentence:

Set up a new Chemenu instance in this folder. Fetch the latest release from https://gitea.nehmer.net/api/v1/repos/torben/chemenu/releases/latest and follow its asset setup-instance.md. Before you start the preflight, read the asset preflight.md from the same release.

With that, the agent reads the description of the latest release, and from it the two instructions. It then downloads the matching preflight script (preflight.ps1 for PowerShell, preflight.sh for a POSIX shell) into the folder with a command of its shell - not through the browser, so that Windows does not mark the file as "from the internet" - and runs it. The script downloads the tarball of the same release, checks its sha256, unpacks it into the folder, deletes itself, and then checks in the unpacked tree that everything is in place.

All releases are listed at https://gitea.nehmer.net/torben/chemenu/releases. The repository is public; the download needs neither an account nor a token.

What the agent asks you

The agent may guess none of these answers, and it carries none of them over from another repository:

• **Author identity** - name and email for `git config`. This is also the author name of every wiki page created from now on ($WIKI_AUTHOR overrides it when needed).
• **Remote** - for an empty clone, only the confirmation that origin is right; otherwise a URL, if you want to push to a server. Without a remote the instance stays local, and every publish runs with --no-push.
• **Language and tone of the pages** - they go into kb/CONVENTIONS.md, plus kb/<name>/COLLECTION.md per collection. Ready-made profiles, including a complete German one, are in instructions/kb-profiles.md. Decide this before the first ingest: afterwards, changing the section names is a migration of every existing page. Titles, wikilink targets, citation ids, schema values, tags, commands and paths follow no language - Act Runner is called Act Runner in every instance.
• **Subject area** - where this wiki draws its sources from. From it the agent proposes a source_type list (for a sports club, say: statutes, minutes, match report). That is a starting point, not a commitment: it gets corrected against real material later (instructions/evolve-subtypes.md).
• **Personalization** - who operates this instance (USER.md) and how it sounds (SOUL.md). The agent interviews you along the templates and writes your answers down verbatim. Two questions only you answer: the name of the persona and the topics that deliberately stay out.
• **Environment** (optional) - harness, MCP servers, remotes, so that later sessions don't ask again. "I don't know" is a valid answer.
• **Telemetry** - off by default; the agent only asks whether you want to switch it on.
• **Task tracker** (optional) - see docs/reference/configuration.md.

At the end the agent makes the first commit. The Mass-Update Gate stops it there (exit 42), because a new instance consists of far more than ten files. That is expected: the agent shows you the file list and the --confirm line, and nothing is published until you approve. Afterwards, restart the agent session in the same folder so that it loads the skills.

When the agent stops

The preflight stops with exit 42 when you have to do something. Its output names, in a numbered block, what is missing, why, the command that fixes it, and how to continue. The agent shows you this block unchanged, adds a translation below it at most, and waits. Tell it when you are done; then it checks again. It may not work around the stop or install anything itself.

While downloading and unpacking (the script from the release, before there is a tree):

• Tools for downloading or unpacking are missing (exit 42). On Linux and macOS the script needs curl, tar and sha256sum (or shasum); on Windows only the tar.exe that comes with Windows 10/11. Install what the output names; on Windows, Git for Windows brings everything for Git Bash.
• The folder path is too long (exit 42, only on Windows without long paths). Take a shorter one, such as C:\Chemenu, open it in the harness and give the sentence there again.
• The folder is not empty (exit 1). It may hold nothing but the script and a .git. Clean it up yourself or take another one - the agent deletes nothing there.
• Download failed or checksum wrong (exit 1). Nothing was unpacked. Check the internet connection and let it try again; the agent does not look for another way to download. Without a direct download you can put the tarball and its .sha256 from the release page side by side yourself; the agent then runs the script with --archive <tarball>.
• A part of the stack could not be moved into place (exit 1, "could not move ... into"). Usually a virus scanner briefly holding a freshly unpacked file open; the script has already waited about 30 seconds for it. If the message says "nothing was installed", the script has taken everything back - let the agent run it again. If it names entries it could not take back, empty the folder yourself (keep .git), then run it again.

In the unpacked tree (every further run is tools/preflight.sh, or under PowerShell pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1):

• A tool is missing - Python, git, ripgrep, on Windows also PowerShell 7. The output names the install command for your system. If it is installed, just somewhere else, tell the agent the path; it passes it on with --set <tool>=<path>.
• A version is too old - Python below 3.11, for example. Install a newer version or name its path.
• A path you named does not work - the path must point at the program itself, not at its folder.
• The Python environment (tools/.venv) or its libraries could not be set up. The output shows what Python or pip reported. Usually a proxy or a security program blocks the download; whoever looks after your machine can sort that out.
• Scripts carry the "from the internet" mark (only on Windows). That happens when the release was downloaded in the browser and unpacked in Explorer. Once, in the folder, in PowerShell 7: Get-ChildItem -Recurse -File | Unblock-File. doctor shows the state under script-marks.
• The execution policy forbids scripts (Restricted or AllSigned, only on Windows). The output names the one line for a PowerShell 7 window (Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned). If a group policy sets it, only your IT department can help - or you work from Git Bash with tools/wikitool. doctor shows the state under execution-policy.
• The installation folder path is too long (only on Windows without long paths). The instance has to move to a shorter folder, such as C:\Chemenu.

If the agent stops anywhere else and the cause is not obvious, it offers you a bug report - see docs/how-to/troubleshoot.md.

Check the instance

tools/wikitool doctor

This checks in one call: dependencies, author resolution, git identity/branch/remote, published skills, structure (collection contracts, generated files), personalization (USER.md/SOUL.md present and filled in), the optional environment note (ENVIRONMENT.md), the task tracker (the tasks section of the settings - if it is missing, that is OK; if a provider is configured, also whether its read path is ready and its API is answering right now, neither ever a FAIL) and the session id. OK/WARN are harmless (a missing remote, for example, is a valid end state); only a FAIL ends with exit 1, and every line names its own fix command.

Then also:

tools/wikitool docs verify
tools/wikitool instructions verify

Next steps

• Your first source and your first answer: docs/tutorials/first-source-to-first-answer.md walks you through both in the instance you just set up.
• Updating to a newer release: docs/how-to/update-an-instance.md.
• Configuration - environment variables and the files per checkout: docs/reference/configuration.md.
• When something does not work: docs/how-to/troubleshoot.md.
• Working with the wiki: docs/how-to/.