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

Assisted-by: GLM 5.3 Flash

docs/man/gasm-verify.1

@@ -0,0 +1,117 @@
+.TH GASM-VERIFY 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-verify \- JIT-assemble a file and run dynamic checks against it
+.SH SYNOPSIS
+.B gasm verify [\-smoke] [\-abi] [\-fuzz] [\-ground\-truth] [\-profile] [\-call] <file.s>
+.SH DESCRIPTION
+Assemble FILE, map it into executable memory and report the available
+functions.  This confirms the assembled image is self-consistent (no
+unresolved external symbols) and executable, the prerequisite for
+dynamic testing.
+.PP
+With
+.BR \-smoke ,
+each NOSPLIT function is called with a zeroed argument block to confirm
+the JIT trampoline works end-to-end.  This is safe only for functions
+that tolerate nil pointers and zero lengths in their arguments.
+.PP
+With
+.BR \-abi ,
+each function is called with sentinel values in the registers the Go
+ABI fixes across calls (the frame pointer and the goroutine pointer)
+plus a canary below SP; violations are reported.  JIT-based checks run
+when the host matches the file's architecture (all but loong64, which
+is ground-truth only for now).
+.PP
+With
+.BR \-fuzz ,
+each function with a
+.B //\ func
+signature is differentially fuzzed against the go-tool-asm version in a
+subprocess (so a crash on a partial function is reported, not fatal).
+.PP
+With
+.BR \-ground\-truth ,
+the assembled machine code is compared byte-for-byte against
+.B go tool asm
+(relocation sites masked), reporting any encoding drift.
+.PP
+With
+.BR \-profile ,
+the static basic-block structure is listed for each function.
+.PP
+With
+.BR \-call ,
+a single function is invoked with user-supplied buffers
+.RB ( \-buf )
+instead of the smoke/abi/fuzz sweeps.  Useful for partial functions
+(e.g. decoders) that crash on random input but should succeed on valid
+data.
+.PP
+With
+.B \-save\-corpus
+(and
+.BR \-fuzz ),
+every input that crashes or mismatches is written to the directory as
+replayable JSON.
+.B \-replay
+re-runs saved entries against the kernel, one child process per entry,
+so an input that crashed the original run crashes only the child: the
+report says whether each entry reproduces.
+.SH OPTIONS
+.TP
+.B \-abi
+Run ABI-checking calls (sentinel registers and red zone).
+.TP
+.B \-abi\-n \fIn\fR
+Number of ABI check iterations with varied inputs; the default is 100.
+.TP
+.B \-args \fIspec\fR
+Scalar args for -call: name=value[,name=value] (decimal or 0x hex).
+.TP
+.B \-buf \fIspec\fR
+Buffer spec for -call: name:size:pattern[,name:size:pattern] where
+pattern is zero, ones, seq, or hex.
+.TP
+.B \-call \fIname\fR
+Call a single function with -buf instead of the sweeps.
+.TP
+.B \-fuzz
+Differential fuzz: JIT both the gasm and the go-tool-asm versions and
+compare outputs.
+.TP
+.B \-ground\-truth
+Compare machine code byte-for-byte against go tool asm.
+.TP
+.B \-n \fIn\fR
+Number of fuzz iterations per function; the default is 1000.
+.TP
+.B \-profile
+List basic-block structure per function.
+.TP
+.B \-repeat \fIn\fR
+Number of times to repeat a -call invocation; the default is 1.
+.TP
+.B \-replay \fIdir\fR
+Replay saved corpus entries (JSON files in this directory) against the
+kernel.
+.TP
+.B \-save\-corpus \fIdir\fR
+With -fuzz: write each failing input to this directory as replayable
+JSON.
+.TP
+.B \-smoke
+Call each NOSPLIT function with zeroed args.
+.SH EXIT STATUS
+Exits 0 when every requested check passes and 1 when any check fails;
+a file that cannot be assembled exits 1 and a usage error exits 2.
+.SH EXAMPLES
+.nf
+gasm verify \-\-call add \-\-args a=2,b=3 hello_amd64.s
+gasm verify \-\-ground\-truth k.s
+gasm verify \-\-fuzz \-n 500 k.s
+.fi
+.SH SEE ALSO
+.BR gasm (1),
+.BR gasm\-asm (1),
+.BR gasm\-debug (1)