docs: Add basic AI guidelines and documentation

2026-06-18 23:51:07 +04:00
parent 2bc54f1cd7
commit 0363e915ee
4 changed files with 333 additions and 10 deletions
@@ -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.