Document read-only submodules policy

bible-local/decisions/2026-04-29-read-only-embedded-submodules.md

@@ -0,0 +1,39 @@
+# Decision: Treat embedded submodules as read-only
+
+## Context
+
+`bee` embeds external git submodules such as:
+
+- `internal/chart/` — `reanimator/chart`, a generic read-only viewer for Reanimator JSON snapshots
+- `bible/` — shared engineering rules and contracts
+
+These repositories are reused by other projects. A local feature request in `bee`
+must not be solved by silently changing shared submodule behavior.
+
+The concrete failure mode here was attempting to add project-specific storage
+telemetry presentation by editing `internal/chart/`. That couples a shared viewer
+to one host application's needs and creates hidden cross-project regressions.
+
+## Decision
+
+Embedded submodules are read-only from the point of view of `bee`.
+
+- Do not implement `bee`-specific behavior by editing `internal/chart/`.
+- Do not implement `bee`-specific behavior by editing `bible/`.
+- If `bee` needs new data in the report, produce it in the standard audit JSON
+  emitted by `bee` itself.
+- `chart` must continue to consume the canonical snapshot as an external viewer,
+  without host-specific forks.
+- Updating a submodule pointer to an upstream commit is allowed.
+- Carrying local unmerged submodule commits as part of a `bee` feature is forbidden.
+
+## Consequences
+
+- Audit/report features must be expressed through the contract in
+  `bible-local/docs/hardware-ingest-contract.md`.
+- `bee` owns collection, normalization, and serialization of storage telemetry in
+  `hardware.storage[]`.
+- `chart` remains a pure visualization module that reads the snapshot it is given.
+- If a capability is genuinely missing in a shared submodule, it must be proposed
+  and landed upstream as a generic change first, then pulled into `bee` via a
+  normal submodule update.

bible-local/decisions/README.md

@@ -6,3 +6,4 @@ One file per decision, named `YYYY-MM-DD-short-topic.md`.
 |---|---|---|
 | 2026-03-05 | Use NVIDIA proprietary driver | active |
 | 2026-04-01 | Treat memtest as explicit ISO content | active |
+| 2026-04-29 | Treat embedded submodules as read-only | active |