docs(readme): add startup flow diagram

[JoergZeidler]

Summary

Adds a Mermaid flowchart to the README that traces every startup phase from PID 1 to switch_root, with inline release/debug branching at each error point.

Reason

The README described implemented features but gave no overview of how they connect at runtime. The diagram makes the startup sequence, degraded-boot split, and recovery policy visible at a glance.

Content

• All 13 phases in execution order (early init → logger → config → core mount → boot env classification → first-boot detection → init_setup → mode dispatch → remaining mounts → overlays → switch_root)
• Release vs debug error branches inline at each fatal failure point
• FsckRequiresReboot always routing to Reboot regardless of image type
• Degraded boot annotated on the APPLY → FBDETECT edge (ods.degraded_boot=true)
• First-boot marker conditions summarized on the node
• Color-coded terminal states (✅ success · 🔁 reboot · 🔴 halt · 🐚 debug shell)
• Terminal-states legend table and prose note on the core_result capture invariant

Verification

Diagram syntax validated; renders correctly on GitHub.

[JanZachmann]

The visual and doc look good. I expected some undefined flows but everything looks consistent. So is there something special I need to review or is this was last specs say?

[JoergZeidler]

The visual and doc look good. I expected some undefined flows but everything looks consistent. So is there something special I need to review or is this was last specs say?

Imho, we haven't yet defined the behavior for how to handle certain situations. The README reflects the current status, and we may now have a basis for discussing changes to that behavior.

[JanZachmann]

Review: does the diagram match the specs and cover all paths?

Scope note: this is a docs-only change (one Mermaid diagram + tables). The code-focused review agents (silent-failure, type-design, test-coverage) don't apply — the relevant review for the stated goal is spec ↔ README ↔ impl traceability. I checked the diagram against src/ (main.rs, lib.rs, mode/normal.rs, init_setup/, filesystem/resize_data.rs, recovery.rs) and all 10 files in docs/superpowers/specs/.

Verdict: the diagram is an accurate, lightly-abstracted picture of the current code. Two things block the "spec and docs match and cover all paths" goal: (1) one region of the flow has no backing spec, and (2) two specs are stale/contradictory relative to what the diagram now shows. Inline comments mark the per-node items.

Coverage matrix (suggested gap-visualization format)

This is the table format you asked about — a traceability matrix is the clearest way to show "all paths covered" at a glance. Rows = flow phases; a row is only green when diagram, spec, and impl all agree.

Phase / node	In diagram	Backing spec	Impl	Status
Early init (MOUNT_ESS, EARLY_ERR)	yes	recovery-policy §2.5/§2.6	main.rs:33-45	✅
Logger init	yes	recovery-policy §2.6(3)	main.rs:50-62	✅
Config/RDEV/LAYOUT/CORE	yes	boot-mode-dispatch, resize-data, preflight	lib.rs:149-170	✅
Boot-env classify/apply (degraded)	yes	degraded-boot-mode, degraded-boot	lib.rs:179-182	✅
First-boot detect + update_pending	yes	first-boot-detection, recovery-policy §2.5	lib.rs:184-192	✅
init_setup / resize preflight	yes (label issue)	preflight, resize-data, fsck-and-resize	init_setup/, resize_data.rs	⚠️ label + missing Fatal edge; specs #2/#4 stale on "resize fatal"
BootMode dispatch	yes (no fail edge)	boot-mode-dispatch, preflight	lib.rs:205	⚠️ minor
mount_remaining_partitions	yes	resize-data, boot-mode-dispatch	normal.rs:51-57	✅
Overlays / fs-links / ODS runtime (OVL,LINKS)	yes	none	normal.rs:59-69	❌ no spec
write_first_boot_marker (resize_ok gate)	yes	first-boot-detection, first-boot-retry	normal.rs:74	✅
switch_root	yes	mentioned only (endpoint)	runtime::switch_root	⚠️ no design doc
Fatal handler (FEB)	yes (Fatal branch only)	recovery-policy	main.rs:74, recovery.rs	✅ simplified

Legend: ✅ diagram = spec = impl · ⚠️ accurate but incomplete/abstracted · ❌ flow drawn, no spec.

Recommend keeping a trimmed version of this matrix in the README (or in a specs index) so the spec↔doc↔impl link is visible and stays maintained — that is what actually enforces "cover all paths" over time.

Spec-hygiene items (not visible in the diff, but block the goal)

