# 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](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](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](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](docs/how-to/use-1password-for-settings.md)). The preflight records it when it finds it and never asks for it. Optional: the **browser component**, if you want the wiki to fetch pages of a website you are subscribed to with your own login, or pages that only appear in a browser ([fetch-pages-behind-a-login.md](docs/how-to/fetch-pages-behind-a-login.md)). It is a Python package plus a Chromium of its own, a few hundred megabytes, installed into the instance's `tools/.venv` and nowhere else. You install it yourself, once the instance runs: `tools/preflight.sh --with browser` (PowerShell 7: `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1 --with browser`). Every later preflight run keeps it up to date. On Linux, the browser may need system libraries the preflight cannot install; Playwright's message then names them, for you or whoever administers the machine. Native Windows is not yet verified 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 . 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`. Without a git server but with a synced folder (OneDrive and the like), the agent offers a backup into that folder instead: [docs/how-to/back-up-to-a-synced-folder.md](docs/how-to/back-up-to-a-synced-folder.md). - **Language and tone of the pages** - they go into `kb/CONVENTIONS.md`, plus `kb//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](docs/reference/configuration.md#task-tracker). 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 `. - **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 =`. - **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](docs/how-to/troubleshoot.md). ## Check the instance ```bash 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: ```bash 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](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](docs/how-to/update-an-instance.md). - **Configuration** - environment variables and the files per checkout: [docs/reference/configuration.md](docs/reference/configuration.md). - **When something does not work:** [docs/how-to/troubleshoot.md](docs/how-to/troubleshoot.md). - **Working with the wiki:** [docs/how-to/](docs/how-to/README.md).