## User Feedback Analysis — 2025-12-19 (elizaOS)

### Data sources reviewed
- Discord summaries: 2025-12-16, 2025-12-17, 2025-12-18 (channels: 💬-discussion, 💬-coders, core-devs, 🥇-partners)
- GitHub: Daily activity 2025-12-18 (PRs #6212, #6261, #6262, #6263; issue #6264 “Docs”), plus recurring monthly migration issue context (e.g., #6211)

---

## 1) Pain Point Categorization (Top recurring friction areas)

### 1) **Documentation** — Missing or outdated “how-to” paths (highest frequency, high severity)
**What users hit**
- **Plugin dev + actions extension steps are unclear**: confusion about where plugin folders live, how to add actions, and the need to register actions in `src/index` (“clone into packages folder”, “put it in src/index”).
- **Migration instructions are hard to find / inconsistent**: users asking “I stucked in AI16Z. How should I migrate?”; needing channel references to find instructions.
- **Provider best practices are tribal knowledge**: debate revealed implicit rules (e.g., “providers should never make API calls; use cache”) that aren’t codified.
- **Release notes imply breaking changes but lack “upgrade checklist”** (Hyperfy v0.16.0: app remains active while moved; needs explicit migration steps).

**Evidence/examples**
- Discord: multiple unanswered FAQs related to migration and cloud timelines (see “Communication gaps” for %).
- GitHub: Issue #6264 titled “Docs” opened with no detail/comments, suggesting “docs dissatisfaction” but unclear scope.

---

### 2) **Technical Functionality** — Token migration + exchange handling (high frequency, high severity, community-wide impact)
**What users hit**
- **Exchange-dependent migration outcomes are confusing** (Bithumb vs Kraken snapshot handling, eligibility questions).
- **Wallet compatibility gaps** (GitHub issue #6211: Tangem wallet not supported via WalletConnect; fear of impersonators; request for “official safe method”).
- **Perceived “disastrous” migration experience** and “dilution” narrative in Discord discussion.

**Evidence/examples**
- Discord: repeated migration confusion across 12/16–12/18, plus strong negative sentiment tied to the swap.
- GitHub: #6211 explicitly requests official guidance due to compromised/unsafe support channels.

---

### 3) **Integration** — Plugin install and versioning friction (medium frequency, medium-high severity)
**What users hit**
- **Uncertainty about correct CLI usage for plugins** (`elizaos plugins add ...` vs manual clone).
- **TypeScript compatibility breaks when integrating plugins** (e.g., `AgentRuntime` vs `IAgentRuntime` mismatches in action files).
- **Dependency/version pinning policy is easy to violate**: confirmed guidance is to pin `@elizaos/*` versions, not use `latest`, but this is easy to miss.

**Evidence/examples**
- 💬-coders: Starknet plugin integration blocked by TS type issues and missing handler error.
- core-devs: explicit confirmation to pin versions.

---

### 4) **Performance** — Provider latency and pipeline behavior (medium frequency, potentially high severity)
**What users hit**
- Providers can be slow and block the pipeline; unclear expectations for provider implementation (cache-only vs allowing I/O).
- Need for guardrails: configurable timeouts, warnings, and better defaults.

**Evidence/examples**
- core-devs: PR #6263 proposes parallel provider execution + timeout (default 1s) + abort behavior; debate indicates real performance pain and unclear contracts.

---

### 5) **UX/UI** — Streaming output inconsistencies (medium frequency, medium severity)
**What users hit**
- Streaming works “in monorepo” and for “simple messages and actions,” but **Actions UI still renders text all at once** (breaks perceived responsiveness).
- This creates a mismatch between “streaming supported” messaging and actual UX.

**Evidence/examples**
- Discord 12/16: streaming feature works but Actions UI not streaming.
- GitHub 12/18: PR #6212 merged (“enhance streaming support in text generation”), implying active work but user-facing gaps remain.

---

### 6) **Community** — Trust, sentiment, and regional inclusion (lower “technical” frequency, very high severity)
**What users hit**
- Significant frustration about token price + “lack of delivered products.”
- **Korean community feels marginalized**; requests for evidence of exchange communication (Bithumb snapshot timing).
- Support trust issues: reports of impersonators/unsafe support pathways (also echoed in GitHub #6211).

**Evidence/examples**
- 💬-discussion: hostility required moderator intervention; repeated questions about project viability and timelines.

---

### 7) **Technical Functionality / DevEx** — Local DB and migration setup pain (lower frequency in this slice, high severity for builders)
**What users hit**
- Persistent PostgreSQL migration/config/permissions issues when setting up locally.
- Users need 1:1 troubleshooting (moved to DMs), which doesn’t scale.

**Evidence/examples**
- 12/16: DB migration problems; ongoing troubleshooting.

---

## 2) Usage Pattern Analysis (actual vs intended)

### How users are actually using elizaOS
- **Building vertical agents with external data + deployment**: example: Polymarket tracking agent → Neon DB → deployed to GitHub + Fly.io (real “agent-as-a-service” usage).
- **Treating plugins as primary extensibility surface**: Starknet plugin integration; Discord plugin PR with 66 commits pending; heavy focus on “actions” authoring.
- **Using elizaOS as a “multi-provider orchestration layer”**: provider performance debates show users rely on provider pipelines as core architecture.

### Emerging/unexpected use cases
- **Web3 operational tooling + safety workflows**: “deploy unruggable meme token” action, SEAL 911 hotline discussion, OTC desk mention.
- **AI-assisted development (“vibe coding”) as a first-class workflow**: Cursor usage recommended for mass-updating action files; community discussing multi-instance AI coding setups.

### Feature requests aligning with actual usage
- **More robust streaming UX** (especially Actions UI) aligns with real-time agent ops.
- **Web search** issue backlog (weekly report mentions #6246) aligns with “data acquisition” agents (e.g., Polymarket tracking).
- **Payments/monetization guide** (#6244) aligns with deployed agents and “publish/monetize” flows referenced in cloud integration PRs.

---

## 3) Implementation Opportunities (solutions per major pain point)

### A) Docs gaps (plugins/actions/providers/migrations)
**High impact / low–medium effort**
1) **Create “Golden Path” docs with copy-pastable steps**:
   - “Install plugin (CLI vs monorepo clone), add action, register in `src/index`, run minimal test.”
   - Include a “common errors” appendix: `AgentRuntime` vs `IAgentRuntime`, handler registration failures.
2) **Add versioned docs that match the current monorepo API**:
   - A “You’re on vX.Y.Z” banner and “breaking changes since vX.Y-1” section.
3) **Provider contract doc + lint rule**:
   - Define “no network I/O inside providers” (if that’s the intended contract), or define allowed patterns.
   - Add an ESLint rule or runtime warning when provider performs fetch (where detectable).

**Comparable approaches**
- Kubernetes / Terraform style “Tutorial → How-to → Reference” split reduces repeated Qs.
- Next.js and Docusaurus use versioned documentation to reduce “stale doc” failures after refactors.

---

### B) Token migration + exchange handling + wallet support
**High impact / medium effort**
1) **Single authoritative “Migration Status” page**:
   - Per exchange (Bithumb, Kraken, etc.): snapshot rules, eligibility caveats, timelines, known issues.
   - Include “what we have/ haven’t confirmed with Exchange X” to address evidence requests.
2) **Wallet compatibility matrix + safe fallback path**:
   - Explicitly document WalletConnect limitations (e.g., Tangem) and what the *official* resolution path is (manual claim, signed message workflow, or “not supported yet”).
