torbenandClaude Code
db8f90c229
Files changed: - .gitignore - AGENTS.md - CHANGES.md - INSTALL.md - VERSION - docs/explanation/knowledge-and-commitment.md - docs/explanation/telemetry-and-evaluation.md - docs/explanation/why-gates-are-code.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/reference/commands/README.md - docs/reference/commands/configuration.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/commands/pages.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/configuration.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - instructions/dev/tracker-testing.md - instructions/gates.md - instructions/ingest-queue.md - instructions/mcp-read-server.md - instructions/migrate-corpus.md - instructions/migrations/10.0.0-settings-tiers.md - instructions/setup-instance.md - raw/CONTRACT.md - reports/CONTRACT.md - tools/CONTRACT.md - tools/README.md - tools/bugreport.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/_util.py - tools/chemenu/commands/config_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/export_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/review_cmd.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/config.py - tools/chemenu/config_shapes.py - tools/chemenu/legacy_settings.py - tools/chemenu/mcp/__main__.py - tools/chemenu/mcp/server.py - tools/chemenu/reference_doc.py - tools/chemenu/review.py - tools/chemenu/settings.py - tools/chemenu/tasks/__init__.py - tools/chemenu/tasks/caldav.py - tools/chemenu/tasks/config.py - tools/chemenu/tasks/superproductivity.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/record_sp_fixtures.py - tools/chemenu/tests/test_bugreport.py - tools/chemenu/tests/test_caldav.py - tools/chemenu/tests/test_config_shapes.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_legacy_settings.py - tools/chemenu/tests/test_mcp_server.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_review.py - tools/chemenu/tests/test_settings.py - tools/chemenu/tests/test_sp_recorded.py - tools/chemenu/tests/test_superproductivity.py - tools/chemenu/tests/test_task_cmd.py - tools/chemenu/tests/test_tasks_config.py - tools/chemenu/tests/test_telemetry_policy.py - tools/chemenu/tests/test_tracker_live.py - tools/chemenu/tests/test_upload.py - tools/chemenu/tests/tracker_live.py - tools/chemenu/upload.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
98 lines
5.0 KiB
Markdown
98 lines
5.0 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.
|
|
|
|
## `doctor` reports `telemetry: WARN`
|
|
|
|
The `telemetry` section of `.wikitool-local.json` holds something telemetry does not read as
|
|
written: an unreadable settings file, a value that is not an object, an `enabled` that is not `true` or `false`, a cap that is not a
|
|
positive whole number, or a key it does not know. Telemetry itself never stops on this. It ignores
|
|
the file or the value, or reads `"no"` as on, and the line names the field. Correct the section to the
|
|
shape in the [configuration reference](../reference/configuration.md#telemetry), or remove it to
|
|
get the default back.
|
|
|
|
## `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 `remotes.allowed_push_urls` list in `.wikitool-local.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 that list yourself. An agent that edits the list 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.
|