docs: Add basic AI guidelines and documentation

AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md
+
+This file is the working guide for people and agents changing MoonWell
+Launcher. Keep it current when architecture, commands, or repository rules
+change.
+
+## Project Shape
+
+MoonWell Launcher is a Flutter desktop app for a private World of Warcraft:
+Wrath of the Lich King server. It logs players in, downloads and synchronizes
+client files, displays launcher news, and starts `Wow.exe`.
+
+Important areas:
+
+- `lib/main.dart` initializes Flutter, the desktop window, dependency
+  injection, and `MoonWellApp`.
+- `lib/app` contains UI screens, BLoC state, widgets, and theme code.
+- `lib/app/widgets` contains shared app-level UI such as the custom desktop
+  title bar.
+- `lib/features/launcher/domain` contains launcher entities such as sessions,
+  manifests, news items, sync status, and exceptions.
+- `lib/features/launcher/application` contains use cases for session restore
+  and client synchronization.
+- `lib/features/launcher/data` contains API, installation, and log services.
+- `lib/features/preferences` stores selected install directory and launcher
+  session data.
+- `lib/service_container.dart` and `lib/service_container.config.dart` provide
+  `get_it`/`injectable` dependency wiring.
+- `docs/launcher_web_api_spec.md` documents the current launcher Web API and
+  sync behavior.
+
+## Flutter SDK Policy
+
+MoonWell Launcher supports the latest stable Flutter SDK only. Do not introduce
+or rely on FVM-pinned workflows.
+
+If `flutter` is not available after installing or updating Flutter, restart the
+shell and verify PATH with `flutter --version`.
+
+## Common Commands
+
+```powershell
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+dart format --set-exit-if-changed .
+flutter analyze
+flutter test
+flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host
+flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host
+```
+
+See `docs/linting.md` for the required format, analyze, test, and Lefthook
+pre-commit workflow.
+
+In the current shell on 2026-06-18, `flutter` was not recognized by
+`Get-Command flutter` or `where.exe flutter`.
+
+## Configuration
+
+The launcher API base URL is compile-time configuration:
+
+```powershell
+--dart-define=MOONWELL_API_BASE_URL=https://host
+```
+
+Do not commit private credentials, production secrets, temporary bearer tokens,
+or local-only API URLs.
+
+## Architecture Notes
+
+- All backend calls should go through `LauncherApiClient`.
+- File sync behavior should stay in `ClientSyncUseCase` and
+  `GameInstallationService`.
+- The server manifest is the source of truth for client files.
+- Downloads must write to `*.moonwell.part`, verify size and SHA-256, then
+  replace the destination file only after successful verification.
+- Local scans should ignore volatile client directories and launcher metadata:
+  `Cache`, `Errors`, `Logs`, `Screenshots`, `WTF`, and `.moonwell_launcher`.
+- Path normalization and traversal checks are safety-critical. Do not bypass
+  `GameInstallationService.resolveClientPath` for manifest-relative paths.
+- `lib/service_container.config.dart` is generated by injectable. Do not
+  hand-edit it unless you are intentionally repairing generated output; prefer
+  regenerating it with build_runner.
+
+## Repository Rules
+
+- Preserve unrelated work in a dirty tree. This repository currently may have
+  user edits in dependency files.
+- Keep changes scoped to the requested behavior.
+- Always keep `README.md` and files under `docs/` up-to-date with any
+  architecture, setup, API, sync, build, or operational change.
+- Keep documentation links current when files move.

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)
+- Flutter desktop
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+- 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
+## Prerequisites
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
+
-samples, guidance on mobile development, and a full API reference.
+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

docs/linting.md

@@ -0,0 +1,42 @@
+# Linting And Test Flow
+
+MoonWell Launcher supports the latest stable Flutter SDK only. Do not use FVM
+for this project.
+
+## Required Checks
+
+Run these commands before committing:
+
+```powershell
+dart format --set-exit-if-changed .
+flutter analyze
+flutter test
+```
+
+Use `dart format .` to apply formatting fixes when the format check fails.
+
+## Lefthook
+
+This repository includes `lefthook.yml` with a `pre-commit` hook that runs the
+same format, analyze, and test flow.
+
+Install Lefthook once on your machine, then install the Git hook from the repo
+root:
+
+```powershell
+lefthook install
+```
+
+Run the pre-commit flow manually with:
+
+```powershell
+lefthook run pre-commit
+```
+
+If `lefthook` is not available, install it with your preferred package manager
+from the official Lefthook distribution, then rerun `lefthook install`.
+
+## Windows Troubleshooting
+
+If Flutter reports that building with plugins requires symlink support, enable
+Windows Developer Mode and rerun the command.

docs/project_review.md

@@ -0,0 +1,105 @@
+# MoonWell Launcher Project Review
+
+Reviewed on 2026-06-18.
+
+## Overview
+
+MoonWell Launcher is a Flutter desktop application for a private World of
+Warcraft: Wrath of the Lich King server. Its core responsibilities are account
+login, client installation/synchronization, news display, and launching
+`Wow.exe`.
+
+The project is already more than a Flutter template: it has a clear launcher
+API contract, domain models for manifests and sessions, a sync use case,
+installation scanning, logging, dependency injection, and tests around the
+most important file verification behavior.
+
+## Strong Points
+
+- The project uses a readable layered structure: UI under `lib/app`, feature
+  code under `lib/features`, and shared primitives under `lib/core`.
+- Client sync is manifest driven and verifies downloaded files by size and
+  SHA-256 before replacing local files.
+- Local path handling normalizes manifest paths and rejects absolute paths or
+  traversal attempts before resolving files under the selected installation
+  directory.
+- Player-generated or volatile client directories are excluded from
+  verification: `Cache`, `Errors`, `Logs`, `Screenshots`, `WTF`, and launcher
+  metadata.
+- Hash caching is implemented as an optimization while keeping the server
+  manifest as the source of truth.
+- Sync diagnostics are written to `.moonwell_launcher/launcher.log`, and failed
+  downloads can be preserved for inspection.
+- The Web API integration is documented in `docs/launcher_web_api_spec.md`,
+  including login, manifest, presigned download, news, pause/resume, and launch
+  behavior.
+- Tests cover deterministic build hash behavior, ignored directories, hash
+  cache behavior, path traversal rejection, sync success, stale file removal,
+  download verification failure, session restore, preferences, and news loading.
+
+## Weak Points And Risks
+
+- `README.md` was still the generated Flutter starter text before this review,
+  so new contributors had no project-specific setup or operation guide.
+- There was no `AGENTS.md`, so future automated or human contributors had to
+  infer architecture, commands, and safety rules from source code.
+- At initial review, `lib/main.dart` contained a large inactive demo
+  `LauncherHome` implementation. This has since been removed from the active
+  entrypoint.
+- At initial review, several Russian UI strings appeared mojibake-encoded in
+  the active login and home flow. These active strings have since been
+  normalized to UTF-8.
+- At initial review, custom title-bar widgets were duplicated between login and
+  home screens. They have since been extracted into a shared widget.
+- Session tokens are persisted through `shared_preferences`. That is simple and
+  testable, but it is not hardened storage for bearer tokens.
+- The dependency injection output file `lib/service_container.config.dart` is
+  committed, but the regeneration command was not previously documented.
+- UI/widget/integration coverage is still light compared with the risk in login,
+  bootstrap, directory selection, news failure handling, sync controls, and
+  launch behavior.
+- There is no visible CI configuration in the repository.
+- The current working tree already had modified `pubspec.yaml` and
+  `pubspec.lock` before this documentation pass. Those changes were not part of
+  this review and should be preserved.
+
+## Flutter 3.44.2 Upgrade Feasibility
+
+Assumption: `3.44.2` means Flutter SDK `3.44.2`.
+
+Current local indicators:
+
+- `.fvmrc` pins Flutter `3.35.2`.
+- `pubspec.yaml` declares Dart SDK `^3.9.0`.
+- `pubspec.lock` declares Flutter SDK `>=3.38.0`.
+- The project policy is latest stable Flutter SDK only; FVM-pinned workflows are
+  not supported.
+- The local shell cannot find `flutter`: both `Get-Command flutter` and
+  `where.exe flutter` fail.
+
+Because `flutter` is not available in this shell, the upgrade cannot be fully
+validated here. If Flutter is installed, restart the shell or fix PATH so
+`flutter --version` works. The code and lockfile already suggest that the
+project has moved beyond the stale `.fvmrc` pin, so the upgrade is plausible,
+but it remains a tooling validation task.
+
+Recommended upgrade path:
+
+1. Install or expose the latest stable Flutter SDK on PATH.
+2. Confirm whether the latest stable Flutter SDK is `3.44.2` or newer.
+3. Remove or ignore stale FVM pinning if it conflicts with the latest-SDK
+   policy.
+4. Run `flutter pub get`.
+5. Regenerate dependency injection only if dependency resolution or generator
+   output requires it:
+   `dart run build_runner build --delete-conflicting-outputs`.
+6. Run `flutter analyze`.
+7. Run a Windows build smoke test:
+   `flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host`.
+
+## Recommended Refactoring Direction
+
+- Decide whether bearer tokens can remain in `shared_preferences`; if not,
+  migrate session storage to platform-secure storage.
+- Add CI or a documented local verification workflow that runs analysis and a
+  Windows build smoke test with the latest stable Flutter SDK.