torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity
Files
893db6e6403a95d45f5e98077e2c988adec5051e
chemenu/docs/reference/commands/instance-health.md
T
torbenandClaude Opus 5.5 893db6e640
CI / verify (push) Successful in 6m17s
Details
CI / pwsh (push) Successful in 2m0s
Details
Release / release (push) Successful in 34s
Details
feat: the shapes of the four hand-written .wikitool-*.json files live in one record each (config_shapes.py); loaders, doctor and docs/reference/configuration.md read them (#193) 
The telemetry, remotes, upload and tasks loaders take field names, defaults, coercions and their Expected: text from the record and accept exactly what they did before. doctor WARNs on a telemetry file the policy silently reads differently. configuration.md carries one generated region per file, also checked in an instance. docs reference --apply now refreshes several regions in one page in sequence instead of keeping only the last.

Files changed:
- CHANGES.md
- VERSION
- docs/how-to/set-up-the-mcp-server.md
- docs/reference/README.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/configuration.md
- instructions/dev/doc-pull-through.md
- instructions/setup-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/config.py
- tools/chemenu/config_shapes.py
- tools/chemenu/reference_doc.py
- tools/chemenu/tasks/caldav.py
- tools/chemenu/tasks/config.py
- tools/chemenu/tasks/superproductivity.py
- tools/chemenu/telemetry/policy.py
- tools/chemenu/tests/test_config_shapes.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_reference_doc.py
- tools/chemenu/upload.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-07 08:44:50 +02:00

4.4 KiB
Raw Blame History

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/instructions structure, and generated files.
  • 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.
  • MCP submit tool: whether .wikitool-upload.json is present, absent or malformed, its limits, and how many submissions wait in mcp-upload/. Absent is OK and means the write path does not exist at all; malformed is a FAIL.
  • Task tracker: .wikitool-tasks.json present, absent or malformed - absent is OK (no tracker configured), malformed is a FAIL. When WIKITOOL_TASKS_CONFIG is set, that file is read instead 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.
  • 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, .wikitool-telemetry.json, or WIKI_TRACE - and the current session's count and byte total against both caps; never a FAIL. A WARN when .wikitool-telemetry.json 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.
  • 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
  • docs/explanation/telemetry-and-evaluation.md - telemetry state and caps
  • instructions/session-setup.md - setting WIKITOOL_SESSION_ID
Reference in new issue View Git Blame Copy Permalink