feat: restructure CLI around subcommands (run/test/disasm/build), hard-break the old mode flags

--test, --disasm, --emit-gbc <path>, and --emit-gbc-module <path> were
flags dressed up as different modes (run vs. run-test-blocks vs.
compile-only-and-disassemble vs. compile-only-and-write-an-artifact)
rather than ordinary settings. gengo bundle already exists as a real
subcommand for exactly this reason; extended that same argv[1]-dispatch
pattern to run/test/disasm/build, routed through the existing flag-parsing
loop so every modifier flag (--heap, --cap, --mount, --modules, --max-ops,
--backend, --no-fusion, --net-listen-allow, --net-dial-allow,
--verify-source) keeps working identically under every subcommand with no
duplicated parsing logic.

gengo <script.gengo> (no subcommand) is unchanged -- still the default,
implicit run. gengo run/test/disasm/build <script> are the new explicit
forms; build takes -o/--output <path> (required) and --lib for the
linkable-module variant.

Hard break, not a soft deprecation: the old flags are gone entirely.
Hitting one now fails with a specific migration message instead of being
silently misparsed as a script path -- the existing arg loop had no
"unknown flag" branch at all, so simply deleting the flag blocks would
have made `gengo --test script.gengo` try to open a file literally named
--test.

Updated every doc referencing the removed flags (docs/cli.md,
docs/language.md, docs/changelog.md, docs/known-limitations.md) in the
same pass. No CI workflow, git hook, or tooling script used any of the
four removed flags to begin with, confirmed via a full grep sweep before
starting.

Verified under standard, -Dpreset=stress, and -Dgc_stress=true builds.

Author: ganehag

CHANGELOG.md

@@ -4,6 +4,39 @@ This changelog tracks notable language/runtime changes by implementation date.
 
 ## 2026-08-21
 
+### Change — CLI restructured around subcommands (`run`/`test`/`disasm`/`build`)
+
+`--test`, `--disasm`, `--emit-gbc <path>`, and `--emit-gbc-module <path>` were
+flags dressed up as different modes (run vs. run-test-blocks vs.
+compile-only-and-disassemble vs. compile-only-and-write-an-artifact) rather
+than ordinary settings — the same shape `gengo bundle` (already a real
+subcommand) exists specifically to avoid. Replaced with explicit
+subcommands, mirroring `bundle`'s existing `argv[1]`-dispatch pattern but
+routed through the same flag-parsing loop so every modifier flag (`--heap`,
+`--cap`, `--mount`, `--modules`, `--max-ops`, `--backend`, `--no-fusion`,
+`--net-listen-allow`, `--net-dial-allow`, `--verify-source`) keeps working
+identically under every subcommand with no duplicated parsing logic:
+
+- `gengo <script.gengo>` (no subcommand) is unchanged — still the default,
+  implicit `run`.
+- `gengo run <script.gengo>` — new explicit alias for the same thing.
+- `gengo test <script.gengo> [--profile]` — replaces `--test`/`--profile`.
+- `gengo disasm <script.gengo>` — replaces `--disasm`.
+- `gengo build <script.gengo> -o <path> [--lib]` — replaces
+  `--emit-gbc <path>` (default) / `--emit-gbc-module <path>` (`--lib`).
+
+Hard break, not a soft deprecation: `--test`/`--disasm`/`--emit-gbc`/
+`--emit-gbc-module` are gone entirely. Hitting one now fails with a specific
+migration message (e.g. `--test was removed — use \`gengo test <script>\`
+instead`) rather than being silently misparsed as a script path — the
+existing arg loop had no "unknown flag" branch at all, so simply deleting
+these blocks would have made `gengo --test script.gengo` try to open a file
+literally named `--test`. `--help` and every doc/example referencing the
+removed flags (`docs/cli.md`, `docs/language.md`, `docs/changelog.md`,
+`docs/known-limitations.md`) updated in the same pass; no CI workflow,
+git hook, or tooling script used any of the four removed flags to begin
+with (confirmed via a full grep sweep before starting).
+
 ### Fix — engine_slots handle-allocation race, and opt-in GBC source-staleness verification
 
 Two follow-ups from digging further into the engine C-API concurrency work

