feat(docs): man pages for gasm and every command, guarded against CLI drift

Assisted-by: GLM 5.3 Flash

docs/man/gasm-debug.1

@@ -0,0 +1,113 @@
+.TH GASM-DEBUG 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-debug \- interactive source-level debugger for JIT-assembled functions
+.SH SYNOPSIS
+.B gasm debug <file.s> \-\-func <name>
+.SH DESCRIPTION
+Interactive debugger for JIT-assembled functions.  Launches the function
+in a traced subprocess (ptrace), then provides a REPL for
+single-stepping, breakpoints, register and memory inspection.
+.PP
+With
+.B \-\-script
+the REPL commands run from a file and the session ends: the headless
+mode CI and scripts use.
+.B \-\-cover
+runs to completion with a breakpoint on every instruction and reports
+which executed and how often, the label-level coverage view.
+.SH REPL COMMANDS
+.TP
+.B break \fIlabel|addr\fR [\fBif \fIreg op val\fR]
+Set a breakpoint, optionally conditional on a register comparison
+(register against register or immediate).
+.TP
+.B delete \fIlabel|addr\fR
+Remove a breakpoint.
+.TP
+.B info break
+List all breakpoints.
+.TP
+.BR step " [" n ], " s
+Single-step n instructions; the default is 1.
+.TP
+.BR next ", " n
+Step over a CALL.
+.TP
+.BR finish ", " fin
+Run until the function returns.
+.TP
+.BR continue ", " c
+Run until a breakpoint, watchpoint or exit.
+.TP
+.BR disas " [" n ], " u
+Disassemble n instructions at PC.
+.TP
+.B regs
+Print general-purpose and vector registers.
+.TP
+.B where
+Show the source line and nearest label at PC.
+.TP
+.B stack
+Show the stack near RSP (return address and ABI0 args).
+.TP
+.BR bt ", " backtrace
+Backtrace: current frame plus return address.
+.TP
+.B x [\fIaddr\fR] [\fIlen\fR]
+Hex-dump memory; the defaults are the current PC and 64 bytes.
+.TP
+.B w \fIaddr val...\fR
+Write bytes to memory.
+.TP
+.B set \fIreg value\fR
+Set a register.
+.TP
+.B watch \fIaddr\fR [\fBr|w\fR] [\fIsize\fR]
+Set a hardware watchpoint; writes are watched by default.
+.TP
+.B unwatch [\fIslot\fR]
+Clear one watchpoint, or all without an argument.
+.TP
+.BR labels ", " l
+List function labels and offsets.
+.TP
+.BR help ", " h ", " ?
+Show command help.
+.TP
+.BR quit ", " q
+Kill the debuggee and exit.
+.SH OPTIONS
+.TP
+.B \-args \fIfile\fR
+File containing the ABI0 argument block.
+.TP
+.B \-buf \fIspec\fR
+Buffer specification: name:size:pattern[,name:size:pattern...] where
+pattern is zero, ones, seq, or hex.
+.TP
+.B \-cover
+Run to completion with a breakpoint on every instruction and report
+which executed and how often.
+.TP
+.B \-func \fIname\fR
+Function to debug.
+.TP
+.B \-script \fIfile\fR
+Run REPL commands from a file (one per line) and exit; - reads stdin.
+.TP
+.B \-timeout \fIduration\fR
+Kill the debuggee after this duration (e.g. 30s); for headless --script
+runs.
+.SH EXIT STATUS
+Exits 0 when the scripted session completes and 1 when the debuggee
+crashes or a check fails; the debugger is Linux-only.
+.SH EXAMPLES
+.nf
+gasm debug \-\-func name k.s
+gasm debug \-\-func name \-\-script cmds.txt \-\-timeout 30s k.s
+gasm debug \-\-func name \-\-cover k.s
+.fi
+.SH SEE ALSO
+.BR gasm (1),
+.BR gasm\-verify (1)