3) **Anti-impersonation support workflow**:
   - A signed GitHub discussion/announcement for critical operations (migration links, support process).
   - In Discord: locked “official-links” channel + bot that replies to “migration” with canonical URLs.

**Comparable approaches**
- Many token migrations (e.g., L2 bridges, airdrops) maintain a “status page” + signed announcements to reduce phishing.
- Projects like Uniswap publish canonical link hubs and verify all claim URLs.

---

### C) Plugin install + TypeScript compatibility friction
**High impact / medium effort**
1) **Stabilize plugin developer surface with a compatibility layer**:
   - Export a single runtime interface and deprecate duplicates (avoid `AgentRuntime` vs `IAgentRuntime` divergence).
2) **`elizaos plugins add` should validate compatibility**:
   - On install: check peer deps, pin versions, run typecheck, and print actionable diffs.
3) **Provide a plugin starter that compiles “out of the box”** for the current version:
   - Include actions registration example, handler scaffolding, and CI workflow.

**Comparable approaches**
- VS Code extensions and Remix starters emphasize “compiling starter templates” + CI checks to prevent drift.

---

### D) Provider performance and timeouts
**High impact / low–medium effort**
1) **Adopt PR #6263 (or merge with #6209 if duplicate) with safe defaults**:
   - Parallel execution + configurable timeout + structured warning logs.
2) **Add provider instrumentation in dev mode**:
   - Per-provider timing breakdown, cache hit/miss counters, and “slowest provider” summary.
3) **Introduce provider tiers**:
   - “Fast providers” (must return <N ms) vs “async enrichers” (allowed to be slow but non-blocking), to resolve the philosophical debate in code.

**Comparable approaches**
- LangChain and similar orchestrators increasingly separate “retrievers” (fast) from “tools” (slow) and expose tracing/timing.

---

### E) Streaming UX inconsistencies (Actions UI)
**High impact / medium effort**
1) **End-to-end streaming contract test**:
   - Ensure client renders incremental tokens for both messages *and* actions.
2) **UI fallback states**:
   - If streaming not available for an action, show “Generating…” + progressive chunk updates to avoid “all-at-once” perception.
