# Council Briefing: 2025-03-22

## Monthly Goal

December 2025: Execution excellence—complete token migration with high success rate, launch ElizaOS Cloud, stabilize flagship agents, and build developer trust through reliability and clear documentation.

## Daily Focus

- Stability-and-DX consolidation day: we shipped tangible onboarding improvements (env drag-and-drop, docs fixes) while surfacing build/voice-key regressions that must be sealed to preserve trust during the V2 transition.

## Key Points for Deliberation

### 1. Topic: Developer Onboarding & “First-Run Success”

**Summary of Topic:** UX and documentation patches (env drag-and-drop upload; quickstart add-plugin correction) directly advance Execution Excellence by reducing friction at install/run time, but they must be paired with ruthless regression control to keep “first-run” success rates high.

#### Deliberation Items (Questions):

**Question 1:** Do we define a hard “first-run success” gate (install → create agent → run basic chat) as the primary release criterion for the beta line?

  **Context:**
  - `GitHub PR #4033: “Added drag & drop option for env uploading” (user interaction improvement).`
  - `GitHub PR #4047: “Updated documentation… correct the add plugin command in quickstart.md.”`

  **Multiple Choice Answers:**
    a) Yes—make first-run success the top gate; defer non-essential features until it’s consistently green.
        *Implication:* Maximizes developer trust and reduces support load, but may slow perceived feature velocity.
    b) Partially—gate only on CLI/agent basics; allow UI enhancements to iterate post-release.
        *Implication:* Balances shipping cadence with reliability, but risks UI-first users hitting sharp edges.
    c) No—prioritize feature completeness for V2; onboarding polish can follow once ecosystem parity is reached.
        *Implication:* Short-term momentum increases, but undermines Core Principle #4 (Trust Through Shipping) if new users churn.
    d) Other / More discussion needed / None of the above.

**Question 2:** Which onboarding surface should be the canonical path for new builders during beta: CLI-first, GUI-first, or Cloud-first?

  **Context:**
  - `Discord (2025-03-20/21): beta install steps repeatedly shared: “npm create eliza@beta … npx @elizaos/cli start”.`
  - `GitHub PRs (Mar 20-22 batch): significant UI/UX enhancements and agent management fixes indicate parallel entry points.`

  **Multiple Choice Answers:**
    a) CLI-first: treat GUI as optional accelerator, not the main runway.
        *Implication:* Keeps the core open-source developer workflow stable, but may reduce appeal to non-TS builders.
    b) GUI-first: declare the builder UI the default and ensure it wraps safe CLI behaviors.
        *Implication:* Improves accessibility and demos, but increases QA surface and risk of UI-driven regressions.
    c) Cloud-first: optimize the path where ElizaOS Cloud is the default provider and onboarding route.
        *Implication:* Accelerates deployment success and monetization, but can create “closed-path” perception if self-hosting lags.
    d) Other / More discussion needed / None of the above.

**Question 3:** How aggressively should we standardize environment/secret configuration UX across plugins (voice, Twitter, LLM providers) to reduce “missing key” failures?

  **Context:**
  - `Issue #4049: “AI_LoadAPIKeyError: Anthropic API key is missing… affecting voice channel operations.”`
  - `PR #4033: env upload UX improvement suggests a push toward centralized configuration ergonomics.`

  **Multiple Choice Answers:**
    a) Centralize: one unified secrets wizard with plugin-aware validation and inline warnings.
        *Implication:* Strong DX win; requires cross-plugin coordination and a clear contract for config schemas.
    b) Hybrid: keep plugin configs decentralized but add a shared validator + preflight checklist in CLI/GUI.
        *Implication:* Faster to implement while still reducing failures, though edge cases may persist across plugins.
    c) Decentralized: keep current approach; document better and rely on community troubleshooting.
        *Implication:* Lowest engineering cost now, but increases support burden and harms perceived reliability.
    d) Other / More discussion needed / None of the above.

---


### 2. Topic: Voice/Realtime Systems Reliability (Discord Voice + Dependencies)

**Summary of Topic:** Discord voice functionality was repaired via targeted fixes (including Opus dependency handling), but the appearance of API-key-related runtime failures highlights an operational risk: multimodal features amplify dependency brittleness and must be stabilized with stronger preflight and fallback behavior.

#### Deliberation Items (Questions):

**Question 1:** Should voice/multimodal features be considered “tier-2” until we can guarantee dependency + key sanity checks across environments?

  **Context:**
  - `PR #4036: “fix: discord voice” (tcm390) restored broken voice behavior.`
  - `PR #4035: “fix: opus issue” (tcm390) indicates native dependency fragility.`

  **Multiple Choice Answers:**
    a) Yes—ship voice as tier-2 behind explicit flags and a stability disclaimer during beta.
        *Implication:* Protects core reliability metrics while still enabling power users to experiment.
    b) No—voice is strategic differentiation; treat it as tier-1 and invest immediately in hardening.
        *Implication:* Accelerates flagship-agent capability, but risks destabilizing the mainline release experience.
    c) Split: tier-1 for Cloud-managed environments, tier-2 for self-hosted until dependency tooling matures.
        *Implication:* Improves reliability where we control infra, but introduces perceived two-class citizenship.
    d) Other / More discussion needed / None of the above.

