chemenu/docs/reference/commands/instance-health.md

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.
• 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