Update README with Maven installation instructions and auth mode guidance (#8)

Co-authored-by: Anthony Spriggs <perspectiveva@gmail.com>
Co-authored-by: Omer Azmon <omer.azmon@id.me>
Co-authored-by: Josh Harris <harrisjb@users.noreply.github.com>

Author: 4 people

README.md

@@ -10,24 +10,53 @@ Android SDK for integrating ID.me community verification into your app via Chrom
 
 ## Installation
 
-### Gradle
+### Maven (GitHub Packages)
 
-Add the SDK module as a dependency in your app's `build.gradle.kts`:
+The SDK is published to GitHub Packages at:
+
+```
+https://maven.pkg.github.com/IDme/android-auth-sample-code
+```
+
+**Step 1:** Generate a GitHub personal access token with `read:packages` scope at https://github.com/settings/tokens.
+
+**Step 2:** Add your GitHub credentials to `local.properties` in your project root (do not commit this file):
+
+```
+gpr.user=YOUR_GITHUB_USERNAME
+gpr.key=YOUR_GITHUB_PAT
+```
+
+**Step 3:** Add the GitHub Packages repository to your project's `settings.gradle.kts`:
 
 ```kotlin
-dependencies {
-    implementation(project(":sdk"))
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        maven {
+            url = uri("https://maven.pkg.github.com/IDme/android-auth-sample-code")
+            credentials {
+                val localProps = java.util.Properties()
+                localProps.load(java.io.FileInputStream(rootProject.projectDir.resolve("local.properties")))
+                username = localProps["gpr.user"] as String?
+                password = localProps["gpr.key"] as String?
+            }
+        }
+    }
 }
 ```
 
-Or if published to a Maven repository:
+**Step 4:** Add the dependency to your app's `build.gradle.kts`:
 
 ```kotlin
 dependencies {
     implementation("com.idmelabs.auth:android-auth-sample-code:1.0.8")
 }
 ```
 
+> **Note:** The package URL `https://maven.pkg.github.com/IDme/android-auth-sample-code` returns a 404 when accessed in a browser without authentication. This is expected — GitHub uses 404 (rather than 401) to protect package visibility. The URL works correctly when Gradle makes authenticated requests using your token.
+
 ## Quick Start
 
 ### 1. Configure the SDK
@@ -161,11 +190,13 @@ idme.logout()
 
 ### Auth Modes
 
+For mobile app integrations, use `OAUTH_PKCE`. This is the only mode that returns the full attributes payload including `status` and subgroup data (e.g. military verification status). Do not use `OIDC` mode — it routes through the OpenID Connect userinfo endpoint which returns only standard claims (`email`, `fname`, `lname`, `uuid`, etc.) and does not include `status` or subgroup data.
+
 | Mode | Description |
 |---|---|
-| `OAUTH_PKCE` | **Recommended.** OAuth 2.0 Authorization Code with PKCE. No client secret sent to authorize endpoint. |
-| `OAUTH` | Standard OAuth 2.0 Authorization Code. Requires `clientSecret`. |
-| `OIDC` | OpenID Connect. Returns an ID token with JWT signature validation against ID.me's JWKS. |
+| `OAUTH_PKCE` | **Required for mobile apps.** OAuth 2.0 Authorization Code with PKCE. No client secret needed. Returns full attributes and `status` payload. |
+| `OAUTH` | Standard OAuth 2.0 Authorization Code. Requires `clientSecret`. Server-side flows only. Not for mobile apps. |
+| `OIDC` | OpenID Connect. Does **not** return `status` or subgroup data. Not recommended for this integration. |
 
 ### Verification Types