docs/changelog.md

@@ -30,8 +30,8 @@
 
 ### Tooling (unreleased)
 
-- **`gengo --test --profile`** — reports each `test` block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line, so integrators can size `engine_init_with_config`'s resource ceilings from measured workload data instead of guessing. Does not affect pass/fail behavior or the exit code; does cost real speed (forces per-instruction accounting on for the run), so it's a diagnostic flag, not something to leave on by default.
-- **`gengo --emit-gbc path` / running a `.gbc` directly** — an early GBC (Gengo Bytecode Cache) implementation: `--emit-gbc` compiles a script and writes a `.gbc` artifact instead of running it; a `.gbc` file passed as the script argument (recognized by magic bytes) loads and runs directly, skipping parsing and compilation. Covers plain and generic functions (real parameter/return types, so interface conformance checks keep working on a loaded function; a generic function's type parameters erase to `any` on the wire, matching their own runtime semantics — constraint checking is unaffected, since it runs at each call site's own compile time against the caller's concrete type arguments, not by inspecting a loaded callee's stored types), `std`/native calls, and struct, named-type, `variant`, `interface`, `enum`, and task/actor declarations (including range/cycle/clamp-constrained named types, a named type's `default` value and `scale`, a module/type-scope `predicate`, variants with shared fields and record/single-payload/no-payload arms, enums with explicit representation values, auto-incremented ordinals, and enum subtypes, spawning/sending/receiving through a task type loaded from a `.gbc` (running one now correctly drives the same task scheduler a normally-compiled program uses, not a one-shot run with no scheduler at all), and a predicate declared inside a function body that closes over the function's own locals, re-capturing fresh on every call exactly as it does compiled normally (this last one turned out to already work once checked directly — a closure with real captures is always built by ordinary `make_closure` bytecode at the point it's declared, never handed to the writer as a literal constant object, so there was nothing to reject in the first place). See `dev-docs/design/gbc-spec.md` and GitHub issue #5 for the full format and remaining scope; the CLI does not yet check a `.gbc`'s recorded source hash against the current source before running it, so regenerate one by hand when its source changes.
+- **`gengo test --profile`** — reports each `test` block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line, so integrators can size `engine_init_with_config`'s resource ceilings from measured workload data instead of guessing. Does not affect pass/fail behavior or the exit code; does cost real speed (forces per-instruction accounting on for the run), so it's a diagnostic flag, not something to leave on by default.
+- **`gengo build script.gengo -o path` / running a `.gbc` directly** — an early GBC (Gengo Bytecode Cache) implementation: `build` compiles a script and writes a `.gbc` artifact instead of running it; a `.gbc` file passed as the script argument (recognized by magic bytes) loads and runs directly, skipping parsing and compilation. Covers plain and generic functions (real parameter/return types, so interface conformance checks keep working on a loaded function; a generic function's type parameters erase to `any` on the wire, matching their own runtime semantics — constraint checking is unaffected, since it runs at each call site's own compile time against the caller's concrete type arguments, not by inspecting a loaded callee's stored types), `std`/native calls, and struct, named-type, `variant`, `interface`, `enum`, and task/actor declarations (including range/cycle/clamp-constrained named types, a named type's `default` value and `scale`, a module/type-scope `predicate`, variants with shared fields and record/single-payload/no-payload arms, enums with explicit representation values, auto-incremented ordinals, and enum subtypes, spawning/sending/receiving through a task type loaded from a `.gbc` (running one now correctly drives the same task scheduler a normally-compiled program uses, not a one-shot run with no scheduler at all), and a predicate declared inside a function body that closes over the function's own locals, re-capturing fresh on every call exactly as it does compiled normally (this last one turned out to already work once checked directly — a closure with real captures is always built by ordinary `make_closure` bytecode at the point it's declared, never handed to the writer as a literal constant object, so there was nothing to reject in the first place). See `dev-docs/design/gbc-spec.md` and GitHub issue #5 for the full format and remaining scope; pass `--verify-source path` when running a `.gbc` to check it against the current source (`SourceGraphStale` on drift) — omitted by default, so a `.gbc` remains runnable standalone without its source present.
 
 ### Fixes (unreleased)
 

docs/cli.md

@@ -7,15 +7,28 @@ this checkout from source and have not installed it, substitute
 ## Invocation
 
 ```text
-gengo [options] [script.gengo]
+gengo [run|test|disasm|build|bundle] [options] [script.gengo]
 ```
 
-Run a source file:
+Run a source file — no subcommand needed, `run` is implicit:
 
 ```bash
 gengo hello.gengo
 ```
 
+`gengo run hello.gengo` does exactly the same thing; the subcommand is there
+for scripts/docs that want to be explicit, or to sit alongside `test`/
+`disasm`/`build` as a sibling. The other subcommands switch what "compile
+this script" actually does instead of running it normally:
+
+| Command | Meaning |
+|---|---|
+| `run <script>` | Compile and run (the default — also what a bare `gengo <script>` does). |
+| `test <script>` | Run top-level `test` blocks rather than ordinary script execution. A failed test exits unsuccessfully. |
+| `disasm <script>` | Compile and print a bytecode disassembly without running the script. This is an implementation-debugging aid, not language semantics. |
+| `build <script> -o path` | Compile the script and write a GBC (Gengo Bytecode Cache) artifact to `path`; do not run. Add `--lib` to write a linkable GBC module artifact instead. See below. |
+| `bundle` | Package a script and its imports into a zip archive. See `gengo bundle --help`. |
+
 Use `-e` or `--eval` for a short program. It cannot be combined with a script
 path:
 
@@ -29,14 +42,18 @@ script from standard input instead.
 
 ## Options
 
+Modifier flags below work identically with or without a subcommand — they
+apply the same way to `gengo script.gengo`, `gengo test script.gengo`,
+`gengo build script.gengo -o out.gbc`, and so on.
+
 | Option | Meaning |
 |---|---|
 | `--help`, `-h` | Print the option summary and exit. |
 | `--version` | Print the CLI version and exit. |
-| `--disasm` | Compile and print a bytecode disassembly without running the script. This is an implementation-debugging aid, not language semantics. |
-| `--emit-gbc path` | Compile the script and write a GBC (Gengo Bytecode Cache) artifact to `path`; do not run. See below. |
-| `--test` | Run top-level `test` blocks rather than ordinary script execution. A failed test exits unsuccessfully. |
-| `--profile` | With `--test`, print each block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line. Does not affect pass/fail behavior or the exit code. Forces per-instruction instruction counting on for the run, which costs real speed — a diagnostic aid, not something to leave on by default. |
+| `-o`, `--output path` | `build`-only: the artifact path to write. Required with `build`. |
+| `--lib` | `build`-only: write a linkable GBC module artifact instead of a normal one. |
+| `--verify-source path` | When running a `.gbc` directly, reject it (`SourceGraphStale`) if it no longer matches this source file. See below. |
+| `--profile` | `test`-only: print each block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line. Does not affect pass/fail behavior or the exit code. Forces per-instruction instruction counting on for the run, which costs real speed — a diagnostic aid, not something to leave on by default. |
 | `--cap name` | Enable one named capability. Repeat for several capabilities. See `capabilities.md`; no capability is enabled merely by importing it. `cap:ffi` requires `--cap ffi` and is native-CLI only. |
 | `--cap net=scope1,scope2` | Scope the `net` capability instead of granting it unscoped. Scopes are `dial` and `listen`, comma-separated (`--cap net=dial`, `--cap net=listen`, `--cap net=dial,listen`). Bare `--cap net` (no `=`) still means dial-only, unchanged from before scopes existed — upgrading never silently grants listen. This general `name=scope1,scope2` syntax is available for any capability that defines scopes, not just `net`. |
 | `--net-listen-allow pattern[:port]` | Add an allow rule to `net.listen`'s bind policy, which defaults to deny-all (see `security.md`). Repeatable. `pattern` accepts the same shapes as the embedding API's policy rules (`"*"`, exact IPv4/IPv6, CIDR, hostname wildcard); an optional `:port` suffix restricts to one port (bracket the pattern for a literal IPv6 address with a port, e.g. `"[::1]:8080"`). With no rules, `--cap net=listen` alone still makes `net.listen(...)` compile and import but refuse every call. |
@@ -78,13 +95,14 @@ for traversal, symlink, and host-platform limits.
 
 ## GBC (Bytecode Cache)
 
-`--emit-gbc path` compiles a script and writes a `.gbc` artifact instead of
-running it. A `.gbc` file passed as the script argument runs directly,
-skipping parsing and compilation entirely — the file is recognized by its
-magic bytes, not its extension, though naming it `.gbc` is the convention:
+`gengo build script.gengo -o path` compiles a script and writes a `.gbc`
+artifact instead of running it. A `.gbc` file passed as the script argument
+runs directly, skipping parsing and compilation entirely — the file is
+recognized by its magic bytes, not its extension, though naming it `.gbc` is
+the convention:
 
 ```bash
-gengo --emit-gbc app.gbc app.gengo    # compile once
+gengo build app.gengo -o app.gbc      # compile once
 gengo app.gbc                         # run the cached artifact, repeatedly
 ```
 
@@ -105,16 +123,19 @@ This is early — the current implementation covers a first milestone (see
   attached via ordinary bytecode execution rather than embedded as a
   constant, both work), or a generic function declaration (generic struct
   and variant types alone round-trip correctly; the rejection triggers only
-  when the script declares a `func` with type parameters). `--emit-gbc`
-  fails with a clear error naming the limitation rather than producing a
-  broken artifact.
-- The artifact records a hash of the source it was compiled from, but the
-  CLI does not yet check it against the current source file before running
-  a `.gbc` — nothing currently stops you from running a `.gbc` that no
-  longer matches its `.gengo` source. Treat a `.gbc` as something you
-  regenerate whenever its source changes, not as a transparent, self-invalidating
-  cache yet.
-- `--emit-gbc` is not currently supported when running the WASI build.
+  when the script declares a `func` with type parameters). `build` fails
+  with a clear error naming the limitation rather than producing a broken
+  artifact.
+- The artifact always records a hash of the source it was compiled from, but
+  running a `.gbc` doesn't check it by default — nothing stops you from
+  running a `.gbc` that no longer matches its `.gengo` source unless you ask
+  for the check. Pass `--verify-source path` (naming the original `.gengo`
+  file) when running a `.gbc` to opt in: a mismatch fails with
+  `SourceGraphStale` instead of silently executing stale bytecode.
+  ```bash
+  gengo --verify-source app.gengo app.gbc
+  ```
+- `gengo build` is not currently supported when running the WASI build.
 
 ## REPL
 

docs/known-limitations.md

@@ -34,8 +34,8 @@ The relevant specifications include
 
 | Area | Current behaviour | Practical consequence |
 |---|---|---|
-| `--emit-gbc` source hash | The artifact records a hash of the source it was compiled from, but the CLI does not yet verify it before running the artifact. | Regenerate the `.gbc` whenever its `.gengo` source changes; do not rely on automatic invalidation. |
-| `--emit-gbc` on WASI | `--emit-gbc` is not supported in the WASI build. | Use the native CLI for GBC emission; run the artifact from WASI if needed. |
+| `gengo build` source hash | The artifact always records a hash of the source it was compiled from, but running a `.gbc` only verifies it against `--verify-source path` when that flag is given — a `.gbc` must remain runnable standalone with no source present, so verification can't be mandatory. | Pass `--verify-source path` when the original `.gengo` file is available and drift should fail loudly (`SourceGraphStale`); otherwise regenerate the `.gbc` by hand whenever its source changes. |
+| `gengo build` on WASI | `gengo build` is not supported in the WASI build. | Use the native CLI for GBC emission; run the artifact from WASI if needed. |
 
 ## Security and Operations
 

docs/language.md

@@ -1918,10 +1918,10 @@ test "range check" {
 
 **Normal execution skips test blocks.** Running `gengo script.gengo` executes the script body but ignores all `test` blocks entirely. No test code runs, and no test infrastructure is paid for.
 
-**`--test` activates them:**
+**`gengo test` activates them:**
 
 ```bash
-gengo script.gengo --test
+gengo test script.gengo
 ```
 
 Each test block runs in order. Results go to stderr: