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

### Data basis
Sampled feedback from Discord (2025-12-14 to 2025-12-16) plus GitHub activity summaries (Dec 2025 month-to-date, top issues/PRs). Approx. **~15 distinct user-facing friction signals** were identifiable in the provided excerpts; percentages below refer to this sample.

---

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

### 1) **Documentation (highest frequency) — “Where is X / how do I do X?”**
**Signal strength:** ~**27%** (≈4/15) of distinct items point to missing, moved, or unclear docs/onboarding.  
**Examples**
- GitHub: **“Where did packages/docs/ go?”** (#6122) indicates doc discoverability regression.
- Discord: **“What’s the twitter page? Is the project still alive?”** → directed to `#links-and-resources` (users can’t find canonical links quickly).
- Discord: Hardware wallet migration confusion: tokens not showing when connecting Ledger; workaround requires using Phantom/Solflare/etc.
- GitHub: request for a public docs UI + API explorer + Cloud architecture overview (#6128).

**Primary problems affecting most users**
- Doc entry points are not obvious (especially for newcomers).
- Critical “first 30 minutes” tasks (setup, migration, auth modes, DB) are scattered across channels/issues.
- Key product narratives (Cloud, “create→publish→monetize”) are discussed in Discord but not anchored in stable docs.

---

### 2) **Technical Functionality — Database migrations & SQL plugin setup**
**Signal strength:** ~**27%** (≈4/15).  
**Examples**
- Discord: FenrirFawks blocked by **PostgreSQL migration failures** (permissions/schema rights; not superuser; Postgres v18).
- Discord: prior report of **foreign key constraint failures** in Twitter replies pipeline; “latest codebase has SQL fixes.”
- GitHub: plugin-sql crashing unless `.eliza` directory exists (**should auto-create**) (#6204, closed); aligns with setup sharp edges.
- GitHub PRs show ongoing churn in plugin-sql migration and RLS handling (e.g., PR #6215) → indicates complexity is real for users.

**Primary problems**
- Local Postgres onboarding is fragile (permissions, schema ownership, migration idempotency).
- Users aren’t sure whether to use docker-compose, pglite, Neon, or local Postgres.
- Error messages and “what to do next” guidance appear to require expert intervention (moved to DMs).

---

### 3) **Integration — Token migration + wallet/exchange workflow**
**Signal strength:** ~**20%** (≈3/15), but **high severity** due to money/security implications.  
**Examples**
- Discord: Korean users frustrated about **Bithumb migration delays**; unclear accountability (“exchanges are responsible”).
- Discord: Hardware wallet migration: Ledger holdings not visible unless routed through browser wallets.
- Discord: reported **possible security breach** of the migration site (“hacked/hijacked… funds stolen”) → severe trust risk even if unconfirmed.

**Primary problems**
- Users expect elizaOS to control exchange migrations; reality is split responsibility.
- Wallet connection UX is inconsistent across hardware wallets and Solana browser wallets.
- Security communication is not centralized; rumors spread in chat faster than official updates.

---

### 4) **UX/UI — Streaming/rendering behavior mismatch**
**Signal strength:** ~**7%** (≈1/15), but directly impacts perceived quality.  
**Example**
- Discord (core-devs): Streaming works in monorepo, but **Actions UI renders all at once** (no incremental streaming).

**Primary problems**
- Users/devs see inconsistent UI behavior across environments (local vs Actions).
- Streaming is a “trust cue” for AI UX; when broken it looks like latency or freezing.

---

### 5) **Community — Project status uncertainty & channel routing friction**
**Signal strength:** ~**13%** (≈2/15).  
**Examples**
- Discord: **“Is ElizaOS finished?”** / “Is project still alive?”; concern amplified by perceived silence.
- Discord: Users posting price talk in wrong channels; moderators redirect manually.

**Primary problems**
- Newcomers lack a single “state of the project” source of truth (roadmap, shipped this week, what’s next).
- Channel taxonomy is non-obvious; requires human routing.

---

### 6) **Performance / DevEx — AI-assisted coding workflow friction**
**Signal strength:** ~**13%** (≈2/15), mainly from power users/devs.  
**Examples**
- Discord: Repetitive AI review handling → request for a **GitHub bot**; waiting for generation; “sloppy designs.”
- Discord: Need for **environment containers / multi-instance dev** (VirtualBox, git worktrees, containers in Cursor).

**Primary problems**
- Contributors are scaling with AI tools, but lack shared automation patterns (review bots, reproducible envs).
- The project is increasingly “platform + cloud + plugins,” raising the cost of local setup.

---

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

### How users are actually using elizaOS (observed)
1. **Building vertical data agents + deploying quickly**
   - Example: Polymarket tracking agent → writes to **Neon** DB, deployed to **GitHub + Fly.io** (Thirtieth).
   - Another: NFL trade data in Neon + Eliza agent for sports queries (request for help).
2. **Treating elizaOS as an automation runtime, not just a chat agent**
   - Agents that ingest external event streams (bets, tweets, sports transactions) and persist structured data.
3. **Heavy reliance on hosted DBs (Neon) over local Postgres**
   - Suggests users value “works immediately” over full control; local Postgres becomes a blocker.
4. **Developers using AI tooling as a primary contributor workflow**
   - Multi-instance prompting; automation hooks (claudekit); PR policy requiring demo videos for larger changes.

### Intended usage (implied by roadmap/conversations)
- “Create → publish → monetize → promote” Cloud loop; build agents/apps/n8n workflows/MCP/A2A services.
- A smoother CLI-driven path to Cloud provisioning and deployment (reinforced by large Cloud integration PRs).

### Emerging / unexpected use cases
- **Agent as a market intelligence + ETL pipeline** (Polymarket → DB → deploy).
- **Agent as a domain Q&A interface over operational datasets** (NFL trades + Neon).

### Feature requests aligning with actual usage
- Strong alignment: **Cloud-first onboarding via CLI**, starter templates for common patterns (tracker → DB → deploy).
- Strong alignment: **Better DB migration defaults** (auto-create directories, clearer Postgres permissions, docker-compose recipes).
- Strong alignment: **Streaming UI reliability** (needed for agent UX in production demos).

---

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

### A) Documentation discoverability & onboarding gaps (High impact / Low–Med difficulty)
**1) Create a single canonical “Start Here” entrypoint**
- Include: local quickstart, Cloud quickstart, DB options matrix (PGlite vs Postgres vs Neon), and “common errors + fixes.”
- Add a prominent “Official Links” panel (Twitter/X, Discord, docs, status page).
- Similar approach: **Next.js** (`create-next-app` + one landing doc), **Supabase** (single CLI-driven start + docs hub).

**2) Publish a “Migration Hub” doc page (token + wallet) with a pinned Discord message**
- Ledger visibility troubleshooting (Phantom/Solflare intermediary) documented explicitly.
- Exchange responsibility table (what team controls vs what exchanges control).
- Include “security updates” section with timestamps to counter rumor cycles.

**3) Ship the requested public docs UI + API explorer (already signaled in #6128)**
- Prioritize an “OpenAI-style API explorer” and Cloud architecture diagram since these reduce repeated Discord Q&A.

---

### B) Database migration & plugin-sql setup fragility (High impact / Med difficulty)
**1) Add a first-run “doctor” command in CLI**
- Example: `elizaos doctor` runs checks:
  - Postgres connectivity, schema privileges, migration status, `.eliza` directory presence, drizzle version conflicts.
- Output copy-pastable fixes (SQL GRANT statements, docker-compose suggestion).
- Similar approach: **Prisma** (`prisma migrate status`), **Hasura** console diagnostics.

**2) Standardize supported DB paths with opinionated presets**
- Provide 3 blessed presets:
  - “Zero-config local” (pglite)  
  - “Local Postgres via docker-compose”  
  - “Hosted Neon template”
- Each preset includes known-good migration config and permissions.
- Reduces “Are you using docker compose?” uncertainty.

**3) Improve error messages + link to exact docs anchors**
- When migration fails due to schema permissions, detect and print:
  - “Missing CREATE on schema public; run: `GRANT CREATE ON SCHEMA public TO <user>;`”
- Similar approach: **Django** and **Rails** migration errors often include actionable hints.

---

### C) Token migration + security/trust communications (Very high impact / Low–Med difficulty)
**1) Centralize migration status + exchange status dashboard**
- A simple static page (or GitHub README section) listing:
  - snapshot rules, ratios, exchange progress (e.g., Bithumb), known incidents, official domains.
- Similar approach: many L2/token migrations maintain a **Statuspage-like** checklist to reduce Discord churn.

**2) Harden and verify migration site trust signals**
- Publish:
  - official domains, checksums, signed announcements, and a “How to verify you’re on the right site.”
- Add in-site banners when incidents are investigated (“We are investigating reports…” with link).

**3) Add a dedicated “Security & Scams” pinned post and intake**
- Single form/email for suspicious links + an auto-response that explains what the team will never ask for.

---

### D) Streaming UI inconsistency (Med impact / Low–Med difficulty)
**1) Add a reproducible test harness for streaming in CI**
- A minimal integration test verifying incremental token rendering in the Actions environment.
- Similar: **Vercel AI SDK** and chat UIs often have deterministic streaming mocks.

**2) Implement a fallback progressive renderer**
- If true streaming fails, render buffered chunks on a timer (e.g., every 50–100ms) to preserve perceived streaming.

**3) Instrument and log streaming mode**
- Log whether the UI is in “true stream” vs “buffered” mode to speed debugging.

---

### E) Contributor DevEx: AI review automation + reproducible environments (Med impact / Med difficulty)
**1) Implement a GitHub “AI review handler” bot (requested explicitly)**
- Auto-summarize changes, run policy checks, post “requested fixes,” and track re-review cycles.
- Similar: **Renovate** style automation; internal tooling patterns like **bors**/**mergify**.

**2) Provide a “contributor container” baseline**
- Devcontainer + documented worktree strategy to support multi-instance workflows.
- Similar: **VS Code Dev Containers** used by many OSS projects to standardize onboarding.

**3) Codify PR demo requirements**
- Turn the “>20 lines requires video” norm into:
  - PR template checkbox + examples of acceptable demos.
- Reduces surprise friction for new contributors.

---

## 4) Communication Gaps (expectations vs reality)

### Recurring expectation mismatches
- **“Is ElizaOS finished / alive?”** → Users interpret low public chatter as inactivity.
  - Fix: weekly “shipping log” + pinned roadmap snippet.
- **Token migration responsibility**: users assume the team controls exchange timelines.
  - Fix: clear doc explaining exchange-controlled vs team-controlled steps, and what users can do.
- **Wallet UX**: users expect Ledger direct-connect to show holdings.
  - Fix: document intermediary wallet requirement and why (wallet adapters / token visibility).

### Recurring questions indicating onboarding gaps
- “Where are the docs now?” (GitHub #6122)
- “What DB setup should I use? Do I need docker-compose? Is it vector DB?” (Discord coders)
- “Where’s the official Twitter / links?” (Discord discussion)

### Specific improvements to align expectations
- Add “Known limitations” sections:
  - Wallet connection limitations
  - Supported Postgres versions + permission requirements
  - Streaming support matrix (where it works today)

---

## 5) Community Engagement Insights

### Power users observed (and their needs)
- **Stan**: cloud + streaming + auth PR coordination; needs reliable CI/UI parity and smoother DB/migration path for users.
- **cjft**: workflow scaling; needs AI review automation + reproducible environments.
- **R0am**: tool-sharing (claudekit); needs a curated “approved tools” area.
- **Thirtieth**: building real deployed agents (Neon/Fly.io); needs production templates and guidance on “agent conversational configuration.”
- **DorianD**: helps with Ledger migration; needs a place to store and reuse these fixes (FAQ/pins).

### Common newcomer questions (onboarding friction indicators)
- Project legitimacy/status (“alive?”), official links, where docs went.
- Basic setup blockers (DB migrations, wallet migration visibility).

### Converting passive users into contributors
- Create a “Good First Project: Templates” track:
  - Neon + Fly.io starter, Polymarket tracker starter, sports/stats ingestion starter.
- Add a “Community Support Playbook”:
  - How to escalate from Discord → GitHub issue with required logs (DB config redactions, reproduction steps).
- Recognize helpers (weekly shoutout + contributor role) to reinforce support behavior already happening.

---

## 6) Feedback Collection Improvements

### Current channel effectiveness (based on sample)
- **Discord** is effective for rapid help, but produces:
  - unstructured reports, repeated questions, and DM-only resolutions (knowledge loss).
- **GitHub issues** capture actionable items, but many user questions still start in Discord and never become trackable.

### Improvements for more structured, actionable feedback
1. **Add a Discord → GitHub “Issue intake” bot or form**
   - Prompt users posting errors to submit: version, DB type, logs, reproduction steps.
2. **Weekly triage post**
   - “Top 5 reported issues this week” + links to canonical docs/threads.
3. **Tagging and templates**
   - GitHub issue templates for: Migration/Wallet, DB/Migrations, Cloud/CLI, UI/Streaming, Security report.

### Underrepresented segments (missing feedback)
- **Non-crypto developers** evaluating elizaOS purely as an agent framework (most visible chat is token/migration-heavy).
- **International users** beyond Korean community (language accessibility for critical migration/security info).
- **Teams/production operators** (needs around auth, multi-tenancy, observability are emerging but not directly represented in user complaints yet).

---

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

1) **Publish a single “Start Here” docs hub + pinned Discord links** (Docs, status, official accounts, quickstarts, DB matrix).  
2) **Launch a “Migration Hub” page + exchange status dashboard + security bulletin format** (timestamped updates, official domains, scam guidance).  
3) **Ship `elizaos doctor` (or equivalent) to diagnose DB/migration/setup issues** with copy-paste fixes and preset configs (pglite/docker/Neon).  
4) **Fix streaming rendering parity in Actions + add CI coverage for streaming UX** (prevent regressions, improve demos).  
5) **Convert repeated workflow pain into automation: AI review helper bot + devcontainer baseline** (reduces contributor friction and review load).