# 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.