From 64ba5aea5d1b19a5ad1b287ca20685850c221454 Mon Sep 17 00:00:00 2001
From: Rene Luria <rene.luria@infomaniak.com>
Date: Thu, 9 Jul 2026 16:07:30 +0200
Subject: [PATCH] docs: add AGENTS.md with build commands, architecture, and
 conventions

---
 AGENTS.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9f3e976
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,82 @@
+# AGENTS.md
+
+## Project
+
+MyIce — Kotlin Multiplatform ice hockey schedule/convocation viewer (Android, iOS, Desktop).
+Port of the Flutter app at `~/work/gitea.parano.ch/herel/myice/myice_mobile/`.
+
+## Build Commands
+
+```bash
+# Compile (desktop)
+./gradlew composeApp:compileKotlinDesktop
+
+# Run desktop app
+./gradlew composeApp:run
+
+# Tests (desktop target — KMP has no commonTest task)
+./gradlew composeApp:desktopTest
+
+# Android debug APK
+./gradlew composeApp:assembleDebug
+
+# Android release APK (requires keystore.properties at project root)
+./gradlew composeApp:assembleRelease
+
+# macOS DMG
+./gradlew composeApp:packageDistributionForCurrentOS
+```
+
+## Lint / Typecheck
+
+There is no separate lint task. Compilation is the type check:
+
+```bash
+./gradlew composeApp:compileKotlinDesktop
+```
+
+## Tech Stack
+
+- Kotlin 2.3.20, Compose Multiplatform 1.11.1, Material 3
+- Ktor 3.5.1 (CIO on Android/Desktop, Darwin on iOS)
+- kotlinx.serialization 1.11.0
+- multiplatform-settings 1.3.0
+- lifecycle-viewmodel-compose 2.10.0
+- Gradle 9.5.1, AGP 8.13.2
+
+## Architecture
+
+Layered: `models → network → cache → filter → viewmodel → ui`
+
+- **commonMain**: all shared code (models, networking, caching, filtering, viewmodels, UI)
+- **androidMain**: Android OAuth (Custom Tabs), MainActivity, CIO engine
+- **iosMain**: iOS OAuth (ASWebAuthenticationSession), MainViewController, Darwin engine
+- **desktopMain**: Desktop OAuth (local HTTP server), Main.kt, CIO engine
+
+Package: `ch.parano.myice`
+
+## Conventions
+
+- Single `composeApp` module, shared UI approach (not per-platform UI)
+- French UI strings (matching the Flutter app)
+- TDD: write tests in `commonTest`, run via `desktopTest` target
+- `expect/actual` for platform-specific code (HttpClient engine, OAuth)
+- No comments in code unless explicitly requested
+- Follow existing file structure: one class per file, organized by layer
+
+## Backend
+
+API at `https://myice.parano.ch` (hardcoded in `network/ApiConfig.kt`).
+Endpoints: `/login`, `/userinfo`, `/accounts`, `/schedule?account=`, `/game/{id}?account=`
+
+## Secrets
+
+- `keystore.properties` and `*.keystore` are gitignored — never commit
+- OAuth tokens stored via multiplatform-settings (plaintext, same as Flutter app)
+
+## Known Limitations
+
+- iOS `.xcodeproj` must be created manually in Xcode (Swift files exist in `iosApp/`)
+- ViewModels use `remember{}` instead of `viewModel()` (state lost on Android rotation)
+- No URL-decoding in token parser (JWT tokens don't need it)
+- `AuthViewModel.init()` logs out on any network error, not just 401