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

Assisted-by: GLM 5.3 Flash

docs/man/gasm-lint.1

@@ -0,0 +1,90 @@
+.TH GASM-LINT 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-lint \- run the static checks over assembly files
+.SH SYNOPSIS
+.B gasm lint <file...>
+.SH DESCRIPTION
+Run the static checks over the given files and print diagnostics as
+\fIfile:line:col: severity: message [code]\fR.  The exit status is
+non-zero when an error-severity diagnostic is found; warnings (e.g. the
+register-clobber audit) do not affect it.
+.PP
+The checks are conservative: they report what can be proven wrong and
+stay quiet otherwise, so a clean lint run is meaningful without
+suppression lists.
+.SH RULES
+.TP
+.B unknown-instruction
+The mnemonic is not in the architecture's instruction table.
+.TP
+.B operand-count
+The operand count disagrees with the instruction's declared arity.
+.TP
+.B undefined-label
+A jump target names no label in the function.
+.TP
+.B duplicate-label
+Two labels in one function share a name.
+.TP
+.B missing-ret
+The function can fall off its end without a terminator.
+.TP
+.B missing-textflag-include
+TEXT flags are used without including textflag.h.
+.TP
+.B abi-argsize
+The declared frame or argument size disagrees with the
+.B //\ function
+signature.
+.TP
+.B unreachable-code
+Code after RET and before the next label is dead; suppressed for
+functions with PC-relative or register-indirect control flow.
+.TP
+.B register-clobber
+A register the Go ABI fixes across calls is written without save and
+restore, computed by liveness over the control-flow graph.
+.TP
+.B funcdata-pcdata
+FUNCDATA and PCDATA indices are malformed.
+.TP
+.B unused-label
+A label no jump reaches.
+.TP
+.B invalid-textflag
+A TEXT flag combination the toolchain rejects.
+.TP
+.B stack-imbalance
+The function does not restore the stack pointer on every path.
+.TP
+.B register-width-mismatch
+An operand register has the wrong width for the instruction.
+.TP
+.B abi0-register-args
+A call passes arguments in registers where ABI0 expects the stack
+frame.
+.TP
+.B nonportable-register-name
+A register spelling that does not exist on the target architecture.
+.TP
+.B unencodable-instruction
+The mnemonic is known to the table but the encoder cannot assemble it
+yet (amd64).
+.TP
+.B reserved-register-write
+A write to the register the runtime reserves (arm64 R18).
+.SH OPTIONS
+.TP
+.B \-disable \fIcodes\fR
+Comma-separated rule codes to disable.
+.SH EXIT STATUS
+Exits 0 when no error-severity diagnostic is found, 1 otherwise, and 2
+on a usage error.
+.SH EXAMPLES
+.nf
+gasm lint kernel_amd64.s
+gasm lint \-disable register-clobber,unused-label *.s
+.fi
+.SH SEE ALSO
+.BR gasm (1),
+.BR gasm\-asm (1)