torbenandClaude Opus 5.5
5c9be38aa8
A part of the stack that will not move from the unpack folder into place is retried for about 30 seconds; each retry removes what reached the target and unpacks the entry afresh from the archive, so the entry ends up there once and whole. If it still fails, both scripts take back everything they moved and exit 1 with the system's message and "nothing was installed". New test hook CHEMENU_PREFLIGHT_MOVE_FAIL=<entry>:<n>[:partial]. Files changed: - CHANGES.md - INSTALL.md - VERSION - instructions/preflight.md - tools/CONTRACT.md - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/tests/test_preflight_pwsh.py - tools/preflight.ps1 - tools/preflight.sh Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
200 lines
11 KiB
Markdown
200 lines
11 KiB
Markdown
# 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.
|
|
|
|
<!-- dist:strip-start -->
|
|
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).
|
|
<!-- dist:strip-end -->
|
|
|
|
## 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:
|
|
|
|
<!-- wikitool:prerequisites -->
|
|
- **Python** ≥ 3.11
|
|
- **Git**
|
|
- **ripgrep (rg)**
|
|
<!-- /wikitool:prerequisites -->
|
|
|
|
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:
|
|
|
|
<!-- wikitool:prerequisites-windows -->
|
|
- **PowerShell 7 (pwsh)** ≥ 7
|
|
<!-- /wikitool:prerequisites-windows -->
|
|
|
|
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:
|
|
|
|
- <!-- setup-question: identity --> **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).
|
|
- <!-- setup-question: remote --> **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`.
|
|
- <!-- setup-question: kb-language --> **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.
|
|
- <!-- setup-question: domain --> **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`).
|
|
- <!-- setup-question: personalization --> **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**.
|
|
- <!-- setup-question: environment --> **Environment** (optional) - harness, MCP servers, remotes,
|
|
so that later sessions don't ask again. "I don't know" is a valid answer.
|
|
- <!-- setup-question: telemetry --> **Telemetry** - off by default; the agent only asks whether
|
|
you want to switch it on.
|
|
- <!-- setup-question: task-tracker --> **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 <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](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
|
|
(`.wikitool-tasks.json` - 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).
|