torbenandClaude Opus 5.5
9736472f48
Files changed: - CHANGES.md - INSTALL.md - VERSION - docs/explanation/configuration-tiers.md - docs/how-to/README.md - docs/how-to/back-up-to-a-synced-folder.md - docs/reference/commands/README.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/configuration.md - instructions/publish-cycle.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/backup.py - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/backup_cmd.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/config_shapes.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_backup.py - tools/chemenu/tests/test_config_shapes.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
217 lines
13 KiB
Markdown
217 lines
13 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 -->
|
|
|
|
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:
|
|
|
|
<!-- 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`. 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).
|
|
- <!-- 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
|
|
(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).
|