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

Assisted-by: GLM 5.3 Flash

docs/man/gasm-asm.1

@@ -0,0 +1,62 @@
+.TH GASM-ASM 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.SH NAME
+gasm-asm \- assemble Plan 9 assembly without the Go toolchain
+.SH SYNOPSIS
+.B gasm asm [\-\-format raw|elf|goobj] [\-p pkg] [\-GOARCH arch] [\-o out] <file>
+.SH DESCRIPTION
+Assemble FILE without the Go toolchain: every TEXT function is encoded
+to machine code and printed as a hex dump.  Supported architectures:
+amd64 (including VEX/AVX2 and EVEX/AVX-512), arm64 (AArch64 integer,
+FP, conditional select, CRC32 and MOV pseudo), riscv64 (RV64IMAFDC and
+RVC) and loong64 (LoongArch base ISA).
+.PP
+With
+.B \-o
+the output is written to a file instead.  The
+.B \-\-format
+flag selects what is written:
+.B raw
+(the default) concatenates the functions and the data section into one
+self-consistent image;
+.B elf
+emits a relocatable object (.text/.data sections, a symbol table and
+one PC32 relocation per static-symbol reference) that links with the
+system toolchain;
+.B goobj
+emits the Go toolchain's own object format, which cmd/link consumes
+directly (it requires
+.BR \-p ,
+the package path, and the installed Go toolchain).
+.PP
+Framed functions receive the stack-split guard and the trailing
+morestack block, byte-identical to the toolchain's output, so split
+functions link too.
+.SH OPTIONS
+.TP
+.B \-\-format \fIraw|elf|goobj\fR
+Output format; the default is raw.
+.TP
+.B \-p \fIpkg\fR
+Package path for --format goobj, qualifying the exported symbols.
+.TP
+.B \-GOARCH \fIarch\fR
+Target architecture: amd64, arm64, riscv64 or loong64; overrides the
+file-name suffix, which is how the suffix-less majority of GOROOT's
+files (cpu_x86.s, stub.s, ...) become assemblable.
+.TP
+.B \-o \fIfile\fR
+Write the output to this file instead of a hex dump on stdout.
+.SH EXIT STATUS
+Exits 0 on success, 1 when parsing or assembly fails, and 2 on a usage
+error.
+.SH EXAMPLES
+.nf
+gasm asm \-o hello.bin hello_amd64.s               raw image
+gasm asm \-\-format elf \-o k.o k.s                 linkable ELF object
+gasm asm \-\-format goobj \-p pkg/path \-o k.o k.s   Go object for go build
+gasm asm \-GOARCH amd64 cpu_x86.s                  arch override
+.fi
+.SH SEE ALSO
+.BR gasm (1),
+.BR gasm\-dis (1),
+.BR gasm\-verify (1)