torbenandClaude Opus 5.5
f9056c04f7
Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/eval_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# Troubleshoot an instance
|
|
|
|
What a common failure means, and what to do about it. During installation itself, the preflight
|
|
names its own stops - what is missing, why, and the command that fixes it - and
|
|
[INSTALL.md](../../INSTALL.md) explains them. This page covers an instance that is already set up.
|
|
|
|
For the MCP read server, see the troubleshooting section of
|
|
[Set up the MCP read server](set-up-the-mcp-server.md#troubleshooting).
|
|
|
|
## `tools/wikitool` ends with `STOP - this checkout is not set up yet` (exit 42)
|
|
|
|
The preflight has not run in this checkout yet, or not since the last update. Run it:
|
|
|
|
```bash
|
|
tools/preflight.sh
|
|
```
|
|
|
|
In PowerShell 7 on Windows, the call is
|
|
`pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`. The `-ExecutionPolicy Bypass`
|
|
applies to that one process only and changes no setting.
|
|
[instructions/preflight.md](../../instructions/preflight.md) is the procedure, and its output says
|
|
what to install if anything is missing.
|
|
|
|
## The agent offers no skills (`wiki-ingest`, `wiki-query`, ...)
|
|
|
|
`.agents/skills/` and `.claude/skills/` are generated and not committed. Run:
|
|
|
|
```bash
|
|
tools/wikitool instructions sync
|
|
```
|
|
|
|
Then restart the agent session. A harness reads its skills only when the session starts.
|
|
|
|
## `doctor` reports `personalization: FAIL`
|
|
|
|
`USER.md` or `SOUL.md` is missing, or still carries the sentinel line from its template. A renamed
|
|
template does not count as a filled one. Ask the agent to run the personalization step of
|
|
[instructions/setup-instance.md](../../instructions/setup-instance.md). For a further clone of an
|
|
older instance, that is the only step to catch up on.
|
|
|
|
## `doctor` reports `environment: WARN`
|
|
|
|
`ENVIRONMENT.md` exists but still carries the template's sentinel line. Fill it in (the template is
|
|
`ENVIRONMENT.md.template`) and remove the line, or delete the file. It is optional, and `absent` is
|
|
a valid state.
|
|
|
|
## `new` stops with "No author configured"
|
|
|
|
Neither `$WIKI_AUTHOR` nor `git config user.name` is set. Run `git config user.name "<Name>"`, or
|
|
export `WIKI_AUTHOR` ([configuration](../reference/configuration.md)).
|
|
|
|
## `publish` ends with exit 42 (Mass-Update Gate)
|
|
|
|
Expected when ten or more files are counted, for example on the very first commit of a new instance
|
|
or after a lint pass. It is not an error. It asks that a human see the output: the complete file
|
|
list and the exact `--confirm <token>` line that publishes once you approve.
|
|
[instructions/gates.md](../../instructions/gates.md) has the details.
|
|
|
|
## `publish` ends with exit 42 (Publish-Remote Gate)
|
|
|
|
This checkout has a `.wikitool-remotes.json`, and the remote being pushed to is not listed in it.
|
|
Also not an error: the output names the push URL it would write to and the URLs that are allowed.
|
|
Unlike the Mass-Update Gate, there is **no token and no flag** here. If the target really is right,
|
|
you add its URL to the file yourself. An agent that edits the file to get past the refusal is
|
|
opening a gate on its own initiative, which it must never do.
|
|
|
|
## Setup or an update fails, and you want to report it
|
|
|
|
Ask the agent to follow [instructions/bug-report.md](../../instructions/bug-report.md), or call
|
|
`tools/bugreport` yourself. It works the same from Bash, Git Bash and PowerShell. It finds a
|
|
Python 3.8 or newer by itself, skipping the Store aliases `python3` points at on Windows. It needs
|
|
neither the preflight nor a working `wikitool`, and if it finds no Python, it says why.
|
|
|
|
The script writes a bundle to `reports/bugreport-<timestamp>/`, with a zip beside it.
|
|
|
|
- **What is removed:** secrets, and page titles from everything the script itself produces.
|
|
`--titles` keeps the titles.
|
|
- **What may still be in it:** the session trace is included by default (`--no-trace` leaves it
|
|
out). Like the chronology and the transcripts, it can contain page content and titles. The bundle
|
|
also contains machine, user and path names.
|
|
- **Pseudonymising:** `--pseudonymise` replaces user, host, path, git and remote names with
|
|
placeholders that keep their length, spaces, hyphens and path depth. The agent can then add more
|
|
names - people, companies, customers, projects - with `--bundle … --candidates …`. That is a
|
|
model's judgment, and it leaves a remainder: read the bundle before you share it. The mapping,
|
|
the checklist and the candidates file contain the originals, and they sit beside the bundle,
|
|
never in it.
|
|
|
|
Nothing is uploaded anywhere. You choose the channel.
|