# 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.