docs: fold development changes into v0.29.0, document --call/--buf/--map

docs/ARCHITECTURE.md

@@ -323,7 +323,13 @@ ABI checks (sentinel registers, canary, stack bounds) with differential fuzz
 testing, comparing the JIT-assembled kernel against the portable Go reference
 bit-for-bit while verifying the ABI contract on every iteration.  When a fuzz
 iteration crashes or mismatches, `FuzzResult.CrashInput` stores the exact input
-for reproducibility.
+for reproducibility.  `gasm verify --call <func> --buf name:size:pattern`
+invokes a single function with user-supplied buffers (patterns: zero, ones,
+seq, or hex), printing the ABI0 argument block before and after the call —
+useful for partial functions (e.g. decoders) that crash on random input but
+should succeed on valid data.  `gasm verify --ground-truth` compares the
+assembled machine code byte-for-byte against `go tool asm` (relocation sites
+masked), reporting any encoding drift.
 
 ### `debug`
 

docs/cli.md

@@ -70,14 +70,25 @@ Assemble FILE, map it into executable memory, and run dynamic checks.
 | `--fuzz` | Differential fuzz: JIT both gasm and go-tool-asm, compare outputs |
 | `-n` | Fuzz iterations per function (default: 1000) |
 | `--abi` | Run ABI-checking calls (sentinel registers + red zone) |
+| `--abi-n` | Number of ABI check iterations with varied inputs (default: 100) |
 | `--profile` | List basic-block structure per function |
 | `--smoke` | Call each NOSPLIT function with zeroed args |
+| `--call <func>` | Invoke a single function with `--buf` instead of the sweeps |
+| `--buf <spec>` | Buffer spec for `--call`: `name:size:pattern[,name:size:pattern]` |
+| `--repeat <n>` | Number of times to repeat a `--call` invocation (default: 1) |
 
 The `--fuzz` mode runs each function in a subprocess; a partial function
 (e.g. a decoder that faults on malformed input) is reported as
-`CRASH` without killing the parent. Use `--ground-truth` for decoders.
+`CRASH` without killing the parent. Use `--call` with `--buf` to invoke
+partial functions with valid data instead.
 
-## `gasm debug --func <name> <file.s>`
+The `--call` mode parses the `// func` signature, allocates the requested
+buffers (`zero`, `ones`, `seq`, or a hex blob), builds the ABI0 argument
+block with buffer pointers/lengths/capacities at the matching parameter
+offsets, and prints the arg block before and after the call — showing
+return values and any output written to the buffers.
+
+## `gasm debug --func <name> [--buf spec] <file.s>`
 
 Interactive debugger for JIT-assembled amd64 functions. Requires a
 compiled binary on `$PATH` (not `go run`).
@@ -85,6 +96,7 @@ compiled binary on `$PATH` (not `go run`).
 | Flag | Description |
 |------|-------------|
 | `--func` | Function to debug (required) |
+| `--buf` | Buffer spec: `name:size:pattern[,name:size:pattern]` |
 
 REPL commands:
 
@@ -93,11 +105,34 @@ REPL commands:
 | `break <label\|addr>` | Set a breakpoint |
 | `step [n]` | Single-step n instructions |
 | `continue` | Run until next breakpoint or exit |
-| `regs` | Print general-purpose registers |
+| `regs` | Print general-purpose + YMM/XMM vector registers |
 | `x [addr] [len]` | Hex-dump memory |
 | `labels` | List function labels and offsets |
 | `quit` | Kill the debuggee and exit |
 
+## `gasm diff [--map old=new,...] <file1.s> <file2.s>`
+
+Compare the machine code produced by assembling two files. Shows which
+functions differ and the first few differing bytes. Useful for verifying
+that two implementations produce identical code, or for tracking encoding
+changes between Go assembler versions.
+
+| Flag | Description |
+|------|-------------|
+| `--map` | Comma-separated `old=new` pairs to match functions with different names |
+
+Without `--map`, functions are paired by exact name. With `--map`, a
+function named `old` in the first file is compared against the function
+named `new` in the second file (e.g. `--map wideCopyAVX2=wideCopyAVX512`
+pairs AVX2 and AVX-512 variants regardless of suffix).
+
+## `gasm profile <file.s>`
+
+Show the basic-block structure of functions in an assembly file. Lists
+each function's labels, their offsets, and the block boundaries. This is
+the static structure; for runtime execution counts, use `gasm verify
+--fuzz` which exercises the code paths.
+
 ## `gasm lsp`
 
 Run the language server over standard input/output (JSON-RPC 2.0 with