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

Assisted-by: GLM 5.3 Flash

docs/man/gasm-diff.1

@@ -0,0 +1,35 @@
+.TH GASM-DIFF 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-diff \- compare the machine code of two assembly files
+.SH SYNOPSIS
+.B gasm diff [\-GOARCH arch] <file1.s> <file2.s>
+.SH DESCRIPTION
+Compare the machine code produced by assembling two files.  Shows which
+functions differ and the byte-level differences.  Useful for verifying
+that two implementations produce identical code, or for tracking
+encoding changes between Go assembler versions.
+.PP
+Functions are paired by exact name unless
+.B \-\-map
+says otherwise, so
+.B \-\-map wideCopyAVX2=wideCopyAVX512
+pairs two variants regardless of suffix.
+.SH OPTIONS
+.TP
+.B \-GOARCH \fIarch\fR
+Target architecture for both files: amd64, arm64, riscv64 or loong64;
+overrides the file-name suffixes.
+.TP
+.B \-\-map \fIspec\fR
+Comma-separated old=new pairs to match functions with different names.
+.SH EXIT STATUS
+Exits 0 when every paired function is identical and 1 when anything
+differs; a usage error exits 2.
+.SH EXAMPLES
+.nf
+gasm diff hello_amd64.s hello_amd64.s
+gasm diff \-\-map wideCopyAVX2=wideCopyAVX512 avx2.s avx512.s
+.fi
+.SH SEE ALSO
+.BR gasm (1),
+.BR gasm\-asm (1)