diff --git a/CLAUDE.md b/CLAUDE.md
index ec78b81..e332824 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,18 +17,50 @@ You are working on **Project Aether** — a beautiful, fast, native open-source
   // (at your option) any later version.
 
 Keep the modular QML structure: separate files in src/qml/components/, src/qml/styles/, src/qml/utils/.
-Every QML file must import:
-
-import QtQuick 2.15
+Every QML file must import:qmlimport QtQuick 2.15
 import QtQuick.Controls 2.15
 import QtQuick.Controls.Material 2.15
 import QtQuick.Layouts 1.15
 import Aether 1.0
 
-    Theme and Constants are singletons — always use Theme.xxx and Constants.xxx. Never use hard-coded colors or sizes.
-    Never use letterSpacing — use font.letterSpacing.
-    Never use modelData directly in Repeater — always use model.modelData or named roles.
-    When fixing errors, change only the necessary lines. Do not rewrite whole files unless asked.
-    Keep code clean, well-commented, and easily changeable later.
+Theme and Constants are singletons — always use Theme.xxx and Constants.xxx. Never hard-code colors, sizes, or fonts.
+Never use letterSpacing: — always use font.letterSpacing:.
+In Repeater delegates, always use named model roles (model.channelId, model.name, etc.) — never modelData.
+When fixing errors, change only the necessary lines. Do not rewrite whole files unless explicitly asked.
+
+QML Best Practices
+
+Use component for inline reusable items inside a file.
+Prefer ListModel + named roles over JS arrays for Repeaters.
+Always wrap Repeater delegates in an Item if you need to pass model properties to custom components.
+Use Loader or StackView for dynamic content.
+Keep QML files small and focused (one component per file when possible).
+
+Qt 6 / CMake Rules
+
+Always use qt_add_qml_module with proper URI Aether.
+Singletons must have pragma Singleton + set_source_files_properties(..., QT_QML_SINGLETON_TYPE TRUE).
+Use Qt 6.8+ minimum in CMake.
+Never hard-code paths.
+
+Resources & Assets
+
+All icons, images, fonts go in resources/.
+Use Qt Resource System (qrc) for everything.
+Prefix resource paths with qrc:/qt/qml/Aether/.
+
+C++ Integration (future)
+
+C++ code only in src/cpp/.
+Expose to QML via QML_ELEMENT, QML_SINGLETON, or context properties.
+Keep C++ minimal — most logic should stay in QML until performance requires otherwise.
+
+UI/UX Style Guide
+
+Dark Material theme with DeepPurple accent.
+Use Theme singleton for all colors, spacing, radii, fonts, animations.
+Use Constants singleton for layout dimensions.
+Subtle hover animations (100–180 ms).
+Clean, modern Discord-like aesthetic.
 
 This is the permanent rule set for Aether. Follow it strictly in every response.
\ No newline at end of file
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..2264a2a
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,74 @@
+# Aether Project Roadmap
+
+**Project**: A beautiful, fast, native cross-platform Qt 6 + QML client for the self-hosted Stoat backend.  
+**License**: AGPL-3.0  
+**Core Principles**: Modular architecture, clean code, performance-first, testability, easy to self-host, no telemetry.
+
+**Theme Direction**  
+Main theme: Black (primary) / Gold (secondary) / Purple (accents) — inspired by apollons.net.  
+The theme will become fully user-customizable in Phase 7.
+
+---
+
+### Phase 1: UI Foundation & Basic Interactivity (Current)
+1. Finalize basic layout stability (guild list, channel list, chat area, member list, voice bar)
+2. Add realistic placeholder data (guilds, channels, fake messages, fake users)
+3. Make UI interactive (channel switching, guild switching, basic message input)
+4. Keyboard navigation basics
+5. Create `UI_Style_Guide.md`
+
+### Phase 2: Core Data Layer & Fake Backend
+6. Create clean in-memory data models (`MessageModel`, `ChannelModel`, `GuildModel`, `UserModel`)
+7. Implement proper channel switching that updates chat content
+8. Fake message sending (adds to list instantly)
+9. Basic app state management (current guild, current channel, etc.)
+
+### Phase 3: Authentication & Stoat API Foundation
+10. Create `StoatClient` C++ class (network layer, JSON handling)
+11. Login / token storage / logout flow
+12. Fetch real guilds, channels, and members from Stoat
+13. Establish real-time WebSocket connection (Stoat events)
+
+### Phase 4: Full Text Chat
+14. Real message loading and sending via Stoat
+15. Read/unread indicators, typing indicators
+16. Message reactions and replies (basic)
+17. Search within a channel
+
+### Phase 5: Voice & Video
+18. Voice channel joining / leaving UI
+19. VoiceBar improvements + mute/deafen logic
+20. Basic voice connection using Qt Multimedia
+21. Video feed placeholder and toggle
+
+### Phase 6: Advanced Features
+22. Direct Messages (DMs)
+23. Notifications (in-app + system tray)
+24. User settings and profile
+25. Threads
+26. Roles and permissions (basic)
+
+### Phase 7: Polish, Theming & Cross-Platform
+27. Full theming system (Black/Gold/Purple base + user-customizable themes)
+28. Dark/Light mode + system preference support
+29. Performance optimizations (virtualization, lazy loading)
+30. Error handling and offline mode
+31. Unit + UI tests
+32. Internationalization stub
+33. Build presets for Windows + macOS
+34. Linux packaging (AppImage + Flatpak)
+35. Android/iOS preparation
+
+### Phase 8: Release & Distribution
+36. Final code review and security audit
+37. Complete documentation (README, build instructions, self-hosting guide)
+38. First public release (v0.1.0)
+39. CI/CD pipeline setup
+
+---
+
+**Current Position**: We are at the beginning of **Phase 1**.
+
+This roadmap is the single source of truth. All future work (with Claude or otherwise) must follow this order unless explicitly revised.
+
+Last updated: 2026-03-30
\ No newline at end of file