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

## Data snapshot (sources & volume)
- **Discord (Dec 12–14, 2025):** ~10 distinct actionable threads (tech support, platform roadmap, security/scam awareness, performance concerns).
- **GitHub (Dec 1, 2025–Jan 1, 2026 interval summary; issues/PRs referenced):** recurring docs/onboarding + setup pitfalls; large PRs pushing Cloud + auth foundations.

Where percentages are used below, they are computed against the **~10–12 distinct actionable feedback threads** observed in the provided dataset (Discord + top GitHub issues). They indicate *directional frequency*, not statistically representative telemetry.

---

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

### 1) Documentation (highest frequency; high severity for onboarding)
**What users report**
- Confusion about **where documentation lives** / docs moved (“Where did packages/docs/ go?” #6122).  
- Requests for a **public, structured /docs** including API explorer + character setup + cloud architecture (#6128).
- Missing “single source of truth” for **token migration steps**, especially hardware wallets (Ledger) and “why tokens don’t appear”.
- Onboarding ambiguity around **API keys vs elizacloud** (“Do I need to connect that [OpenAI API key] to elizacloud?”).

**Frequency (directional):** ~35–45% of actionable threads mention “missing/unclear docs” as the primary blocker.

**Most affected users**
- Newcomers trying “hello world” agents.
- Web3 users migrating tokens and expecting wallet UX parity with common dApps.

---

### 2) Integration (wallets, providers, social platforms)
**What users report**
- **Hardware wallet migration visibility issues**: Ledger connects but Ai16z holdings don’t show until routed via browser wallets (Phantom/Solflare/Rabby/Talisman). Users ask whether they must “move them or how” (unanswered).
- Social distribution dependency: desire/need to **regain access to X (Twitter)**; implied that it affects momentum and promotion.

**Frequency:** ~20–30% of threads.

**Severity drivers**
- Funds/token visibility issues are high anxiety events; users treat them as “critical”.
- Social platform integration is tied to creator monetization and marketing loop.

---

### 3) Technical Functionality (plugins required, installation failures, configuration coupling)
**What users report**
- **TEXT_LARGE errors on minimal input (“hi”)** traced to missing inference plugin registration (OpenAI).  
- **Plugin installation failures** likely from outdated packages; users advised to run `elizaos update`.
- GitHub: setup footgun where **`.eliza` directory must exist** or `plugin-sql` crashes (#6204). (This was addressed by auto-create work in `plugin-sql` PR #6202, but it’s a recurring “first run” failure mode.)

**Frequency:** ~20–30% of threads.

**Most affected users**
- Developers starting from scratch (minimal runtime + plugins).
- Users expecting “batteries included” default providers.

---

### 4) Performance / Cost Controls (API request amplification)
**What users report**
- Twitter agent consuming **excessive API requests (reported as “50 per call”)** (FenrirFawks). This implies rate-limit/cost risks and “runaway” behavior.

**Frequency:** ~5–10% (but high impact when it occurs).

---

### 5) Community (scams, spam, channel noise)
**What users report**
- Scam alert flagged about an externally shared “product beta”.
- Spam/self-promo appearing in technical channels (coders channel had apparent promotion).
- Suggestion to reduce GitHub→Discord webhook noise to “only important events”.

**Frequency:** ~10–20% of threads.

**Severity drivers**
- Safety incidents reduce trust quickly.
- Noise reduces support effectiveness and increases repeated questions.

---

### 6) UX/UI (lower volume in this dataset; still relevant)
**What users report (indirect / via GitHub summaries)**
- Ongoing client UI fixes (markdown spacing, dashboard pointer event) indicate recent friction, though not heavily discussed in Discord over these days.

**Frequency:** low in this slice, but historically non-trivial per weekly report items.

---

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

### Observed real-world usage
1. **Creator/business loop focus (create → publish → monetize → promote)**  
   - Community/partners channel emphasizes shipping a cloud platform oriented around monetization + distribution (SEO, ad network, social publishing).
   - This suggests users are treating elizaOS not just as an agent framework, but as a **creator economy / agent app platform**.

2. **Workflow orchestration over pure coding**
   - Strong emphasis on quickly building **agents, apps, n8n workflows, MCP/A2A services** (shaw).
   - Users appear to want “composable automations” and deployable services, not only local experimentation.

3. **Web3 adjacent operations**
   - Token migration, prediction markets (Sapience), hackathon building “prediction market agents”.
   - NFTs referenced as an interaction surface.

4. **Security automation interest**
   - Request for infosec help to build “security agents” (Jin) indicates an emergent ops/security use case.

### Mismatches vs intended/assumed usage
- Users expect **wallet-connection UX** to behave like a mature Solana dApp; elizaOS site behavior currently requires workaround knowledge (connect Ledger via browser wallet).
- Users expect “agent says hi” to work without deep plugin knowledge; instead they hit **TEXT_LARGE** and plugin registration issues.

### Feature requests aligned with observed usage
- Public docs + API explorer + cloud architecture overview (#6128) maps directly to heavy cloud + workflow usage.
- Provider compatibility (“can I use deepseek api?” #6156) maps to users wanting flexible inference backends.
- Rate-limit/cost controls for social agents maps to promotion loop + X access.

---

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

### Pain Point A — Onboarding docs gaps (docs location, setup, migration)
**Opportunity 1 (High impact / Low–Medium difficulty): “First 15 minutes” guided paths**
- Add 3 short, canonical guides:
  1) **Local quickstart** (run agent, pick inference provider, register plugin)  
  2) **Cloud quickstart** (login, provision key, deploy/publish)  
  3) **Token migration quickstart** (Ledger + browser wallet routing, troubleshooting “token not visible”)
- Include a **troubleshooting table** mapping symptoms → cause → fix (e.g., “TEXT_LARGE on ‘hi’ → no inference plugin registered → install plugin-openai or cloud provider”).

**Opportunity 2 (High impact / Medium difficulty): Public docs site with versioning**
- Implement the requested **public /docs UI** (#6128) with:
  - Version selector (latest/stable)
  - Search
  - Minimal “architecture” diagrams (cloud, MCP/A2A, plugins)
- Similar approach: **FastAPI** + **VitePress/Docusaurus** style docs with auto-versioning.

**Opportunity 3 (Medium impact / Low difficulty): Pin “known answers” in Discord**
- Pin a single “Migration + Wallet FAQ” and “TEXT_LARGE / plugin setup FAQ” in support channels.
- Use a bot command like `/faq migrate-ledger` returning the canonical steps.

---

### Pain Point B — Wallet integration friction (Ledger holdings not visible; unclear steps)
**Opportunity 1 (High impact / Medium difficulty): Wallet adapter UX + detection**
- Detect Ledger connections and prompt:  
  “Ledger detected: connect through Phantom/Solflare/Rabby to expose Solana accounts to the browser.”
- Add an inline link to the migration FAQ and supported wallets list.

**Opportunity 2 (High impact / Medium difficulty): In-app diagnostics**
- Add a “Why don’t I see my tokens?” flow:
  - verify network (Solana cluster)
  - verify token mint address
  - verify selected account index
  - show raw addresses being queried
- Similar pattern: many dApps use “debug wallet” panels and token-list refresh tooling.

**Opportunity 3 (Medium impact / Low difficulty): Explicit migration state model**
- Clarify whether users must “move them” vs “sign a migration” vs “claim” with a step indicator:  
  Connect → Verify holdings → Sign → Confirm → View new asset.

---

### Pain Point C — Plugin & provider configuration failures (TEXT_LARGE; install failures; elizacloud confusion)
**Opportunity 1 (High impact / Low–Medium difficulty): Runtime preflight checks**
- On agent start, validate:
  - at least one inference provider plugin registered
  - required env vars present
  - print a single actionable error message (“No inference plugin found. Run: `elizaos add plugin-openai` or choose Eliza Cloud provider.”)
- Similar pattern: **Next.js** environment checks and **Docker compose** health checks.

**Opportunity 2 (High impact / Medium difficulty): “Provider wizard” in CLI**
- Extend `elizaos create` / `elizaos dev` to ask:
  - local OpenAI/compatible endpoint? (OpenAI, DeepSeek, etc.)
  - Eliza Cloud login?
- Persist config into `.env` and project config; avoid repeated manual steps.

**Opportunity 3 (Medium impact / Low difficulty): Close the “elizacloud vs OpenAI key” confusion**
- One doc page: “Inference providers explained” with a decision tree:
  - “I have OpenAI key” → plugin-openai
  - “I want managed keys + deployment” → Eliza Cloud
  - “I want OpenAI-compatible provider (DeepSeek, etc.)” → OpenAI-compatible config page

---

### Pain Point D — Performance/cost risk in social agents (Twitter agent over-requesting)
**Opportunity 1 (High impact / Medium difficulty): Add rate limiting + caching primitives**
- Provide a standard “social polling” utility:
  - exponential backoff
  - conditional requests (ETags if applicable)
  - dedupe of repeated reads
- Similar pattern: **Slack bots** and **GitHub API clients** commonly ship with built-in throttling.

**Opportunity 2 (High impact / Medium difficulty): Observability defaults**
- Add per-plugin metrics:
  - requests/minute
  - estimated cost
  - last error / rate-limit status
- Surface in CLI and/or dashboard.

**Opportunity 3 (Medium impact / Low difficulty): Safe defaults**
- Lower default polling frequency; require explicit opt-in for aggressive sync.

---

### Pain Point E — Community trust & signal/noise (scams, spam, webhook noise)
**Opportunity 1 (High impact / Low difficulty): Harden Discord hygiene**
- Add automod rules for links + “new account” restrictions in dev channels.
- Add a “Report scam” button/flow and a locked #security-advisories channel.

**Opportunity 2 (Medium impact / Low difficulty): Webhook filtering**
- Implement the suggested GitHub webhook filtering to post only:
  - releases
  - merged PRs with labels (breaking/security)
  - high-priority issues
- Similar approach: many OSS communities use label-based Discord notifications.

**Opportunity 3 (Medium impact / Medium difficulty): Support intake routing**
- Force support requests into a structured form (Discord ticket prompts):
  - OS, version, command output, provider, repro steps.

---

## 4) Communication Gaps (expectations vs reality)

### Gap 1 — “I installed elizaOS, why can’t it answer ‘hi’?”
**Signal:** TEXT_LARGE on minimal input; missing OpenAI/inference plugin registration.  
**Fix:** Make it explicit in onboarding that elizaOS is **provider-agnostic** and requires selecting/registering an inference provider. Add preflight checks and a single canonical error message.

### Gap 2 — “Do I need to connect my OpenAI key to elizacloud?”
**Signal:** Unanswered Discord question.  
**Fix:** Clarify separation:
- Cloud-managed provider keys vs user-supplied OpenAI keys
- When each applies (local dev vs cloud deploy)
- Provide a one-paragraph explanation in CLI output after `create`.

### Gap 3 — Token migration “visibility” interpreted as “missing funds”
**Signal:** Ledger holdings not visible when connecting directly; workaround exists but not documented.  
**Fix:** A migration FAQ + in-app diagnostics + explicit “supported wallet connection paths”.

### Gap 4 — “Docs moved / where are docs?”
**Signal:** GitHub issue #6122 + request for new docs UI.  
**Fix:** Add prominent pointers in README, CLI welcome message, and GitHub issue templates.

---

## 5) Community Engagement Insights

### Power users observed (and what they need)
- **DorianD**: helps users migrate tokens with Ledger; needs a canonical migration doc to point to (reduces repeated 1:1 support).
- **sayonara**: debugging plugin errors; needs standardized troubleshooting playbooks and better error messages.
- **shaw**: driving cloud platform roadmap (agents/apps/n8n/MCP/A2A; monetization loop); needs clear launch comms, docs, and “what’s ready now” status.
- **Jin**: infra/security interest; needs a scoped “security agents” sprint plan + contribution guide for infosec folks.
- **FenrirFawks**: reports Twitter agent API amplification; needs tooling for rate limiting/observability.

### Newcomer repeat questions indicating onboarding friction
- “Why TEXT_LARGE on ‘hi’?”
- “Why plugin install fails / what does `elizaos update` fix?”
- “Do I need elizacloud for API keys?”
- “Why don’t my tokens show up with Ledger?”

### Converting passive users to contributors (practical tactics)
- Create a **“Good First Fix: Docs + DX”** board:
  - migration FAQ
  - provider decision tree page
  - add preflight error copy
- Run a monthly **support-triage hour**: convert top Discord questions into GitHub issues/PRs.
- Offer a “Contributor role” checklist triggered after first helpful Discord answer (recognize helpers like DorianD/sayonara).

---

## 6) Feedback Collection Improvements

### Current channel effectiveness
- **Discord:** fast, high volume, but unstructured; unanswered questions get buried; spam risk.
- **GitHub:** better for durable fixes, but many users don’t file issues unless blocked hard.

### Improvements (structured + actionable)
1. **Add a lightweight “DX bug report” form** (GitHub issue template + Discord ticket integration):
   - exact command
   - logs
   - provider selection
   - expected vs actual
2. **Add tagging/triage automation**
   - auto-label issues: docs / provider / wallet / performance / cloud
3. **Close the loop publicly**
   - weekly “Top 5 fixed from Discord” post, linking to PRs/docs updates.

### Underrepresented segments (missing feedback)
- **Non-web3 developers** using elizaOS purely for agent apps (their needs may differ from token-migration-heavy discourse).
- **Operators/DevOps** deploying at scale (limited direct feedback on deployment, secrets, observability beyond scattered mentions).
- **Windows users** (no explicit dataset signals here; commonly a blind spot in OSS CLI ecosystems).

---

## Prioritized High-Impact Actions (next 2–4 weeks)
1. **Ship onboarding preflight checks + clearer errors for missing inference provider** (eliminate “TEXT_LARGE on hi” dead-end).  
2. **Publish a public, versioned docs hub with “First 15 minutes” paths** (local, cloud, migration) and pin it in Discord + README.  
3. **Create an official Ledger/token migration troubleshooting guide + in-app “why no tokens” diagnostics** (reduce high-anxiety support load).  
4. **Add rate-limit + observability defaults for social/Twitter agents** (prevent runaway requests; protect users from cost/rate-limit failures).  
5. **Harden community channels: spam/scam controls + filtered GitHub webhook notifications** (increase signal, reduce support churn).