**Question 2:** What is our Council doctrine for native dependencies (e.g., Opus): containerize, prebuild binaries, or degrade gracefully?

  **Context:**
  - `PR #4035: Opus dependency fix suggests recurring native-module breakage in user environments.`
  - `Discord discussions (Mar 19-21): recurring Node/version mismatch fixes (e.g., “nvm 23.3.0”).`

  **Multiple Choice Answers:**
    a) Containerize-first: make Docker the recommended path for voice-enabled agents.
        *Implication:* Reduces environment variance, but may slow adoption for local-first developers.
    b) Prebuilt binaries: provide platform packages and CI-tested native builds where possible.
        *Implication:* Improves local UX, but increases maintenance complexity across OS/arch permutations.
    c) Graceful degradation: keep voice optional; if native deps fail, auto-disable and continue with text mode.
        *Implication:* Preserves reliability and reduces rage-quits, but voice becomes less dependable as a flagship feature.
    d) Other / More discussion needed / None of the above.

**Question 3:** How should we handle missing provider keys at runtime: hard fail, soft fail with clear UX, or automated provider fallback?

  **Context:**
  - `Issue #4049: missing Anthropic key impacts voice channel operations.`
  - `Core Principle #1: “Reliability and seamless UX over feature quantity.”`

  **Multiple Choice Answers:**
    a) Hard fail early with explicit preflight errors and no partial startup.
        *Implication:* Predictable behavior for operators, but can block unrelated functionality and frustrate newcomers.
    b) Soft fail: start system, disable affected features, and surface actionable UI/CLI guidance.
        *Implication:* Best user experience and aligns with execution excellence, but requires careful state/telemetry handling.
    c) Automated fallback: route to alternative providers when keys are missing (where legally/technically possible).
        *Implication:* Maximizes continuity, but may create surprising costs, policy issues, or inconsistent outputs.
    d) Other / More discussion needed / None of the above.

---


### 3. Topic: Build/Release Hygiene (Exports, Hooks, and Regression Containment)

**Summary of Topic:** New issues (missing core export `generateText`, Husky pre-commit failures) signal that the project’s velocity is outpacing release hygiene; stabilizing the build/test pipeline is now a strategic prerequisite for trustworthy beta shipping.

#### Deliberation Items (Questions):

**Question 1:** Do we impose a “no broken exports” policy with automated API surface checks for @elizaos/core across all packages/plugins?

  **Context:**
  - `Issue #4046 (ljiang22): “SyntaxError: … '@elizaos/core' does not provide an export named 'generateText'”.`

  **Multiple Choice Answers:**
    a) Yes—add API surface snapshot tests and block merges that change exports without a migration note.
        *Implication:* Reduces ecosystem breakage and reinforces developer trust, at the cost of stricter review gates.
    b) Somewhat—only enforce on stable releases; allow beta branches to evolve rapidly.
        *Implication:* Preserves beta agility but prolongs pain for builders who track beta for early integration.
    c) No—document breaking changes in changelogs; rely on semver and community adaptation.
        *Implication:* Lower process overhead, but repeated breakage erodes the “developer-friendly” promise.
    d) Other / More discussion needed / None of the above.

**Question 2:** How should we treat tooling failures like Husky pre-commit errors: mandatory and fixed immediately, or optional for contributors?

  **Context:**
  - `Issue #4048 (Deadsg): “Husky pre commit error… execution format error… preventing successful commits.”`

  **Multiple Choice Answers:**
    a) Mandatory: keep Husky enforced; prioritize fixing cross-platform hook compatibility.
        *Implication:* Improves code quality and consistency, but risks contributor drop-off if friction remains.
    b) Optional: disable Husky by default; provide a “strict mode” for core maintainers/CI.
        *Implication:* Increases contributor throughput, but pushes quality control later into CI and review.
    c) Replace: move checks entirely to CI (pre-merge), eliminating local hook dependency.
        *Implication:* Simplifies local dev and standardizes enforcement, but feedback loop becomes slower.
    d) Other / More discussion needed / None of the above.

**Question 3:** What is our Council stance on release cadence during beta: frequent patch releases or slower, higher-confidence drops?

  **Context:**
  - `GitHub daily log (Mar 21-23): “10 new PRs… 5 merged… 7 new issues” indicates high churn and constant integration pressure.`
  - `Discord (Mar 19-21): beta described as “somewhat unstable” with active bugfixing.`

  **Multiple Choice Answers:**
    a) Frequent patches: ship daily/near-daily fixes to reduce pain quickly.
        *Implication:* Keeps momentum and resolves blockers fast, but increases upgrade fatigue and regression risk.
    b) Scheduled drops: bundle fixes into predictable weekly releases with explicit QA cycles.
        *Implication:* Improves reliability perception and coordination, but slows delivery of urgent fixes.
    c) Hybrid: rapid hotfix channel + stable beta channel, with clear guidance on who should use which.
        *Implication:* Balances stability and speed, but requires release management discipline and communication clarity.
    d) Other / More discussion needed / None of the above.