reis-mobile 0.3.6 → 0.5.0

package/skills/mobile-android/references/media/media3-cast-integration/references/android/media/media3/cast/index.md

@@ -0,0 +1,21 @@
+The Media3 [`cast`](https://developer.android.com/reference/androidx/media3/cast/package-summary) module extends your media playback experience to
+Cast devices. It lets your app cast content to [compatible devices](https://developer.android.com/media/media3/cast/create-castplayer#get-device),
+such as TVs and speakers. The [sender](https://developers.google.com/cast/glossary#sender) app acts as a remote controller for media
+playback on the [receiver](https://developers.google.com/cast/glossary#receiver) device. This module integrates with the [Jetpack
+Media3](https://developer.android.com/guide/topics/media/media3) library, so you can use the same `Player` interface and UI
+components for both local and remote playback.
+
+## Media3 CastPlayer
+
+The `CastPlayer` is a media player API included in Media3 that supports both
+local and remote media playback. It implements the `Player` interface to manage
+playback, simplifying the integration of casting into your media experience.
+
+[Go to Media3 CastPlayer](https://developer.android.com/media/media3/cast/create-castplayer)
+
+## Other Cast integrations
+
+The Cast SDK overview explains how to integrate Cast with other platforms, such
+as building a receiver app or integrating with the web sender SDK.
+
+[Explore Cast SDK](https://developers.google.com/cast/docs/developers)

package/skills/mobile-android/references/media.md

@@ -0,0 +1,10 @@
+# Android: Camera and media
+
+CameraX and Media3 Cast.
+
+| Guide | What it covers |
+|---|---|
+| [camerax](media/camerax/GUIDE.md) | Provide technical guidance for Android camera development with CameraX. |
+| [media3-cast-integration](media/media3-cast-integration/GUIDE.md) | Implements Google Cast support in Android apps using Jetpack Media3. |
+
+Each guide lives in its own folder with its references and scripts. Relative paths in a guide — and `<repo_root>` where a guide uses it — refer to that guide's folder.

package/skills/mobile-android/references/on-device-ai/appfunctions/GUIDE.md

@@ -0,0 +1,51 @@
+> Adapted from the `appfunctions` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
+
+Analyzes Android apps to identify key user workflows for AppFunctions such as
+creating a note, playing media, or sending an automated or AI agent triggered
+message, voice commands, or system shortcuts, without needing to open the app
+UI.
+
+Generates Kotlin code to expose these workflows to the Android system,
+allowing agents to discover and execute them on-device.
+
+Also refines KDoc documentation to ensure AI agents correctly
+understand and use the provided functionality.
+
+## Prerequisites
+
+The app must **`targetSdk 36`** or newer and use **`compileSdk 37`** or newer as
+AppFunctions, part of the Android platform API, are available from Android 16
+onwards.
+Always use the Jetpack library because it handles backward compatibility.
+
+## Workflows
+
+This skill enables the caller to discover features that will be provided to
+system agents, implement these with AppFunctions, improve function description
+for agents, and use ADB commands for local evaluation and testing.
+
+The full AppFunction development flow consists of these four steps:
+
+- *[Step 1: Discovery](references/feature-discovery-analysis.md)*: Analyze Android codebases to identify and recommend potential AppFunctions. Use this step when a user asks to "discover AppFunctions," "find features for AI," or "analyze my app for agentic tools."
+- *[Step 2: Implementation and configuration](references/implementation-configuration.md)*: Generate Kotlin implementations of AppFunctions, manage system-wide configuration, and configure build dependencies. Use this step when a user asks to "implement AppFunctions," "set up the AppFunctions framework," or "configure Hilt for AppFunctions."
+- *[Step 3: KDoc refinement](references/kdoc-refinement-optimization.md)*: Optimize AppFunction KDoc for AI agents and Model Context Protocol. If a user asks to "write KDoc", "optimize for MCP", or "refactor tool descriptions for LLMs", use this step.
+- *[Step 4: Testing and debugging](references/adb-interaction-testing.md)*: Provide commands to interact with AppFunctions using ADB for testing and debugging. If a user wants to "list app functions", "invoke an app function", or "verify app function registration" on a device, use this step.
+
+If users request a subset of steps, you must encourage them to use all steps.
+
+If they apply, you must load the following references:
+
+- *[Context and terminology](references/context.md)*: Defines the ubiquitous language, architecture definitions, and design patterns across the AppFunctions skill suite. Load when you need to understand core architecture terminology or check the distinctions between modern and legacy AppFunctions APIs.
+- *[Migration to service entry point](references/migrate-to-service-entry-point.md)* : Documents the systematic procedure for migrating Android applications using AppFunctions versions 1.0.0-alpha09 and lower to `AppFunctionServiceEntryPoint` architecture introduced in version 1.0.0-alpha10. Load when a user asks to migrate or upgrade existing AppFunctions code, or when you encounter legacy `AppFunctionConfiguration.Provider` implementations.
+
+## Critical constraints
+
+- **Modular consistency**: You must refine KDocs immediately after you generate AppFunction implementations.
+- **Security**: Don't expose sensitive data or run destructive actions without user confirmation.
+
+## Troubleshooting
+
+- If you encounter build-time errors such as Kotlin Symbol Processing (KSP) issues, see [Implementation and configuration](references/implementation-configuration.md).
+- If you encounter runtime errors such as missing services or execution failures, see [Testing and debugging](references/adb-interaction-testing.md).
+- If you need architecture definitions and vocabulary, see [Context and terminology](references/context.md).
+- If you encounter issues when upgrading legacy configurations, see [Migration to service entry point](references/migrate-to-service-entry-point.md).

package/skills/mobile-android/references/on-device-ai/appfunctions/references/adb-interaction-testing.md

@@ -0,0 +1,95 @@
+Provides commands to interact with AppFunctions on a connected device or
+emulator using ADB for AppFunction testing and debugging.
+
+## Instructions
+
+### Scenario 1: List app functions
+
+Use this scenario when you want to see which app functions are registered on
+the device.
+
+1. **List all functions** : To view all registered app functions in JSON format, run `adb shell cmd app_function list-app-functions`.
+2. **Filter by package** : To view functions for a specific package, pipe the output to `grep` or a JSON tool: `adb shell cmd app_function
+   list-app-functions | grep <package_name>`.
+
+### Scenario 2: Invoke app functions
+
+If you want to test the execution of an app function, use this scenario.
+
+1. **Analyze description** : Before invoking, you must read the `description` field for the function in the `list-app-functions` output. This often contains critical usage constraints, required workflows, or disambiguation rules.
+2. **Follow constraints**: Follow all instructions in the description, such as asking the user to disambiguate or calling another tool first.
+3. **Format parameters** : Format the `--parameters` argument as a valid JSON string that represents the function's input arguments.
+4. **Execute function** : Use `adb shell cmd app_function execute-app-function
+   --package <PACKAGE_NAME> --function <SERVICE_CLASS_NAME#FUNCTION_NAME>
+   --parameters '<PARAMETERS_JSON>'`.
+5. **Handle response** : The command returns the result as a JSON string. To get brief YAML output, use `--brief-yaml`.
+
+### Scenario 3: Manage function state
+
+If you need to enable or disable an app function for testing, use this scenario.
+
+1. **Set enabled state** : Use `adb shell cmd app_function set-enabled
+   --package <PACKAGE_NAME>
+   --function <SERVICE_CLASS_NAME#FUNCTION_NAME>
+   --state <enable|disable|default>`.
+
+## Critical constraints
+
+### Follow metadata descriptions
+
+**Mandatory** : The `description` field in the app function metadata is a set of
+instructions for the LLM. If a description says to "disambiguate with the user"
+or "call another function first," you must perform those steps before execution.
+
+### JSON escaping
+
+**Critical** : When passing JSON using `adb shell`, always wrap the JSON string
+in single quotes to prevent the shell from interpreting special characters or
+spaces. Example: `--parameters '{"key": "value"}'`.
+
+### Device availability
+
+The `app_function` service must be available on the device. If `cmd: Can't find
+service: app_function` is returned, the device doesn't support this feature.
+
+## Examples
+
+### Example 1: Verify app function service availability on connected device
+
+    adb shell cmd app_function help
+
+If executing the preceding command returns a help page, use the commands and
+parameters provided to guide the ADB interaction testing tool interactions.
+
+### Example 2: List all registered app functions
+
+     adb shell cmd app_function list-app-functions
+
+### Example 3: Execute a "send message" function
+
+     adb shell cmd app_function execute-app-function \
+     --package com.example.messaging \
+     --function
+    'com.example.messaging.appfunctions.MessagingAppFunctionService#sendMessage' \
+     --parameters '{"recipient": "Alice", "message": "Hello!"}'
+
+### Example 4: Disable a specific function
+
+     adb shell cmd app_function set-enabled --package com.example.app \
+     --function 'com.example.app.appfunctions.SomeAppFunctionService#someFunction'
+    --state disable
+
+## Troubleshooting
+
+### Error: "Unknown command"
+
+**Cause**: You are likely using an older version of the instructions.
+
+**Solution**: Look up supported commands using "Example 1".
+
+### Error: "Function not found"
+
+**Cause**: The function ID or package name is incorrect.
+
+**Solution** : Run `list-app-functions` and search for the relevant identifiers
+in the JSON output.

package/skills/mobile-android/references/on-device-ai/appfunctions/references/context.md

@@ -0,0 +1,26 @@
+Defines the ubiquitous language for the Android AppFunctions skill suite.
+
+## Architecture and versioning
+
+`AppFunctionServiceEntryPoint` API:
+This compile-time AppFunctions architecture was introduced in version
+1.0.0-alpha10. You annotate a wrapper service extending
+`AppFunctionService` with `@AppFunctionServiceEntryPoint`. KSP then generates
+XML metadata and routes services at compile time.
+
+Legacy manual provider API:
+This deprecated AppFunctions architecture applies to version
+1.0.0-alpha09 and earlier. Applications implement
+`AppFunctionConfiguration.Provider` on the `Application` class. Methods
+require `AppFunctionContext` as the first parameter. Projects depend on
+a standalone `appfunctions-service` library.
+
+## Patterns
+
+Service entry point pattern:
+Version 1.0.0-alpha10 introduced this architectural pattern. You
+declare `@AppFunction` methods directly inside an abstract class extending
+`AppFunctionService`. This class uses `@AppFunctionServiceEntryPoint` and
+`@AndroidEntryPoint` annotations. These annotations let you inject data
+sources or repositories directly, without an intermediate business logic
+delegation layer.

package/skills/mobile-android/references/on-device-ai/appfunctions/references/feature-discovery-analysis.md

@@ -0,0 +1,71 @@
+Analyzes Android codebases to identify and recommend high-value AppFunctions.
+
+## Instructions
+
+### Discover features
+
+1. **Analyze manifest and entry points** : Scan `AndroidManifest.xml` and Activity, Fragment, and Service classes to identify core user journeys, for example, search, create, or share.
+2. **Identify atomic tasks**: Look for methods or logic that represent distinct, self-contained user outcomes.
+3. **Evaluate AI value**: Prioritize tasks that are frequently used or difficult to navigate using touch UI, but instead be expressed using voice or text, for example "Remind me to call Alice when I get home."
+4. **Recommend and justify**: List recommendations with a rationale. Focus on how an AI assistant adds value, such as efficiency, hands-free use, or multi-step automation.
+
+## Critical constraints
+
+### Tool-first thinking
+
+Avoid recommending functions that are purely informational or redundant with
+existing system actions. Focus on "mutations" (writing data) or "rich queries"
+(finding specific entities).
+
+### Security and privacy
+
+Don't recommend exposing functions that handle raw credentials, financial
+secrets, or irreversible destructive actions without explicit user confirmation
+steps.
+
+## Examples
+
+### Example 1: Media app discovery
+
+**Recommended AppFunction** : `playArtistRadio`
+
+**Rationale**: Lets you start a personalized music stream using a voice
+command, bypassing several layers of navigation in the "Search" and "Artist"
+menus.
+
+**Input required** : `artistName` as a `String`.
+
+### Example 2: Chat app contact discovery
+
+**Recommended AppFunction** : `searchContacts`
+
+**Rationale** : Serves as a "rich query" to resolve a human-readable contact
+name, email, or chat group to a unique identifier (`endpointValue`), which is a
+prerequisite before executing actions like sending messages or
+initiating calls. Also allows retrieving recently contacted entities when given
+a blank query.
+
+**Input required** : Query as a `String`, and Filter Type as a `String`
+constrained to `"INDIVIDUAL"` or `"GROUP"`.
+
+### Example 3: Chat app message sending
+
+**Recommended AppFunction** : `send`
+
+**Rationale**: This mutation function lets you send text messages and
+optional image attachments to a contact or group using natural language
+commands, for example, "Tell Alice I'm running 5 minutes late." This
+eliminates multi-step UI navigation across contact lists and conversation
+threads.
+
+**Input required** : Endpoint Value as a `String`, Message Body as a `String`,
+and Image URIs as an optional `List` of URIs.
+
+### Example 4: Chat app voice calling
+
+**Recommended AppFunction** : `makeCall`
+
+**Rationale**: Lets you initiate voice calls hands-free to a contact or
+group using an AI agent without navigating the app's UI.
+
+**Input required** : `endpointValue` as a `String`.

package/skills/mobile-android/references/on-device-ai/appfunctions/references/implementation-configuration.md

@@ -0,0 +1,282 @@
+Specialized instructions for generating Kotlin implementations of AppFunctions,
+handling system-wide configuration, and managing build dependencies.
+
+## Instructions
+
+### Step 1: Configure Gradle dependencies and KSP
+
+Add the following to `build.gradle.kts`. App Functions requires the KSP (Kotlin
+Symbol Processing) plugin.
+
+1. **Version check** : Use library version `1.0.0-alpha10` or later from maven.google.com.
+
+
+```kotlin
+implementation(libs.androidx.appfunctions)
+ksp(libs.androidx.appfunctions.compiler)
+```
+
+<br />
+
+<br />
+
+<br />
+
+### Step 2: Set up app metadata XML
+
+Describe the app's capabilities to the LLM by defining
+`res/xml/app_metadata.xml`.
+
+
+```xml
+<AppFunctionAppMetadata xmlns:appfn="http://schemas.android.com/apk/androidx.appfunctions"
+    appfn:description="This app manages user tasks and reminders.
+    Operational Patterns:
+    - Use 'createTask' to add new tasks or reminders with titles and content.
+    Constraints:
+    - Title or content must be non-null when creating a task."
+    appfn:displayDescription="@string/user_visible_description" />
+```
+
+<br />
+
+Register the service and reference the app metadata in `AndroidManifest.xml`
+within the `<application>` tag:
+
+
+```xml
+<service
+    android:name="com.example.snippets.ai.TaskAppFunctionService"
+    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
+    android:exported="true"
+    tools:targetApi="36">
+    <property
+        android:name="android.app.appfunctions.schema"
+        android:value="app_functions_schema.xsd" />
+    <property
+        android:name="android.app.appfunctions.v2"
+        android:value="task_app_function_service.xml" />
+    <intent-filter>
+        <action android:name="android.app.appfunctions.AppFunctionService" />
+    </intent-filter>
+</service>
+<property
+    android:name="android.app.appfunctions.app_metadata"
+    android:resource="@xml/app_metadata" />
+```
+
+<br />
+
+### Step 3: Implement functions
+
+When generating Kotlin code for AppFunctions, you MUST adhere to these rules:
+
+1. **Annotations** :
+   - Annotate the function with `@AppFunction(isDescribedByKDoc = true)`.
+   - Annotate associated data classes with `@AppFunctionSerializable(isDescribedByKDoc = true)`.
+2. **Parameter strategy** :
+   - **Specificity**: Keep parameters specific. State objects must be unambiguous.
+   - **Optionality**: If a parameter isn't essential, make it optional with a default value.
+3. **Execution and threading** :
+   - Use `suspend` functions.
+   - To avoid blocking the Android UI thread, always run AppFunction implementations on a background dispatcher, such as `withContext(Dispatchers.IO)`.
+4. **Supported types** :
+   - **Primitives** : `Int`, `Long`, `Float`, `Double`, `Boolean`
+   - **Arrays** : `IntArray`, `LongArray`, `FloatArray`, `DoubleArray`, `BooleanArray`
+   - **Native types** : `String`, `PendingIntent`, `Uri`, `LocalTime`, `LocalDate`, `LocalDateTime`, `Instant`. Prefer using `LocalDateTime` or `Instant` for date and time fields.
+   - **Custom objects** : Classes annotated with `@AppFunctionSerializable`.
+   - **Collections** : `List` of any supported non-primitive type
+5. **Default values** :
+   - Use defaults that align with the type's empty state, such as `0` for `Int`, `null` for nullable objects, and `emptyList()` for `List`.
+6. **Error handling** :
+   - Throw subclasses of `androidx.appfunctions.AppFunctionException` to report errors to callers.
+7. **Security** :
+   - Don't expose highly sensitive user data, such as passwords or financial details.
+   - Don't expose irreversible destructive actions without confirmation steps.
+
+### Step 4: Set up dependency injection and service entry points
+
+In version 1.0.0-alpha10 and later, App Functions use the compile-time
+`@AppFunctionServiceEntryPoint` architecture. Create an abstract class extending
+`AppFunctionService` annotated with `@AppFunctionServiceEntryPoint`. KSP
+generates the concrete service class and XML schema.
+
+#### Recommended approach with Hilt
+
+Annotate your service with `@AndroidEntryPoint` and inject your data
+repositories or use cases using standard `@Inject internal lateinit var`:
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "ConfigAppFunctionServiceHeader",
+    appFunctionXmlFileName = "config_app_function_service_header",
+)
+abstract class BaseAppFunctionServiceHeader : AppFunctionService() {
+    @Inject internal lateinit var messageRepository: MessageRepository
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+#### Framework-agnostic approach with alternative dependency injection or service locators
+
+While Hilt is recommended, many Android applications implement AppFunctions with
+alternative dependency injection frameworks (like Koin, Anvil, or manual Service
+Locators). Because `AppFunctionService` inherits from Android
+`android.app.Service` (and therefore `Context`), you are able access your
+application's DI container directly through `applicationContext` in property
+getters or during service lifecycle execution:
+
+
+```kotlin
+@RequiresApi(36)
+@AppFunctionServiceEntryPoint(
+    serviceName = "ServiceLocatorConfigAppFunctionService",
+    appFunctionXmlFileName = "service_locator_config_app_function_service",
+)
+abstract class BaseAppFunctionServiceLocator : AppFunctionService() {
+    // Example using a manual Service Locator / Application container
+    private val messageRepository by lazy {
+        (applicationContext as AppFunctionApplication).appContainer.messageRepository
+    }
+    // Or with Koin / alternative DI locators:
+    // private val messageRepository: MessageRepository by inject()
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+### Step 5: Architectural cleanliness
+
+Don't attempt to make an `AppFunction` class or method OS-agnostic---App Functions are inherently part of the Android platform integration in `androidx.appfunctions`. For architectural cleanliness, use existing
+application functionality (such as existing repositories, use cases, or domain
+orchestrators) to execute the behavior within your `@AppFunction` methods rather
+than creating redundant abstraction layers around the OS service.
+
+<br />
+
+## Critical constraints
+
+### KSP compliance for serializables
+
+**Critical constraints** : For `@AppFunctionSerializable` data classes, KSP
+only extracts documentation if it's written as inline KDoc directly for each
+property definition. Don't use class-level `@param` or `@property` tags.
+
+### Package integrity
+
+Configuration APIs and the `@AppFunction` annotation are located in
+`androidx.appfunctions`.
+
+## Examples
+
+### Example: Serializable with inline KDoc
+
+
+```kotlin
+/** The parameter to create the task. */
+@AppFunctionSerializable(isDescribedByKDoc = true)
+data class CreateTaskParams(
+    /** The title of the task. */
+    val title: String?,
+    /** The content of the task. */
+    val content: String?,
+)
+
+/** The user-created task. */
+@AppFunctionSerializable(isDescribedByKDoc = true)
+data class Task(
+    /** The ID of the task. */
+    val id: String,
+    /** The title of the task. */
+    val title: String,
+    /** The content of the task. */
+    val content: String,
+)
+```
+
+<br />
+
+<br />
+
+### Example: Implementation detail
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "TaskAppFunctionService",
+    appFunctionXmlFileName = "task_app_function_service",
+)
+abstract class BaseTaskAppFunctionService : AppFunctionService() {
+    @Inject internal lateinit var taskRepository: TaskRepository
+
+    /**
+     * Creates a task based on [createTaskParams].
+     *
+     * @param createTaskParams The parameter to describe how to create the task.
+     */
+    @AppFunction(isDescribedByKDoc = true)
+    suspend fun createTask(
+        createTaskParams: CreateTaskParams,
+    ): Task = withContext(Dispatchers.IO) {
+        // Developers can use predefined exceptions to let the agent know
+        // why it failed.
+        if (createTaskParams.title == null && createTaskParams.content == null) {
+            throw AppFunctionInvalidArgumentException("Title or content should be non-null")
+        }
+
+        val id = taskRepository.createTask(
+            createTaskParams.title,
+            createTaskParams.content
+        )
+
+        return@withContext taskRepository
+            .getTask(id)
+            ?.toTask()
+            ?: throw AppFunctionElementNotFoundException("Task not found for ID = $id")
+    }
+
+    // Maps internal TaskEntity
+    private fun TaskEntity.toTask() = Task(id = id, title = title, content = description)
+}
+```
+
+<br />
+
+<br />
+
+## Troubleshooting
+
+### Error: "AppFunction unavailable" or "Metadata missing"
+
+**Cause**: The AppSearch indexing failed to extract the schema correctly.
+
+**Solution**:
+
+1. Verify `@AppFunctionSerializable` classes use inline KDoc comments, not class-level `@param` tags.
+2. Check that the `assets/<appFunctionXmlFileName>.xml` file exists in the APK.
+3. Confirm the `ksp("androidx.appfunctions:appfunctions-compiler")` dependency is correctly applied.
+4. Ensure the `ksp` argument `appfunctions:aggregateAppFunctions` is set to `"true"`.

package/skills/mobile-android/references/on-device-ai/appfunctions/references/kdoc-refinement-optimization.md

@@ -0,0 +1,75 @@
+Optimizes AppFunction KDoc for AI agents and Model Context Protocol.
+
+## Instructions
+
+### Workflow: Agent-centric documentation
+
+1. **Identify the core outcome** : Start the description with a strong imperative verb, for example, "Search", "Create", or "Update". Focus on the *user benefit*, not the code implementation.
+2. **Workflow dependencies** : Explicitly state if another function must be called first using the standard phrase: **Required workflow: Call "Function
+   A" first to "Objective"**.
+3. **Parameter documentation** :
+   - For **functions** : Use specific `@param` tags. Isolate validation rules and default values here.
+   - For **serializables** : Use inline KDoc directly for each property declaration. KSP **won't** extract documentation from class-level tags.
+4. **Error surface mapping** : Rewrite `@throws` descriptions to provide useful recovery steps for the AI agent, for example "If "Error", suggest the user check their internet connection."
+
+### Workflow: Global app description for server instructions
+
+When writing the `appfn:description` for `app_metadata.xml`, follow these
+instructions:
+
+1. **Capture cross-function relationships**: Explain dependencies or sequences between tools, for example, "Always call 'authenticate' before fetching data.".
+2. **Document operational patterns**: Guide the LLM on token-conserving usage, for example, "Use 'batch_update' over multiple 'update' calls."
+3. **Specify constraints**: Define clear boundaries, for example, "File operations limited to workspace" or "Rate limit: 10 requests per minute."
+4. **Anti-patterns** :
+   - Don't repeat individual function descriptions.
+   - Don't include marketing claims or subjective praise.
+   - Don't attempt to prompt model personality or conversation style.
+
+## Critical constraints
+
+### Descriptive, not imperative
+
+Describe what the function *does* , not what the LLM *must* do. Avoid phrases
+like "You must call this..." in favor of "This function provides...".
+
+### No "fluff"
+
+Remove conversational padding like "This method is used to..." or "Helpful
+for...". Be concise and technical.
+
+### Inline KDoc for serializables
+
+**Mandatory** : For `@AppFunctionSerializable` classes, documentation must be
+inline for each property. KSP ignores class-level `@param` or `@property` tags
+for these classes.
+
+## Examples
+
+### Example: MCP refactoring
+
+**Original**:
+
+`/** This function helps you find people. */`
+
+**Refined**:
+
+     /**
+       * Search for message recipients by name or email.
+       * Required workflow: Call this before "sendMessage" to obtain valid recipient IDs.
+       * @param query Search string for name/email. If null, returns 3 most recent contacts.
+       * @return List of "Recipient" objects matching the query.
+       */
+
+### Example: Global app description
+
+**Refined**:
+
+    This app provides functions for task management and team collaboration.
+
+    Operational Patterns:
+    - Always use 'searchUsers' to resolve user handles to internal IDs before calling 'assignTask'.
+    - Prefer 'batchUpdateStatus' when modifying more than three tasks simultaneously to reduce latency.
+
+    Constraints:
+    - Task titles are limited to 100 characters.
+    - Attachment uploads are limited to 5 MB.