# User Feedback Analysis — 2026-04-12

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

**Sample size & method:** 13 distinct feedback threads/items from Discord (Apr 9–10), GitHub issues, and PR review findings included in the aggregated data. Percentages below are share of these 13 items.

### A. Documentation (most frequent; high severity)
**~31% (4/13) of items** center on missing/unclear docs, often blocking integration work.

- **ElizaOS v2 Socket.IO protocol is undocumented/implicit**: users can only infer message types and payload shapes from code. Example: Shah0406 discovered the working pattern (`socket.emit('message', { type: 1 ... })` for ROOM_JOINING, `type: 2` for SEND_MESSAGE) and that **`entityId` UUID is required** for auth, but had to reverse-engineer it.
- **No documented method for programmatic DM channel creation** in v2 (requested explicitly).
- **elizabao_ai lacks “what is this / what can I do today” documentation**, prompting repeated questions (cryptovalutchik_, baogerbao observation).
- **Token-related docs/FAQs missing** (utility, airdrops, buybacks, Jeju gas fees), leading to repeated expectation clashes.

**Who it affects most:** integrators building custom dashboards/connectors; community members evaluating the project’s token/economic roadmap.

---

### B. Technical Functionality (high severity, integration-blocking)
**~23% (3/13)** are concrete breakages/logic bugs that can block setup or cause incorrect runtime behavior.

