# Naming decisions ledger

← [index](./index.md)

A living record of renames driven by superseded assumptions, so future drift is
checkable against one list. "Shipped" means merged to `main`; verify against the
linked code before trusting a row.

## Shipped

| Old → New                                        | Why                                                                               | Anchor                                         |
| ------------------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------- |
| `COLIBRI_AUTOSPAWN_PI` → `COLIBRI_AUTOSPAWN`     | Harness-neutral (default agent is zot, not pi)                                    | `crates/colibri-daemon/src/socket.rs`          |
| `COLIBRI_PI_BINARY` → `COLIBRI_AUTOSPAWN_BINARY` | same                                                                              | `socket.rs` (`autospawn_agent_if_configured`)  |
| `pi_session_id` → `session_id`                   | zot agents have session ids too; `#[serde(alias)]` keeps back-compat              | `crates/colibri-glasspane/src/lib.rs` (`Pane`) |
| `fake-pi-agent.py` → `sample-pi-agent.py`        | "fake" too loaded; it emits a canned _sample_                                     | `scripts/sample-pi-agent.py`                   |
| non-local spawn default `hermes-agent` → `zot`   | `hermes-agent` was a nonexistent leftover binary                                  | `socket.rs` (`default_agent_args`)             |
| `usb_nodes` → `hive_nodes`                       | a node is any host that joined the hive, not only a USB boot (`+node_type`); #161 | `packaging/mother/mother_schema.sql`           |

## In-flight

_None currently._

## Known residue (not yet actioned)

| Item                                 | Note                                                                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pi_type`                            | pi-era name for "normalized event type"; **internal only**, not serialized. Optional rename → `event_type`. `crates/colibri-glasspane/src/lib.rs`            |
| `FEATURE_COLIBRI`                    | `AGENTS.md`/README imply "no separate feature flag," but the build keeps it (default YES, "internal escape hatch"). Reconcile wording or flag. (clawdie-iso) |
| `clawdie-startx`                     | README teaches `clawdie-gui`; `startx` kept as the internal wrapper — documented transition, verify the user-facing launcher leads with `gui`. (clawdie-iso) |
| `ADR-agent-harness-consolidation.md` | Referenced but does not exist; `AGENTS.md` is the real anchor. See [agent-harness](./agent-harness.md).                                                      |

## Structural decisions

| Decision                               | Why / lesson                                                                                                                                                                                                                        | Anchor                                                  |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Single home for mother infra = colibri | The mother MCP scripts were copied into both colibri and clawdie-iso; the iso copy drifted to an **SQL-injectable** `node-register-mcp` on `main`. Same script in two repos drifts — a lint pass should flag cross-repo duplicates. | colibri `packaging/mother/`; iso removal in iso PR #129 |

## See also

- [agent-harness](./agent-harness.md)
- [quality-gates](./quality-gates.md) — the gate that should catch these at PR time