• Stale spec: 2026-05-12-first-boot-mode-design.md (BootMode::FirstBoot, mode::first_boot::run) is superseded by 2026-05-13-preflight-design.md. That flow exists in neither the diagram nor the code. Mark it superseded.
• Contradiction: resize-data and preflight specs both state "resize failure is fatal". fsck-and-resize (#9) and first-boot-retry (#10) reclassify resize as ContinueDegraded (never fatal). The diagram (ISETUP non-fsck → BMODE, continue) and the code follow the latter — so the two earlier specs are stale and should be marked superseded, otherwise the spec set contradicts the README.

Not a gap (checked and ruled out)

Early-init error handling is spec-covered — recovery-policy §2.5 (early failure before boot env → not-pending → terminal) and §2.6 invariant 1 ("release never reaches Shell"). The diagram's EARLY_ERR release→halt / debug→emergency-sh split is exactly the fix that spec mandates.

[JanZachmann]

New findings — still-open points

The five earlier threads are verified against the code (and, for the overlay block, against the legacy bash initramfs in meta-omnect) and resolved. These three points were raised in the original review summary but not addressed in the diff — filing them as discrete findings so they're tracked against the PR goal (spec ↔ README match, all paths covered).

Finding B — stale superseded spec (spec hygiene) · open

docs/superpowers/specs/2026-05-12-first-boot-mode-design.md designs BootMode::FirstBoot + mode::first_boot::run. That design is superseded by 2026-05-13-preflight-design.md, and the flow exists in neither the diagram nor the code. The spec should carry a Superseded by 2026-05-13-preflight-design.md header note (or be removed), otherwise the spec set documents a flow that no longer ships.

Finding C — spec contradicts shipped behaviour: "resize failure is fatal" · open

2026-05-04-resize-data-design.md and 2026-05-13-preflight-design.md both state resize failure is fatal. 2026-05-27-fsck-and-resize-design.md and 2026-06-22-first-boot-retry-on-resize-failure.md reclassify resize as ContinueDegraded (never fatal) — which the diagram (ISETUP non-fsck → BMODE) and the code (resize_data.rs::handle_result) follow. The two earlier specs directly contradict the README and the code; mark them superseded or update the claim.

Finding A — diagram: FsckRequiresReboot edges bypass the error handler · open

See the inline comment. Cosmetic + spec-alignment; not blocking.

---

Findings B and C are spec-file changes outside this PR's diff — they may be better tracked as a separate issue/PR if this one stays scoped to the README diagram.

[JoergZeidler]

Findings B and C — addressed in commit 0fd10f1.

Finding B: Added Status: Superseded by 2026-05-13-preflight-design.md header and a prose note to 2026-05-12-first-boot-mode-design.md clarifying that BootMode::FirstBoot / mode::first_boot::run were never shipped and that resize-data was implemented as a preflight step instead. Spec retained for design history.

Finding C: Added Status: Partially superseded header to both 2026-05-04-resize-data-design.md and 2026-05-13-preflight-design.md, referencing 2026-05-27-fsck-and-resize-design.md as the correcting document. Added an inline annotation directly on the contradicting table row in preflight-design.md so the conflict is visible at the point of reading. Specs retained for design history — removal is not preferred.

[JanZachmann]

Requesting changes for one open item.

Finding A — diagram reroute not in the branch. The reply on that thread credits commit 8d771e4, but 8d771e4 was force-pushed away and is not in the history (head 0fd10f16's parent is a703fbf). The diagram at head still routes FsckRequiresReboot straight to REBOOT (L60/L65/L73) while FEB -->|RebootToApply| REBOOT (L88) has no incoming edge. Please re-apply the 4-line reroute documented in the Finding A thread so REBOOT is reached only through FEB (matches the code and recovery-policy §2.6 invariant 2).

Resolved and not blocking:

• Findings 1–5 (diagram edges/labels, OVL/LINKS legacy annotation) — verified, threads resolved.
• Finding B (stale 2026-05-12-first-boot-mode spec) — superseded header added in 0fd10f16.
• Finding C (resize-fatal contradiction) — partially-superseded headers added in 0fd10f16.

Once the diagram edit lands, this is good to merge.

[JanZachmann]

All findings resolved. Finding A is now applied in 455e66aa — the three FsckRequiresReboot edges route through FEB, and REBOOT is reached only via FEB -->|RebootToApply (e.g. FsckRequiresReboot)| REBOOT, matching the code and recovery-policy §2.6 invariant 2.

Summary: diagram findings 1–5 fixed and verified; OVL/LINKS spec gap annotated (backed by the legacy bash initramfs); Finding B (stale 2026-05-12-first-boot-mode spec) and Finding C (resize-fatal contradiction) marked superseded in 0fd10f16. Diagram now matches the implementation; spec set is consistent with the README. Approving.

[JanZachmann]

Follow-up: comment style — history-describing (non-evergreen) prose

One clear instance, one borderline. Flagging post-approval as a style nit — not re-blocking unless you want it fixed first.

1. README OVL/LINKS note (inline below) — narrates the bash→Rust migration ("ported from the legacy bash initramfs", "The Rust port preserves this behaviour and adds…"). The README is a living doc; it should state the current contract, not the porting history. Evergreen rewrite in the inline comment.

2. Spec status headers (0fd10f16) — borderline, I'd leave them. "Superseded by…" / "Partially superseded…" headers and the ← superseded: reclassified… table annotation are history by nature, but these are design-history documents where lifecycle metadata is conventional and stays true. If you want strict evergreen there too, replace the table annotation's narration with a plain corrected value (Resize failure → ContinueDegraded (non-fatal)).

The rest of the added prose ("Notes on error handling", "Notes on apply_boot_env_decision") is fine — current state and rationale, no history.

Minor: the "FsckRequiresReboot edges … flow through this handler — not via a separate mechanism" clause answers a past review point; trim the trailing clause and it reads as plain current-state.

Say the word and I'll convert this to REQUEST_CHANGES.

[JoergZeidler]

Findings D, E, F addressed in commit 42cb4b5:

• D: FEB in prose replaced with 'the error handler'
• E: OVL/LINKS note rewritten as evergreen current-state contract (your suggested text)
• F: 'not via a separate mechanism' clause trimmed from the FsckRequiresReboot note

Spec status headers left as-is — agreed these are conventional in design-history documents.