.\" ===========================================================================
.\" dotfiles_doctor.1 — Manual page for the dotfiles_doctor utility
.\" ===========================================================================
.TH DOTFILES_DOCTOR 1 "2025-11-06" "dotfiles_doctor" "User Commands"
.SH NAME
dotfiles_doctor \- analyze zsh startup health, timings, and timeline from NDJSON logs
.SH SYNOPSIS
.B dotfiles_doctor
.RI [ --timeline ]
.RI [ --logfile= PATH ]
.SH DESCRIPTION
.B dotfiles_doctor
reads an NDJSON log (newline\-delimited JSON objects) produced by your
.ZN call_file
logger during shell startup and prints a health report:
per\-file durations, exit codes, aggregate timings, and optionally a
microsecond\-precision load timeline.

The log entries are emitted one JSON object per line (not a single JSON array).
The tool always "slurps" the file internally.
.SH OPTIONS
.TP
.BR --timeline
Show a start\->end timeline for each loaded file with microsecond timestamps.
.TP
.BR --logfile = PATH
Path to the NDJSON log file to analyze. Defaults to
.IR ~/zshrc\-log.json .
.SH ENVIRONMENT
.TP
.B SLOW_THRESHOLD
Duration (ms) above which a module is flagged "slow". Default: 200.
.TP
.B WARN_THRESHOLD
Duration (ms) above which a module is flagged "warning/very slow". Default: 500.
.SH REQUIREMENTS
The script relies on
.BR jq (1),
.BR awk (1),
.BR column (1),
and standard shell utilities.
.SH FILES
.TP
.I ~/zshrc\-log.json
Default NDJSON log consumed by
.B dotfiles_doctor .
Each line is a JSON object with keys:
.BR file ,
.BR label ,
.BR start ,
.BR end ,
.BR duration_ms ,
.BR exit_code .
.SH EXIT STATUS
Returns 0 on success; non\-zero on invocation errors (e.g. missing jq or log file).
.SH EXAMPLES
Analyze with defaults:
.P
.EX
dotfiles_doctor
.EE
.P
Show microsecond timeline:
.P
.EX
dotfiles_doctor --timeline
.EE
.P
Use a custom log and tighter thresholds:
.P
.EX
SLOW_THRESHOLD=100 WARN_THRESHOLD=300 dotfiles_doctor \\
  --logfile="$HOME/tmp/startup.ndjson" --timeline
.EE
.SH SEE ALSO
.BR jq (1),
.BR zsh (1),
.BR compinit (1)
.SH AUTHOR
Written for your dotfiles; completion and manpage generated by ChatGPT.