torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity
Files
9868fce3d5b0c9503670ebb2d142392481eaac1d
chemenu/docs/reference/commands/instance-health.md
T
torbenandClaude Code 0e6a50aa98
CI / verify (push) Successful in 6m41s
Details
CI / pwsh (push) Successful in 2m24s
Details
Release / release (push) Successful in 34s
Details
Release / wiki-mirror (push) Skipped
Details
feat(raw): raw derive reads PDF and Outlook MSG; doctor shows each import filter 
PDF is read with pypdf (page markers, scan warning, encrypted files refused), Outlook .msg with olefile as a container like an .eml, and a .msg attached to a mail is quoted. Both packages are in tools/requirements.txt and imported only when such a file is derived, so a missing one stops that format alone. doctor reports one import-filter line per package-backed format.

Files changed:
- CHANGES.md
- VERSION
- docs/how-to/ingest-a-source.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/raw-material-and-uploads.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/raw_cmd.py
- tools/chemenu/filters/__init__.py
- tools/chemenu/filters/mail.py
- tools/chemenu/filters/msg.py
- tools/chemenu/filters/pdf.py
- tools/chemenu/tests/binary_formats.py
- tools/chemenu/tests/test_raw_derive_binary.py
- tools/requirements.txt

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-08 14:02:16 +02:00

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