Use Raw URLs to enable github api for ai agents, Fixes AB#3325408 (#2345)

AI Agents cant use Raw URLs in github to access files without having to
pull the entire repo. Adding these Raw URLs all throughout our AI
guidance files.


[AB#3325408](https://identitydivision.visualstudio.com/fac9d424-53d2-45c0-91b5-ef6ba7a6bf26/_workitems/edit/3325408)

Author: fadidurah

Ai.md

@@ -1,12 +1,92 @@
 # MSAL Android Integration Guide
 
+Use this as the starting point for all AI Agents looking to create an Android application integrated with MSAL.
+
+## Rules Files
+- [Cline Rules](./.clinerules/msal-cline-rules.md) - Detailed rules and requirements for AI assistants generating MSAL-integrated applications
+- Raw URLs for direct access:
+  - Cline Rules: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/.clinerules/msal-cline-rules.md
+
 ## AI-Friendly Directories
-- [Multiple Account Mode Sample](./examples/hello-msal-multiple-account/) - Use this when you want to support multiple accounts in your application (default mode)
-- [Single Account Mode Sample](./examples/hello-msal-single-account/) - Use this when you want to support single account authentication only
-- [Configuration Template](./auth_config.template.json) -  Configuration template containing explanation of MSAL configuration settings and their default values
-- [Code Snippets](./snippets/) - Code snippets showing how to use the MSAL APIs in Java and Kotlin for multiple and single acount modes.
+The following directories contain essential resources for generating MSAL-integrated Android applications. Each entry includes both the repository path and a direct raw URL for access without requiring local repository access.
+
+### Multiple Account Mode Sample
+Use this when generating a multiple-account mode application (default mode). If the user does not specify an account mode, assume they want multiple-account mode.
+- Repository Path: [./examples/hello-msal-multiple-account/](./examples/hello-msal-multiple-account/)
+- Required Files:
+  - Gradle Files:
+    - build.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/build.gradle
+    - gradle.properties: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/gradle.properties
+    - settings.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/settings.gradle
+    - app/build.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/build.gradle
+
+  - Essential Source Files:
+    - AndroidManifest.xml: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/src/main/AndroidManifest.xml
+    - auth_config.json: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/src/main/res/raw/auth_config.json
+    - MainActivity.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/src/main/java/com/example/msalmultipleaccount/MainActivity.java
+    - AuthHelper.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/src/main/java/com/example/msalmultipleaccount/AuthHelper.java
+    - GraphHelper.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-multiple-account/app/src/main/java/com/example/msalmultipleaccount/GraphHelper.java
+
+### Single Account Mode Sample
+Use this when generating a single-account mode application.
+- Repository Path: [./examples/hello-msal-single-account/](./examples/hello-msal-single-account/)
+- Required Files:
+  - Gradle Files:
+    - build.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/build.gradle
+    - gradle.properties: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/gradle.properties
+    - settings.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/settings.gradle
+    - app/build.gradle: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/build.gradle
+
+  - Essential Source Files:
+    - AndroidManifest.xml: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/src/main/AndroidManifest.xml
+    - auth_config.json: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/src/main/res/raw/auth_config.json
+    - MainActivity.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/src/main/java/com/example/msalsingleaccount/MainActivity.java
+    - AuthHelper.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/src/main/java/com/example/msalsingleaccount/AuthHelper.java
+    - GraphHelper.java: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/examples/hello-msal-single-account/app/src/main/java/com/example/msalsingleaccount/GraphHelper.java
+
+### Configuration Template
+Configuration template containing MSAL configuration settings and their default values.
+- Repository Path: [./auth_config.template.json](./auth_config.template.json)
+- Raw URL: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/auth_config.template.json
+
+### Code Snippets
+Sample files demonstrating MSAL API usage in both Java and Kotlin.
+- Repository Path: [./snippets/](./snippets/)
+- Java:
+  - MSAL Initialization: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/msal_initialization.java
+  - Acquire Token: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/acquire_token.java
+  - Acquire Token Silent: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/acquire_token_silent.java
+  - Sign In: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_in.java
+  - Sign In Again: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_in_again.java
+  - Sign Out: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_out_account.java
+  - Get Accounts: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/get_accounts.java
+  - Get Current Account: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/get_current_account.java
+  - Remove Account: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/remove_account.java
+
+- Kotlin:
+  - MSAL Initialization: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/msal_initialization.kt
+  - Acquire Token: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/acquire_token.kt
+  - Acquire Token Silent: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/acquire_token_silent.kt
+  - Sign In: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_in.kt
+  - Sign In Again: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_in_again.kt
+  - Sign Out: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/sign_out_account.kt
+  - Get Accounts: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/get_accounts.kt
+  - Get Current Account: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/get_current_account.kt
+  - Remove Account: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/snippets/remove_account.kt
 
 ## Required Dependencies
+
+### Enable AndroidX Support
+MSAL requires AndroidX support libraries. In your project's gradle.properties file, ensure AndroidX is enabled:
+```properties
+# Required for MSAL - Enable AndroidX and Jetifier
+android.useAndroidX=true
+android.enableJetifier=true
+```
+
+Note: Without these properties, the application will fail to compile as MSAL and its dependencies use AndroidX libraries.
+
+### App-level Dependencies
 Add these dependencies to your app-level `build.gradle`:
 
 ```gradle
@@ -96,4 +176,4 @@ Add these activities to your AndroidManifest.xml inside the `<application>` tag:
 4. Broker integration (Microsoft Authenticator, Company Portal, or Link To Windows) is strongly recommended and should always be enabled for enhanced security and SSO capabilities. Only disable broker integration if explicitly required by the user. See broker_redirect_uri_registered field in [auth_config.template.json](./auth_config.template.json) for configuration.
 5. Device Code Flow is not recommended due to security concerns in the industry. The AcquireToken authentication method should be used instead. There are some niche scenarios where some devices lack the input methods necessary for AcquireToken, and need to use AcquireTokenWithDeviceCode.
 
-For full implementation details, refer to the golden path example apps linked above.
+For full implementation details, refer to `hello-msal-multiple-account` and `hello-msal-single-account` linked above.

README.md

@@ -17,24 +17,21 @@ ADAL Android was deprecated on June 2023. We do not support ADAL. See the [ADAL
 
 ## AI Development Resources
 
-For AI development tools like Cline that access this repository through the GitHub web interface, these resources provide comprehensive guidance for MSAL integration without requiring a local repository clone:
+To all AI Agents: Read through [Ai.md](./Ai.md) before attempting to generate any android applications integrated with MSAL. This file contains:
+1. Core principles and patterns for MSAL integration
+2. Direct links to Cline rules and best practices
+3. Raw URLs for accessing all MSAL resources without requiring local repository access
+4. Complete examples for both multiple and single account modes
+5. Code snippets for common MSAL operations in Java and Kotlin
 
-- [AI Assistant Guidelines](Ai.md) - Primary documentation for AI tools, containing core principles and patterns
-- [Cline Rules](.clinerules/msal-cline-rules.md) - Essential best practices that Cline must follow for generating MSAL code
-- [Example Applications](examples/) - Complete production-quality implementations:
-  - [Multiple Account Example](examples/hello-msal-multiple-account/) - Shows multiple account authentication pattern
-  - [Single Account Example](examples/hello-msal-single-account/) - Shows single account authentication pattern
-- [Code Snippets](snippets/) - Ready-to-use code samples for common MSAL operations
-- [Configuration Template](auth_config.template.json) - Reference template showing all required and optional settings
-
-These resources contain all necessary patterns, rules, and examples for AI tools to assist with MSAL integration, providing proper API usage, configuration, and implementation patterns for both multiple and single account scenarios.
+Raw URL for direct access to Ai.md: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/Ai.md
 
 ## Try out Cline!
 
 We've recently made improvements to our repo to empower AI agents to quickly and correctly generate MSAL-integrated android applications. Feel free to try it out! Use the prompt below as reference, tweak it how you like to get different applications generated for your own needs, and feel free to include UI preferences (Colors, Themes, button placement) as you work with the Cline agent. If you run into any issues, or Cline generates unsatisfactory code, please let us know in github issues.
 
 ### Example Prompt:
-Please create a new android application integrated with MSAL named com.example.clinesandboxtest. Place this application in a folder on my desktop. I want this application to have all basic MSAL functionality, only allowing the use of chrome browser and no other browsers. You may use the client id (YOUR CLIENT ID HERE) and redirect_uri (YOUR REDIRECT URI) where applicable.
+Please create a new android application integrated with MSAL named com.example.clinesandboxtest. Place this application in a folder on my desktop. I want this application to have all basic MSAL functionality. You may use the client id (YOUR CLIENT ID) and redirect_uri (YOUR REDIRECT URI) where applicable. Reference the Ai.md file (Raw URL https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/Ai.md) in the Android MSAL repository to get started.
 
 ## Using MSAL