docs: Add basic AI guidelines and documentation

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.