tooling improvements

docs/cli.md

@@ -65,6 +65,7 @@ pit build -b debug                # build type: release (default), debug, minsiz
 pit build --list-targets          # list available targets
 pit build --force                 # force rebuild
 pit build --dry-run               # show what would be built
+pit build --verbose               # print resolved flags, commands, cache status
 ```
 
 ### pit test
@@ -330,9 +331,14 @@ pit mcode <file.cm>
 Apply the full optimization pipeline to a source file and output optimized mcode as JSON.
 
 ```bash
-pit streamline <file.cm>
+pit streamline <file.cm>                # full optimized IR as JSON (default)
+pit streamline --stats <file.cm>        # summary stats per function
+pit streamline --ir <file.cm>           # human-readable IR
+pit streamline --check <file.cm>        # warnings only (e.g. high slot count)
 ```
 
+Flags can be combined. `--stats` output includes function name, args, slots, instruction counts by category, and nops eliminated. `--check` warns when `nr_slots > 200` (approaching the 255 limit).
+
 ### pit qbe
 
 Compile a source file to QBE intermediate language (for native code generation).
@@ -367,6 +373,17 @@ Ahead-of-time compile and execute a program natively.
 pit run_aot <program.ce>
 ```
 
+### pit seed
+
+Regenerate the boot seed files in `boot/`. Seeds are pre-compiled mcode IR (JSON) that bootstrap the compilation pipeline on cold start. They only need regenerating when the pipeline source changes in a way the existing seeds can't compile, or before distribution.
+
+```bash
+pit seed                # regenerate all boot seeds
+pit seed --clean        # also clear the build cache after
+```
+
+The engine recompiles pipeline modules automatically when source changes (via content-addressed cache). Seeds are a fallback for cold start when no cache exists.
+
 ### Analysis
 
 ### pit explain

docs/compiler-tools.md

@@ -81,9 +81,37 @@ Shows the optimized IR with type annotations. Each instruction is followed by th
 Runs the full pipeline (tokenize, parse, fold, mcode, streamline) and outputs the optimized IR as JSON. Useful for piping to `jq` or saving for comparison.
 
 ```bash
-./cell --core . streamline.ce <file.ce|file.cm>
+./cell --core . streamline.ce <file.ce|file.cm>                # full JSON (default)
+./cell --core . streamline.ce --stats <file.ce|file.cm>        # summary stats per function
+./cell --core . streamline.ce --ir <file.ce|file.cm>           # human-readable IR
+./cell --core . streamline.ce --check <file.ce|file.cm>        # warnings only
 ```
 
+| Flag | Description |
+|------|-------------|
+| (none) | Full optimized IR as JSON (backward compatible) |
+| `--stats` | Per-function summary: args, slots, instruction counts by category, nops eliminated |
+| `--ir` | Human-readable canonical IR (same format as `ir_report.ce`) |
+| `--check` | Warnings only (e.g. `nr_slots > 200` approaching 255 limit) |
+
+Flags can be combined.
+
+## 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.
+
+```bash
+./cell --core . seed.ce                # regenerate all boot seeds
+./cell --core . seed.ce --clean        # also clear the build cache after
+```
+
+The script compiles each pipeline module (tokenize, parse, fold, mcode, streamline) and `internal/bootstrap.cm` through the current pipeline, encodes the output as JSON, and writes it to `boot/<name>.cm.mcode`.
+
+**When to regenerate seeds:**
+- Before a release or distribution
+- When the pipeline source changes in a way the existing seeds can't compile the new source (e.g. language-level changes)
+- Seeds do NOT need regenerating for normal development — the engine recompiles pipeline modules from source automatically via the content-addressed cache
+
 ## ir_report.ce
 
 The optimizer flight recorder. Runs the full pipeline with structured logging and outputs machine-readable, diff-friendly JSON. This is the most detailed tool for understanding what the optimizer did and why.

docs/packages.md

@@ -9,11 +9,11 @@ Packages are the fundamental unit of code organization and sharing in ƿit.
 
 ## Package Structure
 
-A package is a directory containing a `pit.toml` manifest:
+A package is a directory containing a `cell.toml` manifest:
 
 ```
 mypackage/
-├── pit.toml         # package manifest
+├── cell.toml         # package manifest
 ├── main.ce          # entry point (optional)
 ├── utils.cm         # module
 ├── helper/
@@ -23,7 +23,7 @@ mypackage/
     └── helpers.cm   # private module (internal/ only)
 ```
 
-## pit.toml
+## cell.toml
 
 The package manifest declares metadata and dependencies:
 
@@ -47,7 +47,7 @@ mylib = "/Users/john/work/mylib"
 When importing with `use()`, ƿit searches in order:
 
 1. **Local package** — relative to package root
-2. **Dependencies** — via aliases in `pit.toml`
+2. **Dependencies** — via aliases in `cell.toml`
 3. **Core** — built-in ƿit modules
 
 ```javascript
@@ -179,7 +179,7 @@ C files in a package are compiled into per-file dynamic libraries:
 
 ```
 mypackage/
-├── pit.toml
+├── cell.toml
 ├── render.c      # compiled to lib/mypackage/render.dylib
 └── physics.c     # compiled to lib/mypackage/physics.dylib
 ```

docs/shop.md

@@ -48,7 +48,7 @@ When `use('path')` is called from a package context, the shop resolves the modul
 For a call like `use('sprite')` from package `myapp`:
 
 1. **Own package** — `~/.pit/packages/myapp/sprite.cm` and C symbol `js_myapp_sprite_use`
-2. **Aliased dependencies** — if `myapp/pit.toml` has `renderer = "gitea.pockle.world/john/renderer"`, checks `renderer/sprite.cm` and its C symbols
+2. **Aliased dependencies** — if `myapp/cell.toml` has `renderer = "gitea.pockle.world/john/renderer"`, checks `renderer/sprite.cm` and its C symbols
 3. **Core** — built-in core modules and internal C symbols
 
 For calls without a package context (from core modules), only core is searched.

docs/spec/pipeline.md

@@ -93,6 +93,25 @@ String constants are interned in a data section. Integer constants are encoded i
 pit --emit-qbe script.ce > output.ssa
 ```
 
+## Boot Seeds
+
+The `boot/` directory contains pre-compiled mcode IR (JSON) seed files for the pipeline modules:
+
+```
+boot/tokenize.cm.mcode
+boot/parse.cm.mcode
+boot/fold.cm.mcode
+boot/mcode.cm.mcode
+boot/streamline.cm.mcode
+boot/bootstrap.cm.mcode
+```
+
+Seeds are used during cold start (empty cache) to compile the pipeline modules from source. The engine's `load_pipeline_module()` hashes the **source file** content — if the source changes, the hash changes, the cache misses, and the module is recompiled from source using the boot seeds. This means:
+
+- Editing a pipeline module (e.g. `tokenize.cm`) takes effect on the next run automatically
+- Seeds only need regenerating if the pipeline changes in a way the existing seeds can't compile the new source, or before distribution
+- Use `pit seed` to regenerate all seeds, and `pit seed --clean` to also clear the build cache
+
 ## Files
 
 | File | Role |