Repository navigation
Description
Decision (Oded, 2026-09-09) — supersedes the cheaper middle
Consistency first, KISS. Do not keep AI_BUDDY_DIRECTOR_* as a legacy Completer spelling.
Rename Completer configuration completely: env vars → AI_BUDDY_COMPLETER_*, settings/code identifiers that meant Completer-under-the-name-Director, user-facing AI/Completer copy. No dual-accept of old env names.
The domain Director role (Behavior proposer; Static or Completer-backed) in CONTEXT.md / core stays; that is not Completer settings naming.
See PR #561 and the decision comment on this issue.
Problem
A user opens Settings, finds a section called Director, a switch called
Director on, and three fields under it. Nothing on that screen says what a
Director is. The README's answer — "The Director chooses idle Behaviors and
short spoken lines" — is a sentence about our architecture, not about anything
the user wanted to do.
They came to connect an AI. They are being asked about a role in our domain
model.
The second, worse half
The terminology is not just unfamiliar. It is applied to the wrong thing.
CONTEXT.md is clear that these are two concepts:
Director: The role that proposes a Behavior, and Speech when the session
is on. Static weights fill Behaviors and never speak; an attached Harness is
that role.
So a Director is a role, and Static weights are one. The Completer is the
thing that answers. But every user-facing string names the role where it means
the Completer:
| Surface | Says | Configures |
|---|---|---|
AI_BUDDY_DIRECTOR_BASE_URL |
Director | the Completer's endpoint |
AI_BUDDY_DIRECTOR_MODEL |
Director | the Completer's model |
AI_BUDDY_DIRECTOR_API_KEY |
Director | the Completer's credential |
Settings section Director |
Director | mostly Completer fields |
| README | "Point Settings → Director at OpenAI, Anthropic, Ollama" | an endpoint |
A base URL is not a property of a role. Static weights are a Director and have
no base URL at all.
The confusion has already reached our own issue titles: #436 is
"Director Completer source", which needs both nouns to say one thing.
What to decide
Not "rename Director". The domain term is good and CONTEXT.md earns it. The
questions are narrower:
- Which word does the user meet? Something plain for the thing that
answers — the AI, the model, the Completer — and whether "Director" should
appear in the UI at all.src/chat.jsalready gets this right without the
word, inempty-none/empty-off: "Nothing can answer yet." That is the
register to match. - Do the Completer settings stop saying Director? The section, the labels,
and — the expensive one — the env vars. - What does the switch mean? "Director on" reads as a component toggle.
The user is choosing whether the buddy improvises or runs on static weights.
Say that.
The cost, stated up front
Renaming AI_BUDDY_DIRECTOR_* breaks every script, .env and README a user
has. If it happens it needs both names accepted, the old one warned about, and
a documented window — that is most of the work in this issue and the reason it
might not be worth doing.
A cheaper middle: leave the env vars alone REJECTED 2026-09-09 — was: leave the env vars alone as the compatibility surface, fix
only what a user reads — Settings labels, help text and README — and record
in CONTEXT.md that the env prefix is a legacy spelling of Completer. That
buys the clarity without the migration.
Not to be lost
CONTEXT.md keeps an _Avoid_: line per term for exactly this. Whatever is
decided belongs there, so the next writer does not re-derive it, and so the
distinction between the role and the thing that answers stays legible in the
code even if the UI stops using it.
Acceptance
- A decision on which term the user meets, recorded in
CONTEXT.md - Settings no longer labels Completer configuration with a role name
- The on/off switch says what turning it off actually does
- README matches, and stops pointing "Director" at an endpoint
- If env vars change: both spellings work, the old one warns, and the
window is documented -
_Avoid_:records the rejected synonyms so this is settled once
Related
#436 (whose title needs both nouns), #465 (endpoint picker — same screen),
#447, ADR-0004 (Director outside the frame loop, where the role is defined).
🤖 Generated with Claude Code
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
docs: Naming/terminology review against CONTEXT.md glossary
fix(chat): Actually invoke Harness login on connect button click
docs(settings): Rename Director to AI/Completer in user-facing copy
fix(chat): Actually invoke Harness login on connect button click
omesser commentedon Sep 8, 2026
Decision (Oded, 2026-09-09)
Consistency first, KISS. Reject the “cheaper middle” (UI/README only, keep
AI_BUDDY_DIRECTOR_*).Rename everything that was Completer configuration wearing the Director name:
AI_BUDDY_DIRECTOR_*→AI_BUDDY_COMPLETER_*(and any sibling switches that meant Completer on/off). No dual-accept / no legacy alias. Old names go; scripts and docs update in the same change.director_enabled/DirectorEnabledas fossils.What stays “Director”
The domain role in
CONTEXT.md/crates/corethat proposes Behaviors (Static weights or an attached Completer playing that role) remains Director — that is not Completer-config naming; Completer is what answers. Do not rename the role into Completer and erase the glossary split.Acceptance (updated)
AI_BUDDY_DIRECTOR_*left in repo (code, docs, scripts, examples)director_*for those fields)_Avoid_:(no cheap-middle dual spelling)Tracked on #561
— Cursor agent (Coder), on @omesser's behalf.
Rename AI_BUDDY_DIRECTOR_* to AI_BUDDY_COMPLETER_* and all Completer …
docs(settings): Rename Director to AI/Completer in user-facing copy
Rename AI_BUDDY_DIRECTOR_* to AI_BUDDY_COMPLETER_* and all Completer …
fix(chat): Actually invoke Harness login on connect button click
Fix leftover director_base_url field references in test
docs(settings): Rename Director to AI/Completer in user-facing copy
Rename AI_BUDDY_DIRECTOR_* to AI_BUDDY_COMPLETER_* and all Completer …
Fix leftover director_base_url field references in test
refactor(settings): Revert Completer rename, keep Director as domain …
refactor(settings): Fix user-facing labels, keep Director as domain role
refactor(settings): Revert Completer* identifier renames per option A
refactor(settings): Fix user-facing labels, keep Director as domain role
refactor(settings): Revert Completer* identifier renames per option A