docs: fix version mismatches, connection states, config types, broken links, add llms.txt + COMPATIBILITY.md

- Fix min SDK: 24 -> 26 (Android 8.0)
- Fix Kotlin: 2.0+ -> 1.9.22
- Fix Compose BOM: 2024.12+ -> 2024.02.00
- Fix connection states enum: replace 5 wrong names with 8 actual states
- Fix baseUrl type: java.net.URL -> String, fix casing (baseURL -> baseUrl)
- Fix deviceIdProvider naming (was deviceIDProvider)
- Add missing config fields: preferredLocalesProvider, functionPacks
- Remove nonexistent pendingToolCall from Runtime API table
- Add 7 missing runtime state flows
- Fix KSP example return type: Any -> Any?
- Remove incorrect ProGuard rule (**_ResolveKitAdapter)
- Fix CHANGELOG.md broken links (restored missing subject nouns)
- Fix AGENTS.md broken markdown links (14 link placeholders)
- Fix CONTRIBUTING.md hardcoded macOS path
- Create llms.txt for AI agent discovery
- Create COMPATIBILITY.md with SDK/backend version matrix

Author: Hermes Agent

AGENTS.md

@@ -11,30 +11,27 @@ This file is the **table of contents** for coding agents. Keep it short, stable,
 
 ## First Read
 
-1.  for module model and integration patterns.
-2.  for architecture and release knowledge.
-3.  for harness principles.
+1. [README.md](README.md) for module model and integration patterns.
+2. [CHANGELOG.md](CHANGELOG.md) for architecture and release knowledge.
+3. [CONTRIBUTING.md](CONTRIBUTING.md) for harness principles.
 
 ## Commands
 
-
-
 ## Source of Truth Layout
 
--  public SDK facade artifact.
--  shared types and contracts.
--  API + stream transport.
--  runtime and chat surfaces.
--  annotation API.
--  KSP processor.
--  reference app.
--  documentation entry point.
--  plan history and tech debt.
+- [sdk/](sdk/) public SDK facade artifact.
+- [core/](core/) shared types and contracts.
+- [networking/](networking/) API + stream transport.
+- [ui/](ui/) runtime and chat surfaces.
+- [authoring/](authoring/) annotation API.
+- [ksp/](ksp/) KSP processor.
+- [sample/](sample/) reference app.
+- [docs/INDEX.md](docs/INDEX.md) documentation entry point.
+- [AGENTS.md](AGENTS.md) plan history and tech debt.
 
 ## Guardrails
 
-- No secrets in repo (, signing keys, credentials).
+- No secrets in repo ([.env.example](.env.example), signing keys, credentials).
 - Maintain binary compatibility assumptions for public SDK APIs.
 - Prefer small dependency upgrades; coordinated sweeps for major versions.
-- Run  when changing docs structure.
-
+- Run `./gradlew test` when changing docs structure.

CHANGELOG.md

@@ -13,14 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compose chat view rendering in fragment hosts
 
 ### Changed
--  now auto-starts runtime on composition
--  defaults to auto-generated UUID if null
+- `ResolveKitChatView` now auto-starts runtime on composition
+- `deviceIdProvider` defaults to auto-generated UUID if null
 
 ### Added
--  for View-based app integration
--  KSP annotation for typed tool authoring
--  for custom JSON context injection
--  for per-session tool scoping
+- `ResolveKitChatActivity` for View-based app integration
+- `@ResolveKit` KSP annotation for typed tool authoring
+- `llmContextProvider` for custom JSON context injection
+- `availableFunctionNamesProvider` for per-session tool scoping
 - GitHub Packages + Maven Central publish pipeline
 - Sample app with working MainActivity + SampleFunctions
 - Unit tests for core, networking, and ui modules
@@ -29,9 +29,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Kotlin-first runtime for ResolveKit sessions
-- Jetpack Compose  component
--  for full-screen chat
-- KSP-based  annotation for tool functions
+- Jetpack Compose `ResolveKitChatView` component
+- `ResolveKitChatActivity` for full-screen chat
+- KSP-based `@ResolveKit` annotation for tool functions
 - Multi-module architecture (sdk, core, networking, ui, authoring, ksp)
 - HTTP/3-first session event stream
 - Reconnect with in-flight turn replay

COMPATIBILITY.md

