Skip to content

"Director" is our word, not the user's — and it names the Completer's settings #466

Closed

Description

@omesser

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:

  1. 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.js already gets this right without the
    word, in empty-none / empty-off: "Nothing can answer yet." That is the
    register to match.
  2. Do the Completer settings stop saying Director? The section, the labels,
    and — the expensive one — the env vars.
  3. 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

Activity

  1. added this to the V1 milestone on Sep 7, 2026
  2. moved this from Todo to In Progress in Fidgeton Sep 8, 2026
  3. omesser commented on Sep 8, 2026

    @omesser
    OwnerAuthor

    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:

    • Env vars: 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.
    • Code identifiers for that config: settings fields, FormRow ids, BoolField variants, menu actions, inspect structs, etc. — rename to Completer (or the same user-facing “AI” vocabulary where it is the switch), not leave director_enabled / DirectorEnabled as fossils.
    • User-facing copy already moving to AI / Completer on refactor(settings): Fix user-facing labels, keep Director as domain role #561 stays.

    What stays “Director”

    The domain role in CONTEXT.md / crates/core that 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)

    • No AI_BUDDY_DIRECTOR_* left in repo (code, docs, scripts, examples)
    • Settings / menu / chat user-facing Completer config does not say Director
    • Settings/code identifiers for Completer config are Completer-named (no leftover director_* for those fields)
    • CONTEXT.md records the decision and _Avoid_: (no cheap-middle dual spelling)
    • README / DEVELOPMENT match
    • One PR (expand refactor(settings): Fix user-facing labels, keep Director as domain role #561); How-to-test covers rename + no silent fallback to old env names

    Tracked on #561

    — Cursor agent (Coder), on @omesser's behalf.

  4. moved this from 🏗 In Progress to 🙋 Human Triage in Fidgeton Sep 9, 2026
  5. added
    p1Next up: the default for work that should happen
    on Sep 9, 2026
  6. added 3 commits that reference this issue on Sep 9, 2026
    d75b00e
    c17f217
    40988c5
  7. linked a pull request that will close this issuedocs: Say the Chat surface ships #578on Sep 9, 2026
  8. moved this from 🙋 Human Triage to 🏗 In Progress in Fidgeton Sep 9, 2026
  9. moved this from 🏗 In Progress to 🏁 Done in Fidgeton Sep 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageMaintainer needs to evaluate this issuep1Next up: the default for work that should happen

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions