docs: improve README for better discoverability

[LucasSantana-Dev]

Summary

Significant README improvements for better GitHub discoverability and user onboarding:

• Visual scannability: Added emoji icons throughout (🎵 🛡️ 🌐 📊 🔧 etc.)
• Better structure: Reorganized features into clear categories with icons
• Enhanced Quick Start: Clearer prerequisites, Docker setup, and configuration
• Command reference: Visual tables organized by category (Music, Moderation, Engagement)
• New sections: Tech Stack, Key Stats, Why Self-Host comparison
• Improved copy: More compelling descriptions, better technical clarity
• Visual hierarchy: Better use of headers, tables, and formatting

No feature or functionality changes — this is purely documentation/presentation improvement.

Checklist

• All existing content preserved
• No features added or modified
• Clear visual structure and emoji icons
• Tested link formatting in Markdown

---

Summary by cubic

Revamped README to improve GitHub discoverability and onboarding. Documentation only; no functional changes.

• Refactors
  • Restructured features into clear categories with icons for faster scanning.
  • Expanded Quick Start with prerequisites, Docker compose steps, and env setup.
  • Added command reference tables and a concise tech stack overview.
  • Clarified Admin panel setup and streamlined documentation links and copy.

^{Written for commit 9ef6fc7. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Reworked the README with clearer sections, updated branding, and improved links.
  • Expanded feature descriptions into detailed category breakdowns for easier discovery.
  • Added more thorough setup guidance, including prerequisites, Docker, local development, and configuration steps.
  • Reorganized command references into clearer tables with descriptions.
  • Improved development, documentation, contributing, and maintenance guidance with more structured instructions.

[github-actions]

Failed to generate code suggestions for PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The README was rewritten across the overview, onboarding, command reference, development, documentation, and maintenance sections.

Changes

README documentation rewrite

Layer / File(s)	Summary
Header and feature overview README.md	The hero/header block, product introduction, feature subsections, and reliability monitoring list were rewritten.
Self-hosting and stack README.md	The self-hosting rationale and tech stack sections were rewritten with updated framing and stack composition.
Setup and configuration README.md	Quick start now includes prerequisites, Docker and local setup steps, and environment configuration variables.
Command reference README.md	The command documentation was reorganized into category tables with per-command purpose text.
Development and admin docs README.md	The development workflow, code organization, documentation index, and admin setup instructions were rewritten.
Contributing and maintenance README.md	The contributing, security, license, and acknowledgments sections were rewritten.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the README documentation refresh focused on discoverability and onboarding.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/improve-readme

---

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 191-239: The command tables in README.md need blank lines around
them to satisfy markdownlint MD058. Update the section containing the Music,
Moderation, Engagement, Integrations, and General tables so each table is
separated from surrounding headings/paragraphs by an empty line, keeping the
table blocks clearly delimited and consistent with the rest of the document.
- Around line 318-335: The Admin Panel Setup text is inconsistent with the
actual access control config: it says “developer role” even though the setup
uses DEVELOPER_USER_IDS as an allowlist. Update the wording in the README
section that describes /admin access so it matches the real gating behavior, and
keep the setup steps and DEVELOPER_USER_IDS examples aligned with that
terminology.
- Around line 355-360: The Security & Maintenance section in README should not
make an unqualified “zero production incidents” claim or imply contradictory
incident-review wording. Update the incident response bullet to either soften
the statement or add a clear source/proof point, and make sure the wording in
this section is internally consistent and aligned with the rest of the README
narrative.
- Around line 264-270: The fenced tree block in README needs an explicit
language label to satisfy MD040. Update the markdown fence around the packages
layout so the block is tagged with a text-like language identifier, keeping the
existing content unchanged; locate the fenced snippet by the packages/shared,
bot, backend, and frontend tree under the README structure section.
- Line 37: The live demo link has mismatched visible text and href targets, so
update the Markdown in README to point the link destination to the same host
shown in the label. Locate the “Live demo” entry and make the hyperlink target
consistent with the displayed domain so readers land on the intended site.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 78f359b8-1813-436a-86ab-089e93dc0507

📥 Commits

Reviewing files that changed from the base of the PR and between 2807cad and 9ef6fc7.

📒 Files selected for processing (1)

• README.md