# User Feedback Analysis — 2026-04-13 (elizaOS)

## 1) Pain Point Categorization (Top Recurring 5–7)

**Dataset basis:** 9 high-signal feedback items across Discord + GitHub (issues/PR reviews) from the provided logs. Percentages below use *n=9*.

### A. Documentation (most frequent) — **33% (3/9)**
**What users are hitting:**
- **Socket.IO v2 protocol is undocumented**: message type enums, required/optional payload fields, and auth requirements (e.g., `entityId` UUID) are being discovered by trial-and-error. (Discord: shah0406)
- **How to do “programmatic DM channel creation”** without an official UI is unclear (Discord: shah0406).
- **“Docs vs reality” gap** when maintainers recommend “use Cursor to query the codebase” as the path to protocol specs—this is not a stable, canonical source for integrators. (Discord: response from Odilitime)

**Impact:** Blocks dashboard/connector builders and creates fragile integrations.

---

### B. Technical Functionality (core correctness & developer ergonomics) — **44% (4/9)**
**What users are hitting:**
- **CLI project creation failure on macOS (bun postinstall behavior)**: `elizaos create` fails with “Bun's postinstall script was not run,” then cleans up the directory, leaving the user with nothing to inspect. (GitHub issue #6704)
- **Core runtime memory correctness risks** surfaced in PR review:
  - IGNORE-path memory persistence logic appears inconsistent when `ALLOW_MEMORY_SOURCE_IDS` is set (Greptile review on PR #6562).
  - Embedding failure fallback persisting “zero vectors” risks silent semantic-memory corruption (Greptile review on PR #6562).
- **Group-room addressee routing logic bug**: aliasing entity IDs can break name resolution for agents whose `agentId ≠ entityId`, disabling the feature in real deployments (Greptile review on PR #6712).
- **Plugin quality issues reaching PR stage**: MnemoPay plugin flagged for lack of persistence, null-unsafe handlers, ambiguous action triggers, and no tests (Greptile review on PR #6701).

**Impact:** Onboarding failures + silent correctness issues reduce trust in automation and agent behavior.

---

### C. Integration (connectors/platform interoperability) — **22% (2/9)**
**What users are hitting:**
- **Socket.IO integration complexity**: correct message emission patterns and polling fallback behavior are not spelled out; users reverse-engineer (`type: 1` join, `type: 2` send) and auth constraints. (Discord: shah0406)
- **Discord connector/TOON parameterization edge cases**: the platform is actively used via connectors where action params must be reliably captured (PR #6709 context: discovered while testing a Discord connector).

**Impact:** Integrators spend time reverse-engineering instead of building.

---

### D. Community / Support Operations — **22% (2/9)**
**What users are hitting:**
- **Wallet verification problems with Collab.land** remained unresolved in-thread. (Discord: Huey79ng)
- **User frustration with unclear token plans** (airdrops/buybacks/gas fee implementation). (Discord: multiple community members)

**Impact:** Trust and retention risk—especially for token-aligned community members.

---

### E. Performance / Reliability (emerging) — **11% (1/9)**
**What users are hitting:**
- **Provider timeout and latency expectation changes**: PR review flagged a default timeout increase that could change P99 latency and responsiveness in deployments (Greptile review on PR #6562).

**Impact:** May degrade responsiveness for latency-sensitive bots/agents if defaults shift silently.

---

## 2) Usage Pattern Analysis (Actual vs Intended)

### Observed “real usage” patterns
- **Custom dashboards + real-time messaging**: users run ElizaOS v2 behind a custom dashboard (ports 8080/3001) with Socket.IO + HTTP polling fallback, and swap between hosted plugins and local LLMs (e.g., Qwen via Nosana GPU). (Discord: shah0406)
- **Agents as crypto/economic actors**: plugin proposals and repo direction show strong usage in trading, safety checks, wallets, marketplaces, escrow, and “economic memory.” (GitHub issues #6700, #6706, #6708; PR #6701)
- **Multi-agent/group-room deployments**: addressee routing and anti-loop work indicates many deployments run agents in shared rooms and need deterministic “who is this message for?” logic. (PR #6712)
- **Connector-first operation**: Discord/other connectors drive requirements like structured action parameters (“toon”), async action handling, and non-streaming connector compatibility. (PR #6709)

### Mismatches vs intended/assumed usage
- **Integrators expect stable protocol specs** (Socket.IO types, payload schemas); current expectation is “read the code / ask Discord.”
- **“Open-source plugin ecosystem” expectation vs plugin QA reality**: community PRs may be accepted without persistence/tests unless there’s a clear bar and template.

### Feature requests aligned with observed usage
- Canonical **Socket.IO v2 protocol reference** (types, examples, auth).
- **DM creation API/pattern** documentation.
- **Capability/authorization layer** for tool calls (matches economic + real-world action risk). (Issue #6707 aligns with AgentID direction)

---

## 3) Implementation Opportunities (Concrete Solutions)

Below, each major pain point includes **2–3 implementable solutions**, prioritized by **impact vs difficulty**, plus examples of how other projects typically address similar issues.

### 1) Socket.IO v2 protocol is under-documented (Docs + Integration)
**Solutions**
1. **High impact / Low–Med difficulty:** Publish a *versioned protocol spec* page:
   - Enumerate message `type` values (ROOM_JOINING, SEND_MESSAGE, etc.)
   - Define payload schemas (required vs optional)
   - Auth options (`entityId` UUID) and handshake examples  
   *Comparable approach:* Socket.IO-based platforms often ship “event catalogs” + JSON schema snippets (e.g., many realtime SDKs publish an “Events Reference” with payload tables).
2. **High impact / Med difficulty:** Provide a **typed SDK layer** (`@elizaos/socketio-client` or “dashboard connector” example) that exports:
   - `MessageType` enum
   - `joinRoom()`, `sendMessage()` helpers
   - Runtime validation (zod/io-ts) to fail fast on schema drift  
   *Comparable approach:* Supabase Realtime and Firebase publish client helpers to prevent raw event misuse.
3. **Med impact / Low difficulty:** Add a **golden integration test** (CI) that spins up v2 server + sample client and asserts join/send flows.

---

### 2) `elizaos create` fails on macOS due to bun dependency/postinstall (Technical Functionality)
**Solutions**
1. **High impact / Low difficulty:** Remove `bun` from runtime dependencies in `@elizaos/cli` and bootstrap (keep only `@types/bun` as dev dependency), per issue #6704.
2. **High impact / Low difficulty:** Change CLI failure mode: **do not delete the generated project directory** on build failure; instead, leave it with a clear “Next steps” message and log path.
3. **Med impact / Med difficulty:** Add a **preflight checker** in CLI:
   - Detect bun install mode / postinstall script settings
   - Validate expected binary exists before build step  
   *Comparable approach:* Next.js / Create React App style scaffolds run environment checks and provide targeted remediation steps.

---

### 3) Token utility / airdrops / buybacks / gas fees unclear (Community + Communication)
**Solutions**
1. **High impact / Low difficulty:** Create a **single canonical Token FAQ** pinned in Discord + docs:
   - “What’s confirmed vs unconfirmed”
   - “What we are not committing to”
   - Update timestamp + changelog of edits
2. **High impact / Low–Med difficulty:** Adopt **scheduled comms** (e.g., biweekly “token/economics status” post) even if status is “no change,” to reduce repeated questions.
3. **Med impact / Med difficulty:** Add a **public roadmap section** for token mechanics with explicit dependency gates (e.g., “Jeju gas fees after X release milestone”).  
   *Comparable approach:* Many OSS + token projects maintain a “Status & Known Unknowns” page to avoid rumor-driven expectation.

---

### 4) Wallet verification / Collab.land support is stalling (Community + Integration)
**Solutions**
1. **High impact / Low difficulty:** Add a **“Wallet Verification Troubleshooting”** guide (Collab.land common failure modes, re-link steps, what logs/mods need).
2. **High impact / Low–Med difficulty:** Create a **#wallet-verification-support** intake format:
   - required fields (Discord ID, wallet address last 4, error screenshot, timestamp)
   - privacy guidance (never post full seed/private info)
3. **Med impact / Med difficulty:** Add a lightweight **verification status bot command** to show whether the user is recognized by the gating system (without revealing sensitive data).  
   *Comparable approach:* Many Discord-gated communities use structured support forms + a bot to reduce moderator load.

---

### 5) Core runtime correctness risks (memory persistence, embeddings fallback, routing bugs) (Technical Functionality + Reliability)
**Solutions**
1. **High impact / Med difficulty:** Fix and regression-test:
   - IGNORE-path persistence logic under `ALLOW_MEMORY_SOURCE_IDS`
   - Prevent persisting “zero vector” embeddings; instead mark memory as “unembedded” and queue retry/backfill  
   *Comparable approach:* Vector DB pipelines often store “embedding_status=pending/failed” and retry asynchronously.
2. **High impact / Med difficulty:** Add **“behavior-changing default” release notes gates**:
   - If `PROVIDERS_TOTAL_TIMEOUT_MS` defaults change, force explicit opt-in or major-version bump semantics.
3. **Med impact / Med difficulty:** For group addressee routing (PR #6712), fix aliasing ambiguity and add tests specifically for `agentId ≠ entityId` scenarios (the current tests reportedly don’t catch it).

---

### 6) Plugin PR quality and lifecycle inconsistencies (Community + Technical Functionality)
**Solutions**
1. **High impact / Low difficulty:** Add a **plugin PR checklist** template (required):
   - persistence story (if storing “memory”)
   - null-safety patterns for `runtime.getService`
   - tests required (minimum smoke tests)
   - action trigger keyword conflict check
2. **High impact / Med difficulty:** Introduce a **“plugin maturity model”** (Experimental → Beta → Stable) and label registry entries accordingly.
3. **Med impact / Med difficulty:** Add automated CI checks for plugin submissions (lint, typecheck, minimal runtime instantiation).  
   *Comparable approach:* VS Code extensions and many plugin registries enforce “publishing gates” and maturity tags.

---

## 4) Communication Gaps (Expectations vs Reality)

### Where expectations diverge
- **“v2 is usable for dashboards” vs “team focus is on v3”**: integrators need stable v2 Socket.IO docs now, but responses imply limited bandwidth (“team prioritizing v3”). This creates uncertainty about whether to build on v2.
- **“Token announcements exist” vs “no new details”**: repeated questions show users expect concrete timelines (buybacks, gas fees), but answers remain non-committal—without a single canonical page to point to.

### Recurring questions indicating onboarding/documentation gaps
- “What are the Socket.IO message types / payload fields?”
- “How do I authenticate (entityId)?”
- “How do I create DMs programmatically?”
- “Why does `elizaos create` fail and why did it delete my project folder?”

### Specific improvements
- Add “**Supported Integrations & Stability**” matrix: v2 vs v3, connectors supported, protocol stability guarantees.
- Replace “use Cursor on the codebase” guidance with a **doc-first** answer and link to generated API/protocol references.

---

## 5) Community Engagement Insights

### Power users observed (and what they need)
- **shah0406 (Discord)**: building a custom dashboard + Socket.IO integration; needs canonical protocol docs and DM creation patterns.
- **dirtybits (GitHub #6704)**: deep debugging of bun install behavior; needs quick maintainer validation + CLI fix; likely to contribute a PR if guided.
- **NubsCarson / “1gig” (PR #6709)**: connector reliability; needs stable message/action formatting contracts (TOON schema correctness, async action handling).
- **dutchiono (plugin-openrouter PR #25 referenced in weekly summary)**: cross-platform cleanup; needs maintainers to prioritize Windows CI to prevent regressions.

### Common newcomer friction signals
- Setup failures (`elizaos create`) and unclear recovery steps.
- Verification/access gating issues (Collab.land).

### Converting passive users into contributors
- Create “**Integration Bounties**” list (docs + sample clients) with clear acceptance criteria (e.g., “Socket.IO v2 protocol doc + example client = good first issue”).
- Tag issues explicitly as **“needs reproduction,” “needs docs,” “good first PR,”** and provide maintainers’ preferred solution direction to reduce rework.

---

## 6) Feedback Collection Improvements

### Channel effectiveness (current)
- **Discord** captures real-time integrator pain quickly, but outcomes are often *untracked* (e.g., wallet verification unresolved; Socket.IO spec not captured as an issue in the log excerpt).
- **GitHub** contains high-quality technical reports and reviews, but user-impact framing (how many affected, priority) is inconsistent.

### Improvements to gather structured, actionable feedback
1. Add a **Discord → GitHub bridge** process:
   - A slash command or mod workflow to file “docs needed / bug” issues with links to the Discord thread.
2. Add **issue templates** for:
   - “Integration/Protocol docs gap”
   - “Installer/CLI failure”
   - “Verification/Access”
3. Add an **optional anonymous onboarding survey** in the CLI after success/failure (1–3 questions + link).

### Underrepresented segments
- **Non-crypto production users** (few explicit signals; most feedback is crypto/economic + connector-based).
- **UI/low-code builders** (requests center on protocol-level integration; little feedback from less technical users—likely missing because entry barriers are high).

---

## Prioritized High-Impact Actions (Next 1–2 Weeks)
1. **Publish Socket.IO v2 protocol reference (versioned) + minimal client example** (unblocks dashboard/connector builders; reduces repeated Discord support load).
2. **Fix `elizaos create` macOS bun failure + stop deleting project dir on failure** (direct onboarding win; reduces “rage quit” moments).
3. **Create a canonical Token FAQ/status page and pin it (Discord + docs)** (reduces repeated community friction and expectation mismatch).
4. **Patch and add regression tests for the most severe core correctness issues** (IGNORE persistence logic, zero-vector embedding fallback, addressee routing alias bug).
5. **Introduce a plugin PR quality gate (checklist + minimal CI)** to prevent “memory/economy” plugins shipping without persistence/tests/null-safety.