docs: drop process labels and refresh the architecture and manual pages

Assisted-by: GLM 5.3

cmd/gasm/man_test.go

@@ -62,6 +62,42 @@ func TestManPagesTrackTheCLI(t *testing.T) {
 	}
 }
 
+// TestManCommandsTrackHelp compares the gasm(1) COMMANDS list with the
+// top-level help output, so a subcommand added to the binary cannot miss
+// its man entry and a stale entry cannot outlive its command.
+func TestManCommandsTrackHelp(t *testing.T) {
+	if testing.Short() {
+		t.Skip("builds the gasm binary")
+	}
+	bin := filepath.Join(t.TempDir(), "gasm")
+	if out, err := exec.Command("go", "build", "-o", bin, ".").CombinedOutput(); err != nil {
+		t.Fatalf("build gasm: %v\n%s", err, out)
+	}
+
+	raw, err := os.ReadFile(filepath.Join("..", "..", "docs", "man", "gasm.1"))
+	if err != nil {
+		t.Fatalf("read man page: %v", err)
+	}
+
+	helpOut, err := exec.Command(bin, "--help").Output()
+	if err != nil {
+		t.Fatalf("gasm --help: %v", err)
+	}
+
+	binCmds := helpCommands(string(helpOut))
+	pageCmds := roffCommands(string(raw))
+	for c := range binCmds {
+		if !pageCmds[c] {
+			t.Errorf("command %q is in the binary's help but missing from gasm(1) COMMANDS", c)
+		}
+	}
+	for c := range pageCmds {
+		if !binCmds[c] {
+			t.Errorf("command %q is in gasm(1) COMMANDS but the binary does not list it", c)
+		}
+	}
+}
+
 // helpFlags extracts the flag names from a `gasm <cmd> -h` output.
 func helpFlags(help string) map[string]bool {
 	m := map[string]bool{}
@@ -123,6 +159,54 @@ func roffFlags(page string) map[string]bool {
 	return m
 }
 
+// helpCommands extracts the command names from the top-level help output's
+// Commands section.
+func helpCommands(help string) map[string]bool {
+	m := map[string]bool{}
+	inCmds := false
+	for line := range strings.SplitSeq(help, "\n") {
+		if strings.TrimSpace(line) == "Commands:" {
+			inCmds = true
+			continue
+		}
+		if !inCmds {
+			continue
+		}
+		t := strings.TrimSpace(line)
+		if t == "" {
+			break
+		}
+		name, _, _ := strings.Cut(t, " ")
+		m[name] = true
+	}
+	return m
+}
+
+// roffCommands extracts the command names from gasm(1)'s COMMANDS section,
+// where each entry is written as `.B gasm\-<name>(1)` or `.B gasm <name>`.
+func roffCommands(page string) map[string]bool {
+	m := map[string]bool{}
+	inCmds := false
+	for line := range strings.SplitSeq(page, "\n") {
+		if strings.HasPrefix(line, ".SH ") {
+			inCmds = strings.HasPrefix(line, ".SH COMMANDS")
+			continue
+		}
+		if !inCmds || !strings.HasPrefix(line, ".B gasm") {
+			continue
+		}
+		entry := strings.ReplaceAll(strings.TrimPrefix(line, ".B "), `\-`, "-")
+		entry = strings.TrimSuffix(entry, "(1)")
+		switch {
+		case strings.HasPrefix(entry, "gasm-"):
+			m[strings.TrimPrefix(entry, "gasm-")] = true
+		case strings.HasPrefix(entry, "gasm "):
+			m[strings.TrimPrefix(entry, "gasm ")] = true
+		}
+	}
+	return m
+}
+
 // helpUsage returns the command's usage line without the "Usage: " prefix.
 func helpUsage(help string) string {
 	for line := range strings.SplitSeq(help, "\n") {