Merge branch 'better_disasm' into optimize_mcode

docs/compiler-tools.md

@@ -28,6 +28,8 @@ Each stage has a corresponding CLI tool that lets you see its output.
 | streamline  | `streamline.ce --types`   | Optimized IR with type annotations     |
 | streamline  | `streamline.ce --stats`   | Per-function summary stats             |
 | streamline  | `streamline.ce --ir`      | Human-readable canonical IR            |
+| disasm      | `disasm.ce`               | Source-interleaved disassembly          |
+| disasm      | `disasm.ce --optimized`   | Optimized source-interleaved disassembly |
 | all         | `ir_report.ce`            | Structured optimizer flight recorder   |
 
 All tools take a source file as input and run the pipeline up to the relevant stage.
@@ -38,6 +40,9 @@ All tools take a source file as input and run the pipeline up to the relevant st
 # see raw mcode IR (pretty-printed)
 cell mcode --pretty myfile.ce
 
+# source-interleaved disassembly
+cell disasm myfile.ce
+
 # see optimized IR with type annotations
 cell streamline --types myfile.ce
 
@@ -86,6 +91,56 @@ cell streamline --diagnose <file.ce|file.cm>     # compile-time diagnostics
 
 Flags can be combined.
 
+## disasm.ce
+
+Source-interleaved disassembly. Shows mcode or optimized IR with source lines interleaved, making it easy to see which instructions were generated from which source code.
+
+```bash
+cell disasm <file>                         # disassemble all functions (mcode)
+cell disasm --optimized <file>             # disassemble optimized IR (streamline)
+cell disasm --fn 87 <file>                 # show only function 87
+cell disasm --fn my_func <file>            # show only functions named "my_func"
+cell disasm --line 235 <file>              # show instructions generated from line 235
+```
+
+| Flag | Description |
+|------|-------------|
+| (none) | Raw mcode IR with source interleaving (default) |
+| `--optimized` | Use optimized IR (streamline) instead of raw mcode |
+| `--fn <N\|name>` | Filter to specific function by index or name substring |
+| `--line <N>` | Show only instructions generated from a specific source line |
+
+### Output Format
+
+Functions are shown with a header including argument count, slot count, and the source line where the function begins. Instructions are grouped by source line, with the source text shown before each group:
+
+```
+=== [87] <anonymous> (args=0, slots=12, closures=0) [line 234] ===
+
+  --- line 235: var result = compute(x, y) ---
+  0     access         2, "compute"                           :235
+  1     get            3, 1, 0                                :235
+  2     get            4, 1, 1                                :235
+  3     invoke         3, 2, 2                                :235
+
+  --- line 236: if (result > 0) { ---
+  4     access         5, 0                                   :236
+  5     gt             6, 4, 5                                :236
+  6     jump_false     6, "else_1"                            :236
+```
+
+Each instruction line shows:
+- Program counter (left-aligned)
+- Opcode
+- Operands (comma-separated)
+- Source line number (`:N` suffix, right-aligned)
+
+Function creation instructions include a cross-reference annotation showing the target function's name:
+
+```
+  3     function       5, 12                                  :235  ; -> [12] helper_fn
+```
+
 ## seed.ce
 
 Regenerates the boot seed files in `boot/`. These are pre-compiled mcode IR (JSON) files that bootstrap the compilation pipeline on cold start.