@@ -0,0 +1,22 @@
+# ResolveKit Android SDK — Compatibility
+
+## SDK Version Compatibility
+
+| Android SDK | Backend | Kotlin | Compose BOM | Min SDK |
+| --- | --- | --- | --- | --- |
+| 1.0.x | 1.0.x | 1.9.22 | 2024.02.00 | 26 (Android 8.0) |
+
+## Dependencies
+
+| Library | Version |
+| --- | --- |
+| Kotlin | 1.9.22 |
+| Compose BOM | 2024.02.00 |
+| OkHttp | 4.12.0 |
+| Coroutines | 1.7.3 |
+| KSP | 1.9.22-1.0.17 |
+| Kotlinx Serialization | 1.6.3 |
+| Lifecycle | 2.10.0 |
+| Activity Compose | 1.8.2 |
+| Fragment KTX | 1.8.6 |
+| AGP | 8.7.3 |

CONTRIBUTING.md

@@ -19,7 +19,7 @@ resolvekit.apiKey=iaa_your_key_here
 
 You can also export `RESOLVEKIT_API_KEY` instead of writing it to `local.properties`.
 
-For local publishing credentials, copy [`.env.example`](/Users/t0405/Developer/resolvekit-android-sdk/.env.example) to `.env` and fill in the values you need. Use a base64-encoded private key in `SIGNING_KEY_BASE64`. Keep `.env` local only.
+For local publishing credentials, copy [.env.example](.env.example) to `.env` and fill in the values you need. Use a base64-encoded private key in `SIGNING_KEY_BASE64`. Keep `.env` local only.
 
 ## Validation
 