3) **Expose streaming capability flags**:
   - Model/provider capabilities surfaced in UI so expectations match reality.

**Comparable approaches**
- Chat UIs (OpenAI-style) use consistent incremental rendering and explicit “thinking” states when tool calls happen.

---

### F) Local DB setup friction
**Medium impact / medium effort**
1) **One “known-good” docker-compose for Postgres + elizaOS** with exact env vars and migration steps.
2) **Preflight CLI check**:
   - `elizaos doctor` verifies DB connectivity, permissions, migration state, and prints fixes.
3) **Move common setup fixes from DMs to public runbooks**.

**Comparable approaches**
- Supabase and Prisma both provide “doctor” diagnostics and canonical compose files for onboarding.

---

## 4) Communication Gaps (expectations vs reality)

### Repeated expectation mismatches
- **“Is cloud launching before end of year?”** asked and left unanswered in discussion → unclear roadmap communication.
- **“Streaming works” vs “Actions UI streams”**: users hear feature is “working,” but UI contradicts it.
- **Migration availability vs exchange behavior**: users assume migration is uniform, but reality depends heavily on exchange custody/snapshot rules.

### Quantified signal: unanswered questions
Across captured Discord FAQ blocks (n=21 distinct questions across 12/16–12/18 summaries), **9 were unanswered in-channel (~43%)**. Most unanswered questions cluster around:
- Cloud launch timing
- Migration steps and exchange-specific rules
- Security measures / audit-log provenance
- Dev workflow resources (prompts/call artifacts)

### Specific improvements
- Add a **“Roadmap & Status (weekly)” pinned post**: cloud, Babylon, OTC desk, migration milestones, and what’s blocked.
- Create a **“Migration FAQ” bot command** in Discord that only links to canonical resources.
- Publish **“Known limitations”** for streaming and plugins (what’s done, what’s partial, what’s experimental).

---

## 5) Community Engagement Insights

### Power users and their needs
- **Stan**: pushing core performance + streaming improvements; needs clear provider contracts and a merge path for PR #6263.
- **Odilitime**: strong opinions on provider design + plugin development guidance; needs documentation codifying best practices to reduce repeated debates.
- **FenrirFawks**: representative plugin integrator hitting real TS/action registration issues; needs a stable plugin dev surface + troubleshooting guide.
- **Thirtieth**: deploying real agents (Polymarket → Neon → Fly.io); needs production hardening guides (deploy, observability, DB patterns).

### Newcomer friction signals
- “Where is the plugin folder?” / “Which CLI command?” / “Is type conversion issues normal?” indicates onboarding gaps in plugin dev.
- “Is project still alive?” / “Is Eliza finished?” indicates trust gap and weak “front door” messaging.

### Converting passive users into contributors
- Create **“Good First Fix: Docs”** issues with concrete scope (unlike #6264 which is too vague).
- Host a **monthly “plugin clinic”** with a maintained transcript + code samples (reduce repeated Qs).
- Add recognition for non-code contributions (migration FAQ improvements, translations—especially for Korean community).

---

## 6) Feedback Collection Improvements

### Current channel effectiveness
- Discord is high-volume but produces many **unanswered, high-stakes questions** (migration, security).
- GitHub issues capture serious concerns (e.g., wallet support + impersonation risk) but may not be routed fast enough.

### Improvements for structured, actionable feedback
1) Add **issue templates** for:
   - Plugin integration bugs (requires: versions, install method, typecheck output)
   - Migration problems (exchange, custody type, snapshot status, wallet type, proof requirements)
2) Add a **“Support Safety” intake**:
   - Report impersonators/phishing attempts with timestamps and screenshots; publish outcomes.
3) Run a **quarterly developer survey**:
   - Top blockers: setup, plugin dev, streaming, performance; include environment details.

### Underrepresented segments
- **Non-English communities (notably Korean users)**: strong sentiment signal but unclear feedback loop; needs localized announcements and a trusted liaison/mod presence.
- **CEX-based users**: repeatedly impacted by migration but lack a single official, comprehensible guide.

---

## Prioritized High-Impact Actions (next 2–4 weeks)

1) **Publish a canonical Migration Hub (status + per-exchange rules + wallet compatibility + anti-phishing guidance)** and link it everywhere (Discord pinned + GitHub).
2) **Ship “Plugin Dev Golden Path” docs + a compiling starter template**, covering install method, actions registration, version pinning, and common TS errors.
3) **Resolve provider contract ambiguity**: merge/iterate on PR #6263 with clear documented expectations + runtime timing warnings.
4) **Fix Actions UI streaming end-to-end** (contract tests + UI fallback states) so “streaming supported” matches user experience.
5) **Implement `elizaos doctor` preflight checks** for DB + env + plugin compatibility to reduce DM-based troubleshooting and repeated setup failures.