tooling improvements

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 |