Sam & Claude
95c487546d
New docs/guide/ tree — canonical home for operator-facing procedural docs. Starlight frontmatter added to all files. 0.12 alignment fixes applied: - v0.11.0 → v0.12.0 throughout - PI_TUI_PROVIDER/MODEL → DEEPSEEK_API_KEY - Headless Codex login → Agent runtime setup (zot + RPC mode) - /login and auth.json references removed - pi → zot in provider-fallback spawn reference - colibri-provider-verify (was pi-provider-smoke) - Language cleanup: smoke test → verification, fake → test, can't self-fix → requires operator intervention, broken → unresponsive, Fix anything broken → Verify all checks pass Two-tree model: docs/wiki/ (decisions) + docs/guide/ (procedural). Single source of truth in colibri. clawdie-ai docs/public/ to be retired.
5.1 KiB
5.1 KiB
Naming decisions ledger
← index
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.
Naming principle — harness-agnostic by default
Name a thing by what it is, not by the harness that happens to be the current default:
- Neutral concept (any harness has one — a session id, an event type,
autospawn, "the agent") → a neutral name. The harness is a configurable
value (e.g.
COLIBRI_AUTOSPAWN_BINARY=zot), never baked into the name and always operator-overridable. - Harness-specific thing (one harness's actual wire format) → the harness
name belongs in it, and the parallels stay symmetric (
zot_event_type↔pi_event_type,AgentRuntime::{Zot, Pi}) so neither is privileged.
The pi_* rows in Shipped are the cautionary tale: neutral concepts
wrongly named after a harness. Same applies to docs — a per-harness reference is
neutral (AGENT-EVENTS-REFERENCE), not ZOT-…, unless it is truly about one
harness only.
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) |
sample-pi-agent.py |
Renamed from legacy test-agent filename; 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 |
pi_type → event_type |
internal name for the normalized event type; harness-neutral (not serialized) | crates/colibri-glasspane/src/lib.rs |
In-flight
None currently.
Known residue (not yet actioned)
| Item | Note |
|---|---|
ADR-agent-harness-consolidation.md |
Referenced but does not exist; AGENTS.md is the real anchor. See agent-harness. |
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 |
FEATURE_COLIBRI is internal, not user-facing |
colibri is staged by default; FEATURE_COLIBRI=NO is a build-time escape hatch (e.g. no colibri checkout). README clarified. |
clawdie-iso #130 |
clawdie-gui is the stable operator command |
clawdie-startx retained as a back-compat alias (both installed); docs teach clawdie-gui. Verified intentional, not drift. |
clawdie-iso/README.md §clawdie-gui; clawdie-iso/build.sh |
See also
- agent-harness
- quality-gates — the gate that should catch these at PR time