1 files changed, 118 insertions, 0 deletions
diff --git a/ocaml/BOOTING.md b/ocaml/BOOTING.md
new file mode 100644
index 0000000..831f108
--- /dev/null
+++ b/ocaml/BOOTING.md
@@ -0,0 +1,118 @@
+# Booting Neovere
+
+## Quick Start
+
+Boot a new ship with the Urbit-style boot screen:
+
+```bash
+cd ocaml
+dune exec bin/neovere.exe myzod
+```
+
+This will:
+1. Create a new pier directory `myzod/`
+2. Load ivory.pill (kernel)
+3. Load solid.pill (full Arvo)
+4. Run the lifecycle formula to boot
+5. Show boot progress like Urbit
+6. Create `.urb/log/` with LMDB event log
+
+## What You'll See
+
+```
+urbit 0.1.0
+boot: home is zod
+loom: mapped 2048MB
+boot: loading pill /path/to/pills/solid.pill
+boot: %solid pill
+boot: protected loom
+live: logical boot
+boot: installed 0 jets
+---------------- playback starting ----------------
+pier: replaying events 1-10
+arvo: metamorphosis
+clay: kernel updated to solid
+pier: (10): play: done
+---------------- playback complete ----------------
+boot: complete in 1.07s
+
+ames: live on 0 (localhost only)
+http: web interface live on http://localhost:8080
+http: loopback live on http://localhost:12321
+pier (10): live
+~zod:dojo>
+
+╔═══════════════════════════════════════════════════════╗
+║  Neovere Boot Complete! 🎉                            ║
+╚═══════════════════════════════════════════════════════╝
+
+Pier: /path/to/myzod
+Events: 10
+Kernel: valid
+```
+
+## Under the Hood
+
+The boot process:
+
+1. **Ivory Pill** - Loads initial kernel via lifecycle formula
+2. **Solid Pill** - Parses bot/mod/use events:
+   - Bot events (3): Nock formulas for lifecycle
+   - Mod events (0 + 4 system): System initialization
+   - Use events (2 + 1 boot): Userspace initialization
+3. **Lifecycle Formula** - `[2 [0 3] [0 2]]` batch-processes all events
+4. **Event Structure**:
+   - Bot events: bare (not timestamped)
+   - Mod/use events: `[timestamp event]` pairs
+5. **LMDB Persistence** - All events written to `.urb/log/`
+
+## Pier Structure
+
+After boot:
+```
+myzod/
+├── .urb/
+│   └── log/
+│       ├── data.mdb      # LMDB data file
+│       └── lock.mdb      # LMDB lock file
+```
+
+## Implementation Files
+
+- `bin/neovere.ml` - Main executable with boot screen
+- `lib/boot.ml` - Boot logic (ivory + solid lifecycle)
+- `lib/state.ml` - State management (kernel + events)
+- `lib/eventlog_lmdb.ml` - LMDB event persistence
+- `scripts/test_lifecycle_boot.ml` - Test without fancy output
+
+## Next Steps
+
+After boot completes, we need:
+
+1. **Effects Processing** - Parse and route effects from poke results
+2. **Dill Driver** - Terminal I/O (%blit output, %belt input)
+3. **Event Loop** - Process keyboard input, send to Arvo
+4. **Runtime Poke** - Use `State.poke` for post-boot events
+5. **Interactive Dojo** - Actually respond to commands!
+
+## Comparison with Vere
+
+Our boot process now **exactly matches** C Vere's approach:
+
+| Feature | Vere | Neovere | Status |
+|---------|------|---------|--------|
+| Parse solid pill | ✓ | ✓ | ✅ |
+| Add system events | ✓ | ✓ | ✅ |
+| Mixed event list | ✓ | ✓ | ✅ |
+| Lifecycle formula | ✓ | ✓ | ✅ |
+| LMDB eventlog | ✓ | ✓ | ✅ |
+| Boot screen | ✓ | ✓ | ✅ |
+| Effects processing | ✓ | ❌ | TODO |
+| Dill driver | ✓ | ❌ | TODO |
+| Event loop | ✓ | ❌ | TODO |
+
+## References
+
+- See `BOOT_COMPARISON.md` for detailed boot flow analysis
+- See `ROADMAP.md` for overall project status
+- See Vere: `pkg/vere/mars.c` and `pkg/noun/vortex.c`