- **`elizaos create` fails on macOS due to Bun postinstall/runtime dependency behavior** (Issue #6704). CLI cleans up and leaves no project, increasing frustration and retriage time.
- **Core runtime correctness hazards surfaced in PR review notes**:
  - Memory pipeline edge cases (e.g., IGNORE memory persistence logic when `ALLOW_MEMORY_SOURCE_IDS` is set; embedding failure producing **zero vectors** that make memories unretrievable).
- **Group addressee routing risk**: PR #6712 review flags a P1 bug where aliasing may break addressing resolution for agents with separate `entityId`/`agentId`.

**Who it affects most:** new developers onboarding (CLI), production deployers relying on memory, multi-agent/group-room users.

---

### C. Integration (frequent; medium-to-high severity)
**~23% (3/13)** relate to integrating elizaOS with external systems (connectors, identity, deployment).

- **Socket.IO compatibility details** (message types, payload schema) missing, leading to trial-and-error integration.
- **Wallet verification via Collab.land** unresolved (Huey79ng). This is an ecosystem integration issue that blocks role-gated participation.
- **No-code/serverless deployment interest** (Hatcher.host) suggests users want “deploy without managing infra,” which may not match current official tooling/onboarding.

**Who it affects most:** community operators, agent hosts, and “builder” users who want a dashboard + hosted runtime.

---

### D. Community / Governance / Project Clarity (high emotional severity)
**~15% (2/13)**, but high impact on trust.

- **Token utility / airdrop / buyback timing uncertainty**: users expressed frustration; responses indicate plans exist but details aren’t available (“no additional plans beyond what was previously announced”).
- **Strategic focus shift (v2 → v3, messaging deprioritized)**: Odilitime noted the team is focusing on v3, while users are actively building on v2 messaging protocols today.

**Who it affects most:** token holders, community members tracking roadmap, and builders needing confidence in which version to target.

---

### E. Performance / Reliability (lower frequency; potentially high severity)
**~8% (1/13)** but important for production.

- Provider timeouts/latency sensitivity surfaced indirectly: changes like total provider timeout defaults and new logging/pipeline controls can shift P99 latency expectations (raised in PR review context). Users don’t explicitly report latency, but review notes suggest likely production friction without clear guidance.

---

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

### What users are actually doing
- **Building custom dashboards + real-time chat connectors**: Shah0406 runs a dashboard (8080) talking to elizaOS v2 via Socket.IO with HTTP polling fallback; model stack includes `@elizaos/plugin-openai` and **local Qwen3.5 via Nosana GPU**. This is “agent as a service” with custom UI, not just local CLI usage.
- **Seeking “deployment platforms”** rather than self-hosting: Hatcher.host pitch indicates strong demand for no-code/serverless deployment.
- **Using agents for crypto/economic workflows**: wallet plugin, SafeAgent token safety, marketplace plugins, and economic memory (MnemoPay) show strong pull toward **autonomous financial operations** and risk controls.
- **Community discovery-driven engagement**: elizabao_ai interest appears driven by hype/word-of-mouth, but users lack an entry point to convert curiosity into usage.

### Emerging / unexpected use cases
- **Agent-to-agent commerce & “marketplace” primitives**: MAXIA plugin proposal and AIGEN reward economy point to an ecosystem trend: agents buying services, renting GPUs, swapping tokens, and needing escrow/reputation.
- **Governance/authorization layers for tool calls**: capability token enforcement proposal (@sint/eliza-plugin) aligns with the project’s AgentID direction and real-world safety constraints (robots/IoT noted by proposer).

### Feature requests aligning with real usage
- Canonical **Socket.IO protocol spec** + message type enum + payload schema (v2).
- **Programmatic DM creation** API/docs for connector builders.
- **Safer autonomous finance**: pre-trade safety checks, escrow flows, reputation/economic memory—users are already proposing plugins, implying demand is present now.

---

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

### Pain Point 1: Missing Socket.IO v2 protocol documentation (Docs + Integration)
**Impact:** High (blocks connector/dashboard builders). **Difficulty:** Low–Medium.

**Implementable solutions (priority order):**
1. **Publish a single “Socket.IO Protocol Spec (v2)” page**:
   - Include message types (ROOM_JOINING=1, SEND_MESSAGE=2), required fields, auth (`entityId`), and example payloads.
   - Add a “compat matrix” for WebSocket vs HTTP polling fallback.
2. **Auto-generate docs from source enums/schemas**:
   - Extract message types/payload schemas at build time into docs to prevent drift.
   - Similar approach: projects like **tRPC** and **OpenAPI** ecosystems reduce mismatch by generating typed clients/specs.
3. **Provide a minimal reference client + test fixture**:
   - A small Node client that joins a room and sends/receives messages, used as an integration contract test.

---

### Pain Point 2: Onboarding breakage in `elizaos create` on macOS (Technical Functionality)
**Impact:** Very High (hard stop for new users). **Difficulty:** Medium.

**Implementable solutions:**
1. **Remove `bun` as runtime dependency** in CLI/templates as suggested in Issue #6704; use `@types/bun` in devDependencies only.
2. **Change CLI behavior on failure: don’t delete the project directory**:
   - Keep generated files and emit a “next steps” recovery guide.
   - Similar pattern: **create-next-app** and **create-vite** leave artifacts to aid debugging.
3. **Preflight checks + actionable error messaging**:
   - Detect bun install mode (`--ignore-scripts`, pnpm-like behaviors) and warn before build.
   - Provide a single command workaround if possible.

---

### Pain Point 3: Token/economic roadmap ambiguity (Community + Documentation)
**Impact:** High on trust; persistent confusion. **Difficulty:** Low.

**Implementable solutions:**
1. **Create a “Token & Economics Status” living page** updated weekly:
   - Explicit “Known / Unknown / Not planned” sections for airdrops, buybacks, gas fees (Jeju).
2. **Add a public “decision log” (short-form RFC outcomes)**:
   - One paragraph per decision to prevent repeated debates.
   - Similar approach: **Rust RFCs** / **Kubernetes KEPs** improve expectation-setting even when timelines slip.
3. **Set a default response template for mods/core team**:
   - A consistent, link-first answer reduces repeated back-and-forth and perceived evasiveness.

---

### Pain Point 4: Wallet verification (Collab.land) unresolved (Integration + Community)
**Impact:** Medium–High (blocks participation, role gating). **Difficulty:** Medium.

**Implementable solutions:**
1. **Create a pinned “Wallet Verification Troubleshooting” guide**:
   - Common failure modes, screenshots, expected time to sync, escalation path.
2. **Add a lightweight support workflow**:
   - A single Discord form/thread template capturing wallet/network/tx hash/Collab.land status.
3. **Instrument verification outcomes**:
   - Track failure reasons monthly to prioritize fixes (API rate limits, chain mismatch, stale signatures).

---

### Pain Point 5: Version focus mismatch (v2 in use, v3 prioritized) (Communication Gaps + Docs)
**Impact:** High for builders choosing a target. **Difficulty:** Low.

**Implementable solutions:**
1. **Publish a “Support Policy” for v2/v3**:
   - “v2 stable but docs limited,” “v3 recommended for new builds,” and what will/won’t be backported.
2. **Add a v2 “Bridge Guide”**:
   - Best-effort docs for the top v2 integration points still in active use (Socket.IO, DMs, connectors).
3. **Tag docs clearly by version**:
   - Prevent users reading v3 docs while building v2 (a common hidden friction).

---

### Pain Point 6: Plugin submissions quality/fit variability (Technical + Community)
**Impact:** Medium (maintainer load, ecosystem quality). **Difficulty:** Medium.

**Implementable solutions:**
1. **Introduce a plugin acceptance checklist** (persistence, null-safety, tests, memory bounds, config validation).
2. **Provide a “golden plugin template” with tests**:
   - Similar to **VS Code extension generator** and **Nx plugin generators** that bake in best practices.
3. **Add automated CI checks for community plugin PRs**:
   - Lint for unsafe casts, missing tests, unbounded memory growth patterns.

---

## 4) Communication Gaps (Expectations vs. Reality)

### Recurring expectation mismatches
- **“There must be Socket.IO message type docs” vs. reality: reverse-engineer from code**
  - Odilitime’s suggestion to “use Cursor AI to query the codebase” is helpful for power users, but signals that canonical docs are missing.
- **“Token plans should have timelines” vs. reality: plans acknowledged, details unavailable**
  - This gap is driving frustration; even a “no ETA” statement in a canonical location would reduce repeated questions.
- **“v2 is supported because it exists” vs. reality: team focus is v3**
  - Users are actively integrating v2 today; they need to know if they’re building on shifting ground.
- **“Wallet verification is a quick fix” vs. reality: no resolution path surfaced**
  - Unresolved support threads diminish confidence for newcomers.

### Documentation/onboarding gaps indicated by repeated questions
- “Where are Socket.IO enums and payload specs?”
- “How do I create DMs programmatically?”
- “What is elizabao_ai and what can I do with it right now?”
- “What are the concrete mechanics/timeline for airdrops/buybacks/gas fees?”

**Suggested improvements (specific):**
- Add “Most Asked” section to docs homepage linking to the above four topics.
- Maintain versioned docs nav (v2/v3) with a prominent selector/badge.
- Add a one-page “Integration Recipes” section (Socket.IO, Discord connector, dashboard pattern).

---

## 5) Community Engagement Insights

### Power users (and what they need)
- **Shah0406 (Discord)**: needs authoritative protocol docs, DM creation guidance, and stable integration contracts for Socket.IO.
- **dirtybits (GitHub #6704)**: provides high-quality repro + root cause analysis; needs fast triage, confirmation, and a changelog entry when fixed.
- **NubsCarson (PR #6709)**: focused on connector reliability (toon params, async action spam); would benefit from a maintainer-endorsed connector testing checklist.
- **dutchiono (Windows friction fix in plugin-openrouter)**: represents cross-platform onboarding needs; suggests value in a Windows CI gate for common install actions.

### Newcomer questions indicating onboarding friction
- **Wallet verification** (Huey79ng): “I can’t get verified” with no visible resolution.
- **“What is elizabao_ai?”** (cryptovalutchik_): curiosity without activation path.

### Converting passive users into contributors
- Run a monthly **“Docs bug bash”** with scoped tickets: Socket.IO spec page, elizabao_ai explainer, v2/v3 support policy.
- Add **“good first issue”** labels specifically for docs + integration examples.
- Provide a Discord “Contributor Onramp” post: how to reproduce, where to file issues, minimal PR standards.

---

## 6) Feedback Collection Improvements

### Current channel effectiveness
- **Discord** is high-volume but low-structure: issues like Collab.land verification can remain unresolved and untracked.
- **GitHub issues** are high-signal (e.g., #6704) but skew toward developers; community/economics questions stay in Discord and repeat.

### Improvements for structured, actionable feedback
1. **Add Discord issue-intake shortcuts**:
   - A bot command like `/report-bug` that generates a prefilled GitHub issue link (env, steps, expected/actual).
2. **Create a dedicated “Integration Support” tracker**:
   - One GitHub Discussions category or repo board for Socket.IO/connectors/auth flows.
3. **Monthly “Top 10 questions” digest**:
   - Convert repeated Discord questions into doc PRs; track reduction over time.

### Underrepresented segments (missing feedback)
- **Non-crypto / non-token users**: current signal is heavily finance/economics; need feedback from “standard agent automation” users.
- **Python/Rust runtime users**: prompt/template regeneration mentions multi-language, but feedback is mostly TypeScript/Discord.
- **Enterprise/self-host operators**: little direct feedback on observability, upgrades, and SLOs—despite changes touching logging/timeouts.

---

## Prioritized High-Impact Actions (next 1–2 weeks)
1. **Publish canonical v2 Socket.IO protocol documentation** (types, required fields, auth via `entityId`, examples) + a minimal reference client.  
2. **Fix `elizaos create` macOS Bun dependency issue** (remove bun runtime dependency) and change CLI failure mode to keep project files for debugging.  
3. **Create a public “v2 vs v3 support & migration policy” page** with clear guidance on what is maintained, best-effort docs, and recommended targets.  
4. **Ship a “Token & Economics Status” living FAQ** (airdrops/buybacks/Jeju gas fees) to reduce repeated Discord churn and rebuild trust.  
5. **Stand up a structured Discord → GitHub escalation path for account/verification issues** (Collab.land troubleshooting guide + intake template + tracking).