README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/resolve-kit/resolvekit-android-sdk/actions/workflows/android.yml/badge.svg)](https://github.com/resolve-kit/resolvekit-android-sdk/actions/workflows/android.yml)
 [![Maven Central](https://img.shields.io/maven-central/v/app.resolvekit/sdk.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/app.resolvekit/sdk)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Min SDK](https://img.shields.io/badge/minSDK-24-blue.svg)](https://developer.android.com/studio/releases/platforms)
+[![Min SDK](https://img.shields.io/badge/minSDK-26-blue.svg)](https://developer.android.com/studio/releases/platforms)
 
 Android SDK for embedding ResolveKit agent chat, tool calling, and host UI surfaces into Android apps.
 
@@ -33,13 +33,13 @@ The repository contains:
 
 | Requirement | Value |
 | --- | --- |
-| Min SDK | 24 (Android 7.0) |
+| Min SDK | 26 (Android 8.0) |
 | Target SDK | 36 |
 | JDK | 17 |
 | Android Studio | Ladybug+ |
 | Gradle | 8.9+ (wrapper included) |
-| Compose | BOM 2024.12+ |
-| Kotlin | 2.0+ |
+| Compose | BOM 2024.02.00 |
+| Kotlin | 1.9.22 |
 
 ## Installation
 
@@ -193,25 +193,27 @@ supportFragmentManager.beginTransaction()
 
 ```kotlin
 ResolveKitConfiguration(
-    baseURL: URL = URL("https://agent.example.com"),
+    baseUrl: String = "https://agent.example.com",
     apiKeyProvider: () -> String?,
-    deviceIDProvider: () -> String? = { null },
+    deviceIdProvider: () -> String? = { null },
     llmContextProvider: () -> JSONObject = { emptyMap() },
     availableFunctionNamesProvider: (() -> List<String>)? = null,
     localeProvider: (() -> String)? = null,
+    preferredLocalesProvider: (() -> List<String>)? = null,
     functions: List<AnyResolveKitFunction> = emptyList(),
+    functionPacks: List<ResolveKitFunctionPack> = emptyList(),
     context: Context
 )
 ```
 
-### `baseURL`
+### `baseUrl`
 
-**Type:** `URL` | **Required:** No | **Default:** `https://agent.example.com`
+**Type:** `String` | **Required:** No | **Default:** `https://agent.example.com`
 
 Base URL of the ResolveKit backend. Override only when self-hosting:
 
 ```kotlin
-baseURL = URL("https://your-backend.example.com")
+baseUrl = "https://your-backend.example.com"
 ```
 
 ### `apiKeyProvider`
@@ -224,14 +226,14 @@ Called at the start of each session. Return `null` or an empty string to block c
 apiKeyProvider = { SecureConfig.getApiKey() }
 ```
 
-### `deviceIDProvider`
+### `deviceIdProvider`
 
 **Type:** `() -> String?` | **Required:** No | **Default:** `{ null }`
 
 Stable device or user identifier used to correlate sessions across app launches. If `null` is returned, the SDK generates and persists a UUID automatically.
 
 ```kotlin
-deviceIDProvider = {
+deviceIdProvider = {
     val prefs = PreferenceManager.getDefaultSharedPreferences(context)
     prefs.getString("device_id", null) ?: run {
         val id = UUID.randomUUID().toString()
@@ -268,20 +270,29 @@ List of tool functions available to the agent.
 | `messages` | `StateFlow<List<ResolveKitChatMessage>>` | Chat transcript in chronological order |
 | `connectionState` | `StateFlow<ResolveKitConnectionState>` | Current session-stream connection phase |
 | `isTurnInProgress` | `StateFlow<Boolean>` | True while the agent is processing a turn |
-| `pendingToolCall` | `StateFlow<ResolveKitPendingToolCall?>` | Current active tool call awaiting approval |
 | `toolCallChecklist` | `StateFlow<List<ToolCallChecklistItem>>` | Live checklist of tool calls in current batch |
 | `toolCallBatchState` | `StateFlow<ResolveKitToolCallBatchState>` | Aggregate approval state of current batch |
+| `toolCallBatches` | `StateFlow<List<ToolCallChecklistBatch>>` | Historical tool call batches |
+| `lastError` | `StateFlow<String?>` | Last error message |
+| `chatTitle` | `StateFlow<String>` | Chat window title |
+| `messagePlaceholder` | `StateFlow<String>` | Input placeholder text |
+| `appearanceMode` | `StateFlow<ResolveKitAppearanceMode>` | Appearance mode |
+| `currentLocale` | `StateFlow<String>` | Current session locale |
+| `chatTheme` | `StateFlow<ChatTheme?>` | Active chat theme |
 | `executionLog` | `StateFlow<List<String>>` | Debug log of runtime lifecycle events |
 
 ### Connection States
 
 | State | Description |
 | --- | --- |
-| `Disconnected` | Not connected (initial state) |
-| `Connecting` | Establishing WebSocket connection |
-| `Connected` | Session established, ready for chat |
-| `Reconnecting` | Connection lost, attempting reconnect |
-| `Error` | Connection failed with error |
+| `IDLE` | Not connected (initial state) |
+| `REGISTERING` | Registering device with backend |
+| `CONNECTING` | Establishing WebSocket connection |
+| `ACTIVE` | Session established, ready for chat |
+| `RECONNECTING` | Connection lost, attempting reconnect |
+| `RECONNECTED` | Successfully reconnected after loss |
+| `FAILED` | Connection failed with error |
+| `BLOCKED` | Connection blocked (e.g., invalid API key) |
 
 ## Defining Tools
 
@@ -314,7 +325,7 @@ object GetCurrentTime : AnyResolveKitFunction {
     requiresApproval = false
 )
 class EchoMessage(private val message: String) : ResolveKitFunction {
-    override suspend fun perform(): Any = message
+    override suspend fun perform(): Any? = message
 }
 ```
 
@@ -346,7 +357,6 @@ Add these rules to your app's `proguard-rules.pro` to prevent obfuscation of Res
 
 # KSP-generated adapters
 -keep class **ResolveKitAdapter { *; }
--keep class **_ResolveKitAdapter { *; }
 
 # JSON serialization
 -keepclassmembers class * {
@@ -442,7 +452,7 @@ GitHub Actions publishing is defined in `.github/workflows/publish.yml`. GitHub
 
 ### Connection fails with 401
 - Verify your API key starts with `iaa_`
-- Check that `baseURL` points to a running ResolveKit backend
+- Check that `baseUrl` points to a running ResolveKit backend
 - Ensure the backend has an app configured for your API key
 
 ### Tool calls not appearing in chat

llms.txt

@@ -0,0 +1,14 @@
+---
+title: "ResolveKit Android SDK"
+---
+ResolveKit Android SDK - Embedded AI resolution framework for Android.
+
+Key files:
+- README.md: Integration guide and API reference
+- CHANGELOG.md: Version history
+- ui/src/main/kotlin/app/resolvekit/ui/ResolveKitConfiguration.kt: Configuration
+- ui/src/main/kotlin/app/resolvekit/ui/ResolveKitRuntime.kt: Main runtime
+- authoring/src/main/kotlin/app/resolvekit/authoring/ResolveKit.kt: @ResolveKit annotation
+
+Quick start: Add Gradle dependency, use @ResolveKit annotation on functions, present ResolveKitChat composable.
+Requires: Android 8.0 (API 26)+, Kotlin 1.9.22, Compose BOM 2024.02.00