## User Feedback Report — 2025-12-20 (based on aggregated feedback through 2025-12-19)

### Data snapshot (what this analysis is based on)
- **Discord (Dec 17–19)**: heavy discussion in `#discussion`, `#coders`, `#core-devs` around token migration, cloud streaming release readiness, and onchain/EVM plugin status.
- **GitHub (Dec 19 daily)**: **0 new issues**, **1 PR merged** (PR **#6261**). Several UX-related issues by @borisudovicic were closed (Agent Builder naming, JSON export without deploying, markdown bullets, gallery refresh, model selection).
- **GitHub (month/weekly rollups)**: recurring themes: documentation discoverability, onboarding/terminology cleanup, plugin stability/migrations, token migration support edge cases (e.g., Tangem wallet), and persistent plugin issues.

Where percentages are used below, they refer to the **share of distinct feedback items** observed in this dataset (Discord threads + referenced GitHub issues), not overall user base telemetry.

---

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

### 1) Documentation — Token migration clarity & exchange/wallet edge cases (High frequency, High severity)
**What users report**
- Repeated confusion about **eligibility (“0 eligible”)**, **deadline** (Feb 4, 2026), and what happens to unmigrated tokens (“abandoned in old contract”).
- Confusion from users holding tokens on **CEXs** (e.g., Kraken, Bithumb) due to **snapshot timing** and exchange-specific handling.
- Safety concerns about **support impersonation/scams** and the need for “official guidance” (seen strongly in GitHub issue **#6211** for Tangem wallet + compromised Discord support concerns).

**Evidence/examples**
- Discord FAQs repeatedly asked: “What happens after deadline?”, “0 eligible—how migrate?”, “What’s ticker?”, “Should I buy ai16z?”
- Discord Dec 17: exchange discrepancies (Kraken vs Bithumb) and requests for proof of comms with Bithumb about snapshots.
- GitHub: **#6211** highlights a **WalletConnect unsupported wallet** (Tangem) and explicit fear of impersonators.

**Estimated prevalence in dataset:** ~30–40% of distinct feedback items mention migration confusion or its consequences.

---

### 2) Integration — Onchain/EVM capability uncertainty (Medium frequency, High severity for builders)
**What users report**
- Builders can’t tell whether **plugin-evm** is the “official” path, whether it’s maintained, or what’s recommended for production.
- Users are looking for alternatives and “what people are actually using” for onchain actions.

**Evidence/examples**
- Discord `#coders`: Roman V asks if plugin-evm is the go-to and what alternatives exist; Odilitime points to active PR work for EVM support in Spartan; Jin points to the knowledge repo and APIs.

**Estimated prevalence:** ~10–15% of distinct items, but higher severity for developer adoption.

---

### 3) Technical Functionality — Plugin dev friction: TypeScript/runtime interface breaks & action registration (Medium frequency, Medium–High severity)
**What users report**
- Type mismatches (`AgentRuntime` vs `IAgentRuntime`) and action file conversion issues across plugins.
- Confusion about **where to add actions** (can’t see plugin folder; must clone into packages; must register in `src/index`).
- Missing handler errors in specific actions (Starknet “unruggable meme token” deploy handler).

**Evidence/examples**
- Discord Dec 18: Starknet plugin integration blocked by TS incompatibilities and missing handler.
- Discord Dec 17: questions about adding new actions and plugin folder visibility.

**Estimated prevalence:** ~15–20% of dataset items.

---

### 4) Performance — Provider pipeline latency & timeouts (Lower frequency, High impact when it occurs)
**What users report**
- Providers can be slow; need clearer best practices (avoid API calls, cache) and runtime-level guardrails (timeouts, parallel execution).

**Evidence/examples**
- Discord Dec 18: PR discussion about parallel provider execution with configurable timeout (default 1s), warnings for slow providers, and debate about proper provider responsibilities.

**Estimated prevalence:** ~5–10% of dataset items, but impactful to reliability perception.

---

### 5) UX/UI — Terminology, editor flows, and small papercut bugs (Medium frequency, Medium severity)
**What users report**
- Users want clearer naming and flows: “Chat assistant” vs “Agent Builder”; “export JSON without deploying”; gallery refresh; markdown bullets rendering.
- Larger trend (weekly/monthly rollups): “reduce jargon” (RAG→Files, MCP→Services), onboarding overlays, dashboard prioritizing agent creation.

**Evidence/examples**
- GitHub issues closed: **#6258** rename to “Agent Builder”, **#6259** JSON export without deploying, **#6257** markdown bullets, **#6256** gallery refresh, **#6185** model selection optimization.
- Weekly report indicates a large backlog of UX simplification issues created mid-month.

**Estimated prevalence:** ~15–20% across GitHub UX issues and related discussion.

---

### 6) Community — Regional trust & sentiment management (Medium frequency, High risk)
**What users report**
- Korean community members feel **marginalized**; distrust amplified by migration/exchange confusion.
- Broader frustration about “lack of delivered products” and price decline discussions derail technical channels.

**Evidence/examples**
- Discord Dec 18: explicit mention that Korean users feel marginalized; migration described as “disastrous/dilution”; frustration about delivery.

**Estimated prevalence:** ~10–15% of dataset items, but high strategic risk.

---

### 7) Release/Operations — Monorepo release sequencing & NPM token disruptions (Lower frequency, Medium severity)
**What users report**
- Release process depends on strict sequence (release monorepo → merge elizacloud-plugin → bump cloud-v2 core).
- NPM “classic token deleted” caused release friction.

**Evidence/examples**
- `#core-devs`: explicit release order and NPM token issue.

**Estimated prevalence:** ~5–10% (mostly internal/dev-focused), but affects delivery cadence.

---

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

### How users are actually using elizaOS
1. **Web3 + token ecosystem participation** is a major “front door” for many users (migration, exchange handling, wallet eligibility). This is not purely a product UX issue—it's an onboarding + trust + safety requirement.
2. **Builders are using elizaOS as a plugin-first agent runtime** (Starknet/EVM, Discord/Telegram bots, engagement plugins) more than as a single “app”.
3. **Data/analytics-driven agents are emerging**: Jin’s “knowledge repository” endpoints (leaderboards/summaries) are being used as structured inputs for agents; users are exploring turning that into **infographics** and visualization plugins.

### Emerging / unexpected use cases
- **Customer support / internet support agents** requested directly (Error P015-A). This implies demand for:
  - strong streaming UX,
  - robust tool/plugin integrations,
  - safety/guardrails and auditability.

### Feature requests that align with observed usage
- **Streaming everywhere** (cloud streaming release readiness) aligns with support-agent and real-time chat expectations.
- **Visualization plugin** aligns with analytics endpoints and “agents that reason over ecosystem activity”.
- **Export JSON without deploying** aligns with users treating Agent Builder as a design tool and wanting portability/versioning.

---

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

### A) Token migration confusion & edge cases (Docs + UX + Ops)
**Opportunity 1 (High impact, Low–Medium effort): “Migration Center” single canonical page**
- Add an official, versioned page in docs: *Migration status, deadline, eligibility rules, safety warnings, wallet support matrix, CEX snapshot explanation*.
- Include a **decision tree**: “Held on CEX → do X”, “Held on unsupported wallet (Tangem) → do Y”.
- Similar approach: **Uniswap** and **Arbitrum** token claim pages use a single canonical FAQ + “do not trust DMs” banners.

**Opportunity 2 (High impact, Medium effort): In-portal eligibility diagnostics**
- When user sees “0 eligible”, show **specific detected reasons** (snapshot wallet mismatch, wrong chain, CEX custody, unsupported connector).
- Provide “next best action” buttons: “Go to migration-support”, “Check snapshot wallet”, “Read exchange guide”.
- Similar approach: **Gitcoin passport** and **LayerZero airdrop checkers** provide reason codes and remediation tips.

**Opportunity 3 (Medium impact, Medium effort): Verified support workflow**
- Publish a **signed verification method** for support (e.g., “Only trust links from docs.elizaos.ai/migration” + PGP-signed announcement hash).
- Add Discord automation: auto-reply in migration channels with official links + scam warning; lock down tickets.
- Similar approach: many crypto projects pin a “Support will never DM” bot message plus “official links only” command.

---

### B) EVM/onchain integration uncertainty (Integration + Docs)
**Opportunity 1 (High impact, Low effort): “Official Onchain Stack” page**
- A short “recommended stack” page: current status of plugin-evm, Spartan EVM work, stability level, examples.
- Include a maintenance badge: *Active / Experimental / Deprecated* per plugin.
- Similar approach: **LangChain** labels integrations as “community” vs “official” and shows maintenance levels.

**Opportunity 2 (High impact, Medium effort): Reference onchain examples**
- Provide 2–3 canonical recipes:
  - “Read-only chain queries”
  - “Sign + send tx (testnet)”
  - “Indexing / knowledge repo integration”
- Ship as examples in-repo and keep in CI.
- Similar approach: **Hardhat** and **Foundry** provide minimal recipes that become the de facto onboarding path.

**Opportunity 3 (Medium impact, Medium effort): Plugin registry metadata**
- In registry UI/README: last release date, compatible core versions, known issues.
- Reduces “is it maintained?” questions.

---

### C) Plugin development friction (TS types + action registration) (Technical Functionality + Docs)
**Opportunity 1 (High impact, Medium effort): Compatibility layer + codemods**
- Provide a small compatibility shim for `AgentRuntime`/`IAgentRuntime` transitions, plus a codemod to update plugins.
- Similar approach: **Next.js** and **React** ecosystems often ship codemods for breaking API migrations.

**Opportunity 2 (High impact, Low effort): “Create/Extend Actions” doc upgrade**
- Add explicit steps:
  - where plugin source lives,
  - how to clone into `/packages`,
  - action file conventions,
  - required `src/index` registration,
  - debugging guidance (log level debug).
- Include a “common errors” table (missing handler, type mismatch).

**Opportunity 3 (Medium impact, Medium effort): Plugin template tests**
- Ensure starter plugin templates have a CI test that fails if actions aren’t registered or types drift.

---

### D) Provider performance/timeouts (Performance)
**Opportunity 1 (High impact, Medium effort): Merge provider timeout + warnings**
- Proceed with configurable timeout + warning logs (“Provider X took 2500ms—consider caching”), and clear documentation on provider expectations.
- Similar approach: **VS Code extensions** and many plugin systems enforce time budgets and surface “slow extension” warnings.

**Opportunity 2 (Medium impact, Low effort): Provider best-practices guide**
- Explicitly recommend:
  - no network calls in providers unless cached,
  - memoization,
  - batching,
  - observability hooks.

**Opportunity 3 (Medium impact, Medium effort): Tracing dashboard for dev mode**
- Simple per-provider timing output in dev tools / logs to make performance issues actionable.

---

### E) UX/UI papercuts + terminology confusion (UX/UI + Documentation)
**Opportunity 1 (High impact, Low–Medium effort): Continue terminology simplification**
- Align UI labels with user mental models (Agent Builder, Files vs Knowledge, Services vs MCP).
- Add tooltips where jargon must remain (e.g., “RAG”).

**Opportunity 2 (Medium impact, Low effort): Fix high-friction editor workflows**
- Prioritize items like “export JSON without deploying”, “gallery refresh”, markdown rendering.
- These are already being closed—ensure they’re released prominently in changelogs.

**Opportunity 3 (Medium impact, Medium effort): Guided onboarding overlays**
- The issue backlog already suggests this; implement minimal first-run guidance focusing on:
  - create agent,
  - add plugins,
  - add files,
  - test chat,
  - export/deploy.

---

### F) Community trust & regional inclusion (Community)
**Opportunity 1 (High impact, Low effort): Regional comms cadence**
- Post a biweekly Korean-language summary (migration status, exchange coordination updates, roadmap).
- Recruit bilingual community moderators with clear escalation path.

**Opportunity 2 (High impact, Medium effort): Public “delivery scoreboard”**
- A simple page listing shipped features, current sprint goals, and what’s blocked (e.g., NPM token, monorepo release ordering).
- Similar approach: many open-source projects use **public roadmaps** (GitHub Projects) to reduce “nothing shipped” perceptions.

**Opportunity 3 (Medium impact, Medium effort): Community office hours**
- Separate token discussion from developer support; schedule office hours for migration/exchange topics.

---

## 4) Communication Gaps (expectations vs reality)

### Gap: “Migration should be straightforward” vs real-world custody complexity
- Users expect the portal to “just work” for any wallet/exchange custody.
- Reality: snapshot eligibility + unsupported connectors (Tangem) + CEX pooled wallets create real constraints.
**Fix:** Make constraints explicit early (wallet support matrix + custody explanation), and provide safe official escalation routes.

### Gap: “There is an official EVM plugin” vs current evolving implementation
- Builders want a single recommended path; current state appears fragmented (plugin-evm vs Spartan PRs).
**Fix:** Publish an “official onchain status” page with maturity levels and examples.

### Gap: “Plugins are stable across versions” vs frequent type/API changes
- Type mismatches and action format changes (PR #6261) indicate ongoing evolution.
**Fix:** Add a “Plugin API stability” section (semver expectations, migration guides, pinned versions policy).

### Recurring questions indicating onboarding/documentation gaps
- “0 eligible—how to migrate?”
- “Should I buy ai16z?” / “What’s the ticker?”
- “Is plugin-evm the go-to? What do people use?”
- “How do I add actions / where is plugin folder?”
Each of these should be directly answered via docs + pinned Discord FAQs.

---

## 5) Community Engagement Insights

### Power users (observed) and what they need
- **Stan**: driving streaming release and provider performance discussions; needs predictable release mechanics and fast CI feedback.
- **Odilitime**: heavy on plugin ecosystem work (engagement plugin, EVM support PRs); needs clearer plugin API stability, templates, and registry metadata.
- **Jin**: knowledge repo + analytics endpoints; needs productization path (naming, documentation, stable endpoints).
- **@borisudovicic (GitHub)**: high-volume UX issue creator; needs a structured intake process to convert issues into prioritized design tasks.

### Newcomer questions indicating friction
- Migration eligibility (“0 eligible”), ticker confusion, and where to get official help safely.
- Plugin extension basics (actions registration, folder layout).

### Converting passive users into contributors
- Create “good first issue” bundles around:
  - docs improvements (migration center, onchain status page),
  - plugin templates/codemods,
  - registry metadata enrichment.
- Recognize contributors who answer support questions with “Verified Helper” role, tied to a published verification policy.

---

## 6) Feedback Collection Improvements

### Current channel effectiveness
- **Discord** is effective for rapid Q&A but is producing:
  - repetitive migration questions,
  - sentiment spirals (price/delivery debates),
  - safety concerns (impersonation).
- **GitHub issues** capture actionable product/UX items well (e.g., the cluster of UI papercuts and terminology changes), but migration support and wallet edge cases also spill into GitHub due to trust concerns.

### Improvements for more structured, actionable feedback
1. **Add a weekly “Top Questions” digest** generated from Discord, with links to canonical docs answers (reduces repeat questions).
2. **Introduce structured Discord forms** (or a GitHub issue template) for migration problems:
   - custody type (CEX/self-custody),
   - chain,
   - snapshot wallet,
   - portal result,
   - wallet connector availability.
3. **Tagging + routing automation**
   - Auto-tag GitHub issues: `migration`, `wallet`, `docs`, `plugin-api`, `performance`.
   - Auto-respond with the relevant canonical doc link and request missing fields.

### Underrepresented user segments
- **Non-English communities** (explicit Korean concerns).
- **Non-EVM chains** beyond Starknet/EVM appear early-stage; need targeted outreach to chain-specific builders.
- **Enterprise/support-agent builders** are hinted (customer service agents) but not yet systematically interviewed.

---

## Prioritized High-Impact Actions (next 2–4 weeks)
1. **Publish a canonical “Migration Center” page + pin it everywhere** (docs + Discord auto-replies), including safety/anti-scam guidance and CEX/wallet edge cases (Tangem included).
2. **Ship “official onchain status” documentation**: recommended EVM path, plugin maturity badges, and 2–3 reference examples.
3. **Reduce plugin-dev breakage with a migration kit**: codemods/compat layer + improved “extend actions” docs + template tests.
4. **Land provider performance guardrails** (timeouts + warnings) and document provider best practices (cache/no network in providers).
5. **Address community trust gaps** with a lightweight public delivery scoreboard + regional comms cadence (starting with Korean summaries and clearer exchange-handling updates).