Add AGENTS guide for app-platform contributors

Document the repo structure, architecture rules, authoritative docs, and platform-specific run/test commands for the sample, recipes, and starter apps.

An AGENTS.md file gives contributors and coding agents a single entry point for understanding how this repository is organized, where the real documentation lives, and how to execute common workflows without rediscovering them from build files and CI.

Author: vRallev

AGENTS.md

@@ -0,0 +1,283 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is the Amazon App Platform: a Kotlin Multiplatform application framework plus example applications and a starter blueprint. The core concepts are documented in [`docs/`](docs/) and implemented across reusable library modules plus a few app entrypoints.
+
+Start here before changing code:
+
+- `README.md`
+- `docs/index.md`
+- `docs/setup.md`
+- `docs/module-structure.md`
+- `docs/di.md`
+- `docs/presenter.md`
+- `docs/renderer.md`
+- `docs/template.md`
+- `docs/testing.md`
+- `settings.gradle`
+- `buildSrc/src/main/kotlin/software/amazon/app/platform/gradle/buildsrc/`
+
+`mkdocs.yml` is the docs site manifest. The Pages workflow builds Wasm artifacts for `:sample:app` and `:recipes:app` and copies them into `docs/web/` before publishing.
+
+## Repo Shape
+
+Important top-level areas:
+
+- `gradle-plugin/`: the published `software.amazon.app.platform` Gradle plugin.
+- `buildSrc/`: repo-local convention plugins used by this repository’s own modules. This is where platform targets, emulator config, desktop packaging, and Wasm defaults are defined.
+- `docs/`: framework documentation. Treat this as the authoritative product docs.
+- `sample/`: the main sample app. This is the best place to study end-to-end usage of scopes, DI, presenters, renderers, templates, fakes, and robots.
+- `recipes/`: a second example app plus reusable “recipe” patterns, including the separate `recipesIosApp` SwiftUI/Xcode wrapper.
+- `blueprints/starter/`: a standalone starter app template with its own Gradle wrapper, version catalog, and README.
+
+Core framework module families:
+
+- `scope`, `di-common`
+- `presenter`, `presenter-molecule`
+- `renderer`, `renderer-android-view`, `renderer-compose-multiplatform`
+- `robot`, `robot-compose-multiplatform`, `robot-internal`
+- `kotlin-inject`, `kotlin-inject-extensions`
+- `metro`, `metro-extensions`
+- `ksp-common`
+
+## Architecture Rules
+
+The most important repo rule is the module structure documented in `docs/module-structure.md`.
+
+- `:public` modules expose reusable APIs and shared code.
+- `:impl` modules contain concrete implementations.
+- `:testing` modules hold shared fakes and test helpers.
+- `:*-robots` modules hold shared UI robots.
+- `:app` modules are the only modules allowed to depend on `:impl` modules.
+
+Do not introduce a dependency from a non-`:app` module to an `:impl` module. The build enforces this via `checkModuleStructureDependencies`.
+
+The framework’s architectural flow is:
+
+1. `Scope` and DI assemble objects for a lifecycle boundary.
+2. `MoleculePresenter` implementations produce models.
+3. App-specific `Template` presenters wrap the root model tree.
+4. `RendererFactory` resolves platform renderers for those models.
+5. Thin platform entrypoints bootstrap the root scope and start rendering.
+
+Representative entrypoints:
+
+- Android: `sample/app/src/androidMain/.../AndroidApplication.kt`, `MainActivity.kt`
+- iOS: `sample/app/src/iosMain/.../MainViewController.kt`, `sample/iosApp/`
+- Desktop: `sample/app/src/desktopMain/.../Main.kt`, `DesktopApp.kt`
+- Wasm: `sample/app/src/wasmJsMain/.../Main.kt`
+
+## Toolchain
+
+Local development should match CI as closely as possible. These versions live in `gradle/libs.versions.toml`.
+
+Expected warning: Gradle prints a warning that configuration-on-demand is not supported for Wasm targets. This is noisy but currently normal in this repo.
+
+## Run The Apps
+
+There are three app-style entrypoints to care about:
+
+- `:sample:app`: main sample app inside the root build.
+- `:recipes:app`: recipe/demo app inside the root build.
+- `blueprints/starter`: standalone starter app; run commands from inside that directory or use its own `./gradlew`.
+
+### Android
+
+Install the debug APK onto a connected device or emulator:
+
+```bash
+./gradlew :sample:app:installDebug
+./gradlew :recipes:app:installDebug
+```
+
+For the standalone starter:
+
+```bash
+cd blueprints/starter
+./gradlew :app:installDebug
+```
+
+`buildSrc/.../BaseAndroidPlugin.kt` configures managed emulator tests with a local device named `emulator` using a Pixel 3 / API 30 `aosp-atd` image.
+
+### iOS
+
+Sample app:
+
+```bash
+open sample/iosApp/iosApp.xcodeproj
+```
+
+Recipe app:
+
+```bash
+open recipes/recipesIosApp/recipesIosApp.xcodeproj
+```
+
+The Xcode projects include a shell build phase that calls Gradle:
+
+- `:sample:app:embedAndSignAppleFrameworkForXcode`
+- `:recipes:app:embedAndSignAppleFrameworkForXcode`
+
+If you only want to build the Kotlin framework without opening Xcode:
+
+```bash
+./gradlew :sample:app:linkDebugFrameworkIosSimulatorArm64
+./gradlew :recipes:app:linkDebugFrameworkIosSimulatorArm64
+```
+
+CI builds the sample iOS wrapper with `xcodebuild -project sample/iosApp/iosApp.xcodeproj -scheme iosApp ... -destination id=<simulator-id>`. Use `xcrun simctl list devices` to pick a simulator if you need a pure CLI invocation.
+
+### Desktop
+
+Run the desktop Compose app:
+
+```bash
+./gradlew :sample:app:run
+./gradlew :recipes:app:run
+```
+
+Starter blueprint:
+
+```bash
+cd blueprints/starter
+./gradlew :app:run
+```
+
+Desktop packaging tasks such as `packageDmg`, `packageDeb`, and `packageMsi` are available on app modules.
+
+### Wasm
+
+Development server:
+
+```bash
+./gradlew :sample:app:wasmJsBrowserDevelopmentRun
+./gradlew :recipes:app:wasmJsBrowserDevelopmentRun
+```
+
+Production bundle:
+
+```bash
+./gradlew :sample:app:wasmJsBrowserDistribution
+./gradlew :recipes:app:wasmJsBrowserDistribution
+```
+
+Starter blueprint:
+
+```bash
+cd blueprints/starter
+./gradlew :app:wasmJsBrowserDevelopmentRun
+```
+
+After a production Wasm build, serve the generated files from:
+
+- `sample/app/build/dist/wasmJs/productionExecutable/`
+- `recipes/app/build/dist/wasmJs/productionExecutable/`
+
+The starter README suggests `npx http-server` from the production output directory.
+
+## Run The Tests
+
+### Repo-wide CI-style checks
+
+These are the main root-level quality gates used by GitHub Actions:
+
+```bash
+./gradlew testDebugUnitTest
+./gradlew iosSimulatorArm64Test -Pkotlin.incremental.native=true
+./gradlew desktopTest
+./gradlew linuxX64Test
+./gradlew wasmJsTest
+./gradlew apiCheck
+./gradlew ktfmtCheck
+./gradlew detekt
+./gradlew lint
+./gradlew checkModuleStructureDependencies
+```
+
+### Sample app tests by platform
+
+Android instrumented UI tests:
+
+```bash
+./gradlew :sample:app:emulatorCheck
+```
+
+Or against a manually started device:
+
+```bash
+./gradlew :sample:app:connectedDebugAndroidTest
+```
+
+Desktop UI tests:
+
+```bash
+./gradlew :sample:app:desktopTest
+```
+
+Android unit tests:
+
+```bash
+./gradlew :sample:app:testDebugUnitTest
+```
+
+iOS simulator tests:
+
+```bash
+./gradlew :sample:app:iosSimulatorArm64Test -Pkotlin.incremental.native=true
+```
+
+All sample app target tests:
+
+```bash
+./gradlew :sample:app:allTests
+```
+
+### Where tests live
+
+- Android UI tests: `sample/app/src/androidInstrumentedTest/`
+- Desktop UI tests: `sample/app/src/desktopTest/`
+- Shared unit tests: `sample/*/src/commonTest/`
+- Shared fakes: `sample/user/testing/`
+- Shared robots: `sample/login/impl-robots/`, `sample/user/impl-robots/`
+
+## Current Test Reality
+
+As of this checkout:
+
+- `:sample:app:desktopTest` runs successfully.
+- `:sample:app:testDebugUnitTest` succeeds but currently has `NO-SOURCE`.
+- `:sample:app:iosSimulatorArm64Test -Pkotlin.incremental.native=true` succeeds but is currently skipped because `sample/app` has no iOS test sources.
+- Android UI coverage for the sample app is in `androidInstrumentedTest` and is exercised through `emulatorCheck`/`connectedDebugAndroidTest`.
+
+## Wasm Lockfile Caveat
+
+Wasm tasks are currently strict about the committed Yarn lockfile under `kotlin-js-store/wasm/yarn.lock`.
+
+If a Wasm task fails with:
+
+```text
+Execution failed for task ':kotlinWasmStoreYarnLock'.
+Lock file was changed. Run the `kotlinWasmUpgradeYarnLock` task to actualize lock file
+```
+
+then the generated `build/wasm/yarn.lock` does not match the committed lock. In this checkout, both `:sample:app:wasmJsTest` and `:sample:app:wasmJsBrowserDistribution` hit that failure.
+
+Treat `kotlinWasmUpgradeYarnLock` as an intentional dependency update step, not a routine run command. If you change Wasm/npm dependencies on purpose, update and review `kotlin-js-store/wasm/yarn.lock` in the same change.
+
+## Docs Workflow
+
+To work on docs locally:
+
+```bash
+cp CHANGELOG.md docs/changelog.md
+pip install mkdocs-material "mkdocs-material[imaging]"
+mkdocs serve
+```
+
+When changing framework behavior, update both:
+
+- the relevant `docs/*.md` page
+- the sample and/or starter code that demonstrates that behavior
+
+If a change affects how consumers start a new project, also update `blueprints/starter/README.md`.