docs: Add basic AI guidelines and documentation

README.md

@@ -1,16 +1,100 @@
-# moonwell_launcher
+# MoonWell Launcher
 
-A new Flutter project.
+MoonWell Launcher is the desktop launcher for MoonWell, a private World of
+Warcraft: Wrath of the Lich King server focused on a player-friendly experience
+without excessive grind and with stronger social play.
 
-## Getting Started
+The launcher is responsible for:
 
-This project is a starting point for a Flutter application.
+- logging in to a player's MoonWell account
+- downloading and synchronizing client files
+- displaying launcher news
+- launching the game client
 
-A few resources to get you started if this is your first Flutter project:
+## Stack
 
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+- Flutter desktop
+- Dart
+- `flutter_bloc` for launcher UI state
+- `get_it` and `injectable` for dependency injection
+- `dio` for Web API and file download requests
+- `shared_preferences` for launcher preferences
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Prerequisites
+
+Use the latest stable Flutter SDK available from the official Flutter release
+channel. This project does not support FVM-pinned SDK workflows.
+
+```powershell
+flutter pub get
+```
+
+If `flutter` is unavailable, restart the shell after installing Flutter or
+fix PATH so `flutter --version` works.
+
+## Configuration
+
+Set the launcher Web API base URL at compile time:
+
+```powershell
+--dart-define=MOONWELL_API_BASE_URL=https://host
+```
+
+Example run command:
+
+```powershell
+flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host
+```
+
+## Development
+
+Regenerate dependency injection after changing injectable services:
+
+```powershell
+dart run build_runner build --delete-conflicting-outputs
+```
+
+Run static analysis:
+
+```powershell
+flutter analyze
+```
+
+See `docs/linting.md` for the full format, analyze, test, and Lefthook
+pre-commit workflow.
+
+Build the Windows launcher:
+
+```powershell
+flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host
+```
+
+The Inno Setup installer script lives at `installer/moonwell_launcher.iss`.
+
+## Architecture
+
+The UI lives in `lib/app`, with shared UI widgets under `lib/app/widgets`.
+Launcher domain models, sync use cases, API clients, installation services, and
+preferences live under `lib/features`.
+
+The launcher sync flow is manifest-based:
+
+1. authenticate against the MoonWell Web API
+2. fetch the client manifest
+3. scan the selected installation directory
+4. compare local files to the manifest
+5. remove stale files outside ignored directories
+6. download missing or changed files to temporary part files
+7. verify size and SHA-256 before replacing client files
+8. launch `Wow.exe` from the selected client directory
+
+See `docs/launcher_web_api_spec.md` for the API and sync contract.
+
+## Documentation
+
+- `AGENTS.md`: architecture, commands, and repository rules for contributors
+- `TODO.md`: refactoring, verification, and Flutter upgrade tasks
+- `docs/linting.md`: format, analyze, test, and Lefthook workflow
+- `docs/project_review.md`: project review with strengths, weaknesses, and
+  upgrade feasibility notes
+- `docs/launcher_web_api_spec.md`: current launcher Web API and sync behavior