Table of Contents

Instance health

doctor

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/reference/commands/instance-health.md at v10.1.0 – edit the repository, not this wiki.

Instance health

A single check of whether this instance is set up and working.

`doctor`

Check that this instance is correctly configured.

Synopsis

wikitool doctor [--json]

Options

  --json      Print the checks as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool doctor
tools/wikitool doctor --json

Behaviour

Checks dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, the kb/raw/reports/work/sites/instructions structure, and generated files.
Import filters (import-filter-<name>): one line for each raw derive format that reads through a package (PDF, Outlook .msg) - a WARN naming the package when it is missing, since that costs only its own format; fixed by running tools/preflight.sh again.
Tool paths (tool-paths): .wikitool-tools.json written by a preflight that finished, every tool tools/prerequisites.txt names for this platform recorded, and every recorded path still there - a FAIL otherwise, fixed by running tools/preflight.sh again (PowerShell 7: tools/preflight.ps1).
Install folder (install-dir): on Windows with long paths off, a FAIL when the folder holding tools/ is longer than tools/prerequisites.txt allows (95 characters) - the limit the preflight enforces before it sets anything up.
PowerShell (execution-policy, script-marks; Windows only, OK elsewhere): a FAIL when the effective execution policy is Restricted or AllSigned - the line then says whether a group policy sets it, which only whoever administers the computer can change - and a FAIL when a script under tools/ carries a Mark of the Web from the internet zone, which a browser download unpacked in Explorer leaves behind and Invoke-WebRequest plus tar do not. tools/preflight.ps1 checks the same two things before it stops.
Personalization: USER.md/SOUL.md present and filled - a file still carrying the template's sentinel is a FAIL.
KB conventions: kb/CONVENTIONS.md present, unsentinelled, and naming all three tool-owned section headings - a FAIL on any of the three.
Environment note: ENVIRONMENT.md is optional, so absent is OK; a still-templated one is a WARN.
Legacy settings (legacy-settings): one FAIL for each per-feature settings file of an earlier version (telemetry, remotes, upload, task tracker) that is still there. Nothing reads them any more, so the settings they hold are not in effect; the fix is tools/wikitool config migrate.
Synced folder (sync-folder): a WARN when the git directory, links and junctions resolved, lies under a folder named by OneDrive, OneDriveCommercial or OneDriveConsumer (compared without regard to case on Windows) or under ~/Library/CloudStorage/ (macOS); OK otherwise, never a FAIL.
Backup (backup): the backup section absent is OK, malformed is a FAIL. Configured, a WARN when <target>/git is not a bare repository, origin does not push there, or - with machine_data true - no machine-data backup exists yet; otherwise OK with the age of the last machine-data backup.
Page export (export): the export section absent is OK, malformed is a FAIL; otherwise OK listing each target with its handler, folder and whether it runs after publish.
Intake channels (upload-intake): the channels of the intake section with their handler, and how many submissions wait in quarantine/. Absent is OK and means no channel - no submit tool, nothing to collect; malformed is a FAIL, and so is an mcp-upload/ of an earlier version that still holds submissions (the message names the command that moves it). A folder channel whose path does not exist is a WARN.
Task tracker: the tasks section present, absent or malformed - absent is OK (no tracker configured), malformed is a FAIL. When WIKITOOL_TASKS_CONFIG is set, the profile it names is read instead of the tasks, superproductivity and caldav sections and the finding names it; a set variable that names no file is a FAIL, never OK.
For a configured superproductivity provider, the configured access path's own state: access: "api" reports whether its local REST API answers GET /health with a ready renderer right now, access: "snapshot" whether a backup file is ready. The other access path is never attempted, and neither state is ever a FAIL.
For a configured caldav provider, whether the server is reachable and Basic auth succeeds - never a FAIL; only a broken config block is.
Settings (settings-instance, settings-checkout, settings-secrets): one line per tier. wikitool.json and .wikitool-local.json each present or absent - absent is OK - and a FAIL naming file, key and the right tier when a value sits in the wrong file, a secret or a committed private field holds a plain value, or a value fails its field; a section this version does not read is a WARN. For the references: how many resolve, never a value - an unresolvable one is a FAIL, one 1Password will not hand out until a human unlocks it a WARN.
Session id source: OK for WIKITOOL_SESSION_ID or a registered harness variable, WARN only for the bare parent-pid fallback.
Telemetry: on or off and why - installation-form default, the telemetry section of .wikitool-local.json, or WIKI_TRACE - and the current session's count and byte total against both caps; never a FAIL. A WARN when that section is not read as written - unreadable JSON, not an object, enabled not a JSON boolean, a cap not a positive integer, or an unknown key - naming the field; telemetry itself drops or reinterprets such a value without a word, so this is where it shows.
Site handlers (site-handlers): every file in sites/ is read against the handler schema and the rules the schema cannot state; FAIL for a file that cannot be used, naming the file and the reason, and OK listing the instance's handlers, each one that replaces a stack handler (the same host and path) named as such.
Browser component (browser): whether the optional Playwright component and its browser are installed in the venv - OK either way, never a FAIL; a WARN only when it is missing and the instance needs it: a host fetch.routes sends through the session (raw login), or a site handler that declares render. The user installs it with tools/preflight.sh --with browser.
Exits 1 only on a FAIL; a missing remote, session id or VERSION is a WARN, not a fault.
Read-only and exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: yes

Exit codes

0 - success
1 - At least one check reported FAIL (a WARN, e.g. no remote or no WIKITOOL_SESSION_ID, does not exit 1)

See also

instructions/setup-instance.md - the setup steps most findings point back to
instructions/preflight.md - what tool-paths and install-dir point back to
docs/reference/configuration.md - the per-checkout configuration files and the tiered settings
docs/explanation/telemetry-and-evaluation.md - telemetry state and caps
docs/how-to/back-up-to-a-synced-folder.md - what sync-folder and backup point to
instructions/session-setup.md - setting WIKITOOL_SESSION_ID